Askutron Relay

Connects a host with clients through web sockets when the clients cannot connect to the host directly due to firewall restrictions. In this case the clients instead connect to this relay server. Also implements matchmaking.

API

The Relay's API endpoints

  • GET / - This page
  • GET /session[?id=<id>][&secret=<secret>][&keepAlive=str][&reconnect=true|false] {Upgrade} - WebSocket connection for the host. id is an optional parameter useful when you want to reconnect to the same session or determine the session id yourself. If ommitted a session ID will be generated. If given together with a secret the server will try to connect to an existing session and take it over. If keepAlive is present "str" is sent to the host every 30s to make sure the connection is kept alive. reconnect is true by default which means a session is kept running for 2 minutes even after the host disconnects so that they can reconnect. If disabled the session will be killed instantly instead.
  • GET /session/:id[?keepAlive=str][&client=<uuid>] {Upgrade} - WebSocket connection for clients. Any messages sent to this socket will be relayed to the host which connected through /session to the session with the given ID. If keepAlive is present "str" is sent to the client every 30s to make sure the connection is kept alive.

Protocol

There are the following message formats used for the host-to-server communication (/session).

Messages (Server → Host)

  • session: <session-id> - Sent as the first message from the relay (this) server to the connecting host to identify the created session. The host has to give this ID to any clients wanting to connect to it.
  • secret: <secret> - Sent as the 2nd message from the relay to the connected host. The host can take over this session from a new connection using this secret.
  • connected: <client-id> - Sent to the host when a client connects to the relay.
  • disconnected: <client-id> - Sent to the host when a client disconnects from the relay.
  • <client-id>: <message> - Message from the host to the client with the given ID or the other way around. Meaning this is the message a host has to send to relay a message to a client and at the same time this is the message a host will receive if a client wants to relay a message to it. Only the <message> part will be sent to the client.
  • unknown: <client-id> - Response to the host when it tried sending a message to an unknown client.
  • invalid - Sent to the host when it sent a message that the relay did not understand.

Commands (Host → Server)

  • /join-session [master [private]| slave] [id=<session-id>] [ghostMode=<true|false>] [steamUserId=<steam-id>] - Starts looking to join with another session either as a master or a slave. Given the respective options it can be forced which role the host wants to take. I.e. /join-session slave does not allow other sessions to join but only tries to join other sessions. A master session can be public (default) or private. If a private another host can join that session only if they know the session-id. For instance /join-session id=foo tries joining the session with the id foo as a slave. steamUserId can be used when the ghost mode is enabled to have the ghosts of the player's friends join the game. Without it only the ghosts of random players will join.
  • /close-session - Closes the session to join attempts by other sessions and also stops trying to join other sessions.
  • /leave-session - Leaves any connected sessions. If master, it will disconnect all slaves and send them a notification !master-left. If a slave, it will leave the master session and the master host will get a notification !slave-left: <session-id>. In either case on each side the session will stop looking to join or have another session join. Potentially to allow for a reconnect of the previously disconnected session.
  • /stats - Request stats about the relay. The host will receive a json object containing numHostsOnline, numHostsLookingForSession, numClientsOnline and numPlayers: !stats {...}
  • /version - Request the version the relay. The host will receive a version string like this: !version 1.9.1

Client Messages

Messages from clients are relayed as-is to the server listening to the given session.

Test

You can test the interaction between servers and clients, and servers among themselves here.

Host 1

Client 1

Client 2

Host 2

Client 3

Client 4

Host 3

Client 5

Client 6