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

package/src/websocket/contracts/WebSocketOptions.ts

@@ -0,0 +1,50 @@
+import type { WebSocketEndpoint } from './WebSocketEndpoint';
+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/src/websocket/contracts/WebSocketPresence.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/src/websocket/contracts/WebSocketServiceOptions.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/src/websocket/contracts/index.ts

@@ -0,0 +1,6 @@
+export type { WebSocketContext, WebSocketClosed, WebSocketEndpoint } from './WebSocketEndpoint';
+export type { WebSocketOptions, WebSocketLimits } from './WebSocketOptions';
+export type { WebSocketPresence } from './WebSocketPresence';
+export type { ClientSocket, WebSocketClientOptions, WebSocketClientState, WebSocketClientChannel } from './WebSocketClient';
+export type { WebSocketChannelContext, WebSocketChannelDefinition, WebSocketChannelPublisher } from './WebSocketChannel';
+export type { WebSocketServiceOptions } from './WebSocketServiceOptions';

package/src/websocket/defineChannel.ts

@@ -0,0 +1,14 @@
+import type { WebSocketChannelDefinition } from './contracts/WebSocketChannel';
+
+/**
+ * Defines a private resource channel with an explicit application access policy.
+ * @param pattern - Colon-delimited name with optional {parameter} segments.
+ * @param options - Access check using the freshly authenticated user and resource parameters.
+ * @returns A definition to include in an endpoint's channels array.
+ */
+export function defineChannel(pattern: string, options: Omit<WebSocketChannelDefinition, 'pattern'>): WebSocketChannelDefinition {
+	const segments = pattern.split(':');
+	const parameters = segments.filter(segment => segment.startsWith('{'));
+	if (pattern.length > 256 || !segments.every(segment => /^[a-zA-Z0-9_.-]+$/.test(segment) || /^\{[a-zA-Z][a-zA-Z0-9_]*\}$/.test(segment)) || new Set(parameters).size !== parameters.length || typeof options.authorize !== 'function') throw new Error('Invalid channel definition.');
+	return Object.freeze({ pattern, authorize: options.authorize });
+}

package/src/websocket/defineWebSocket.ts

@@ -0,0 +1,15 @@
+import type { WebSocketEndpoint } from './contracts';
+
+/**
+ * Defines controller actions while inferring the validated message type.
+ * @param endpoint - Application-owned authorization, validation and lifecycle actions.
+ * @returns The same definition for registration against an exact URL path.
+ * @example defineWebSocket({ open: async ({ send }) => { await send({ ready: true }); } });
+ */
+export function defineWebSocket<TMessage = unknown>(endpoint: WebSocketEndpoint<TMessage, null> & { auth: 'public' }): WebSocketEndpoint<TMessage, null> & { auth: 'public' };
+/** Defines an authenticated endpoint; omitted auth always requires a valid session. */
+export function defineWebSocket<TMessage = unknown>(endpoint: WebSocketEndpoint<TMessage>): WebSocketEndpoint<TMessage>;
+/** Retains controller definitions without wrapping application actions. */
+export function defineWebSocket(endpoint: WebSocketEndpoint<any, any>): WebSocketEndpoint<any, any> {
+	return endpoint;
+}

package/src/websocket/examples/board/LiveBoard.ts

