From 7e954df909b78dc6943255706c7b271003b7bc15 Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 14:28:34 +0800 Subject: [PATCH] Import apps/server/src/gateway.ts --- apps/server/src/gateway.ts | 655 +++++++++++++++++++++++++++++++++++++ 1 file changed, 655 insertions(+) create mode 100644 apps/server/src/gateway.ts diff --git a/apps/server/src/gateway.ts b/apps/server/src/gateway.ts new file mode 100644 index 0000000..5639757 --- /dev/null +++ b/apps/server/src/gateway.ts @@ -0,0 +1,655 @@ +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() + } +}