Editing SimTX API/Session status

{{SimTX API navigation}}
Every receiver and transmitter session is described to the client by [[SimTX API/Packets/SessionStatus|SessionStatus]] frames: once when the server accepts the start, whenever the session changes and keeps running, and when it is refused or stopped. This page describes that life cycle. It applies to <code>ROLE_RECEIVER</code>, <code>ROLE_TX_AUDIO</code> and <code>ROLE_TX_GENERATED</code>; control and moderation sessions report failures with [[SimTX API/Packets/Error|Error]] instead.

<syntaxhighlight lang="protobuf">
message SessionStatus {
  SessionState state = 1;
  string reason = 2;
  ErrorCode code = 3;
  bytes session_id = 4;          // per-connection id (the transmission id for TX)
  BoundStation station = 5;      // unset for ad-hoc sessions
  double frequency_hz = 6;
  Tracking tracking = 7;
  AntennaPointing pointing = 8;
  int64 request_id = 9;          // echoes AntennaPointingUpdate / ReceiverRetune request_id
  UpdateReason update_reason = 10;  // UPDATED only
}
</syntaxhighlight>

== Life cycle ==
<syntaxhighlight lang="text">
 client                                                 server
   | -- [10] receiver_start / [12] transmitter_start --> |
   | <------------- [10] session_status  REJECTED ------- |   code + reason, then close
   |                         or                           |
   | <------------- [10] session_status  BOUND ---------- |   session_id, station, frequency
   |                    ... stream runs ...               |
   | <------------- [10] session_status  UPDATED -------- |   update_reason + current state
   | <------------- [10] session_status  UPDATED -------- |
   |                    ... stream runs ...               |
   | <------------- [10] session_status  ENDED ---------- |   code + reason, then close
</syntaxhighlight>

{| class="wikitable"
! State !! When !! Afterwards
|-
| <code>BOUND</code> || Once, when the start is accepted. || The stream begins: [[SimTX API/Packets/IqStreamDescriptor|IqStreamDescriptor]] for a receiver, [[SimTX API/Packets/TxQueue|TxQueue]] and [[SimTX API/Packets/TxAccept|TxAccept]] for a transmitter.
|-
| <code>REJECTED</code> || Instead of <code>BOUND</code>, when the start cannot be accepted. || The connection closes.
|-
| <code>UPDATED</code> || Any number of times, when something about the running session changed. || The session continues.
|-
| <code>ENDED</code> || When the server stops a running session. || The connection closes.
|}