@@ -0,0 +1,97 @@
+import { ActiveRecord, type FieldBuilder } from '@db3.ai/app/db';
+import { app } from '@db3.ai/app/server';
+import { defineChannel, defineWebSocket } from '@db3.ai/app/websocket';
+import { z } from 'zod';
+import { boardSnapshotSchema, type BoardSnapshot } from './boardSnapshot';
+import { SummarizeBoardJob } from './SummarizeBoardJob';
+
+/** Application-owned example: a small shared board and its latest durable background activity. */
+export class LiveBoard extends ActiveRecord {
+	static override table = 'example_live_boards';
+	static override requestFillable = [];
+
+	/** Defines durable state. Register this model in the host's normal migration workflow. */
+	static override fields(field: FieldBuilder) {
+		return {
+			id: field.ulid(), members: field.json<string[]>(),
+			cards: field.json<BoardSnapshot['cards']>(),
+			revision: field.integer({ required: true, default: 0 }),
+			activity: field.json<BoardSnapshot['activity']>(),
+		};
+	}
+	declare id: string;
+	declare members: string[];
+	declare cards: BoardSnapshot['cards'];
+	declare revision: number;
+	declare activity: BoardSnapshot['activity'];
+
+	/** Checks fresh membership for HTTP reads/writes and each subscription or event delivery. */
+	static async canAccess(id: string, userId: string): Promise<boolean> {
+		const board = await this.where('id', id).first();
+		return board?.members.includes(userId) ?? false;
+	}
+
+	/** Creates channel definitions to merge into the app's one authenticated endpoint. */
+	static endpoint() {
+		return defineWebSocket({ channels: [defineChannel('board:{boardId}', {
+			/** A client-controlled board ID is never proof of access. */
+			authorize: ({ userId, params }) => LiveBoard.canAccess(params.boardId!, userId),
+		})] });
+	}
+
+	/** Returns an authorized projection; derive userId from the HTTP session, never its body. */
+	static async snapshot(id: string, userId: string): Promise<BoardSnapshot> {
+		const board = await this.where('id', id).first();
+		if (!board?.members.includes(userId)) throw new Error('Board unavailable.');
+		return board.snapshot();
+	}
+
+	/** Produces a bounded public projection, excluding membership and private model fields. */
+	snapshot(): BoardSnapshot {
+		return boardSnapshotSchema.parse({ id: this.id, revision: this.revision, cards: this.cards, activity: this.activity });
+	}
+
+	/** Serializes edits and rejects stale revisions rather than silently overwriting another user's move. */
+	static async move(id: string, userId: string, input: unknown): Promise<BoardSnapshot> {
+		const command = z.object({ cardId: z.string(), column: z.enum(['todo', 'doing', 'done']), revision: z.number().int().nonnegative() }).strict().parse(input);
+		const snapshot = await app().db.transaction(async () => {
+			const board = await this.where('id', id).forUpdate().first();
+			if (!board?.members.includes(userId)) throw new Error('Board unavailable.');
+			if (board.revision !== command.revision) throw new Error('Board changed; reload before saving.');
+			if (!board.cards.some(card => card.id === command.cardId)) throw new Error('Card unavailable.');
+			board.cards = board.cards.map(card => card.id === command.cardId ? { ...card, column: command.column } : card);
+			board.revision++;
+			await board.save();
+			return board.snapshot();
+		});
+		await this.publishChanged(id);
+		return snapshot;
+	}
+
+	/**
+	 * Commits loading state and SQL queue dispatch together; duplicate active requests reuse the run.
+	 * Call outside an outer transaction, with the database queue driver on the same database.
+	 * A client retains requestId across a lost HTTP response; it is an idempotency key, not authority.
+	 */
+	static async startSummary(id: string, userId: string, requestId: string): Promise<BoardSnapshot> {
+		z.string().uuid().parse(requestId);
+		const snapshot = await app().db.transaction(async () => {
+			const board = await this.where('id', id).forUpdate().first();
+			if (!board?.members.includes(userId)) throw new Error('Board unavailable.');
+			if (board.activity?.id === requestId || ['queued', 'running'].includes(board.activity?.status ?? '')) return board.snapshot();
+			board.activity = { id: requestId, status: 'queued', result: null };
+			board.revision++;
+			await board.save();
+			await app().queue.dispatch(new SummarizeBoardJob({ boardId: id, userId, runId: requestId }), { queue: 'boards', maxTries: 1 });
+			return board.snapshot();
+		});
+		await this.publishChanged(id);
+		return snapshot;
+	}
+
+	/** Emits a small post-commit invalidation. Transport failure must not make a saved edit look rolled back. */
+	static async publishChanged(id: string): Promise<void> {
+		try { await app().webSockets.channel(`board:${id}`).publish('changed', { boardId: id }); }
+		catch (error) { app().log.error({ error, boardId: id }, 'Board saved but live notification failed'); }
+	}
+}

package/src/websocket/examples/board/SummarizeBoardJob.ts

