Voice 7: fluxer-core::voice connection machine and ports (#68) #110

Manually merged
charles merged 0 commits from voice-7-core-voice-connection into voice 2026-11-11 19:59:25 +00:00
Owner

What this builds

Voice plan Task 7: this client's own voice connection in fluxer-core, and the ports the voice session and the audio engine are driven through.

  • Ports (voice::port, spec §5.3): VoiceCommand, VoiceEvent, AudioCommand, AudioEvent with exactly the variants of the spec, plus TrackSource, DisconnectReason, PlaybackSource, ClipRef, ClipTag, Chime, CaptureConfig, AudioDevices, DeviceId. Effect::{Voice, Audio} and CoreEvent::{Voice, Audio} carry them. VoiceCommand::Connect holds the token and the E2EE key as SecretStrings; a test checks that neither shows in Debug.
  • Connection machine (voice::connection): VoiceConnection::{Idle, AwaitingServer, Connecting, Connected, Reconnecting, Failed} and VoiceFailure::{Timeout, Gateway(GatewayErrorCode), Room(String), E2eeRequired}. Join (op 4 without connection id, 15 s timeout, Connect on VOICE_SERVER_UPDATE), leave (Disconnect, then op 4 with a null channel), move (same connection id), kick and moderator move (own VOICE_STATE_UPDATE), op 4 re-sent after READY/RESUMED, a fresh VOICE_SERVER_UPDATE replacing the room without leaving, room loss and connect failure.
  • Local state (voice::local): LocalVoiceState { self_mute, self_deaf }, UserAction::{JoinVoice, LeaveVoice, RetryVoice, DismissVoiceError, ToggleSelfMute, ToggleSelfDeaf}, effective_mute(&App), effective_deaf(&App). Deafening mutes, undeafening restores the mute state from before, unmuting while deafened undeafens (the fork's LocalVoiceStateMachine.ts). The microphone track follows effective mute through SetMicrophoneMuted, sent only on change.
  • Persistence: LocalSettings::voice, saved through PersistOp::SaveSettings on each toggle; a settings file without the section loads as not muted.

How it was tested

crates/fluxer-core/tests/voice_connection.rs, written first and committed failing (eab2d31): the twelve tests the plan names, the proptest any_event_order_never_panics (random walks over user actions, dispatches, room events, timers, gateway errors and logout, checking that a room or a capture never outlives the connection and that capture is never started twice; also run once with 4000 cases), and four more (unusable_endpoint_fails_the_join, local_state_is_saved_and_loaded, logout_leaves_the_room, events_of_later_tasks_are_accepted). crates/fluxer-platform/tests/settings.rs gains a test for a settings file from before voice. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally.

Deviations from the plan

  • Other crates touched. fluxer-platform (settings.rs, its test and README): the [voice] section, without which the new setting would never reach the file. apps/fluxer/src/runtime.rs: one match arm that drops Effect::Voice / Effect::Audio with a debug line, so the workspace compiles until Voice 14. In fluxer-core, session.rs and messages.rs each gained the new CoreEvent variants in an exhaustive match.
  • CoreEvent::GatewayError(GatewayError) is new and not in the plan: op 12 had no way into the store. Nothing sends it yet, because fluxer-gateway only logs the frame (#108). Until that lands, a refused join shows as a timeout after 15 s.
  • Connected.since is Option<Timestamp> and always None. The store has no clock and VoiceEvent::Connected carries no time (#109). Voice 17's duration display depends on it.
  • AwaitingServer has a fourth field, moving: Option<MovingFrom>. During a move the old room stays up, and a move the server refuses or never answers returns to Connected in the old channel instead of dropping the call. The refusal is only logged; the UI gets no error for it.
  • VoiceTarget { guild_id, channel_id } is the target the spec leaves untyped.
  • Shapes the spec only names, chosen here and open to the tasks that consume them: DisconnectReason::{ClientInitiated, DuplicateIdentity, ParticipantRemoved, RoomDeleted, ServerShutdown, ConnectionLost, Other(String)}, PlaybackSource::{Participant(identity), Clip(ClipTag)}, ClipRef { key, content_type }, ClipTag(u64), DeviceId(String) with "default", AudioDevices { inputs, outputs } of AudioDevice { id, name, is_default }, CaptureConfig { denoise, gate, auto_gain, echo_cancellation, stereo, input_volume_percent } (mirrors fluxer_audio::ChainConfig without depending on it).
  • Behaviour the spec does not settle:
    • A room that ends by itself (Disconnected with any reason but ClientInitiated, or ConnectFailed) goes to Failed and sends the op 4 leave form for the connection, so the server does not keep a ghost; "Try again" is a fresh join. There is no automatic rejoin beyond the SDK's own reconnection.
    • Leaving or timing out before the server answered sends no op 4: there is no connection id, and the fork's leave form with a null id in a guild is not something I could verify as safe.
    • Joining a channel of another guild (or a DM call) while connected is leave plus fresh join, not a move.
    • While connected, only the op 12 codes that say the connection is gone (VOICE_CONNECTION_NOT_FOUND, VOICE_USER_NOT_IN_VOICE, VOICE_PENDING_EXPIRED, VOICE_NONCE_MISMATCH) fail it; others are ignored.
    • GUILD_DELETE of the connection's guild ends the connection.
  • Emitted here although later tasks own the area: AudioCommand::StartCapture(CaptureConfig::default()) on Connected and StopCapture when the connection ends (Voice 9 replaces the default with capture_config(&App)), and the mute, unmute, deafen, undeafen and disconnect chimes (Voice 8 adds join and leave). The mute and deafen chimes play whether or not the client is in voice, as in the original.

Notes for the reviewer

  • The remote branch is voice-7-core-voice-connection: voice/7-... cannot exist on the remote next to the voice branch (same as Voice 1 to 6). The local branch keeps the plan's name.
  • Room events carry no attempt id, so a late ConnectFailed from an abandoned attempt would fail the next one if it arrives while that one is Connecting. Worth keeping in mind for Voice 12.

Stacked on: voice-6-core-voice-states

Closes #68

🤖 Generated with Claude Code

## What this builds Voice plan Task 7: this client's own voice connection in `fluxer-core`, and the ports the voice session and the audio engine are driven through. - **Ports** (`voice::port`, spec §5.3): `VoiceCommand`, `VoiceEvent`, `AudioCommand`, `AudioEvent` with exactly the variants of the spec, plus `TrackSource`, `DisconnectReason`, `PlaybackSource`, `ClipRef`, `ClipTag`, `Chime`, `CaptureConfig`, `AudioDevices`, `DeviceId`. `Effect::{Voice, Audio}` and `CoreEvent::{Voice, Audio}` carry them. `VoiceCommand::Connect` holds the token and the E2EE key as `SecretString`s; a test checks that neither shows in `Debug`. - **Connection machine** (`voice::connection`): `VoiceConnection::{Idle, AwaitingServer, Connecting, Connected, Reconnecting, Failed}` and `VoiceFailure::{Timeout, Gateway(GatewayErrorCode), Room(String), E2eeRequired}`. Join (op 4 without connection id, 15 s timeout, `Connect` on `VOICE_SERVER_UPDATE`), leave (`Disconnect`, then op 4 with a null channel), move (same connection id), kick and moderator move (own `VOICE_STATE_UPDATE`), op 4 re-sent after `READY`/`RESUMED`, a fresh `VOICE_SERVER_UPDATE` replacing the room without leaving, room loss and connect failure. - **Local state** (`voice::local`): `LocalVoiceState { self_mute, self_deaf }`, `UserAction::{JoinVoice, LeaveVoice, RetryVoice, DismissVoiceError, ToggleSelfMute, ToggleSelfDeaf}`, `effective_mute(&App)`, `effective_deaf(&App)`. Deafening mutes, undeafening restores the mute state from before, unmuting while deafened undeafens (the fork's `LocalVoiceStateMachine.ts`). The microphone track follows effective mute through `SetMicrophoneMuted`, sent only on change. - **Persistence**: `LocalSettings::voice`, saved through `PersistOp::SaveSettings` on each toggle; a settings file without the section loads as not muted. ## How it was tested `crates/fluxer-core/tests/voice_connection.rs`, written first and committed failing (`eab2d31`): the twelve tests the plan names, the proptest `any_event_order_never_panics` (random walks over user actions, dispatches, room events, timers, gateway errors and logout, checking that a room or a capture never outlives the connection and that capture is never started twice; also run once with 4000 cases), and four more (`unusable_endpoint_fails_the_join`, `local_state_is_saved_and_loaded`, `logout_leaves_the_room`, `events_of_later_tasks_are_accepted`). `crates/fluxer-platform/tests/settings.rs` gains a test for a settings file from before voice. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. ## Deviations from the plan - **Other crates touched.** `fluxer-platform` (`settings.rs`, its test and README): the `[voice]` section, without which the new setting would never reach the file. `apps/fluxer/src/runtime.rs`: one match arm that drops `Effect::Voice` / `Effect::Audio` with a debug line, so the workspace compiles until Voice 14. In `fluxer-core`, `session.rs` and `messages.rs` each gained the new `CoreEvent` variants in an exhaustive match. - **`CoreEvent::GatewayError(GatewayError)`** is new and not in the plan: op 12 had no way into the store. Nothing sends it yet, because `fluxer-gateway` only logs the frame (#108). Until that lands, a refused join shows as a timeout after 15 s. - **`Connected.since` is `Option<Timestamp>` and always `None`.** The store has no clock and `VoiceEvent::Connected` carries no time (#109). Voice 17's duration display depends on it. - **`AwaitingServer` has a fourth field, `moving: Option<MovingFrom>`.** During a move the old room stays up, and a move the server refuses or never answers returns to `Connected` in the old channel instead of dropping the call. The refusal is only logged; the UI gets no error for it. - **`VoiceTarget { guild_id, channel_id }`** is the `target` the spec leaves untyped. - **Shapes the spec only names**, chosen here and open to the tasks that consume them: `DisconnectReason::{ClientInitiated, DuplicateIdentity, ParticipantRemoved, RoomDeleted, ServerShutdown, ConnectionLost, Other(String)}`, `PlaybackSource::{Participant(identity), Clip(ClipTag)}`, `ClipRef { key, content_type }`, `ClipTag(u64)`, `DeviceId(String)` with `"default"`, `AudioDevices { inputs, outputs }` of `AudioDevice { id, name, is_default }`, `CaptureConfig { denoise, gate, auto_gain, echo_cancellation, stereo, input_volume_percent }` (mirrors `fluxer_audio::ChainConfig` without depending on it). - **Behaviour the spec does not settle:** - A room that ends by itself (`Disconnected` with any reason but `ClientInitiated`, or `ConnectFailed`) goes to `Failed` and sends the op 4 leave form for the connection, so the server does not keep a ghost; "Try again" is a fresh join. There is no automatic rejoin beyond the SDK's own reconnection. - Leaving or timing out before the server answered sends no op 4: there is no connection id, and the fork's leave form with a null id in a guild is not something I could verify as safe. - Joining a channel of another guild (or a DM call) while connected is leave plus fresh join, not a move. - While connected, only the op 12 codes that say the connection is gone (`VOICE_CONNECTION_NOT_FOUND`, `VOICE_USER_NOT_IN_VOICE`, `VOICE_PENDING_EXPIRED`, `VOICE_NONCE_MISMATCH`) fail it; others are ignored. - `GUILD_DELETE` of the connection's guild ends the connection. - **Emitted here although later tasks own the area:** `AudioCommand::StartCapture(CaptureConfig::default())` on `Connected` and `StopCapture` when the connection ends (Voice 9 replaces the default with `capture_config(&App)`), and the mute, unmute, deafen, undeafen and disconnect chimes (Voice 8 adds join and leave). The mute and deafen chimes play whether or not the client is in voice, as in the original. ## Notes for the reviewer - The remote branch is `voice-7-core-voice-connection`: `voice/7-...` cannot exist on the remote next to the `voice` branch (same as Voice 1 to 6). The local branch keeps the plan's name. - Room events carry no attempt id, so a late `ConnectFailed` from an abandoned attempt would fail the next one if it arrives while that one is `Connecting`. Worth keeping in mind for Voice 12. Stacked on: voice-6-core-voice-states Closes #68 🤖 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>
Stubs for the voice module and the selectors so the tests compile; they fail.

Refs #67

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): voice states and sidebar selectors
All checks were successful
ci / Linux (x86_64) (push) Successful in 7m41s
ci / Windows (x64) (push) Successful in 8m12s
ci / Linux (x86_64) (pull_request) Successful in 7m38s
ci / Windows (x64) (pull_request) Successful in 8m24s
d245b6f466
App.voice.states keeps one VoiceState per connection, indexed by channel and
user, fed by READY, GUILD_CREATE, GUILD_DELETE and VOICE_STATE_UPDATE.
voice_channel_participants and voice_channel_user_count derive the sidebar rows.

Refs #67

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

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
feat(core): voice connection state machine and ports
Some checks failed
ci / Linux (x86_64) (push) Has been cancelled
ci / Windows (x64) (push) Has been cancelled
ci / Linux (x86_64) (pull_request) Has been cancelled
ci / Windows (x64) (pull_request) Has been cancelled
3b33ca2c55
The ports of Voice spec §5.3 (voice::port), Effect::{Voice, Audio},
CoreEvent::{Voice, Audio, GatewayError}, the connection machine
(VoiceConnection, VoiceFailure) with join, leave, move, kick, resume and
token refresh, the user's mute and deafen switches (LocalVoiceState) saved
in a new [voice] section of the local settings, and effective_mute /
effective_deaf.

fluxer-platform reads and writes the new settings section; apps/fluxer
drops the two new effects until the voice runtime (Voice 14) exists.

Refs #68

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

Independent review: Voice 7 (core voice connection), head 3b33ca2

Reviewed d245b6f..3b33ca2 cold, in its own worktree.

Checks

  1. Tests the plan names: all 12 plus the proptest any_event_order_never_panics exist in crates/fluxer-core/tests/voice_connection.rs and assert the spec's values: 15 s timer (JOIN_TIMEOUT and the scheduled after), the fork's join form with connection_id: null, the leave form (channel_id: null, self_mute/self_deaf: true, connection id) sent after VoiceCommand::Disconnect, the move with the same connection id, kick without op 4 and with the disconnect chime, op 4 re-sent on RESUMED and READY, a refreshed VOICE_SERVER_UPDATE giving exactly one Connect and no Disconnect/StopCapture, undeafen restoring the earlier mute state, server mute/suppress/deaf keeping the track muted, Reconnecting then Failed, and another connection's server update ignored.
  2. Interfaces: every name of the Interfaces block exists as written (VoiceCommand, VoiceEvent, AudioCommand, AudioEvent with the spec §5.3 variants and field names, TrackSource, DisconnectReason, PlaybackSource, ClipRef, ClipTag, Chime, CaptureConfig, AudioDevices, DeviceId, Effect::{Voice, Audio}, CoreEvent::{Voice, Audio}, VoiceFailure with its four variants, the six UserActions, LocalVoiceState { self_mute, self_deaf }, effective_mute(&App), effective_deaf(&App)). Two shape differences from spec §5.1 are listed below.
  3. Invariants: no Cargo.toml/lock change, so fluxer-core gains no dependency; no unwrap/expect/indexing in the new source; the token and E2EE key stay SecretString and a test checks they do not show in Debug; the endpoint parse error is logged without the URL; no fixture was added.
  4. Review Focus: no item belongs to this task (1 is Voice 8/12, 7 is Voice 14).
  5. cargo xtask ci in the review worktree: all steps passed (screenshot step skipped, FLUXER_SCREENSHOT_TESTS not set for this run).

Findings

  • minor voice/connection.rs — VoiceConnection differs from spec §5.1 in two places: Connected.since is Option<Timestamp> and always None (#109), and AwaitingServer has a fourth field moving. Both are declared in the PR. Voice 17 must handle None until #109 lands, and consumers have to match AwaitingServer { .. }.
  • minor voice/connection.rs (on_timer, on_server_update) — after a 15 s timeout, or a leave before the server answered, a late VOICE_SERVER_UPDATE is dropped in Idle/Failed and the connection the server created for it is never given back. The original sends the leave form after the timeout (VoiceEngineV2AppConnectionHostAdapter.ts:1095). Until the server expires the pending connection, the user can show in the channel without being in it. Suggest answering such an update with VoiceStateUpdateParams::leave(guild_id, connection_id); worth a follow-up issue.
  • minor voice/connection.rs (on_gateway_error) — any op 12 while AwaitingServer fails the join, including codes that are not about voice. Nothing emits CoreEvent::GatewayError yet (#108); when it does, filter on voice codes or the join can fail because of an unrelated request.
  • minor voice/connection.rs (on_gateway, GuildDelete) — the call is ended with no op 4 also when unavailable: true (an outage, the user is still a member). If only the guild's gateway side restarted, the server may keep the connection while the client dropped it. Not checked against the original.
  • minor voice/connection.rs (on_room) — room events carry no attempt id, so a late ConnectFailed/Disconnected from a replaced or abandoned room can fail the next attempt while it is Connecting. Declared in the PR; Voice 12 has to guarantee that a replaced room reports nothing.
  • minor voice/local.rs — unmute_on_undeafen is not persisted, so after a restart while deafened, undeafening leaves the microphone muted even if it was unmuted before deafening.
  • minor scope — the task touches fluxer-platform and apps/fluxer besides fluxer-core. Both are needed (the [voice] section, an exhaustive match) and declared; the platform change has its own test.

Verdict: approved — no blocking findings, local ci green.

## Independent review: Voice 7 (core voice connection), head `3b33ca2` Reviewed `d245b6f..3b33ca2` cold, in its own worktree. **Checks** 1. **Tests the plan names**: all 12 plus the proptest `any_event_order_never_panics` exist in `crates/fluxer-core/tests/voice_connection.rs` and assert the spec's values: 15 s timer (`JOIN_TIMEOUT` and the scheduled `after`), the fork's join form with `connection_id: null`, the leave form (`channel_id: null`, `self_mute/self_deaf: true`, connection id) sent after `VoiceCommand::Disconnect`, the move with the same connection id, kick without op 4 and with the disconnect chime, op 4 re-sent on `RESUMED` and `READY`, a refreshed `VOICE_SERVER_UPDATE` giving exactly one `Connect` and no `Disconnect`/`StopCapture`, undeafen restoring the earlier mute state, server mute/suppress/deaf keeping the track muted, `Reconnecting` then `Failed`, and another connection's server update ignored. 2. **Interfaces**: every name of the Interfaces block exists as written (`VoiceCommand`, `VoiceEvent`, `AudioCommand`, `AudioEvent` with the spec §5.3 variants and field names, `TrackSource`, `DisconnectReason`, `PlaybackSource`, `ClipRef`, `ClipTag`, `Chime`, `CaptureConfig`, `AudioDevices`, `DeviceId`, `Effect::{Voice, Audio}`, `CoreEvent::{Voice, Audio}`, `VoiceFailure` with its four variants, the six `UserAction`s, `LocalVoiceState { self_mute, self_deaf }`, `effective_mute(&App)`, `effective_deaf(&App)`). Two shape differences from spec §5.1 are listed below. 3. **Invariants**: no `Cargo.toml`/lock change, so `fluxer-core` gains no dependency; no `unwrap`/`expect`/indexing in the new source; the token and E2EE key stay `SecretString` and a test checks they do not show in `Debug`; the endpoint parse error is logged without the URL; no fixture was added. 4. **Review Focus**: no item belongs to this task (1 is Voice 8/12, 7 is Voice 14). 5. **`cargo xtask ci`** in the review worktree: all steps passed (screenshot step skipped, `FLUXER_SCREENSHOT_TESTS` not set for this run). **Findings** - **minor** `voice/connection.rs` — `VoiceConnection` differs from spec §5.1 in two places: `Connected.since` is `Option<Timestamp>` and always `None` (#109), and `AwaitingServer` has a fourth field `moving`. Both are declared in the PR. Voice 17 must handle `None` until #109 lands, and consumers have to match `AwaitingServer { .. }`. - **minor** `voice/connection.rs` (`on_timer`, `on_server_update`) — after a 15 s timeout, or a leave before the server answered, a late `VOICE_SERVER_UPDATE` is dropped in `Idle`/`Failed` and the connection the server created for it is never given back. The original sends the leave form after the timeout (`VoiceEngineV2AppConnectionHostAdapter.ts:1095`). Until the server expires the pending connection, the user can show in the channel without being in it. Suggest answering such an update with `VoiceStateUpdateParams::leave(guild_id, connection_id)`; worth a follow-up issue. - **minor** `voice/connection.rs` (`on_gateway_error`) — any op 12 while `AwaitingServer` fails the join, including codes that are not about voice. Nothing emits `CoreEvent::GatewayError` yet (#108); when it does, filter on voice codes or the join can fail because of an unrelated request. - **minor** `voice/connection.rs` (`on_gateway`, `GuildDelete`) — the call is ended with no op 4 also when `unavailable: true` (an outage, the user is still a member). If only the guild's gateway side restarted, the server may keep the connection while the client dropped it. Not checked against the original. - **minor** `voice/connection.rs` (`on_room`) — room events carry no attempt id, so a late `ConnectFailed`/`Disconnected` from a replaced or abandoned room can fail the next attempt while it is `Connecting`. Declared in the PR; Voice 12 has to guarantee that a replaced room reports nothing. - **minor** `voice/local.rs` — `unmute_on_undeafen` is not persisted, so after a restart while deafened, undeafening leaves the microphone muted even if it was unmuted before deafening. - **minor** scope — the task touches `fluxer-platform` and `apps/fluxer` besides `fluxer-core`. Both are needed (the `[voice]` section, an exhaustive match) and declared; the platform change has its own test. **Verdict: approved** — no blocking findings, local ci green.
Merge remote-tracking branch 'origin/voice' into voice/7-core-voice-connection
All checks were successful
ci / Linux (x86_64) (push) Successful in 7m37s
ci / Windows (x64) (push) Successful in 8m56s
ci / Linux (x86_64) (pull_request) Successful in 7m50s
ci / Windows (x64) (pull_request) Successful in 8m51s
67f0d8f32f
charles manually merged commit b6c6251df2 into voice 2026-11-11 19:59:25 +00:00
Sign in to join this conversation.
No description provided.