@fishenv/http 0.0.2 → 0.0.4

package/dist/ws/route-builder.js

@@ -0,0 +1,265 @@
+/** Fluent builder for WebSocket routes, layered on the core `RouteBuilder`. */
+import { BadRequestError, DEFAULT_MAX_PAYLOAD_LENGTH, HttpError, requestUpgrade, TooManyRequestsError, } from "../core/index.js";
+import { channel, } from "./channels/channel.js";
+import { channels } from "./channels/handler.js";
+import { isWebSocketUpgrade, negotiateProtocol, UpgradeRequiredError, } from "./helpers.js";
+import { createLifecycle } from "./lifecycle.js";
+import { ConnectionCounter } from "./limits.js";
+import { createOriginPolicy, originSourcesFromCors, } from "./origin.js";
+import { TypedWsConnection } from "./typed.js";
+import { WsCloseCode, WsCloseError, } from "./types.js";
+const ServiceUnavailable = () => new HttpError(503, "Too many open connections");
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry
+ * exactly the same generics as HTTP and SSE routes.
+ *
+ * Handshake order: origin → upgrade headers (426) → subprotocol →
+ * middleware → path params → connection limits → upgrade.
+ */
+export class WsRouteBuilder {
+    #inner;
+    #options;
+    constructor(inner, options = {}) {
+        this.#inner = inner;
+        this.#options = {
+            routerOrigins: [],
+            origins: [],
+            inheritOrigins: true,
+            ...options,
+        };
+    }
+    meta(data) {
+        this.#inner.meta(data);
+        return this;
+    }
+    /**
+     * Add allowed origins on top of the inherited ones (root `cors()` and
+     * `withWs()` options). Pass `{ inherit: false }` to replace them instead.
+     */
+    origin(...args) {
+        const last = args.at(-1);
+        let sources = args;
+        if (last != null && typeof last === "object" && !(last instanceof RegExp)) {
+            sources = args.slice(0, -1);
+            if (last.inherit === false) {
+                this.#options.inheritOrigins = false;
+            }
+        }
+        createOriginPolicy(sources); // validate eagerly: fail at definition time
+        this.#options.origins.push(...sources);
+        return this;
+    }
+    /** Supported subprotocols in preference order; others get `400`. */
+    protocols(list) {
+        if (list.length === 0)
+            throw new Error("protocols(): list is empty");
+        this.#options.protocols = [...list];
+        return this;
+    }
+    /** Per-route inbound limit (closes with `1009`). Must be ≤ the server-wide limit. */
+    maxMessageSize(bytes) {
+        if (!(bytes > 0))
+            throw new Error("maxMessageSize(): must be positive");
+        this.#options.maxMessageSize = bytes;
+        return this;
+    }
+    /** Inbound token bucket per connection. Opt-in. */
+    rateLimit(limit) {
+        if (!(limit.messages > 0) || !(limit.perMs > 0)) {
+            throw new Error("rateLimit(): messages and perMs must be positive");
+        }
+        this.#options.rateLimit = { ...limit };
+        return this;
+    }
+    /** Cap open sockets on this route (`503`) and/or per key (`429`). */
+    maxConnections(limit) {
+        this.#options.maxConnections = limit;
+        return this;
+    }
+    /** Not available on contract routes — the contract owns the params. */
+    param(name, schema) {
+        if (this.#options.contract != null) {
+            throw new Error(`param("${name}"): params of contract routes come from the contract`);
+        }
+        return new WsRouteBuilder(this.#inner.param(name, schema), cloneOptions(this.#options));
+    }
+    with(mw) {
+        return new WsRouteBuilder(this.#inner.with(mw), cloneOptions(this.#options));
+    }
+    /**
+     * Terminal: serve the channel protocol. Every implementation must be
+     * complete (all client events handled, join authorized or `.public()`),
+     * and on contract routes the set must match the socket contract exactly.
+     *
+     * Pass a callback to get a `channel` factory typed with this route's ctx:
+     * `.channels((channel) => [channel(room).join(({ ctx }) => …)])`.
+     */
+    channels(impls, options) {
+        const list = typeof impls === "function"
+            ? impls(channel.withContext())
+            : impls;
+        return this.handleWith(channels(list, options));
+    }
+    /** Terminal: plug in a reusable protocol handler (see `channels()`). */
+    handleWith(handler) {
+        if (handler.protocols != null && this.#options.protocols == null) {
+            this.#options.protocols = [...handler.protocols];
+        }
+        return this.#finish(handler.setup, false, handler.onBuild?.bind(handler));
+    }
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * socket under the key derived from the handshake (e.g. the user id).
+     */
+    subscribe(
+    // biome-ignore lint/suspicious/noExplicitAny: intentional any
+    token, key) {
+        return this.handle((args) => {
+            const socket = args.socket;
+            args.container
+                .get(token)
+                .add(key(args), socket instanceof TypedWsConnection ? socket.connection : socket);
+        });
+    }
+    /**
+     * Terminal. Runs once per socket, after the upgrade. The returned function
+     * (if any) runs when the socket closes.
+     *
+     * `.catch()` on the result only covers failures *before* the upgrade
+     * (origin, middleware, params) — after that, errors close the socket.
+     */
+    handle(fn) {
+        if (this.#options.contract?.kind === "channels") {
+            throw new Error(`${this.#options.contract.path}: channel contracts are implemented with .channels([...])`);
+        }
+        return this.#finish(fn, true);
+    }
+    #finish(fn, typed, onBuild) {
+        const options = cloneOptions(this.#options);
+        const messages = typed ? options.contract?.messages : undefined;
+        const counter = options.maxConnections ? new ConnectionCounter() : null;
+        let policy;
+        let development = false;
+        let logger = console;
+        const route = this.#inner.handle((args) => {
+            const { req } = args;
+            const protocol = options.protocols
+                ? negotiateProtocol(req, options.protocols)
+                : null;
+            const baseArgs = {
+                path: args.path,
+                ctx: args.ctx,
+                req,
+                container: args.container,
+            };
+            // Pre-upgrade connection limits — cheap rejection with a real status.
+            const limit = options.maxConnections;
+            let key = null;
+            if (limit != null && counter != null) {
+                if (limit.total != null && counter.total >= limit.total) {
+                    throw ServiceUnavailable();
+                }
+                if (limit.perKey != null) {
+                    key = limit.perKey.key(baseArgs);
+                    if (counter.count(key) >= limit.perKey.max) {
+                        throw new TooManyRequestsError("Too many connections");
+                    }
+                }
+            }
+            const handlers = createLifecycle(req, protocol, (socket) => fn({
+                socket: messages == null
+                    ? socket
+                    : new TypedWsConnection(socket, messages, () => development),
+                ...baseArgs,
+            }), {
+                maxMessageSize: options.maxMessageSize,
+                rateLimit: options.rateLimit,
+                maxQueuedMessages: options.maxQueuedMessages,
+                development,
+                logger,
+                onOpen: counter == null
+                    ? undefined
+                    : (socket) => {
+                        // Re-check: concurrent handshakes may both have passed above.
+                        const overTotal = limit?.total != null && counter.total >= limit.total;
+                        const overKey = key != null &&
+                            limit?.perKey != null &&
+                            counter.count(key) >= limit.perKey.max;
+                        if (overTotal || overKey) {
+                            throw new WsCloseError(WsCloseCode.TryAgainLater, "Too many connections");
+                        }
+                        socket.onClose(counter.acquire(key));
+                    },
+            });
+            return requestUpgrade(req, {
+                handlers,
+                headers: protocol ? { "Sec-WebSocket-Protocol": protocol } : undefined,
+            });
+        });
+        const definition = route.definition;
+        definition.kind = "ws";
+        definition.guards = [
+            async (req) => {
+                policy ??= createOriginPolicy(resolveOrigins(options, null).sources);
+                if (!(await policy.check(req)))
+                    throw new ForbiddenOrigin();
+                if (!isWebSocketUpgrade(req))
+                    throw new UpgradeRequiredError();
+                if (options.protocols != null &&
+                    negotiateProtocol(req, options.protocols) == null) {
+                    throw new BadRequestError("Unsupported WebSocket subprotocol");
+                }
+            },
+        ];
+        definition.onBuild = (env) => {
+            development = env.development;
+            logger = env.logger;
+            const { sources, wildcard } = resolveOrigins(options, env.cors);
+            if (wildcard) {
+                logger.warn(`[fishenv.ws] ${definition.path}: cors origin "*" is not applied to WebSocket routes (CSWSH); use .origin("any") to allow every origin`);
+            }
+            policy = createOriginPolicy(sources);
+            if (policy.allowsAny) {
+                logger.warn(`[fishenv.ws] ${definition.path}: origin check disabled via .origin("any")`);
+            }
+            const globalMax = env.websocket.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
+            if (options.maxMessageSize != null &&
+                options.maxMessageSize > globalMax) {
+                logger.warn(`[fishenv.ws] ${definition.path}: maxMessageSize ${options.maxMessageSize} exceeds the server-wide maxPayloadLength ${globalMax}; the server limit wins`);
+            }
+            onBuild?.(env, { path: definition.path, contract: options.contract });
+        };
+        return route;
+    }
+}
+/** 403 without detail on which rule failed. */
+class ForbiddenOrigin extends HttpError {
+    constructor() {
+        super(403, "Origin not allowed");
+    }
+    get code() {
+        return "forbidden";
+    }
+}
+function resolveOrigins(options, cors) {
+    if (!options.inheritOrigins) {
+        return { sources: [...options.origins], wildcard: false };
+    }
+    const inherited = originSourcesFromCors(cors);
+    return {
+        sources: [
+            ...inherited.sources,
+            ...options.routerOrigins,
+            ...options.origins,
+        ],
+        wildcard: inherited.wildcard,
+    };
+}
+function cloneOptions(options) {
+    return {
+        ...options,
+        routerOrigins: [...options.routerOrigins],
+        origins: [...options.origins],
+        rateLimit: options.rateLimit ? { ...options.rateLimit } : undefined,
+    };
+}

