Clanker: Remove development history and server internals

2026-10-24T17:16:36Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 108:		Line 108:
	* Reconnect with a fresh ticket shortly before <code>account.lease_expires_at_ms</code>.		* Reconnect with a fresh ticket shortly before <code>account.lease_expires_at_ms</code>.
	* Check <code>features</code> before using an optional capability, and rely on revision-gated behaviour only when <code>protocol_revision</code> is high enough. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].		* Check <code>features</code> before using an optional capability, and rely on revision-gated behaviour only when <code>protocol_revision</code> is high enough. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].
	* A client that sent preface version 24 does not receive a ServerHello. It receives a v24-format rejection; see [[SimTX API/Connection and handshake#Version 24 clients\|Version 24 clients]].

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>hello_result_accepted_account</code>''' (server to client, 130 bytes):		'''<code>hello_result_accepted_account</code>''' (server to client, 130 bytes):

Clanker: Protocol v25 reference

2026-10-24T16:27:52Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = ServerHello
| frame = ServerFrame
| field = 1
| member = hello_result
| direction = s2c
| session = [[SimTX API/Connection and handshake|All roles]]
| roles = All roles. Always the first server frame.
| permission = None
| answers = [[SimTX API/Packets/ClientHello|ClientHello]]
| group = connection
| file = frames.proto
}}
'''ServerHello''' answers the [[SimTX API/Packets/ClientHello|ClientHello]]. It accepts the connection, in which case the session continues according to the role, or rejects it, in which case the server closes the connection after sending it. For an authenticated connection it describes the account. It also carries the server's feature list, protocol revision and clocks.

== Definition ==
<syntaxhighlight lang="protobuf">
message ServerHello {
HelloStatus status = 1;
string message = 2;
Account account = 3; // unset for anonymous sessions
repeated string features = 4; // server feature registry (see the top of this file)
string server_version = 5;
int64 server_time_ms = 6; // Unix ms
int64 simulation_time_ms = 7; // Unix ms of the simulated world clock
int32 protocol_revision = 8; // highest protocol revision this server implements
}
</syntaxhighlight>

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>status</code> || [[SimTX API/Data types#HelloStatus|HelloStatus]] || Result of the hello. Anything other than <code>HELLO_STATUS_ACCEPTED</code> is followed by the server closing the connection.
|-
| 2 || <code>message</code> || <code>string</code> || Human-readable explanation. Empty on success. Show it to the user on rejection.
|-
| 3 || <code>account</code> || [[#Account|Account]] || The account, for authenticated connections. Unset for anonymous ones.
|-
| 4 || <code>features</code> || <code>repeated string</code> || Optional server capabilities of this deployment, from the [[SimTX API/Compatibility and versioning#Feature registry|feature registry]]. Ignore names you do not know.
|-
| 5 || <code>server_version</code> || <code>string</code> || Server software version, for display and diagnostics.
|-
| 6 || <code>server_time_ms</code> || <code>int64</code> || Server wall clock, Unix ms.
|-
| 7 || <code>simulation_time_ms</code> || <code>int64</code> || Simulated world clock, Unix ms. Use it, not the local clock, as "now" for satellite positions and pass predictions.
|-
| 8 || <code>protocol_revision</code> || <code>int32</code> || Highest protocol revision the server implements.
|}

=== Account ===
<syntaxhighlight lang="protobuf">
message Account {
bytes account_id = 1;
string handle = 2;
string display_name = 3;
repeated string permissions = 4;
int64 authorization_revision = 5;
int64 lease_expires_at_ms = 6;
}
</syntaxhighlight>
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>account_id</code> || <code>bytes</code> || 16-byte account UUID.
|-
| 2 || <code>handle</code> || <code>string</code> || Account handle.
|-
| 3 || <code>display_name</code> || <code>string</code> || Display name.
|-
| 4 || <code>permissions</code> || <code>repeated string</code> || Effective [[SimTX API/Permissions|permissions and numeric capabilities]] on this server, after the credential's scope, for example <code>game.transmit</code> or <code>tx.pa_limit.400</code>.
|-
| 5 || <code>authorization_revision</code> || <code>int64</code> || Revision of the account's authorisation data. Changes when permissions change.
|-
| 6 || <code>lease_expires_at_ms</code> || <code>int64</code> || When the server will close this authenticated connection, Unix ms. About 12 hours after the hello.
|}

== Status codes ==
{| 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: This role requires a SimTX account.
|-
| 4 || <code>HELLO_STATUS_CREDENTIAL_INVALID</code> || The ticket is unknown, expired, used, or minted for another server or role. Typical message: Game ticket is invalid or expired.
|-
| 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: Account is not permitted to transmit.
|-
| 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.
|}

On any status other than <code>ACCEPTED</code> the server closes the connection. Only <code>SERVER_UNAVAILABLE</code> is worth retrying unchanged; the others need a new ticket, a different role or user action.

== Usage ==
* After <code>ACCEPTED</code> on a receiver or transmitter connection, send the start frame immediately. A control or moderation session may send requests at once.
* Show <code>message</code> to the user on rejection.
* Use the numeric capabilities in <code>account.permissions</code>, such as <code>tx.pa_limit.400</code>, to configure the user interface.
* Reconnect with a fresh ticket shortly before <code>account.lease_expires_at_ms</code>.
* Check <code>features</code> before using an optional capability, and rely on revision-gated behaviour only when <code>protocol_revision</code> is high enough. See [[SimTX API/Compatibility and versioning|Compatibility and versioning]].
* A client that sent preface version 24 does not receive a ServerHello. It receives a v24-format rejection; see [[SimTX API/Connection and handshake#Version 24 clients|Version 24 clients]].

== Examples ==
Complete frames, including the varint length prefix, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>).

'''<code>hello_result_accepted_account</code>''' (server to client, 130 bytes):

<syntaxhighlight lang="text">
80 01 frame length 128
0A 7E hello_result (ServerHello), 126 bytes
08 01 status = 1 (HELLO_STATUS_ACCEPTED)
1A 4E account (Account), 78 bytes
0A 10 0F 8E 2C 4A … account_id = 0f8e2c4a-1b3d-4e5f-8a9b-0c1d2e3f4a5b
12 08 6F 70 65 72 61 74 6F 72 handle = "operator"
1A 08 4F 70 65 72 61 74 6F 72 display_name = "Operator"
22 0D 67 61 6D 65 2E 74 72 61 … permissions = "game.transmit"
22 0E 73 74 61 74 69 6F 6E 2E … permissions = "station.manage"
28 07 authorization_revision = 7
30 80 F1 DE BA 97 34 lease_expires_at_ms = 1793003600000
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"
2A 05 30 2E 33 2E 35 server_version = "0.3.5"
30 80 94 83 B9 97 34 server_time_ms = 1793000000000
38 F4 97 83 B9 97 34 simulation_time_ms = 1793000000500
</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>

'''<code>hello_result_version_unsupported</code>''' (server to client, 55 bytes):

<syntaxhighlight lang="text">
36 frame length 54
0A 34 hello_result (ServerHello), 52 bytes
08 02 status = 2 (HELLO_STATUS_VERSION_UNSUPPORTED)
12 30 54 68 69 73 20 73 65 72 … message = "This server speaks protocol v25; client sent v26"
</syntaxhighlight>

== See also ==
* [[SimTX API/Connection and handshake]]
* [[SimTX API/Permissions]]

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

SimTX API/Packets/ServerHello - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference