State Machine

Phase 1 note: the gateway and voice-node do not share membership state. The voice node registers a client on the first UDP packet and drops idle addresses after 30 seconds. Diagrams that show gateway notify voice node describe the Phase 2 target.

Client and server maintain synchronized state machines over the LNEx connection. This document describes the states, transitions, and what triggers them.

Client states

                    ┌─────────────────┐
                    │   DISCONNECTED  │ ◄─── initial state / after disconnect
                    └────────┬────────┘
                             │ connect(address)
                             ▼
                    ┌─────────────────┐
                    │   CONNECTING    │ TCP handshake in progress
                    └────────┬────────┘
                             │ TCP established
                             ▼
                    ┌─────────────────┐
                    │   HANDSHAKING   │ HELLO received, sending AUTH
                    └────────┬────────┘
                             │ SESSION received
                             ▼
                    ┌─────────────────┐
                    │   CONNECTED     │ ◄─── idle, no channel joined
                    └────────┬────────┘
                             │ join_channel()
                             ▼
                    ┌─────────────────┐
              ┌────►│  IN_CHANNEL     │ text + voice available
              │     └────────┬────────┘
              │              │ leave_channel() / switch channel
              └──────────────┘
                             │ disconnect() / TCP drop
                             ▼
                    ┌─────────────────┐
                    │  RECONNECTING   │ exponential backoff (Phase 2)
                    └────────┬────────┘
                             │ max retries exceeded
                             ▼
                    ┌─────────────────┐
                    │  DISCONNECTED   │
                    └─────────────────┘

Any state can transition to DISCONNECTED on:

TCP connection drop
DISCONNECT packet received
auth failure (ERR_AUTH_FAILED)
version mismatch (ERR_VERSION_MISMATCH)

Server session states

Per-client session on the gateway:

                    ┌─────────────────┐
                    │    ACCEPTING    │ TCP connection received, sending HELLO
                    └────────┬────────┘
                             │ AUTH received
                             ▼
                    ┌─────────────────┐
                    │  AUTHENTICATING │ verifying Ed25519 signature
                    └────────┬────────┘
                             │ signature valid + not banned
                             ▼
                    ┌─────────────────┐
                    │   ESTABLISHED   │ SESSION sent, client is authenticated
                    └────────┬────────┘
                             │ JOIN_CHANNEL received
                             ▼
                    ┌─────────────────┐
              ┌────►│  IN_CHANNEL     │ forwarding messages + voice state
              │     └────────┬────────┘
              │              │ LEAVE_CHANNEL / JOIN different channel
              └──────────────┘
                             │ TCP drop / DISCONNECT / idle timeout
                             ▼
                    ┌─────────────────┐
                    │   TERMINATED    │ session cleaned up, resources freed
                    └─────────────────┘

Auth failure paths

AUTHENTICATING
    │ invalid signature      → send ERR_AUTH_FAILED → TERMINATED
    │ banned pubkey          → send ERR_AUTH_FAILED → TERMINATED
    │ unsupported version    → send ERR_VERSION_MISMATCH → TERMINATED
    │ rate limit on auth     → send ERR_RATE_LIMITED → TERMINATED

Voice session states (per user, on voice-node)

Phase 1: transition from INACTIVE to JOINING happens when the first UDP packet arrives from a client address, not when the gateway sends a signal.

                    ┌─────────────────┐
                    │    INACTIVE     │ user not in a voice channel
                    └────────┬────────┘
                             │ first UDP packet from client (Phase 1)
                             │ gateway signals join (Phase 2, not implemented)
                             ▼
                    ┌─────────────────┐
                    │    JOINING      │ UDP path being established
                    └────────┬────────┘
                             │ first UDP packet received from client
                             ▼
                    ┌─────────────────┐
                    │    SILENT       │ in channel, not transmitting
                    └────────┬────────┘
                             │ voice packets arriving
                             ▼
                    ┌─────────────────┐
              ┌────►│    SPEAKING     │ relaying to other channel members
              │     └────────┬────────┘
              │              │ DTX / push-to-talk released / silence
              └──────────────┘
                    ┌─────────────────┐
                    │     MUTED       │ server-side mute (moderator action)
                    └────────┬────────┘
                             │ unmuted by moderator
                             ▼
                    ┌─────────────────┐
                    │    SILENT       │
                    └─────────────────┘

Voice state is broadcast to all channel members as VOICE_STATE packets on every transition: SILENT → SPEAKING, SPEAKING → SILENT, MUTED, DEAFENED.

Channel join sequence (detailed)

Full flow from join_channel() call to receiving audio:

Client                    Gateway                   Voice Node
  │                          │                          │
  │── JOIN_CHANNEL ─────────►│                          │
  │                          │ check permissions         │
  │                          │ check channel exists      │
  │◄─ CHANNEL_STATE ─────────│                          │
  │   { members,             │                          │
  │     voice_endpoint,      │   (Phase 2: gateway      │
  │     channel_id }         │    notifies voice node)  │
  │                          │                          │
  │   [start UDP]            │                          │
  │── UDP VOICE_PACKET ──────────────────────────────── ►│
  │                          │                          │ relay to others
  │◄─ UDP VOICE_PACKET ───────────────────────────────── │
  │                          │                          │
  │◄─ USER_JOIN broadcast ───│                          │
  │   (sent to all members)  │                          │

If ERR_PERMISSION_DENIED is returned on JOIN_CHANNEL, the client stays in CONNECTED state and does not attempt UDP.

Reconnect logic (Phase 2)

On unexpected TCP drop from IN_CHANNEL or CONNECTED:

disconnect detected
    │
    ▼
RECONNECTING state
    │
    ├── attempt 1: wait 1s
    ├── attempt 2: wait 2s
    ├── attempt 3: wait 4s
    ├── attempt 4: wait 8s
    ├── attempt 5: wait 16s
    └── attempt 6+: wait 30s (cap)

On successful reconnect:

full auth exchange (new session token)
if user was IN_CHANNEL before disconnect: auto-rejoin same channel

On reconnect failure after N attempts (configurable, default 10):

transition to DISCONNECTED
notify user in UI

Packet validity by state

Packets received in an unexpected state are dropped with ERR_INVALID_PACKET.

Packet	Valid in states
`HELLO`	server sends in `ACCEPTING`
`AUTH`	client sends in `HANDSHAKING`
`SESSION`	server sends in `AUTHENTICATING`
`JOIN_CHANNEL`	`CONNECTED`, `IN_CHANNEL`
`LEAVE_CHANNEL`	`IN_CHANNEL`
`CHAT_MESSAGE`	`IN_CHANNEL`
`VOICE_PACKET`	UDP, user in voice channel
`PING` / `PONG`	any authenticated state
`DISCONNECT`	any state

9.8 KiB Raw Blame History