tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/websocket.d.ts

@@ -0,0 +1,402 @@
+/**
+ * Tina4 WebSocket — Zero-dependency RFC 6455 implementation.
+ *
+ * Native WebSocket server using Node.js built-in `http` module.
+ *
+ *   import { WebSocketServer } from "@tina4/core";
+ *
+ *   const wss = new WebSocketServer({ port: 8080 });
+ *   wss.on("open", (client) => {
+ *     console.log("Connected:", client.id);
+ *   });
+ *   wss.on("message", (client, message) => {
+ *     wss.broadcast(message);
+ *   });
+ *   await wss.start();
+ *
+ * Supported:
+ *   - HTTP Upgrade handshake (RFC 6455 Sec-WebSocket-Accept)
+ *   - Frame protocol: text, binary, close, ping, pong
+ *   - Masking / unmasking (client->server)
+ *   - Extended payload lengths (7-bit, 16-bit, 64-bit)
+ *   - Connection manager with broadcast
+ */
+import { IncomingMessage } from "node:http";
+import type { Socket } from "node:net";
+import type { WebSocketConnection } from "./websocketConnection.js";
+export declare const OP_CONTINUATION = 0;
+export declare const OP_TEXT = 1;
+export declare const OP_BINARY = 2;
+export declare const OP_CLOSE = 8;
+export declare const OP_PING = 9;
+export declare const OP_PONG = 10;
+export declare const CLOSE_NORMAL = 1000;
+export declare const CLOSE_GOING_AWAY = 1001;
+export declare const CLOSE_PROTOCOL_ERROR = 1002;
+export declare const CLOSE_POLICY_VIOLATION = 1008;
+export interface WebSocketClient {
+    id: string;
+    socket: Socket;
+    ip: string;
+    connectedAt: number;
+    closed: boolean;
+    /** The URL path this client connected on (e.g. "/chat", "/notifications"). */
+    path: string;
+    /**
+     * Epoch ms of the last inbound frame. Updated on every frame; the idle
+     * reaper closes connections silent longer than `TINA4_WS_IDLE_TIMEOUT`
+     * (opt-in). Optional so externally-injected/legacy client objects still fit.
+     */
+    lastActivity?: number;
+    /**
+     * Verified JWT payload when this client connected on a secured WS route, or
+     * `null` on a public route. Mirrors Python's `connection.auth`. Optional so
+     * externally-injected/legacy client objects still fit.
+     */
+    auth?: Record<string, unknown> | null;
+}
+/**
+ * Compute Sec-WebSocket-Accept from Sec-WebSocket-Key per RFC 6455.
+ */
+/**
+ * Build an RFC 6455 close frame carrying a status code and optional reason.
+ *
+ * The code is a big-endian uint16 in the first two payload bytes (s5.5.1), so
+ * a peer that only reads the code still gets a valid one.
+ */
+export declare function buildCloseFrame(code: number, reason?: string): Buffer;
+export declare function computeAcceptKey(key: string): string;
+/**
+ * Return true if the upgrade request's `Origin` is permitted.
+ *
+ * Controlled by `TINA4_WS_ALLOWED_ORIGINS` (comma-separated list of exact
+ * origins, e.g. `https://app.example.com,https://admin.example.com`).
+ *
+ * Empty/unset = allow ALL origins (current behaviour, non-breaking). When set,
+ * only requests whose `Origin` header exactly matches a listed value are
+ * allowed; a missing `Origin` header is rejected once the allow-list is active.
+ * Header lookup is case-insensitive on the key (Node lowercases header keys,
+ * but the helper also checks an exact `Origin` so it works with raw maps too).
+ */
+export declare function originAllowed(headers: Record<string, string | string[] | undefined>): boolean;
+/**
+ * Extract a bearer token from a WebSocket upgrade handshake.
+ *
+ * Order (mirrors Python's `ws_token`): the `Authorization: Bearer` header (set
+ * by server/CLI/mobile clients), then the `Sec-WebSocket-Protocol` subprotocol
+ * in the form `"bearer, <token>"` (the only way a *browser* can pass a token,
+ * since `new WebSocket()` cannot set headers), then a `?token=` query param.
+ * Returns the token string or `null`.
+ *
+ * @param headers       - Upgrade-request headers (case-insensitive lookup).
+ * @param queryString   - Raw query string (without the leading `?`), e.g. `token=abc`.
+ * @param subprotocol   - The offered `Sec-WebSocket-Protocol` value, if already parsed out.
+ */
+export declare function wsToken(headers: Record<string, string | string[] | undefined>, queryString?: string, subprotocol?: string): string | null;
+/**
+ * Per-route WebSocket authentication, checked on the upgrade.
+ *
+ * A route is secured when `authRequired` is truthy (set by `.secure()` /
+ * `{ secured: true }` on the WS route, or a `_secured` flag on the handler).
+ * Public routes (the default) always pass. A secured route needs a valid JWT
+ * via the Authorization header, the `bearer` subprotocol, or `?token=`.
+ *
+ * Returns `[payload, ok]` — the verified token payload (or `null`) and whether
+ * the upgrade may proceed. Mirrors Python's `ws_authorized`.
+ */
+export declare function wsAuthorized(route: {
+    authRequired?: boolean;
+} | null | undefined, headers: Record<string, string | string[] | undefined>, queryString?: string, subprotocol?: string): [Record<string, unknown> | null, boolean];
+/**
+ * Whether the client offered the `bearer` subprotocol — if so, the server MUST
+ * echo `bearer` back as the accepted `Sec-WebSocket-Protocol` in the handshake
+ * (RFC 6455 §1.3; browsers send the token as the second subprotocol token).
+ */
+export declare function offeredBearerSubprotocol(subprotocol: string): boolean;
+/**
+ * Parse HTTP headers from raw upgrade request data.
+ */
+export declare function parseUpgradeHeaders(raw: string): Record<string, string>;
+/**
+ * Build a WebSocket frame (server->client, never masked).
+ */
+export declare function buildFrame(opcode: number, payload: Buffer, fin?: boolean): Buffer;
+/**
+ * Parse a WebSocket frame from a buffer.
+ * Returns { fin, opcode, payload, bytesConsumed } or null if not enough data.
+ */
+export declare function parseFrame(data: Buffer): {
+    fin: boolean;
+    opcode: number;
+    payload: Buffer;
+    bytesConsumed: number;
+} | null;
+export declare class WebSocketServer {
+    private port;
+    private server;
+    private clients;
+    private handlers;
+    /** rooms[roomName] = Set of clientIds */
+    private rooms;
+    /** clientRooms[clientId] = Set of roomNames */
+    private clientRooms;
+    /** Route-style handlers registered via route(), keyed by path */
+    private _routeHandlers;
+    /**
+     * Backplane (multi-instance scaling). Lazily wired on the first broadcast
+     * via {@link ensureBackplane}. Each instance owns a stable id so it can
+     * ignore its own echoes coming back over the shared pub/sub channel.
+     */
+    private backplane;
+    /** Set once ensureBackplane() has fired so we only attempt the wiring once. */
+    private backplaneStarted;
+    /** Idle-connection reaper timer (opt-in via TINA4_WS_IDLE_TIMEOUT). */
+    private reaperTimer;
+    constructor(options?: {
+        port?: number;
+    });
+    /** Test/diagnostic helper: this instance's stable backplane id. */
+    get instanceId(): string;
+    /**
+     * Register an event handler.
+     */
+    on(event: string, handler: Function): WebSocketServer;
+    /**
+     * Register a WebSocket handler for a path (decorator style, matches Python).
+     *
+     * The handler receives a WebSocketConnection and sets up callbacks via
+     * `conn.onMessage(handler)` and `conn.onClose(handler)`.
+     *
+     * Internally this creates an adapter that converts from the decorator style
+     * to the Router's `(conn, event, data)` style and registers it via
+     * `Router.websocket()`.
+     */
+    route(path: string, handler: (conn: WebSocketConnection) => void | Promise<void>, options?: {
+        secured?: boolean;
+    }): void;
+    /**
+     * Broadcast a message to all connected clients.
+     *
+     * When `path` is provided, only clients connected on that specific path
+     * receive the message (matching PHP's WebSocket::broadcast behaviour).
+     * When `path` is omitted/undefined, all clients receive the message
+     * (backward compatible).
+     */
+    broadcast(message: string | Buffer, excludeIds?: string[], path?: string): void;
+    /**
+     * Send a message to a specific client by ID.
+     *
+     * Local-only: a connection lives on exactly one instance, so there is
+     * nothing to fan out over the backplane.
+     */
+    sendTo(clientId: string, message: string | Buffer): void;
+    /**
+     * Start the WebSocket server.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server and disconnect all clients.
+     */
+    stop(): void;
+    /**
+     * Get all connected clients.
+     */
+    getClients(): Map<string, WebSocketClient>;
+    /**
+     * Close a specific client connection with an optional code and reason.
+     */
+    close(clientId: string, code?: number, reason?: string): void;
+    /**
+     * Add a client to a named room.
+     */
+    joinRoom(clientId: string, roomName: string): void;
+    /**
+     * Remove a client from a named room.
+     */
+    leaveRoom(clientId: string, roomName: string): void;
+    /**
+     * Return the list of client IDs in a room.
+     */
+    getRoomConnections(roomName: string): string[];
+    /**
+     * Return the number of clients in a room.
+     */
+    roomCount(roomName: string): number;
+    /**
+     * Return the names of all rooms a client has joined.
+     */
+    getClientRooms(clientId: string): string[];
+    /**
+     * Broadcast a message to all clients in a room.
+     *
+     * Resilient to dead clients (a failed send prunes the client, never aborts
+     * the loop) and fans out to sibling instances over the backplane when
+     * configured — a room can span instances, so each one delivers to its own
+     * members.
+     */
+    broadcastToRoom(roomName: string, message: string | Buffer, excludeIds?: string[]): void;
+    private emit;
+    /** Lazily wire the backplane on the first broadcast. Idempotent. */
+    private ensureBackplane;
+    /**
+     * Deliver a remote-originated envelope to LOCAL connections only. NEVER
+     * re-publishes (that would loop the message around the cluster). Dispatches
+     * by `kind`: room / path / all.
+     */
+    private relayLocal;
+    /**
+     * Send to ONE client without letting a single dead/slow client abort a
+     * broadcast loop. A write failure (or an already-closed client) is logged
+     * and the client is pruned. Returns true if the frame was handed to the
+     * socket.
+     *
+     * Slow-client backpressure: `socket.write()` returns false when the kernel
+     * send buffer is full. We don't unboundedly buffer — a client whose backlog
+     * has blown past TINA4_WS_MAX_BACKLOG bytes is hopelessly behind, so we drop
+     * and close it rather than let it grow the process heap without bound.
+     */
+    private safeSend;
+    /** Remove a client from the manager, rooms, and close its socket. */
+    private pruneClient;
+    /**
+     * Close connections whose last inbound frame is older than `timeoutSeconds`.
+     * Returns the number reaped. `timeoutSeconds <= 0` is a no-op (the reaper is
+     * opt-in via TINA4_WS_IDLE_TIMEOUT).
+     */
+    reapIdle(timeoutSeconds: number): number;
+    /**
+     * Spin up the idle-connection reaper when TINA4_WS_IDLE_TIMEOUT is a
+     * positive number of seconds. Opt-in and non-breaking — unset/0 means no
+     * timer is created at all (current behaviour). Called from start().
+     */
+    private startIdleReaper;
+    private handleUpgrade;
+    private processBuffer;
+    private removeClientFromAllRooms;
+}
+/** A live route connection in the integrated server. */
+interface RouteConnState {
+    conn: WebSocketConnection;
+    socket: Socket;
+    path: string;
+    rooms: Set<string>;
+    closed: boolean;
+    /** Optional dev-admin tracker id so the connection shows in the websockets list. */
+    trackerId?: string;
+}
+/**
+ * Process-wide manager for user WebSocket route connections served by the
+ * integrated server. Path-scoped broadcast + rooms mirror the standalone
+ * WebSocketServer semantics so a route handler behaves the same either way.
+ */
+declare class WsRouteManager {
+    private connections;
+    private rooms;
+    private onAdd?;
+    private onRemove?;
+    /** Wire dev-admin tracking callbacks (WsTracker.add / WsTracker.remove). */
+    setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void;
+    /** Currently-open route connections (test/diagnostic helper). */
+    get size(): number;
+    add(state: RouteConnState): void;
+    remove(id: string): void;
+    /**
+     * Close every open route connection with an RFC 6455 status code.
+     *
+     * Used by graceful shutdown with 1001 "going away", which is the code RFC
+     * 6455 s7.4.1 defines for exactly this case ("a server going down"). A
+     * client that is told 1001 can reconnect on a schedule; a socket that just
+     * vanishes looks like a network fault and produces an error instead.
+     *
+     * Best-effort per connection: a dead socket is skipped, never aborting the
+     * rest. Returns how many were signalled.
+     */
+    closeAll(code?: number, reason?: string): number;
+    /** Send a text frame to one connection (best-effort). */
+    sendTo(id: string, message: string): void;
+    /** Broadcast a text frame to every connection on the same path. */
+    broadcastPath(path: string, message: string): void;
+    joinRoom(id: string, room: string): void;
+    leaveRoom(id: string, room: string): void;
+    /**
+     * The live connections currently in a room (open only). Returns the
+     * WebSocketConnection objects so callers can read each `.auth` (presence
+     * rosters). Mirrors Python's mgr.get_room_connections / PHP getRoomConnections.
+     */
+    getRoomConnections(room: string): WebSocketConnection[];
+    /**
+     * Broadcast a text frame to every connection in a room, optionally skipping
+     * one connection id (self-exclusion). A dead/slow socket is skipped, never
+     * aborting the rest.
+     */
+    broadcastToRoom(room: string, message: string, excludeId?: string): void;
+}
+/** Process-wide manager for integrated-server user WS route connections. */
+export declare const wsRouteManager: WsRouteManager;
+/**
+ * Serve a user WebSocket route on the integrated server's `upgrade` event.
+ *
+ * This is the second half of per-route WS auth in Node: it's the entry point
+ * that wires a user-registered WS route (the WS route table) into the integrated
+ * server so the route actually gets a live open/message/close lifecycle on a
+ * real connection — parity with Python/PHP/Ruby — AND enforces per-route auth.
+ *
+ * Order mirrors Python's `_handle_dev_websocket` / `_handle_asgi_websocket`:
+ *   1. require a Sec-WebSocket-Key (else 400);
+ *   2. origin allow-list (else 403) — TINA4_WS_ALLOWED_ORIGINS, unset = allow all;
+ *   3. per-route auth (else 401) — public by default, secured needs a valid JWT;
+ *   4. accept the handshake, echoing `bearer` when offered;
+ *   5. build the connection (conn.auth = payload), fire "open", then pump
+ *      frames into "message" / "close".
+ *
+ * Returns true if a matching route was found and handled (accepted OR rejected),
+ * false if no WS route matched this path (caller falls through to its 404).
+ */
+export declare function serveWebSocketRoute(req: IncomingMessage, socket: Socket, head: Buffer): boolean;
+/**
+ * Connection manager for the dev-reload channel (`/__dev_reload`).
+ *
+ * Mirrors Python's `_ws_manager` scoped to `/__dev_reload`: it accepts the
+ * RFC 6455 handshake on the *main* dev server's HTTP `upgrade` event, holds the
+ * raw sockets open, and lets `POST /__dev/api/reload` push an instant reload to
+ * every connected browser via {@link broadcast}. The framework never reads from
+ * the client — the open socket is the whole point. This restores the documented
+ * WebSocket-primary DevReload design (the dev toolbar and dev-admin dashboard
+ * both connect here). Registered only when `TINA4_DEBUG` is on, and never on the
+ * stable AI port.
+ */
+declare class DevReloadWsManager {
+    private clients;
+    /** Optional hooks (add/remove) so the dev-admin connection list stays in sync. */
+    private onAdd?;
+    private onRemove?;
+    /** Wire dev-admin tracking callbacks (WsTracker.add / WsTracker.remove). */
+    setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void;
+    /** Number of currently-open dev-reload sockets (test/diagnostic helper). */
+    get size(): number;
+    /**
+     * Close every open dev-reload socket with an RFC 6455 status code (1001
+     * "going away" on shutdown). The browser client reconnects on a schedule
+     * when it is told the server went away, rather than reporting an error.
+     * Best-effort per socket. Returns how many were signalled.
+     */
+    closeAll(code?: number, reason?: string): number;
+    /**
+     * Accept a WebSocket upgrade on `/__dev_reload` and hold the socket open.
+     *
+     * Completes the RFC 6455 handshake, registers the connection, and drains
+     * inbound frames — responding to pings and cleaning up on close — without
+     * ever interpreting client data. Returns true if the handshake was accepted.
+     */
+    handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): boolean;
+    /**
+     * Broadcast a text frame to every connected dev-reload client.
+     *
+     * Best-effort: a dead socket is dropped silently. Never throws — the caller
+     * (`POST /__dev/api/reload`) must not 500 because a browser tab went away.
+     */
+    broadcast(message: string): void;
+}
+/** Process-wide dev-reload manager (one channel: `/__dev_reload`). */
+export declare const devReloadWs: DevReloadWsManager;
+export {};

