View source for Dbserver-protocols

dbserver listens on several ports, each one providing a different service. Most services correspond to another server which will connect. All of these services use the common [[Network protocol]], in TCP-only mode.

== account ==

AccountServer connects to this service. It deals primarily with the ShardAccount container, with ''auth_id'' being the container ID for this DbList.

It can receive the following commands:

=== ACCOUNT_SVR_CONNECT ===

This message has no body. If an AccountServer is already connected, dbserver will respond by closing the link. Otherwise, it will respond with DBSERVER_ACCOUNT_PROTOCOL_VERSION:
 autobits protocol_version
 string shard_name
 autobits count
 repeated count times:
   autobits auth_id
   string auth_name

protocol_version will be DBSERVER_ACCOUNT_PROTOCOL_VERSION, currently 20070925.

dbserver will send the complete list of names and container IDs for all ShardAccount containers.

If ''IsLoggingMaster'' is set in server_cfg, dbserver will also send a ACCOUNT_CLIENT_UPDATE_LOG_LEVELS message:
 repeated LOG_LEVELS times:
  packint(1) log_level

These are the log levels, as managed by log.h, for all logging types in order from 0 to LOG_LEVELS. They are set in servers.cfg with SetLogLevel lines.

=== ACCOUNT_SVR_RELAY_CMD ===
 autobits message_dbid
 optional autobits auth_id
 string cmd

''auth_id'' is sent only if ''message_dbid'' is 0.

If ''message_dbid'' is not 0, then it is the container ID of an Ent, and dbserver will send a DBSERVER_RELAY_CMD to the MapServer where that Ent is connected:
 string relay_cmd
where ''relay_cmd'' will be:
 cmdrelay_dbid %d 0
 conprint "%s"
filled in with ''message_dbid'' and ''cmd''.

If ''auth_id'' is not 0, then it is the ''auth_id'' of a player, which will be used to find the link that game client has with the dbserver. If one exists, then dbserver will send it a DBGAMESERVER_ACCOUNTSERVER_UNAVAILABLE:
 string cmd
with ''cmd'' unchanged.

=== ACCOUNT_SVR_CHARCOUNT_REQUEST ===
 autobits auth_id
 bits(1) vip

The ''vip'' flag will be applied to the ShardAccount ''auth_id'', doing an SQL update if necessary.

Some SQL queries will be run to get the current character count, and when they are complete, dbserver will respond with a ACCOUNT_CLIENT_CHARCOUNT_REPLY:
 autobits auth_id
 autobits unlocked_used_count
 autobits total_char_count
 autobits bonus_slots
 autobits server_max_count
 autobits vip_only_server

=== ACCOUNT_SVR_CHARCOUNT_REPLY ===
 autobits auth_id
 autobits shards
 repeated shards times:
   string shard_name
   autobits unlocked_used
   autobits total_used
   autobits account_extra
   autobits server_max
   autobits vip_only_server

If ''shards'' is 0 then instead the packet will contain:
 autobits auth_id
 autobits shards
 string error_msg

dbserver finds the game client connection corresponding to ''auth_id'' and sends it DBGAMESERVER_ACCOUNTSERVER_CHARCOUNT, which is identical to the message received, except the ''auth_id'' is not included.

=== ACCOUNT_SVR_SLOTCOUNT_REQUEST ===
 autobits auth_id

dbserver replies with ACCOUNT_CLIENT_SLOTCOUNT_REPLY:
 autobits auth_id
 autobits slot_count

Taking ''slot_count'' from the ShardAccount container for ''auth_id''

=== ACCOUNT_SVR_PRODUCT_CATALOG_UPDATE ===
 autobits timestamp
 autobits auth_timeout
 string mtx_environment
 string playspan_domain
 string playspan_catalog
 string playspan_url_home
 string playspan_url_categoryview
 string playspan_url_itemview
 string playspan_url_showcart
 string playspan_url_addtocart
 string playspan_url_manageaccount
 string playspan_url_supportpage
 string playspan_url_supportpage_de
 string playspan_url_supportpage_fr
 string playspan_url_upgradetovip
 string coh_url_newfeatures
 string coh_url_newfeaturesupdate
 autobits playspan_store_flags

