@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/websocket/WebSockets.js

@@ -0,0 +1,194 @@
+import { WebSocketServer } from 'ws';
+import { WebSocketConnection } from './WebSocketConnection.js';
+import { WebSocketChannels } from './WebSocketChannels.js';
+/** App-owned WebSocket endpoints on an existing Node HTTP/S listener. */
+export class WebSockets {
+    app;
+    options;
+    /** Process-local, server-authorized channels. Each delivery rechecks the connection's policy. */
+    channels = new WebSocketChannels();
+    #close;
+    #connections = new Map();
+    #presenceListeners = new Map();
+    #closed = false;
+    /** Configures worker HTTP delivery without opening a connection or starting a polling loop. */
+    constructor(app, options = {}) {
+        this.app = app;
+        this.options = options;
+        if (options.publish) {
+            const { url, token, timeoutMs = 5000 } = options.publish;
+            const target = new URL(url);
+            if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.hash || target.search)
+                throw new Error('Use a trusted HTTP(S) publishing URL without credentials, query or fragment.');
+            if (!/^[A-Za-z0-9_-]{32,256}$/.test(token))
+                throw new Error('WebSocket publish token must contain 32 to 256 URL-safe characters.');
+            if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+                throw new Error('Invalid WebSocket publish timeout.');
+        }
+    }
+    /** Returns a publisher for a concrete authorized resource channel. No client subscription is created. */
+    channel(name) {
+        if (name.length > 256 || !/^[a-zA-Z0-9_.-]+(?::[a-zA-Z0-9_.-]+)*$/.test(name))
+            throw new Error('Invalid channel name.');
+        return { publish: async (event, data) => {
+                if (!event || event.length > 256)
+                    throw new Error('Invalid channel event.');
+                if (this.#closed)
+                    throw new Error('WebSocket service is closed.');
+                const message = JSON.stringify({ channel: name, event, data });
+                if (Buffer.byteLength(message) > 65536)
+                    throw new Error('WebSocket event exceeds 64 KiB.');
+                if (!this.#close && this.options.publish) {
+                    const { url, token, timeoutMs = 5000 } = this.options.publish;
+                    const response = await fetch(url, {
+                        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+                        headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: message,
+                    });
+                    try {
+                        if (!response.ok)
+                            throw new Error(`WebSocket publishing failed (${response.status}).`);
+                        // HTTP acceptance is not a browser delivery receipt or a remote connection count.
+                        return 0;
+                    }
+                    finally {
+                        await response.body?.cancel();
+                    }
+                }
+                return this.channels.publishEvent(name, event, data);
+            } };
+    }
+    /**
+     * Mounts exact-path endpoint actions on one existing HTTP/S server.
+     * @param server - Host-owned listener; the service never opens or closes its port.
+     * @param options - Allowed origins, controller definitions and resource limits.
+     */
+    mount(server, options) {
+        if (this.#close)
+            throw new Error('WebSockets are already mounted.');
+        this.#closed = false;
+        const origins = new Set(options.origins);
+        if (!origins.size || [...origins].some(origin => { try {
+            const url = new URL(origin);
+            return !['http:', 'https:'].includes(url.protocol) || url.origin !== origin;
+        }
+        catch {
+            return true;
+        } }))
+            throw new Error('WebSockets require exact HTTP(S) origins.');
+        const endpoints = new Map(Object.entries(options.endpoints));
+        for (const [path, endpoint] of endpoints) {
+            if (!path.startsWith('/') || path.startsWith('//') || /[?#\s]/.test(path) || !endpoint || typeof endpoint !== 'object')
+                throw new Error('Invalid WebSocket endpoint.');
+        }
+        const limits = { maxConnections: 1000, maxPayloadBytes: 65536, maxBufferedBytes: 262144, maxPendingMessages: 16, maxPendingSends: 32, authTimeoutMs: 5000, heartbeatMs: 30000, shutdownTimeoutMs: 3000 };
+        for (const key of Object.keys(limits)) {
+            const value = options[key] ?? limits[key];
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new Error(`Invalid WebSocket limit: ${key}.`);
+            limits[key] = value;
+        }
+        const connections = this.#connections;
+        const sockets = new WebSocketServer({ noServer: true, maxPayload: limits.maxPayloadBytes, perMessageDeflate: false });
+        /** Contains reporting failures and keeps credentials out of transport diagnostics. */
+        const report = (error) => { try {
+            options.onError?.(error);
+        }
+        catch { /* Reporting cannot break cleanup. */ } };
+        let closing;
+        /** Handles only owned paths; other upgrade listeners retain ownership of their paths. */
+        const upgrade = (request, stream, head) => {
+            let pathname;
+            try {
+                pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+            }
+            catch {
+                stream.destroy();
+                return;
+            }
+            const endpoint = endpoints.get(pathname);
+            if (!endpoint) {
+                if (server.listenerCount('upgrade') === 1)
+                    stream.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+                return;
+            }
+            if (closing || !request.headers.origin || !origins.has(request.headers.origin) || connections.size >= limits.maxConnections) {
+                stream.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+                return;
+            }
+            sockets.handleUpgrade(request, stream, head, ws => {
+                const connection = new WebSocketConnection(ws, request, this.app, endpoint, limits, report, () => {
+                    for (const listener of this.#presenceListeners.get(pathname) ?? []) {
+                        try {
+                            void Promise.resolve(this.app.requestContext.run(listener)).catch(report);
+                        }
+                        catch (error) {
+                            report(error);
+                        }
+                    }
+                }, options.resolveToken);
+                connections.set(connection, pathname);
+                void connection.finished().then(() => connections.delete(connection));
+            });
+        };
+        server.on('upgrade', upgrade);
+        this.#close = () => closing ??= (async () => {
+            const current = [...connections.keys()];
+            for (const connection of current)
+                connection.stop(1001);
+            let timer;
+            try {
+                await Promise.race([Promise.all(current.map(connection => connection.finished())), new Promise(resolve => { timer = setTimeout(resolve, limits.shutdownTimeoutMs); })]);
+            }
+            finally {
+                clearTimeout(timer);
+                for (const connection of current)
+                    connection.ws.terminate();
+                connections.clear();
+                this.#presenceListeners.clear();
+                this.channels.clear();
+                server.off('upgrade', upgrade);
+                await new Promise(resolve => sockets.close(() => resolve()));
+                this.#close = undefined;
+            }
+        })();
+    }
+    /** Stops accepting upgrades and bounds socket/application cleanup; safe to call repeatedly. */
+    async close() { this.#closed = true; await this.#close?.(); }
+    /**
+     * Lists distinct authenticated users connected to an exact endpoint in this process.
+     * Application code must authorize disclosure; this is never exposed automatically.
+     * Presence is approximate and excludes the other instance during blue/green overlap.
+     * @param path - Registered endpoint path, excluding query parameters.
+     * @returns Current user IDs and connection counts; no session tokens or profile data.
+     */
+    presence(path) {
+        const users = new Map();
+        for (const [connection, endpoint] of this.#connections) {
+            const id = connection.userId;
+            if (endpoint === path && id)
+                users.set(id, (users.get(id) ?? 0) + 1);
+        }
+        return [...users].map(([userId, connections]) => ({ userId, connections }));
+    }
+    /**
+     * Subscribes to local presence changes on one exact endpoint, without exposing them to browsers.
+     * Call presence(path) inside the listener to read current users. The listener has no Auth context
+     * and does not serialize asynchronous listeners; connection.send() reauthenticates its recipient.
+     * @param path - Exact endpoint whose authenticated connections should be observed.
+     * @param listener - Application callback for connect, disconnect or revocation changes.
+     * @returns Idempotent unsubscribe callback; register it on the owning connection's abort signal.
+     */
+    onPresence(path, listener) {
+        let listeners = this.#presenceListeners.get(path);
+        if (!listeners) {
+            listeners = new Set();
+            this.#presenceListeners.set(path, listeners);
+        }
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+            if (!listeners.size && this.#presenceListeners.get(path) === listeners)
+                this.#presenceListeners.delete(path);
+        };
+    }
+}

package/dist/websocket/client/WebSocketClient.d.ts

@@ -0,0 +1,21 @@
+import type { WebSocketClientOptions, WebSocketClientState, WebSocketClientChannel } from '../contracts/WebSocketClient.js';
+/** Browser-safe JSON transport with generation fencing, bounded reconnect and no offline message queue. */
+export declare class WebSocketClient {
+    #private;
+    /** Validates configuration without opening a connection, allowing safe SSR imports. */
+    constructor(options: WebSocketClientOptions);
+    /** Current transport state; connected is set only after the server accepts the endpoint handshake. */
+    get state(): WebSocketClientState;
+    /** Starts once, or explicitly retries after credentials/policy have been repaired. */
+    connect(): void;
+    /** Closes the socket, cancels reconnect and fences late token/network results. */
+    close(): void;
+    /** Sends JSON only while connected; rejected messages are never queued or replayed. */
+    send(data: unknown): boolean;
+    /**
+     * Returns a logical channel sharing this client's physical connection.
+     * The first listener subscribes; removing the final listener unsubscribes.
+     * @param name - Concrete resource channel; the server must independently authorize it.
+     */
+    channel(name: string): WebSocketClientChannel;
+}

package/dist/websocket/client/WebSocketClient.js

@@ -0,0 +1,230 @@
+/** Browser-safe JSON transport with generation fencing, bounded reconnect and no offline message queue. */
+export class WebSocketClient {
+    #subscriptionQueue = [];
+    #subscribing;
+    #channels = new Map();
+    #state = 'closed';
+    #socket;
+    #generation = 0;
+    #attempt = 0;
+    #stopped = true;
+    #retry;
+    #deadline;
+    #options;
+    /** Validates configuration without opening a connection, allowing safe SSR imports. */
+    constructor(options) {
+        const url = new URL(options.url);
+        if (!['ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.hash)
+            throw new Error('Use an absolute ws(s) URL without credentials or fragment.');
+        this.#options = { maxReconnectDelayMs: 30000, connectTimeoutMs: 10000, maxBufferedBytes: 65536, ...options };
+        for (const key of ['maxReconnectDelayMs', 'connectTimeoutMs', 'maxBufferedBytes']) {
+            if (!Number.isSafeInteger(this.#options[key]) || this.#options[key] <= 0)
+                throw new Error(`Invalid WebSocket client option: ${key}.`);
+        }
+    }
+    /** Current transport state; connected is set only after the server accepts the endpoint handshake. */
+    get state() { return this.#state; }
+    /** Starts once, or explicitly retries after credentials/policy have been repaired. */
+    connect() {
+        if (!this.#stopped)
+            return;
+        this.#stopped = false;
+        this.#attempt = 0;
+        void this.#open();
+    }
+    /** Closes the socket, cancels reconnect and fences late token/network results. */
+    close() {
+        this.#stopped = true;
+        this.#generation++;
+        clearTimeout(this.#retry);
+        clearTimeout(this.#deadline);
+        this.#socket?.close(1000);
+        this.#socket = undefined;
+        this.#subscriptionQueue = [];
+        this.#subscribing = undefined;
+        this.#setState('closed');
+    }
+    /** Sends JSON only while connected; rejected messages are never queued or replayed. */
+    send(data) {
+        if (this.#state !== 'connected' || this.#socket?.readyState !== 1 || data === undefined)
+            return false;
+        const frame = JSON.stringify({ type: 'message', data });
+        if (new TextEncoder().encode(frame).length + this.#socket.bufferedAmount > this.#options.maxBufferedBytes)
+            return false;
+        this.#socket.send(frame);
+        return true;
+    }
+    /**
+     * Returns a logical channel sharing this client's physical connection.
+     * The first listener subscribes; removing the final listener unsubscribes.
+     * @param name - Concrete resource channel; the server must independently authorize it.
+     */
+    channel(name) {
+        if (name.length > 256 || !/^[a-zA-Z0-9_.-]+(?::[a-zA-Z0-9_.-]+)*$/.test(name))
+            throw new Error('Invalid channel name.');
+        return { on: (event, listener) => {
+                if (!event || event.length > 256)
+                    throw new Error('Invalid channel event.');
+                let events = this.#channels.get(name);
+                const subscribe = !events;
+                if (!events) {
+                    events = new Map();
+                    this.#channels.set(name, events);
+                }
+                let listeners = events.get(event);
+                if (!listeners) {
+                    listeners = new Set();
+                    events.set(event, listeners);
+                }
+                // Each registration owns its own cleanup, even when callbacks are identical.
+                const callback = (data) => listener(data);
+                listeners.add(callback);
+                if (subscribe && this.#state === 'connected') {
+                    this.#subscriptionQueue.push(name);
+                    this.#subscribeNext();
+                }
+                return () => {
+                    if (!listeners.delete(callback))
+                        return;
+                    if (!listeners.size)
+                        events.delete(event);
+                    if (!events.size) {
+                        this.#channels.delete(name);
+                        this.#subscriptionQueue = this.#subscriptionQueue.filter(channel => channel !== name);
+                        this.send({ type: 'channel.unsubscribe', channel: name });
+                    }
+                };
+            } };
+    }
+    /** Serializes subscriptions so a reconnect cannot flood the server's bounded action queue. */
+    #subscribeNext() {
+        if (this.#subscribing || this.#state !== 'connected')
+            return;
+        const channel = this.#subscriptionQueue.shift();
+        if (!channel)
+            return;
+        this.#subscribing = channel;
+        if (!this.send({ type: 'channel.subscribe', channel })) {
+            this.#subscribing = undefined;
+            this.#deny();
+        }
+    }
+    /** Dispatches reserved channel envelopes without exposing them as ordinary application messages. */
+    #message(data) {
+        if (data && typeof data.channel === 'string' && typeof data.type === 'string' && data.type.startsWith('channel.')) {
+            if (['channel.subscribed', 'channel.denied'].includes(data.type) && this.#subscribing === data.channel) {
+                this.#subscribing = undefined;
+                this.#subscribeNext();
+            }
+            const events = this.#channels.get(data.channel);
+            if (!events)
+                return;
+            if (data.type === 'channel.subscribed')
+                this.#options.onSubscribed?.(data.channel);
+            else if (data.type === 'channel.denied')
+                this.#options.onChannelDenied?.(data.channel);
+            else if (data.type === 'channel.event' && typeof data.event === 'string') {
+                for (const listener of [...events.get(data.event) ?? []])
+                    listener(data.data);
+            }
+            return;
+        }
+        this.#options.onMessage?.(data);
+    }
+    /** Creates one attempt and ignores callbacks from replaced connections. */
+    async #open() {
+        const generation = ++this.#generation;
+        this.#setState(this.#attempt ? 'reconnecting' : 'connecting');
+        this.#deadline = setTimeout(() => {
+            if (generation !== this.#generation || this.#stopped)
+                return;
+            this.#generation++;
+            this.#socket?.close();
+            this.#retryLater();
+        }, this.#options.connectTimeoutMs);
+        try {
+            const auth = this.#options.auth ?? 'required';
+            const token = auth === 'required' ? await this.#options.token?.() : null;
+            if (generation !== this.#generation || this.#stopped)
+                return;
+            if (auth === 'required' && !token) {
+                this.#deny();
+                return;
+            }
+            const factory = this.#options.createSocket ?? nativeSocket;
+            const ws = factory(this.#options.url);
+            this.#socket = ws;
+            ws.onopen = () => { if (generation === this.#generation && !this.#stopped)
+                ws.send(JSON.stringify(auth === 'public' ? { type: 'connect' } : { type: 'authenticate', token })); };
+            ws.onmessage = event => {
+                if (generation !== this.#generation || this.#stopped)
+                    return;
+                let frame;
+                try {
+                    frame = JSON.parse(String(event.data));
+                }
+                catch {
+                    this.#deny();
+                    return;
+                }
+                if (frame?.type === 'ready' && this.#state !== 'connected') {
+                    clearTimeout(this.#deadline);
+                    this.#attempt = 0;
+                    this.#subscriptionQueue = [...this.#channels.keys()];
+                    this.#subscribing = undefined;
+                    this.#setState('connected');
+                    this.#subscribeNext();
+                }
+                else if (frame?.type === 'message' && this.#state === 'connected')
+                    this.#message(frame.data);
+                else
+                    this.#deny();
+            };
+            ws.onerror = () => { };
+            ws.onclose = event => {
+                if (generation !== this.#generation || this.#stopped)
+                    return;
+                this.#generation++;
+                clearTimeout(this.#deadline);
+                if ([4401, 4403, 1003, 1007, 1008, 1009].includes(event.code))
+                    this.#deny();
+                else
+                    this.#retryLater();
+            };
+        }
+        catch {
+            if (generation !== this.#generation || this.#stopped)
+                return;
+            clearTimeout(this.#deadline);
+            this.#retryLater();
+        }
+    }
+    /** Stops retries on an authentication, policy or protocol failure until explicitly connected again. */
+    #deny() { this.close(); this.#setState('denied'); }
+    /** Retries transient failures with exponential backoff and jitter after blue/green shutdown. */
+    #retryLater() {
+        if (this.#stopped)
+            return;
+        if (this.#options.reconnect === false) {
+            this.close();
+            return;
+        }
+        this.#setState('reconnecting');
+        const ceiling = Math.min(this.#options.maxReconnectDelayMs, 500 * 2 ** Math.min(this.#attempt++, 16));
+        this.#retry = setTimeout(() => void this.#open(), Math.max(1, Math.floor(ceiling * (0.5 + Math.random() * 0.5))));
+    }
+    /** Notifies state consumers only when the lifecycle actually changes. */
+    #setState(state) {
+        if (this.#state === state)
+            return;
+        this.#state = state;
+        this.#options.onState?.(state);
+    }
+}
+/** Resolves the native browser constructor only when connecting, keeping imports SSR-safe. */
+function nativeSocket(url) {
+    const Constructor = globalThis.WebSocket;
+    if (!Constructor)
+        throw new Error('This runtime needs a WebSocket factory.');
+    return new Constructor(url);
+}

package/dist/websocket/client/index.d.ts

@@ -0,0 +1,3 @@
+export { WebSocketClient } from './WebSocketClient.js';
+export type { ClientSocket, WebSocketClientOptions, WebSocketClientState } from '../contracts/WebSocketClient.js';
+export type { WebSocketClientChannel } from '../contracts/WebSocketClient.js';

package/dist/websocket/client/index.js

@@ -0,0 +1 @@
+export { WebSocketClient } from './WebSocketClient.js';

package/dist/websocket/contracts/WebSocketChannel.d.ts

@@ -0,0 +1,20 @@
+import type { WebSocketContext } from './WebSocketEndpoint.js';
+/** Current authenticated context and parameters extracted from a channel name. */
+export type WebSocketChannelContext = Omit<WebSocketContext, 'send' | 'close'> & {
+    /** Concrete requested channel, never trusted as proof of access. */
+    readonly channel: string;
+    /** Colon-delimited parameters matched by the server's definition. */
+    readonly params: Readonly<Record<string, string>>;
+};
+/** Application policy for a named resource channel. All subscriptions require authorization. */
+export interface WebSocketChannelDefinition {
+    /** Pattern such as website:{websiteId}:jobs. */
+    readonly pattern: string;
+    /** Pure access check, evaluated on subscription and before every delivery. */
+    authorize(context: WebSocketChannelContext): boolean | Promise<boolean>;
+}
+/** Server publisher for a concrete channel, including configured worker-to-API HTTP delivery. */
+export interface WebSocketChannelPublisher {
+    /** Returns accepted local sends, or zero after remote HTTP acceptance. Never a browser delivery receipt. */
+    publish(event: string, data: unknown): Promise<number>;
+}

package/dist/websocket/contracts/WebSocketChannel.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/contracts/WebSocketClient.d.ts

@@ -0,0 +1,45 @@
+/** Browser-visible lifecycle; connected means accepted under the endpoint's authentication policy. */
+export type WebSocketClientState = 'closed' | 'connecting' | 'connected' | 'reconnecting' | 'denied';
+/** Minimal native browser socket surface, also usable by Node integration clients. */
+export interface ClientSocket {
+    readonly readyState: number;
+    readonly bufferedAmount: number;
+    onopen: ((event: any) => void) | null;
+    /** Native implementations have different event types; the client reads only data. */
+    onmessage: ((event: any) => void) | null;
+    /** Native implementations have different event types; the client reads only code. */
+    onclose: ((event: any) => void) | null;
+    onerror: ((event: any) => void) | null;
+    send(data: string): void;
+    close(code?: number): void;
+}
+/** Options for the small JSON client. Incoming application data remains untrusted/unknown. */
+export interface WebSocketClientOptions {
+    /** Absolute ws(s) URL. Production applications must use wss. */
+    url: string;
+    /** Reads the existing bearer session afresh on every connection attempt. Never put it in the URL. */
+    token?(): string | null | Promise<string | null>;
+    /** Must match the endpoint: required (default), cookie (server token resolver), or public. */
+    auth?: 'required' | 'cookie' | 'public';
+    onMessage?(data: unknown): void;
+    /** Called after each successful subscription, including reconnect; reload durable state here. */
+    onSubscribed?(channel: string): void;
+    /** Called when a requested channel is unknown, ambiguous, denied or exceeds the subscription limit. */
+    onChannelDenied?(channel: string): void;
+    onState?(state: WebSocketClientState): void;
+    /** Defaults to true; authentication/policy denial and protocol failures never auto-retry. */
+    reconnect?: boolean;
+    /** Maximum delay between reconnect attempts. Default 30000 ms. */
+    maxReconnectDelayMs?: number;
+    /** Deadline including token acquisition, socket opening and server authentication. Default 10000 ms. */
+    connectTimeoutMs?: number;
+    /** Outgoing frame/queue limit. Default 64 KiB. */
+    maxBufferedBytes?: number;
+    /** Optional native-compatible factory for non-browser runtimes. */
+    createSocket?(url: string): ClientSocket;
+}
+/** Browser-side view of one logical channel on a shared connection. */
+export interface WebSocketClientChannel {
+    /** Adds a listener and subscribes on first use. Returns idempotent listener cleanup. Payloads require app validation. */
+    on(event: string, listener: (data: unknown) => void): () => void;
+}

package/dist/websocket/contracts/WebSocketClient.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/contracts/WebSocketEndpoint.d.ts

@@ -0,0 +1,43 @@
+import type { WebSocketChannelDefinition } from './WebSocketChannel.js';
+import type { IncomingMessage } from 'node:http';
+import type { UserIdentity } from '../../auth/index.js';
+/** An accepted connection. Authenticated sends recheck the session; all sends recheck endpoint policy. */
+export interface WebSocketContext<TUser extends UserIdentity | null = UserIdentity> {
+    /** Stable connection identity for application-owned local subscriptions. */
+    readonly id: string;
+    /** Authenticated account ID, derived from framework Auth rather than client data. */
+    readonly userId: TUser extends UserIdentity ? string : null;
+    /** Fresh account model for this action. */
+    readonly user: TUser;
+    /** Original upgrade request; HTTP route hooks do not run for this transport. */
+    readonly request: IncomingMessage;
+    /** Aborted as soon as the connection closes or shutdown starts. */
+    readonly signal: AbortSignal;
+    /** Sends JSON after fresh authentication and endpoint policy checks. Optional resource guard uses that same fresh context; false means closed or denied. */
+    send(data: unknown, authorize?: (context: Omit<WebSocketContext<TUser>, 'send' | 'close'>) => boolean | Promise<boolean>): Promise<boolean>;
+    /** Ends the connection normally. */
+    close(): void;
+}
+/** Cleanup metadata; close handlers run without authenticated request context. */
+export interface WebSocketClosed {
+    id: string;
+    userId: string | null;
+    code: number;
+}
+/** Controller-style JSON endpoint. Authentication is required unless public access is explicit. */
+export interface WebSocketEndpoint<TMessage = unknown, TUser extends UserIdentity | null = UserIdentity> {
+    /** Authentication is required by default. Public endpoints explicitly opt out and always have null identity. */
+    auth?: TUser extends UserIdentity ? 'required' : 'public';
+    /** Additional resource/tenant authorization, rerun before each action and send. */
+    authorize?(context: Omit<WebSocketContext<TUser>, 'send' | 'close'>): boolean | Promise<boolean>;
+    /** Named channel policies on this shared endpoint. Anonymous endpoints cannot subscribe to private channels. */
+    channels?: readonly WebSocketChannelDefinition[];
+    /** Called once after authentication. May send initial application data. */
+    open?(context: WebSocketContext<TUser>): void | Promise<void>;
+    /** Validates untrusted JSON. Throwing closes with 1008; omitted messages remain unknown. */
+    parse?(data: unknown): TMessage | Promise<TMessage>;
+    /** Called sequentially for validated application messages in a fresh Auth context. */
+    message?(context: WebSocketContext<TUser>, data: TMessage): void | Promise<void>;
+    /** Releases application subscriptions. Must settle promptly and must not send data. */
+    close?(context: WebSocketClosed): void | Promise<void>;
+}

package/dist/websocket/contracts/WebSocketEndpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/contracts/WebSocketOptions.d.ts

@@ -0,0 +1,48 @@
+import type { WebSocketEndpoint } from './WebSocketEndpoint.js';
+import type { IncomingMessage } from 'node:http';
+/** Mount configuration for one app-owned HTTP/S server. No additional port is opened. */
+export interface WebSocketOptions {
+    /** Optional service-authenticated HTTP publisher registered by the Fastify adapter. */
+    publish?: {
+        /** Exact private route path on this API; keep it off public reverse-proxy routes. */
+        path: string;
+        /** Dedicated server-only bearer secret matching worker configuration. */
+        token: string;
+    };
+    /** Exact HTTP(S) origins allowed to upgrade. Missing origins are rejected. */
+    origins: readonly string[];
+    /** Exact paths to endpoint actions. Query parameters are available on request.url. */
+    endpoints: Readonly<Record<string, WebSocketEndpoint<any, any>>>;
+    /** Resolves an existing session from the upgrade request, e.g. an HttpOnly cookie. Origin checks still apply. Public endpoints never invoke this. */
+    resolveToken?(request: IncomingMessage): string | null | Promise<string | null>;
+    /** Maximum simultaneous sockets, including unauthenticated handshakes. Default 1000. */
+    maxConnections?: number;
+    /** Incoming and outgoing JSON frame limit in bytes. Default 64 KiB. */
+    maxPayloadBytes?: number;
+    /** Maximum queued outgoing bytes per client. Default 256 KiB. */
+    maxBufferedBytes?: number;
+    /** Maximum queued incoming actions per client. Default 16. */
+    maxPendingMessages?: number;
+    /** Maximum concurrent outgoing sends awaiting access checks per client. Overflow closes with retryable 1013. Default 32. */
+    maxPendingSends?: number;
+    /** Deadline for initial authentication. Default 5000 ms. */
+    authTimeoutMs?: number;
+    /** Ping and session/policy revalidation interval. Default 30000 ms. */
+    heartbeatMs?: number;
+    /** Bounded wait for connection cleanup at shutdown. Default 3000 ms. */
+    shutdownTimeoutMs?: number;
+    /** Server-only error reporting. Never receives authentication frames or raw tokens. */
+    onError?(error: unknown): void;
+}
+/** Validated internal limits shared by the transport and its connections. */
+export interface WebSocketLimits {
+    maxConnections: number;
+    maxPayloadBytes: number;
+    maxBufferedBytes: number;
+    maxPendingMessages: number;
+    /** Includes authentication and resource authorization, before socket buffering begins. */
+    maxPendingSends: number;
+    authTimeoutMs: number;
+    heartbeatMs: number;
+    shutdownTimeoutMs: number;
+}

package/dist/websocket/contracts/WebSocketOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/contracts/WebSocketPresence.d.ts

@@ -0,0 +1,6 @@
+/** Approximate authenticated presence on one endpoint in this API process. */
+export interface WebSocketPresence {
+    userId: string;
+    /** Multiple tabs/devices for the same account count as separate connections. */
+    connections: number;
+}

package/dist/websocket/contracts/WebSocketPresence.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/contracts/WebSocketServiceOptions.d.ts

@@ -0,0 +1,12 @@
+/** Optional worker-to-API HTTP delivery; browser connections remain owned by the API. */
+export interface WebSocketServiceOptions {
+    /** Used by publishers without a mounted WebSocket server. Mounted APIs deliver locally. */
+    publish?: {
+        /** Trusted absolute HTTP(S) endpoint; use HTTPS outside a private application network. */
+        url: string;
+        /** Server-only bearer secret, at least 32 characters. Never expose it to browsers. */
+        token: string;
+        /** Bounded connection and response deadline. Defaults to 5000 milliseconds. */
+        timeoutMs?: number;
+    };
+}

package/dist/websocket/contracts/WebSocketServiceOptions.js

@@ -0,0 +1 @@
+export {};