Editing SimTX API/Connection and handshake

{{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]], an 8-byte preface and a [[SimTX API/Packets/ClientHello|ClientHello]] from the client, and a [[SimTX API/Packets/ServerHello|ServerHello]] 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, <code>argon.simtx.net</code>, uses 5556.
|-
| Protocol version || 25, sent in the preface. Must match exactly.
|-
| Framing || Varint length, then one protobuf <code>ClientFrame</code> or <code>ServerFrame</code>. See [[SimTX API/Framing]].
|-
| Encoding || Standard protobuf 3. Sample payloads inside <code>bytes</code> fields are big-endian. See [[SimTX API/Data types]].
|}

Recommended socket options are <code>TCP_NODELAY</code> (frames are small and latency matters) and <code>SO_KEEPALIVE</code>. [[SimTX API/Packets/Ping|Ping]] and [[SimTX API/Packets/Pong|Pong]] are available on every role for round-trip measurement and liveness checks.

Unencrypted connections are accepted only by a development server bound to the loopback address. Public servers never accept them.

== Connection sequence ==
<syntaxhighlight lang="text">
 client                                                    server
   | ---- TCP connect, TLS handshake -----------------------> |
   | ---- preface  53 49 4D 54 00 00 00 19 ------------------> |
   | ---- [1] hello            ClientHello ----------------> |
   | <--- [1] hello_result     ServerHello ----------------- |   status 1 = ACCEPTED
   |                                                         |
   |   ROLE_RECEIVER:            [10] receiver_start ------> |   then session_status, IQ
   |   ROLE_TX_AUDIO / _GENERATED: [12] transmitter_start ---> |   then session_status, queue
   |   ROLE_CONTROL:             requests at once ---------> |   banner if a notice is active
   |   ROLE_MODERATION:          moderation requests ------> |
</syntaxhighlight>

The numbers in brackets are the <code>oneof</code> member numbers of the frames. The preface, the hello and the first start frame must arrive within '''5 seconds''' of connecting. Send them immediately after the TLS handshake completes.