dbserver will send DBSERVER_ACCOUNTSERVER_CATALOG to every map server, proxying the contents of the packet.

dbserver will send DBGAMESERVER_ACCOUNTSERVER_CATALOG to every connected game client, proxying the contents of the packet.

=== ACCOUNT_SVR_CLIENTAUTH ===
 autobits auth_id
 autobits timestamp
 string playspan_digest

dbserver finds the game client connection corresponding to ''auth_id'' and proxies this message as DBGAMESERVER_ACCOUNTSERVER_CLIENTAUTH, excluding the ''auth_id'' field.

=== ACCOUNT_SVR_PLAYNC_AUTH_KEY ===
 autobits auth_id
 autobits request_key
 string plaync_auth_key

dbserver finds the game client link for this ''auth_id'' and proxies this message as DBGAMESERVER_ACCOUNTSERVER_PLAYNC_AUTH_KEY, excluding the ''auth_id''.

=== ACCOUNT_SVR_SHARDXFER ===

 OrderId order_id
 autobits step

Depending on the value of ''step'', the layout of the rest of the packet changes. Each of these messages is a step in the process of transferring a player character from one dbserver to another. dbserver will respond with ACCOUNT_CLIENT_SHARDXFER, which begins with the same two fields:
 OrderId order_id
 autobits step

The rest of the messages are described below, for each possible value of ''step''.

When ''step'' is SHARDXFER_VALIDATE_SRC:
 autobits ent_id

dbserver responds with:
 bits(1) exists

where ''exists'' is 1 if the ent_id is a valid Ent and 0 if it does not exist.

When ''step'' is SHARDXFER_VALIDATE_DST:
 autobits auth_id
 bits(1) vip

dbserver responds with:
 autobits unlocked_used_count
 autobits total_used_count
 autobits account_max_slots
 autobits server_max_slots
 autobits vip_only_server

When ''step'' is SHARDXFER_FULFILL_COPY_SRC:
 autobits ent_id
 autobits type
 string visitor_data_packet

then dbserver will send DBSERVER_RELAY_CMD to the MapServer for this Ent (forcibly loading them to a MapServer if the player is offline) with:
 cmdrelay_dbid %d
 shardxfer_init %s %d %d %s
populated with ent_id, order_id, type, home_shard, visitor_data_packet
where home_shard is the shard_id of this dbserver in turnstile_server.cfg.

If ''type'' is XFER_TYPE_VISITOR_OUTBOUND or XFER_TYPE_VISITOR_BACK then visitor_data_packet will be suffixed by a semicolon and the name of this shard from servers.cfg.

If ''ent_id'' is not a loaded Ent, and ''type'' is XFER_TYPE_PAID, then dbserver runs SQL queries to load the Ent and continues. For all other values of ''type'', it returns an error to AccountServer.

When ''step'' is SHARDXFER_FULFILL_COPY_DST:
 string container_txt
then dbserver will run an SQL query to check the Ent table for rows where AccSvrLock is ''order_id'' (or in development mode, where AccSvrLock is kOrderIdInvalid - this probably breaks things). If that row exists, then the ID of that Ent is returned. Otherwise, a new Ent will be created from container_txt, and the ID of that Ent is returned:
 autobits ent_id

dbserver will extract the AuthName from container_txt and validate that this account has free character slots. It will rename the character if there is a collision, and grant a rename token to the character if it does so. The container is then created and added to the SQL queue for writing. The container is immediately backed up into a hogg, and then unloaded.

When ''step'' is SHARDXFER_FULFILL_COMMIT_SRC:
 autobits dbid
 string dst_shard
 autobits dst_dbid
 autobits type

In this step, visitor transfers (when ''type'' is XFER_TYPE_VISITOR_OUTBOUND or XFER_TYPE_VISITOR_BACK) are handled differently: for these, dbserver finds the turnstile server for the destination shard, and sends it DBSERVER_COOKIE_REQUEST:
 OrderId order_id
 autobits dbid
 autobits type
 autobits dst_dbid
 autobits auth_id
 string account_name
 bits(1024) auth_data
 autobits home_shard_id
 autobits dst_shard_id

