SYS — System information

SYS-CLOSE - Notifies the client that the connection is about to be closed

A server sends a notification of this type to a client when the client will be forcibly disconnected from the server. Clients may then display the reason attached to the message to the user if it is practical to do so.

Typical reasons for a forced disconnection may be:

  • the server is shutting down

  • the server is limiting the number of concurrent connections

  • the server is enforcing limits on the maximum duration of a connection

Note that servers are not required to send this message upon a disconnection; the message is sent only as a courtesy to the user at the other end of the connection.

Notification fields

Name Required? Type Description

reason

no

string

An optional explanation of why the forced disconnection happened

Example notification

{
  "type": "SYS-CLOSE",
  "reason": "Maximum number of concurrent connections exceeded"
}

SYS-MSG - Send arbitrary human-readable messages to the client

Notification fields

Name Required? Type Description

items

yes

array of LogMessage

The array of messages to send

Example notification

{
  "type": "SYS-MSG",
  "items": [
    {
      "severity": "info",
      "message": "Free cookies in the lobby!"
    }
  ]
}

SYS-PING — Check whether a connection is alive

Either party in the connection may send a SYS-PING message to the other party to test whether the connection is still alive. Parties receiving a SYS-PING message are expected to respond with an ACK-ACK message as soon as it is practical to do so.

Note that each party may decide whether it wants to send SYS-PING messages over the wire periodically. Typically, the message is used to implement "heartbeating" to detect broken connections. If the transport protocol used to convey Flockwave messages implements heartbeating on its own, there is no additional benefit to firing SYS-PING messages. However, when Flockwave messages are transmitted over a plain TCP connection, SYS-PING messages may be used by either side to detect when the connection was dropped.

Request fields

This request has no fields.

Response fields

Responses should not be sent with this type; use ACK-ACK instead.

Example request

{
  "type": "SYS-PING"
}

SYS-PORTS - Return the mapping of registered services on the server to the corresponding ports

A client sends a request of this type to the server in order to retrieve the mapping from services and communication channels offered by the server to the corresponding TCP or UDP port numbers. There is no formal specification for the service names yes, but the reference implementation of the server uses service IDs as follows: tcp for the TCP-based communication channel, udp for the UDP-based communication channel, ssdp for the Simple Service Discovery Protocol (used by clients to discover the existence of the server) and http for a HTTP-based user interface and a WebSockets channel.

Request fields

This request has no fields.

Response fields

Name Required? Type Description

ports

yes

object

An object mapping names of registered services to the corresponding TCP or UDP port numbers.

Example request

{
  "type": "SYS-PORTS"
}

Example response

{
  "type": "SYS-PORTS",
  "ports": {
    "http": 5000,
    "ssdp": 1900,
    "tcp": 5001,
    "udp": 5001
  }
}

SYS-TIME - Retrieve or adjust the server clock

A client sends a request of this type to the server to obtain an accurate representation of the current UNIX timestamp on the server, or to adjust the server clock by a given number of milliseconds if the server allows it.

The retrieval form of the message is typically used to measure round-trip time and estimate clock skew between the client and the server, so care should be taken on the server side to ensure the accuracy of the returned timestamp to the extent permitted by the transport protocol.

The adjustment form of the message uses a relative adjustment deliberately. The idea is that one should first estimate the round-trip time and the necessary adjustment between client and server to bring their clocks in sync (using the retrieval form of the SYS-TIME message), and then send the required adjustment to the server only, avoiding the need to compensate for the round-trip time once again.

Request fields

Name Required? Type Description

adjustment

no

number

The number of milliseconds that the clock of the server should be forwarded by. Use zero to detect whether the server supports clock adjustment or not.

Response fields

Name Required? Type Description

timestamp

yes

timestamp

The current UNIX timestamp on the server at the time when the message was received if no adjustment was performed, or the timestamp after the adjustment if an adjustment was performed.

Example request

{
  "type": "SYS-TIME"
}

Example response

{
  "type": "SYS-TIME",
  "timestamp": 1588763723147
}

SYS-VER — Version number of the server

A SYS-VER request retrieves the version number of the server.

Request fields

This request has no fields.

Response fields

Name Required? Type Description

name

no

string

The name of the server. May be used to distinguish between multiple servers running concurrently so the operators know that they are connecting to the right server from the client.

revision

no

string

The revision number of the server, if known. This field is optional and can be used to convey more detailed version information than what the version field allows; for instance, one could provide the Git hash of the last commit in the server’s repository.

software

yes

string

The name of the server implementation.

version

yes

string

The version number of the server, in major.minor.patch format. The patch level is optional and may be omitted.

Example request

{
  "type": "SYS-VER"
}

Example response

{
  "type": "SYS-VER",
  "name": "CollMot test server",
  "software": "flockwave-server",
  "version": "1.0"
}