Task 7: fluxer-gateway state machine and transport #7

Closed
opened 2026-11-11 08:01:22 +00:00 by charles · 0 comments
Owner

Files:

  • Create: crates/fluxer-gateway/src/{lib.rs,machine.rs,transport.rs,compression.rs,connection.rs}
  • Test: crates/fluxer-gateway/tests/{machine.rs,connection.rs}; crates/fluxer-gateway/fuzz/fuzz_targets/envelope.rs (cargo-fuzz, not run in CI)

Interfaces:

  • Produces (pure): GatewayMachine::new(token: SecretString, properties: ClientProperties) -> Self; enum Input { SocketOpen, Frame(Envelope), SocketClosed(Option<u16>), DecodeFailed, Tick(Instant) }; enum Output { Send(Envelope), Dispatch { seq: u64, event: GatewayEvent }, ScheduleTick(Duration), Reconnect { resume: bool, after: Duration, compression: Compression }, AuthFailed, StateChanged(GatewayState) }; fn handle(&mut self, Input) -> Vec<Output>; enum GatewayState { Disconnected, Connecting, Identifying, Resuming, Ready { session_id }, Reconnecting, AuthFailed } (AuthFailed is terminal: the machine emits no further Reconnect). Rules: on HELLO schedule first heartbeat at interval*0.8 + jitter(0..=min(1500, interval*0.05)), then every interval; heartbeat d = last seq; missing ACK for 15 s → Reconnect{resume: true}; op 1 from server → immediate heartbeat; op 7 → Reconnect{resume: true}; op 9 d=true → Reconnect{resume: true, after: 2.5–3.5 s}, d=false → Reconnect{resume: false}; close 4004 → AuthFailed; 4007/4009 → fresh identify; other closes → resume with exponential backoff 1 s·2ⁿ capped 60 s, jittered; DecodeFailed → Reconnect{compression: None}; RESUMED dispatch → Ready.
  • Produces (I/O): Connection::connect(gateway_url: Url, machine: GatewayMachine) -> Result<Connection>; async fn next(&mut self) -> Option<ConnectionEvent> where enum ConnectionEvent { Dispatch(u64, GatewayEvent), State(GatewayState) } (auth failure arrives as State(GatewayState::AuthFailed)); fn send(&self, Envelope). Transport: tokio-tungstenite (rustls), zstd streaming both directions (zstd::stream::{Encoder,Decoder} level 3, window log ≤ 21), binary frames when compressed; URL query v=1&encoding=json&compress=zstd-stream&stream=1.

Plan: https://git.forked.io/charles/fluxer-native/src/branch/foundation/docs/superpowers/plans/2026-11-11-foundation.md (section "Task 7")

**Files:** - Create: `crates/fluxer-gateway/src/{lib.rs,machine.rs,transport.rs,compression.rs,connection.rs}` - Test: `crates/fluxer-gateway/tests/{machine.rs,connection.rs}`; `crates/fluxer-gateway/fuzz/fuzz_targets/envelope.rs` (cargo-fuzz, not run in CI) **Interfaces:** - Produces (pure): `GatewayMachine::new(token: SecretString, properties: ClientProperties) -> Self`; `enum Input { SocketOpen, Frame(Envelope), SocketClosed(Option<u16>), DecodeFailed, Tick(Instant) }`; `enum Output { Send(Envelope), Dispatch { seq: u64, event: GatewayEvent }, ScheduleTick(Duration), Reconnect { resume: bool, after: Duration, compression: Compression }, AuthFailed, StateChanged(GatewayState) }`; `fn handle(&mut self, Input) -> Vec<Output>`; `enum GatewayState { Disconnected, Connecting, Identifying, Resuming, Ready { session_id }, Reconnecting, AuthFailed }` (`AuthFailed` is terminal: the machine emits no further `Reconnect`). Rules: on HELLO schedule first heartbeat at `interval*0.8 + jitter(0..=min(1500, interval*0.05))`, then every `interval`; heartbeat `d` = last seq; missing ACK for 15 s → `Reconnect{resume: true}`; op 1 from server → immediate heartbeat; op 7 → `Reconnect{resume: true}`; op 9 `d=true` → `Reconnect{resume: true, after: 2.5–3.5 s}`, `d=false` → `Reconnect{resume: false}`; close 4004 → `AuthFailed`; 4007/4009 → fresh identify; other closes → resume with exponential backoff 1 s·2ⁿ capped 60 s, jittered; `DecodeFailed` → `Reconnect{compression: None}`; `RESUMED` dispatch → `Ready`. - Produces (I/O): `Connection::connect(gateway_url: Url, machine: GatewayMachine) -> Result<Connection>`; `async fn next(&mut self) -> Option<ConnectionEvent>` where `enum ConnectionEvent { Dispatch(u64, GatewayEvent), State(GatewayState) }` (auth failure arrives as `State(GatewayState::AuthFailed)`); `fn send(&self, Envelope)`. Transport: `tokio-tungstenite` (rustls), zstd streaming both directions (`zstd::stream::{Encoder,Decoder}` level 3, window log ≤ 21), binary frames when compressed; URL query `v=1&encoding=json&compress=zstd-stream&stream=1`. --- Plan: https://git.forked.io/charles/fluxer-native/src/branch/foundation/docs/superpowers/plans/2026-11-11-foundation.md (section "Task 7")
charles added this to the Foundation milestone 2026-11-11 08:01:22 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
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
charles/fluxer-native#7
No description provided.