For non-visitor transfers, dbserver instead sends AUCTION_CLIENT_ACCOUNT_SHARDXFER to AuctionServer, to begin the inventory transfer:
 OrderId order_id
 autobits dbid
 string dst_shard
 autobits dst_dbid

In development mode, dbserver skips the AuctionServer interaction and sends back a response to AccountServer with no further fields.

When ''step'' is SHARDXFER_FULFILL_COMMIT_DST:
 autobits auth_id
 autobits ent_id
dbserver sends an SQL update to remove the AccSvrLock field from the Ents table for ''ent_id'', and sends ACCOUNT_CLIENT_MARK_SAVED to AccountServer:
 autobits auth_id
 autobits count // always 1 in this scenario
 repeated count times:
   OrderId order_id
then responds with ACCOUNT_CLIENT_SHARDXFER as usual, with no additional fields.

When ''step'' is SHARDXFER_FULFILL_COMMIT_RECOVERY:
 autobits auth_id
dbserver searches the Ents table for entries with AccSvrLock matching this OrderId, and then runs the COMMIT_DST procedure on those rows. It then responds with:
 bits(1) found
where ''found'' is 1 if any rows matched this OrderId, and 0 if none did.

When ''step'' is SHARDXFER_FULFILL_XFER_JUMP:
 autobits dbid
dbserver sends a DBSERVER_RELAY_CMD to the client (forcibly loading offline characters onto a MapServer if necessary), with this command:
 cmdrelay_dbid %s
 shardxfer_jump
populated with dbid.

For this step, dbserver does not send a ACCOUNT_CLIENT_SHARDXFER response to AccountServer.

=== ACCOUNT_SVR_RENAME ===
 OrderId order_id
 bits(1) fulfill
 autobits ent_id

When ''fulfill'' is false, dbserver will do some checks and then respond with ACCOUNT_CLIENT_RENAME:
 OrderId order_id
 bits(1) validating
 bits(1) confirm
''validating'' will be 1. ''confirm'' will be 1 if:
* The Ent is currently loaded (this may be a bug, it does not check for the renameable flag)
* There is an Ent in the SQL database with this ID, which is not locked, and the DbFlags column for that row has the DBFLAG_RENAMEABLE bit set.

When ''fulfill'' is true, the Ent will be loaded if necessary, forcibly loaded onto a MapServer if currently offline, and then sent a DBSERVER_RELAY_CMD with:
 cmdrelay_dbid %d
 order_rename %s
populated with ent_id and order_id

If the Ent is loaded, no response will be sent (bug), otherwise an ACCOUNT_CLIENT_RENAME will be sent with ''validating'' set to 0, and ''confirm'' will be set to 1 if the Ent was found and sent the command.

=== ACCOUNT_SVR_SLOT ===
 OrderId order_id
 autobits auth_id
dbserver increments the SlotCount field in the ShardAccount identified by ''auth_id'' and saves the container. It responds to AccountServer with ACCOUNT_CLIENT_SLOT:
 OrderId order_id
 bits(1) confirm
where ''confirm'' is 1 if the update was applied, and 0 if no ShardAccount with this ID could be found.

=== ACCOUNT_SVR_RESPEC ===
 OrderId order_id
 bits(1) fulfilling
 autobits ent_id

When ''fulfilling'' is 0, dbserver checks the Ent identified by ''ent_id'', and responds with ACCOUNT_CLIENT_RESPEC:
 OrderId order_id
 bits(1) validating
 bits(1) confirm
where ''validating'' is 1 and ''confirm'' is 1 if the Ent exists and is not locked.

When ''fulfilling'' is 1, the Ent will be loaded if necessary, forcibly loaded onto a MapServer if currently offline, and then sent a DBSERVER_RELAY_CMD with:
 cmdrelay_dbid %d
 order_respec %s
The response will have ''validating'' set to 0 and ''confirm'' set to 1 if the Ent was found and a command sent. The response might not be sent if the container is already loaded (bug).

