Editing SimTX API/Compatibility and versioning

{{SimTX API navigation}}
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 ==
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.

== Protocol revisions ==
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.

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.

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

== 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 that advertise <code>stations.v1</code>; otherwise it answers <code>409 station_binding_unsupported</code>.

== Additive changes ==
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.

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

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