Module state 

Vehicle-state codec for the state socket (Contract B).

The state is a JSON telemetry snapshot (attitude, position, GPS, battery, mode, armed, link stats). The producer broadcasts it as length-prefixed msgpack (v2): a 4-byte big-endian length followed by a versioned map body {"v": <version>, "s": <state>}. The v integer lets a reader reject a frame it does not understand rather than mis-decode it.

This module also keeps the legacy v1 reader (newline-terminated JSON) so a stray v1 frame still decodes; the auto-detect reader picks the format per frame off the leading byte. The state is kept as an open serde_json::Value map rather than a fixed struct so new telemetry fields round-trip without a schema change.

Enums

StateError

Constants

MAX_CONSECUTIVE_VERSION_MISMATCHES

How many consecutive version-mismatched frames a reader skips before it gives up on the connection. The producer publishes at 10 Hz, so this is under a second of frames: long enough to ride out one stray frame, short enough that a producer/reader version skew surfaces as an error instead of a live connection that never yields a snapshot.

STATE_V2_MAX_FRAME

Maximum v2 state frame payload. State snapshots are small (a few KiB); the cap is generous headroom and guards against a runaway producer.

STATE_WIRE_VERSION

The on-wire version integer carried in the v2 frame body’s v field. Kept in lock-step with the contract registry (state.v2) — a test asserts they are equal so the wire and the registry can never silently diverge. A reader rejects any frame whose v does not match this.

Functions

decode_v2

Decode a v2 msgpack body (the frame payload, without the length prefix) into its inner state snapshot. Reads the version integer first and returns StateError::Version if it is not STATE_WIRE_VERSION, so a newer / unknown frame is rejected rather than mis-read as the current shape.

decode_v1_line

Decode one v1 line (with or without the trailing newline) into a state snapshot.

encode_v1

Encode a state snapshot in the v1 wire format: compact JSON terminated by a newline. Equivalent to Python json.dumps(state).encode() + b"\n".

encode_v2

Encode a state snapshot as a complete v2 frame: a 4-byte big-endian length followed by the msgpack body {"v": STATE_WIRE_VERSION, "s": state}.

read_state_value

Read exactly one state snapshot from reader, auto-detecting the wire format from the leading byte:

read_state_value_blocking

Blocking sibling of read_state_value for the sync heartbeat-enrichment path, which reads one snapshot under a socket read timeout rather than on a tokio task. Shares the exact framing + decode core (v2_body_len + decode_state_body); only the byte pump differs.

read_state_value_into

read_state_value reading each frame into the caller’s buf, so a long-lived subscriber reuses one allocation for every snapshot instead of allocating a body per frame. The buffer’s contents are scratch on return.

version_mismatch_skips

Total state frames this process skipped because their wire version did not match STATE_WIRE_VERSION, for status surfaces.