Task 7: fluxer-gateway state machine and transport (#7) #44

Merged
charles merged 5 commits from task/7-gateway-machine-transport into foundation 2026-11-11 18:16:05 +00:00
Owner

What this builds

fluxer-gateway, the connection lifecycle of Foundation spec §3.4, in two layers:

  • machine.rs: GatewayMachine, a pure state machine with the plan's Input / Output / GatewayState. HELLO → IDENTIFY (flags 14) or RESUME; first heartbeat at interval*0.8 + jitter(0..=min(1500, interval*0.05)), then every interval, d = last seq; no ACK within 15 s → reconnect; op 1 → immediate heartbeat; op 7; op 9 (true → resume after 2.5–3.5 s, false → session cleared); close 4004 → AuthFailed (terminal, no output for any later input); 4007/4009 → fresh IDENTIFY; other closes → resume; backoff 1 s·2ⁿ capped at 60 s, jittered into the upper half, reset by READY/RESUMED; DecodeFailed → Reconnect{compression: None} and compression stays off for the machine's life; RESUMED → Ready.
  • connection.rs: Connection::connect(gateway_url, machine), next(), send(), plus state() (spec §3.4) and close(). One tokio task owns the socket, the machine's single timer and the reconnect timer.
  • transport.rs (private): query v=1&encoding=json&compress=zstd-stream&stream=1 or compress=none, tokio-tungstenite over rustls (platform roots, explicit ring provider), binary messages when compressed and text otherwise.
  • compression.rs: StreamEncoder / StreamDecoder on zstd::stream::raw: one stream per direction, one flushed piece per WebSocket message, level 3, window log 21, decoder WindowLogMax 21, 64 MiB cap per decompressed message. Public so fluxer-devserver (Task 13) can speak the same framing.
  • fuzz/fuzz_targets/envelope.rs: cargo-fuzz target (own workspace, not in CI) that parses envelopes and runs them through the machine.

How it was tested

  • tests/machine.rs (23 tests): the eight named in the plan, the proptest random_frames_never_panic (also asserts no Reconnect after AuthFailed and bounded delays), and extra cases for op 7, op 9 true, 4007/4009, repeated decode failures backing off, malformed dispatches, token not in Debug.
  • tests/connection.rs (10 tests) against an in-process tokio-tungstenite server: the four named in the plan, plus Review Focus 4 end to end (undecodable_stream_reconnects_without_compression: garbage mid-session → next socket asks compress=none, resumes over text, and stays uncompressed on the following reconnect), 4004 ending the stream, frames sent before READY, clean close, first-connect failure. Run 25 times in a row without a failure.
  • Unit tests for the codec (multi-chunk messages, garbage, oversized window refused) and the URL query.
  • cargo xtask ci green locally (fmt, clippy -D warnings, deny, core-isolation, tests). The fuzz target compiles (cargo check in fuzz/); it has not been run.

Deviations from the plan

  • Reconnect.resume reports what will happen: it is true only when a session id and sequence number are known, so a heartbeat timeout before the first READY says resume: false. The plan's wording reads as an unconditional true.
  • HELLO timeout added: SocketOpen schedules a 20 s tick and a tick before HELLO reconnects (the fork's GATEWAY_TIMEOUTS.Hello). Without it a socket that opens and stays silent would hang forever. Own commit.
  • Every reconnect is backed off, including op 7, op 9 false, decode failure and ACK timeout (first attempt 0.5–1 s). A server that keeps answering with op 7 or garbage therefore cannot make the client spin.
  • Bad JSON is skipped, not DecodeFailed: only a zstd failure triggers the uncompressed fallback; a message that decompresses but is not an envelope is logged and dropped.
  • Connection::send drops frames while the session is not ready instead of queueing them.
  • Reconnects close the old socket with 4000 (as the fork's client does) so the server keeps the session resumable; close() uses 1000.
  • Workspace Cargo.toml touched (outside the Files list): adds zstd (default features off), rustls (ring) and rustls-native-certs as workspace dependencies. The plan names tokio-tungstenite (rustls) and zstd; rustls/rustls-native-certs were already in the lockfile through reqwest and are named directly only to build the TLS config with an explicit crypto provider. cargo deny stays green.
  • The events channel is unbounded, so a consumer that stops calling next() while the connection stays up grows memory.
  • Not implemented: the fork's 15 s wait for RESUMED after a RESUME.

Closes #7

🤖 Generated with Claude Code

## What this builds `fluxer-gateway`, the connection lifecycle of Foundation spec §3.4, in two layers: - `machine.rs`: `GatewayMachine`, a pure state machine with the plan's `Input` / `Output` / `GatewayState`. HELLO → IDENTIFY (flags 14) or RESUME; first heartbeat at `interval*0.8 + jitter(0..=min(1500, interval*0.05))`, then every interval, `d` = last seq; no ACK within 15 s → reconnect; op 1 → immediate heartbeat; op 7; op 9 (`true` → resume after 2.5–3.5 s, `false` → session cleared); close 4004 → `AuthFailed` (terminal, no output for any later input); 4007/4009 → fresh IDENTIFY; other closes → resume; backoff 1 s·2ⁿ capped at 60 s, jittered into the upper half, reset by READY/RESUMED; `DecodeFailed` → `Reconnect{compression: None}` and compression stays off for the machine's life; `RESUMED` → `Ready`. - `connection.rs`: `Connection::connect(gateway_url, machine)`, `next()`, `send()`, plus `state()` (spec §3.4) and `close()`. One tokio task owns the socket, the machine's single timer and the reconnect timer. - `transport.rs` (private): query `v=1&encoding=json&compress=zstd-stream&stream=1` or `compress=none`, `tokio-tungstenite` over rustls (platform roots, explicit `ring` provider), binary messages when compressed and text otherwise. - `compression.rs`: `StreamEncoder` / `StreamDecoder` on `zstd::stream::raw`: one stream per direction, one flushed piece per WebSocket message, level 3, window log 21, decoder `WindowLogMax` 21, 64 MiB cap per decompressed message. Public so `fluxer-devserver` (Task 13) can speak the same framing. - `fuzz/fuzz_targets/envelope.rs`: cargo-fuzz target (own workspace, not in CI) that parses envelopes and runs them through the machine. ## How it was tested - `tests/machine.rs` (23 tests): the eight named in the plan, the proptest `random_frames_never_panic` (also asserts no `Reconnect` after `AuthFailed` and bounded delays), and extra cases for op 7, op 9 `true`, 4007/4009, repeated decode failures backing off, malformed dispatches, token not in `Debug`. - `tests/connection.rs` (10 tests) against an in-process `tokio-tungstenite` server: the four named in the plan, plus Review Focus 4 end to end (`undecodable_stream_reconnects_without_compression`: garbage mid-session → next socket asks `compress=none`, resumes over text, and stays uncompressed on the following reconnect), 4004 ending the stream, frames sent before READY, clean close, first-connect failure. Run 25 times in a row without a failure. - Unit tests for the codec (multi-chunk messages, garbage, oversized window refused) and the URL query. - `cargo xtask ci` green locally (fmt, clippy `-D warnings`, deny, core-isolation, tests). The fuzz target compiles (`cargo check` in `fuzz/`); it has not been run. ## Deviations from the plan - **`Reconnect.resume` reports what will happen**: it is `true` only when a session id and sequence number are known, so a heartbeat timeout before the first READY says `resume: false`. The plan's wording reads as an unconditional `true`. - **HELLO timeout added**: `SocketOpen` schedules a 20 s tick and a tick before HELLO reconnects (the fork's `GATEWAY_TIMEOUTS.Hello`). Without it a socket that opens and stays silent would hang forever. Own commit. - **Every reconnect is backed off**, including op 7, op 9 `false`, decode failure and ACK timeout (first attempt 0.5–1 s). A server that keeps answering with op 7 or garbage therefore cannot make the client spin. - **Bad JSON is skipped, not `DecodeFailed`**: only a zstd failure triggers the uncompressed fallback; a message that decompresses but is not an envelope is logged and dropped. - **`Connection::send` drops frames while the session is not ready** instead of queueing them. - **Reconnects close the old socket with 4000** (as the fork's client does) so the server keeps the session resumable; `close()` uses 1000. - **Workspace `Cargo.toml` touched** (outside the Files list): adds `zstd` (default features off), `rustls` (`ring`) and `rustls-native-certs` as workspace dependencies. The plan names `tokio-tungstenite` (rustls) and `zstd`; `rustls`/`rustls-native-certs` were already in the lockfile through `reqwest` and are named directly only to build the TLS config with an explicit crypto provider. `cargo deny` stays green. - The events channel is unbounded, so a consumer that stops calling `next()` while the connection stays up grows memory. - Not implemented: the fork's 15 s wait for RESUMED after a RESUME. Closes #7 🤖 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>
Author
Owner

Independent review: Task 7 (gateway machine + transport), head e600215

Verdict: APPROVE (0 blocking, 6 minor). Local cargo xtask ci in a fresh worktree with its own target dir: all steps passed (fmt, clippy, deny, core isolation, tests, screenshot tests); gateway: 23 machine tests, 10 connection tests, 6 unit tests. Remote runners not checked. Fuzz target not run.

1. Plan tests. All named tests exist and assert the spec values: hello_schedules_identify_and_first_heartbeat_in_window (33000..=34500 ms for 41250, flags 14, "Fluxer Native"), heartbeat_carries_last_seq (null, then 42, exactly one interval later), missing_ack_15s_reconnects_with_resume (14.999 s no, 15 s yes, RESUME payload checked), close_4004_is_auth_failed (terminal for every later input), invalid_session_false_clears_session, decode_failure_reconnects_without_compression, reconnect_backoff_caps_at_60s, resumed_dispatch_returns_to_ready, proptest random_frames_never_panic; connection: identify_sent_after_hello_with_compression, dispatch_events_are_yielded_in_order, server_close_triggers_reconnect_with_resume_payload, zstd_roundtrip_both_directions.

2. Interfaces. GatewayMachine::new, Input, Output, handle, GatewayState, Connection::connect/next/send, ConnectionEvent match the plan. Additions (Compression, with_seed, with_compression, state(), close(), public compression module) do not conflict.

3. Invariants. No fluxer-core/ui changes; no real tokens (test token is an obvious placeholder); GatewayMachine Debug hides the token; no panicking paths found on server data (interval clamped, decompression bounded at 64 MiB, malformed HELLO/dispatch/JSON handled). Constants cross-checked against the fork (GATEWAY_TIMEOUTS.Hello 20000, HeartbeatAck 15000, zstd level 3, window log max 21).

4. Review Focus 4. Covered in the machine (decode_failure_..., repeated_decode_failures_back_off_instead_of_looping) and end to end (undecodable_stream_reconnects_without_compression: next socket has compress=none, text frames, resumes, stays uncompressed). Compression is never re-enabled and every retry is backed off, so no loop.

Findings (all minor)

  1. minor machine.rs: no RESUMED timeout (fork: ResumeResponse 15 s). A server that accepts RESUME, keeps ACKing heartbeats and never sends RESUMED leaves the connection in Resuming indefinitely, with Connection::send dropping every frame. Follow-up issue recommended.
  2. minor machine.rs: Output and Input derive Debug, and Output::Send(IDENTIFY/RESUME) carries the raw token in d. Nothing in the crate logs them, but a consumer writing {output:?} leaks the token (the test helper reconnect() already formats {outputs:?}, with the placeholder token only). A redacting Debug would make this structural instead of a doc comment.
  3. minor connection.rs: Connection::send silently drops frames unless the state is Ready, and the plan's fn send(&self, Envelope) gives the caller no signal. Task 14's effect executor must not assume queuing across reconnects; worth stating in that task.
  4. minor connection.rs: Transport::open runs inside the select arm body, so for up to 20 s (connect timeout) the driver handles neither shutdown nor application frames; close() then falls back to aborting after 2 s without a 1000 close. The events channel is unbounded (a consumer that stops polling grows memory).
  5. minor Cargo.toml: rustls and rustls-native-certs added as direct workspace deps although the task names only tokio-tungstenite (rustls) and zstd. Both were already in the lockfile via reqwest and cargo deny is green; disclosed in the PR body. zstd-sys builds bundled C, so the Windows runner result matters here.
  6. minor Reconnect.resume is true only when session id and seq are known, and op 7 / op 9 / decode failure / ACK timeout are all backed off (0.5–1 s first). Deviates from the literal plan text (resume: true), but is the correct reading and is tested; the wss/TLS path is not exercised by any test.
## Independent review: Task 7 (gateway machine + transport), head e600215 **Verdict: APPROVE** (0 blocking, 6 minor). Local `cargo xtask ci` in a fresh worktree with its own target dir: all steps passed (fmt, clippy, deny, core isolation, tests, screenshot tests); gateway: 23 machine tests, 10 connection tests, 6 unit tests. Remote runners not checked. Fuzz target not run. **1. Plan tests.** All named tests exist and assert the spec values: `hello_schedules_identify_and_first_heartbeat_in_window` (33000..=34500 ms for 41250, flags 14, "Fluxer Native"), `heartbeat_carries_last_seq` (null, then 42, exactly one interval later), `missing_ack_15s_reconnects_with_resume` (14.999 s no, 15 s yes, RESUME payload checked), `close_4004_is_auth_failed` (terminal for every later input), `invalid_session_false_clears_session`, `decode_failure_reconnects_without_compression`, `reconnect_backoff_caps_at_60s`, `resumed_dispatch_returns_to_ready`, proptest `random_frames_never_panic`; connection: `identify_sent_after_hello_with_compression`, `dispatch_events_are_yielded_in_order`, `server_close_triggers_reconnect_with_resume_payload`, `zstd_roundtrip_both_directions`. **2. Interfaces.** `GatewayMachine::new`, `Input`, `Output`, `handle`, `GatewayState`, `Connection::connect/next/send`, `ConnectionEvent` match the plan. Additions (`Compression`, `with_seed`, `with_compression`, `state()`, `close()`, public `compression` module) do not conflict. **3. Invariants.** No fluxer-core/ui changes; no real tokens (test token is an obvious placeholder); `GatewayMachine` Debug hides the token; no panicking paths found on server data (interval clamped, decompression bounded at 64 MiB, malformed HELLO/dispatch/JSON handled). Constants cross-checked against the fork (`GATEWAY_TIMEOUTS.Hello` 20000, `HeartbeatAck` 15000, zstd level 3, window log max 21). **4. Review Focus 4.** Covered in the machine (`decode_failure_...`, `repeated_decode_failures_back_off_instead_of_looping`) and end to end (`undecodable_stream_reconnects_without_compression`: next socket has `compress=none`, text frames, resumes, stays uncompressed). Compression is never re-enabled and every retry is backed off, so no loop. ### Findings (all minor) 1. **minor** `machine.rs`: no RESUMED timeout (fork: `ResumeResponse` 15 s). A server that accepts RESUME, keeps ACKing heartbeats and never sends RESUMED leaves the connection in `Resuming` indefinitely, with `Connection::send` dropping every frame. Follow-up issue recommended. 2. **minor** `machine.rs`: `Output` and `Input` derive `Debug`, and `Output::Send(IDENTIFY/RESUME)` carries the raw token in `d`. Nothing in the crate logs them, but a consumer writing `{output:?}` leaks the token (the test helper `reconnect()` already formats `{outputs:?}`, with the placeholder token only). A redacting Debug would make this structural instead of a doc comment. 3. **minor** `connection.rs`: `Connection::send` silently drops frames unless the state is `Ready`, and the plan's `fn send(&self, Envelope)` gives the caller no signal. Task 14's effect executor must not assume queuing across reconnects; worth stating in that task. 4. **minor** `connection.rs`: `Transport::open` runs inside the select arm body, so for up to 20 s (connect timeout) the driver handles neither shutdown nor application frames; `close()` then falls back to aborting after 2 s without a 1000 close. The events channel is unbounded (a consumer that stops polling grows memory). 5. **minor** `Cargo.toml`: `rustls` and `rustls-native-certs` added as direct workspace deps although the task names only tokio-tungstenite (rustls) and zstd. Both were already in the lockfile via reqwest and `cargo deny` is green; disclosed in the PR body. `zstd-sys` builds bundled C, so the Windows runner result matters here. 6. **minor** `Reconnect.resume` is true only when session id and seq are known, and op 7 / op 9 / decode failure / ACK timeout are all backed off (0.5–1 s first). Deviates from the literal plan text (`resume: true`), but is the correct reading and is tested; the wss/TLS path is not exercised by any test.
charles merged commit db1314f5d2 into foundation 2026-11-11 18:15:53 +00:00
Sign in to join this conversation.
No description provided.