Session Lifecycle¶

An external session follows this sequence:

hello
query_state
subscribe
commands and events

Required Sequence¶

The first three frames sent by a driver establish authentication, the authoritative state baseline, and the event subscription.

First frames sent by the driver

{"type":"hello","protocol_version":"1.0","auth":{"token":"integration-secret"}}
{"type":"query_state"}
{"type":"subscribe"}

Reconnect rule

Repeat the full lifecycle after every reconnect and discard stale local assumptions until the new baseline is applied.

Authentication¶

External clients authenticate in hello using an integration token supplied by the installer or operator.

Invalid, missing, or revoked tokens produce error_response(error_code="unauthorized") and the connection closes.

Clients must send protocol_version: "1.0" on hello. The successful response echoes that negotiated version. The redundant auth.mode field is forbidden, and the response omits constant status.

Every later external request and response must omit protocol_version; sending it after hello is an invalid_message error.

Baseline¶

After hello, send query_state before subscribing or commanding. Apply its response as the authoritative baseline before processing later deltas.

The external baseline contains motors and groups. It does not contain processor settings or group membership topology. Supported scopes are all, motors, and groups.

After a successful baseline, subscribe requests the complete external event stream. There is no filter. The request and acknowledgement contain only type="subscribe" plus an optional request_id; the acknowledgement has no constant success status.

Baseline Recovery¶

The processor preflights the complete serialized response against the 1 MiB external frame limit. If scope="all" is too large, it returns a correlated error_response(error_code="response_too_large", retryable=false), keeps the connection open, and leaves the session query-required. Request scope="motors" and then scope="groups" to assemble the baseline without reconnecting. A successful scoped query advances the lifecycle. If either individual scope is still too large, it returns the same error; protocol 1.0 does not paginate.

Liveness¶

With default settings, the processor closes an external connection after 90 seconds without an inbound frame. A long-lived client should send ping every 30 seconds while it has no other requests to send. Outbound events do not extend the inbound deadline.

ping is available after hello. It does not advance lifecycle state and does not replace reconnect re-baselining. A pong is a direct response and may arrive interleaved with subscribed events or a deferred command response.

Request Correlation¶

request_id is optional on every request. When supplied, it must be a string containing 1 through 64 Unicode code points. The matching normal or error response echoes a valid ID; otherwise the response omits it. Empty, non-string, and over-length IDs produce an uncorrelated invalid_message. An ID-less client should keep at most one request outstanding so direct responses remain unambiguous.