GRI-1854: protocol envelope, registration and media transfer frames #84

Merged
vivy merged 1 commit from feature/GRI-1854-protocol-envelope into dev 2026-11-09 19:36:12 +00:00
Member

Part of GRI-1854 (signage #20). The contract from #79 (GRI-1763) leaves four gaps that the client and the server have to agree on. This PR closes them in crates/shared/src/protocol.rs and plan/shared/protocol.md. It is small on purpose, so it can land before the client sync PR and before the server side of #12, #14 and #16 is written.

What is added

  1. An envelope for every frame after the handshake. PlaylistPush and MediaManifest had no tag, so a peer could not tell them apart.
    • ServerMessage (untagged) wraps EnrolmentUpdate and a new ServerControl, tagged "type": playlist_push, media_manifest, transfer_offer, plus an Unknown fallback.
    • ClientMessage, tagged: registration, heartbeat, transfer_accept, transfer_complete, plus Unknown.
    • The pinned EnrolmentUpdate wire form does not change. A test proves that.
  2. Registration. Hostname and architecture are required. OS, kernel and MAC addresses are optional. The client sends it on each Pending connection, and the panel uses the hostname as the default device name.
  3. Media transfer frames. TransferOffer, TransferAccept, TransferComplete, and the binary chunk layout: a 12-byte header (transfer_id u32 BE, offset u64 BE) followed by at most 256 KiB of data. The resume and verify rules are written out in protocol.md.
  4. DEVICE_WS_PATH = "/ws/device" and HEARTBEAT_INTERVAL_SECONDS = 30.

protocol.md also gains a section called "The session, in order", which says what each HelloOutcome makes the client do.

Reversibility: this is a one-way change to the wire format, but no code on either side uses it yet. That makes now the cheapest moment to settle it.

For the server side (Nyssa, #12): the server is free to keep a pending connection open and send Approved on it, or to close it and let the client reconnect. The client will handle both.

Tests: 12 new unit tests in shared. ./scripts/local-gates.sh --rust-only passes locally. There is no front-end change.

Part of GRI-1854 (signage #20). The contract from #79 (GRI-1763) leaves four gaps that the client and the server have to agree on. This PR closes them in `crates/shared/src/protocol.rs` and `plan/shared/protocol.md`. It is small on purpose, so it can land before the client sync PR and before the server side of #12, #14 and #16 is written. **What is added** 1. **An envelope for every frame after the handshake.** `PlaylistPush` and `MediaManifest` had no tag, so a peer could not tell them apart. - `ServerMessage` (untagged) wraps `EnrolmentUpdate` and a new `ServerControl`, tagged `"type"`: `playlist_push`, `media_manifest`, `transfer_offer`, plus an `Unknown` fallback. - `ClientMessage`, tagged: `registration`, `heartbeat`, `transfer_accept`, `transfer_complete`, plus `Unknown`. - The pinned `EnrolmentUpdate` wire form does not change. A test proves that. 2. **Registration.** Hostname and architecture are required. OS, kernel and MAC addresses are optional. The client sends it on each `Pending` connection, and the panel uses the hostname as the default device name. 3. **Media transfer frames.** `TransferOffer`, `TransferAccept`, `TransferComplete`, and the binary chunk layout: a 12-byte header (`transfer_id` u32 BE, `offset` u64 BE) followed by at most 256 KiB of data. The resume and verify rules are written out in protocol.md. 4. **`DEVICE_WS_PATH = "/ws/device"`** and `HEARTBEAT_INTERVAL_SECONDS = 30`. protocol.md also gains a section called "The session, in order", which says what each `HelloOutcome` makes the client do. **Reversibility:** this is a one-way change to the wire format, but no code on either side uses it yet. That makes now the cheapest moment to settle it. **For the server side (Nyssa, #12):** the server is free to keep a pending connection open and send `Approved` on it, or to close it and let the client reconnect. The client will handle both. **Tests:** 12 new unit tests in `shared`. `./scripts/local-gates.sh --rust-only` passes locally. There is no front-end change.
GRI-1854: protocol envelope, registration and media transfer frames
Some checks failed
CI / the pre-push hook (pull_request) Successful in 4s
CI / cargo fmt (pull_request) Successful in 4s
CI / cargo deny (pull_request) Successful in 40s
CI / cargo deny advisories (pull_request) Failing after 41s
CI / repository boundary (pull_request) Successful in 5s
CI / cargo clippy (pull_request) Successful in 9m33s
CI / cargo test (pull_request) Successful in 9m37s
CI / frontend-web (pull_request) Successful in 9m51s
CI / CI (pull_request) Successful in 4s
CI / Notify gate failed (pull_request) Has been skipped
b5484cb073
ServerMessage/ServerControl/ClientMessage tag every frame after the
handshake, so PlaylistPush and MediaManifest can be told apart. Adds the
Registration report, the transfer offer/accept/complete messages, the
12-byte binary chunk header, the device WebSocket path and the heartbeat
interval. protocol.md describes the session in order.
vivy merged commit b22fcf163b into dev 2026-11-09 19:36:12 +00:00
vivy deleted branch feature/GRI-1854-protocol-envelope 2026-11-09 19:36:12 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage!84
No description provided.