Editing SimTX API/Schema (section)

== frames.proto ==
<syntaxhighlight lang="protobuf">
// SimTX wire protocol v25: connection framing.
//
// Byte stream: the client sends the 8-byte preface  i32be 0x53494D54 ("SIMT"), i32be 25.
// From then on, each direction is a sequence of frames: varint length + one ClientFrame /
// ServerFrame message (protobuf "delimited" encoding). Max frame 16 MiB; the client hello frame
// at most 64 KiB. Receivers also bound a frame's shape (nested messages, list elements and
// unknown fields; never the group encoding). Unknown oneof members are skipped by the receiver.
// The first client frame must be `hello`; the first server frame is `hello_result`.
//
// Protocol revisions (ClientHello / ServerHello `protocol_revision`): each side sends the highest
// revision it implements and relies on revision-N behaviour only when the peer's revision is >= N.
// Revision 1 is the current protocol; clients send 1. A server keeps a station-bound session
// running across a station edit (SessionStatus UPDATED with update_reason and a station snapshot)
// only when the client's revision is >= 1; other clients get ENDED.
//
// Feature registry (ServerHello `features`): optional server capabilities that depend on the
// deployment rather than on the schema. Clients ignore names they do not know; names are never
// reused or redefined (a changed meaning gets a new name, e.g. stations.v2).
//   stations.v1  persistent stations: StationBinding in session starts, StationList entries
//   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 (stations.v1: it
// handles BoundStation and station-bound sessions); servers ignore names they do not know.
// Prefer protocol_revision for schema-level knowledge.
syntax = "proto3";

package simtx.v25;

import "simtx/v25/common.proto";
import "simtx/v25/session.proto";
import "simtx/v25/control.proto";

// Required: servers reject a hello with UNSPECIFIED (or an unknown role).
enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_RECEIVER = 1;
  ROLE_TX_AUDIO = 2;
  ROLE_TX_GENERATED = 3;
  ROLE_CONTROL = 4;
  ROLE_MODERATION = 5;
}

// 0 = ANONYMOUS. An anonymous hello that carries a credential is refused.
enum AuthKind {
  AUTH_KIND_ANONYMOUS = 0;
  AUTH_KIND_GAME_TICKET = 1;
}

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
}

// 0 = UNSPECIFIED: clients treat it (and unknown values) as SERVER_UNAVAILABLE.
enum HelloStatus {
  HELLO_STATUS_UNSPECIFIED = 0;
  HELLO_STATUS_ACCEPTED = 1;
  HELLO_STATUS_VERSION_UNSUPPORTED = 2;
  HELLO_STATUS_AUTHENTICATION_REQUIRED = 3;
  HELLO_STATUS_CREDENTIAL_INVALID = 4;
  HELLO_STATUS_ACCOUNT_RESTRICTED = 5;
  HELLO_STATUS_ROLE_FORBIDDEN = 6;
  HELLO_STATUS_SERVER_UNAVAILABLE = 7;
  HELLO_STATUS_IP_BANNED = 8;
}

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;
}

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
}

message Ping { int64 nonce = 1; int64 client_time_ms = 2; }
message Pong { int64 nonce = 1; int64 client_time_ms = 2; int64 server_time_ms = 3; }

message ForwardedClientAddress { string address = 1; }   // trusted proxies only, before ReceiverStart

// The one error frame. request_id echoes the failed request (control and moderation requests,
// TxUpdate, AntennaPointingUpdate, ReceiverRetune, Start/StopMonitor); 0 = the connection as a
// whole (a protocol violation: the connection closes after it). Session refusals and ends use
// SessionStatus REJECTED / ENDED instead.
message Error {
  ErrorCode code = 1;
  string message = 2;
  int64 request_id = 3;
}

// Frame member numbers are allocated by block, in both ClientFrame and ServerFrame:
// 1-9 connection (hello, ping, errors), 10-29 RX/TX sessions, 30-59 control, 60-79 moderation,
// 80-99 reserved for the next area. Numbers 1-15 encode the tag in one byte.
message ClientFrame {
  oneof msg {
    ClientHello hello = 1;
    Ping ping = 2;
    ForwardedClientAddress forwarded_address = 3;
    ReceiverStart receiver_start = 10;
    ReceiverRetune receiver_retune = 11;
    TransmitterStart transmitter_start = 12;
    SampleBlock samples = 13;
    TxUpdate tx_update = 14;
    TxModeInfo tx_mode_info = 15;
    AntennaPointingUpdate pointing = 16;
    ListStations list_stations = 30;
    StartMonitor start_monitor = 31;
    StopMonitor stop_monitor = 32;
    WeatherMapRequest weather_map = 33;
    ServerHealthRequest health = 34;
    CoverageMapRequest coverage_map = 35;
    CatalogListRequest catalog_list = 36;
    CatalogFetch catalog_fetch = 37;
    CatalogUpload catalog_upload = 38;
    CatalogDelete catalog_delete = 39;
    EphemerisRequest ephemeris = 40;
    PassPredictionRequest passes = 41;
    KickRequest kick = 60;
    IpModerationRequest ip_moderation = 61;
    BroadcastBanner broadcast_banner = 62;
  }
}

message ServerFrame {
  reserved 15, 16, 62;
  oneof msg {
    ServerHello hello_result = 1;
    Pong pong = 2;
    Error error = 3;
    Banner banner = 4;
    SessionStatus session_status = 10;
    IqStreamDescriptor iq_descriptor = 11;
    IqBlock iq = 12;
    TxQueue tx_queue = 13;
    TxAccept tx_accept = 14;
    TxTelemetry tx_telemetry = 17;
    TxUpdateAck tx_update_ack = 18;
    StationList station_list = 30;
    MonitorBlock monitor_block = 31;
    MonitorEnd monitor_end = 32;
    WeatherMapResponse weather_map = 33;
    ServerHealthReport health = 34;
    CoverageMapResponse coverage_map = 35;
    CatalogList catalog_list = 36;
    CatalogEntry catalog_entry = 37;
    CatalogUploadResult catalog_upload_result = 38;
    CatalogDeleteResult catalog_delete_result = 39;
    EphemerisResponse ephemeris = 40;
    PassPredictionResponse passes = 41;
    MonitorAck monitor_ack = 42;
    KickResult kick_result = 60;
    IpModerationResult ip_moderation_result = 61;
    StationImpactList station_impacts = 63;
  }
}
</syntaxhighlight>