Voice 12: fluxer-voice crate — session state machine over a room trait (#73) #114

Manually merged
charles merged 0 commits from voice-12-voice-session into voice 2026-11-11 21:03:51 +00:00
Owner

What

New crate crates/fluxer-voice (Voice spec §7, plan Voice 12):

  • room.rs: trait Room (connect(url, token, RoomOptions { e2ee_key, max_bitrate }) returning the connection's mpsc::Receiver<RoomEvent>, disconnect, set_mic_muted, set_subscribed(identity, sid, bool), publish_data, push_mic(Frame10ms)), RoomEvent (incl. Audio { identity, sid, samples } and Rtt), Frame10ms, RoomError.
  • session.rs: VoiceSession::spawn<R: Room>(room, events) -> VoiceHandle; VoiceHandle::{send, push_microphone(&[i16], channels), remote_audio() -> mpsc::Receiver<RemoteAudio>}.
  • fake.rs (feature fake): FakeRoom + FakeRoomControl (scripted participants, tracks, tones, data, RTT, reconnects, connect failures and delays; records every call), tone_frame.

Rules (documented at the top of session.rs and in the README):

  • Idle: everything but Connect is dropped. Connecting: SetMicrophoneMuted / SetSubscribed are queued, PublishData is dropped, Disconnect cancels the attempt, another Connect replaces it.
  • SetSubscribed { identity, source } resolves to the publication; a wish for a track published later is applied when it appears, and is forgotten when the participant leaves.
  • Remote audio is passed on only for subscribed tracks. Unsubscribe calls the room (Review Focus 1: stop receiving) and gates frames at once even if the room call fails; a muted microphone is never fed to the room, even if the room could not be told.
  • Rtt every 2 s while connected, with the room's last measurement.
  • Disconnect is idempotent; a Connect while connected swaps rooms without Disconnected, keeping mic state and wished subscriptions (the core does not re-send them on a token refresh).
  • No URL, token, key or payload is logged.

Tests

crates/fluxer-voice/tests/session.rs, 23 tests on tokio's paused clock against FakeRoom: the eight named by the plan plus cancel/replace while connecting, queue-or-reject before connected, failed swap, per-source subscription, late-published track, mic gating, receiver replacement, and shutdown when the handle or the event reader is dropped. Seen failing against a stub session first. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green locally.

Deviations from the plan

  • Room::connect returns the event stream of that connection instead of the room having one stream for its lifetime: stale events of a replaced room cannot leak into the new one.
  • RoomEvent::Audio carries the track sid next to identity and samples (a Frame10ms), so the session can gate per track.
  • RoomOptions also has max_bitrate (Voice 13 reads it). VoiceCommand::Connect does not carry the channel bitrate, so the session always passes DEFAULT_MAX_BITRATE (64 kbit/s); wiring the real value needs a port change in fluxer-core.
  • Frame10ms is defined here rather than reusing fluxer_audio::Frame, so the crate does not depend on fluxer-audio.
  • Dev-dependency on itself with feature fake (so cargo test needs no flags) and tokio test-util for dev only; no new third-party crate. Cargo.lock gains only the fluxer-voice entry.

Stacked on: voice-7-core-voice-connection

Closes #73

🤖 Generated with Claude Code

## What New crate `crates/fluxer-voice` (Voice spec §7, plan Voice 12): - `room.rs`: `trait Room` (`connect(url, token, RoomOptions { e2ee_key, max_bitrate })` returning the connection's `mpsc::Receiver<RoomEvent>`, `disconnect`, `set_mic_muted`, `set_subscribed(identity, sid, bool)`, `publish_data`, `push_mic(Frame10ms)`), `RoomEvent` (incl. `Audio { identity, sid, samples }` and `Rtt`), `Frame10ms`, `RoomError`. - `session.rs`: `VoiceSession::spawn<R: Room>(room, events) -> VoiceHandle`; `VoiceHandle::{send, push_microphone(&[i16], channels), remote_audio() -> mpsc::Receiver<RemoteAudio>}`. - `fake.rs` (feature `fake`): `FakeRoom` + `FakeRoomControl` (scripted participants, tracks, tones, data, RTT, reconnects, connect failures and delays; records every call), `tone_frame`. Rules (documented at the top of `session.rs` and in the README): - Idle: everything but `Connect` is dropped. Connecting: `SetMicrophoneMuted` / `SetSubscribed` are queued, `PublishData` is dropped, `Disconnect` cancels the attempt, another `Connect` replaces it. - `SetSubscribed { identity, source }` resolves to the publication; a wish for a track published later is applied when it appears, and is forgotten when the participant leaves. - Remote audio is passed on only for subscribed tracks. Unsubscribe calls the room (Review Focus 1: stop *receiving*) and gates frames at once even if the room call fails; a muted microphone is never fed to the room, even if the room could not be told. - `Rtt` every 2 s while connected, with the room's last measurement. - `Disconnect` is idempotent; a `Connect` while connected swaps rooms without `Disconnected`, keeping mic state and wished subscriptions (the core does not re-send them on a token refresh). - No URL, token, key or payload is logged. ## Tests `crates/fluxer-voice/tests/session.rs`, 23 tests on tokio's paused clock against `FakeRoom`: the eight named by the plan plus cancel/replace while connecting, queue-or-reject before connected, failed swap, per-source subscription, late-published track, mic gating, receiver replacement, and shutdown when the handle or the event reader is dropped. Seen failing against a stub session first. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green locally. ## Deviations from the plan - `Room::connect` returns the event stream of that connection instead of the room having one stream for its lifetime: stale events of a replaced room cannot leak into the new one. - `RoomEvent::Audio` carries the track `sid` next to `identity` and `samples` (a `Frame10ms`), so the session can gate per track. - `RoomOptions` also has `max_bitrate` (Voice 13 reads it). `VoiceCommand::Connect` does not carry the channel bitrate, so the session always passes `DEFAULT_MAX_BITRATE` (64 kbit/s); wiring the real value needs a port change in `fluxer-core`. - `Frame10ms` is defined here rather than reusing `fluxer_audio::Frame`, so the crate does not depend on `fluxer-audio`. - Dev-dependency on itself with feature `fake` (so `cargo test` needs no flags) and tokio `test-util` for dev only; no new third-party crate. `Cargo.lock` gains only the `fluxer-voice` entry. Stacked on: voice-7-core-voice-connection Closes #73 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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>
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
feat(voice): session state machine over a room trait
All checks were successful
ci / Linux (x86_64) (push) Successful in 8m1s
ci / Windows (x64) (push) Successful in 8m43s
3622ad7160
New crate fluxer-voice: trait Room, VoiceSession/VoiceHandle, and the
scripted FakeRoom behind the feature "fake".

Refs #73

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

Independent review — Voice 12 (fluxer-voice session), commit 3622ad7

Reviewed e847130..3622ad7 cold (8 files, all in crates/fluxer-voice plus the Cargo.lock entry).

Checks

  1. Plan tests: all eight exist in tests/session.rs and assert what the plan says — connect_emits_connected_and_publishes_muted_mic, connect_failure_reports_error, subscribe_unsubscribe_gates_audio, reconnect_events_pass_through, second_connect_swaps_room_silently (no Disconnected, exactly one room Disconnect before the new Connect), disconnect_is_idempotent, rtt_reported_every_2s (paused clock, on the 2000 ms grid), data_messages_round_trip (topic equals fluxer_proto::rtc::CODEC_NEGOTIATION_TOPIC). 23 tests in total, all pass.
  2. Interfaces: VoiceSession::spawn<R: Room>(room, events: mpsc::Sender<VoiceEvent>) -> VoiceHandle, VoiceHandle::{send, push_microphone(&[i16], channels), remote_audio() -> mpsc::Receiver<RemoteAudio>}, RemoteAudio { identity, samples: Vec<i16>, channels }, FakeRoom + FakeRoomControl behind feature fake are as written. trait Room has the six methods. Deviations are listed under findings; none breaks a consumer that builds against the merged code.
  3. Invariants: fluxer-core untouched; no LiveKit type anywhere; no unwrap/expect/indexing in src/; malformed microphone frames are dropped, not asserted; no secret in code or tests (tokens are literals like token-one), Target/RoomOptions hold SecretString, nothing logs a URL, token, key or payload. Crate also checks standalone with and without fake (no reliance on feature unification).
  4. Review Focus 1: unsubscribe calls room.set_subscribed(.., false) (asserted as the last room call) and frames arriving afterwards are not passed on; a muted microphone is never fed to the room (asserted on mic_frames). Core ignores Disconnected { ClientInitiated } (connection.rs:664), so the cancel-while-connecting event is harmless.
  5. FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci in the review worktree: all steps passed (fmt, clippy, deny, core-isolation, parity, test, screenshot-tests).

Findings

  • minor — session.rs:427 always passes DEFAULT_MAX_BITRATE (64 kbit/s). Spec §7 wants the channel bitrate clamped to 8–510 kbit/s; that needs VoiceCommand::Connect to carry it (a fluxer-core port change). Per CLAUDE.md a deferred item needs a follow-up issue linked from this PR before merge; none exists yet.
  • minor — Interface deviations Voice 13/14 must build against: Room::connect returns Result<mpsc::Receiver<RoomEvent>, RoomError> (one stream per connection, not per room); RoomEvent::Audio { identity, sid, samples: Frame10ms } (plan: { identity, samples }); RoomOptions has max_bitrate besides e2ee_key; Room::connect may be dropped mid-flight and is then followed by disconnect(). Reasonable and documented; flagged so the Voice 13 implementer does not follow the plan text.
  • minor — The claim "gates frames even if the room call fails" (apply_subscription) and "a mute holds even if the room could not be told" have no test: FakeRoomControl cannot fail set_subscribed/set_mic_muted for a published track. The code is right by reading. Related: a failed subscribe leaves the wish true but is not retried until the track is republished.
  • minor — On a swap, wanted.subscriptions keeps entries for identities that are not in the new room; they are only cleared by ParticipantLeft or going idle. Bounded and harmless (an identity that reappears is re-subscribed as the core last asked), but it grows across repeated channel moves in one session.
  • minor — step() uses a biased select with room events ahead of the RTT timer and the microphone queue; a room that keeps its event stream non-empty would delay microphone frames. Not reachable with the fake; worth keeping in mind when Voice 13 feeds decoded audio of many participants through the same stream.
  • minor — Root README.md crate table has no crates/fluxer-voice row (outside this task's Files list).

Verdict: APPROVE — zero blocking findings, local ci green. Remote runners not checked by this review.

## Independent review — Voice 12 (`fluxer-voice` session), commit 3622ad7 Reviewed `e847130..3622ad7` cold (8 files, all in `crates/fluxer-voice` plus the `Cargo.lock` entry). **Checks** 1. Plan tests: all eight exist in `tests/session.rs` and assert what the plan says — `connect_emits_connected_and_publishes_muted_mic`, `connect_failure_reports_error`, `subscribe_unsubscribe_gates_audio`, `reconnect_events_pass_through`, `second_connect_swaps_room_silently` (no `Disconnected`, exactly one room `Disconnect` before the new `Connect`), `disconnect_is_idempotent`, `rtt_reported_every_2s` (paused clock, on the 2000 ms grid), `data_messages_round_trip` (topic equals `fluxer_proto::rtc::CODEC_NEGOTIATION_TOPIC`). 23 tests in total, all pass. 2. Interfaces: `VoiceSession::spawn<R: Room>(room, events: mpsc::Sender<VoiceEvent>) -> VoiceHandle`, `VoiceHandle::{send, push_microphone(&[i16], channels), remote_audio() -> mpsc::Receiver<RemoteAudio>}`, `RemoteAudio { identity, samples: Vec<i16>, channels }`, `FakeRoom` + `FakeRoomControl` behind feature `fake` are as written. `trait Room` has the six methods. Deviations are listed under findings; none breaks a consumer that builds against the merged code. 3. Invariants: `fluxer-core` untouched; no LiveKit type anywhere; no `unwrap`/`expect`/indexing in `src/`; malformed microphone frames are dropped, not asserted; no secret in code or tests (tokens are literals like `token-one`), `Target`/`RoomOptions` hold `SecretString`, nothing logs a URL, token, key or payload. Crate also checks standalone with and without `fake` (no reliance on feature unification). 4. Review Focus 1: unsubscribe calls `room.set_subscribed(.., false)` (asserted as the last room call) and frames arriving afterwards are not passed on; a muted microphone is never fed to the room (asserted on `mic_frames`). Core ignores `Disconnected { ClientInitiated }` (`connection.rs:664`), so the cancel-while-connecting event is harmless. 5. `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` in the review worktree: **all steps passed** (fmt, clippy, deny, core-isolation, parity, test, screenshot-tests). **Findings** - **minor** — `session.rs:427` always passes `DEFAULT_MAX_BITRATE` (64 kbit/s). Spec §7 wants the channel bitrate clamped to 8–510 kbit/s; that needs `VoiceCommand::Connect` to carry it (a `fluxer-core` port change). Per `CLAUDE.md` a deferred item needs a `follow-up` issue linked from this PR before merge; none exists yet. - **minor** — Interface deviations Voice 13/14 must build against: `Room::connect` returns `Result<mpsc::Receiver<RoomEvent>, RoomError>` (one stream per connection, not per room); `RoomEvent::Audio { identity, sid, samples: Frame10ms }` (plan: `{ identity, samples }`); `RoomOptions` has `max_bitrate` besides `e2ee_key`; `Room::connect` may be dropped mid-flight and is then followed by `disconnect()`. Reasonable and documented; flagged so the Voice 13 implementer does not follow the plan text. - **minor** — The claim "gates frames even if the room call fails" (`apply_subscription`) and "a mute holds even if the room could not be told" have no test: `FakeRoomControl` cannot fail `set_subscribed`/`set_mic_muted` for a published track. The code is right by reading. Related: a failed *subscribe* leaves the wish `true` but is not retried until the track is republished. - **minor** — On a swap, `wanted.subscriptions` keeps entries for identities that are not in the new room; they are only cleared by `ParticipantLeft` or going idle. Bounded and harmless (an identity that reappears is re-subscribed as the core last asked), but it grows across repeated channel moves in one session. - **minor** — `step()` uses a `biased` select with room events ahead of the RTT timer and the microphone queue; a room that keeps its event stream non-empty would delay microphone frames. Not reachable with the fake; worth keeping in mind when Voice 13 feeds decoded audio of many participants through the same stream. - **minor** — Root `README.md` crate table has no `crates/fluxer-voice` row (outside this task's Files list). **Verdict: APPROVE** — zero blocking findings, local ci green. Remote runners not checked by this review.
charles manually merged commit fb05a010cb into voice 2026-11-11 21:03:51 +00:00
Sign in to join this conversation.
No description provided.