Task 4: fluxer-proto gateway envelope, opcodes, events (#4) #36
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "task/4-proto-gateway-events"
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_proto::gateway(issue #4, plan Task 4):Envelope { op, d, s, t }with buildersheartbeat,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).DebugofIdentify/Resumeredacts the token.ReadyPayload,GuildReadyData(guild object nested underproperties).GatewayEventwith the typed variants of the plan andUnknown { name, payload };GatewayEvent::from_dispatch(t, d) -> Result<GatewayEvent, ProtoError>;ProtoError::Malformed { t, source }.DISPATCH_NAMES: [&str; 84]from the fork'sEventRouter.ts, plusTYPED_DISPATCH_NAMESandUNTYPED_IN_FOUNDATION.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 (commitbc7cf35), 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_classifiedchecks the lists against each other and against whatfrom_dispatchactually returns for each name.cargo xtask ciis green locally.Deviations from the plan (reviewer: please look at these)
task/3-proto-rest-models(PR #35, at7f384d7). The gateway payloads are made of Task 3's models (Message,Guild,Channel, ...), which are not onfoundationyet 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 arecrates/fluxer-proto/src/lib.rs(module + re-exports) andcrates/fluxer-proto/README.md.GuildReadyData.propertiesisOption<Guild>, notGuild. The gateway sends an unavailable guild inREADY.guildsas{"id": "...", "unavailable": true}with nothing else (fluxer_gateway/src/session/session_ready_dispatch.erl:197, andGatewayReady.ts:131skips them). A requiredpropertieswould make one unavailable guild fail the wholeREADY.channels/roles/membersdefault to empty,member_countto 0. Task 9 has to handleNone.RESUMEDandREAD_STATE_UPDATEare typed but are not among the 84 names: the fork handlesRESUMEDin the socket, not the router, and noREAD_STATE_UPDATEdispatch exists in the fork (read markers move withMESSAGE_ACK). TheReadStateUpdate(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 inUNTYPED_IN_FOUNDATION.Ready(Box<ReadyPayload>),MessageCreate(Box<Message>),GuildCreate(Box<GuildReadyData>),Channel*,GuildUpdate,PresenceUpdate,UserUpdate,MessageUpdate) to keep the enum small.ClientPropertiesfollows the plan's field list. The fork'sGatewaySocketPropertiesalso hasuser_agentand has nosystem_locale; the gateway only readspropertiesas a map, so this was left as planned.Envelopealways writesd(nullwhenNone), as the Electron client does for the first heartbeat;s/tare omitted when unset.Closes #4
🤖 Generated with Claude Code
Independent review — Task 4 (proto-gateway-events), head
425f13cVerdict: APPROVE — 0 blocking, 4 minor. Local
cargo xtask ciin a clean review worktree: green (fmt, clippy, deny, tests; screenshot step skipped as configured). Remote runners not checked (integrator's job).What I verified
crates/fluxer-proto/tests/gateway.rsand 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 whatfrom_dispatchactually does).DISPATCH_NAMESis identical, in order, to the 84registry.set(...)names inEventRouter.ts; the 18 opcodes and 12 close codes matchGatewayConstants.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.fixtures/rest/login_ok.jsonfrom Task 3);Identify/ResumeDebugredact the token. Nothing in the gateway module can panic on server data: I probed nulls, floats, missing members and wrong types and gotErr(Malformed)every time.arbitrary_dispatch_never_panicsproptest.fluxer_gateway/src/session/session_ready.erlbuild_unavailable_stateemits exactly{id, unavailable: true}(plusunavailable_hidden), so a requiredpropertieswould fail the whole READY.Findings
gateway/events.rs,gateway/ready.rs):GuildReadyData.propertiesisOption<Guild>(Task 9 must handleNone);Ready,MessageCreate,MessageUpdate,Channel*,GuildCreate,GuildUpdate,PresenceUpdate,UserUpdateare boxed, andGuildMemberAdd/Update.memberisBox<GuildMember>;ReadStateUpdatecarries aReadState. Tasks 7-11 pattern-match on these; the plan's Interfaces block should be updated to the shipped shapes before they start.nullis rejected where absence is accepted (gateway/ready.rs,gateway/events.rs):#[serde(default)]without thenull_to_defaulthelper Task 3's models use.{"channels": null}or{"member_count": null}in one guild snapshot, or{"unavailable": null}in GUILD_DELETE, givesMalformed; 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.MessageUpdate.channel_idis required (gateway/events.rs): the fork'sMessageUpdatePayloaddeclareschannel_id?: string. An update without it is dropped asMalformed(logged, session continues).ClientPropertiesdiffers from the fork'sGatewaySocketProperties(gateway/identify.rs): it follows the plan (hassystem_locale, lacks the fork's requireduser_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