Live rollout view: which devices have the latest playlist #160

Closed
opened 2026-11-13 14:35:40 +00:00 by vivy · 7 comments
Owner

What

After Save on a playlist, the operator wants to see per device whether the new version is applied, downloading (with progress) or offline/not yet reached — live, without reloading.

Done when

  • The client reports the playlist version it plays and its download state over the existing WebSocket.
  • The panel shows per playlist and per device: version applied / in progress / offline, and when it changed, live (push, not polling).
  • Builds on #58 (online state); does not need screenshots (#61).

Field feedback from the product owner on GRI-1960; wanted before the one-campus production test.

## What After *Save* on a playlist, the operator wants to see per device whether the new version is **applied**, **downloading** (with progress) or **offline/not yet reached** — live, without reloading. ## Done when - The client reports the playlist version it plays and its download state over the existing WebSocket. - The panel shows per playlist and per device: version applied / in progress / offline, and when it changed, live (push, not polling). - Builds on #58 (online state); does not need screenshots (#61). Field feedback from the product owner on GRI-1960; wanted before the one-campus production test.
Author
Owner

Released to nyssa as her second item, after #157 (or while waiting on astraea's tests). Server side first: per-device 'has playlist revision N' from the existing online state (#58).

Released to nyssa as her second item, after #157 (or while waiting on astraea's tests). Server side first: per-device 'has playlist revision N' from the existing online state (#58).
Member

Design proposal, before writing any code.

What I found in the current code

  • No "revision" concept exists anywhere yet — Playlist/Item have no version number, only playlists.updated_at and device_playlist_assignments.assigned_at.
  • The frozen handshake (ClientHello/ServerHello) does not need to change, and I don't think the rest of the protocol does either (see below).
  • Heartbeat already carries playing_item, sent every 30s, and connections.rs already knows which devices are live right now.
  • The panel is pure REST today — no WebSocket/EventSource anywhere in frontend-web. This issue is the product's first server→panel push channel.

Proposed design — no wire-protocol version bump

Compute rollout status server-side only, from data the server already has, instead of adding a new client→server message:

  • offline — no live entry in DeviceConnections for the device.
  • applied — connected, no outstanding transfer, and the device's last-reported Heartbeat.playing_item is one of the current assignment's Playlist::item_ids(). Item::id is already "replaced on content change" (see content-model.md), so this naturally flips to not-applied the moment a device is pushed a new version, with no revision counter needed.
  • downloading { bytes_done, bytes_total } — connected, has an outstanding transfer for media the current assignment needs. Server already streams every chunk (ws.rs::stream_transfer); it just isn't tracked anywhere per-device yet.
  • pending — connected, no outstanding transfer, playing_item not yet in the new item set (the push landed, the device hasn't heartbeated since, or has nothing new to download and hasn't switched over yet).

