Editing SimTX API/Control session

{{SimTX API navigation}}
A '''control session''' is a request-response channel for everything that is not a radio stream: the list of stations on the server, server-wide notices, health statistics, predicted coverage and tropospheric weather maps, satellite ephemerides and pass predictions, monitoring one's own transmitter, and the [[SimTX API/Extension catalog protocol|extension catalog]]. Control sessions use <code>ROLE_CONTROL</code> and accept anonymous connections.

== Requests ==
Every request carries a nonzero <code>request_id</code> chosen by the client. The response echoes it. A request that fails is answered with [[SimTX API/Packets/Error|Error]] carrying the same <code>request_id</code> instead of its response; responses describe success only.

{| class="wikitable"
! Request (C2S) !! Response (S2C) !! Heavy !! Purpose
|-
| [[SimTX API/Packets/ListStations|ListStations]] (30) || [[SimTX API/Packets/StationList|StationList]] (30) || Yes || Stations, satellites and live sessions on the server.
|-
| [[SimTX API/Packets/ServerHealthRequest|ServerHealthRequest]] (34) || [[SimTX API/Packets/ServerHealthReport|ServerHealthReport]] (34) || Yes || Load and session statistics.
|-
| [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]] (35) || [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] (35) || Yes || Predicted received power for a hypothetical transmitter.
|-
| [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]] (33) || [[SimTX API/Packets/WeatherMapResponse|WeatherMapResponse]] (33) || Yes || Tropospheric weather raster.
|-
| [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] (40) || [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]] (40) || Yes || Positions of a satellite over a time window.
|-
| [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] (41) || [[SimTX API/Packets/PassPredictionResponse|PassPredictionResponse]] (41) || Yes || Passes of a satellite over an observer.
|-
| [[SimTX API/Packets/StartMonitor|StartMonitor]] (31) || [[SimTX API/Packets/MonitorAck|MonitorAck]] (42), then [[SimTX API/Packets/MonitorBlock|MonitorBlock]] (31) ... [[SimTX API/Packets/MonitorEnd|MonitorEnd]] (32) || No || Stream of one's own transmitted signal.
|-
| [[SimTX API/Packets/StopMonitor|StopMonitor]] (32) || [[SimTX API/Packets/MonitorAck|MonitorAck]] (42) || No || Ends a monitor stream.
|-
| [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] (36) || [[SimTX API/Packets/CatalogList|CatalogList]] (36) || Yes || Catalog index.
|-
| [[SimTX API/Packets/CatalogFetch|CatalogFetch]] (37) || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] (37) || Yes || One catalog entry with its files.
|-
| [[SimTX API/Packets/CatalogUpload|CatalogUpload]] (38) || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] (38) || Yes || Publish an entry.
|-
| [[SimTX API/Packets/CatalogDelete|CatalogDelete]] (39) || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] (39) || Yes || Remove an entry.
|}