package/dist/ws/router.d.ts

@@ -0,0 +1,21 @@
+/** The `withWs()` mixin that adds `.ws()` to a core `Router`. */
+import type { AnyWsContract, InferSocket } from "../contract/index.ts";
+import type { BasePathParams, Router } from "../core/index.ts";
+import type { WsConnection } from "./connection.ts";
+import { WsRouteBuilder, type WsRouterOptions } from "./route-builder.ts";
+import type { TypedWsConnection } from "./typed.ts";
+/** The `socket` type handlers get for a contract. */
+export type SocketOf<C extends AnyWsContract> = InferSocket<C>["kind"] extends "messages" ? TypedWsConnection<InferSocket<C>["clientMessage"], InferSocket<C>["serverMessageIn"]> : WsConnection;
+export interface WsRouter<Ctx extends Record<string, unknown>> {
+    ws<P extends string>(path: P): WsRouteBuilder<Ctx, Record<never, never>, BasePathParams<P>>;
+    /** Implement a `c.ws()` contract: path, params and protocol come from it. */
+    ws<C extends AnyWsContract>(contract: C): WsRouteBuilder<Ctx, Record<never, never>, InferSocket<C>["params"], SocketOf<C>, C>;
+}
+/**
+ * `.use()` returns a *new* router, so apply `withWs` last:
+ * `withWs(r({ prefix: "/api" }).use(auth))`.
+ *
+ * `options.origins` are added to the allowed origins of every ws route
+ * registered through this router (on top of the root `cors()` origins).
+ */
+export declare function withWs<Ctx extends Record<string, unknown>, Req extends Record<string, unknown> = Record<never, never>>(router: Router<Ctx, Req>, options?: WsRouterOptions): Router<Ctx, Req> & WsRouter<Ctx>;

