SimTX API/Compatibility and versioning - Revision history

Clanker: Remove development history and server internals

2026-10-24T17:16:13Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API navigation}}
	This page ~~explains how~~ the [[SimTX API]] game protocol ~~changes over time~~, and what a client must do to ~~keep working~~ as ~~it does: the protocol version, protocol revisions within a version, the feature registry, and the additive-only rule. It ends with a summary of the changes from~~ version 24.		This page describes the protocol version, the protocol revision and the feature registry of the [[SimTX API]] game protocol, and what a client must do to stay compatible as version 25 grows.

	== Protocol version ==		== Protocol version ==
	The protocol version is the integer in the 8-byte [[SimTX API/Framing#Preface\|preface]]. ~~It changes only for a breaking change. A breaking change gets a new~~ version ~~and a new~~ protobuf package (<code>simtx.~~v26~~</code> ~~after <code>simtx~~.~~v25</code>), and servers answer older prefaces~~ with a version~~-unsupported result rather than misreading them~~.		The protocol version is the integer in the 8-byte [[SimTX API/Framing#Preface\|preface]]. The current version is 25, protobuf package <code>simtx.v25</code>. A server refuses a preface with any other version. An incompatible change would get a new version number and a new package.

	~~Version 25 replaced~~ version ~~24 completely; the two are not compatible. See [[#Changes from v24\|Changes from v24]]~~.

	== Protocol revisions ==		== Protocol revisions ==
	~~Within version 25, additive changes that a peer may need to detect increase the '''protocol revision'''.~~ Both hellos carry it: <code>ClientHello.protocol_revision</code> and <code>ServerHello.protocol_revision</code> are the highest revision the sender implements. ~~A peer relies on revision-''N'' behaviour only when~~ the ~~other side's revision is at least ''N''~~. ~~An unset value is 0~~.		Both hellos carry <code>protocol_revision</code>: <code>ClientHello.protocol_revision</code> and <code>ServerHello.protocol_revision</code> are the highest revision the sender implements. Revision 1 is the current protocol. Clients send 1.

	~~{\| class="wikitable"~~		A server keeps a station-bound session running across a station edit, with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>UPDATED</code>, <code>update_reason</code> and a station snapshot, only for clients that announce revision 1 or higher. A client that announces nothing gets <code>ENDED</code> instead and must reconnect.
	~~! Revision !! Adds~~
	\|-
	~~\| 0 \|\|~~ A ~~peer that sends no revision: the v25 schema without the revision-gated behaviours.~~
	\|-
	\| 1 \|\| The first released v25, frozen on 24 October 2026: everything in the current [[SimTX API/Schema\|.proto files]], including the late additions <code>AntennaAim</code> on both starts, <code>Tracking.since_*</code>, <code>IqBlock.sequence</code>, <code>request_id</code> on ReceiverRetune and on StartMonitor / StopMonitor (acknowledged by MonitorAck), <code>BannerLevel</code> and <code>ERROR_CODE_CANCELLED</code>. Gated on the client's revision: a server keeps a station-bound session running across a station edit, with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>UPDATED</code>, <code>update_reason</code> and a station snapshot, only ~~when the client announced~~ revision 1 or higher. ~~Older clients get~~ <code>ENDED</code>.
	\|}

	~~A client should send the highest revision whose behaviour it really implements. A client that announces~~ revision ~~1 must handle <code>UPDATED</code> statuses with a station snapshot.~~		Behaviour tied to a revision applies only when the other side announced at least that revision.

	~~The schema changed incompatibly before release: enum zero values,~~ the shared <code>StationCore</code> and <code>SessionSite</code>, the single Error model, and the removal of TxReject, TxKick and ModerationError. That final shape is documented as revision 1 rather than 2, because no released peer predates it. Pre-release builds that ~~also announced~~ revision ~~0 or 1 are not v25 peers. Regenerate bindings from the current files~~.

	== Feature registry ==		== Feature registry ==
Line 46:		Line 36:
	* Treat a missing feature as "not available" and hide the user interface for it.		* Treat a missing feature as "not available" and hide the user interface for it.
	* Prefer feature checks for deployment capabilities and <code>protocol_revision</code> for knowledge of the schema. Avoid checks on <code>server_version</code>.		* Prefer feature checks for deployment capabilities and <code>protocol_revision</code> for knowledge of the schema. Avoid checks on <code>server_version</code>.
	* The account service mints station-bound tickets only for servers ~~whose every node advertises~~ <code>stations.v1</code>; otherwise it answers <code>409 station_binding_unsupported</code>.		* The account service mints station-bound tickets only for servers that advertise <code>stations.v1</code>; otherwise it answers <code>409 station_binding_unsupported</code>.

	== Additive ~~only~~ ==		== Additive changes ==
	~~After the freeze, version~~ 25 grows only by adding:		Version 25 grows only by adding:
	* new messages and new <code>oneof</code> members of <code>ClientFrame</code> and <code>ServerFrame</code>;		* new messages and new <code>oneof</code> members of <code>ClientFrame</code> and <code>ServerFrame</code>;
	* new fields in existing messages;		* new fields in existing messages;
Line 55:		Line 45:
	* new names in the [[SimTX API/Data types#String enumerations\|string enumerations]] (modulations, antenna types, sources, weather layers, catalog types).		* new names in the [[SimTX API/Data types#String enumerations\|string enumerations]] (modulations, antenna types, sources, weather layers, catalog types).

	Field numbers and enum numbers are never renumbered or reused, field types and labels never change, and <code>oneof</code> membership never changes. A removed field's number and name are reserved. The schema of every revision is frozen as a binary descriptor, and the build compares the current schema against it, failing on any removed, renumbered, retyped or relabelled field, removed enum value or message, or changed <code>oneof</code> membership.		Field numbers and enum numbers are never renumbered or reused, field types and labels never change, and <code>oneof</code> membership never changes.

	=== What a client must do ===		=== What a client must do ===
Line 64:		Line 54:
	* '''Use presence.''' Proto3 omits zero values. Fields marked <code>optional</code> say whether they were set; unset means "use the default".		* '''Use presence.''' Proto3 omits zero values. Fields marked <code>optional</code> say whether they were set; unset means "use the default".
	* '''Ignore unknown JSON fields''' from the account service, which follows the same rule.		* '''Ignore unknown JSON fields''' from the account service, which follows the same rule.

	~~== Changes from v24 ==~~
	~~A summary for authors of v24 clients. The v24 reference is archived at [[SimTX API v24]].~~

	~~{\| class="wikitable"~~
	~~! Area !! v24 !! v25~~
	\|-
	\| Encoding \|\| Hand-laid big-endian packets with an ID byte and no length prefix \|\| Protobuf messages in varint-delimited <code>ClientFrame</code> / <code>ServerFrame</code> frames; unknown frames and fields are skipped
	\|-
	\| Handshake \|\| <code>Handshake</code> with magic, version, role, auth kind and credential \|\| 8-byte preface, then [[SimTX API/Packets/ClientHello\|ClientHello]] with client name, version, features and protocol revision
	\|-
	~~\| Handshake result \|\| <code>HandshakeResult</code>, status 0 = accepted \|\| [[SimTX API/Packets/ServerHello\|ServerHello]], status 1 = accepted; adds features, protocol revision and clocks~~
	\|-
	~~\| Roles \|\| Six roles including <code>TIMESTAMPED_RECEIVER</code> \|\| Five roles; timestamps are an option of every receiver~~
	\|-
	\| Receiver start \|\| <code>ReceiverSessionRequest</code> with inline callsign, location and antenna \|\| [[SimTX API/Packets/ReceiverStart\|ReceiverStart]] with a <code>SessionSite</code>: a station binding or an ad-hoc site; sample format, tracking
	\|-
	\| Transmitter start \|\| <code>TransmitterSessionRequest</code>, a TLV field list \|\| [[SimTX API/Packets/TransmitterStart\|TransmitterStart]] with a <code>SessionSite</code>; imperfections in <code>TxImperfections</code>; ad-hoc transmitters need <code>tx.adhoc</code>
	\|-
	~~\| Stations \|\| Each session was its own station with a new UUID \|\| Persistent, account-owned [[SimTX API/Stations\|stations]] and [[SimTX API/Satellites\|satellites]]; sessions bind to them~~
	\|-
	\| Session state \|\| Implicit; failures often closed the connection silently \|\| [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>BOUND</code>, <code>UPDATED</code>, <code>REJECTED</code>, <code>ENDED</code>
	\|-
	\| Errors \|\| <code>TxReject</code>, <code>TxKick</code>, <code>ModerationError</code>, flags in responses, silent closes \|\| One [[SimTX API/Packets/Error\|Error]] model with <code>request_id</code>; SessionStatus for sessions
	\|-
	~~\| IQ blocks \|\| <code>IqBlock</code> and <code>TimedIqBlock</code> \|\| One [[SimTX API/Packets/IqBlock\|IqBlock]] with optional timestamps and a <code>sequence</code> number~~
	\|-
	~~\| Retune \|\| No acknowledgement \|\| Optional <code>request_id</code>, confirmed by SessionStatus <code>UPDATED</code>~~
	\|-
	~~\| Control session start \|\| <code>ControlAck</code> \|\| Nothing; an accepted ServerHello is enough~~
	\|-
	~~\| Requests \|\| Most control requests had no id \|\| Every control and moderation request has a <code>request_id</code>~~
	\|-
	~~\| Ids \|\| UUIDs as 36-character text \|\| UUIDs as 16 bytes~~
	\|-
	~~\| Frequencies \|\| <code>f32</code> \|\| <code>double</code>~~
	\|-
	~~\| New \|\| \|\| Ping and Pong, antenna pointing and tracking, Doppler correction, ephemerides, pass predictions, monitor acknowledgements~~
	\|}

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

Clanker: Reconcile with the frozen v25 schema

2026-10-24T16:52:24Z

Reconcile with the frozen v25 schema

← Older revision		Revision as of 16:52, 24 October 2026
Line 15:		Line 15:
	\| 0 \|\| A peer that sends no revision: the v25 schema without the revision-gated behaviours.		\| 0 \|\| A peer that sends no revision: the v25 schema without the revision-gated behaviours.
	\|-		\|-
	\| 1 \|\| The first released v25, frozen on 24 October 2026: everything in the current [[SimTX API/Schema\|.proto files]]. Gated on the client's revision: a server keeps a station-bound session running across a station edit, with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>UPDATED</code>, <code>update_reason</code> and a station snapshot, only when the client announced revision 1 or higher. Older clients get <code>ENDED</code>.		\| 1 \|\| The first released v25, frozen on 24 October 2026: everything in the current [[SimTX API/Schema\|.proto files]], including the late additions <code>AntennaAim</code> on both starts, <code>Tracking.since_*</code>, <code>IqBlock.sequence</code>, <code>request_id</code> on ReceiverRetune and on StartMonitor / StopMonitor (acknowledged by MonitorAck), <code>BannerLevel</code> and <code>ERROR_CODE_CANCELLED</code>. Gated on the client's revision: a server keeps a station-bound session running across a station edit, with [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>UPDATED</code>, <code>update_reason</code> and a station snapshot, only when the client announced revision 1 or higher. Older clients get <code>ENDED</code>.
	\|}		\|}

	A client should send the highest revision whose behaviour it really implements. A client that announces revision 1 must handle <code>UPDATED</code> statuses with a station snapshot.		A client should send the highest revision whose behaviour it really implements. A client that announces revision 1 must handle <code>UPDATED</code> statuses with a station snapshot.

	The schema changed incompatibly before release: enum zero values, the shared <code>StationCore</code> and <code>SessionSite</code>, the single Error model, and the removal of TxReject, TxKick and ModerationError. Pre-release builds that also announced revision 0 or 1 are not v25 peers. Regenerate bindings from the current files.		The schema changed incompatibly before release: enum zero values, the shared <code>StationCore</code> and <code>SessionSite</code>, the single Error model, and the removal of TxReject, TxKick and ModerationError. That final shape is documented as revision 1 rather than 2, because no released peer predates it. Pre-release builds that also announced revision 0 or 1 are not v25 peers. Regenerate bindings from the current files.

	== Feature registry ==		== Feature registry ==

Clanker: Protocol v25 reference

2026-10-24T16:27:35Z

Protocol v25 reference

New page

{{SimTX API navigation}}
This page explains how the [[SimTX API]] game protocol changes over time, and what a client must do to keep working as it does: the protocol version, protocol revisions within a version, the feature registry, and the additive-only rule. It ends with a summary of the changes from version 24.

== Protocol version ==
The protocol version is the integer in the 8-byte [[SimTX API/Framing#Preface|preface]]. It changes only for a breaking change. A breaking change gets a new version and a new protobuf package (<code>simtx.v26</code> after <code>simtx.v25</code>), and servers answer older prefaces with a version-unsupported result rather than misreading them.

Version 25 replaced version 24 completely; the two are not compatible. See [[#Changes from v24|Changes from v24]].

== Protocol revisions ==
Within version 25, additive changes that a peer may need to detect increase the '''protocol revision'''. Both hellos carry it: <code>ClientHello.protocol_revision</code> and <code>ServerHello.protocol_revision</code> are the highest revision the sender implements. A peer relies on revision-''N'' behaviour only when the other side's revision is at least ''N''. An unset value is 0.

{| class="wikitable"
! Revision !! Adds
|-
| 0 || A peer that sends no revision: the v25 schema without the revision-gated behaviours.
|-
| 1 || The first released v25, frozen on 24 October 2026: everything in the current [[SimTX API/Schema|.proto files]]. Gated on the client's revision: a server keeps a station-bound session running across a station edit, with [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code>, <code>update_reason</code> and a station snapshot, only when the client announced revision 1 or higher. Older clients get <code>ENDED</code>.
|}

A client should send the highest revision whose behaviour it really implements. A client that announces revision 1 must handle <code>UPDATED</code> statuses with a station snapshot.

The schema changed incompatibly before release: enum zero values, the shared <code>StationCore</code> and <code>SessionSite</code>, the single Error model, and the removal of TxReject, TxKick and ModerationError. Pre-release builds that also announced revision 0 or 1 are not v25 peers. Regenerate bindings from the current files.

== Feature registry ==
Optional server capabilities that depend on the deployment rather than on the schema are listed by name in <code>ServerHello.features</code>, and per server in the [[SimTX API/Server directory|server directory]] with <code>?include=features</code>.

{| class="wikitable"
! Feature !! Meaning
|-
| <code>stations.v1</code> || Persistent stations: <code>StationBinding</code> in session starts, station-bound tickets, station entries in the station list.
|-
| <code>pointing</code> || [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] and <code>Tracking</code> are accepted.
|-
| <code>ephemeris</code> || [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] is answered.
|-
| <code>passes</code> || [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] is answered.
|-
| <code>kinematics</code> || Satellite motion (orbit, attitude, Doppler) is simulated.
|}

<code>ClientHello.features</code> uses the same names for what the client understands: send <code>stations.v1</code> if the client handles [[SimTX API/Data types#BoundStation|BoundStation]] and station-bound sessions.

Rules:
* Clients ignore feature names they do not know; servers do the same.
* Names are never reused or redefined. A changed meaning gets a new name, such as <code>stations.v2</code>.
* Treat a missing feature as "not available" and hide the user interface for it.
* Prefer feature checks for deployment capabilities and <code>protocol_revision</code> for knowledge of the schema. Avoid checks on <code>server_version</code>.
* The account service mints station-bound tickets only for servers whose every node advertises <code>stations.v1</code>; otherwise it answers <code>409 station_binding_unsupported</code>.

== Additive only ==
After the freeze, version 25 grows only by adding:
* new messages and new <code>oneof</code> members of <code>ClientFrame</code> and <code>ServerFrame</code>;
* new fields in existing messages;
* new enum values;
* new names in the [[SimTX API/Data types#String enumerations|string enumerations]] (modulations, antenna types, sources, weather layers, catalog types).

Field numbers and enum numbers are never renumbered or reused, field types and labels never change, and <code>oneof</code> membership never changes. A removed field's number and name are reserved. The schema of every revision is frozen as a binary descriptor, and the build compares the current schema against it, failing on any removed, renumbered, retyped or relabelled field, removed enum value or message, or changed <code>oneof</code> membership.

=== What a client must do ===
* '''Skip unknown frames.''' A frame whose member you do not know parses with no member set; ignore it and keep reading.
* '''Skip unknown fields''' of every wire type. Generated parsers do; hand-written codecs must.
* '''Keep unknown enum values''' and show them as unknown rather than failing.
* '''Accept unknown string-enumeration names''' from the server and show them as they are.
* '''Use presence.''' Proto3 omits zero values. Fields marked <code>optional</code> say whether they were set; unset means "use the default".
* '''Ignore unknown JSON fields''' from the account service, which follows the same rule.

== Changes from v24 ==
A summary for authors of v24 clients. The v24 reference is archived at [[SimTX API v24]].

{| class="wikitable"
! Area !! v24 !! v25
|-
| Encoding || Hand-laid big-endian packets with an ID byte and no length prefix || Protobuf messages in varint-delimited <code>ClientFrame</code> / <code>ServerFrame</code> frames; unknown frames and fields are skipped
|-
| Handshake || <code>Handshake</code> with magic, version, role, auth kind and credential || 8-byte preface, then [[SimTX API/Packets/ClientHello|ClientHello]] with client name, version, features and protocol revision
|-
| Handshake result || <code>HandshakeResult</code>, status 0 = accepted || [[SimTX API/Packets/ServerHello|ServerHello]], status 1 = accepted; adds features, protocol revision and clocks
|-
| Roles || Six roles including <code>TIMESTAMPED_RECEIVER</code> || Five roles; timestamps are an option of every receiver
|-
| Receiver start || <code>ReceiverSessionRequest</code> with inline callsign, location and antenna || [[SimTX API/Packets/ReceiverStart|ReceiverStart]] with a <code>SessionSite</code>: a station binding or an ad-hoc site; sample format, tracking
|-
| Transmitter start || <code>TransmitterSessionRequest</code>, a TLV field list || [[SimTX API/Packets/TransmitterStart|TransmitterStart]] with a <code>SessionSite</code>; imperfections in <code>TxImperfections</code>; ad-hoc transmitters need <code>tx.adhoc</code>
|-
| Stations || Each session was its own station with a new UUID || Persistent, account-owned [[SimTX API/Stations|stations]] and [[SimTX API/Satellites|satellites]]; sessions bind to them
|-
| Session state || Implicit; failures often closed the connection silently || [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>BOUND</code>, <code>UPDATED</code>, <code>REJECTED</code>, <code>ENDED</code>
|-
| Errors || <code>TxReject</code>, <code>TxKick</code>, <code>ModerationError</code>, flags in responses, silent closes || One [[SimTX API/Packets/Error|Error]] model with <code>request_id</code>; SessionStatus for sessions
|-
| IQ blocks || <code>IqBlock</code> and <code>TimedIqBlock</code> || One [[SimTX API/Packets/IqBlock|IqBlock]] with optional timestamps and a <code>sequence</code> number
|-
| Retune || No acknowledgement || Optional <code>request_id</code>, confirmed by SessionStatus <code>UPDATED</code>
|-
| Control session start || <code>ControlAck</code> || Nothing; an accepted ServerHello is enough
|-
| Requests || Most control requests had no id || Every control and moderation request has a <code>request_id</code>
|-
| Ids || UUIDs as 36-character text || UUIDs as 16 bytes
|-
| Frequencies || <code>f32</code> || <code>double</code>
|-
| New || || Ping and Pong, antenna pointing and tracking, Doppler correction, ephemerides, pass predictions, monitor acknowledgements
|}

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