@@ -0,0 +1,52 @@
+import { QueueableJob } from '@db3.ai/app/queue';
+import { app } from '@db3.ai/app/server';
+import { z } from 'zod';
+import { LiveBoard } from './LiveBoard';
+
+/** Immutable identities persisted in the SQL queue; permissions are checked again by the worker. */
+interface SummarizeBoardData extends Record<string, unknown> { boardId: string; userId: string; runId: string }
+
+/** Server-owned work whose durable UI state outlives any browser connection. */
+export class SummarizeBoardJob extends QueueableJob<SummarizeBoardData> {
+	static readonly jobName = 'boards.summarize.v1';
+
+	/** Validates new and rehydrated queue payloads. */
+	constructor(data: SummarizeBoardData) {
+		super(z.object({ boardId: z.string().min(1), userId: z.string().min(1), runId: z.string().uuid() }).parse(data));
+	}
+
+	/**
+	 * Builds a deterministic summary. Replace computation with your slow server activity.
+	 * Browser disconnect never cancels this job; a repeated attempt safely replaces the same result.
+	 */
+	async handle(): Promise<void> {
+		const snapshot = await app().db.transaction(async () => {
+			const board = await LiveBoard.where('id', this.data.boardId).forUpdate().firstOrFail();
+			if (board.activity?.id !== this.data.runId || ['completed', 'failed'].includes(board.activity.status)) return null;
+			if (!board.members.includes(this.data.userId)) throw new Error('Board access revoked.');
+			board.activity = { ...board.activity, status: 'running' };
+			board.revision++;
+			await board.save();
+			return board.snapshot();
+		});
+		if (!snapshot) return;
+		await LiveBoard.publishChanged(this.data.boardId);
+		const result = `${snapshot.cards.filter(card => card.column === 'done').length} of ${snapshot.cards.length} cards complete`;
+		await this.#finish('completed', result);
+	}
+
+	/** Makes terminal failure visible after Queue persists its failed-job record. */
+	override async onFinalFailure(): Promise<void> { await this.#finish('failed', null); }
+
+	/** Fences an old attempt from overwriting a newer run and publishes only after commit. */
+	async #finish(status: 'completed' | 'failed', result: string | null): Promise<void> {
+		await app().db.transaction(async () => {
+			const board = await LiveBoard.where('id', this.data.boardId).forUpdate().first();
+			if (!board || board.activity?.id !== this.data.runId || ['completed', 'failed'].includes(board.activity.status)) return;
+			board.activity = { id: this.data.runId, status, result };
+			board.revision++;
+			await board.save();
+		});
+		await LiveBoard.publishChanged(this.data.boardId);
+	}
+}

package/src/websocket/examples/board/boardSnapshot.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+/** Browser-safe, bounded public projection; membership and queue internals never leave the server. */
+export const boardSnapshotSchema = z.object({
+	id: z.string().min(1),
+	revision: z.number().int().nonnegative(),
+	cards: z.array(z.object({ id: z.string().min(1), title: z.string().max(120), column: z.enum(['todo', 'doing', 'done']) })).max(100),
+	activity: z.object({
+		id: z.string().uuid(),
+		status: z.enum(['queued', 'running', 'completed', 'failed']),
+		result: z.string().nullable(),
+	}).nullable(),
+});
+
+/** Complete authorized board state fetched after a channel invalidation or reconnect. */
+export type BoardSnapshot = z.infer<typeof boardSnapshotSchema>;

package/src/websocket/examples/board/createBoardClient.ts