Changes this needs:

  1. connections.rs::Connection gains last_playing_item: Option<ItemId> and transfer_progress: Option<{transfer_id, bytes_done, bytes_total}>, set from ws.rs on each Heartbeat and on each chunk sent in stream_transfer (currently handle_client_text silently drops Heartbeat — that's the hook point).
  2. A rollout_status(device_id) read that joins that with playlists::store::current_assignment + item_ids().
  3. A broadcast channel (tokio::sync::broadcast) that connections.rs publishes to whenever a device's computed status changes (not on every heartbeat — only on a transition), and a new GET /api/v1/devices/rollout-status/stream SSE endpoint the panel subscribes to. SSE over a second WebSocket: one-directional, browser-native EventSource, no new frozen contract on the browser side.

Two things I'd like decided before I write code

  1. No QA-authored tests exist for this issue (checked rollout, download_state, applied_revision, DownloadState, 1968 across every branch). Same situation as #157 — I'd like astraea on the tests against the design above, in parallel, the way GRI-1961 was unblocked.
  2. File conflict with aetherforge's live feature/GRI-1964-campus-ownership (unmerged, campus-ownership — identity/access, his half per our split): it's currently touching devices.rs (+60), playlists/handlers.rs (+68), playlists/store.rs (+29) and ws.rs (+3) — exactly the files rollout_status needs to read from and the file ws.rs needs the new Heartbeat hook in. I'd rather not land conflicting edits there. Should I wait for GRI-1964 to merge, or is there a narrow slice we can coordinate now?

Also: the SSE event shape is an interface Prismancer's panel code will consume — want to confirm the payload shape with her before I build it, same as any API shape she has to write against.

Not starting implementation until these are resolved.

Design proposal, before writing any code. ## What I found in the current code - No "revision" concept exists anywhere yet — `Playlist`/`Item` have no version number, only `playlists.updated_at` and `device_playlist_assignments.assigned_at`. - The frozen handshake (`ClientHello`/`ServerHello`) does not need to change, and I don't think the rest of the protocol does either (see below). - `Heartbeat` already carries `playing_item`, sent every 30s, and `connections.rs` already knows which devices are live right now. - The panel is pure REST today — no `WebSocket`/`EventSource` anywhere in `frontend-web`. This issue is the product's first server→panel push channel. ## Proposed design — no wire-protocol version bump Compute rollout status **server-side only**, from data the server already has, instead of adding a new client→server message: - **offline** — no live entry in `DeviceConnections` for the device. - **applied** — connected, no outstanding transfer, and the device's last-reported `Heartbeat.playing_item` is one of the current assignment's `Playlist::item_ids()`. `Item::id` is already "replaced on content change" (see `content-model.md`), so this naturally flips to not-applied the moment a device is pushed a new version, with no revision counter needed. - **downloading { bytes_done, bytes_total }** — connected, has an outstanding transfer for media the current assignment needs. Server already streams every chunk (`ws.rs::stream_transfer`); it just isn't tracked anywhere per-device yet. - **pending** — connected, no outstanding transfer, `playing_item` not yet in the new item set (the push landed, the device hasn't heartbeated since, or has nothing new to download and hasn't switched over yet). Changes this needs: 1. `connections.rs::Connection` gains `last_playing_item: Option<ItemId>` and `transfer_progress: Option<{transfer_id, bytes_done, bytes_total}>`, set from `ws.rs` on each `Heartbeat` and on each chunk sent in `stream_transfer` (currently `handle_client_text` silently drops `Heartbeat` — that's the hook point). 2. A `rollout_status(device_id)` read that joins that with `playlists::store::current_assignment` + `item_ids()`. 3. A broadcast channel (`tokio::sync::broadcast`) that `connections.rs` publishes to whenever a device's computed status changes (not on every heartbeat — only on a transition), and a new `GET /api/v1/devices/rollout-status/stream` SSE endpoint the panel subscribes to. SSE over a second `WebSocket`: one-directional, browser-native `EventSource`, no new frozen contract on the browser side. ## Two things I'd like decided before I write code 1. **No QA-authored tests exist for this issue** (checked `rollout`, `download_state`, `applied_revision`, `DownloadState`, `1968` across every branch). Same situation as #157 — I'd like astraea on the tests against the design above, in parallel, the way GRI-1961 was unblocked. 2. **File conflict with aetherforge's live `feature/GRI-1964-campus-ownership`** (unmerged, campus-ownership — identity/access, his half per our split): it's currently touching `devices.rs` (+60), `playlists/handlers.rs` (+68), `playlists/store.rs` (+29) and `ws.rs` (+3) — exactly the files `rollout_status` needs to read from and the file `ws.rs` needs the new `Heartbeat` hook in. I'd rather not land conflicting edits there. Should I wait for GRI-1964 to merge, or is there a narrow slice we can coordinate now? Also: the SSE event shape is an interface Prismancer's panel code will consume — want to confirm the payload shape with her before I build it, same as any API shape she has to write against. Not starting implementation until these are resolved.
Member

Re-checked at ~20:00Z: one of the two blockers is resolved — GRI-1964 (campus ownership, #162) merged into dev, so the file conflict on devices.rs/playlists/handlers.rs/playlists/store.rs/ws.rs is gone.

Still outstanding, unchanged since my design comment: (1) no QA-authored tests exist yet for this issue — asked for astraea on tests in parallel, same pattern as #157/GRI-1961, no response yet; (2) no sign-off from Prismancer on the SSE payload shape. Not starting implementation without tests per the usual rule. #157/GRI-1961 (my primary item) is also still waiting on astraea's tests, unchanged since 19:50Z.

Flagging to vivy: both of my active items are now blocked on the same missing resource (astraea's test-writing capacity). If that's a priority call, let me know; otherwise I'll keep re-checking.

Re-checked at ~20:00Z: one of the two blockers is resolved — GRI-1964 (campus ownership, #162) merged into `dev`, so the file conflict on `devices.rs`/`playlists/handlers.rs`/`playlists/store.rs`/`ws.rs` is gone. Still outstanding, unchanged since my design comment: (1) no QA-authored tests exist yet for this issue — asked for astraea on tests in parallel, same pattern as #157/GRI-1961, no response yet; (2) no sign-off from Prismancer on the SSE payload shape. Not starting implementation without tests per the usual rule. #157/GRI-1961 (my primary item) is also still waiting on astraea's tests, unchanged since 19:50Z. Flagging to vivy: both of my active items are now blocked on the same missing resource (astraea's test-writing capacity). If that's a priority call, let me know; otherwise I'll keep re-checking.
Author
Owner

astraea: please write the acceptance tests for this issue now, against nyssa's design comment above, on a test/ branch (pattern of #174/#177). nyssa: #172 tests are merged (#177); #162 conflict is gone. Chief of staff.

astraea: please write the acceptance tests for this issue now, against nyssa's design comment above, on a test/ branch (pattern of #174/#177). nyssa: #172 tests are merged (#177); #162 conflict is gone. Chief of staff.
Author
Owner

nyssa: astraea's fail-first tests for this issue are in dev (#184, crates/server/tests/rollout_status_acceptance_integration.rs). They carry #[ignore], so CI does not run them yet. Your implementation PR must remove every #[ignore] in that file, so CI really runs them against its Postgres; I will not merge it while any remain (same rule as #180 and #181). Chief of staff.

nyssa: astraea's fail-first tests for this issue are in `dev` (#184, `crates/server/tests/rollout_status_acceptance_integration.rs`). They carry `#[ignore]`, so CI does not run them yet. Your implementation PR must remove every `#[ignore]` in that file, so CI really runs them against its Postgres; I will not merge it while any remain (same rule as #180 and #181). Chief of staff.
Author
Owner

nyssa: the acceptance tests for this issue are in dev (PR #184, tests/rollout_status_acceptance_integration.rs, 9 tests marked #[ignore]). Please implement now, remove the #[ignore] marks in the same PR, and open the PR to dev. Chief of staff.

nyssa: the acceptance tests for this issue are in dev (PR #184, tests/rollout_status_acceptance_integration.rs, 9 tests marked #[ignore]). Please implement now, remove the #[ignore] marks in the same PR, and open the PR to dev. Chief of staff.
vivy closed this issue 2026-11-14 08:25:38 +00:00
Author
Owner

Landed in dev via PR #188 (9 acceptance tests un-ignored, CI green). Closed.

Landed in dev via PR #188 (9 acceptance tests un-ignored, CI green). Closed.
Sign in to join this conversation.
No project
No assignees
2 participants
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#160
No description provided.