import { type HandlerArgs, type HandlerFn, createFsm } from 'machina'; /** * Runtime lifecycle states of the signal connection. * * `offline` is the resting state after the transport was lost without an explicit close: no * attempt is in flight, but a resume is still legal. It is what makes retrying a failed resume * expressible — `closed` is only reached by an explicit close or by a terminal attempt failure. */ export type SignalLifecycleState = 'new' | 'connecting' | 'connected' | 'offline' | 'reconnecting' | 'disconnecting' | 'closed'; export interface SignalMachineContext { /** Monotonic id of the current (re)connection attempt and of the transport it owns */ attemptId: number; /** Error or reason that ended the last attempt, kept for diagnostics. */ lastError?: unknown; /** Reason passed to the last close request. */ closeReason?: string; } export type SignalMachineInput = /** * Start an initial session, or restart from scratch (full reconnect). * * Establishing is legal exactly where no transport and no attempt are in play: `new`, `offline` * and `closed`. `closed` is included because it means "no transport", not "session over" — a * deliberate close and an unexpected loss leave the session equally resumable, and the engine * recovers from both. Establishing over a live session, or over an attempt already in flight, is * a caller error; `disconnecting` is waited out rather than refused. */ | { type: 'connect' } /** * Resume the existing session: legal wherever establishing is, minus `new` (nothing to resume * yet), plus `connected` — the peer connection can be severed while signalling stays up. */ | { type: 'reconnect' } /** * An attempt established its transport. Carries the attempt it belongs to: an attempt that a * newer one has already superseded must not declare the session live. */ | { type: 'connectComplete'; attemptId: number } | { type: 'connectFailed'; error?: unknown } | { type: 'reconnectComplete'; attemptId: number } /** * A resume attempt ended. `recoverable` distinguishes "another resume may follow" (→ `offline`) * from a terminal outcome such as a server leave or an expired token (→ `closed`). */ | { type: 'reconnectFailed'; error?: unknown; recoverable: boolean } /** The transport identified by `attemptId` was lost (unexpected ws close, ping timeout). */ | { type: 'transportFailed'; attemptId: number; reason: string } | { type: 'close'; reason: string } | { type: 'closeComplete' }; type Args = HandlerArgs; type Handler = HandlerFn; /** * Declares a handler for one input, restoring the payload typing that machina's `...unknown[]` * handler arguments give up. */ function on( handler: ( args: Args, event: Extract, ) => SignalLifecycleState | void, ): Handler { return handler as Handler; } /** * Whether a transport-originated input belongs to the attempt that currently owns the session. * Inputs from a superseded attempt are dropped: its transport is already being replaced, so it can * neither declare the session live nor take it down. */ function isCurrentAttempt(ctx: SignalMachineContext, event: { attemptId: number }) { return event.attemptId === ctx.attemptId; } const attemptEstablished = on<'connectComplete' | 'reconnectComplete'>(({ ctx }, event) => { if (!isCurrentAttempt(ctx, event)) { return; } return 'connected'; }); const startConnect = on<'connect'>(({ ctx }) => { ctx.attemptId += 1; ctx.lastError = undefined; return 'connecting'; }); const startReconnect = on<'reconnect'>(({ ctx }) => { ctx.attemptId += 1; ctx.lastError = undefined; return 'reconnecting'; }); const requestClose = on<'close'>(({ ctx }, event) => { ctx.closeReason = event.reason; return 'disconnecting'; }); const signalStates = { new: { connect: startConnect, close: requestClose, }, connecting: { connectComplete: attemptEstablished, // An initial connect has no session to fall back on, so failure is terminal. connectFailed: on<'connectFailed'>(({ ctx }, event) => { ctx.lastError = event.error; return 'closed'; }), close: requestClose, }, connected: { reconnect: startReconnect, transportFailed: on<'transportFailed'>(({ ctx }, event) => { if (!isCurrentAttempt(ctx, event)) { // a transport that has already been replaced, reporting its close late return; } ctx.lastError = event.reason; return 'offline'; }), close: requestClose, }, offline: { connect: startConnect, reconnect: startReconnect, close: requestClose, }, reconnecting: { reconnectComplete: attemptEstablished, reconnectFailed: on<'reconnectFailed'>(({ ctx }, event) => { ctx.lastError = event.error; return event.recoverable ? 'offline' : 'closed'; }), close: requestClose, }, // Owns the transport until the close handshake settles. Every path into this state is followed // by a `closeComplete`, so it cannot become a trap. disconnecting: { closeComplete: 'closed', }, // No transport, but the session may still be resumable: the engine resumes after an unexpected // close just as it does from `offline`. closed: { connect: startConnect, reconnect: startReconnect, }, } as const; /** * Lifecycle model of the signal connection. * * The machine deliberately does not own connection attempts: `SignalClient` performs the * asynchronous work and reports the outcome. It also does not decide *whether* to reconnect — * that policy (backoff, resume vs. full reconnect, region failover, giving up) belongs to * `RTCEngine`, so transport loss lands in `offline` rather than starting a reconnect on its own. * * Each client gets its own instance: the context is mutable and per-connection. */ export function createSignalMachine(initialState: SignalLifecycleState = 'new') { const context: SignalMachineContext = { attemptId: 0 }; return createFsm({ id: 'signal', initialState: initialState, context, states: signalStates, }); } export type SignalMachine = ReturnType; /** All lifecycle states, derived from the machine itself so the two cannot drift. */ export const signalLifecycleStates = Object.keys(signalStates) as Array;