Task 13: fluxer-devserver fixture server (#13) #47

Manually merged
charles merged 0 commits from task/13-devserver into foundation 2026-11-11 18:28:10 +00:00
Owner

Stacked on: task/7-gateway-machine-transport

What this builds

fluxer-devserver: a fixture-backed Fluxer instance on one ephemeral loopback port, for tests and for fluxer --devserver (Task 14).

  • DevServer::spawn(fixtures_dir: &Path, scenario: &str) -> DevServer { instance_url: Url } (panics if the fixtures cannot be loaded) and DevServer::try_spawn(..) -> Result<DevServer, Error>. Dropping the server stops it and its gateway sessions. Constants DEMO_LOGIN, DEMO_PASSWORD, MFA_LOGIN, MFA_CODE.
  • REST (axum): /api/.well-known/fluxer with every endpoint rewritten to the server, /auth/login (demo/demo; mfa answers the MFA fixture), /auth/login/mfa/totp (code 000000), /auth/logout, /users/@me, GET /channels/{id}/messages (limit/before/after/around, newest first) over a history generated from the scenario, POST messages echoing the nonce, typing, ack. Error bodies are {code, message}; a wrong or missing token is a 401.
  • Gateway at /gateway: HELLO 41250 -> IDENTIFY -> READY from ready.json, heartbeat ACKs, compress=zstd-stream (using fluxer_gateway::compression) or plain text frames, close 4004 for a wrong token, INVALID_SESSION false for RESUME (sessions are not kept), then the scenario timeline with increasing sequence numbers, and a MESSAGE_CREATE for every message sent over REST.
  • fixtures/scenarios/basic.toml: 120 generated messages in #general, then GUILD_CREATE (2 guilds, 6 channels), a three-event typing burst, a MESSAGE_CREATE, a PRESENCE_UPDATE; plays in 3.5 s.
  • Binary: fluxer-devserver --fixtures fixtures --scenario basic prints the instance URL and serves until interrupted.

How it was tested

crates/fluxer-devserver/tests/scenario.rs drives the server with the real fluxer-api and fluxer-gateway crates: client_can_login_and_receive_ready_from_devserver, scenario_events_arrive_in_order (names, sequence numbers 1..=7, 2 guilds / 6 channels), plain-JSON gateway, 4004 on a wrong token, the MFA flow, 400/401 rejections, pagination through all 120 messages with before/after/around, send -> nonce echo -> gateway MESSAGE_CREATE -> newest in history, and an unknown scenario being an error. Unit tests cover history generation, the endpoint rewrite and frame unwrapping. The tests were committed failing first. cargo xtask ci is green locally; the binary was smoke-tested with curl.

Deviations from the plan

  • New dependencies beyond axum: toml (the plan asks for a .toml scenario but names no parser) and direct use of hyper / hyper-util, both already in the graph. The WebSocket upgrade is done by hand on axum's connection because axum's ws feature pulls tungstenite 0.29 next to the workspace's 0.30.
  • spawn keeps the plan's signature (synchronous, infallible, must be called inside a tokio runtime); try_spawn is the fallible form the binary uses.
  • The signed-in user is the user of gateway/ready.json on both sides, not the user of rest/login_ok.json / rest/user_me.json: the REST and gateway fixtures describe different accounts, and one session needs one identity. Only the token is taken from login_ok.json.
  • Scenario files also have a [[messages]] table (channel, count, newest id) for the generated history; the plan only shows [[event]].
  • basic reaches "2 guilds, 6 channels" through its GUILD_CREATE event, because ready.json has the second guild unavailable.
  • Message edit and delete are not served (404); the plan does not list them.

Closes #13

🤖 Generated with Claude Code

Stacked on: task/7-gateway-machine-transport ## What this builds `fluxer-devserver`: a fixture-backed Fluxer instance on one ephemeral loopback port, for tests and for `fluxer --devserver` (Task 14). - `DevServer::spawn(fixtures_dir: &Path, scenario: &str) -> DevServer { instance_url: Url }` (panics if the fixtures cannot be loaded) and `DevServer::try_spawn(..) -> Result<DevServer, Error>`. Dropping the server stops it and its gateway sessions. Constants `DEMO_LOGIN`, `DEMO_PASSWORD`, `MFA_LOGIN`, `MFA_CODE`. - REST (axum): `/api/.well-known/fluxer` with every endpoint rewritten to the server, `/auth/login` (`demo`/`demo`; `mfa` answers the MFA fixture), `/auth/login/mfa/totp` (code `000000`), `/auth/logout`, `/users/@me`, `GET /channels/{id}/messages` (`limit`/`before`/`after`/`around`, newest first) over a history generated from the scenario, `POST messages` echoing the `nonce`, `typing`, `ack`. Error bodies are `{code, message}`; a wrong or missing token is a 401. - Gateway at `/gateway`: HELLO 41250 -> IDENTIFY -> READY from `ready.json`, heartbeat ACKs, `compress=zstd-stream` (using `fluxer_gateway::compression`) or plain text frames, close 4004 for a wrong token, INVALID_SESSION `false` for RESUME (sessions are not kept), then the scenario timeline with increasing sequence numbers, and a `MESSAGE_CREATE` for every message sent over REST. - `fixtures/scenarios/basic.toml`: 120 generated messages in `#general`, then `GUILD_CREATE` (2 guilds, 6 channels), a three-event typing burst, a `MESSAGE_CREATE`, a `PRESENCE_UPDATE`; plays in 3.5 s. - Binary: `fluxer-devserver --fixtures fixtures --scenario basic` prints the instance URL and serves until interrupted. ## How it was tested `crates/fluxer-devserver/tests/scenario.rs` drives the server with the real `fluxer-api` and `fluxer-gateway` crates: `client_can_login_and_receive_ready_from_devserver`, `scenario_events_arrive_in_order` (names, sequence numbers 1..=7, 2 guilds / 6 channels), plain-JSON gateway, 4004 on a wrong token, the MFA flow, 400/401 rejections, pagination through all 120 messages with `before`/`after`/`around`, send -> nonce echo -> gateway `MESSAGE_CREATE` -> newest in history, and an unknown scenario being an error. Unit tests cover history generation, the endpoint rewrite and frame unwrapping. The tests were committed failing first. `cargo xtask ci` is green locally; the binary was smoke-tested with curl. ## Deviations from the plan - New dependencies beyond `axum`: `toml` (the plan asks for a `.toml` scenario but names no parser) and direct use of `hyper` / `hyper-util`, both already in the graph. The WebSocket upgrade is done by hand on axum's connection because axum's `ws` feature pulls tungstenite 0.29 next to the workspace's 0.30. - `spawn` keeps the plan's signature (synchronous, infallible, must be called inside a tokio runtime); `try_spawn` is the fallible form the binary uses. - The signed-in user is the `user` of `gateway/ready.json` on both sides, not the user of `rest/login_ok.json` / `rest/user_me.json`: the REST and gateway fixtures describe different accounts, and one session needs one identity. Only the token is taken from `login_ok.json`. - Scenario files also have a `[[messages]]` table (channel, count, newest id) for the generated history; the plan only shows `[[event]]`. - `basic` reaches "2 guilds, 6 channels" through its `GUILD_CREATE` event, because `ready.json` has the second guild unavailable. - Message edit and delete are not served (404); the plan does not list them. Closes #13 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Adds the gateway crate's dependencies (rustls, rustls-native-certs and zstd are
new to the workspace; Task 7 names tokio-tungstenite with rustls and zstd).

