Shell 31: statusapi-default-avatars (#823) #891

Closed
charles wants to merge 0 commits from shell-31-statusapi-default-avatars into shell
Owner

What

fluxer-status-api (Desktop shell spec §11, #734):

  • GET /avatars/default/<index>.png?token=…: the caller's bundled default avatars (StatusApiConfig::default_avatars: Arc<[Bytes]>, the crate reads no files). Same loopback, origin and token rules as /status; image/png, Cache-Control: max-age=86400; 404 for an unknown or non-canonical index (only after the token check, so nothing is revealed without it); 405 for other methods; a WebSocket upgrade there gets 404.
  • hello (and the one-shot GET /status) carry "capabilities":["control"] while StatusApiConfig::control / StatusApi::set_control(bool) is on; the key is absent otherwise, so the existing read-only hello is byte-for-byte unchanged. Version stays 1.
  • WebSocket ops set_mute / set_deaf ("value": bool, required), toggle_mute, toggle_deaf, disconnect are forwarded as fluxer_core::shell::companion::CompanionOp (re-exported) through StatusApi::take_ops() -> Option<mpsc::Receiver<CompanionOp>> (handed out once, queue of 64, a full queue drops). At most 10 per rolling second per client (MAX_OPS_PER_SECOND), more are dropped; ops while control is off, malformed and unknown ops are ignored and do not use up the allowance.
  • StatusApi::bind_error() -> Option<io::ErrorKind>: the bind failure while enabled and retrying (the port warning), None while listening, disabled or stopped.
  • The stale "Foundation always publishes None" comment (#734 item 4) is gone. README updated.

Deviations / decisions

  • fluxer-status-api now depends on fluxer-core (path dependency, for CompanionOp as the Interfaces block names it) and bytes (workspace dependency, for Arc<[Bytes]>). No new external crate.
  • set_control disconnects every client when the value changes, so each reconnects and reads the new capabilities (as set_token does). The spec does not say; this keeps a client's capabilities honest.
  • apps/fluxer/src/runtime.rs: only the two new config fields (control: false, no images) so it compiles. Wiring the images, voice_status_with, set_control, take_ops + companion_action and bind_error into the runtime is not owned by any plan task; opened #889 (follow-up). Until then the server side of #734 is done but the app does not use it yet.

Strings

None new in this crate (the switch label and port warning live in fluxer-core, Task 15).

Tests

  • New: tests/avatars.rs (default_avatar_served_with_token_only, web_origin_refused_for_avatars, avatars_follow_the_enabled_switch, no_images_means_every_index_is_unknown), tests/control.rs (hello_capabilities, ops_forwarded_when_enabled, ops_ignored_when_disabled, op_rate_limited, unknown_op_ignored, bind_error_reported); unit tests for the path parser, request parser and the rolling-window limiter. All on loopback with port 0; no test binds 21863.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally. No desktop-only tests apply (none were run).
  • Nothing Windows-specific.

Stacked on: origin/shell-15-core-status-payload-gaps (already contained in origin/shell when this branch was cut)

Closes #823
Closes #734

🤖 Generated with Claude Code

https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K

## What `fluxer-status-api` (Desktop shell spec §11, #734): - `GET /avatars/default/<index>.png?token=…`: the caller's bundled default avatars (`StatusApiConfig::default_avatars: Arc<[Bytes]>`, the crate reads no files). Same loopback, origin and token rules as `/status`; `image/png`, `Cache-Control: max-age=86400`; `404` for an unknown or non-canonical index (only after the token check, so nothing is revealed without it); `405` for other methods; a WebSocket upgrade there gets `404`. - `hello` (and the one-shot `GET /status`) carry `"capabilities":["control"]` while `StatusApiConfig::control` / `StatusApi::set_control(bool)` is on; the key is absent otherwise, so the existing read-only hello is byte-for-byte unchanged. Version stays 1. - WebSocket ops `set_mute` / `set_deaf` (`"value": bool`, required), `toggle_mute`, `toggle_deaf`, `disconnect` are forwarded as `fluxer_core::shell::companion::CompanionOp` (re-exported) through `StatusApi::take_ops() -> Option<mpsc::Receiver<CompanionOp>>` (handed out once, queue of 64, a full queue drops). At most 10 per rolling second per client (`MAX_OPS_PER_SECOND`), more are dropped; ops while control is off, malformed and unknown ops are ignored and do not use up the allowance. - `StatusApi::bind_error() -> Option<io::ErrorKind>`: the bind failure while enabled and retrying (the port warning), `None` while listening, disabled or stopped. - The stale "Foundation always publishes `None`" comment (#734 item 4) is gone. README updated. ## Deviations / decisions - `fluxer-status-api` now depends on `fluxer-core` (path dependency, for `CompanionOp` as the Interfaces block names it) and `bytes` (workspace dependency, for `Arc<[Bytes]>`). No new external crate. - `set_control` disconnects every client when the value changes, so each reconnects and reads the new `capabilities` (as `set_token` does). The spec does not say; this keeps a client's capabilities honest. - `apps/fluxer/src/runtime.rs`: only the two new config fields (`control: false`, no images) so it compiles. Wiring the images, `voice_status_with`, `set_control`, `take_ops` + `companion_action` and `bind_error` into the runtime is not owned by any plan task; opened #889 (follow-up). Until then the server side of #734 is done but the app does not use it yet. ## Strings None new in this crate (the switch label and port warning live in `fluxer-core`, Task 15). ## Tests - New: `tests/avatars.rs` (`default_avatar_served_with_token_only`, `web_origin_refused_for_avatars`, `avatars_follow_the_enabled_switch`, `no_images_means_every_index_is_unknown`), `tests/control.rs` (`hello_capabilities`, `ops_forwarded_when_enabled`, `ops_ignored_when_disabled`, `op_rate_limited`, `unknown_op_ignored`, `bind_error_reported`); unit tests for the path parser, request parser and the rolling-window limiter. All on loopback with port 0; no test binds 21863. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally. No desktop-only tests apply (none were run). - Nothing Windows-specific. Stacked on: origin/shell-15-core-status-payload-gaps (already contained in origin/shell when this branch was cut) Closes #823 Closes #734 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
GET /avatars/default/<index>.png?token=... serves the caller's bundled
default avatars (image/png, Cache-Control: max-age=86400, same peer,
origin and token rules as /status, 404 for an unknown index). hello
carries "capabilities":["control"] while control is on (set_control);
the WebSocket ops set_mute, set_deaf, toggle_mute, toggle_deaf and
disconnect are forwarded as fluxer-core's CompanionOp through take_ops,
at most 10 per second per client, ignored while control is off.
StatusApi::bind_error reports the bind failure behind the port warning.
The stale payload.rs comment of #734 item 4 is gone.

apps/fluxer: only the two new StatusApiConfig fields (off, no images).

Refs #823

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0161qMQMsCyJhjYw4gqa6e4K
Author
Owner

Independent review: Shell 31 (statusapi-default-avatars), e63e7831

Reviewed git diff 2412c1d0..origin/shell-31-statusapi-default-avatars cold.

(1) Plan tests: all eight named tests exist and assert what the plan says: default_avatar_served_with_token_only (200, image/png, max-age=86400, exact bytes incl. non-UTF-8; 403 without/with wrong token; 404 for unknown index only with the token, 403 without), web_origin_refused_for_avatars, hello_capabilities (exact hello JSON, ["control"] only when on, version 1), ops_forwarded_when_enabled (all five ops), ops_ignored_when_disabled, op_rate_limited (10 of 15 pass, per client, window rolls), unknown_op_ignored, bind_error_reported (AddrInUse; None while off and while listening).

(2) Interfaces: GET /avatars/default/<index>.png?token=…, StatusApiConfig::{control, default_avatars: Arc<[Bytes]>}, set_control(bool), CompanionOp (Task 15's type, re-exported), ops channel via take_ops(), bind_error() -> Option<io::ErrorKind>, stale payload.rs comment removed. All present. Branch merges cleanly into current origin/shell (99bde430); the only other StatusApiConfig literal (runtime.rs) is updated.

(3) Invariants: fluxer-core untouched; the new status-api -> fluxer-core edge is acyclic and adds no external crate (bytes is a workspace dep). No token in logs (Debug still redacts; images shown as a count). Server/client input cannot panic: index parse is canonical-decimal with overflow → 404; malformed JSON/ops ignored; binary frames ignored. No cfg(windows) code.

(4) Parity (vs fluxer_desktop/src/main/StatusApi.ts): order loopback-403 → path-404 → disabled-404 / origin-403 / token-403 (lines 80-85, 325-345) kept for the new route; origin rule (no header, null, non-http(s), loopback hosts) unchanged and reused; unknown ops ignored as handleClientMessage (183-186); 405 with Allow: GET as line 301.

(5) Review Focus 9: control off by default (new and runtime pass false), requires the token (same authorize path as the upgrade), and ops only become CompanionOp, which Task 15's companion_action maps to tray actions (ToggleSelfMute/ToggleSelfDeaf/LeaveVoice). OK.

(6) Gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in the review worktree: all steps passed.

Findings

  • minor: Closes #734 while nothing in the app uses the new route or ops until follow-up #889 lands. Matches the plan's "Closes #734" for Task 31 and #889 is open with follow-up, so not blocking; worth keeping #889 visible.
  • minor (decision check): set_control dropping all clients on a change is consistent with set_token and keeps the advertised capabilities honest; accepted.

Verdict: APPROVED (0 blocking findings, gate green).

## Independent review: Shell 31 (statusapi-default-avatars), e63e7831 Reviewed `git diff 2412c1d0..origin/shell-31-statusapi-default-avatars` cold. **(1) Plan tests:** all eight named tests exist and assert what the plan says: `default_avatar_served_with_token_only` (200, `image/png`, `max-age=86400`, exact bytes incl. non-UTF-8; 403 without/with wrong token; 404 for unknown index only with the token, 403 without), `web_origin_refused_for_avatars`, `hello_capabilities` (exact hello JSON, `["control"]` only when on, version 1), `ops_forwarded_when_enabled` (all five ops), `ops_ignored_when_disabled`, `op_rate_limited` (10 of 15 pass, per client, window rolls), `unknown_op_ignored`, `bind_error_reported` (AddrInUse; None while off and while listening). **(2) Interfaces:** `GET /avatars/default/<index>.png?token=…`, `StatusApiConfig::{control, default_avatars: Arc<[Bytes]>}`, `set_control(bool)`, `CompanionOp` (Task 15's type, re-exported), ops channel via `take_ops()`, `bind_error() -> Option<io::ErrorKind>`, stale payload.rs comment removed. All present. Branch merges cleanly into current `origin/shell` (99bde430); the only other `StatusApiConfig` literal (runtime.rs) is updated. **(3) Invariants:** fluxer-core untouched; the new status-api -> fluxer-core edge is acyclic and adds no external crate (`bytes` is a workspace dep). No token in logs (Debug still redacts; images shown as a count). Server/client input cannot panic: index parse is canonical-decimal with overflow → 404; malformed JSON/ops ignored; binary frames ignored. No cfg(windows) code. **(4) Parity** (vs `fluxer_desktop/src/main/StatusApi.ts`): order loopback-403 → path-404 → disabled-404 / origin-403 / token-403 (lines 80-85, 325-345) kept for the new route; origin rule (no header, `null`, non-http(s), loopback hosts) unchanged and reused; unknown ops ignored as `handleClientMessage` (183-186); 405 with `Allow: GET` as line 301. **(5) Review Focus 9:** control off by default (`new` and runtime pass `false`), requires the token (same authorize path as the upgrade), and ops only become `CompanionOp`, which Task 15's `companion_action` maps to tray actions (ToggleSelfMute/ToggleSelfDeaf/LeaveVoice). OK. **(6) Gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in the review worktree: **all steps passed**. ### Findings - **minor**: `Closes #734` while nothing in the app uses the new route or ops until follow-up #889 lands. Matches the plan's "Closes #734" for Task 31 and #889 is open with `follow-up`, so not blocking; worth keeping #889 visible. - **minor** (decision check): `set_control` dropping all clients on a change is consistent with `set_token` and keeps the advertised capabilities honest; accepted. **Verdict: APPROVED** (0 blocking findings, gate green).
Author
Owner

Merged into shell by hand (the merge API returns 405); the commits are in the branch.

Merged into `shell` by hand (the merge API returns 405); the commits are in the branch.
charles closed this pull request 2026-11-18 12:29:20 +00:00

Pull request closed

Sign in to join this conversation.
No description provided.