The numbers are the frame member numbers. [[SimTX API/Packets/Ping|Ping]] is also accepted. Any other frame is answered with [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code> and the connection closes.

Unsolicited server frames:
* [[SimTX API/Packets/Banner|Banner]] (4), when the session starts if a notice is active, and at any later time when a notice is set, changed or cleared.
* [[SimTX API/Packets/MonitorBlock|MonitorBlock]] and [[SimTX API/Packets/MonitorEnd|MonitorEnd]] while a monitor runs.

== Sequence ==
<syntaxhighlight lang="text">
 client                                              server
   | -- preface, [1] hello (ROLE_CONTROL) ----------> |
   | <------------------------ [1] hello_result      |
   | <------------------------ [4] banner            |   (only if a notice is active)
   | -- [30] list_stations (request_id 1) ----------> |
   | <------------------------ [30] station_list     |   request_id 1
   | -- [40] ephemeris (request_id 2) --------------> |
   | <------------------------ [3] error             |   request_id 2, NOT_FOUND
   |                   ...                            |
   | <------------------------ [4] banner            |   (any time)
</syntaxhighlight>

A control session is ready as soon as its [[SimTX API/Packets/ServerHello|ServerHello]] is <code>ACCEPTED</code>. Responses arrive in the order the requests were sent, but a Banner, a MonitorBlock or a Pong may arrive between any two of them, and slow requests (coverage maps, ephemerides, passes) are answered when they finish. Read the session with a loop that dispatches on the frame member and matches responses by <code>request_id</code>.

The session has no idle timeout. A client may keep it open indefinitely and send requests when needed.

== Rate limits ==
Control requests are limited by token buckets shared by '''all control connections from the same IP address''':

{| class="wikitable"
! Bucket !! Sustained !! Burst
|-
| All requests, per address || 20 per second || 40
|-
| Heavy requests, per address || 4 per second || 12
|-
| All requests, whole server || 200 per second || 400
|-
| Heavy requests, whole server || 40 per second || 80
|}

A heavy request draws from both its heavy bucket and the general bucket. Exceeding a limit is answered with [[SimTX API/Packets/Error|Error]] <code>RATE_LIMITED</code> (naming the request that overran) and '''closes the control connection'''.

In practice: poll the station list every few seconds at most, request the health report rarely, and do not fetch the whole catalog in a tight loop. A client that reconnects after being closed for rate limiting should wait a few seconds first.

== Station list ==
[[SimTX API/Packets/StationList|StationList]] lists persistent stations with their live sessions, every visible satellite even when nobody is attached, and ad-hoc sessions as entries of kind <code>ADHOC</code>. UNLISTED stations of other accounts appear only as ad-hoc-style entries with their callsign. Client addresses are never included on a control session. The list is a snapshot; clients that need to follow changes poll it.

For map markers, use <code>LiveSession.location</code>: for a satellite it is the satellite's position, and it moves. Satellites can also be drawn between polls by propagating <code>core.orbit</code>; see [[SimTX API/Satellites]].

== Health report ==
[[SimTX API/Packets/ServerHealthReport|ServerHealthReport]] exposes the server's load: CPU, memory, simulation tick timing, worker queues, and per-session statistics for every transmitter and receiver. It is intended for status pages and operators. Client addresses in it are empty unless the account holds <code>monitor.any</code> or <code>moderation.manage</code>.

== Maps ==
* '''Coverage maps''' predict, for a hypothetical transmitter at a [[SimTX API/Data types#SessionSite|site]], the power a reference receiving antenna would see across the whole globe. Servers enable them by default. One prediction runs at a time on the whole server, with one more waiting; a newer request on the same session cancels the previous one, which is answered with [[SimTX API/Packets/Error|Error]] <code>CANCELLED</code>. See [[SimTX API/Packets/CoverageMapRequest|CoverageMapRequest]].
* '''Weather maps''' show the simulated troposphere over a chosen area: duct strength, rain rate, cloud water, surface temperature or lightning rate. They affect VHF and higher propagation. See [[SimTX API/Packets/WeatherMapRequest|WeatherMapRequest]].

== Ephemerides and passes ==
[[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] returns the positions of a satellite at regular steps; [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] returns when a satellite rises above an observer's horizon. They need the server features <code>ephemeris</code> and <code>passes</code>, listed in the [[SimTX API/Packets/ServerHello|ServerHello]]. The satellite must be PUBLIC or the account's own. Use the server's simulation clock as "now". See [[SimTX API/Satellites]].

== Monitoring a transmitter ==
[[SimTX API/Packets/StartMonitor|StartMonitor]] streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation.

Only transmitters belonging to the same account can be monitored, so the control session must be authenticated. Monitoring requires <code>catalog.publish</code>: the account service issues <code>control</code> tickets only to credentials with that permission. See [[SimTX API/Game tickets#Roles|Game tickets]].

The <code>session_id</code> to monitor is the one in the transmitter's own [[SimTX API/Packets/SessionStatus|SessionStatus]], or a <code>LiveSession.session_id</code> from the station list. The server confirms with [[SimTX API/Packets/MonitorAck|MonitorAck]] and then streams [[SimTX API/Packets/MonitorBlock|MonitorBlock]] frames; [[SimTX API/Packets/StopMonitor|StopMonitor]] is confirmed by a MonitorAck with <code>active = false</code>. When the transmitter goes off the air, the server sends [[SimTX API/Packets/MonitorEnd|MonitorEnd]].

Monitor blocks share the control session's output queue (64 frames or 8 MiB). A client that does not read them fast enough has its control connection closed.

== See also ==
* [[SimTX API/Extension catalog protocol]]: the catalog requests in detail.
* [[SimTX API/Moderation session]]: the moderator equivalent of this session.
* [[SimTX API/Limits and errors]]

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