=== ACCOUNT_SVR_NOTIFYTRANSACTION ===
 autobits auth_id
 autobits2 sku
 autobits inv_type
 OrderId order_id
 autobits granted
 autobits claimed
 bits(1) success

The game client link for ''auth_id'' is found. If dbserver has a direct link to that client, nothing happens. Otherwise, dbsevers send a DBSERVER_ACCOUNTSERVER_NOTIFYTRANSACTION to the player's current MapServer with the same content as this message, except the ''auth_id'' is replaced with the entity ID of the player's current character.

=== ACCOUNT_SVR_NOTIFYREQUEST ===
 autobits auth_id
 autobits type
 OrderId order_id
 bits(1) success
 string message

The game client link for auth_id is found. A DBGAMESERVER_ACCOUNTSERVER_NOTIFYREQUEST is sent with the same content as this message, without the ''auth_id''.

=== ACCOUNT_SVR_NOTIFYSAVED ===
 autobits auth_id
 autobits type
 OrderId order_id
 bits(1) success
 string message

The game client link for auth_id is found. If there is a direct connection to the dbserver, nothing happens. Otherwise, a DBSERVER_ACCOUNTSERVER_NOTIFYSAVED is sent to the MapServer where that client is connected, with the same content as this message, with the ''auth_id'' replaced by the ''ent_id'' of the player's current character.

=== ACCOUNT_SVR_INVENTORY ===
 autobits auth_id
 autobits count
 repeated count times:
   autobits2 sku
   autobits granted_total
   autobits claimed_total
   autobits expires
 packint(1) shard_xfer_free_only
 autobits shard_xfer_tokens
 bits(128) loyalty_status
 autobits loyalty_points_unspent
 autobits loyalty_points_earned
 autobits virtual_currency_balance
 autobits last_email_time
 autobits last_num_emails_sent

This data is stored in the ShardAccount container, and then either sent to the game client or MapServer as DBGAMESERVER_ACCOUNTSERVER_INVENTORY or DBSERVER_ACCOUNTSERVER_INVENTORY

=== ACCOUNT_SVR_CERTIFICATION_GRANT_ACK ===
=== ACCOUNT_SVR_CERTIFICATION_CLAIM_ACK ===
=== ACCOUNT_SVR_CERTIFICATION_REFUND_ACK ===
=== ACCOUNT_SVR_MULTI_GAME_TRANSACTION_ACK ===
=== ACCOUNT_SVR_MULTI_GAME_TRANSACTION_COMPLETED ===
=== ACCOUNT_SVR_FORCE_LOGOUT ===
 autobits auth_id

The game client connected for auth_id is forcibly disconnected, notifying connected MapServer or QueueServer.

=== ACCOUNT_SVR_DB_HEARTBEAT ===

== arena ==

This service supports the same protocol messages as the db service, documented below. It is used for ArenaServer to connect to dbserver, and the remote socket address of the ArenaServer connected on this port is used in processing DBCLIENT_REQ_ARENA_ADDRESS, but this service is not otherwise different.

== auction ==

AuctionServer connects to this service. It can receive the following commands:

=== AUCTION_SVR_CONNECT (2) ===

The message has no parameters. dbserver will accept only a single connection, and while it has one, it will respond to all further AUCTION_SVR_CONNECT messages by closing the connection.

dbserver responds with AUCTION_CLIENT_CONNECT (2):

 packint(1) protocol_version
 string shard_name
 bits(1) have_inactive_players
 something....

=== AUCTION_SVR_SEND_INV (3) ===

 autobits entity_id
 string inventory

dbserver finds the mapserver for ''entity_id'', and proxies the message there as DBSERVER_AUCTION_SEND_INV

inventory is eventually decoded by AuctionInventory_FromStr in the mapserver, but dbserver proxies it without inspecting its value.

=== AUCTION_SVR_SEND_HISTORYINFO (4) ===

 autobits entity_id
 string identifier
 autobits buying_count
 autobits selling_count
 autobits history_count
 repeated history_count times:
   autobits date
   autobits price

dbserver finds the mapserver for ''entity_id'', and proxies the message there as DBSERVER_AUCTION_SEND_HIST.