Refs #7

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #7

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #7

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #7

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(gateway): websocket transport with zstd streaming
All checks were successful
ci / Windows (x64) (push) Successful in 57s
ci / Windows (x64) (pull_request) Successful in 48s
ci / Linux (x86_64) (push) Successful in 1m3s
ci / Linux (x86_64) (pull_request) Successful in 1m3s
e60021584a
Refs #7

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Refs #13

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(devserver): fixture-backed API and gateway for tests
All checks were successful
ci / Windows (x64) (pull_request) Successful in 1m11s
ci / Linux (x86_64) (pull_request) Successful in 1m20s
ci / Windows (x64) (push) Successful in 57s
ci / Linux (x86_64) (push) Successful in 1m10s
4c00cf12fd
Refs #13

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Task 13 (devserver) at 4c00cf1

Scope: git diff e600215..origin/task/13-devserver (11 files). Read cold; implementer notes verified against the code.

1. Plan tests - OK. client_can_login_and_receive_ready_from_devserver and scenario_events_arrive_in_order exist in crates/fluxer-devserver/tests/scenario.rs, drive the real fluxer-api + fluxer-gateway against DevServer::spawn, and assert discovery pointing at the server, demo login, READY at seq 1 over zstd-stream, ordered timeline with seq 1..=7, 2 guilds / 6 channels. Further tests cover 120 messages in #general with pagination, nonce echo + gateway MESSAGE_CREATE, MFA with 000000, 4004 on a wrong token, plain JSON. Failing-test commit precedes the implementation commit.

