import type * as web from "../types/web.ts"; import type { SyncDriver } from "./sync.ts"; import { kNodeInspect, serializeMessage } from "./utils.ts"; export interface PeerContext extends Record {} export interface WaitForDrainOptions { /** * Resolve once {@link Peer.bufferedAmount} drops to or below this many bytes. * * @default 0 */ threshold?: number; /** * Polling interval (in milliseconds) used to re-check {@link Peer.bufferedAmount}. * * @default 100 */ pollInterval?: number; /** * Abort the wait (e.g. `AbortSignal.timeout(ms)`). The returned promise * rejects with the signal's `reason`. */ signal?: AbortSignal; } export interface AdapterInternal { ws: unknown; request: Request; namespace: string; peers?: Set; context?: PeerContext; /** Optional sync backplane used to relay publishes to other instances. */ sync?: SyncDriver; } export abstract class Peer { protected _internal: Internal; protected _topics: Set; protected _id?: string; #ws?: Partial; #pingUnsupportedWarned = false; constructor(internal: Internal) { this._topics = new Set(); this._internal = internal; } get context(): PeerContext { return (this._internal.context ??= {}); } get namespace(): string { return this._internal.namespace; } /** * Unique random [uuid v4](https://developer.mozilla.org/en-US/docs/Glossary/UUID) identifier for the peer. */ get id(): string { if (!this._id) { this._id = crypto.randomUUID(); } return this._id; } /** IP address of the peer */ get remoteAddress(): string | undefined { return undefined; } /** upgrade request */ get request(): Request { return this._internal.request; } /** * Get the [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) instance. * * **Note:** crossws adds polyfill for the following properties if native values are not available: * - `protocol`: Extracted from the `sec-websocket-protocol` header. * - `extensions`: Extracted from the `sec-websocket-extensions` header. * - `url`: Extracted from the request URL (http -> ws). * */ get websocket(): Partial { if (!this.#ws) { const _ws = this._internal.ws as Partial; const _request = this._internal.request; this.#ws = _request ? createWsProxy(_ws, _request) : _ws; } return this.#ws; } /** All connected peers to the server */ get peers(): Set { return this._internal.peers || new Set(); } /** All topics, this peer has been subscribed to. */ get topics(): Set { return this._topics; } /** * Number of bytes queued for transmission but not yet flushed to the client. * * Use this to apply backpressure: pause sending while it grows past a high * watermark and resume once it drops (or on the `drain` hook). Returns `0` on * adapters that do not expose a buffer signal. Refer to the * [compatibility table](https://crossws.h3.dev/guide/peer#compatibility). */ get bufferedAmount(): number { return (this._internal.ws as Partial)?.bufferedAmount ?? 0; } /** * Wait until the send buffer drains to `threshold` bytes (default `0`). * * Resolves immediately when there is no backpressure (or on adapters that do * not expose {@link Peer.bufferedAmount}). Otherwise it polls every * `pollInterval` milliseconds until the buffer drains, also resolving early if * the connection is no longer open so a send loop never hangs on a dropped * client. * * ```ts * for (const chunk of stream) { * peer.send(chunk); * if (peer.bufferedAmount > 1024 * 1024) { * await peer.waitForDrain({ threshold: 256 * 1024 }); * } * } * ``` */ waitForDrain(opts: WaitForDrainOptions = {}): Promise { const threshold = opts.threshold ?? 0; if (this.bufferedAmount <= threshold) { return Promise.resolve(); } const signal = opts.signal; if (signal?.aborted) { return Promise.reject(signal.reason); } return new Promise((resolve, reject) => { const check = () => { // Resolve once drained, or if the socket left the OPEN (1) state — a // closed peer never drains, so this prevents a permanent hang + leak. if (this.bufferedAmount <= threshold || (this.websocket.readyState ?? 1) > 1) { cleanup(); resolve(); } }; const onAbort = () => { cleanup(); reject(signal!.reason); }; const timer = setInterval(check, opts.pollInterval ?? 100); // Don't keep the event loop alive just for a pending drain check. timer.unref?.(); const cleanup = () => { clearInterval(timer); signal?.removeEventListener("abort", onAbort); }; signal?.addEventListener("abort", onAbort, { once: true }); }); } abstract close(code?: number, reason?: string): void; /** Abruptly close the connection */ terminate(): void { this.close(); } /** * Send an application-level WebSocket ping control frame to the client. * * Pair with the {@link Hooks.pong} hook (e.g. embedding a timestamp in * `data`) to measure round-trip latency, or rely on the {@link Hooks.ping} * hook to observe pings the client sends unprompted. * * `data` is optional and, per RFC 6455, must not exceed 125 bytes (a ping is * a control frame); an over-long or otherwise invalid payload is reported via * the {@link Hooks.error} hook instead of being sent. * * **Note:** Not all adapters can send a ping frame; unsupported adapters * warn once and no-op. Refer to the * [compatibility table](https://crossws.h3.dev/guide/peer#compatibility). */ ping(_data?: unknown): number | void | undefined { // Warn once per peer instead of on every call, so a heartbeat loop against // an unsupported adapter can't spam the console. if (!this.#pingUnsupportedWarned) { this.#pingUnsupportedWarned = true; console.warn("[crossws] `peer.ping()` is not supported by this adapter."); } } /** Subscribe to a topic */ subscribe(topic: string): void { this._topics.add(topic); } /** Unsubscribe from a topic */ unsubscribe(topic: string): void { this._topics.delete(topic); } /** Send a message to the peer. */ abstract send(data: unknown, options?: { compress?: boolean }): number | void | undefined; /** * Send a message to subscribers of a topic. * * When a sync backplane is configured, the message is also relayed to the * other crossws instances so their subscribers receive it too. */ publish(topic: string, data: unknown, options?: { compress?: boolean }): void { this._publish(topic, data, options); // Fire-and-forget relay to the other instances. The driver handed in via // `_internal.sync` is the wrapped instance from `adapterUtils`, which // isolates its own publish rejections and routes them to `onError`, so a // transient backplane error never surfaces as an unhandled rejection here. this._internal.sync?.publish({ namespace: this.namespace, topic, data: serializeMessage(data), }); } /** * Adapter-specific, relay-free local fan-out to subscribers of a topic * (excludes this peer). Implemented by each adapter; used both by * {@link Peer.publish} and by the internal cross-instance delivery path. * * @internal Adapter extension point, not part of the stable public API. */ abstract _publish(topic: string, data: unknown, options?: { compress?: boolean }): void; // --- inspect --- toString(): string { return this.id; } [Symbol.toPrimitive](): string { return this.id; } [Symbol.toStringTag](): "WebSocket" { return "WebSocket"; } [kNodeInspect](): unknown { return { peer: { id: this.id, ip: this.remoteAddress, }, }; } } function createWsProxy( ws: Partial, request: Partial, ): Partial { return new Proxy(ws, { get: (target, prop) => { const value = Reflect.get(target, prop); if (!value) { switch (prop) { case "protocol": { return request?.headers?.get("sec-websocket-protocol") || ""; } case "extensions": { return request?.headers?.get("sec-websocket-extensions") || ""; } case "url": { return request?.url?.replace(/^http/, "ws") || undefined; } } } return value; }, }); }