import { randomUUID } from 'node:crypto' import type { Server } from 'node:http' import { WebSocket, WebSocketServer } from 'ws' import { createControlFrame, decodeControlFrame, MAX_CONTROL_FRAME_BYTES, MAX_RELAY_FRAME_BYTES, SERVER_SHUTDOWN_CLOSE_CODE, SERVER_SHUTDOWN_CLOSE_REASON, type ControlFrame, type HelloPayload, type ConnectRequestPayload, type SecureHandshakePayload, type RelayPayload, type TransportSelectedPayload, } from '@dsh-remote/protocol' import { ApiError, Store } from './store.js' import { Logger, type LogLevel } from './logger.js' import { normalizeGatewayOptions, normalizeMaxFramesPerSec, type GatewayTimingOptions } from './config.js' export interface GatewayOptions extends GatewayTimingOptions { maxFramesPerSec?: number logLevel?: LogLevel logger?: Logger /** Advertise `transport.turn` (and accept TURN credential requests). */ turnEnabled?: boolean } /** * Connection lifecycle. Frames are only ever interpreted in `awaiting_hello` * or `authenticated`; `closing`/`closed` exists so a hello that loses the race * against the handshake deadline can never authenticate, register a peer, * touch the store or replace a healthy socket. */ type ConnectionState = 'awaiting_hello' | 'authenticated' | 'closing' | 'closed' type Peer = { ws: WebSocket; id: string; role: 'host' | 'client'; capabilities: string[]; version: string; lastPong: number; nonce?: string; evictedTombstoneUntil?: number } type Link = { id: string; host: string; client: string; stage: 'pending' | 'accepted' | 'handshake' | 'ready'; created: number; counters: Map; preferredTransports: TransportName[]; iceCandidates: number } type DroppedLink = { host: string; client: string; expiresAt: number; droppedFrames: number } /** Keep tombstones long enough for late in-flight frames to drain without CONNECTION_NOT_FOUND storms. */ const DROPPED_LINK_TTL_MS = 300_000 const MAX_DROPPED_LINKS_PER_HOST = 64 const MAX_DROPPED_LINKS = 16_384 /** Protocol v1 default: at most 256 ICE candidates per logical connection. */ export const MAX_ICE_CANDIDATES_PER_CONNECTION = 256 /** Mirrors docs/protocol.md: Clients use max(server, local) and default to 12 s. */ const WEBRTC_FALLBACK_TIMEOUT_MS = 12_000 const SUPPORTED_TRANSPORTS = ['transport.lan', 'transport.p2p', 'transport.turn', 'transport.relay'] as const const TRANSPORT_NAMES = ['lan', 'p2p', 'turn', 'relay'] as const type TransportName = (typeof TRANSPORT_NAMES)[number] function modernHost(version: string): boolean { const match = /^v?(\d+)\.(\d+)\.(\d+)(?:\+.*)?$/.exec(version) if (!match) return false const [major, minor, patch] = match.slice(1).map(Number) return major! > 0 || (minor! > 2 || (minor === 2 && patch! >= 15)) } const SAFE_TEXT = /^[A-Za-z0-9_.:-]+$/ const SAFE_PATH = /^[A-Za-z0-9/._~-]*$/ const SAFE_ADDRESS = /^[0-9a-fA-F:.]{2,45}$/ const SAFE_ERROR_NAME = /^[A-Za-z][A-Za-z0-9]{0,31}$/ const SAFE_ERROR_CODE = /^[A-Z0-9_]{1,32}$/ /** Diagnostics must never echo client-supplied text verbatim. */ function safeText(value: unknown, max = 64): string | undefined { return typeof value === 'string' && SAFE_TEXT.test(value) ? value.slice(0, max) : undefined } /** Parse the upgrade request path, dropping the query string (it may carry a token). */ function requestPath(rawUrl: string | undefined): string { if (typeof rawUrl !== 'string' || rawUrl === '') return '' const end = rawUrl.search(/[?#]/) const path = end === -1 ? rawUrl : rawUrl.slice(0, end) return SAFE_PATH.test(path) ? path.slice(0, 64) : '' } function socketAddress(socket: unknown): string | undefined { try { const address = (socket as { remoteAddress?: unknown } | null)?.remoteAddress return typeof address === 'string' && SAFE_ADDRESS.test(address) ? address : undefined } catch { return undefined } } function errorName(error: unknown): string { try { const name = error instanceof Error ? error.name : undefined return typeof name === 'string' && SAFE_ERROR_NAME.test(name) ? name : 'Error' } catch { return 'Error' } } function errorCode(error: unknown): string | undefined { try { const code = (error as { code?: unknown } | null | undefined)?.code return typeof code === 'string' && SAFE_ERROR_CODE.test(code) ? code : undefined } catch { return undefined } } export class Gateway { readonly peers = new Map() private links = new Map() private droppedLinks = new Map() private wss = new WebSocketServer({ noServer: true, maxPayload: MAX_RELAY_FRAME_BYTES, perMessageDeflate: false }) private heartbeat: ReturnType private closed = false readonly turnEnabled: boolean readonly helloTimeoutMs: number readonly heartbeatIntervalMs: number readonly heartbeatDisconnectMs: number readonly forceTerminateGraceMs: number readonly maxFramesPerSec: number readonly logger: Logger constructor(server: Server, private store: Store, origin: string, options: GatewayOptions = {}) { // One normalization path for CLI and programmatic callers: NaN, Infinity, // negatives and out-of-range values degrade to documented defaults instead // of becoming 1ms timers. const timing = normalizeGatewayOptions(options) this.helloTimeoutMs = timing.helloTimeoutMs this.heartbeatIntervalMs = timing.heartbeatIntervalMs this.heartbeatDisconnectMs = timing.heartbeatDisconnectMs this.forceTerminateGraceMs = timing.forceTerminateGraceMs this.maxFramesPerSec = normalizeMaxFramesPerSec(options.maxFramesPerSec) this.logger = options.logger ?? new Logger('gateway', options.logLevel ?? 'info') this.turnEnabled = options.turnEnabled === true store.onInvalidate = id => this.disconnect(id, 'AUTH_INVALID') server.on('upgrade', (req, socket, head) => { const path = requestPath(req.url) // The route still requires an exact match: a query string is rejected // (exactly as before) but only its parsed pathname is ever logged. const pathRejected = req.url !== '/ws/v1/connect' const originRejected = Boolean(req.headers.origin) && req.headers.origin !== origin if (pathRejected || originRejected || this.wss.clients.size >= 256) { this.logger.warn('ws_upgrade_rejected', { // Parsed pathname only: the raw URL may carry credentials in its query. path: path === '' ? 'unknown' : path, reason: pathRejected ? 'invalid_url' : originRejected ? 'origin_mismatch' : 'connection_limit_reached', clientCount: this.wss.clients.size, hasOrigin: Boolean(req.headers.origin), remoteAddress: socketAddress(socket), }) socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n') return } this.wss.handleUpgrade(req, socket, head, ws => this.accept(ws)) }) this.heartbeat = setInterval(() => { if (this.closed) return for (const peer of this.peers.values()) { if (Date.now() - peer.lastPong > this.heartbeatDisconnectMs) { this.logger.warn('ws_heartbeat_timeout', { peerId: peer.id, role: peer.role, lastPong: peer.lastPong, elapsedMs: Date.now() - peer.lastPong, thresholdMs: this.heartbeatDisconnectMs, }) this.disconnect(peer.id, 'CONNECTION_FAILED') continue } peer.nonce = randomUUID() this.send(peer, createControlFrame('ping', { nonce: peer.nonce })) } for (const link of this.links.values()) { if (link.stage !== 'ready' && Date.now() - link.created > 30_000) this.drop(link, 'CONNECTION_FAILED') } this.pruneDroppedLinks(Date.now()) }, this.heartbeatIntervalMs) this.heartbeat.unref() } private pruneDroppedLinks(now: number): void { for (const [id, entry] of this.droppedLinks) { if (entry.expiresAt <= now) this.droppedLinks.delete(id) } } private evictDroppedLink(id: string, entry: DroppedLink, now: number): void { this.droppedLinks.delete(id) if (entry.expiresAt <= now) return for (const peerId of [entry.host, entry.client]) { const p = this.peers.get(peerId) if (p) p.evictedTombstoneUntil = Math.max(p.evictedTombstoneUntil ?? 0, entry.expiresAt) } } private recordDroppedLink(link: Link): void { const now = Date.now() this.pruneDroppedLinks(now) this.droppedLinks.delete(link.id) let hostCount = 0 let oldestForHost: [string, DroppedLink] | undefined for (const [id, entry] of this.droppedLinks) { if (entry.host === link.host) { if (oldestForHost === undefined) oldestForHost = [id, entry] hostCount += 1 } } if (hostCount >= MAX_DROPPED_LINKS_PER_HOST && oldestForHost !== undefined) { this.evictDroppedLink(oldestForHost[0], oldestForHost[1], now) } while (this.droppedLinks.size >= MAX_DROPPED_LINKS) { const oldest = this.droppedLinks.entries().next().value as [string, DroppedLink] | undefined if (oldest === undefined) break this.evictDroppedLink(oldest[0], oldest[1], now) } this.droppedLinks.set(link.id, { host: link.host, client: link.client, expiresAt: now + DROPPED_LINK_TTL_MS, droppedFrames: 0, }) } private isDroppedLinkFrame(peer: Peer, frame: ControlFrame): boolean { if (frame.type === 'ping' || frame.type === 'pong' || frame.type === 'connect.request') return false const p = frame.payload as Record const id = p.connectionId if (typeof id !== 'string' || this.links.has(id)) return false const now = Date.now() const dropped = this.droppedLinks.get(id) if (!dropped) { return peer.evictedTombstoneUntil !== undefined && now < peer.evictedTombstoneUntil } if (dropped.expiresAt <= now) { this.droppedLinks.delete(id) return false } if (peer.id !== dropped.host && peer.id !== dropped.client) return false dropped.droppedFrames += 1 if (dropped.droppedFrames === 1) { this.logger.debug('ws_stale_link_frames_dropped', { peerId: peer.id, role: peer.role, connectionId: safeText(id), }) } return true } droppedLinkFrameCount(connectionId: string): number { return this.droppedLinks.get(connectionId)?.droppedFrames ?? 0 } private send(peer: Peer, frame: ControlFrame): void { if (peer.ws.readyState !== WebSocket.OPEN) return if (peer.ws.bufferedAmount > 4 * MAX_RELAY_FRAME_BYTES) { this.disconnect(peer.id, 'SLOW_CONSUMER'); return } peer.ws.send(JSON.stringify(frame)) } private drop(link: Link, code: string): void { this.links.delete(link.id) this.recordDroppedLink(link) for (const id of [link.host, link.client]) { const p = this.peers.get(id) if (p && (p.role === 'client' || modernHost(p.version))) this.send(p, createControlFrame('error', { code, message: code, connectionId: link.id, retryable: true })) } } disconnect(id: string, code: string): void { const peer = this.peers.get(id) this.peers.delete(id) for (const link of this.links.values()) if (link.host === id || link.client === id) this.drop(link, code) if (!peer) return this.logger.info('ws_peer_disconnected', { peerId: id, code }) try { peer.ws.close(code === 'CONNECTION_REPLACED' ? 4003 : 4001, code) } catch { // Socket already closing: the grace below still forces termination. } const timer = setTimeout(() => { if (peer.ws.readyState !== WebSocket.CLOSED) peer.ws.terminate() }, this.forceTerminateGraceMs) timer.unref() } /** * Authorize a REST `/api/v1/turn/credentials` request. Only the two devices * of an active logical connection may obtain credentials, and only while * that connection is still being established. */ authorizeIce(deviceId: string, connectionId: string): boolean { const link = this.links.get(connectionId) if (link === undefined) return false if (link.host !== deviceId && link.client !== deviceId) return false if (link.stage !== 'accepted' && link.stage !== 'handshake') return false return this.peers.has(link.host) && this.peers.has(link.client) } private supportedCapabilities(): string[] { return SUPPORTED_TRANSPORTS.filter(capability => capability !== 'transport.turn' || this.turnEnabled) } private negotiatedCapabilities(offered: readonly string[]): string[] { return this.supportedCapabilities().filter(capability => offered.includes(capability)) } private accept(ws: WebSocket): void { let state: ConnectionState = 'awaiting_hello' let peer: Peer | undefined let deadline: ReturnType | undefined let graceTimer: ReturnType | undefined // Timer cleanup is idempotent: every path (auth, timeout, close) can call // it any number of times without leaving a scheduled callback behind. const clearDeadline = (): void => { if (deadline === undefined) return clearTimeout(deadline) deadline = undefined } const clearGrace = (): void => { if (graceTimer === undefined) return clearTimeout(graceTimer) graceTimer = undefined } const terminateSoon = (target: WebSocket): void => { clearGrace() graceTimer = setTimeout(() => { graceTimer = undefined if (target.readyState !== WebSocket.CLOSED) target.terminate() }, this.forceTerminateGraceMs) graceTimer.unref() } this.logger.debug('ws_connection_accepted', { clientCount: this.wss.clients.size }) deadline = setTimeout(() => { deadline = undefined if (state !== 'awaiting_hello') return // Close the door before closing the socket: any hello still in flight is // then discarded by the frame guard instead of authenticating late. state = 'closing' this.logger.warn('ws_hello_timeout', { timeoutMs: this.helloTimeoutMs, readyState: ws.readyState }) if (ws.readyState === WebSocket.OPEN) { try { const frame = createControlFrame('error', { code: 'HELLO_TIMEOUT', message: `Hello handshake timed out after ${this.helloTimeoutMs}ms`, retryable: true, }) ws.send(JSON.stringify(frame)) } catch (error) { this.logger.warn('ws_hello_timeout_send_failed', { errorName: errorName(error) }) } } try { ws.close(4001, 'CONNECTION_FAILED') } catch { // ws might not be closable in some edge states; the grace below terminates it. } terminateSoon(ws) }, this.helloTimeoutMs) deadline.unref() let windowStart = Date.now(), frames = 0, bytes = 0, droppedFrames = 0, droppedBytes = 0 ws.on('error', (error) => { // Error messages can embed payload fragments: log the class and errno only. this.logger.warn('ws_socket_error', { peerId: peer?.id, errorName: errorName(error), errorCode: errorCode(error), }) }) ws.on('close', (code, reason) => { state = 'closed' clearDeadline() clearGrace() this.logger.info('ws_connection_closed', { ...(peer ? { peerId: peer.id, role: peer.role } : {}), code, // The close reason is arbitrary client text: report only its presence. hasReason: Buffer.isBuffer(reason) ? reason.length > 0 : false, }) if (peer && this.peers.get(peer.id) === peer) this.disconnect(peer.id, 'CONNECTION_FAILED') }) ws.on('message', (raw, binary) => { // Frames arriving after the handshake deadline are dropped before any // parsing, authentication or store access can happen. if (state !== 'awaiting_hello' && state !== 'authenticated') return if (ws.readyState !== WebSocket.OPEN) return let frame: ControlFrame | undefined try { if (binary) throw new ApiError('INVALID_MESSAGE') const text = raw.toString() const frameBytes = Buffer.byteLength(text) if (Date.now() - windowStart >= 1000) { windowStart = Date.now() frames = 0 bytes = 0 droppedFrames = 0 droppedBytes = 0 } const maxDroppedFrames = Math.max(this.maxFramesPerSec * 2, 1024) const maxDroppedBytes = 8 * MAX_RELAY_FRAME_BYTES if (frames + droppedFrames + 1 > this.maxFramesPerSec + maxDroppedFrames || bytes + droppedBytes + frameBytes > 16 * MAX_RELAY_FRAME_BYTES + maxDroppedBytes) { throw new ApiError('RATE_LIMITED') } if (state === 'awaiting_hello' && (++frames > this.maxFramesPerSec || (bytes += frameBytes) > 16 * MAX_RELAY_FRAME_BYTES)) { throw new ApiError('RATE_LIMITED') } const envelope = JSON.parse(text) as { v?: unknown } if (envelope && envelope.v !== 1) throw new ApiError('UNSUPPORTED_VERSION') frame = decodeControlFrame(text) if (state === 'awaiting_hello') { if (frame.type !== 'hello') throw new ApiError('AUTH_REQUIRED') const p = frame.payload as HelloPayload const device = this.store.authenticate(p.accessToken).descriptor if (device.deviceId !== p.deviceId || device.role !== p.role) throw new ApiError('AUTH_INVALID') if (!p.protocols.includes(1)) throw new ApiError('UNSUPPORTED_VERSION') // Re-assert the state: if the deadline fired while credentials were // checked, the timeout wins and none of the side effects below run. if (state !== 'awaiting_hello') return state = 'authenticated' clearDeadline() this.disconnect(device.deviceId, 'CONNECTION_REPLACED') // Keep the negotiated set (what hello.ack advertises), so a link can // never coordinate a transport this Server did not offer — e.g. TURN // while no TURN deployment is configured. peer = { ws, id: device.deviceId, role: device.role, capabilities: this.negotiatedCapabilities(p.capabilities), version: p.clientVersion ?? device.clientVersion, lastPong: Date.now() } this.peers.set(peer.id, peer) this.store.touch(peer.id, p.clientVersion, p.harnessVersion) this.logger.info('ws_hello_authenticated', { deviceId: safeText(peer.id), role: peer.role, clientVersion: safeText(peer.version), capabilities: peer.capabilities.filter(capability => typeof capability === 'string' && SAFE_TEXT.test(capability)).slice(0, 8), }) this.send(peer, createControlFrame('hello.ack', { protocol: 1, serverVersion: 'self-hosted/0.1.0', connectionSessionId: randomUUID(), heartbeatIntervalMs: this.heartbeatIntervalMs, maxControlFrameBytes: MAX_CONTROL_FRAME_BYTES, maxRelayFrameBytes: MAX_RELAY_FRAME_BYTES, capabilities: this.negotiatedCapabilities(p.capabilities), webrtcEnabled: true, webrtcFallbackTimeoutMs: WEBRTC_FALLBACK_TIMEOUT_MS, })) return } if (frame.type === 'hello') throw new ApiError('INVALID_MESSAGE') if (!peer || this.peers.get(peer.id) !== peer) throw new ApiError('AUTH_INVALID') this.store.get(peer.id) if (this.isDroppedLinkFrame(peer, frame)) { if (++droppedFrames > maxDroppedFrames || (droppedBytes += frameBytes) > maxDroppedBytes) { throw new ApiError('RATE_LIMITED') } return } if (++frames > this.maxFramesPerSec || (bytes += frameBytes) > 16 * MAX_RELAY_FRAME_BYTES) { throw new ApiError('RATE_LIMITED') } this.handle(peer, frame) } catch (error) { const code = error instanceof ApiError ? error.code : 'INVALID_MESSAGE' this.logger.warn('ws_message_error', { code, peerId: peer?.id, // Never log error.message: JSON parse failures echo the payload. errorName: errorName(error), }) // Valid connection-scoped failures must not close the Host's other clients. const connectionId = (frame?.payload as { connectionId?: unknown } | undefined)?.connectionId if (peer && typeof connectionId === 'string' && code !== 'RATE_LIMITED') { const link = this.links.get(connectionId) if (link && (link.host === peer.id || link.client === peer.id)) { this.drop(link, code); return } this.send(peer, createControlFrame('error', { code, message: code, connectionId, retryable: false })) return } state = 'closing' clearDeadline() if (ws.readyState === WebSocket.OPEN) { try { ws.send(JSON.stringify(createControlFrame('error', { code, message: code, retryable: false }))) } catch { /* closing anyway */ } } if (peer) this.disconnect(peer.id, code) else { try { ws.close(4001, code) } catch { /* terminate below */ } terminateSoon(ws) } } }) } private handle(peer: Peer, frame: ControlFrame): void { const p = frame.payload as Record if (frame.type === 'ping') { this.send(peer, createControlFrame('pong', { nonce: p.nonce })); return } if (frame.type === 'pong') { if (peer.nonce && p.nonce === peer.nonce) { peer.lastPong = Date.now(); peer.nonce = undefined } return } if (frame.type === 'connect.request') { const request = frame.payload as ConnectRequestPayload if (peer.role !== 'client') throw new ApiError('MEMBERSHIP_REQUIRED') const candidateHost = this.peers.get(request.hostDeviceId) if (candidateHost && Date.now() - candidateHost.lastPong > this.heartbeatDisconnectMs) { this.logger.warn('ws_heartbeat_timeout', { peerId: candidateHost.id, role: candidateHost.role, lastPong: candidateHost.lastPong, elapsedMs: Date.now() - candidateHost.lastPong, thresholdMs: this.heartbeatDisconnectMs, }) this.disconnect(candidateHost.id, 'CONNECTION_FAILED') } const host = this.peers.get(request.hostDeviceId) if (!host || host.role !== 'host') { this.send(peer, createControlFrame('error', { code: 'HOST_OFFLINE', message: 'Host is offline.', retryable: true })); return } this.store.get(host.id) if (!request.preferredTransports.includes('relay') || !peer.capabilities.includes('transport.relay') || !host.capabilities.includes('transport.relay')) throw new ApiError('CAPABILITY_NOT_SUPPORTED') // The link coordinates only transports both peers actually advertised; // the Host receives the same intersection so it never sees a transport // it could not have negotiated. const preferredTransports = [...new Set(request.preferredTransports)].filter(transport => peer.capabilities.includes(`transport.${transport}`) && host.capabilities.includes(`transport.${transport}`)) if (preferredTransports.length === 0) throw new ApiError('CAPABILITY_NOT_SUPPORTED') for (const old of this.links.values()) if (old.client === peer.id || (old.host === host.id && !modernHost(host.version))) this.drop(old, 'CONNECTION_REPLACED') if (this.links.size >= 256) throw new ApiError('RATE_LIMITED') const link: Link = { id: randomUUID(), host: host.id, client: peer.id, stage: 'pending', created: Date.now(), counters: new Map(), preferredTransports, iceCandidates: 0, } this.links.set(link.id, link) this.send(host, createControlFrame('connect.incoming', { connectionId: link.id, clientDeviceId: peer.id, clientIdentityKey: this.store.get(peer.id).descriptor.identityKey, authorization: 'account', preferredTransports: link.preferredTransports, })) return } const id = p.connectionId const link = typeof id === 'string' ? this.links.get(id) : undefined if (!link || (peer.id !== link.host && peer.id !== link.client)) throw new ApiError('CONNECTION_NOT_FOUND') const otherId = peer.id === link.host ? link.client : link.host const other = this.peers.get(otherId) this.store.get(otherId) if (!other) throw new ApiError('CONNECTION_FAILED') if (frame.type === 'connect.accepted' || frame.type === 'connect.rejected') { if (peer.id !== link.host || link.stage !== 'pending') throw new ApiError('INVALID_MESSAGE') if (frame.type === 'connect.rejected') { this.links.delete(link.id) this.recordDroppedLink(link) } else link.stage = 'accepted' this.send(other, frame) return } if (p.targetDeviceId !== otherId || link.stage === 'pending') throw new ApiError('CONNECTION_NOT_FOUND') if (frame.type.startsWith('signal.')) { this.forwardSignal(link, peer, other, frame) return } if (frame.type === 'transport.selected') { this.forwardTransportSelected(link, peer, other, frame.payload as TransportSelectedPayload) return } if (frame.type === 'secure.handshake') { const step = (frame.payload as SecureHandshakePayload).step if (step === 1 && peer.id === link.client && link.stage === 'accepted') link.stage = 'handshake' else if (step === 2 && peer.id === link.host && link.stage === 'handshake') link.stage = 'ready' else throw new ApiError('INVALID_MESSAGE') } else if (frame.type === 'relay') { const counter = (frame.payload as RelayPayload).counter if (link.stage !== 'ready' || counter <= (link.counters.get(peer.id) ?? -1)) throw new ApiError('INVALID_MESSAGE') link.counters.set(peer.id, counter) } else throw new ApiError('INVALID_MESSAGE') this.send(other, frame) } /** * Forward WebRTC signaling only while the logical connection is being * established, and only for a transport this link actually negotiated. A * relay-only link has no data plane to coordinate — the Host treats * unsolicited signaling as a protocol violation that closes its whole * Control connection and every tunnel on it, so such frames are dropped for * the Client to time out and fall back to Relay. */ private forwardSignal(link: Link, peer: Peer, other: Peer, frame: ControlFrame): void { if (link.stage === 'ready') return if (!link.preferredTransports.some(transport => transport !== 'relay')) return if (frame.type === 'signal.offer') { if (peer.id !== link.client) throw new ApiError('INVALID_MESSAGE') } else if (frame.type === 'signal.answer') { if (peer.id !== link.host) throw new ApiError('INVALID_MESSAGE') } else if (frame.type === 'signal.ice') { if (++link.iceCandidates > MAX_ICE_CANDIDATES_PER_CONNECTION) throw new ApiError('INVALID_MESSAGE') } else { throw new ApiError('INVALID_MESSAGE') } this.send(other, frame) } /** * Forward the initiator's transport choice, gated on the transports the * link negotiated. `lan` is downgraded to `p2p` only when the link did not * negotiate `transport.lan` (old RC2 peers), as required by * docs/protocol.md. Relay keeps the legacy compatibility gate. */ private forwardTransportSelected(link: Link, peer: Peer, other: Peer, payload: TransportSelectedPayload): void { // The protocol only lets the initiator (Client) select the transport. A // responder (Host) may also announce its own selection after its RTC data // channel opens; clients ignore it, so ignoring here is compatibility, not // a protocol violation. Throwing would drop the whole link and prevent the // Noise handshake from completing. if (peer.id !== link.client) return if (link.stage !== 'accepted' && link.stage !== 'handshake') throw new ApiError('INVALID_MESSAGE') const transport: TransportName = payload.transport if (!TRANSPORT_NAMES.includes(transport)) throw new ApiError('INVALID_MESSAGE') const selected = transport === 'lan' && !link.preferredTransports.includes('lan') && link.preferredTransports.includes('p2p') ? 'p2p' : transport if (!link.preferredTransports.includes(selected)) throw new ApiError('CAPABILITY_NOT_SUPPORTED') if (selected === 'relay' && !modernHost(other.version)) return this.send(other, selected === transport ? createControlFrame('transport.selected', { ...payload }) : createControlFrame('transport.selected', { ...payload, transport: selected })) } close(): void { if (this.closed) return this.closed = true clearInterval(this.heartbeat) this.logger.info('ws_gateway_closing', { clientCount: this.wss.clients.size }) for (const ws of this.wss.clients) { // Give resumable clients an explicit, unambiguous shutdown signal. A // process restart is different from heartbeat failure (4001) and from // replacement/authentication failures, so clients can retain only the // bounded lease-backed session state. try { if (ws.readyState === WebSocket.OPEN) ws.close(SERVER_SHUTDOWN_CLOSE_CODE, SERVER_SHUTDOWN_CLOSE_REASON) else ws.terminate() } catch { // Force termination below. } const timer = setTimeout(() => { if (ws.readyState !== WebSocket.CLOSED) ws.terminate() }, this.forceTerminateGraceMs) timer.unref() } this.wss.close() } }