GRI-1854: client sync over wss — enrolment, playlist, media cache, reconnect #86

Merged
vivy merged 3 commits from feature/GRI-1854-client-sync into dev 2026-11-09 20:39:36 +00:00
Member

Signage #20 (GRI-1854): the client syncs over wss://. It covers enrolment, the playlist, the media download into a hash-keyed cache, and reconnecting with backoff.

Stacked on #84 (the protocol envelope). This branch contains #84's commit, so merge #84 first and this diff shrinks to the client alone.

Done-when for #20, as a test. crates/client/tests/sync_survives_restart.rs runs a fake server over a real WebSocket on loopback. The server enrols the client and sends playlist v1 plus one file in two chunks. Then it drops both the connection and the listener. A second server on the same port checks that the client comes back with its permanent device_id and token, sends playlist v2, and checks the cached file is accepted at its end offset, so nothing is downloaded again. A second test covers a pending device: it sends Registration and reconnects with its temporary id.

Modules (all in crates/client)

Module What it does Failure behaviour
state.rs state.json: identity, temporary id, pinned key, last playlist, last manifest. Write to a temp file, fsync, rename A corrupt file is an error and is left alone. Starting empty would enrol the display again as a new device
cache.rs <sha256> holds verified files, <sha256>.part holds downloads in progress (its length is the resume offset), plus a sweep down to the manifest A name that is not a 64-hex sha256 never becomes a path (no ../). A hash mismatch deletes the partial, so nothing unverified ever gets the final name
session.rs The protocol for one connection, with no network: hello outcome, enrolment, manifest, playlist, offer/accept/chunk/complete An out-of-order chunk or an unknown transfer id is dropped and the partial kept. A chunk past the offered length ends the transfer and deletes the partial. The sweep runs only once a playlist arrives, so the files on screen stay until they are replaced
sync.rs The wss loop: connect (15 s timeout), hello (15 s), heartbeat and ping every 30 s, closed as dead after 75 s of silence. Backoff runs 1 s → 5 min with full jitter. Rejected or UpdateRequired waits the cap Bad frames are logged and ignored. A state or cache I/O error closes and reconnects. Playback reads a watch channel that is filled from disk before the first connect, so it never waits on the network
config.rs Server from GRIMOIRIX_SIGNAGE_SERVER, else server = "https://…" in /etc/grimoirix-signage/client.toml, turned into wss://host/ws/device. Data dir from GRIMOIRIX_SIGNAGE_DATA_DIR, else XDG, else ~/.local/share Errors name the setting to fix
main.rs The headless client: runs the sync and prints each playlist —

Dependencies: tokio (current-thread), tokio-tungstenite 0.28 using rustls with the native trust store (so a campus CA goes in the system store), ring as the only crypto provider, and no OpenSSL. cargo deny passes.

Decisions

  • state.json plus file names as the cache index, instead of the SQLite the plan named. rusqlite is banned in deny.toml, and the directory is the index. Two-way: easy to change later. offline-first.md is updated.
  • Chunks are written with blocking file I/O on the sync task. That is fine for one display process. If a 500 MB video ever stalls heartbeats, move it to spawn_blocking.

Security surface, for the security checker:

  • Server-supplied hashes become file names, and are validated (tested).
  • The token is stored in plaintext in state.json, mode 0600 (tested), under the user's data dir.
  • TLS uses the system roots, with no pinning.

Not in this PR: playback from the cache in the renderer is #21, next.

Tests: 72 unit tests and 2 integration tests in client. ./scripts/local-gates.sh --rust-only passes locally.

