Editing SimTX API v24/Control session

{{SimTX API v24 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, monitoring one's own transmitter, and the [[SimTX API v24/Extension catalog protocol|extension catalog]]. Control sessions use role 4 (<code>CONTROL</code>) and accept anonymous connections.

The official transmitter keeps one control session open for its station list, banners and catalog browser. A station map, a band-activity bot or a status page needs nothing else.

== Packets ==
{| class="wikitable"
! Request (C2S) !! Response (S2C) !! Heavy !! Purpose
|-
| [[SimTX API v24/Packets/ListStations|ListStations]] (4) || [[SimTX API v24/Packets/StationList|StationList]] (9) || Yes || All stations on the server.
|-
| [[SimTX API v24/Packets/ServerHealthRequest|ServerHealthRequest]] (10) || [[SimTX API v24/Packets/ServerHealthReport|ServerHealthReport]] (16) || Yes || Load and session statistics.
|-
| [[SimTX API v24/Packets/CoverageMapRequest|CoverageMapRequest]] (24) || [[SimTX API v24/Packets/CoverageMapResponse|CoverageMapResponse]] (27) || Yes || Predicted received power for a hypothetical transmitter.
|-
| [[SimTX API v24/Packets/WeatherMapRequest|WeatherMapRequest]] (8) || [[SimTX API v24/Packets/WeatherMapResponse|WeatherMapResponse]] (14) || Yes || Tropospheric weather raster.
|-
| [[SimTX API v24/Packets/StartMonitor|StartMonitor]] (6) || [[SimTX API v24/Packets/MonitorBlock|MonitorBlock]] (10) … [[SimTX API v24/Packets/MonitorEnd|MonitorEnd]] (11) || No || Stream of one's own transmitted signal.
|-
| [[SimTX API v24/Packets/StopMonitor|StopMonitor]] (7) || None || No || Ends a monitor stream.
|-
| [[SimTX API v24/Packets/CatalogListRequest|CatalogListRequest]] (20) || [[SimTX API v24/Packets/CatalogList|CatalogList]] (24) || Yes || Catalog index.
|-
| [[SimTX API v24/Packets/CatalogFetch|CatalogFetch]] (21) || [[SimTX API v24/Packets/CatalogEntry|CatalogEntry]] (25) || Yes || One catalog entry with its files.
|-
| [[SimTX API v24/Packets/CatalogUpload|CatalogUpload]] (22) || [[SimTX API v24/Packets/CatalogUploadResult|CatalogUploadResult]] (21) || Yes || Publish an entry.
|-
| [[SimTX API v24/Packets/CatalogDelete|CatalogDelete]] (26) || [[SimTX API v24/Packets/CatalogDeleteResult|CatalogDeleteResult]] (29) || Yes || Remove an entry.
|}

Unsolicited server packets:
* [[SimTX API v24/Packets/ControlAck|ControlAck]] (8), once, as soon as the session is accepted.
* [[SimTX API v24/Packets/Banner|Banner]] (17), on accept if a notice is active, and at any later time when a notice is set, changed or cleared.

Any other packet closes the connection.

== Sequence ==
<syntaxhighlight lang="text">
 client                                           server
   | -- Handshake (role 4, anonymous) ------------> |
   | <----------------------- [30] HandshakeResult |
   | <----------------------------- [8] ControlAck |
   | <------------------------------- [17] Banner  |   (only if a notice is active)
   | -- [4] ListStations -------------------------> |
   | <---------------------------- [9] StationList |
   |                  ...                           |
   | <------------------------------- [17] Banner  |   (any time)
</syntaxhighlight>

Responses to requests arrive in the order the requests were sent, but a [[SimTX API v24/Packets/Banner|Banner]] or a [[SimTX API v24/Packets/MonitorBlock|MonitorBlock]] may arrive between any two of them. Read the session with a loop that dispatches on the packet ID, rather than expecting a particular reply next. A [[SimTX API v24/Packets/CoverageMapResponse|CoverageMapResponse]] carries the request ID it answers, because coverage predictions may take several seconds.

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 IP || 20 per second || 40
|-
| Heavy requests, per IP || 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 '''closes the control connection''' without a message. Opening more connections does not help, since the per-IP bucket is shared.

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 v24/Packets/StationList|StationList]] contains every transmitter and receiver on the server, with callsign, frequency, mode, power, position and occupied bandwidth. Client IP addresses are never included on a control session. The list is a snapshot. Clients that need to follow changes poll it.

== Health report ==
[[SimTX API v24/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, the power a standard receiving antenna would see across the whole globe. Coverage prediction is optional and is '''disabled by default'''; a server without it answers every request as unavailable. One prediction runs at a time on the whole server, with one more waiting. See [[SimTX API v24/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 v24/Packets/WeatherMapRequest|WeatherMapRequest]].

== Monitoring a transmitter ==
[[SimTX API v24/Packets/StartMonitor|StartMonitor]] streams the complex baseband a transmitter is producing, after its modulator and amplifier model but before the antenna and propagation. It is how the official application lets an operator hear their own signal.

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

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

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

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