Task 7: fluxer-gateway state machine and transport (#7) #44
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "task/7-gateway-machine-transport"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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'sInput/Output/GatewayState. HELLO → IDENTIFY (flags 14) or RESUME; first heartbeat atinterval*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(), plusstate()(spec §3.4) andclose(). One tokio task owns the socket, the machine's single timer and the reconnect timer.transport.rs(private): queryv=1&encoding=json&compress=zstd-stream&stream=1orcompress=none,tokio-tungsteniteover rustls (platform roots, explicitringprovider), binary messages when compressed and text otherwise.compression.rs:StreamEncoder/StreamDecoderonzstd::stream::raw: one stream per direction, one flushed piece per WebSocket message, level 3, window log 21, decoderWindowLogMax21, 64 MiB cap per decompressed message. Public sofluxer-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 proptestrandom_frames_never_panic(also asserts noReconnectafterAuthFailedand bounded delays), and extra cases for op 7, op 9true, 4007/4009, repeated decode failures backing off, malformed dispatches, token not inDebug.tests/connection.rs(10 tests) against an in-processtokio-tungsteniteserver: the four named in the plan, plus Review Focus 4 end to end (undecodable_stream_reconnects_without_compression: garbage mid-session → next socket askscompress=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.cargo xtask cigreen locally (fmt, clippy-D warnings, deny, core-isolation, tests). The fuzz target compiles (cargo checkinfuzz/); it has not been run.Deviations from the plan
Reconnect.resumereports what will happen: it istrueonly when a session id and sequence number are known, so a heartbeat timeout before the first READY saysresume: false. The plan's wording reads as an unconditionaltrue.SocketOpenschedules a 20 s tick and a tick before HELLO reconnects (the fork'sGATEWAY_TIMEOUTS.Hello). Without it a socket that opens and stays silent would hang forever. Own commit.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.DecodeFailed: only a zstd failure triggers the uncompressed fallback; a message that decompresses but is not an envelope is logged and dropped.Connection::senddrops frames while the session is not ready instead of queueing them.close()uses 1000.Cargo.tomltouched (outside the Files list): addszstd(default features off),rustls(ring) andrustls-native-certsas workspace dependencies. The plan namestokio-tungstenite(rustls) andzstd;rustls/rustls-native-certswere already in the lockfile throughreqwestand are named directly only to build the TLS config with an explicit crypto provider.cargo denystays green.next()while the connection stays up grows memory.Closes #7
🤖 Generated with Claude Code
Independent review: Task 7 (gateway machine + transport), head
e600215Verdict: APPROVE (0 blocking, 6 minor). Local
cargo xtask ciin 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, proptestrandom_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,ConnectionEventmatch the plan. Additions (Compression,with_seed,with_compression,state(),close(), publiccompressionmodule) do not conflict.3. Invariants. No fluxer-core/ui changes; no real tokens (test token is an obvious placeholder);
GatewayMachineDebug 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.Hello20000,HeartbeatAck15000, 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 hascompress=none, text frames, resumes, stays uncompressed). Compression is never re-enabled and every retry is backed off, so no loop.Findings (all minor)
machine.rs: no RESUMED timeout (fork:ResumeResponse15 s). A server that accepts RESUME, keeps ACKing heartbeats and never sends RESUMED leaves the connection inResumingindefinitely, withConnection::senddropping every frame. Follow-up issue recommended.machine.rs:OutputandInputderiveDebug, andOutput::Send(IDENTIFY/RESUME)carries the raw token ind. Nothing in the crate logs them, but a consumer writing{output:?}leaks the token (the test helperreconnect()already formats{outputs:?}, with the placeholder token only). A redacting Debug would make this structural instead of a doc comment.connection.rs:Connection::sendsilently drops frames unless the state isReady, and the plan'sfn send(&self, Envelope)gives the caller no signal. Task 14's effect executor must not assume queuing across reconnects; worth stating in that task.connection.rs:Transport::openruns 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).Cargo.toml:rustlsandrustls-native-certsadded as direct workspace deps although the task names only tokio-tungstenite (rustls) and zstd. Both were already in the lockfile via reqwest andcargo denyis green; disclosed in the PR body.zstd-sysbuilds bundled C, so the Windows runner result matters here.Reconnect.resumeis 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.