SimTX API v24/Connection and handshake
Every SimTX game connection begins the same way: a TLS connection to the host and port from the server directory, a Handshake from the client, and a HandshakeResult from the server. What follows depends on the role the client asked for.
Transport
| Property | Value |
|---|---|
| Transport | TCP |
| Security | TLS 1.3 or TLS 1.2, required. Verify the server certificate against the system's public CA store and the host name from the directory.
|
| Port | From the server directory. The public deployment currently uses 5556. |
| Protocol version | 24. Must match exactly. |
| Byte order | Big-endian. See Data types. |
| Framing | u8 packetId followed by the body. No length prefix. See Framing.
|
Recommended socket options are TCP_NODELAY (packets are small and latency matters) and SO_KEEPALIVE. The protocol has no application-level ping or heartbeat. A dead connection is detected by TCP keepalive and by the server's stall timers.
Unencrypted connections are accepted only by a development server explicitly configured for it and bound to the loopback address. Public servers never accept them.
Connection sequence
client server
| ---- TCP connect, TLS handshake -------------------> |
| ---- Handshake (no ID byte) -----------------------> |
| <--- [30] HandshakeResult -------------------------- | status 0 = ACCEPTED
| |
| role 1 / 6: [1] ReceiverSessionRequest ---> |
| role 2 / 3: [2] TransmitterSessionRequest --> |
| role 4: <--- [8] ControlAck, [17] Banner? |
| role 5: moderation requests |
The handshake and the first session request must arrive promptly. Through the public gateway the limit is 5 seconds from connecting until the session request has been read and admitted; a server reached directly allows 15 seconds. Send both immediately after the TLS handshake completes.
Roles
The role byte in the handshake selects the kind of session. It cannot be changed later on the same connection.
| Byte | Name | Purpose | Authentication |
|---|---|---|---|
| 1 | RECEIVER |
Receive IQ at a location. See Receiver session. | Anonymous or ticket (receiver)
|
| 2 | TX_AUDIO |
Transmit audio or IQ streamed by the client. See Transmitter session. | Ticket (tx-audio) with game.transmit
|
| 3 | TX_GENERATED |
Transmit a source generated by the server (white noise). | Ticket (tx-generated) with game.transmit
|
| 4 | CONTROL |
Station list, banners, health, maps, catalog, own-transmitter monitor. See Control session. | Anonymous or ticket (control)
|
| 5 | MODERATION |
Moderator tools. See Moderation session. | Ticket (moderation) with moderation.manage
|
| 6 | TIMESTAMPED_RECEIVER |
Receiver whose IQ blocks carry UTC timestamps. | Anonymous only |
A TIMESTAMPED_RECEIVER connection that presents a ticket is rejected with CREDENTIAL_INVALID, because no ticket can be issued for that role.
An authenticated receiver behaves exactly like an anonymous one, except that receiver limits and permissions such as monitor.any are evaluated against the account.
Handshake results
The server answers every well-formed handshake with a HandshakeResult. Status 0 means the connection is accepted and the session may begin. Any other status is followed by the server closing the connection.
| Status | Name | Typical cause |
|---|---|---|
| 0 | ACCEPTED |
|
| 1 | VERSION_UNSUPPORTED |
The client's version is not 24. The message names the required version. |
| 2 | AUTHENTICATION_REQUIRED |
The role needs a ticket and none was sent. |
| 3 | CREDENTIAL_INVALID |
The ticket is unknown, expired, already used, or issued for another server or role. |
| 4 | ACCOUNT_RESTRICTED |
The account is suspended or under a restriction that covers this action. |
| 5 | ROLE_FORBIDDEN |
The account lacks the permission the role requires. |
| 6 | SERVER_UNAVAILABLE |
The server could not reach the account service, or cannot take the connection. |
| 7 | IP_BANNED |
The client address is banned. The message gives the reason. |
A handshake that is malformed, such as one with the wrong magic number, an unknown authentication kind, or an illegal credential string, is closed without any reply.
Accounts on the connection
For an authenticated connection, the HandshakeResult carries the account's UUID, handle, display name and effective permissions. Software should use these for display and to show limits such as the maximum transmitter power, rather than asking the account service separately.
Authenticated connections carry a lease of about 12 hours, given as leaseExpiresAtEpochMillis. When it runs out, the server closes the connection without a message. A long-running client should reconnect with a fresh ticket before the lease expires. Changes to the account, such as a revoked device, a new restriction or a ban, can close all of its connections at any moment, also without a message.
Connection limits
- At most 32 simultaneous connections per client IP address, and 256 per server in total. A connection over either limit is closed straight away without a reply.
- Further limits on receivers and transmitters apply once a session is requested. See SimTX API/Limits and errors.
Example
An anonymous receiver handshake, as bytes:
53 49 4D 54 magic "SIMT"
00 00 00 18 version 24
01 role RECEIVER
00 authKind ANONYMOUS
00 00 credential "" (UTF, length 0)
A successful anonymous reply:
1E packet ID 30 HandshakeResult
00 status ACCEPTED
00 00 message ""
00 hasAccount false
00 00 handle ""
00 00 displayName ""
00 permissionCount 0
00 00 00 00 00 00 00 00 authorizationRevision 0
00 00 00 00 00 00 00 00 leaseExpiresAtEpochMillis 0