# Signaling (WebSocket)

> **Area:** realtime
> **Status:** Active
> **Last updated:** 2026-07-05

## Overview

The signaling server exposes a single WebSocket per origin that carries identity, room membership, presence, WebRTC SDP/ICE relay, selected server-relayed chat/DM/voice fallbacks, plugin events, and multi-device `account_sync`. The product client implements the consumer in `toju-app/src/app/infrastructure/realtime/signaling/`.

**Canonical contract:** this document and [`server/src/websocket/handler.ts`](../../server/src/websocket/handler.ts). Do **not** treat `toju-app/src/app/shared-kernel/signaling-contracts.ts` as authoritative — it lists legacy types (`join`, `leave`, `chat`, `ice-candidate`) that do not match the live server.

## Responsibilities

- Authenticate connections via `identify` (session token).
- Track per-connection room membership and broadcast room-scoped presence.
- Relay WebRTC offers/answers/ICE between peers that share server membership (or DM/direct-call rules).
- Relay narrow server fallbacks when P2P data channels are unavailable (chat, DM, voice presence).
- Forward `account_sync` payloads to sibling connections for the same user identity.
- It does NOT own: P2P data-channel payloads (attachments, message inventory, custom emoji chunks, plugin message bus), local persistence, or REST server-directory APIs.

## Key concepts

- **Envelope:** JSON object with required `type` string; additional fields vary by type.
- **oderId:** user identity on the wire (legacy spelling, matches server code).
- **clientInstanceId:** per-tab/device id stored in `sessionStorage`; multiple open connections per `oderId` are allowed.
- **connectionScope:** optional string grouping connections (e.g. browser profile).
- **voiceActive:** server marks the connection that owns outbound RTC relay for a user; updated from `voice_state` payloads.

## Ordering invariants

1. **`identify` before anything else** — unauthenticated connections receive `auth_required` for all types except `identify` and `keepalive`.
2. **Per-connection serialization** — `handleWebSocketMessage` chains handlers per `connectionId` so `join_server` cannot run while `identify` is still awaiting the token DB lookup.
3. **Client replay on reconnect** — `SignalingManager.reIdentifyAndRejoin` sends `identify` then re-joins rooms; see [`toju-app/src/app/infrastructure/realtime/README.md`](../../toju-app/src/app/infrastructure/realtime/README.md).

## Connection lifecycle (server → client)

On connect the server assigns a `connectionId` and may emit:

| type | When |
|------|------|
| `connected` | Immediately after WebSocket open (`server/src/websocket/index.ts`) |

On disconnect, if the connection was voice-active, the server broadcasts a cleared `voice_state` via `finalizeVoiceDisconnectForConnection`.

## Inbound types (client → server)

| type | Auth | Behavior |
|------|------|----------|
| `keepalive` | Optional | Responds `keepalive_ack` with `serverTime` |
| `identify` | N/A (establishes auth) | Validates session token; sets `oderId`, profile fields; evicts stale same `(oderId, connectionScope, clientInstanceId)` sockets; emits `account_sync_peer_online` to siblings |
| `join_server` | Required | Access check; adds `serverId` to connection; sends `server_users` + `plugin_requirements`; may broadcast `user_joined` (identity-aware) |
| `view_server` | Required | Switches `viewedServerId`; refreshes `server_users` + `plugin_requirements` |
| `leave_server` | Required | Removes membership; may broadcast `user_left` with remaining `serverIds` |
| `offer`, `answer`, `ice_candidate` | Required | Relay to `targetUserId` when peers share server membership |
| `direct-message`, `direct-message-status`, `direct-message-mutation`, `direct-message-typing`, `direct-message-sync-request`, `direct-message-sync`, `direct-call` | Required | Relay to `targetUserId` (DM rules — no shared-server requirement) |
| `server_icon_peer_request`, `server_icon_peer_data` | Required | Relay when both users share `serverId` membership |
| `chat_message` | Required | Broadcast to server members (excludes sender connection) |
| `voice_state` | Required | Updates `voiceActive` / snapshot; broadcast to server members |
| `voice_client_takeover` | Required | Notifies sibling connections via `notifyOtherConnectionsForOderId` |
| `account_sync` | Required | Forwards `payload` object to other connections for same `oderId` |
| `typing` | Required | Broadcast `user_typing` to server members |
| `status_update` | Required | Broadcast `status_update` (`online` \| `away` \| `busy` \| `offline`) to joined servers |
| `server_icon_available` | Required | Records local `iconUpdatedAt` per server on the connection |
| `server_icon_sync_request` | Required | Responds `server_icon_sync_peers` with peers having newer icons |
| `plugin_event` | Required | Validates against server plugin metadata; broadcast or `plugin_error` |