package/dist/ws/router.js

@@ -0,0 +1,36 @@
+/** The `withWs()` mixin that adds `.ws()` to a core `Router`. */
+import { createRouteBuilder } from "../core/index.js";
+import { WsRouteBuilder } from "./route-builder.js";
+/**
+ * `.use()` returns a *new* router, so apply `withWs` last:
+ * `withWs(r({ prefix: "/api" }).use(auth))`.
+ *
+ * `options.origins` are added to the allowed origins of every ws route
+ * registered through this router (on top of the root `cors()` origins).
+ */
+export function withWs(router, options = {}) {
+    const target = router;
+    const routerOrigins = [...(options.origins ?? [])];
+    const ws = (pathOrContract) => {
+        if (typeof pathOrContract === "string") {
+            return new WsRouteBuilder(createRouteBuilder(router, "GET", pathOrContract), { routerOrigins: [...routerOrigins] });
+        }
+        const contract = pathOrContract._definition;
+        // biome-ignore lint/suspicious/noExplicitAny: params are typed via the contract
+        let inner = createRouteBuilder(router, "GET", contract.path);
+        for (const [name, schema] of contract.paramSchemas) {
+            inner = inner.param(name, schema);
+        }
+        return new WsRouteBuilder(inner, {
+            routerOrigins: [...routerOrigins],
+            protocols: contract.protocols,
+            contract,
+        });
+    };
+    Object.defineProperty(target, "ws", {
+        value: ws,
+        enumerable: false,
+        configurable: true,
+    });
+    return target;
+}