=== AUCTION_SVR_BATCH_SEND_ITEMINFO (5) ===

 autobits entity_id
 zipped data

dbserver finds the mapserver for ''entity_id'', and proxies the message there as DBSERVER_AUCTION_BATCH_INFO. The zipped data is not inspected by dbserver.

After this output packet has been queued, dbserver sends AUCTION_CLIENT_DATAOK to the AuctioServer, with no both. This is a primitive form of flow control. It does not wait for the message to be sent to the mapserver before doing this.

=== AUCTION_SVR_XACT_CMD (7) ===

 autobits entity_id
 autobits type
 XactCmd cmd

dbserver finds the mapserver for ''entity_id''. If there is one, it proxies the message there as DBSERVER_AUCTION_XACT_CMD. If there is no mapserver, then dbserver responds to AuctionServer with AUCTION_CLIENT_XACT_UPDATE, sending:

 autobits xid
 autobits subid
 autobits result

Where ''xid'' and ''subid'' are taken from ''cmd'', and the result is set to ''kXactCmdRes_No''.

=== AUCTION_SVR_RELAY_CMD_BYENT (9) ===

 packint(1) entity_id
 packint(1) force
 string msg

dbserver finds the mapserver for ''entity_id''. If there is one, it sends DBSERVER_RELAY_CMD there with ''msg'' as the body. If there is no mapserver, and force is set to 1, then the message is queued for relaying when the entity is available, and dbserver begins attempting to load the entity into a mapserver.

=== AUCTION_SVR_THROTTLE_ON (10) ===

This message has no parameters, and dbserver sends no response. It enables throttling, which prevents some (???) messages from being sent to the AuctionServer.

=== AUCTION_SVR_THROTTLE_OFF (11) ===

This message has no parameters, and dbserver sends no response. It disables throttling.

=== AUCTION_SVR_ACCOUNT_SHARDXFER (12) ===

 OrderId order_id
 autobits dbid

''dbid'' is interpreted as an Ent id. dbserver will offline (???) and delete (???) the player, and then send AccountServer an ACCOUNT_CLIENT_SHARDXFER with:

 OrderId order_id
 autobits SHARDXFER_FULFILL_COMMIT_SRC

== beacon ==

This service is used for the beacon servers and clients to connect to dbserver. It consists of two network ports, one for clients and one for servers.

All messages on the beacon client port are ignored.

Only one message is handled on the beacon server port. It is:

=== BEACON2DB_BEACONSERVER_STATUS ===
 packint(1) version
 packint(1) longest_wait

''version'' is ignored. When dbserver receives this packet, it records ''longest_wait'' and the time when this message was received.

This information is not used for any purpose other than relaying to ServerMonitor.

== client ==

This service is used for the game client to communicate with dbserver.

It is documented on [[Client-to-dbserver]]

== db ==

This service is used to communicate with MapServer and RaidServer.

It is documented on [[Dbserver-to-mapserver]]

== launcher ==

This service is used for launchers to connect to dbserver and receive instructions on what processes to start. It forms a primitive job scheduler, attempting to start processes on launchers which have spare capacity.

=== LAUNCHERQUERY_STARTPROCESS ===
=== LAUNCHERQUERY_GAMEVERSION ===
=== LAUNCHERQUERY_CONTROL ===
=== LAUNCHERANSWER_PROCESSES ===
=== LAUNCHERANSWER_LOCALONLY ===
=== LAUNCHERANSWER_GAMEVERSION ===
=== LAUNCHERANSWER_PROCESS_CLOSED ===
=== LAUNCHERANSWER_PROCESS_CRASHED ===

== log ==

=== LOGCLIENT_LOG ===
=== LOGCLIENT_LOGBUG ===
=== LOGCLIENT_SAVELISTS ===
=== LOGCLIENT_SHARDCHAT ===
=== LOGCLIENT_ZEROMQ_SET_CONNECT_STATE ===
=== LOGCLIENT_ZEROMQ_GET_STATUS ===

== mission ==

This service is used for the MissionServer to connect to dbserver. Only one MissionServer is allowed to connect.