@@ -0,0 +1,43 @@
+import type { Pinia } from 'pinia';
+import type { WebSocketClientOptions } from '@db3.ai/app/websocket/client';
+import { createChannelSync } from '../createChannelSync';
+import { createBoardStore, type BoardApi } from './createBoardStore';
+
+/** Host-owned URLs and current bearer identity; create this once at browser application startup. */
+export interface BoardClientOptions {
+	baseUrl: string;
+	boardId: string;
+	pinia: Pinia;
+	token(): string | null;
+	/** Optional native-compatible socket factory for Node integration tests. */
+	createSocket?: WebSocketClientOptions['createSocket'];
+}
+
+/**
+ * Composes one authenticated HTTP adapter, Pinia store and shared socket for the board recipe.
+ * Other features use sync.watch() on this same connection. Route unmount does not close it.
+ * Call close() at logout or before replacing the authenticated identity.
+ */
+export function createBoardClient(options: BoardClientOptions) {
+	const base = options.baseUrl.replace(/\/$/, '');
+	/** Rejects unsuccessful HTTP responses before parsing their public snapshot. */
+	async function request(method: string, suffix = '', body?: unknown): Promise<unknown> {
+		const response = await fetch(`${base}/boards/${encodeURIComponent(options.boardId)}${suffix}`, {
+			method, headers: { authorization: `Bearer ${options.token() ?? ''}`, 'content-type': 'application/json' },
+			...(body === undefined ? {} : { body: JSON.stringify(body) }),
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return response.json();
+	}
+	const api: BoardApi = { read: () => request('GET'), move: input => request('PATCH', '', input), start: requestId => request('POST', '/summary', { requestId }) };
+	const store = createBoardStore(options.boardId, api)(options.pinia);
+	const socketUrl = new URL('/ws', base);
+	socketUrl.protocol = socketUrl.protocol === 'https:' ? 'wss:' : 'ws:';
+	const sync = createChannelSync({ url: socketUrl.href, token: options.token, createSocket: options.createSocket });
+	const binding = sync.watch(`board:${options.boardId}`, api.read, store.apply, store.fail);
+	sync.client.connect();
+	return { store, sync, binding, api,
+		/** Stop app-owned listeners and clear private state when identity changes or the app is disposed. */
+		close() { sync.close(); store.dispose(); store.$dispose(); },
+	};
+}

package/src/websocket/examples/board/createBoardStore.ts

@@ -0,0 +1,58 @@
+import { defineStore } from 'pinia';
+import { computed, ref } from 'vue';
+import { boardSnapshotSchema, type BoardSnapshot } from './boardSnapshot';
+
+/** Authenticated HTTP actions supplied by the host; user identity is never a request-body parameter. */
+export interface BoardApi {
+	read(): Promise<unknown>;
+	move(input: { cardId: string; column: 'todo' | 'doing' | 'done'; revision: number }): Promise<unknown>;
+	start(requestId: string): Promise<unknown>;
+}
+
+/**
+ * Creates a Pinia store for the selected board. Register once per application, with its HTTP adapter.
+ * Install pinia and vue in the consuming browser app; neither is required by the backend runtime.
+ */
+export function createBoardStore(boardId: string, api: BoardApi) {
+	return defineStore(`board:${boardId}`, () => {
+		let active = true;
+		const snapshot = ref<BoardSnapshot | null>(null);
+		const submitting = ref(false);
+		const error = ref<string | null>(null);
+		const busy = computed(() => submitting.value || ['queued', 'running'].includes(snapshot.value?.activity?.status ?? ''));
+
+		/** Validates the projection and ignores old responses arriving after a newer mutation. */
+		function apply(value: unknown): void {
+			if (!active) return;
+			const next = boardSnapshotSchema.parse(value);
+			if (next.id !== boardId) throw new Error('Wrong board snapshot.');
+			if (!snapshot.value || next.revision >= snapshot.value.revision) snapshot.value = next;
+			error.value = null;
+		}
+
+		/** Clears private data on failed authorization; the UI keeps an explicit retry/error state. */
+		function fail(_cause: unknown): void { snapshot.value = null; error.value = 'Board unavailable. Reconnect or refresh to try again.'; }
+
+		/** Applies the HTTP result immediately; a broadcast is only an extra refresh trigger. */
+		async function move(cardId: string, column: 'todo' | 'doing' | 'done'): Promise<void> {
+			if (!snapshot.value) return;
+			try { apply(await api.move({ cardId, column, revision: snapshot.value.revision })); }
+			catch (cause) { error.value = 'Save failed or conflicted. Refresh before retrying.'; throw cause; }
+		}
+
+		/**
+		 * Shows immediate button feedback, then lets durable activity status own loading.
+		 * Keep requestId across an uncertain response. On reload, GET restores the latest run.
+		 */
+		async function start(requestId: string): Promise<void> {
+			if (busy.value || !snapshot.value) return;
+			submitting.value = true;
+			try { apply(await api.start(requestId)); }
+			catch (cause) { error.value = 'Start outcome unknown. Refresh before retrying with the same request ID.'; throw cause; }
+			finally { submitting.value = false; }
+		}
+		/** Fences late mutation responses and removes private state on logout or identity replacement. */
+		function dispose(): void { active = false; snapshot.value = null; submitting.value = false; error.value = null; }
+		return { snapshot, submitting, error, busy, apply, fail, move, start, dispose };
+	});
+}

package/src/websocket/examples/board/registerBoardRoutes.ts

@@ -0,0 +1,31 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import type { App } from '@db3.ai/app/server';
+import { z } from 'zod';
+import { LiveBoard } from './LiveBoard';
+
+/** Registers the example's bearer-authenticated HTTP API beside the shared WebSocket endpoint. */
+export function registerBoardRoutes(server: FastifyInstance, application: App): void {
+	/** Creates a fresh authentication scope and maps expected example errors without disclosing private data. */
+	function authorized(action: (id: string, userId: string, body: unknown) => Promise<unknown>) {
+		return async (request: FastifyRequest, reply: FastifyReply) => application.requestContext.run(async () => {
+			const header = request.headers.authorization ?? '';
+			const user = header.startsWith('Bearer ') ? await application.auth.authenticateToken(header.slice(7)) : null;
+			if (!user) return reply.code(401).send({ error: 'Sign in required.' });
+			try {
+				const { id } = z.object({ id: z.string().min(1).max(26) }).parse(request.params);
+				return await action(id, String(user.id), request.body);
+			} catch (error) {
+				if (error instanceof z.ZodError) return reply.code(400).send({ error: 'Invalid board input.' });
+				if (error instanceof Error && error.message === 'Board changed; reload before saving.') return reply.code(409).send({ error: error.message });
+				if (error instanceof Error && ['Board unavailable.', 'Card unavailable.'].includes(error.message)) return reply.code(404).send({ error: 'Board unavailable.' });
+				throw error;
+			}
+		});
+	}
+	server.get('/boards/:id', authorized((id, userId) => LiveBoard.snapshot(id, userId)));
+	server.patch('/boards/:id', authorized((id, userId, body) => LiveBoard.move(id, userId, body)));
+	server.post('/boards/:id/summary', authorized((id, userId, body) => {
+		const { requestId } = z.object({ requestId: z.string().uuid() }).strict().parse(body);
+		return LiveBoard.startSummary(id, userId, requestId);
+	}));
+}

package/src/websocket/examples/createChannelSync.ts

@@ -0,0 +1,66 @@
+import { WebSocketClient, type WebSocketClientOptions } from '@db3.ai/app/websocket/client';
+
+/** A snapshot binding owned by one feature; stopping it must not close the shared socket. */
+export interface SnapshotBinding { refresh(): Promise<void>; stop(): void; denied(): void }
+
+/**
+ * Owns one browser-tab connection and routes subscription acknowledgements to snapshot loaders.
+ * Create once at app boot. Snapshot GETs use the app's existing authenticated HTTP client.
+ * This is copyable application code, not automatic ORM broadcasting or a framework store API.
+ */
+export function createChannelSync(options: Omit<WebSocketClientOptions, 'onSubscribed' | 'onChannelDenied'>) {
+	const bindings = new Map<string, Set<SnapshotBinding>>();
+	const client = new WebSocketClient({ ...options,
+		/** Reconcile only after the server has installed membership, including after reconnect. */
+		onSubscribed: channel => { for (const binding of bindings.get(channel) ?? []) void binding.refresh(); },
+		/** Clear feature data and fence any old HTTP response when membership is refused. */
+		onChannelDenied: channel => { for (const binding of bindings.get(channel) ?? []) binding.denied(); },
+	});
+	return {
+		client,
+		/**
+		 * Binds invalidations to an authoritative snapshot, coalescing concurrent refreshes.
+		 * A change during a GET schedules another GET, so an older response cannot swallow it.
+		 * load must validate HTTP status and payload; apply should reject older model revisions.
+		 */
+		watch<T>(channel: string, load: () => Promise<T>, apply: (value: T) => void, fail: (error: unknown) => void): SnapshotBinding {
+			let active = true;
+			let dirty = false;
+			let pending: Promise<void> | undefined;
+			let group = bindings.get(channel);
+			if (!group) { group = new Set(); bindings.set(channel, group); }
+			const binding: SnapshotBinding = {
+				/** At most one HTTP read per binding is in flight; errors require explicit refresh or reconnect. */
+				refresh() {
+					if (!active) return Promise.resolve();
+					dirty = true;
+					return pending ??= (async () => {
+						try {
+							while (active && dirty) {
+								dirty = false;
+								try { const value = await Promise.resolve().then(load); if (active) apply(value); }
+								catch (error) { if (active) fail(error); }
+							}
+						} finally { pending = undefined; }
+					})();
+				},
+				/** Removes listeners and ignores late responses; the shared connection stays alive. */
+				stop() {
+					active = false;
+					unsubscribe();
+					group.delete(binding);
+					if (!group.size) bindings.delete(channel);
+				},
+				/** Reports access loss after clearing the binding's ability to apply late responses. */
+				denied() { binding.stop(); fail(new Error('Channel access denied.')); },
+			};
+			const unsubscribe = client.channel(channel).on('changed', () => { void binding.refresh(); });
+			group.add(binding);
+			// HTTP still provides initial state if the socket is unavailable. The subscription ACK refresh closes the race.
+			void binding.refresh();
+			return binding;
+		},
+		/** Dispose once on logout or app teardown, not when an individual route unmounts. */
+		close() { for (const group of bindings.values()) for (const binding of group) binding.stop(); client.close(); },
+	};
+}

package/src/websocket/examples/deploymentEndpoint.ts

@@ -0,0 +1,13 @@
+import { defineChannel, defineWebSocket } from '@db3.ai/app/websocket';
+
+/**
+ * Adds an environment-scoped deployment audience to the application's shared endpoint.
+ * @param canReadEnvironment - Host policy checking current organization and environment access.
+ * @returns An authenticated endpoint; merge its channels if /ws is already registered.
+ */
+export function deploymentEndpoint(canReadEnvironment: (userId: string, environmentId: string) => boolean | Promise<boolean>) {
+	return defineWebSocket({ channels: [defineChannel('environment:{environmentId}:deployments', {
+		/** Rechecks membership on subscription and before every event; read access never grants deploy permission. */
+		authorize: ({ userId, params }) => canReadEnvironment(userId, params.environmentId!),
+	})] });
+}

package/src/websocket/examples/deploymentSnapshot.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+
+/** Public deployment status supplied by the application's deployment controller after persistence. */
+export const deploymentSnapshotSchema = z.object({
+	id: z.string().min(1).max(128),
+	environmentId: z.string().min(1).max(128),
+	revision: z.number().int().nonnegative(),
+	releaseId: z.string().min(1).max(128),
+	activeReleaseId: z.string().min(1).max(128).nullable(),
+	phase: z.enum(['queued', 'building', 'migrating', 'starting', 'checking', 'switching', 'live', 'failed', 'rolled-back', 'cancelled']),
+	health: z.enum(['unknown', 'checking', 'passed', 'failed']),
+	/** A safe application message, never raw build output, environment values or provider errors. */
+	message: z.string().max(500),
+}).strict().superRefine((snapshot, context) => {
+	if (snapshot.phase === 'live' && (snapshot.health !== 'passed' || snapshot.activeReleaseId !== snapshot.releaseId)) {
+		context.addIssue({ code: 'custom', message: 'Live requires passed health and the intended active release.' });
+	}
+});
+
+/** Validated browser projection; it neither executes a deployment nor measures infrastructure health. */
+export type DeploymentSnapshot = z.infer<typeof deploymentSnapshotSchema>;
+
+/**
+ * Validates a snapshot for the selected environment/run and rejects older HTTP responses.
+ * The server increments revision across the entire run, including retries and rollback.
+ * @param input - Authorized HTTP response, treated as unknown until validation.
+ * @param expected - Route-selected resource identities, independently authorized by the server.
+ * @param current - Last accepted snapshot, or null after a fresh page load.
+ * @returns The newest validated snapshot for this exact deployment.
+ */
+export function readDeploymentSnapshot(input: unknown, expected: { id: string; environmentId: string }, current: DeploymentSnapshot | null): DeploymentSnapshot {
+	const next = deploymentSnapshotSchema.parse(input);
+	if (next.id !== expected.id || next.environmentId !== expected.environmentId) throw new Error('Wrong deployment snapshot.');
+	if (current && (current.id !== expected.id || current.environmentId !== expected.environmentId)) throw new Error('Clear the previous deployment before changing resources.');
+	return current && next.revision <= current.revision ? current : next;
+}

package/src/websocket/examples/resourceChannels.ts

@@ -0,0 +1,18 @@
+import { defineChannel, defineWebSocket, type WebSocketChannelContext } from '@db3.ai/app/websocket';
+
+/**
+ * Defines one authenticated endpoint for website jobs and private account notifications.
+ * @param canAccessWebsite - App-owned policy checking current organization membership and website access.
+ * @returns An endpoint to mount at /ws using the existing HTTP server and session.
+ */
+export function resourceChannels(canAccessWebsite: (context: WebSocketChannelContext) => boolean | Promise<boolean>) {
+	return defineWebSocket({
+		channels: [
+			defineChannel('website:{websiteId}:jobs', { authorize: canAccessWebsite }),
+			defineChannel('user:{userId}:notifications', {
+				/** Only the authenticated account may subscribe to its notification events. */
+				authorize: ({ userId, params }) => userId === params.userId,
+			}),
+		],
+	});
+}

package/src/websocket/examples/userEndpoint.ts

@@ -0,0 +1,27 @@
+import type { App } from '@db3.ai/app/server';
+import { defineWebSocket } from '@db3.ai/app/websocket';
+
+/**
+ * Creates controller-style actions for the current user. No snapshots or persistence are implied.
+ * @param application - The same app used to mount the endpoints.
+ * @returns Copyable authenticated endpoint definition.
+ */
+export function userEndpoint(application: App) {
+	return defineWebSocket({
+		/** Sends only this connection's identity after framework authentication. */
+		async open({ userId, send }) {
+			await send({ type: 'hello', userId });
+		},
+		/** Validates an application command before the message action runs. */
+		parse(data: unknown): { type: 'ping' | 'my-presence' } {
+			if (!data || typeof data !== 'object' || !('type' in data) || !['ping', 'my-presence'].includes(String(data.type))) throw new Error('Unknown command.');
+			return data as { type: 'ping' | 'my-presence' };
+		},
+		/** Handles commands; presence disclosure is limited to the authenticated account. */
+		async message({ userId, send }, command) {
+			await send(command.type === 'ping'
+				? { type: 'pong' }
+				: { type: 'my-presence', users: application.webSockets.presence('/ws/me').filter(user => user.userId === userId) });
+		},
+	});
+}

package/src/websocket/fastify.ts

@@ -0,0 +1,39 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import type { FastifyInstance } from 'fastify';
+import type { App } from '../server/App';
+import type { WebSocketOptions } from './contracts';
+
+/**
+ * Registers authenticated controller endpoints and closes upgraded sockets before Fastify drains HTTP.
+ * @param server - Fastify server before listen(). HTTP route hooks do not authorize upgrades.
+ * @param options - Application, exact origins, endpoints and optional limits.
+ */
+export function registerWebSockets(server: FastifyInstance, options: WebSocketOptions & { app: App }): void {
+	options.app.webSockets.mount(server.server, options);
+	if (options.publish) {
+		const { path, token } = options.publish;
+		if (!/^\/[A-Za-z0-9/_-]+$/.test(path) || path.startsWith('//')) throw new Error('Invalid WebSocket publishing path.');
+		if (!/^[A-Za-z0-9_-]{32,256}$/.test(token)) throw new Error('WebSocket publish token must contain 32 to 256 URL-safe characters.');
+		const expected = createHash('sha256').update(`Bearer ${token}`).digest();
+		server.post<{ Body: { channel: string; event: string; data?: unknown } }>(path, {
+			bodyLimit: 65536,
+			/** Service credentials are checked before parsing a body; browser/session credentials never authorize publication. */
+			onRequest: async (request, reply) => {
+				const supplied = createHash('sha256').update(request.headers.authorization ?? '').digest();
+				if (request.headers.origin !== undefined || !timingSafeEqual(expected, supplied)) return reply.code(401).send({ error: 'Unauthorized' });
+			},
+			schema: { body: {
+				type: 'object', required: ['channel', 'event'], additionalProperties: false,
+				properties: {
+					channel: { type: 'string', maxLength: 256, pattern: '^[a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)*$' },
+					event: { type: 'string', minLength: 1, maxLength: 256 }, data: {},
+				},
+			} },
+		}, async (request, reply) => {
+			// Deliver locally, never call the outbound HTTP publisher or relay recursively.
+			await options.app.requestContext.run(() => options.app.webSockets.channels.publishEvent(request.body.channel, request.body.event, request.body.data));
+			return reply.code(204).send();
+		});
+	}
+	server.addHook('preClose', async () => { await options.app.webSockets.close(); });
+}

package/src/websocket/index.ts

@@ -0,0 +1,5 @@
+export { WebSockets } from './WebSockets';
+export { WebSocketChannels } from './WebSocketChannels';
+export { defineWebSocket } from './defineWebSocket';
+export type * from './contracts';
+export { defineChannel } from './defineChannel';