Task 4: fluxer-proto gateway envelope, opcodes, events (#4) #36

Merged
charles merged 5 commits from task/4-proto-gateway-events into foundation 2026-11-11 09:18:59 +00:00
Owner

What this builds

fluxer_proto::gateway (issue #4, plan Task 4):

  • Envelope { op, d, s, t } with builders heartbeat, identify, resume, presence_update; Opcode (the fork's 18 values + Unknown(u8)); CloseCode (4000-4012 + Unknown(u16)).
  • IDENTIFY_FLAGS = 14, ClientProperties, Identify, Resume, Hello, PresenceUpdate (the client's own presence). Debug of Identify/Resume redacts the token.
  • ReadyPayload, GuildReadyData (guild object nested under properties).
  • GatewayEvent with the typed variants of the plan and Unknown { name, payload }; GatewayEvent::from_dispatch(t, d) -> Result<GatewayEvent, ProtoError>; ProtoError::Malformed { t, source }.
  • DISPATCH_NAMES: [&str; 84] from the fork's EventRouter.ts, plus TYPED_DISPATCH_NAMES and UNTYPED_IN_FOUNDATION.
  • 11 hand-authored frames in fixtures/gateway (whole {op, d, s, t} envelopes, no secrets), README section for the crate.

How it was tested

crates/fluxer-proto/tests/gateway.rs, written first and seen failing (commit bc7cf35), 18 tests: the seven named in the plan (envelope_roundtrip, hello_parses_41250, ready_fixture_parses_with_guild_properties_nested, unknown_dispatch_becomes_unknown_variant, malformed_known_dispatch_is_error_not_panic, identify_serializes_flags_14, all_84_dispatch_names_are_classified), every fixture mapped to its variant, the events without a fixture parsed from the fork's payload shapes, opcode/close-code tables, token redaction, and two proptests (arbitrary dispatch name + payload, arbitrary frame) for Review Focus 1. all_84_dispatch_names_are_classified checks the lists against each other and against what from_dispatch actually returns for each name. cargo xtask ci is green locally.

Deviations from the plan (reviewer: please look at these)

  1. This branch contains a merge of task/3-proto-rest-models (PR #35, at 7f384d7). The gateway payloads are made of Task 3's models (Message, Guild, Channel, ...), which are not on foundation yet although the plan runs Tasks 3 and 4 in parallel. Merge #35 first; until then this PR's diff also shows Task 3's files. The only Task 4 changes outside the task's Files list are crates/fluxer-proto/src/lib.rs (module + re-exports) and crates/fluxer-proto/README.md.
  2. GuildReadyData.properties is Option<Guild>, not Guild. The gateway sends an unavailable guild in READY.guilds as {"id": "...", "unavailable": true} with nothing else (fluxer_gateway/src/session/session_ready_dispatch.erl:197, and GatewayReady.ts:131 skips them). A required properties would make one unavailable guild fail the whole READY. channels/roles/members default to empty, member_count to 0. Task 9 has to handle None.
  3. RESUMED and READ_STATE_UPDATE are typed but are not among the 84 names: the fork handles RESUMED in the socket, not the router, and no READ_STATE_UPDATE dispatch exists in the fork (read markers move with MESSAGE_ACK). The ReadStateUpdate(ReadState) variant is kept because the plan's interface lists it; it is documented as not sent today. So 22 of the 84 are typed, 62 are in UNTYPED_IN_FOUNDATION.
  4. Large payloads are boxed (Ready(Box<ReadyPayload>), MessageCreate(Box<Message>), GuildCreate(Box<GuildReadyData>), Channel*, GuildUpdate, PresenceUpdate, UserUpdate, MessageUpdate) to keep the enum small.
  5. ClientProperties follows the plan's field list. The fork's GatewaySocketProperties also has user_agent and has no system_locale; the gateway only reads properties as a map, so this was left as planned.
  6. Envelope always writes d (null when None), as the Electron client does for the first heartbeat; s/t are omitted when unset.

Closes #4

🤖 Generated with Claude Code

## What this builds `fluxer_proto::gateway` (issue #4, plan Task 4): - `Envelope { op, d, s, t }` with builders `heartbeat`, `identify`, `resume`, `presence_update`; `Opcode` (the fork's 18 values + `Unknown(u8)`); `CloseCode` (4000-4012 + `Unknown(u16)`). - `IDENTIFY_FLAGS = 14`, `ClientProperties`, `Identify`, `Resume`, `Hello`, `PresenceUpdate` (the client's own presence). `Debug` of `Identify`/`Resume` redacts the token. - `ReadyPayload`, `GuildReadyData` (guild object nested under `properties`). - `GatewayEvent` with the typed variants of the plan and `Unknown { name, payload }`; `GatewayEvent::from_dispatch(t, d) -> Result<GatewayEvent, ProtoError>`; `ProtoError::Malformed { t, source }`. - `DISPATCH_NAMES: [&str; 84]` from the fork's `EventRouter.ts`, plus `TYPED_DISPATCH_NAMES` and `UNTYPED_IN_FOUNDATION`. - 11 hand-authored frames in `fixtures/gateway` (whole `{op, d, s, t}` envelopes, no secrets), README section for the crate. ## How it was tested `crates/fluxer-proto/tests/gateway.rs`, written first and seen failing (commit `bc7cf35`), 18 tests: the seven named in the plan (`envelope_roundtrip`, `hello_parses_41250`, `ready_fixture_parses_with_guild_properties_nested`, `unknown_dispatch_becomes_unknown_variant`, `malformed_known_dispatch_is_error_not_panic`, `identify_serializes_flags_14`, `all_84_dispatch_names_are_classified`), every fixture mapped to its variant, the events without a fixture parsed from the fork's payload shapes, opcode/close-code tables, token redaction, and two proptests (arbitrary dispatch name + payload, arbitrary frame) for Review Focus 1. `all_84_dispatch_names_are_classified` checks the lists against each other and against what `from_dispatch` actually returns for each name. `cargo xtask ci` is green locally. ## Deviations from the plan (reviewer: please look at these) 1. **This branch contains a merge of `task/3-proto-rest-models` (PR #35, at `7f384d7`).** The gateway payloads are made of Task 3's models (`Message`, `Guild`, `Channel`, ...), which are not on `foundation` yet although the plan runs Tasks 3 and 4 in parallel. Merge #35 first; until then this PR's diff also shows Task 3's files. The only Task 4 changes outside the task's Files list are `crates/fluxer-proto/src/lib.rs` (module + re-exports) and `crates/fluxer-proto/README.md`. 2. **`GuildReadyData.properties` is `Option<Guild>`, not `Guild`.** The gateway sends an unavailable guild in `READY.guilds` as `{"id": "...", "unavailable": true}` with nothing else (`fluxer_gateway/src/session/session_ready_dispatch.erl:197`, and `GatewayReady.ts:131` skips them). A required `properties` would make one unavailable guild fail the whole `READY`. `channels`/`roles`/`members` default to empty, `member_count` to 0. Task 9 has to handle `None`. 3. **`RESUMED` and `READ_STATE_UPDATE` are typed but are not among the 84 names**: the fork handles `RESUMED` in the socket, not the router, and no `READ_STATE_UPDATE` dispatch exists in the fork (read markers move with `MESSAGE_ACK`). The `ReadStateUpdate(ReadState)` variant is kept because the plan's interface lists it; it is documented as not sent today. So 22 of the 84 are typed, 62 are in `UNTYPED_IN_FOUNDATION`. 4. Large payloads are boxed (`Ready(Box<ReadyPayload>)`, `MessageCreate(Box<Message>)`, `GuildCreate(Box<GuildReadyData>)`, `Channel*`, `GuildUpdate`, `PresenceUpdate`, `UserUpdate`, `MessageUpdate`) to keep the enum small. 5. `ClientProperties` follows the plan's field list. The fork's `GatewaySocketProperties` also has `user_agent` and has no `system_locale`; the gateway only reads `properties` as a map, so this was left as planned. 6. `Envelope` always writes `d` (`null` when `None`), as the Electron client does for the first heartbeat; `s`/`t` are omitted when unset. Closes #4 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Refs #3

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

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(proto): REST wire models and fixtures
All checks were successful
ci / Windows (x64) (push) Successful in 16s
ci / Windows (x64) (pull_request) Successful in 14s
ci / Linux (x86_64) (push) Successful in 47s
ci / Linux (x86_64) (pull_request) Successful in 45s
7f384d7aa0
Refs #3

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The gateway payloads are built from the REST models of Task 3 (Message,
Guild, Channel, ...), which are not on foundation yet.

Refs #4

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(proto): gateway envelope, opcodes and events
All checks were successful
ci / Windows (x64) (push) Successful in 14s
ci / Windows (x64) (pull_request) Successful in 16s
ci / Linux (x86_64) (push) Successful in 50s
ci / Linux (x86_64) (pull_request) Successful in 45s
425f13c13b
Refs #4

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

Independent review — Task 4 (proto-gateway-events), head 425f13c

Verdict: APPROVE — 0 blocking, 4 minor. Local cargo xtask ci in a clean review worktree: green (fmt, clippy, deny, tests; screenshot step skipped as configured). Remote runners not checked (integrator's job).

What I verified

  1. Plan tests — all seven named tests exist in crates/fluxer-proto/tests/gateway.rs and assert the plan's values: envelope_roundtrip (all 11 fixtures), hello_parses_41250, ready_fixture_parses_with_guild_properties_nested, unknown_dispatch_becomes_unknown_variant (FAVORITE_MEME_CREATE, payload untouched), malformed_known_dispatch_is_error_not_panic, identify_serializes_flags_14, all_84_dispatch_names_are_classified (also checks the lists against what from_dispatch actually does).
  2. Interfaces vs. the fork — DISPATCH_NAMES is identical, in order, to the 84 registry.set(...) names in EventRouter.ts; the 18 opcodes and 12 close codes match GatewayConstants.ts; IDENTIFY_FLAGS == 14; payload shapes of TYPING_START, MESSAGE_ACK, MESSAGE_DELETE(_BULK), GUILD_DELETE, GUILD_MEMBER_ADD/REMOVE, GUILD_ROLE_CREATE/DELETE match the fork's handler payload types.
  3. Invariants — no new dependencies (no Cargo.toml / Cargo.lock / deny.toml change); pure data, no I/O; no tokens in fixtures (only the obvious placeholder in fixtures/rest/login_ok.json from Task 3); Identify/Resume Debug redact the token. Nothing in the gateway module can panic on server data: I probed nulls, floats, missing members and wrong types and got Err(Malformed) every time.
  4. Review Focus 1 — covered by the fixture test, the future-name loop and the arbitrary_dispatch_never_panics proptest.
  5. Deviation 2 is correct: fluxer_gateway/src/session/session_ready.erl build_unavailable_state emits exactly {id, unavailable: true} (plus unavailable_hidden), so a required properties would fail the whole READY.

Findings

  • minor — interface deviations other tasks must know about (gateway/events.rs, gateway/ready.rs): GuildReadyData.properties is Option<Guild> (Task 9 must handle None); Ready, MessageCreate, MessageUpdate, Channel*, GuildCreate, GuildUpdate, PresenceUpdate, UserUpdate are boxed, and GuildMemberAdd/Update.member is Box<GuildMember>; ReadStateUpdate carries a ReadState. Tasks 7-11 pattern-match on these; the plan's Interfaces block should be updated to the shipped shapes before they start.
  • minor — explicit null is rejected where absence is accepted (gateway/ready.rs, gateway/events.rs): #[serde(default)] without the null_to_default helper Task 3's models use. {"channels": null} or {"member_count": null} in one guild snapshot, or {"unavailable": null} in GUILD_DELETE, gives Malformed; inside READY that loses the whole READY, so the session never becomes ready. The fork's types say these are absent-or-present, never null, so not blocking; worth a follow-up to make the gateway types as lenient as the models.
  • minor — MessageUpdate.channel_id is required (gateway/events.rs): the fork's MessageUpdatePayload declares channel_id?: string. An update without it is dropped as Malformed (logged, session continues).
  • minor — ClientProperties differs from the fork's GatewaySocketProperties (gateway/identify.rs): it follows the plan (has system_locale, lacks the fork's required user_agent). Already flagged by the implementer; decide before Task 7 sends a real IDENTIFY.

Merge order

The branch contains a merge of task/3-proto-rest-models (7f384d7), so this PR's diff shows Task 3's files too. Merge #35 first; if Task 3 changes in review, this branch needs that merged in again before it lands.

🤖 Generated with Claude Code

## Independent review — Task 4 (proto-gateway-events), head `425f13c` **Verdict: APPROVE** — 0 blocking, 4 minor. Local `cargo xtask ci` in a clean review worktree: **green** (fmt, clippy, deny, tests; screenshot step skipped as configured). Remote runners not checked (integrator's job). ### What I verified 1. **Plan tests** — all seven named tests exist in `crates/fluxer-proto/tests/gateway.rs` and assert the plan's values: `envelope_roundtrip` (all 11 fixtures), `hello_parses_41250`, `ready_fixture_parses_with_guild_properties_nested`, `unknown_dispatch_becomes_unknown_variant` (`FAVORITE_MEME_CREATE`, payload untouched), `malformed_known_dispatch_is_error_not_panic`, `identify_serializes_flags_14`, `all_84_dispatch_names_are_classified` (also checks the lists against what `from_dispatch` actually does). 2. **Interfaces vs. the fork** — `DISPATCH_NAMES` is identical, in order, to the 84 `registry.set(...)` names in `EventRouter.ts`; the 18 opcodes and 12 close codes match `GatewayConstants.ts`; `IDENTIFY_FLAGS == 14`; payload shapes of TYPING_START, MESSAGE_ACK, MESSAGE_DELETE(_BULK), GUILD_DELETE, GUILD_MEMBER_ADD/REMOVE, GUILD_ROLE_CREATE/DELETE match the fork's handler payload types. 3. **Invariants** — no new dependencies (no Cargo.toml / Cargo.lock / deny.toml change); pure data, no I/O; no tokens in fixtures (only the obvious placeholder in `fixtures/rest/login_ok.json` from Task 3); `Identify`/`Resume` `Debug` redact the token. Nothing in the gateway module can panic on server data: I probed nulls, floats, missing members and wrong types and got `Err(Malformed)` every time. 4. **Review Focus 1** — covered by the fixture test, the future-name loop and the `arbitrary_dispatch_never_panics` proptest. 5. **Deviation 2 is correct**: `fluxer_gateway/src/session/session_ready.erl` `build_unavailable_state` emits exactly `{id, unavailable: true}` (plus `unavailable_hidden`), so a required `properties` would fail the whole READY. ### Findings - **minor — interface deviations other tasks must know about** (`gateway/events.rs`, `gateway/ready.rs`): `GuildReadyData.properties` is `Option<Guild>` (Task 9 must handle `None`); `Ready`, `MessageCreate`, `MessageUpdate`, `Channel*`, `GuildCreate`, `GuildUpdate`, `PresenceUpdate`, `UserUpdate` are boxed, and `GuildMemberAdd/Update.member` is `Box<GuildMember>`; `ReadStateUpdate` carries a `ReadState`. Tasks 7-11 pattern-match on these; the plan's Interfaces block should be updated to the shipped shapes before they start. - **minor — explicit `null` is rejected where absence is accepted** (`gateway/ready.rs`, `gateway/events.rs`): `#[serde(default)]` without the `null_to_default` helper Task 3's models use. `{"channels": null}` or `{"member_count": null}` in one guild snapshot, or `{"unavailable": null}` in GUILD_DELETE, gives `Malformed`; inside READY that loses the whole READY, so the session never becomes ready. The fork's types say these are absent-or-present, never null, so not blocking; worth a follow-up to make the gateway types as lenient as the models. - **minor — `MessageUpdate.channel_id` is required** (`gateway/events.rs`): the fork's `MessageUpdatePayload` declares `channel_id?: string`. An update without it is dropped as `Malformed` (logged, session continues). - **minor — `ClientProperties` differs from the fork's `GatewaySocketProperties`** (`gateway/identify.rs`): it follows the plan (has `system_locale`, lacks the fork's required `user_agent`). Already flagged by the implementer; decide before Task 7 sends a real IDENTIFY. ### Merge order The branch contains a merge of `task/3-proto-rest-models` (7f384d7), so this PR's diff shows Task 3's files too. Merge #35 first; if Task 3 changes in review, this branch needs that merged in again before it lands. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Merge origin/foundation into task/4-proto-gateway-events
All checks were successful
ci / Windows (x64) (push) Successful in 15s
ci / Windows (x64) (pull_request) Successful in 15s
ci / Linux (x86_64) (push) Successful in 50s
ci / Linux (x86_64) (pull_request) Successful in 48s
e9f2a4ae39
Refs #4

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Merge origin/foundation into task/4-proto-gateway-events
All checks were successful
ci / Windows (x64) (push) Successful in 31s
ci / Linux (x86_64) (push) Successful in 1m5s
ci / Windows (x64) (pull_request) Successful in 33s
ci / Linux (x86_64) (pull_request) Successful in 1m4s
f19070cff7
README conflict: both sides added a section; kept both.

Refs #4

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
charles merged commit 9ffe99fa98 into foundation 2026-11-11 09:18:59 +00:00
Sign in to join this conversation.
No description provided.