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 v24/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