package/dist/ws/tickets.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Browser-safe handshake authentication.
+ *
+ * Browsers can't set `Authorization` on a WebSocket handshake. Instead of
+ * putting a long-lived token in the URL (where it lands in logs, proxies and
+ * history), an authenticated HTTP call mints a short-lived **single-use**
+ * ticket, and the ws route redeems it:
+ *
+ * ```ts
+ * class SocketTickets extends WsTickets<{ userId: string }> {}
+ *
+ * api.post("/ws-ticket").with(auth).handle(async ({ ctx, container }) =>
+ *   Response.json({ ticket: await container.get(SocketTickets).issue({ userId: ctx.user.id }) }));
+ *
+ * api.ws("/live").with(SocketTickets.middleware()).handle(({ ctx }) => ctx.ticket.userId);
+ * // client: new WebSocket(`wss://host/live?ticket=${ticket}`)
+ * ```
+ */
+import { type MiddlewareFn } from "../core/index.ts";
+/** Storage seam — use Redis (`SET PX` + `GETDEL`) for multi-instance setups. */
+export interface TicketStore {
+    set(id: string, value: string, ttlMs: number): void | Promise<void>;
+    /** Atomically read *and delete*; `null`/`undefined` if absent or expired. */
+    take(id: string): string | null | undefined | Promise<string | null | undefined>;
+}
+/** In-process store with lazy expiry and a hard size cap. */
+export declare class MemoryTicketStore implements TicketStore {
+    #private;
+    constructor(opts?: {
+        maxSize?: number;
+        now?: () => number;
+    });
+    get size(): number;
+    set(id: string, value: string, ttlMs: number): void;
+    take(id: string): string | null;
+}
+export interface WsTicketsOptions {
+    /** Ticket lifetime. Default 30 s. */
+    ttlMs?: number;
+    store?: TicketStore;
+    /** Query parameter read by `middleware()`. Default `"ticket"`. */
+    param?: string;
+    /**
+     * Bind tickets to a request property (e.g. `User-Agent`) to cut replay
+     * value. Compared in constant time; a mismatch still consumes the ticket.
+     */
+    fingerprint?: (req: Request) => string;
+}
+type TicketsToken<T> = abstract new (...args: any[]) => WsTickets<T>;
+/** Payloads must be JSON-serializable (stores hold strings). */
+export declare class WsTickets<T = unknown> {
+    #private;
+    constructor(options?: WsTicketsOptions);
+    /** Mint a ticket. Pass the issuing request when using `fingerprint`. */
+    issue(payload: T, req?: Request): Promise<string>;
+    /** Consume a ticket. `null` if unknown, used, expired or mismatched. */
+    redeem(ticket: string | null | undefined, req?: Request): Promise<T | null>;
+    /** Middleware that redeems `?ticket=` and adds `ctx.ticket`; `401` otherwise. */
+    middleware(): MiddlewareFn<Record<string, unknown>, {
+        ticket: T;
+    }>;
+    /**
+     * Same as {@link WsTickets.middleware}, but resolves the instance from the
+     * DI container on each request: `.with(SocketTickets.middleware())`.
+     */
+    static middleware<T>(this: TicketsToken<T>): MiddlewareFn<Record<string, unknown>, {
+        ticket: T;
+    }>;
+}
+/**
+ * Read a bearer token from `Sec-WebSocket-Protocol: bearer, <token>` — the
+ * one header browsers *can* set on a handshake. Less preferred than tickets
+ * (the token is long-lived), but useful for native clients and dev tools.
+ *
+ * The scheme must be offered **first**: Bun echoes the first offered
+ * subprotocol when the route doesn't negotiate, so this guarantees the
+ * token is never reflected back. Pair it with `.protocols(["bearer"])`.
+ */
+export declare function bearerFromProtocol(scheme?: string): MiddlewareFn<Record<string, unknown>, {
+    bearerToken: string;
+}>;
+export {};

package/dist/ws/tickets.js

@@ -0,0 +1,161 @@
+/**
+ * Browser-safe handshake authentication.
+ *
+ * Browsers can't set `Authorization` on a WebSocket handshake. Instead of
+ * putting a long-lived token in the URL (where it lands in logs, proxies and
+ * history), an authenticated HTTP call mints a short-lived **single-use**
+ * ticket, and the ws route redeems it:
+ *
+ * ```ts
+ * class SocketTickets extends WsTickets<{ userId: string }> {}
+ *
+ * api.post("/ws-ticket").with(auth).handle(async ({ ctx, container }) =>
+ *   Response.json({ ticket: await container.get(SocketTickets).issue({ userId: ctx.user.id }) }));
+ *
+ * api.ws("/live").with(SocketTickets.middleware()).handle(({ ctx }) => ctx.ticket.userId);
+ * // client: new WebSocket(`wss://host/live?ticket=${ticket}`)
+ * ```
+ */
+import { timingSafeEqual } from "node:crypto";
+import { TooManyRequestsError, UnauthorizedError, } from "../core/index.js";
+import { requestedProtocols } from "./helpers.js";
+/** In-process store with lazy expiry and a hard size cap. */
+export class MemoryTicketStore {
+    #entries = new Map();
+    #maxSize;
+    #now;
+    constructor(opts = {}) {
+        this.#maxSize = opts.maxSize ?? 100_000;
+        this.#now = opts.now ?? Date.now;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    set(id, value, ttlMs) {
+        if (this.#entries.size >= this.#maxSize)
+            this.#sweep();
+        if (this.#entries.size >= this.#maxSize) {
+            throw new TooManyRequestsError("Too many outstanding tickets");
+        }
+        this.#entries.set(id, { value, expires: this.#now() + ttlMs });
+    }
+    take(id) {
+        const entry = this.#entries.get(id);
+        if (entry == null)
+            return null;
+        this.#entries.delete(id);
+        return entry.expires > this.#now() ? entry.value : null;
+    }
+    #sweep() {
+        const now = this.#now();
+        for (const [id, entry] of this.#entries) {
+            if (entry.expires <= now)
+                this.#entries.delete(id);
+        }
+    }
+}
+/** 32 random bytes, base64url → 43 chars. */
+const TICKET_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+function newTicketId() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    return Buffer.from(bytes).toString("base64url");
+}
+function digest(value) {
+    return Buffer.from(new Bun.CryptoHasher("sha256").update(value).digest());
+}
+/** Payloads must be JSON-serializable (stores hold strings). */
+export class WsTickets {
+    #ttlMs;
+    #store;
+    #param;
+    #fingerprint;
+    constructor(options = {}) {
+        this.#ttlMs = options.ttlMs ?? 30_000;
+        this.#store = options.store ?? new MemoryTicketStore();
+        this.#param = options.param ?? "ticket";
+        this.#fingerprint = options.fingerprint;
+    }
+    /** Mint a ticket. Pass the issuing request when using `fingerprint`. */
+    async issue(payload, req) {
+        const id = newTicketId();
+        const record = { p: payload };
+        if (this.#fingerprint != null) {
+            if (req == null) {
+                throw new Error("WsTickets.issue(): fingerprint requires the request");
+            }
+            record.f = digest(this.#fingerprint(req)).toString("base64");
+        }
+        await this.#store.set(id, JSON.stringify(record), this.#ttlMs);
+        return id;
+    }
+    /** Consume a ticket. `null` if unknown, used, expired or mismatched. */
+    async redeem(ticket, req) {
+        if (ticket == null || !TICKET_PATTERN.test(ticket))
+            return null;
+        const raw = await this.#store.take(ticket);
+        if (raw == null)
+            return null;
+        let record;
+        try {
+            record = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (record.f != null) {
+            if (this.#fingerprint == null || req == null)
+                return null;
+            const expected = Buffer.from(record.f, "base64");
+            const actual = digest(this.#fingerprint(req));
+            if (expected.byteLength !== actual.byteLength ||
+                !timingSafeEqual(expected, actual)) {
+                return null;
+            }
+        }
+        return record.p;
+    }
+    /** Middleware that redeems `?ticket=` and adds `ctx.ticket`; `401` otherwise. */
+    middleware() {
+        return async ({ req }) => {
+            const ticket = new URL(req.url).searchParams.get(this.#param);
+            const payload = await this.redeem(ticket, req);
+            if (payload == null) {
+                throw new UnauthorizedError("Invalid or expired ticket");
+            }
+            return { ticket: payload };
+        };
+    }
+    /**
+     * Same as {@link WsTickets.middleware}, but resolves the instance from the
+     * DI container on each request: `.with(SocketTickets.middleware())`.
+     */
+    static middleware() {
+        return (ctx) => {
+            const container = ctx.container;
+            if (container == null) {
+                throw new Error("WsTickets.middleware(): no DI container available");
+            }
+            // `this` is the subclass the method was called on — the DI token.
+            // biome-ignore lint/complexity/noThisInStatic: intentional, see above
+            return container.get(this).middleware()(ctx);
+        };
+    }
+}
+/**
+ * Read a bearer token from `Sec-WebSocket-Protocol: bearer, <token>` — the
+ * one header browsers *can* set on a handshake. Less preferred than tickets
+ * (the token is long-lived), but useful for native clients and dev tools.
+ *
+ * The scheme must be offered **first**: Bun echoes the first offered
+ * subprotocol when the route doesn't negotiate, so this guarantees the
+ * token is never reflected back. Pair it with `.protocols(["bearer"])`.
+ */
+export function bearerFromProtocol(scheme = "bearer") {
+    return ({ req }) => {
+        const [first, token, ...rest] = requestedProtocols(req);
+        if (first !== scheme || token == null || token === "" || rest.length > 0) {
+            throw new UnauthorizedError("Missing bearer subprotocol");
+        }
+        return { bearerToken: token };
+    };
+}

package/dist/ws/typed.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A contract-typed view of a {@link WsConnection} for `c.ws().messages()`
+ * sockets: inbound JSON is validated against the client schema, outbound
+ * messages are typed (and validated in development).
+ */
+import * as v from "valibot";
+import type { AnySchema } from "../core/index.ts";
+import type { WsCloseListener, WsConnection } from "./connection.ts";
+import type { WsMessage } from "./message.ts";
+import { type WsCleanupFn, type WsSendResult } from "./types.ts";
+/** Thrown in development when the server sends something off-contract. */
+export declare class ContractViolationError extends Error {
+    readonly issues: v.BaseIssue<unknown>[];
+    constructor(what: string, issues: v.BaseIssue<unknown>[]);
+}
+/**
+ * Validate an inbound payload. Failure is the *client's* fault → protocol
+ * error (`1008`); the reason names the first issue only in development.
+ */
+export declare function parseInbound<S extends AnySchema>(schema: S, value: unknown, development: boolean): v.InferOutput<S>;
+/**
+ * In development, validate an outbound payload so contract drift surfaces
+ * immediately. A no-op in production (types are the guarantee there).
+ */
+export declare function checkOutbound(schema: AnySchema | undefined, value: unknown, development: boolean, what: string): void;
+export declare class TypedWsConnection<In, Out> {
+    #private;
+    /** The untyped connection — pass this to hubs. */
+    readonly connection: WsConnection;
+    /** @internal Created by contract routes. */
+    constructor(connection: WsConnection, schemas: {
+        client: AnySchema;
+        server: AnySchema;
+    }, development: () => boolean);
+    get id(): string;
+    get req(): Request;
+    get protocol(): string | null;
+    get closed(): boolean;
+    get remoteAddress(): string;
+    get bufferedBytes(): number;
+    get data(): Record<string, unknown>;
+    set data(value: Record<string, unknown>);
+    /**
+     * Validated inbound messages. Non-JSON or off-contract input closes the
+     * socket with `1008` before `fn` runs.
+     */
+    onMessage(fn: (data: In, message: WsMessage) => unknown): () => void;
+    /** JSON-encode and send. Validated against the server schema in development. */
+    send(data: Out): WsSendResult;
+    close(code?: number, reason?: string): void;
+    expireAt(when: Date | number): void;
+    onClose(fn: WsCloseListener | WsCleanupFn): void;
+    onDrain(fn: () => void): () => void;
+}