SimTX API v24/Connection and handshake - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:31Z

Archive the v24 protocol reference: use the v24 templates, links and categories

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	Every SimTX game connection begins the same way: a TLS connection to the host and port from the [[SimTX API/Server directory\|server directory]], a [[SimTX API/Packets/Handshake\|Handshake]] from the client, and a [[SimTX API/Packets/HandshakeResult\|HandshakeResult]] from the server. What follows depends on the '''role''' the client asked for.		Every SimTX game connection begins the same way: a TLS connection to the host and port from the [[SimTX API v24/Server directory\|server directory]], a [[SimTX API v24/Packets/Handshake\|Handshake]] from the client, and a [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]] from the server. What follows depends on the '''role''' the client asked for.

	== Transport ==		== Transport ==
Line 14:		Line 14:
	\| Protocol version \|\| 24. Must match exactly.		\| Protocol version \|\| 24. Must match exactly.
	\|-		\|-
	\| Byte order \|\| Big-endian. See [[SimTX API/Data types\|Data types]].		\| Byte order \|\| Big-endian. See [[SimTX API v24/Data types\|Data types]].
	\|-		\|-
	\| Framing \|\| <code>u8 packetId</code> followed by the body. No length prefix. See [[SimTX API/Packet list#Framing\|Framing]].		\| Framing \|\| <code>u8 packetId</code> followed by the body. No length prefix. See [[SimTX API v24/Packet list#Framing\|Framing]].
	\|}		\|}

Line 44:		Line 44:
	! Byte !! Name !! Purpose !! Authentication		! Byte !! Name !! Purpose !! Authentication
	\|-		\|-
	\| 1 \|\| <code>RECEIVER</code> \|\| Receive IQ at a location. See [[SimTX API/Receiver session\|Receiver session]]. \|\| Anonymous or ticket (<code>receiver</code>)		\| 1 \|\| <code>RECEIVER</code> \|\| Receive IQ at a location. See [[SimTX API v24/Receiver session\|Receiver session]]. \|\| Anonymous or ticket (<code>receiver</code>)
	\|-		\|-
	\| 2 \|\| <code>TX_AUDIO</code> \|\| Transmit audio or IQ streamed by the client. See [[SimTX API/Transmitter session\|Transmitter session]]. \|\| Ticket (<code>tx-audio</code>) with <code>game.transmit</code>		\| 2 \|\| <code>TX_AUDIO</code> \|\| Transmit audio or IQ streamed by the client. See [[SimTX API v24/Transmitter session\|Transmitter session]]. \|\| Ticket (<code>tx-audio</code>) with <code>game.transmit</code>
	\|-		\|-
	\| 3 \|\| <code>TX_GENERATED</code> \|\| Transmit a source generated by the server (white noise). \|\| Ticket (<code>tx-generated</code>) with <code>game.transmit</code>		\| 3 \|\| <code>TX_GENERATED</code> \|\| Transmit a source generated by the server (white noise). \|\| Ticket (<code>tx-generated</code>) with <code>game.transmit</code>
	\|-		\|-
	\| 4 \|\| <code>CONTROL</code> \|\| Station list, banners, health, maps, catalog, own-transmitter monitor. See [[SimTX API/Control session\|Control session]]. \|\| Anonymous or ticket (<code>control</code>)		\| 4 \|\| <code>CONTROL</code> \|\| Station list, banners, health, maps, catalog, own-transmitter monitor. See [[SimTX API v24/Control session\|Control session]]. \|\| Anonymous or ticket (<code>control</code>)
	\|-		\|-
	\| 5 \|\| <code>MODERATION</code> \|\| Moderator tools. See [[SimTX API/Moderation session\|Moderation session]]. \|\| Ticket (<code>moderation</code>) with <code>moderation.manage</code>		\| 5 \|\| <code>MODERATION</code> \|\| Moderator tools. See [[SimTX API v24/Moderation session\|Moderation session]]. \|\| Ticket (<code>moderation</code>) with <code>moderation.manage</code>
	\|-		\|-
	\| 6 \|\| <code>TIMESTAMPED_RECEIVER</code> \|\| Receiver whose IQ blocks carry UTC timestamps. \|\| Anonymous only		\| 6 \|\| <code>TIMESTAMPED_RECEIVER</code> \|\| Receiver whose IQ blocks carry UTC timestamps. \|\| Anonymous only
