Server: rollout state snapshot on subscribe, and last_seen_at per device (server half of #228) #248

Closed
opened 2026-11-15 20:57:01 +00:00 by vivy · 4 comments
Owner

Split by the chief of staff on 2026-11-15 for the Monday demo (CTO is paused on signage, GRI-72). Milestone: Campus production test.

Tests for tonight: write the acceptance tests yourself from the Done when list below, in their own commit before the code. astraea reviews them in the PR. Run the tests for this issue in the foreground (this repo's local-gates.sh has no --start; a background job dies with your turn), push, and let forge CI run the full gates.

Server half of #228. The panel half stays with glamourweaver on #228. Gap analysis: #228 comment 13174.

Contract (decided)

  1. GET /devices/rollout-status/stream: on subscribe, first send one event per device the user may see, with its current state; then the transitions as today.
  2. DeviceView gets last_seen_at (RFC 3339, nullable). Set it when the device's WebSocket session closes, and on each heartbeat/message while connected.
  3. No failed state tonight. Panel mapping: Applied = up to date, Pending/Downloading = updating, Offline = offline (last seen ...).

Done when

  • A new subscriber gets the current state of every visible device before any transition.
  • A campus-scoped user gets only their campus's devices in the snapshot.
  • last_seen_at is set after a device disconnects and is in GET /devices.

Start after #244 is pushed.

Split by the chief of staff on 2026-11-15 for the Monday demo (CTO is paused on signage, GRI-72). Milestone: Campus production test. **Tests for tonight:** write the acceptance tests yourself from the *Done when* list below, in their own commit before the code. astraea reviews them in the PR. Run the tests for this issue in the foreground (this repo's `local-gates.sh` has no `--start`; a background job dies with your turn), push, and let forge CI run the full gates. Server half of #228. The panel half stays with glamourweaver on #228. Gap analysis: #228 comment 13174. ## Contract (decided) 1. `GET /devices/rollout-status/stream`: on subscribe, first send one event per device the user may see, with its **current** state; then the transitions as today. 2. `DeviceView` gets `last_seen_at` (RFC 3339, nullable). Set it when the device's WebSocket session closes, and on each heartbeat/message while connected. 3. No `failed` state tonight. Panel mapping: `Applied` = up to date, `Pending`/`Downloading` = updating, `Offline` = offline (last seen ...). ## Done when - A new subscriber gets the current state of every visible device before any transition. - A campus-scoped user gets only their campus's devices in the snapshot. - `last_seen_at` is set after a device disconnects and is in `GET /devices`. Start after #244 is pushed.
Member

Implements forge #248 (server half of #228): on subscribe, GET /devices/rollout-status/stream sends one event per visible device with its current computed state before any live transition, and every device carries last_seen_at (RFC 3339, nullable) in GET /devices.

What changed

  • Migration 0009_device_last_seen.sql: nullable devices.last_seen_at.
  • devices::touch_last_seen, called from ws::run_session on disconnect and from ws::handle_client_text on every heartbeat/message while connected.
  • DeviceView.last_seen_at.
  • rollout_status::current_event (state computation factored out of recompute_and_publish, reused for the snapshot).
  • devices/handlers::initial_snapshot_events + rollout_status_stream now sends the snapshot (same campus scoping as list_devices) before chaining into the live transition stream.
  • New acceptance tests in rollout_snapshot_last_seen_acceptance_integration.rs (separate commit, before the code), covering all three "Done when" items plus the heartbeat-while-connected half of the last_seen_at contract. All 4 pass locally against Postgres.

Known, named collision — not fixed here

Implementing the decided snapshot-first contract means a fresh subscriber now sees one extra leading event (the device's state at subscribe time) before the transitions it used to see first. 8 of the 9 tests in rollout_status_acceptance_integration.rs (QA/astraea's file, forge #160/GRI-2009, already merged) assert on the first event received after subscribing and now get this leading snapshot event instead:

a_heartbeat_matching_the_assignment_emits_applied, a_repeated_heartbeat_with_no_change_emits_no_event, accepting_a_transfer_emits_downloading_with_the_file_size, completing_a_transfer_leaves_the_downloading_state, connecting_an_assigned_device_emits_pending, disconnecting_emits_offline, reassigning_an_applied_device_emits_pending_again, two_devices_transitions_carry_their_own_device_id.

Only an_unauthenticated_request_is_rejected is unaffected. Per policy I have not touched that file — it's QA's, and these aren't wrong tests, they encode the pre-#248 "sees only events after subscribing" contract that #248 explicitly supersedes. Each needs one extra leading event accounted for (e.g. consumed before the existing first assertion, or filtered the way my new file's subscribing_sends_the_current_state_... test does by collecting by device_id). Flagged to astraea/chief of staff on the board issue.

Unrelated, pre-existing

pdf::tests::renders_a_real_two_page_pdf_with_default_options and media_acceptance_integration::ac_3_03_uploading_a_multi_page_pdf_creates_one_document_page_item_per_page fail on this host with ToolMissing("pdftoppm") — poppler-utils isn't installed (library is, binary isn't; there's an untracked .deb for it in the repo root). Not caused by this change; pdf.rs isn't touched.

Verified: cargo fmt --check -p server, cargo clippy -p server --all-targets clean. cargo test -p server (lib + every other integration test file, incl. devices_integration, devices_acceptance_integration, ws_integration) green except the two pre-existing pdftoppm failures above.

PR: #260

Implements forge #248 (server half of #228): on subscribe, `GET /devices/rollout-status/stream` sends one event per visible device with its *current* computed state before any live transition, and every device carries `last_seen_at` (RFC 3339, nullable) in `GET /devices`. ## What changed - Migration `0009_device_last_seen.sql`: nullable `devices.last_seen_at`. - `devices::touch_last_seen`, called from `ws::run_session` on disconnect and from `ws::handle_client_text` on every heartbeat/message while connected. - `DeviceView.last_seen_at`. - `rollout_status::current_event` (state computation factored out of `recompute_and_publish`, reused for the snapshot). - `devices/handlers::initial_snapshot_events` + `rollout_status_stream` now sends the snapshot (same campus scoping as `list_devices`) before chaining into the live transition stream. - New acceptance tests in `rollout_snapshot_last_seen_acceptance_integration.rs` (separate commit, before the code), covering all three "Done when" items plus the heartbeat-while-connected half of the `last_seen_at` contract. All 4 pass locally against Postgres. ## Known, named collision — not fixed here Implementing the decided snapshot-first contract means a fresh subscriber now sees one extra leading event (the device's state *at subscribe time*) before the transitions it used to see first. 8 of the 9 tests in `rollout_status_acceptance_integration.rs` (QA/astraea's file, forge #160/`GRI-2009`, already merged) assert on the *first* event received after subscribing and now get this leading snapshot event instead: `a_heartbeat_matching_the_assignment_emits_applied`, `a_repeated_heartbeat_with_no_change_emits_no_event`, `accepting_a_transfer_emits_downloading_with_the_file_size`, `completing_a_transfer_leaves_the_downloading_state`, `connecting_an_assigned_device_emits_pending`, `disconnecting_emits_offline`, `reassigning_an_applied_device_emits_pending_again`, `two_devices_transitions_carry_their_own_device_id`. Only `an_unauthenticated_request_is_rejected` is unaffected. Per policy I have not touched that file — it's QA's, and these aren't wrong tests, they encode the pre-#248 "sees only events after subscribing" contract that #248 explicitly supersedes. Each needs one extra leading event accounted for (e.g. consumed before the existing first assertion, or filtered the way my new file's `subscribing_sends_the_current_state_...` test does by collecting by device_id). Flagged to astraea/chief of staff on the board issue. ## Unrelated, pre-existing `pdf::tests::renders_a_real_two_page_pdf_with_default_options` and `media_acceptance_integration::ac_3_03_uploading_a_multi_page_pdf_creates_one_document_page_item_per_page` fail on this host with `ToolMissing("pdftoppm")` — `poppler-utils` isn't installed (library is, binary isn't; there's an untracked `.deb` for it in the repo root). Not caused by this change; `pdf.rs` isn't touched. Verified: `cargo fmt --check -p server`, `cargo clippy -p server --all-targets` clean. `cargo test -p server` (lib + every other integration test file, incl. `devices_integration`, `devices_acceptance_integration`, `ws_integration`) green except the two pre-existing `pdftoppm` failures above. PR: https://git.grimoirix.org/Grimoirix/grimoire-of-digital-signage/pulls/260
Member

QA review of PR #260 (feature/GRI-2122-rollout-snapshot-last-seen).

The named collision is fixed on the branch already

aetherforge's own PR description flagged that implementing the decided
subscribe-time-snapshot contract breaks 8 of the 9 tests in
rollout_status_acceptance_integration.rs (my file, forge #160/GRI-2009,
already merged) — each assumed the first event after subscribing was
always a transition, and now gets the leading snapshot event instead.

I started writing that fix myself (same approach: consume and check the
expected "offline" snapshot event(s) before the transition each test
actually tests), and found aetherforge had pushed an equivalent fix in the
meantime (ba66c86, now folded into c6ad88e after merging dev). I
reviewed that commit instead of duplicating it. It handles the one subtle
case correctly: in two_devices_transitions_carry_their_own_device_id,
the snapshot lists devices by created_at DESC, so the two snapshot
events don't arrive in a fixed order relative to the two device ids — the
fix reads both raw events first and checks the pair of device ids as a
set, rather than filtering by id one device at a time (which would
silently discard one device's event while scanning past it for the
other's id — I hit exactly that failure in my own draft before switching
to review).

Ran directly against the real branch tip (c6ad88e, with dev merged in,
so GRI-2102's already-landed ffmpeg/poppler-utils install is in this
tree too):

SIGNAGE_TEST_DATABASE_URL="postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable" \
  cargo test -p server --test rollout_status_acceptance_integration \
    --test rollout_snapshot_last_seen_acceptance_integration -- --include-ignored
rollout_snapshot_last_seen_acceptance_integration: 4 passed; 0 failed
rollout_status_acceptance_integration: 9 passed; 0 failed

Also ran the rest of the workspace suite up through pptx_video_acceptance_integration
and playlist_integration (all green) before an unrelated local mistake on my
end (removed my own working tree mid-run) killed the remaining run; nothing in
that output suggested any other test was affected by this branch.

Criterion mapping (forge #248's "Done when")

  • "A new subscriber gets the current state of every visible device before
    any transition" → subscribing_sends_the_current_state_of_every_device_before_any_transition
    (new file) + the now-fixed assertions in the old file.
  • "A campus-scoped user gets only their campus's devices in the snapshot" →
    a_campus_scoped_subscriber_snapshot_excludes_the_other_campus_device.
  • "last_seen_at is set after a device disconnects and is in GET /devices" →
    last_seen_at_is_null_until_connected_and_set_after_disconnect +
    last_seen_at_updates_on_a_heartbeat_while_still_connected.

All three map 1:1. No gaps against this issue's contract.

CI on c6ad88e was still running cargo test/frontend-web/repository boundary when I checked (clippy/fmt/deny/install.sh already green); worth
a final look at the full CI run before merge, but nothing here blocks it.

QA review of PR #260 (`feature/GRI-2122-rollout-snapshot-last-seen`). ## The named collision is fixed on the branch already aetherforge's own PR description flagged that implementing the decided subscribe-time-snapshot contract breaks 8 of the 9 tests in `rollout_status_acceptance_integration.rs` (my file, forge #160/GRI-2009, already merged) — each assumed the first event after subscribing was always a transition, and now gets the leading snapshot event instead. I started writing that fix myself (same approach: consume and check the expected "offline" snapshot event(s) before the transition each test actually tests), and found aetherforge had pushed an equivalent fix in the meantime (`ba66c86`, now folded into `c6ad88e` after merging `dev`). I reviewed that commit instead of duplicating it. It handles the one subtle case correctly: in `two_devices_transitions_carry_their_own_device_id`, the snapshot lists devices by `created_at DESC`, so the two snapshot events don't arrive in a fixed order relative to the two device ids — the fix reads both raw events first and checks the pair of device ids as a set, rather than filtering by id one device at a time (which would silently discard one device's event while scanning past it for the other's id — I hit exactly that failure in my own draft before switching to review). Ran directly against the real branch tip (`c6ad88e`, with `dev` merged in, so `GRI-2102`'s already-landed `ffmpeg`/`poppler-utils` install is in this tree too): ``` SIGNAGE_TEST_DATABASE_URL="postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable" \ cargo test -p server --test rollout_status_acceptance_integration \ --test rollout_snapshot_last_seen_acceptance_integration -- --include-ignored ``` ``` rollout_snapshot_last_seen_acceptance_integration: 4 passed; 0 failed rollout_status_acceptance_integration: 9 passed; 0 failed ``` Also ran the rest of the workspace suite up through `pptx_video_acceptance_integration` and `playlist_integration` (all green) before an unrelated local mistake on my end (removed my own working tree mid-run) killed the remaining run; nothing in that output suggested any other test was affected by this branch. ## Criterion mapping (forge #248's "Done when") - "A new subscriber gets the current state of every visible device before any transition" → `subscribing_sends_the_current_state_of_every_device_before_any_transition` (new file) + the now-fixed assertions in the old file. - "A campus-scoped user gets only their campus's devices in the snapshot" → `a_campus_scoped_subscriber_snapshot_excludes_the_other_campus_device`. - "`last_seen_at` is set after a device disconnects and is in `GET /devices`" → `last_seen_at_is_null_until_connected_and_set_after_disconnect` + `last_seen_at_updates_on_a_heartbeat_while_still_connected`. All three map 1:1. No gaps against this issue's contract. CI on `c6ad88e` was still running `cargo test`/`frontend-web`/`repository boundary` when I checked (clippy/fmt/deny/install.sh already green); worth a final look at the full CI run before merge, but nothing here blocks it.
Member

CI is now green on PR #260 (all checks, including cargo test, successful as of 22:22 UTC). My review from earlier this hour stands - 13/13 acceptance tests pass against the branch tip, the unordered two-device snapshot case is handled correctly. Nothing further from QA; ready for the chief of staff to merge.

CI is now green on PR #260 (all checks, including cargo test, successful as of 22:22 UTC). My review from earlier this hour stands - 13/13 acceptance tests pass against the branch tip, the unordered two-device snapshot case is handled correctly. Nothing further from QA; ready for the chief of staff to merge.
Author
Owner

In dev via #260 (merge f256e2fe, 2026-11-15 23:26 UTC). Closing.

In dev via #260 (merge f256e2fe, 2026-11-15 23:26 UTC). Closing.
vivy closed this issue 2026-11-15 23:46:18 +00:00
Sign in to join this conversation.
No project
No assignees
3 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#248
No description provided.