Editing SimTX API v24/Connection and handshake

{{SimTX API v24 navigation}}
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 ==
{| 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 v24/Data types|Data types]].
|-
| Framing || <code>u8 packetId</code> followed by the body. No length prefix. See [[SimTX API v24/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 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 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>
|-
| 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 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
|}

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 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"
! 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 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.

== 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:

<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 v24 navbox}}
[[Category:SimTX API v24]]
[[Category:SimTX API v24 sessions]]