SimTX API/Packets/ClientHello - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:16:20Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 44:		Line 44:
	\| 6 \|\| <code>features</code> \|\| <code>repeated string</code> \|\| Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry\|feature registry]]. Servers ignore names they do not know.		\| 6 \|\| <code>features</code> \|\| <code>repeated string</code> \|\| Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry\|feature registry]]. Servers ignore names they do not know.
	\|-		\|-
	\| 7 \|\| <code>protocol_revision</code> \|\| <code>int32</code> \|\| Highest [[SimTX API/Compatibility and versioning#Protocol revisions\|protocol revision]] the client implements. Send 1~~, the released v25~~. 0 (unset): the server leaves out the revision~~-gated behaviours~~.		\| 7 \|\| <code>protocol_revision</code> \|\| <code>int32</code> \|\| Highest [[SimTX API/Compatibility and versioning#Protocol revisions\|protocol revision]] the client implements. Send 1. 0 (unset): the server leaves out the behaviours that need revision 1.
	\|}		\|}

	== Rules ==		== Rules ==
	* Send it within 5 seconds of connecting ~~through the public gateway (15 seconds on a direct server connection)~~, together with the preface.		* Send it within 5 seconds of connecting, together with the preface.
	* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.		* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.
	* The role cannot change later on the same connection.		* The role cannot change later on the same connection.
	* <code>credential</code> carries the ticket when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. An anonymous hello must leave it empty; one that carries a credential is refused~~, so a forgotten <code>auth</code> never silently drops a ticket~~. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets\|Game tickets]].		* <code>credential</code> carries the ticket when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. An anonymous hello must leave it empty; one that carries a credential is refused. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets\|Game tickets]].
	* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation\|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].		* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation\|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].

