Jump to content

SimTX API/Compatibility and versioning: Difference between revisions

From SimTX Wiki
← Older edit
VisualWikitext
Clanker (talk | contribs)
660 edits
Reconcile with the frozen v25 schema
Clanker (talk | contribs)
660 edits
Remove development history and server internals
 
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]]

Latest revision as of 17:16, 24 October 2026

API overviewQuick startHandshakeFramingAll messagesData typesStationsAccount serviceLimits and errorsv24 reference

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[edit | edit source]

The protocol version is the integer in the 8-byte preface. The current version is 25, protobuf package simtx.v25. A server refuses a preface with any other version. An incompatible change would get a new version number and a new package.

Protocol revisions[edit | edit source]

Both hellos carry protocol_revision: ClientHello.protocol_revision and ServerHello.protocol_revision are the highest revision the sender implements. Revision 1 is the current protocol. Clients send 1.

A server keeps a station-bound session running across a station edit, with SessionStatus UPDATED, update_reason and a station snapshot, only for clients that announce revision 1 or higher. A client that announces nothing gets ENDED instead and must reconnect.

Behaviour tied to a revision applies only when the other side announced at least that revision.

Feature registry[edit | edit source]

Optional server capabilities that depend on the deployment rather than on the schema are listed by name in ServerHello.features, and per server in the server directory with ?include=features.

Feature Meaning
stations.v1 Persistent stations: StationBinding in session starts, station-bound tickets, station entries in the station list.
pointing AntennaPointingUpdate and Tracking are accepted.
ephemeris EphemerisRequest is answered.
passes PassPredictionRequest is answered.
kinematics Satellite motion (orbit, attitude, Doppler) is simulated.

ClientHello.features uses the same names for what the client understands: send stations.v1 if the client handles 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 stations.v2.
  • Treat a missing feature as "not available" and hide the user interface for it.
  • Prefer feature checks for deployment capabilities and protocol_revision for knowledge of the schema. Avoid checks on server_version.
  • The account service mints station-bound tickets only for servers that advertise stations.v1; otherwise it answers 409 station_binding_unsupported.

Additive changes[edit | edit source]

Version 25 grows only by adding:

  • new messages and new oneof members of ClientFrame and ServerFrame;
  • new fields in existing messages;
  • new enum values;
  • new names in the 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 oneof membership never changes.

What a client must do[edit | edit source]

  • 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 optional say whether they were set; unset means "use the default".
  • Ignore unknown JSON fields from the account service, which follows the same rule.
SimTX API reference (protocol v25)
Start OverviewQuick startFramingData typesPacket listSchemaLimits and errorsCompatibility and versioning
Account service OverviewDevice loginServer directoryStation endpointsGame ticketsPermissionsPublic endpoints
Game protocol Connection and handshakeSession statusReceiver sessionTransmitter sessionControl sessionCatalogModeration
Stations StationsSatellitesTracking and pointing
Connection ClientHelloPingServerHelloPongErrorBanner
Session AntennaPointingUpdateSessionStatus
Receiver ForwardedClientAddressReceiverStartReceiverRetuneIqStreamDescriptorIqBlock
Transmitter TransmitterStartSampleBlockTxUpdateTxModeInfoTxQueueTxAcceptTxTelemetryTxUpdateAck
Control ListStationsStartMonitorStopMonitorWeatherMapRequestServerHealthRequestCoverageMapRequestEphemerisRequestPassPredictionRequestStationListMonitorBlockMonitorEndWeatherMapResponseServerHealthReportCoverageMapResponseEphemerisResponsePassPredictionResponseMonitorAck
Catalog CatalogListRequestCatalogFetchCatalogUploadCatalogDeleteCatalogListCatalogEntryCatalogUploadResultCatalogDeleteResult
Moderation KickRequestIpModerationRequestBroadcastBannerKickResultIpModerationResultStationImpactList
Archive Protocol v24 reference
Retrieved from "https://wiki.simtx.net/index.php?title=SimTX_API/Compatibility_and_versioning&oldid=2395"