2. Interfaces - OK. DevServer::spawn(fixtures_dir: &Path, scenario: &str) -> DevServer with pub instance_url: Url, ephemeral loopback port; all listed endpoints served; /gateway does HELLO (41250, from hello.json) -> IDENTIFY -> READY from ready.json, then the [[event]] timeline; binary takes --fixtures / --scenario and prints the URL. Additions (try_spawn, DEMO_LOGIN, DEMO_PASSWORD, MFA_LOGIN, MFA_CODE, [[messages]]) do not conflict with the plan.

3. Constraints / invariants - OK. No change to fluxer-core or fluxer-ui; no secrets (the only token is the existing placeholder in fixtures/rest/login_ok.json); no unwrap/expect on request data in the server; README updated; commit trailers and Refs #13 present.

4. Review Focus - no item belongs to this task.

5. cargo xtask ci - green locally in the review worktree (fmt, clippy, deny: advisories/bans/licenses/sources ok, all tests; devserver 4 unit + 9 integration; screenshot step skipped as configured).

Findings

  • minor - Cargo.toml: toml (plus serde_spanned, toml_writer) is new to the lockfile, and hyper / hyper-util become direct dependencies; the plan names only axum. CLAUDE.md says new dependencies come only via a task that names them. A TOML parser is implied by basic.toml and cargo deny is green, so not blocking, but Charles should accept this explicitly at merge.
  • minor - tests/scenario.rs: no test asserts HELLO heartbeat_interval == 41250; the value comes from fixtures/gateway/hello.json (verified by inspection). A one-line assertion would pin the Global Constraint.
  • minor - src/scenario.rs: identity deviation confirmed. login_ok.json / user_me.json ("charles") and ready.json ("charlie") disagree; the server serves ready.json's user everywhere and user_me.json is unused by it. Reasonable for this task (fixtures belong to other tasks), but the fixtures should be aligned in a follow-up issue.
  • minor - src/gateway.rs: every new connection replays the whole timeline and RESUME is always answered with INVALID_SESSION false, so a client that reconnects sees typing/presence/GUILD_CREATE again (the MESSAGE_CREATE is deduplicated in history, not on the wire). Fine for Foundation; Task 14 and later UI tests should not assume resume works against the devserver.
  • minor - src/lib.rs: Drop aborts the accept loop and ends gateway sessions, but HTTP connections already accepted by axum::serve keep being served until the peer closes them. Harmless in tests.
  • minor - src/scenario.rs: a sent message is stored with its nonce, so later GET messages returns it too, unlike the real server.