=== MISSION_SERVER_MESSAGEENTITY ===
=== MISSION_SERVER_SEARCHPAGE ===
=== MISSION_SERVER_ARCINFO ===
=== MISSION_SERVER_ARCDATA ===
=== MISSION_SERVER_SENDPETITION ===
=== MISSION_SERVER_COMMENT ===
=== MISSION_SERVER_INVENTORY ===
=== MISSION_SERVER_CLAIM_TICKETS ===
=== MISSION_SERVER_ITEM_BOUGHT ===
=== MISSION_SERVER_OVERFLOW_GRANTED ===
=== MISSION_SERVER_ALLARCS ===
=== MISSION_SERVER_BANSTATUS ===
=== MISSION_SERVER_ARCDATA_OTHERUSER ===

== queue ==

This service is used for the QueueServer to connect to dbserver. Only one connection is allowed.

The use of the QueueServer is optional. When it is used, game clients connect to QueueServer instead of dbserver, and QueueServer proxies all the usual [[Client-to-dbserver]] messages.

Proxied messages for clients, sent from dbserver to QueueServer, will be prefixed with these fields to identify the client they are for:
 string client_name
 autobits link_id

Proxies messages from clients, send from QueueServer to dbserver, will be sent in QUEUECLIENT_CLIENTCOMMAND messages.

=== QUEUESERVER_SVR_CONNECT ===
=== QUEUESERVER_SVR_ERROR ===
=== QUEUESERVER_SVR_ENQUEUESTATUS ===
=== QUEUESERVER_SVR_UPDATE ===
=== QUEUESERVER_SVR_REMOVECLIENT ===
=== QUEUESERVER_SVR_SET_LOG_LEVELS ===
=== QUEUESERVER_SVR_TEST_LOG_LEVELS ===
=== QUEUECLIENT_CONNECT ===
=== QUEUECLIENT_UPDATE_REQUEST ===
=== QUEUECLIENT_CLIENTCOMMAND ===
=== QUEUECLIENT_CLIENTPLAY ===
=== QUEUECLIENT_REMOVECLIENT ===

== stat ==

This service is used for StatServer to connect. It is used to identify the StatServer in order to send messages to it. It supports the same messages as the db service, and is not otherwise different.

== svrmon ==

This service is used for ServerMonitor to connect to dbserver. Many ServerMonitors can connect to the service simultaneously.

Unusually, this service reuses command numbers for requests and responses, instead of having two distinct namespaces for messages in each direction.

=== DBSVRMON_REQUEST ===
=== DBSVRMON_REQUESTDIFF ===
=== DBSVRMON_LAUNCHERS ===
=== DBSVRMON_MAPSERVERS ===
=== DBSVRMON_CRASHEDMAPSERVERS ===
=== DBSVRMON_PLAYERS ===
=== DBSVRMON_RELAYMESSAGE ===
=== DBSVRMON_REQUESTVERSION ===
=== DBSVRMON_REQUEST_PLAYERS ===
=== DBSVRMON_CONNECT ===
=== DBSVRMON_DBSTATS ===
=== DBSVRMON_SERVERAPPS ===
=== DBSVRMON_LOGSERVERSTATS ===

== turnstile ==

This service is used for the TurnstileServer to connect to dbserver. It assumes that only one TurnstileServer will connect at a time, but does not enforce this; the most recently registered one will receive messages intended for TurnstileServer.

=== TURNSTILE_REGISTER ===
=== TURNSTILE_EVENT_WAIT_TIMES ===
=== TURNSTILE_QUEUE_STATUS ===
=== TURNSTILE_EVENT_READY ===
=== TURNSTILE_EVENT_READY_ACCEPT ===
=== TURNSTILE_EVENT_FAILED_START ===
=== TURNSTILE_MAP_START ===
=== TURNSTILE_EVENT_START ===
=== TURNSTILE_SHARD_XFER ===
=== TURNSTILE_COOKIE_REQUEST ===
=== TURNSTILE_COOKIE_REPLY ===
=== TURNSTILE_REJOIN_FAIL ===