package/types/core/src/websocketBackplane.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Base interface for scaling WebSocket broadcast across instances.
+ *
+ * Implementations relay messages over a shared bus so every server instance
+ * receives every broadcast, not just the originator.
+ */
+export interface WebSocketBackplane {
+    /** Publish a message to all instances listening on `channel`. */
+    publish(channel: string, message: string): Promise<void>;
+    /** Subscribe to `channel`. `callback` is invoked with each incoming message. */
+    subscribe(channel: string, callback: (message: string) => void): Promise<void>;
+    /** Stop listening on `channel`. */
+    unsubscribe(channel: string): Promise<void>;
+    /** Tear down connections. */
+    close(): Promise<void>;
+}
+/**
+ * Redis pub/sub backplane.
+ *
+ * Requires the `redis` package (`npm install redis`). The import is deferred
+ * so the rest of Tina4 works fine without it installed — an error is thrown
+ * only when this class is actually instantiated.
+ */
+export declare class RedisBackplane implements WebSocketBackplane {
+    private publisher;
+    private subscriber;
+    private url;
+    private ready;
+    constructor(url?: string);
+    publish(channel: string, message: string): Promise<void>;
+    subscribe(channel: string, callback: (message: string) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * NATS pub/sub backplane.
+ *
+ * Requires the `nats` package (`npm install nats`). The import is deferred
+ * so the rest of Tina4 works fine without it installed — an error is thrown
+ * only when this class is actually instantiated.
+ *
+ * NATS is async-native. The subscription listener runs via the NATS client's
+ * built-in async iteration.
+ */
+export declare class NATSBackplane implements WebSocketBackplane {
+    private nc;
+    private url;
+    private subs;
+    private ready;
+    constructor(url?: string);
+    publish(channel: string, message: string): Promise<void>;
+    subscribe(channel: string, callback: (message: string) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Factory that reads TINA4_WS_BACKPLANE and returns the appropriate
+ * backplane instance, or `null` if no backplane is configured.
+ *
+ * This keeps backplane usage entirely optional — callers simply check
+ * `if (backplane)` before publishing.
+ */
+export declare function createBackplane(url?: string): WebSocketBackplane | null;
+/**
+ * The shared pub/sub channel name. Identical across all four Tina4 frameworks
+ * (cross-framework constant parity) so a Python, PHP, Ruby and Node instance
+ * can all relay each other's broadcasts over the same bus.
+ */
+export declare const WS_BACKPLANE_CHANNEL = "tina4:ws";
+/** What `kind` a broadcast envelope carries — mirrors the master design. */
+export type WsEnvelopeKind = "all" | "path" | "room";
+/**
+ * The JSON envelope published to the backplane channel. The wire shape is
+ * identical across all four frameworks. JSON can't carry bytes, so a string
+ * message rides under `text` and a binary message rides under `b64`
+ * (base64 of the bytes).
+ */
+export interface WsEnvelope {
+    /** Stable per-process instance id of the publisher (for the origin guard). */
+    src: string;
+    /** Delivery kind: every local conn / a path / a room. */
+    kind: WsEnvelopeKind;
+    /** Optional connection id to skip on delivery. */
+    exclude?: string | null;
+    /** Room name (only when kind === "room"). */
+    room?: string | null;
+    /** Path (only when kind === "path"). */
+    path?: string | null;
+    /** Text payload (str messages). */
+    text?: string;
+    /** Base64 payload (binary messages). */
+    b64?: string;
+}
+/**
+ * Wires a {@link WebSocketBackplane} into a local connection manager so a
+ * broadcast on one server instance reaches the local connections of every
+ * sibling instance.
+ *
+ * Node is single-threaded async, so — unlike Python's bg-thread →
+ * `run_coroutine_threadsafe` bridge — the subscribe callback can relay
+ * directly on the event loop. We still apply the two invariants that keep a
+ * cluster correct:
+ *
+ *   1. **Origin guard** — drop any envelope whose `src` is *this* instance's
+ *      id. We already delivered it locally on broadcast; relaying it again
+ *      would double-send.
+ *   2. **No re-publish** — the relay path only delivers to LOCAL connections;
+ *      it never publishes, so a message can't loop around the cluster.
+ *
+ * The manager is generic over the local-delivery callback (`relay`) so it can
+ * sit beside the WebSocketServer without importing it (no module cycle).
+ */
+export declare class WsBackplaneManager {
+    /** Stable per-process id so we can ignore our own echoes. */
+    readonly instanceId: string;
+    readonly channel: string;
+    private backplane;
+    private started;
+    /** Local-delivery callback, installed by the owner (WebSocketServer). */
+    private relay;
+    constructor(channel?: string);
+    /** True once a backplane is actually attached (a network bus is configured). */
+    get active(): boolean;
+    /**
+     * Lazily wire the configured backplane and subscribe. Idempotent and
+     * best-effort — a failure here logs and leaves the manager in local-only
+     * mode; it must NEVER crash a broadcast. The `relay` callback is invoked
+     * (on this same event loop) for every *remote* envelope that survives the
+     * origin guard.
+     */
+    ensure(relay: (env: WsEnvelope) => void, log?: WsBackplaneLogger): Promise<void>;
+    /**
+     * Handle a raw envelope arriving on the channel. Applies the origin guard
+     * then hands a *remote* envelope to the local relay. Never throws (a
+     * malformed envelope is dropped silently).
+     */
+    onMessage(raw: string): void;
+    /**
+     * Publish a broadcast to the shared channel for sibling instances. No-op
+     * when no backplane is configured. Best-effort — a publish failure logs and
+     * is swallowed so the local broadcast that already happened is never undone
+     * by a flaky message bus.
+     */
+    publish(kind: WsEnvelopeKind, message: string | Buffer, opts?: {
+        room?: string | null;
+        path?: string | null;
+        exclude?: string | null;
+    }, log?: WsBackplaneLogger): void;
+    /**
+     * Reconstruct the original str/Buffer message from an envelope. JSON can't
+     * carry bytes, so `text` → string and `b64` → Buffer.
+     */
+    static decodeMessage(env: WsEnvelope): string | Buffer | null;
+}
+/** Minimal logger shape so the manager doesn't import the logger module. */
+export interface WsBackplaneLogger {
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+/** Build the cross-framework envelope. Exported for tests. */
+export declare function buildEnvelope(src: string, kind: WsEnvelopeKind, message: string | Buffer, opts?: {
+    room?: string | null;
+    path?: string | null;
+    exclude?: string | null;
+}): WsEnvelope;

package/types/core/src/websocketConnection.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Represents a WebSocket connection with send/broadcast/close capabilities.
+ * Used by Router.websocket() route handlers.
+ */
+export interface WebSocketConnection {
+    /** Unique connection identifier */
+    id: string;
+    /** The WebSocket route path this connection is on */
+    path: string;
+    /** Client IP address */
+    ip: string;
+    /** HTTP headers from the upgrade request */
+    headers: Record<string, string>;
+    /** Route parameters extracted from `{param}` segments in the path */
+    params: Record<string, string>;
+    /**
+     * Verified JWT payload on a `@secured` / `.secure()` WebSocket route, or
+     * `null` on a public route (the default). Set on the upgrade after the token
+     * is validated — mirrors Python's `connection.auth`.
+     */
+    auth: Record<string, unknown> | null;
+    /** Send a message to this connection only */
+    send(message: string): void;
+    /** Serialize an object to JSON and send it to this connection. Parity with Python/PHP. */
+    sendJson(data: unknown): void;
+    /** Broadcast a message to all connections on the same path (path-scoped) */
+    broadcast(message: string): void;
+    /**
+     * Broadcast a message to every connection in a room. Pass `excludeSelf: true`
+     * to skip this connection (the common signalling/chat relay case). Mirrors
+     * Python `connection.broadcast_to_room(room, msg, exclude_self=...)`.
+     */
+    broadcastToRoom(roomName: string, message: string, excludeSelf?: boolean): void;
+    /**
+     * The live connections currently in a room (for presence rosters — read each
+     * returned connection's `.auth`). Mirrors the manager room enumeration used
+     * by the Python/PHP/Ruby realtime rosters.
+     */
+    getRoomConnections(roomName: string): WebSocketConnection[];
+    /** Join a room */
+    joinRoom(roomName: string): void;
+    /** Leave a room */
+    leaveRoom(roomName: string): void;
+    /** Close this connection */
+    close(): void;
+    /** Internal message callback, set via onMessage(). */
+    _onMessage: ((data: string) => void | Promise<void>) | null;
+    /** Internal close callback, set via onClose(). */
+    _onClose: (() => void | Promise<void>) | null;
+    /** Register a message handler (decorator style, matches Python). */
+    onMessage(handler: (data: string) => void | Promise<void>): void;
+    /** Register a close handler (decorator style, matches Python). */
+    onClose(handler: () => void | Promise<void>): void;
+}