Verdict: APPROVE - zero blocking findings, local ci green. Remote runners not checked (integrator's job).

## Independent review: Task 13 (devserver) at 4c00cf1 Scope: `git diff e600215..origin/task/13-devserver` (11 files). Read cold; implementer notes verified against the code. **1. Plan tests** - OK. `client_can_login_and_receive_ready_from_devserver` and `scenario_events_arrive_in_order` exist in `crates/fluxer-devserver/tests/scenario.rs`, drive the real `fluxer-api` + `fluxer-gateway` against `DevServer::spawn`, and assert discovery pointing at the server, demo login, READY at seq 1 over zstd-stream, ordered timeline with seq 1..=7, 2 guilds / 6 channels. Further tests cover 120 messages in `#general` with pagination, nonce echo + gateway `MESSAGE_CREATE`, MFA with `000000`, 4004 on a wrong token, plain JSON. Failing-test commit precedes the implementation commit. **2. Interfaces** - OK. `DevServer::spawn(fixtures_dir: &Path, scenario: &str) -> DevServer` with `pub instance_url: Url`, ephemeral loopback port; all listed endpoints served; `/gateway` does HELLO (41250, from `hello.json`) -> IDENTIFY -> READY from `ready.json`, then the `[[event]]` timeline; binary takes `--fixtures` / `--scenario` and prints the URL. Additions (`try_spawn`, `DEMO_LOGIN`, `DEMO_PASSWORD`, `MFA_LOGIN`, `MFA_CODE`, `[[messages]]`) do not conflict with the plan. **3. Constraints / invariants** - OK. No change to `fluxer-core` or `fluxer-ui`; no secrets (the only token is the existing placeholder in `fixtures/rest/login_ok.json`); no `unwrap`/`expect` on request data in the server; README updated; commit trailers and `Refs #13` present. **4. Review Focus** - no item belongs to this task. **5. `cargo xtask ci`** - green locally in the review worktree (fmt, clippy, deny: advisories/bans/licenses/sources ok, all tests; devserver 4 unit + 9 integration; screenshot step skipped as configured). ### Findings - **minor** - `Cargo.toml`: `toml` (plus `serde_spanned`, `toml_writer`) is new to the lockfile, and `hyper` / `hyper-util` become direct dependencies; the plan names only `axum`. CLAUDE.md says new dependencies come only via a task that names them. A TOML parser is implied by `basic.toml` and `cargo deny` is green, so not blocking, but Charles should accept this explicitly at merge. - **minor** - `tests/scenario.rs`: no test asserts HELLO `heartbeat_interval == 41250`; the value comes from `fixtures/gateway/hello.json` (verified by inspection). A one-line assertion would pin the Global Constraint. - **minor** - `src/scenario.rs`: identity deviation confirmed. `login_ok.json` / `user_me.json` ("charles") and `ready.json` ("charlie") disagree; the server serves `ready.json`'s user everywhere and `user_me.json` is unused by it. Reasonable for this task (fixtures belong to other tasks), but the fixtures should be aligned in a `follow-up` issue. - **minor** - `src/gateway.rs`: every new connection replays the whole timeline and RESUME is always answered with INVALID_SESSION `false`, so a client that reconnects sees typing/presence/GUILD_CREATE again (the `MESSAGE_CREATE` is deduplicated in history, not on the wire). Fine for Foundation; Task 14 and later UI tests should not assume resume works against the devserver. - **minor** - `src/lib.rs`: `Drop` aborts the accept loop and ends gateway sessions, but HTTP connections already accepted by `axum::serve` keep being served until the peer closes them. Harmless in tests. - **minor** - `src/scenario.rs`: a sent message is stored with its `nonce`, so later `GET messages` returns it too, unlike the real server. **Verdict: APPROVE** - zero blocking findings, local ci green. Remote runners not checked (integrator's job).
charles manually merged commit 24e7c9d137 into foundation 2026-11-11 18:28:10 +00:00
Sign in to join this conversation.
No description provided.