AMS watchdog protocol

Overview

This document describes the protocol which the DS is expected to use to communicate with the local watchdog. This can be used as a reference for dedicated servers which need to integrate with AccelByte Multiplayer Servers but are not supported by an AccelByte Client SDK.

Connecting to the watchdog

The watchdog listens for websocket connections from each Dedicated Server (DS) that it starts.
By default the DS should connect to ws://localhost:5555/watchdog, which is the address the watchdog listens to in AMS.

Watchdog <-> DS messages

Messages between the DS and watchdog are in JSON format. The messages which are defined by the protocol are as follows:

Ready

Once the DS has established a connection to the watchdog and has completed any startup work and is ready to be allocated to a game session it is expected to send the "ready" message to the watchdog.

The "ready" message has the following form:

{
  "ready": {
    "dsid": "string"
  }
}

The "dsid" value is the DS ID provided on the command line when the DS process is started.

Heartbeat

The DS is expected to send a "heartbeat" message to the watchdog every 15 seconds.

The "heartbeat" message has the following form:

{
  "heartbeat": {}
}

Reset session timeout

The DS can optionally send a "reset session timeout" message to the watchdog at any time.

For most scenarios, this is not needed as long as the pre-configured value in the fleet config has a session timeout long enough to accomodate a typical game session, but can be useful for scenarios with much longer lived game sessions or with game sessions that occasionally last much longer than a typical session.

If the DS chooses to send it, the message resets the session timeout if the DS is in the "in session" state. The pre-configured timeout duration can be overridden using the new_timeout field, which is given in nanoseconds. If new_timeout is not set, the timeout duration is reset to the pre-configured value and starts counting from zero at the time the reset message is recieved.

The "reset session timeout" message has the following form:

{
  "reset_session_timeout": {
    "new_timeout": <int32 new timeout value>
  }
}

Drain

The watchdog can send a "drain" message to the DS at any time to indicate that AMS would like to reclaim the node once existing game sessions hosted by the DSes on it have finished. See Listening to the drain signal for details on how the DS is expected to handle the drain signal.

The "drain' signal has the following form:

{
  "drain": {}
}