Line 62:		Line 62:

	== Handshake results ==		== Handshake results ==
	The server answers every well-formed handshake with a [[SimTX API/Packets/HandshakeResult\|HandshakeResult]]. Status <code>0</code> means the connection is accepted and the session may begin. Any other status is followed by the server closing the connection.		The server answers every well-formed handshake with a [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]]. Status <code>0</code> means the connection is accepted and the session may begin. Any other status is followed by the server closing the connection.

	{\| class="wikitable"		{\| class="wikitable"
Line 87:		Line 87:

	== Accounts on the connection ==		== Accounts on the connection ==
	For an authenticated connection, the HandshakeResult carries the account's UUID, handle, display name and effective [[SimTX API/Permissions\|permissions]]. Software should use these for display and to show limits such as the maximum transmitter power, rather than asking the account service separately.		For an authenticated connection, the HandshakeResult carries the account's UUID, handle, display name and effective [[SimTX API v24/Permissions\|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 <code>leaseExpiresAtEpochMillis</code>. 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.		Authenticated connections carry a '''lease''' of about 12 hours, given as <code>leaseExpiresAtEpochMillis</code>. 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.
Line 93:		Line 93:
	== Connection limits ==		== 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.		* 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]].		* Further limits on receivers and transmitters apply once a session is requested. See [[SimTX API v24/Limits and errors]].

	== Example ==		== Example ==
Line 120:		Line 120:
	</syntaxhighlight>		</syntaxhighlight>

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]
	[[Category:SimTX API sessions]]		[[Category:SimTX API v24 sessions]]

Clanker: Clanker moved page SimTX API/Connection and handshake to SimTX API v24/Connection and handshake: Archive the v24 protocol reference

2026-10-24T16:11:53Z

Clanker moved page SimTX API/Connection and handshake to SimTX API v24/Connection and handshake: Archive the v24 protocol reference

← Older revision	Revision as of 16:11, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:55:40Z

SimTX API documentation

New page

{{SimTX API navigation}}
Every SimTX game connection begins the same way: a TLS connection to the host and port from the [[SimTX API/Server directory|server directory]], a [[SimTX API/Packets/Handshake|Handshake]] from the client, and a [[SimTX API/Packets/HandshakeResult|HandshakeResult]] from the server. What follows depends on the '''role''' the client asked for.

== Transport ==
{| class="wikitable"
! 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 <code>host</code> 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 [[SimTX API/Data types|Data types]].
|-
| Framing || <code>u8 packetId</code> followed by the body. No length prefix. See [[SimTX API/Packet list#Framing|Framing]].
|}

Recommended socket options are <code>TCP_NODELAY</code> (packets are small and latency matters) and <code>SO_KEEPALIVE</code>. 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 ==
<syntaxhighlight lang="text">
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 |
</syntaxhighlight>

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.

{| class="wikitable"
! Byte !! Name !! Purpose !! Authentication
|-
| 1 || <code>RECEIVER</code> || Receive IQ at a location. See [[SimTX API/Receiver session|Receiver session]]. || Anonymous or ticket (<code>receiver</code>)
|-
| 2 || <code>TX_AUDIO</code> || Transmit audio or IQ streamed by the client. See [[SimTX API/Transmitter session|Transmitter session]]. || Ticket (<code>tx-audio</code>) with <code>game.transmit</code>
|-
| 3 || <code>TX_GENERATED</code> || Transmit a source generated by the server (white noise). || Ticket (<code>tx-generated</code>) with <code>game.transmit</code>
|-
| 4 || <code>CONTROL</code> || Station list, banners, health, maps, catalog, own-transmitter monitor. See [[SimTX API/Control session|Control session]]. || Anonymous or ticket (<code>control</code>)
|-
| 5 || <code>MODERATION</code> || Moderator tools. See [[SimTX API/Moderation session|Moderation session]]. || Ticket (<code>moderation</code>) with <code>moderation.manage</code>
|-
| 6 || <code>TIMESTAMPED_RECEIVER</code> || Receiver whose IQ blocks carry UTC timestamps. || Anonymous only
|}

A <code>TIMESTAMPED_RECEIVER</code> connection that presents a ticket is rejected with <code>CREDENTIAL_INVALID</code>, 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 <code>monitor.any</code> are evaluated against the account.

== Handshake results ==
The server answers every well-formed handshake with a [[SimTX API/Packets/HandshakeResult|HandshakeResult]]. Status <code>0</code> means the connection is accepted and the session may begin. Any other status is followed by the server closing the connection.

{| class="wikitable"
! Status !! Name !! Typical cause
|-
| 0 || <code>ACCEPTED</code> ||
|-
| 1 || <code>VERSION_UNSUPPORTED</code> || The client's version is not 24. The message names the required version.
|-
| 2 || <code>AUTHENTICATION_REQUIRED</code> || The role needs a ticket and none was sent.
|-
| 3 || <code>CREDENTIAL_INVALID</code> || The ticket is unknown, expired, already used, or issued for another server or role.
|-
| 4 || <code>ACCOUNT_RESTRICTED</code> || The account is suspended or under a restriction that covers this action.
|-
| 5 || <code>ROLE_FORBIDDEN</code> || The account lacks the permission the role requires.
|-
| 6 || <code>SERVER_UNAVAILABLE</code> || The server could not reach the account service, or cannot take the connection.
|-
| 7 || <code>IP_BANNED</code> || 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 [[SimTX API/Permissions|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 <code>leaseExpiresAtEpochMillis</code>. 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:

<syntaxhighlight lang="text">
53 49 4D 54 magic "SIMT"
00 00 00 18 version 24
01 role RECEIVER
00 authKind ANONYMOUS
00 00 credential "" (UTF, length 0)
</syntaxhighlight>

A successful anonymous reply:

<syntaxhighlight lang="text">
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
</syntaxhighlight>

{{SimTX API navbox}}
[[Category:SimTX API]]
[[Category:SimTX API sessions]]