<code>REJECTED</code> and <code>ENDED</code> are the only refusal and kick signal, for receivers and transmitters alike. They carry an [[SimTX API/Data types#ErrorCode|ErrorCode]] in <code>code</code> and a human-readable <code>reason</code>. Show the reason to the user; branch on the code.

A session can also end without a SessionStatus, when the connection itself fails or the account's lease runs out. Treat a closed connection as the end of the session.

== BOUND ==
<code>BOUND</code> describes the session as the server runs it:
* <code>session_id</code>: a 16-byte id for this session. For a transmitter it is the transmission id. It identifies the session in [[SimTX API/Packets/StationList|station lists]], [[SimTX API/Packets/ServerHealthReport|health reports]] and the [[SimTX API/Packets/StartMonitor|own-transmitter monitor]]. Keep it.
* <code>station</code>: for a station-bound session, the [[SimTX API/Data types#BoundStation|BoundStation]] the server resolved: station, antenna and rig with their revisions, the effective PA cap, and the antenna as modelled. Show the user what the station dictates from it. Unset for ad-hoc sessions.
* <code>frequency_hz</code>, <code>tracking</code>, <code>pointing</code>: the current values. Unset <code>tracking</code> or <code>pointing</code> means none.

== UPDATED ==
<code>UPDATED</code> means the session keeps running with a changed state. <code>update_reason</code> gives the most significant cause:

{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>UPDATE_REASON_UNSPECIFIED</code> || Not an <code>UPDATED</code> status. On an <code>UPDATED</code> status: apply the snapshot fields.
|-
| 1 || <code>UPDATE_REASON_POINTING</code> || This session's [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] was applied (<code>request_id</code>).
|-
| 2 || <code>UPDATE_REASON_TRACKING</code> || The server changed tracking, for example because the target was deleted or reentered.
|-
| 3 || <code>UPDATE_REASON_STATION_EDIT</code> || The station, its antenna or its rig was edited; revisions are bumped.
|-
| 4 || <code>UPDATE_REASON_ORBIT_CHANGE</code> || The bound satellite's elements or attitude changed.
|-
| 5 || <code>UPDATE_REASON_DEORBIT_SCHEDULED</code> || The bound satellite fired its deorbit burn; <code>station.core.deorbit</code> says when it reenters.
|-
| 6 || <code>UPDATE_REASON_RETUNE</code> || This session's [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] took effect (<code>request_id</code>).
|}

Rules for applying an update:
* <code>frequency_hz</code>, <code>tracking</code> and <code>pointing</code> are always the current values. Replace the client's copies.
* <code>station</code> is set only when the station changed (<code>STATION_EDIT</code>, <code>ORBIT_CHANGE</code>, <code>DEORBIT_SCHEDULED</code>). It replaces the client's copy as a whole. Unset means unchanged.
* <code>request_id</code> is set when the update confirms the client's own request: an [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]] (<code>POINTING</code>) or a [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]] (<code>RETUNE</code>).
* A reason the client does not know, or <code>UPDATE_REASON_UNSPECIFIED</code>, means "apply the snapshot fields".
* Statuses arrive in order on one connection, so the last one received is the current state.

=== Station edits and protocol revisions ===
A station-bound session keeps the station snapshot it was bound with. When the owner edits the station, its antenna or its rig in a way the session can follow, a server sends <code>UPDATED</code> with <code>STATION_EDIT</code> and the new snapshot, with the revisions bumped. It does this only for clients whose [[SimTX API/Packets/ClientHello|ClientHello]] carried <code>protocol_revision</code> ≥ 1. A client that announced no revision gets <code>ENDED</code> instead and must reconnect to pick up the new revision. See [[SimTX API/Compatibility and versioning#Protocol revisions|Protocol revisions]].

Edits a session cannot follow always end it, whatever the revision: the station is deleted, its bound antenna or rig is removed, or the account loses access to it.

=== Satellites ===
A session bound to a satellite also gets <code>UPDATED</code> when the satellite's orbit or attitude changes (<code>ORBIT_CHANGE</code>) and when its owner fires the deorbit burn (<code>DEORBIT_SCHEDULED</code>). After <code>DEORBIT_SCHEDULED</code>, <code>station.core.deorbit.reentry_at_ms</code> says when the session will end. At that time the server ends it with <code>ENDED</code> and the reason ''Satellite burned up on reentry''. See [[SimTX API/Satellites#Deorbit|Deorbit]].

When the target of a session's tracking disappears, for example because the tracked satellite reentered, the server changes the tracking and sends <code>UPDATED</code> with <code>TRACKING</code>.

== REJECTED ==
Typical codes:

{| class="wikitable"
! Code !! Typical cause
|-
| <code>INVALID_REQUEST</code> || A value outside its range, no site, an unknown modulation or antenna type, an invalid NEC deck.
|-
| <code>FORBIDDEN</code> || A station-bound start without a ticket for that station; a binding that does not match the ticket; a ticket bound to a station used with an ad-hoc site; transmitting through someone else's station.
|-
| <code>STATION_INACTIVE</code> || The station was deleted, or the satellite has reentered.
|-
| <code>STATION_REQUIRED</code> || An ad-hoc transmitter without <code>tx.adhoc</code> on a server whose policy refuses ad-hoc transmitters.
|-
| <code>LIMIT_REACHED</code> || A server, address, account or station limit, or the wideband budget.
|-
| <code>UNAVAILABLE</code> || The server cannot place the session right now, for example no transmitter capacity.
|}

== ENDED ==
Typical causes are a moderator's kick, a ban of the client's address, the station being deleted or losing its antenna or rig, the account losing access, and a satellite's reentry. A session that simply ended may carry <code>ERROR_CODE_UNSPECIFIED</code>.

There is no session resumption. To continue, mint a new [[SimTX API/Game tickets|ticket]] if the connection was authenticated, and reconnect with exponential backoff. See [[SimTX API/Limits and errors#Reconnecting|Reconnecting]].

== Examples ==
'''<code>session_status_rejected_station_required</code>''' (server to client, 56 bytes):

<syntaxhighlight lang="text">
37                                 frame length 55
52 35                              session_status (SessionStatus), 53 bytes
  08 02                            state = 2 (SESSION_STATE_REJECTED)
  12 2F 41 64 2D 68 6F 63 20 74 …  reason = "Ad-hoc transmitters are disabled on this server"
  18 09                            code = 9 (ERROR_CODE_STATION_REQUIRED)
</syntaxhighlight>

'''<code>session_status_updated_retune</code>''' (server to client, 36 bytes):

<syntaxhighlight lang="text">
23                            frame length 35
52 21                         session_status (SessionStatus), 33 bytes
  08 04                       state = 4 (SESSION_STATE_UPDATED)
  22 10 AA AA AA AA …         session_id = aaaaaaaa-bbbb-4ccc-8ddd-ffffffffffff
  31 00 00 00 00 12 D8 6A 41  frequency_hz = 14074000.0
  48 29                       request_id = 41
  50 06                       update_reason = 6 (UPDATE_REASON_RETUNE)
</syntaxhighlight>

'''<code>session_status_ended_kicked</code>''' (server to client, 46 bytes):

<syntaxhighlight lang="text">
2D                                 frame length 45
52 2B                              session_status (SessionStatus), 43 bytes
  08 03                            state = 3 (SESSION_STATE_ENDED)
  12 15 4B 69 63 6B 65 64 20 62 …  reason = "Kicked by a moderator"
  22 10 AA AA AA AA …              session_id = aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
</syntaxhighlight>

More examples, including a satellite <code>BOUND</code> with its station snapshot, are on the [[SimTX API/Packets/SessionStatus|SessionStatus]] page.

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