== Preface ==
The client opens the byte stream with 8 bytes: the magic number <code>0x53494D54</code> ("SIMT") and the protocol version <code>25</code>, both as big-endian 32-bit integers. A server refuses any other version. The server sends no preface. Everything after it, in both directions, is framed. See [[SimTX API/Framing#Preface|Framing]].

== Hello ==
The first frame from the client must be <code>ClientFrame.hello</code>, a [[SimTX API/Packets/ClientHello|ClientHello]]:

<syntaxhighlight lang="protobuf">
message ClientHello {
  Role role = 1;
  AuthKind auth = 2;
  string credential = 3;        // stx_gt1_… game ticket; empty when anonymous
  string client_name = 4;       // e.g. "SimTX Transmitter"
  string client_version = 5;
  repeated string features = 6;  // client feature registry (see the top of this file)
  int32 protocol_revision = 7;    // highest protocol revision this client implements
}
</syntaxhighlight>

* <code>role</code> selects the kind of session. It cannot change later on the same connection.
* <code>auth</code> and <code>credential</code> carry a [[SimTX API/Game tickets|game ticket]] for authenticated connections. Anonymous connections leave both unset; an anonymous hello that carries a credential is refused.
* <code>client_name</code> and <code>client_version</code> identify the software to operators.
* <code>features</code> and <code>protocol_revision</code> say which optional behaviours the client implements. See [[SimTX API/Compatibility and versioning]].

The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and closes the connection 20 seconds after connecting if no hello has arrived.

== Roles ==
{| class="wikitable"
! Value !! Name !! Purpose !! Authentication
|-
| 1 || <code>ROLE_RECEIVER</code> || Receive IQ. See [[SimTX API/Receiver session|Receiver session]]. || Anonymous for an ad-hoc site. A ticket (<code>receiver</code>) for a station-bound site.
|-
| 2 || <code>ROLE_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>ROLE_TX_GENERATED</code> || Transmit a source generated by the server (white noise). || Ticket (<code>tx-generated</code>) with <code>game.transmit</code>
|-
| 4 || <code>ROLE_CONTROL</code> || Station list, banners, health, maps, ephemerides, passes, catalog, own-transmitter monitor. See [[SimTX API/Control session|Control session]]. || Anonymous, or ticket (<code>control</code>). A ticket unlocks the own-transmitter monitor and catalog publishing.
|-
| 5 || <code>ROLE_MODERATION</code> || Moderator tools. See [[SimTX API/Moderation session|Moderation session]]. || Ticket (<code>moderation</code>) with <code>moderation.manage</code>
|}

<code>ROLE_UNSPECIFIED</code> (0) and unknown values are refused. Any receiver can ask for timestamps with <code>ReceiverStart.timestamped</code>, with or without an account.

An authenticated receiver behaves like an anonymous one, except that it may bind to a station, and receiver limits and permissions such as <code>monitor.any</code> are evaluated against the account.

== Hello results ==
The server answers every hello with a [[SimTX API/Packets/ServerHello|ServerHello]] as its first frame. Status <code>HELLO_STATUS_ACCEPTED</code> means the session may begin. Any other status is followed by the server closing the connection.

{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>HELLO_STATUS_UNSPECIFIED</code> || Not sent by servers. Treat it, and unknown values, as <code>SERVER_UNAVAILABLE</code>.
|-
| 1 || <code>HELLO_STATUS_ACCEPTED</code> || The session may begin.
|-
| 2 || <code>HELLO_STATUS_VERSION_UNSUPPORTED</code> || The preface version is not 25.
|-
| 3 || <code>HELLO_STATUS_AUTHENTICATION_REQUIRED</code> || The role needs a ticket and none was sent. Typical message: <i>This role requires a SimTX account</i>.
|-
| 4 || <code>HELLO_STATUS_CREDENTIAL_INVALID</code> || The ticket is unknown, expired, used, or minted for another server or role. Typical message: <i>Game ticket is invalid or expired</i>.
|-
| 5 || <code>HELLO_STATUS_ACCOUNT_RESTRICTED</code> || The account is restricted.
|-
| 6 || <code>HELLO_STATUS_ROLE_FORBIDDEN</code> || The account lacks the permission the role needs. Typical message: <i>Account is not permitted to transmit</i>.
|-
| 7 || <code>HELLO_STATUS_SERVER_UNAVAILABLE</code> || The server cannot verify the ticket or take the connection now. The only status worth retrying unchanged.
|-
| 8 || <code>HELLO_STATUS_IP_BANNED</code> || The client address is banned. The message gives the reason.
|}

Only <code>SERVER_UNAVAILABLE</code> is worth retrying unchanged. A ticket is single-use, so every retry of an authenticated connection needs a new one.

== Accounts on the connection ==
For an authenticated connection, the ServerHello carries the account's id, handle, display name and effective [[SimTX API/Permissions|permissions]], including numeric capabilities such as <code>tx.pa_limit.400</code>. Software should use these for display and to show limits, rather than asking the account service separately.

Authenticated connections carry a '''lease''' of about 12 hours, given as <code>account.lease_expires_at_ms</code>. When it runs out, the server closes the connection. 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 end its connections at any moment.

The ServerHello also carries the server's clocks. <code>simulation_time_ms</code> is the simulated world clock; use it, not the local clock, as "now" for satellite positions and pass predictions.

== 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, before the hello.
* Further limits on receivers and transmitters apply once a session is started. See [[SimTX API/Limits and errors]].

== Ping ==
<code>ClientFrame.ping</code> ([[SimTX API/Packets/Ping|Ping]]) is answered by <code>ServerFrame.pong</code> ([[SimTX API/Packets/Pong|Pong]]) on every role, at any time after the hello. Pongs may arrive between any other frames.

== Examples ==
The preface, an anonymous receiver hello, and an accepted reply from a server that implements protocol revision 1:

'''<code>preface</code>''' (client to server, 8 bytes):

<syntaxhighlight lang="text">
53 49 4D 54 00 00 00 19
</syntaxhighlight>

'''<code>hello_anonymous_receiver</code>''' (client to server, 37 bytes):

<syntaxhighlight lang="text">
24                                           frame length 36
0A 22                                        hello (ClientHello), 34 bytes
  08 01                                      role = 1 (ROLE_RECEIVER)
  22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E  client_name = "SimTX Golden"
  2A 06 32 35 2E 30 2E 30                    client_version = "25.0.0"
  32 08 70 6F 69 6E 74 69 6E 67              features = "pointing"
</syntaxhighlight>

'''<code>hello_result_revision_1</code>''' (server to client, 96 bytes):

<syntaxhighlight lang="text">
5F                                        frame length 95
0A 5D                                     hello_result (ServerHello), 93 bytes
  08 01                                   status = 1 (HELLO_STATUS_ACCEPTED)
  22 0B 73 74 61 74 69 6F 6E 73 2E 76 31  features = "stations.v1"
  22 08 70 6F 69 6E 74 69 6E 67           features = "pointing"
  22 09 65 70 68 65 6D 65 72 69 73        features = "ephemeris"
  22 06 70 61 73 73 65 73                 features = "passes"
  22 0A 6B 69 6E 65 6D 61 74 69 63 73     features = "kinematics"
  2A 13 73 69 6D 74 78 2D 73 65 …         server_version = "simtx-server/25.1.0"
  30 80 94 83 B9 97 34                    server_time_ms = 1793000000000
  38 F4 97 83 B9 97 34                    simulation_time_ms = 1793000000500
  40 01                                   protocol_revision = 1
</syntaxhighlight>

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