Signage #20 (GRI-1854): the client syncs over `wss://`. It covers enrolment, the playlist, the media download into a hash-keyed cache, and reconnecting with backoff. **Stacked on #84** (the protocol envelope). This branch contains #84's commit, so merge #84 first and this diff shrinks to the client alone. **Done-when for #20, as a test.** `crates/client/tests/sync_survives_restart.rs` runs a fake server over a real WebSocket on loopback. The server enrols the client and sends playlist v1 plus one file in two chunks. Then it drops both the connection and the listener. A second server on the same port checks that the client comes back with its permanent `device_id` and token, sends playlist v2, and checks the cached file is accepted at its end offset, so nothing is downloaded again. A second test covers a pending device: it sends `Registration` and reconnects with its temporary id. **Modules** (all in `crates/client`) | Module | What it does | Failure behaviour | | --- | --- | --- | | `state.rs` | `state.json`: identity, temporary id, pinned key, last playlist, last manifest. Write to a temp file, fsync, rename | A corrupt file is an **error and is left alone**. Starting empty would enrol the display again as a new device | | `cache.rs` | `<sha256>` holds verified files, `<sha256>.part` holds downloads in progress (its length is the resume offset), plus a sweep down to the manifest | **A name that is not a 64-hex sha256 never becomes a path** (no `../`). A hash mismatch deletes the partial, so nothing unverified ever gets the final name | | `session.rs` | The protocol for one connection, with no network: hello outcome, enrolment, manifest, playlist, offer/accept/chunk/complete | An out-of-order chunk or an unknown transfer id is dropped and the partial kept. A chunk past the offered length ends the transfer and deletes the partial. The sweep runs only once a playlist arrives, so the files on screen stay until they are replaced | | `sync.rs` | The `wss` loop: connect (15 s timeout), hello (15 s), heartbeat and ping every 30 s, closed as dead after 75 s of silence. Backoff runs 1 s → 5 min with full jitter. `Rejected` or `UpdateRequired` waits the cap | Bad frames are logged and ignored. A state or cache I/O error closes and reconnects. Playback reads a `watch` channel that is filled from disk **before** the first connect, so it never waits on the network | | `config.rs` | Server from `GRIMOIRIX_SIGNAGE_SERVER`, else `server = "https://…"` in `/etc/grimoirix-signage/client.toml`, turned into `wss://host/ws/device`. Data dir from `GRIMOIRIX_SIGNAGE_DATA_DIR`, else XDG, else `~/.local/share` | Errors name the setting to fix | | `main.rs` | The headless client: runs the sync and prints each playlist | — | **Dependencies:** `tokio` (current-thread), `tokio-tungstenite` 0.28 using rustls with the **native** trust store (so a campus CA goes in the system store), `ring` as the only crypto provider, and no OpenSSL. `cargo deny` passes. **Decisions** - `state.json` plus file names as the cache index, instead of the SQLite the plan named. `rusqlite` is banned in `deny.toml`, and the directory is the index. Two-way: easy to change later. `offline-first.md` is updated. - Chunks are written with blocking file I/O on the sync task. That is fine for one display process. If a 500 MB video ever stalls heartbeats, move it to `spawn_blocking`. **Security surface**, for the security checker: - Server-supplied hashes become file names, and are validated (tested). - The token is stored in plaintext in `state.json`, **mode 0600** (tested), under the user's data dir. - TLS uses the system roots, with no pinning. **Not in this PR:** playback from the cache in the renderer is #21, next. **Tests:** 72 unit tests and 2 integration tests in `client`. `./scripts/local-gates.sh --rust-only` passes locally.
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.
GRI-1854: client sync over wss — enrolment, playlist, media cache, reconnect
Some checks failed
CI / the pre-push hook (pull_request) Has been cancelled
CI / cargo fmt (pull_request) Has been cancelled
CI / cargo clippy (pull_request) Has been cancelled
CI / cargo test (pull_request) Has been cancelled
CI / cargo deny (pull_request) Has been cancelled
CI / cargo deny advisories (pull_request) Has been cancelled
CI / frontend-web (pull_request) Has been cancelled
CI / repository boundary (pull_request) Has been cancelled
CI / CI (pull_request) Has been cancelled
CI / Notify gate failed (pull_request) Has been cancelled
a6bb13bf04
state.rs keeps the identity and the last playlist in state.json, written
by rename. cache.rs stores media by sha256, resumes from <sha>.part and
only renames a file into place once its hash is checked; a name that is
not a sha256 never becomes a path. session.rs is the protocol for one
connection with no network in it. sync.rs is the wss loop: hello
timeout, heartbeat and ping, dead-connection detection, backoff with
jitter, and a watch channel that playback reads, filled from disk before
the first connect. config.rs reads the server from the environment or
/etc/grimoirix-signage/client.toml. The integration test runs a fake
server, restarts it on the same port, and checks the client comes back
with its identity and picks up the changed playlist.
GRI-1854: state.json is readable by its owner only (it holds the token)
Some checks failed
CI / the pre-push hook (pull_request) Successful in 10s
CI / cargo fmt (pull_request) Successful in 7s
CI / cargo clippy (pull_request) Successful in 9m40s
CI / cargo deny (pull_request) Successful in 44s
CI / cargo deny advisories (pull_request) Failing after 38s
CI / cargo test (pull_request) Successful in 9m41s
CI / repository boundary (pull_request) Successful in 4s
CI / frontend-web (pull_request) Successful in 9m37s
CI / CI (pull_request) Has been cancelled
CI / Notify gate failed (pull_request) Has been cancelled
52110c7f35
Merge remote-tracking branch 'origin/dev' into feature/GRI-1854-client-sync
Some checks failed
CI / the pre-push hook (pull_request) Successful in 6s
CI / cargo fmt (pull_request) Successful in 5s
CI / cargo deny (pull_request) Successful in 42s
CI / cargo deny advisories (pull_request) Failing after 44s
CI / repository boundary (pull_request) Successful in 5s
CI / cargo clippy (pull_request) Successful in 9m39s
CI / cargo test (pull_request) Successful in 9m49s
CI / frontend-web (pull_request) Successful in 9m37s
CI / CI (pull_request) Successful in 4s
CI / Notify gate failed (pull_request) Has been skipped
3cc319998f
# Conflicts:
#	Cargo.lock
vivy merged commit 4fcfc0a76c into dev 2026-11-09 20:39:36 +00:00
vivy deleted branch feature/GRI-1854-client-sync 2026-11-09 20:39:36 +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!86
No description provided.