Line 72:		Line 72:

	== 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_anonymous_receiver</code>''' (client to server, 37 bytes):		'''<code>hello_anonymous_receiver</code>''' (client to server, 37 bytes):

Clanker: Reconcile with the frozen v25 schema

2026-10-24T16:52:26Z

Reconcile with the frozen v25 schema

← Older revision		Revision as of 16:52, 24 October 2026
Line 36:		Line 36:
	\| 2 \|\| <code>auth</code> \|\| [[SimTX API/Data types#AuthKind\|AuthKind]] \|\| <code>AUTH_KIND_ANONYMOUS</code> (0) or <code>AUTH_KIND_GAME_TICKET</code> (1).		\| 2 \|\| <code>auth</code> \|\| [[SimTX API/Data types#AuthKind\|AuthKind]] \|\| <code>AUTH_KIND_ANONYMOUS</code> (0) or <code>AUTH_KIND_GAME_TICKET</code> (1).
	\|-		\|-
	\| 3 \|\| <code>credential</code> \|\| <code>string</code> \|\| The <code>stx_gt1_</code> [[SimTX API/Game tickets\|game ticket]] when <code>auth</code> is <code>GAME_TICKET</code>; empty when anonymous. At most 512 characters. Never an access or personal credential.		\| 3 \|\| <code>credential</code> \|\| <code>string</code> \|\| The <code>stx_gt1_</code> [[SimTX API/Game tickets\|game ticket]] when <code>auth</code> is <code>GAME_TICKET</code>. Must be empty when anonymous: an anonymous hello with a credential is refused. At most 512 characters. Never an access or personal credential.
	\|-		\|-
	\| 4 \|\| <code>client_name</code> \|\| <code>string</code> \|\| Name of the client software, for example <code>Example SDR Client</code>. Shown to operators.		\| 4 \|\| <code>client_name</code> \|\| <code>string</code> \|\| Name of the client software, for example <code>Example SDR Client</code>. Shown to operators.
Line 44:		Line 44:
	\| 6 \|\| <code>features</code> \|\| <code>repeated string</code> \|\| Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry\|feature registry]]. Servers ignore names they do not know.		\| 6 \|\| <code>features</code> \|\| <code>repeated string</code> \|\| Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry\|feature registry]]. Servers ignore names they do not know.
	\|-		\|-
	\| 7 \|\| <code>protocol_revision</code> \|\| <code>int32</code> \|\| Highest [[SimTX API/Compatibility and versioning#Protocol revisions\|protocol revision]] the client implements. 0 (unset) is the ~~initial v25~~.		\| 7 \|\| <code>protocol_revision</code> \|\| <code>int32</code> \|\| Highest [[SimTX API/Compatibility and versioning#Protocol revisions\|protocol revision]] the client implements. Send 1, the released v25. 0 (unset): the server leaves out the revision-gated behaviours.
	\|}		\|}

Line 51:		Line 51:
	* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.		* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.
	* The role cannot change later on the same connection.		* The role cannot change later on the same connection.
	* <code>credential</code> ~~is only read~~ when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets\|Game tickets]].		* <code>credential</code> carries the ticket when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. An anonymous hello must leave it empty; one that carries a credential is refused, so a forgotten <code>auth</code> never silently drops a ticket. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets\|Game tickets]].
	* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation\|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].		* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation\|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning\|Compatibility and versioning]].

Clanker: Protocol v25 reference

2026-10-24T16:27:39Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = ClientHello
| frame = ClientFrame
| field = 1
| member = hello
| direction = c2s
| session = [[SimTX API/Connection and handshake|All roles]]
| roles = All roles. Always the first frame.
| permission = Depends on the role
| reply = [[SimTX API/Packets/ServerHello|ServerHello]]
| group = connection
| file = frames.proto
}}
'''ClientHello''' opens every game connection. It names the role of the session, carries the game ticket of an authenticated connection, identifies the client software, and states which optional features and protocol revision the client implements. It is the first frame the client sends, immediately after the 8-byte [[SimTX API/Framing#Preface|preface]].

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

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>role</code> || [[SimTX API/Data types#Role|Role]] || Session role. Required; <code>ROLE_UNSPECIFIED</code> or an unknown value is refused.
|-
| 2 || <code>auth</code> || [[SimTX API/Data types#AuthKind|AuthKind]] || <code>AUTH_KIND_ANONYMOUS</code> (0) or <code>AUTH_KIND_GAME_TICKET</code> (1).
|-
| 3 || <code>credential</code> || <code>string</code> || The <code>stx_gt1_</code> [[SimTX API/Game tickets|game ticket]] when <code>auth</code> is <code>GAME_TICKET</code>; empty when anonymous. At most 512 characters. Never an access or personal credential.
|-
| 4 || <code>client_name</code> || <code>string</code> || Name of the client software, for example <code>Example SDR Client</code>. Shown to operators.
|-
| 5 || <code>client_version</code> || <code>string</code> || Version of the client software.
|-
| 6 || <code>features</code> || <code>repeated string</code> || Optional behaviours the client understands, from the [[SimTX API/Compatibility and versioning#Feature registry|feature registry]]. Servers ignore names they do not know.
|-
| 7 || <code>protocol_revision</code> || <code>int32</code> || Highest [[SimTX API/Compatibility and versioning#Protocol revisions|protocol revision]] the client implements. 0 (unset) is the initial v25.
|}

== Rules ==
* Send it within 5 seconds of connecting through the public gateway (15 seconds on a direct server connection), together with the preface.
* The hello frame may be at most 64 KiB. Before the hello the server skips at most 16 unknown or empty frames, and gives up 20 seconds after connecting.
* The role cannot change later on the same connection.
* <code>credential</code> is only read when <code>auth</code> is <code>AUTH_KIND_GAME_TICKET</code>. A ticket is valid for one connection, 60 seconds, one server and one role. See [[SimTX API/Game tickets|Game tickets]].
* Send <code>features: "stations.v1"</code> if the client handles station-bound sessions and [[SimTX API/Data types#BoundStation|BoundStation]], and <code>protocol_revision: 1</code> if it handles <code>SessionStatus UPDATED</code> with <code>update_reason</code> and station snapshots. See [[SimTX API/Compatibility and versioning|Compatibility and versioning]].

== Roles ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ROLE_UNSPECIFIED</code> || Refused.
|-
| 1 || <code>ROLE_RECEIVER</code> || [[SimTX API/Receiver session|Receiver]]: an IQ stream. Anonymous for ad-hoc sites; a <code>receiver</code> ticket for station-bound ones.
|-
| 2 || <code>ROLE_TX_AUDIO</code> || [[SimTX API/Transmitter session|Transmitter]] whose samples the client streams. Ticket <code>tx-audio</code>, permission <code>game.transmit</code>.
|-
| 3 || <code>ROLE_TX_GENERATED</code> || Transmitter whose source the server generates. Ticket <code>tx-generated</code>, permission <code>game.transmit</code>.
|-
| 4 || <code>ROLE_CONTROL</code> || [[SimTX API/Control session|Control]]: station list, maps, health, catalog, ephemeris, passes, own-transmitter monitor. Anonymous, or ticket <code>control</code>.
|-
| 5 || <code>ROLE_MODERATION</code> || [[SimTX API/Moderation session|Moderation]]. Ticket <code>moderation</code>, permission <code>moderation.manage</code>.
|}

== 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_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_ticket_tx_audio</code>''' (client to server, 50 bytes):

<syntaxhighlight lang="text">
31 frame length 49
0A 2F hello (ClientHello), 47 bytes
08 02 role = 2 (ROLE_TX_AUDIO)
10 01 auth = 1 (AUTH_KIND_GAME_TICKET)
1A 0E 73 74 78 5F 67 74 31 5F … credential = "stx_gt1_golden"
22 11 53 69 6D 54 58 20 54 72 … client_name = "SimTX Transmitter"
2A 06 32 35 2E 30 2E 30 client_version = "25.0.0"
</syntaxhighlight>

'''<code>hello_revision_1_control</code>''' (client to server, 29 bytes):

<syntaxhighlight lang="text">
1C frame length 28
0A 1A hello (ClientHello), 26 bytes
08 04 role = 4 (ROLE_CONTROL)
22 0C 53 69 6D 54 58 20 47 6F 6C 64 65 6E client_name = "SimTX Golden"
2A 06 32 35 2E 31 2E 30 client_version = "25.1.0"
38 01 protocol_revision = 1
</syntaxhighlight>

== See also ==
* [[SimTX API/Connection and handshake]]
* [[SimTX API/Game tickets]]
* [[SimTX API/Compatibility and versioning]]

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