Unknown inbound types are logged and ignored.

### `identify` request fields

| Field | Required | Notes |
|-------|----------|-------|
| `token` | Yes | Session token from REST login/register |
| `oderId` | No | If present, must match token user id |
| `displayName` | No | Defaults to existing or `"User"` |
| `description`, `profileUpdatedAt`, `homeSignalServerUrl` | No | Profile card fields |
| `clientInstanceId` | No | Per-tab id for multi-device and voice ownership |
| `connectionScope` | No | Eviction scope for stale sockets |

Errors: `auth_error` with `MISSING_TOKEN`, `INVALID_TOKEN`, or `USER_ID_MISMATCH`.

## Server-emitted types (server → client)

| type | Trigger |
|------|---------|
| `keepalive_ack` | Response to `keepalive` |
| `auth_required` | Message before `identify` |
| `auth_error` | Failed `identify` |
| `access_denied` | `join_server` rejected (`serverId`, `reason`) |
| `server_users` | After join/view; lists unique users in room |
| `user_joined` | New identity in server (excludes same identity's connections) |
| `user_left` | Identity fully left server (`serverIds` = remaining rooms) |
| `plugin_requirements` | Plugin install snapshot after join/view |
| `plugin_error` | Invalid plugin event |
| `server_icon_sync_peers` | Response to `server_icon_sync_request` |
| `account_sync_peer_online` | Sibling connection came online |
| `account_sync` | Relayed multi-device payload |
| `chat_message` | Relayed room chat fallback |
| `user_typing` | Typing indicator |
| `status_update` | Presence status change |
| `voice_state` | Voice roster / disconnect cleanup |
| `voice_client_takeover` | Another tab took voice ownership |
| `plugin_event` | Broadcast plugin event |
| Forwarded RTC/DM | Copies of client messages with `fromUserId` set |

## Relay rules

- **RTC (`offer` / `answer` / `ice_candidate`):** forwarded when sender and target share any server membership.
- **Direct signaling types:** forwarded to `targetUserId` without shared-server check.
- **Server icon P2P:** both users must be members of `message.serverId`.
- **Broadcasts** (`chat_message`, `voice_state`, `typing`, etc.): exclude sender **connection id** (not whole identity) so multi-device sessions still receive updates.
- **`user_joined` / `user_left`:** exclude whole **identity** so other users do not see duplicate join/leave for multiple tabs.

## P2P vs signaling split

| Transport | Carries |
|-----------|---------|
| **WebRTC data channel** | Chat events, attachments, custom emoji, message revisions/inventory, profile avatar bytes, voice/screen control, plugin message bus, game activity |
| **WebSocket signaling** | Identity, membership, presence, RTC SDP/ICE, chat/DM/voice fallbacks, `account_sync`, plugin events |

Server-relayed chat (`chat_message`) and DM types exist so users see written chat and delivery state while data channels are down. Media, attachments, and inventory sync remain peer-plane responsibilities.

## Multi-device (`account_sync`)

The client wraps relayable local changes in `account_sync` envelopes. The server forwards the inner `payload` to other open connections for the same `oderId`. When a device identifies, siblings receive `account_sync_peer_online` and push snapshots (saved servers, friends, emoji library, chat history batches, etc.). See [authentication.md](authentication.md) and domain-specific feature docs.

## Client implementation map

| Concern | Location |
|---------|----------|
| One socket per signal URL | `signaling/signaling.manager.ts` |
| Route picker | `signaling/signaling-transport-handler.ts` |
| Room affinity | `signaling/server-signaling-coordinator.ts` |
| Inbound dispatch | `signaling/signaling-message-handler.ts` |
| Constants (intervals, types) | `realtime.constants.ts` |

## Related

- [authentication.md](authentication.md) — session tokens and `identify` trust boundary
- [direct-messaging.md](direct-messaging.md) — DM envelope relay types
- [voice-webrtc.md](voice-webrtc.md) — RTC relay and `voice_state`
- [plugins.md](plugins.md) — `plugin_event` / `plugin_requirements`
- [message-integrity.md](message-integrity.md) — signed revisions (P2P; `account_sync` relay)
- Product client deep dive: [`toju-app/src/app/infrastructure/realtime/README.md`](../../toju-app/src/app/infrastructure/realtime/README.md)
- Server handler: [`server/src/websocket/handler.ts`](../../server/src/websocket/handler.ts)

## Changelog

| Date | Change |
|------|--------|
| 2026-07-05 | Initial canonical envelope catalog; deprecates `shared-kernel/signaling-contracts.ts` as wire source |