QoS protocol

• The Discovery service allows the client to determine at runtime the regions that are currently active to test for connection quality.
• The QoS server allows the client to test for connection quality to each of the available regions.

Discovery service

https://qos.multiplay.com/v1/fleets/[fleet_id]/servers

[fleet_id]

Response types

200 OK

• Response Content Type: application/JSON
• Response Body: List of all QoS servers in fleet regions associated with the provided fleet in a JSON array called “servers”

{
  "servers": [
    {
      "location_id": 123,
      "region_id": "4f7d1d1a-a565-40b4-955a-ff0257d7ed3b",
      "ipv4": "1.1.1.1",
      "ipv6": "",
      "port": 9000
    },
    {
      "location_id": 456,
      "region_id": "22bf10c2-2565-4e75-848f-d2df25210896",
      "ipv4": "",
      "ipv6": "2606:4700:4700::1001",
      "port": 9000
    }
  ]
}

304 Not Modified

• Response Type: N/A
• Response Body: None

403 Forbidden

• Response Type: text/plain
• Response Body: “access denied for REMOTE_ADDR” (where REMOTE_ADDR is the network address of the caller)

404 Not Found

fleet_id

• Response Content Type: application/JSON
• Response Body: JSON object with details about the error

{
    "success": false,
    "error": true,
    "error_code": -1,
    "error_message": "fleet does not exist",
    "messages": []
}

500 Internal Server Error

• Response Content Type: application/JSON
• Response Body: Similar to the response for 404 Not Found, but with an

  error_message

  that contains information about the reason for the internal error.

ETag support

If-None-Match

Discovery best practices

• The Discovery service should be contacted once before the first QoS check after running the game. Cache the results locally, and use the provided ETag in subsequent requests whenever possible. This process can improve response times, reduce bytes over the wire, and reduce the load on the server when no changes are made to the servers list.
• Discovery should be performed at no less than 20 minute intervals.
• There are no duplicate entries in the “servers” array in the response. However, note that the same QoS server IP might serve multiple overlapping regions. Accordingly, you can isolate each unique server to be contacted only once, and then use the results for each region that uses that server. This process can reduce the amount of time that is spent sending requests and waiting for responses.
• If the game client only supports IPv4 connections, contact the IPv4 QoS servers. Conversely, if the game client only supports IPv6, contact the IPv6 QoS servers. If the game client is IP version-agnostic, then you can contact either or both versions of the QoS servers.
• The 4xx and 5xx responses contain legacy properties in the JSON object that should not be relied upon. Instead, only focus on the HTTP status code and the error_message field.

QoS server

QoS Request

0000b

0000b

QoS Response

0000b

0000b

0nnnb

nnnb

0010b

1nnnb

nnnb

1000b

1001b

Flow control

QoS check best practices

• A single QoS check should involve sending between 10-20 requests to a QoS server and then waiting for responses. The requests can be batched and sent in succession without first waiting for a response. The time to wait for responses depends on how latency tolerant the game is and how much time is dedicated to checking QoS in the game flow.
• Instead of checking one server at a time, developers can send requests to several servers at once and then wait for all responses from all servers. Note that contacting too many servers simultaneously might introduce latency when waiting for the responses to be read off of the sockets.
• While the packet length of a request is 1500 bytes (plus the IP and UDP headers), it is generally not advisable to send such large UDP packets. A UDP frame that is subjected to fragmentation and reassembly has a much higher chance of being discarded by intermediate routers along the path.
• Consider padding the QoS request with enough data to approximate the size of the game data packets to help identify servers on routes that are discarding larger UDP packets.
• QoS can be refreshed at periodic intervals when outside of an online game session, but there should be a minimum of 3 minutes between automatic checks. When in an online game session, QoS checks must be stopped to avoid unnecessary network traffic on the client and load on the QoS servers.
• Refrain from sending other network traffic when checking QoS. The time spent processing other network traffic might skew results or add additional latency.
• Rechecking QoS inside of the recommended minimum interval of 3 minutes is acceptable under specific circumstances, such as changing networks from cellular to Wi-Fi or Ethernet. If this is happening so frequently that most or all QoS checks are happening inside of the minimum interval, consider waiting until the underlying network becomes more stable before you resume performing QoS checks to avoid getting temporarily banned by the server.

Identifying packet loss

Computing latency

Identifying duplicate responses

Identifying stale responses

Example QoS flow