chanora/crates/chanora_state

chanora_state

Authoritative client-side mirror of server state: channel tree, client list, and connection lifecycle. Owns the reducers that fold protocol events into state and produce deltas for the bridge (per SAD §7.2 and SDD §5).

Architecture

Core reducer pattern

The crate exposes a single reduce(state: &mut Option<ServerState>, event: StateEvent) -> Reduction function. Callers own state storage and pass it by &mut. The reducer returns a Reduction containing only the emitted Delta values. This satisfies:

• SRS-056 — deterministic deltas: the same (state, event) always produces the same Reduction
• SRS-057 — per-connection ordering
• SRS-058 — reducer functions are pure

Module: channel_join

A more specialized reducer for voice-channel join/leave state tracking with:

• Optimistic UserJoinRequested events
• AuthoritativeSelfMove confirmation from live deltas
• SnapshotReady reconciliation after connects/reconnects
• ChannelJoinProjection for UI rendering (in_channel, can_join, can_leave, sync_state)
• ConnectionEpoch tracking to disambiguate stale events across reconnects

State model

• ServerState — owned HashMap<u64, ChannelInfo> and HashMap<u64, ClientInfo> with stable ordering vectors. Built from ServerSnapshot, updated incrementally via StateEvents.
• ConnectionState — enum: Idle / Connecting / Ready / Reconnecting / Lost

Public API Summary

Types

Type	Role
ServerState	Authoritative mirror of connected server state
ConnectionState	Lifecycle enum (Idle, Connecting, Ready, Reconnecting, Lost)
StateEvent	Protocol-layer input events (Snapshot, ChannelChanged, ClientChanged, etc.)
Delta	Bridge output events (SnapshotApplied, ChannelUpserted, ClientRemoved, etc.)
Reduction	Result of reduce(): a Vec<Delta>
StateError	Reducer errors (Unknown entity, invariant violation)

Key functions

• reduce(state, event) → Reduction — apply a protocol event, return deltas
• reduce_reconnect_snapshot(state, snap) → Reduction — replace all state on reconnect (SRS-059)

ServerState methods

• channel(id) / client(id) — lookup by id
• channels() / clients() — ordered iterators
• own_channel() — the channel our client is in
• clients_in_channel(channel_id) — filtered iterator

channel_join module

• reduce(state, event) → JoinReduction — channel-join state machine
• project(state) → ChannelJoinProjection — UI-ready snapshot
• ChannelJoinEvent, ChannelJoinState, ChannelJoinProjection — state machine types

Design notes

• Events are ignored when state is None (disconnected), except Snapshot (creates state) and ConnectionChanged.
• Deleting a channel also removes all clients in that channel.
• Duplicate IDs in snapshots are deduplicated deterministically.