Voice 1: fluxer-proto voice gateway types (#62) #102

Merged
charles merged 1 commit from voice-1-proto-voice-gateway into voice 2026-11-11 18:30:50 +00:00
Owner

What this builds

The gateway half of voice in fluxer-proto (spec §4, facts §1), in the new module gateway::voice:

  • VoiceStateUpdateParams — d of op 4, with join(..), leave(..) and into_envelope(). Every member is written (connection_id: null on a fresh join), p2p is never sent.
  • VoiceState — VOICE_STATE_UPDATE and the entries of voice_states. Only user_id and connection_id are required; absent and null members read the same; an unreadable member is dropped, not the state.
  • VoiceServerUpdate::{Sfu { token, endpoint, connection_id, guild_id, channel_id, e2ee_key }, P2p} — token/e2ee_key are SecretString, there is no Serialize, and Debug prints <redacted> (also through GatewayEvent's Debug and through ProtoError).
  • CallData (aliases CallCreate, CallUpdate), CallDelete, CallVoiceState.
  • GatewayErrorCode and GatewayError { code, message } (d of op 12).
  • GatewayEvent::{VoiceStateUpdate, VoiceServerUpdate, CallCreate, CallUpdate, CallDelete}; the five names moved from UNTYPED_IN_FOUNDATION to TYPED_DISPATCH_NAMES.
  • GuildReadyData::voice_states is now Vec<VoiceState> (it serves both READY.guilds and GUILD_CREATE). An entry that does not parse is skipped so one bad voice state cannot fail a READY.
  • Fixtures fixtures/gateway/voice_*.json (eight frames), README section "Voice".

How it was tested

crates/fluxer-proto/tests/voice.rs, written first and seen failing: op4_join_serialises_like_the_fork, op4_leave_form, voice_state_minimal_and_full_fixture, voice_server_update_sfu_and_p2p, voice_server_update_debug_hides_secrets, call_events_roundtrip, ready_with_voice_states, unknown_voice_error_code_is_tolerated. The existing all_84_dispatch_names_are_classified covers the moved names. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci passes locally.

Deviations from the plan

  1. Branch name. The plan's voice/1-proto-voice-gateway cannot be pushed: the remote has the branch voice, and git refuses voice/<anything> beside it (refname conflict). This branch is voice-1-proto-voice-gateway. Every later Voice task will hit the same thing.
  2. GatewayErrorCode::Unknown(String), not Unknown(u32). On the wire the codes are strings ("VOICE_CHANNEL_FULL"; GatewayConstants.ts:49-75, gateway_handler_dispatch.erl:126-131), so a u32 cannot hold an unknown one. The enum is therefore Clone but not Copy. A numeric code is still accepted and kept as its digits.
  3. Fixtures are in fixtures/gateway/ at the repo root, not crates/fluxer-proto/fixtures/gateway/: that is where the merged tests and the devserver read gateway fixtures from.
  4. ClientProperties, not IdentifyProperties. The merged type already has pub e2ee_capable: bool defaulting to false; only its documentation changed.
  5. crates/fluxer-proto/Cargo.toml (+ Cargo.lock), outside the Files list: secrecy.workspace = true, needed for SecretString. It is already a workspace dependency (used by fluxer-core and fluxer-api); cargo deny is unchanged. Also crates/fluxer-proto/README.md, per CLAUDE.md.
  6. ready_with_voice_states builds its payload from the existing ready.json / guild_create.json plus the voice-state fixtures instead of adding a second full READY fixture.
  7. connection_id of VoiceState is required (the server's default map allows null, but a state without one cannot be keyed); such a dispatch is ProtoError::Malformed and such a list entry is skipped.
  8. Additions beyond the Interfaces block: VoiceStateUpdateParams::{join, leave}, VoiceServerUpdate::connection_id(), GatewayError, GatewayErrorCode::as_str().

Closes #62

🤖 Generated with Claude Code

## What this builds The gateway half of voice in `fluxer-proto` (spec §4, facts §1), in the new module `gateway::voice`: - `VoiceStateUpdateParams` — `d` of op 4, with `join(..)`, `leave(..)` and `into_envelope()`. Every member is written (`connection_id: null` on a fresh join), `p2p` is never sent. - `VoiceState` — `VOICE_STATE_UPDATE` and the entries of `voice_states`. Only `user_id` and `connection_id` are required; absent and `null` members read the same; an unreadable `member` is dropped, not the state. - `VoiceServerUpdate::{Sfu { token, endpoint, connection_id, guild_id, channel_id, e2ee_key }, P2p}` — `token`/`e2ee_key` are `SecretString`, there is no `Serialize`, and `Debug` prints `<redacted>` (also through `GatewayEvent`'s `Debug` and through `ProtoError`). - `CallData` (aliases `CallCreate`, `CallUpdate`), `CallDelete`, `CallVoiceState`. - `GatewayErrorCode` and `GatewayError { code, message }` (`d` of op 12). - `GatewayEvent::{VoiceStateUpdate, VoiceServerUpdate, CallCreate, CallUpdate, CallDelete}`; the five names moved from `UNTYPED_IN_FOUNDATION` to `TYPED_DISPATCH_NAMES`. - `GuildReadyData::voice_states` is now `Vec<VoiceState>` (it serves both `READY.guilds` and `GUILD_CREATE`). An entry that does not parse is skipped so one bad voice state cannot fail a `READY`. - Fixtures `fixtures/gateway/voice_*.json` (eight frames), README section "Voice". ## How it was tested `crates/fluxer-proto/tests/voice.rs`, written first and seen failing: `op4_join_serialises_like_the_fork`, `op4_leave_form`, `voice_state_minimal_and_full_fixture`, `voice_server_update_sfu_and_p2p`, `voice_server_update_debug_hides_secrets`, `call_events_roundtrip`, `ready_with_voice_states`, `unknown_voice_error_code_is_tolerated`. The existing `all_84_dispatch_names_are_classified` covers the moved names. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` passes locally. ## Deviations from the plan 1. **Branch name.** The plan's `voice/1-proto-voice-gateway` cannot be pushed: the remote has the branch `voice`, and git refuses `voice/<anything>` beside it (`refname conflict`). This branch is `voice-1-proto-voice-gateway`. Every later Voice task will hit the same thing. 2. **`GatewayErrorCode::Unknown(String)`, not `Unknown(u32)`.** On the wire the codes are strings (`"VOICE_CHANNEL_FULL"`; `GatewayConstants.ts:49-75`, `gateway_handler_dispatch.erl:126-131`), so a `u32` cannot hold an unknown one. The enum is therefore `Clone` but not `Copy`. A numeric code is still accepted and kept as its digits. 3. **Fixtures are in `fixtures/gateway/`** at the repo root, not `crates/fluxer-proto/fixtures/gateway/`: that is where the merged tests and the devserver read gateway fixtures from. 4. **`ClientProperties`, not `IdentifyProperties`.** The merged type already has `pub e2ee_capable: bool` defaulting to `false`; only its documentation changed. 5. **`crates/fluxer-proto/Cargo.toml` (+ `Cargo.lock`)**, outside the Files list: `secrecy.workspace = true`, needed for `SecretString`. It is already a workspace dependency (used by `fluxer-core` and `fluxer-api`); `cargo deny` is unchanged. Also `crates/fluxer-proto/README.md`, per CLAUDE.md. 6. `ready_with_voice_states` builds its payload from the existing `ready.json` / `guild_create.json` plus the voice-state fixtures instead of adding a second full `READY` fixture. 7. `connection_id` of `VoiceState` is required (the server's default map allows `null`, but a state without one cannot be keyed); such a dispatch is `ProtoError::Malformed` and such a list entry is skipped. 8. Additions beyond the Interfaces block: `VoiceStateUpdateParams::{join, leave}`, `VoiceServerUpdate::connection_id()`, `GatewayError`, `GatewayErrorCode::as_str()`. Closes #62 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(proto): voice gateway types
All checks were successful
ci / Linux (x86_64) (push) Successful in 7m25s
ci / Windows (x64) (push) Successful in 8m0s
ci / Linux (x86_64) (pull_request) Successful in 7m29s
ci / Windows (x64) (pull_request) Successful in 8m4s
2be0cff6f0
Op 4 payload (VoiceStateUpdateParams), VoiceState, VoiceServerUpdate
(SFU and P2P forms, secrets redacted), the DM-call dispatches, the op 12
error payload with its string codes, and typed voice_states on the guild
snapshots of READY and GUILD_CREATE. Fixtures: fixtures/gateway/voice_*.json.

Refs #62

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

Independent review: Voice 1 (proto voice gateway types), commit 2be0cff

Reviewed 8b37da4..origin/voice-1-proto-voice-gateway cold, against the plan's Task 1, facts §1 and the fork (GatewayConstants.ts, GatewaySocket.ts, gateway_errors.erl, voice_state_utils.erl).

Local gate: cargo xtask ci in a fresh worktree with its own target dir: all steps passed (fmt, clippy, deny, core-isolation, parity, test; tests/voice.rs 8/8). The screenshot step was skipped because I ran it without FLUXER_SCREENSHOT_TESTS=1; this diff touches no UI.

Checked and fine

  • Tests: all eight tests named in Step 1 exist under those names and assert what the plan says. op4_join_serialises_like_the_fork compares the whole frame with facts §1's join form (connection_id: null, no p2p); op4_leave_form matches sendVoiceStateDisconnect; the Debug test also covers GatewayEvent's Debug and the ProtoError of a malformed payload.
  • Interfaces: VoiceStateUpdateParams (fields and into_envelope, op 4), VoiceState (guild_id: Option<Snowflake>, version: Option<u64>), VoiceServerUpdate::{Sfu {..}, P2p} with SecretString secrets, CallCreate/CallUpdate/CallData, CallDelete, CallVoiceState, the five GatewayEvent variants, voice_states: Vec<VoiceState> on GuildReadyData (serves both READY and GUILD_CREATE), e2ee_capable defaulting to false. All re-exported from fluxer_proto::gateway.
  • Invariants: no panic path on server data (no unwrap/index in the new code; malformed input is Err or a dropped list entry). VoiceServerUpdate has no Serialize and a redacting Debug. Fixture secrets are placeholders (fixture.livekit.jwt, fixture-shared-key), host is fluxer.example. secrecy was already a workspace dependency; deny is green.
  • Error codes against the fork: the 30 variants cover all 25 of GatewayErrorCodes plus the gateway-only ones in gateway_errors.erl; wire strings match.
  • Leniency of voice_states lists (the implementer asked): confirmed as the right call. One unreadable entry must not cost a READY, and it matches how properties: Option<Guild> already treats an unavailable guild.
  • No Review Focus item belongs to this task (item 7, secrets in logs / --record, is tested in Voice 14; this type's part of it is done).

Findings

  1. minor — GatewayErrorCode::Unknown(String) instead of the plan's Unknown(u32); the enum is Clone, not Copy. The deviation is correct: the fork sends codes as strings (GatewayConstants.ts:49-75, gateway_errors.erl), so Unknown(u32) could not hold one. Voice 7's VoiceFailure::Gateway(GatewayErrorCode) still compiles but cannot derive Copy; the plan's Task 1 Interfaces line should be corrected so Voice 7/23 build against the merged type.
  2. minor — dropped voice_states entries are silent. lenient_vec discards unreadable entries with no count or signal, so a server-side shape change would show up as people missing from voice with nothing in the log. The crate is pure and cannot log; worth a follow-up only if it ever bites (e.g. return the number dropped for Voice 6 to log).
  3. minor — plan paths and names differ from what landed (all justified by merged code being the source of truth): fixtures are in repo-root fixtures/gateway/voice_*.json, not crates/fluxer-proto/fixtures/; the type is ClientProperties, not IdentifyProperties; the branch is voice-1-proto-voice-gateway because the remote cannot hold voice/<x> beside a voice branch. Every later Voice task will hit the same branch-name conflict, so the plan's Global Constraints should say voice-N-<slug>.
  4. minor — VoiceState.connection_id is required, although the fork's default map spells it null. Every broadcast path I read sets it, and there is nothing to key a state on without it, so a Malformed (logged, skipped) dispatch is acceptable. Noting it so Voice 6 does not assume otherwise.

Verdict: APPROVE — 0 blocking, 4 minor; local ci green.

## Independent review: Voice 1 (proto voice gateway types), commit 2be0cff Reviewed `8b37da4..origin/voice-1-proto-voice-gateway` cold, against the plan's Task 1, facts §1 and the fork (`GatewayConstants.ts`, `GatewaySocket.ts`, `gateway_errors.erl`, `voice_state_utils.erl`). **Local gate:** `cargo xtask ci` in a fresh worktree with its own target dir: all steps passed (fmt, clippy, deny, core-isolation, parity, test; `tests/voice.rs` 8/8). The screenshot step was skipped because I ran it without `FLUXER_SCREENSHOT_TESTS=1`; this diff touches no UI. ### Checked and fine - **Tests:** all eight tests named in Step 1 exist under those names and assert what the plan says. `op4_join_serialises_like_the_fork` compares the whole frame with facts §1's join form (`connection_id: null`, no `p2p`); `op4_leave_form` matches `sendVoiceStateDisconnect`; the Debug test also covers `GatewayEvent`'s Debug and the `ProtoError` of a malformed payload. - **Interfaces:** `VoiceStateUpdateParams` (fields and `into_envelope`, op 4), `VoiceState` (`guild_id: Option<Snowflake>`, `version: Option<u64>`), `VoiceServerUpdate::{Sfu {..}, P2p}` with `SecretString` secrets, `CallCreate`/`CallUpdate`/`CallData`, `CallDelete`, `CallVoiceState`, the five `GatewayEvent` variants, `voice_states: Vec<VoiceState>` on `GuildReadyData` (serves both READY and GUILD_CREATE), `e2ee_capable` defaulting to `false`. All re-exported from `fluxer_proto::gateway`. - **Invariants:** no panic path on server data (no unwrap/index in the new code; malformed input is `Err` or a dropped list entry). `VoiceServerUpdate` has no `Serialize` and a redacting `Debug`. Fixture secrets are placeholders (`fixture.livekit.jwt`, `fixture-shared-key`), host is `fluxer.example`. `secrecy` was already a workspace dependency; deny is green. - **Error codes against the fork:** the 30 variants cover all 25 of `GatewayErrorCodes` plus the gateway-only ones in `gateway_errors.erl`; wire strings match. - **Leniency of `voice_states` lists** (the implementer asked): confirmed as the right call. One unreadable entry must not cost a READY, and it matches how `properties: Option<Guild>` already treats an unavailable guild. - No Review Focus item belongs to this task (item 7, secrets in logs / `--record`, is tested in Voice 14; this type's part of it is done). ### Findings 1. **minor — `GatewayErrorCode::Unknown(String)` instead of the plan's `Unknown(u32)`; the enum is `Clone`, not `Copy`.** The deviation is correct: the fork sends codes as strings (`GatewayConstants.ts:49-75`, `gateway_errors.erl`), so `Unknown(u32)` could not hold one. Voice 7's `VoiceFailure::Gateway(GatewayErrorCode)` still compiles but cannot derive `Copy`; the plan's Task 1 Interfaces line should be corrected so Voice 7/23 build against the merged type. 2. **minor — dropped `voice_states` entries are silent.** `lenient_vec` discards unreadable entries with no count or signal, so a server-side shape change would show up as people missing from voice with nothing in the log. The crate is pure and cannot log; worth a follow-up only if it ever bites (e.g. return the number dropped for Voice 6 to log). 3. **minor — plan paths and names differ from what landed** (all justified by merged code being the source of truth): fixtures are in repo-root `fixtures/gateway/voice_*.json`, not `crates/fluxer-proto/fixtures/`; the type is `ClientProperties`, not `IdentifyProperties`; the branch is `voice-1-proto-voice-gateway` because the remote cannot hold `voice/<x>` beside a `voice` branch. Every later Voice task will hit the same branch-name conflict, so the plan's Global Constraints should say `voice-N-<slug>`. 4. **minor — `VoiceState.connection_id` is required**, although the fork's default map spells it `null`. Every broadcast path I read sets it, and there is nothing to key a state on without it, so a `Malformed` (logged, skipped) dispatch is acceptable. Noting it so Voice 6 does not assume otherwise. **Verdict: APPROVE** — 0 blocking, 4 minor; local ci green.
charles merged commit 54a9f1e62c into voice 2026-11-11 18:30:50 +00:00
Sign in to join this conversation.
No description provided.