@classytic/arc 2.10.3 → 2.11.0

package/dist/integrations/websocket.mjs

@@ -1,5 +1,5 @@
 import fp from "fastify-plugin";
-//#region src/integrations/websocket.ts
+//#region src/integrations/websocket/adapter.ts
 /**
 * Default adapter — no cross-instance broadcast (single-instance only).
 * All methods are no-ops. Used when no adapter is configured.
@@ -10,6 +10,271 @@ var LocalWebSocketAdapter = class {
 	async subscribe() {}
 	async close() {}
 };
+//#endregion
+//#region src/integrations/websocket/auth.ts
+function createCaptureReply() {
+	let rejected = false;
+	let capturedStatus;
+	const reply = {
+		code(statusCode) {
+			rejected = true;
+			capturedStatus = statusCode;
+			return reply;
+		},
+		send() {
+			return reply;
+		},
+		get rejected() {
+			return rejected;
+		},
+		get statusCode() {
+			return capturedStatus;
+		},
+		sent: false
+	};
+	return reply;
+}
+/**
+* Run authentication against a request and return a uniform `AuthResult`
+* (or `null` if denied). Handles both modes:
+*
+*   - `customAuth` provided → call it directly; trust its return shape.
+*   - Otherwise → invoke `fastify.authenticate(request, captureReply)` to
+*     populate `request.user` / `request.scope`, then read IDs off those.
+*
+* This is the single source of truth for "did this request authenticate
+* successfully, and what identity did it establish". The handshake path
+* calls it once; the re-auth loop calls it on every interval.
+*/
+async function authenticateWebSocket(fastify, request, customAuth) {
+	if (customAuth) try {
+		return await customAuth(request);
+	} catch {
+		return null;
+	}
+	const authenticate = fastify.authenticate;
+	if (!authenticate) return null;
+	const reply = createCaptureReply();
+	try {
+		await authenticate(request, reply);
+	} catch {
+		return null;
+	}
+	if (reply.rejected) return null;
+	const shape = request;
+	const user = shape.user;
+	const scope = shape.scope;
+	if (!user) return null;
+	const userId = readIdField(user, "id") ?? readIdField(user, "sub");
+	const organizationId = scope ? readIdField(scope, "organizationId") : void 0;
+	return {
+		...userId !== void 0 ? { userId } : {},
+		...organizationId !== void 0 ? { organizationId } : {}
+	};
+}
+function readIdField(obj, key) {
+	const value = obj[key];
+	return typeof value === "string" ? value : void 0;
+}
+//#endregion
+//#region src/integrations/websocket/connection.ts
+async function handleConnection(ctx, socket, request) {
+	const { fastify, rooms, options } = ctx;
+	const clientId = ctx.nextClientId();
+	let userId;
+	let organizationId;
+	let serviceClientId;
+	let serviceScopes;
+	if (options.auth) {
+		const result = await authenticateWebSocket(fastify, request, options.authenticate);
+		if (!result) {
+			socket.close(4001, "Unauthorized");
+			return;
+		}
+		userId = result.userId;
+		organizationId = result.organizationId;
+		serviceClientId = result.clientId;
+		serviceScopes = result.scopes;
+	}
+	const client = {
+		id: clientId,
+		socket,
+		subscriptions: /* @__PURE__ */ new Set(),
+		userId,
+		organizationId,
+		...serviceClientId ? { clientId: serviceClientId } : {},
+		...serviceScopes ? { scopes: serviceScopes } : {}
+	};
+	rooms.addClient(client);
+	await options.onConnect?.(client);
+	socket.send(JSON.stringify({
+		type: "connected",
+		clientId,
+		resources: options.resources
+	}));
+	let heartbeatTimer;
+	if (options.heartbeatInterval > 0) heartbeatTimer = setInterval(() => {
+		if (socket.readyState === 1) socket.send(JSON.stringify({
+			type: "ping",
+			timestamp: Date.now()
+		}));
+	}, options.heartbeatInterval);
+	let reauthTimer;
+	if (options.reauthInterval > 0 && options.auth) reauthTimer = setInterval(async () => {
+		if (socket.readyState !== 1) return;
+		if (!await authenticateWebSocket(fastify, request, options.authenticate)) {
+			socket.send(JSON.stringify({
+				type: "error",
+				error: "Session expired"
+			}));
+			socket.close(4003, "Session expired");
+		}
+	}, options.reauthInterval);
+	socket.on("message", async (raw) => {
+		if ((typeof raw === "string" ? Buffer.byteLength(raw) : raw.length) > options.maxMessageBytes) {
+			socket.send(JSON.stringify({
+				type: "error",
+				error: "Message too large"
+			}));
+			return;
+		}
+		let msg;
+		try {
+			msg = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+		} catch {
+			socket.send(JSON.stringify({
+				type: "error",
+				error: "Invalid message format"
+			}));
+			return;
+		}
+		switch (msg.type) {
+			case "subscribe": {
+				const room = msg.resource ?? msg.channel;
+				if (!room) break;
+				if (client.subscriptions.size >= options.maxSubscriptionsPerClient) {
+					socket.send(JSON.stringify({
+						type: "error",
+						channel: room,
+						error: "Subscription limit reached"
+					}));
+					break;
+				}
+				if (options.roomPolicy) {
+					if (!await options.roomPolicy(client, room)) {
+						socket.send(JSON.stringify({
+							type: "error",
+							channel: room,
+							error: "Subscription denied"
+						}));
+						break;
+					}
+				}
+				const ok = rooms.subscribe(clientId, room);
+				socket.send(JSON.stringify({
+					type: ok ? "subscribed" : "error",
+					channel: room,
+					...ok ? {} : { error: "Room at capacity" }
+				}));
+				break;
+			}
+			case "unsubscribe": {
+				const room = msg.resource ?? msg.channel;
+				if (room) {
+					rooms.unsubscribe(clientId, room);
+					socket.send(JSON.stringify({
+						type: "unsubscribed",
+						channel: room
+					}));
+				}
+				break;
+			}
+			case "pong": break;
+			default:
+				await options.onMessage?.(client, msg);
+				break;
+		}
+	});
+	socket.on("close", async () => {
+		if (heartbeatTimer) clearInterval(heartbeatTimer);
+		if (reauthTimer) clearInterval(reauthTimer);
+		await options.onDisconnect?.(client);
+		rooms.removeClient(clientId);
+	});
+	socket.on("error", () => {
+		if (heartbeatTimer) clearInterval(heartbeatTimer);
+		if (reauthTimer) clearInterval(reauthTimer);
+		rooms.removeClient(clientId);
+	});
+}
+//#endregion
+//#region src/integrations/websocket/event-bridge.ts
+/**
+* Subscribe to `<resource>.created|updated|deleted` events for every
+* resource in `resources` and fan them out to the matching room (same
+* name as the resource). Returns the unsubscriber list so the caller can
+* clean up on `onClose`.
+*
+* Org-scoped events (events carrying `meta.organizationId`) broadcast
+* only to clients in that org; unscoped events broadcast to every
+* subscriber of the room.
+*/
+async function wireResourceEvents(fastify, rooms, resources) {
+	const unsubscribers = [];
+	const events = fastify.events;
+	if (!events?.subscribe) return unsubscribers;
+	if (resources.length === 0) return unsubscribers;
+	const subscribe = events.subscribe;
+	for (const resourceName of resources) for (const op of [
+		"created",
+		"updated",
+		"deleted"
+	]) {
+		const unsub = await subscribe(`${resourceName}.${op}`, (event) => {
+			const room = resourceName;
+			const payload = JSON.stringify({
+				type: `${resourceName}.${op}`,
+				data: event.payload,
+				meta: {
+					timestamp: event.meta?.timestamp,
+					userId: event.meta?.userId,
+					organizationId: event.meta?.organizationId
+				}
+			});
+			if (event.meta?.organizationId) rooms.broadcastToOrgWithAdapter(event.meta.organizationId, room, payload);
+			else rooms.broadcastWithAdapter(room, payload);
+		});
+		unsubscribers.push(unsub);
+	}
+	return unsubscribers;
+}
+/**
+* Register the optional `{path}/stats` endpoint.
+*
+*   - `false` (default): no registration
+*   - `true`: open endpoint
+*   - `'authenticated'`: guarded by `fastify.authenticate` if registered;
+*     silently skipped with a warn when it isn't (doesn't fail boot — the
+*     stats endpoint is diagnostic, not load-bearing)
+*/
+function registerStatsRoute(fastify, rooms, path, expose) {
+	if (expose === true) {
+		fastify.get(`${path}/stats`, async () => ({
+			success: true,
+			data: rooms.getStats()
+		}));
+		return;
+	}
+	if (expose === "authenticated") if (fastify.hasDecorator("authenticate")) {
+		const authenticate = fastify.authenticate;
+		fastify.get(`${path}/stats`, { preHandler: authenticate }, async () => ({
+			success: true,
+			data: rooms.getStats()
+		}));
+	} else fastify.log.warn("arc-websocket: exposeStats is \"authenticated\" but fastify.authenticate is not registered — stats endpoint skipped");
+}
+//#endregion
+//#region src/integrations/websocket/room-manager.ts
 var RoomManager = class {
 	rooms = /* @__PURE__ */ new Map();
 	clients = /* @__PURE__ */ new Map();
@@ -106,11 +371,12 @@ var RoomManager = class {
 		};
 	}
 };
+//#endregion
+//#region src/integrations/websocket/plugin.ts
 const websocketPluginImpl = async (fastify, options) => {
-	let clientCounter = 0;
 	const { path = "/ws", auth = true, resources = [], heartbeatInterval = 3e4, authenticate: customAuth, maxClientsPerRoom = 1e4, roomPolicy, maxMessageBytes = 16384, maxSubscriptionsPerClient = 100, reauthInterval = 0, adapter, exposeStats = false, onMessage, onConnect, onDisconnect } = options;
 	if (auth && !customAuth && !fastify.hasDecorator("authenticate")) throw new Error("[arc-websocket] auth is true but fastify.authenticate is not registered. Register an auth plugin before WebSocket, provide a custom authenticate function, or set auth: false.");
-	const rooms = new RoomManager(maxClientsPerRoom, adapter);
+	const rooms = new RoomManager(maxClientsPerRoom, adapter ?? new LocalWebSocketAdapter());
 	if (adapter) await adapter.subscribe((room, message) => {
 		if (room.startsWith("org:")) {
 			const parts = room.split(":");
@@ -139,229 +405,31 @@ const websocketPluginImpl = async (fastify, options) => {
 		},
 		getStats: () => rooms.getStats()
 	});
-	const eventUnsubscribers = [];
-	if (resources.length > 0 && fastify.events?.subscribe) for (const resourceName of resources) for (const op of [
-		"created",
-		"updated",
-		"deleted"
-	]) {
-		const unsub = await fastify.events.subscribe(`${resourceName}.${op}`, async (event) => {
-			const room = resourceName;
-			const payload = JSON.stringify({
-				type: `${resourceName}.${op}`,
-				data: event.payload,
-				meta: {
-					timestamp: event.meta?.timestamp,
-					userId: event.meta?.userId,
-					organizationId: event.meta?.organizationId
-				}
-			});
-			if (event.meta?.organizationId) rooms.broadcastToOrgWithAdapter(event.meta.organizationId, room, payload);
-			else rooms.broadcastWithAdapter(room, payload);
-		});
-		eventUnsubscribers.push(unsub);
-	}
-	fastify.get(path, { websocket: true }, async (socket, request) => {
-		const clientId = `ws_${++clientCounter}_${Date.now()}`;
-		let userId;
-		let organizationId;
-		let serviceClientId;
-		let serviceScopes;
-		if (auth) if (customAuth) {
-			const result = await customAuth(request);
-			if (!result) {
-				socket.close(4001, "Unauthorized");
-				return;
-			}
-			userId = result.userId;
-			organizationId = result.organizationId;
-			serviceClientId = result.clientId;
-			serviceScopes = result.scopes;
-		} else {
-			if (fastify.authenticate) try {
-				let rejected = false;
-				const fakeReply = {
-					code(_statusCode) {
-						rejected = true;
-						return fakeReply;
-					},
-					send() {
-						return fakeReply;
-					},
-					sent: false
-				};
-				await fastify.authenticate(request, fakeReply);
-				if (rejected) {
-					socket.close(4001, "Unauthorized");
-					return;
-				}
-			} catch {
-				socket.close(4001, "Unauthorized");
-				return;
-			}
-			if (request.user) {
-				userId = request.user.id ?? request.user.sub;
-				organizationId = request.scope?.organizationId;
-			} else {
-				socket.close(4001, "Unauthorized");
-				return;
-			}
+	const eventUnsubscribers = await wireResourceEvents(fastify, rooms, resources);
+	let clientCounter = 0;
+	const ctx = {
+		fastify,
+		rooms,
+		nextClientId: () => `ws_${++clientCounter}_${Date.now()}`,
+		options: {
+			auth,
+			resources,
+			heartbeatInterval,
+			maxClientsPerRoom,
+			maxMessageBytes,
+			maxSubscriptionsPerClient,
+			reauthInterval,
+			authenticate: customAuth,
+			roomPolicy,
+			onConnect,
+			onDisconnect,
+			onMessage
 		}
-		const client = {
-			id: clientId,
-			socket,
-			subscriptions: /* @__PURE__ */ new Set(),
-			userId,
-			organizationId,
-			...serviceClientId ? { clientId: serviceClientId } : {},
-			...serviceScopes ? { scopes: serviceScopes } : {}
-		};
-		rooms.addClient(client);
-		await onConnect?.(client);
-		socket.send(JSON.stringify({
-			type: "connected",
-			clientId,
-			resources
-		}));
-		let heartbeatTimer;
-		if (heartbeatInterval > 0) heartbeatTimer = setInterval(() => {
-			if (socket.readyState === 1) socket.send(JSON.stringify({
-				type: "ping",
-				timestamp: Date.now()
-			}));
-		}, heartbeatInterval);
-		let reauthTimer;
-		if (reauthInterval > 0 && auth) reauthTimer = setInterval(async () => {
-			if (socket.readyState !== 1) return;
-			try {
-				if (customAuth) {
-					if (!await customAuth(request)) {
-						socket.send(JSON.stringify({
-							type: "error",
-							error: "Session expired"
-						}));
-						socket.close(4003, "Session expired");
-						return;
-					}
-				} else if (fastify.authenticate) {
-					let rejected = false;
-					const fakeReply = {
-						code() {
-							rejected = true;
-							return fakeReply;
-						},
-						send() {
-							return fakeReply;
-						},
-						sent: false
-					};
-					await fastify.authenticate(request, fakeReply);
-					if (rejected) {
-						socket.send(JSON.stringify({
-							type: "error",
-							error: "Session expired"
-						}));
-						socket.close(4003, "Session expired");
-						return;
-					}
-				}
-			} catch {
-				socket.send(JSON.stringify({
-					type: "error",
-					error: "Session expired"
-				}));
-				socket.close(4003, "Session expired");
-			}
-		}, reauthInterval);
-		socket.on("message", async (raw) => {
-			if ((typeof raw === "string" ? Buffer.byteLength(raw) : raw.length) > maxMessageBytes) {
-				socket.send(JSON.stringify({
-					type: "error",
-					error: "Message too large"
-				}));
-				return;
-			}
-			try {
-				const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString());
-				switch (msg.type) {
-					case "subscribe": {
-						const room = msg.resource ?? msg.channel;
-						if (room) {
-							if (client.subscriptions.size >= maxSubscriptionsPerClient) {
-								socket.send(JSON.stringify({
-									type: "error",
-									channel: room,
-									error: "Subscription limit reached"
-								}));
-								break;
-							}
-							if (roomPolicy) {
-								if (!await roomPolicy(client, room)) {
-									socket.send(JSON.stringify({
-										type: "error",
-										channel: room,
-										error: "Subscription denied"
-									}));
-									break;
-								}
-							}
-							const ok = rooms.subscribe(clientId, room);
-							socket.send(JSON.stringify({
-								type: ok ? "subscribed" : "error",
-								channel: room,
-								...ok ? {} : { error: "Room at capacity" }
-							}));
-						}
-						break;
-					}
-					case "unsubscribe": {
-						const room = msg.resource ?? msg.channel;
-						if (room) {
-							rooms.unsubscribe(clientId, room);
-							socket.send(JSON.stringify({
-								type: "unsubscribed",
-								channel: room
-							}));
-						}
-						break;
-					}
-					case "pong": break;
-					default:
-						await onMessage?.(client, msg);
-						break;
-				}
-			} catch {
-				socket.send(JSON.stringify({
-					type: "error",
-					error: "Invalid message format"
-				}));
-			}
-		});
-		socket.on("close", async () => {
-			if (heartbeatTimer) clearInterval(heartbeatTimer);
-			if (reauthTimer) clearInterval(reauthTimer);
-			await onDisconnect?.(client);
-			rooms.removeClient(clientId);
-		});
-		socket.on("error", () => {
-			if (heartbeatTimer) clearInterval(heartbeatTimer);
-			if (reauthTimer) clearInterval(reauthTimer);
-			rooms.removeClient(clientId);
-		});
-	});
-	if (exposeStats === true) fastify.get(`${path}/stats`, async () => {
-		return {
-			success: true,
-			data: rooms.getStats()
-		};
-	});
-	else if (exposeStats === "authenticated") if (fastify.hasDecorator("authenticate")) fastify.get(`${path}/stats`, { preHandler: fastify.authenticate }, async () => {
-		return {
-			success: true,
-			data: rooms.getStats()
-		};
+	};
+	fastify.get(path, { websocket: true }, async (socket, request) => {
+		await handleConnection(ctx, socket, request);
 	});
-	else fastify.log.warn("arc-websocket: exposeStats is \"authenticated\" but fastify.authenticate is not registered — stats endpoint skipped");
+	registerStatsRoute(fastify, rooms, path, exposeStats);
 	fastify.addHook("onClose", async () => {
 		for (const unsub of eventUnsubscribers) unsub();
 		eventUnsubscribers.length = 0;

package/dist/{keys-qcD-TVJl.mjs → keys-CARyUjiR.mjs}

@@ -30,6 +30,8 @@ function stableStringify(value) {
 	if (value === null || value === void 0) return "";
 	if (typeof value !== "object") return String(value);
 	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	if (value instanceof RegExp) return `/${value.source}/${value.flags}`;
+	if (value instanceof Date) return `d${value.getTime()}`;
 	return "{" + Object.keys(value).sort().map((k) => `${k}:${stableStringify(value[k])}`).join(",") + "}";
 }
 function djb2(str) {

package/dist/{loadResources-BAzJItAJ.mjs → loadResources-YNwKHvRA.mjs}

@@ -59,7 +59,8 @@ var loadResources_exports = /* @__PURE__ */ __exportAll({ loadResources: () => l
 */
 async function loadResources(dir, options = {}) {
 	const { suffix = ".resource", recursive = true, exclude, include, silent = false } = options;
-	const files = await collectFiles(resolve(dir.startsWith("file://") ? dirname(fileURLToPath(dir)) : dir), new RegExp(`${escapeRegex(suffix)}\\.(ts|js|mts|mjs)$`), recursive);
+	const absDir = resolve(dir.startsWith("file://") ? dirname(fileURLToPath(dir)) : dir);
+	const files = await collectFiles(absDir, new RegExp(`${escapeRegex(suffix)}\\.(ts|js|mts|mjs)$`), recursive);
 	files.sort();
 	const includeSet = include ? new Set(include) : null;
 	const excludeSet = exclude ? new Set(exclude) : null;
@@ -128,6 +129,7 @@ async function loadResources(dir, options = {}) {
 			log.warn(`[arc] loadResources: ${skipped.length} file(s) skipped (no default export with toPlugin):`);
 			for (const f of skipped) log.warn(`  - ${f}`);
 		}
+		if (resources.length === 0 && files.length === 0) log.warn(`[arc] loadResources: 0 matching files found at "${absDir}" (pattern: *${suffix}.{ts,js,mts,mjs}). Check the path and runtime layout (src/ vs dist/).`);
 	}
 	return resources;
 }

package/dist/logger/index.d.mts

@@ -0,0 +1,81 @@
+//#region src/logger/index.d.ts
+/**
+ * Arc Logger — Centralized debug & warning system
+ *
+ * Lightweight, zero-dependency logger for Arc framework internals.
+ * Inspired by the `debug` npm package — disabled by default, opt-in via
+ * environment variable or `createApp({ debug })` option.
+ *
+ * @example
+ * ```typescript
+ * // Enable via env var
+ * ARC_DEBUG=1 node server.js        // all modules
+ * ARC_DEBUG=scope,elevation node server.js // specific modules
+ *
+ * // Enable via createApp
+ * const app = await createApp({ debug: true });
+ * const app = await createApp({ debug: 'scope,elevation' });
+ *
+ * // Suppress warnings (not recommended)
+ * ARC_SUPPRESS_WARNINGS=1 node server.js
+ *
+ * // Framework internals use:
+ * import { arcLog } from '../logger/index.js';
+ * const log = arcLog('elevation');
+ * log.debug('Elevation applied', { userId });
+ * log.warn('Something unexpected');
+ * ```
+ */
+interface ArcLoggerOptions {
+  /**
+   * Enable debug output.
+   * - `true` or `'*'` — all modules
+   * - `string` — comma-separated module names (e.g., `'scope,elevation'`)
+   * - `false` — disabled (default)
+   */
+  debug?: boolean | string;
+  /**
+   * Custom log writer. Defaults to `console`.
+   * Useful for routing Arc logs into Fastify's pino logger or test fixtures.
+   */
+  writer?: ArcLogWriter;
+}
+interface ArcLogWriter {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+interface ArcLogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+/**
+ * Configure the Arc logger globally.
+ *
+ * Called automatically by `createApp({ debug })`, but can also be
+ * called manually for standalone usage outside of `createApp`.
+ */
+declare function configureArcLogger(options: ArcLoggerOptions): void;
+/**
+ * Create a module-scoped logger.
+ *
+ * Debug and info messages are gated by the `ARC_DEBUG` env var or
+ * `createApp({ debug })` option. Warnings always show (unless
+ * `ARC_SUPPRESS_WARNINGS=1`). Errors always show.
+ *
+ * @param module - Module name (e.g., 'scope', 'elevation', 'sse', 'preset')
+ * @returns Logger instance for that module
+ *
+ * @example
+ * ```typescript
+ * const log = arcLog('elevation');
+ * log.debug('Checking elevation header');
+ * log.warn('No authenticate decorator found');
+ * ```
+ */
+declare function arcLog(module: string): ArcLogger;
+//#endregion
+export { ArcLogWriter, ArcLogger, ArcLoggerOptions, arcLog, configureArcLogger };

package/dist/{logger-DLg8-Ueg.mjs → logger/index.mjs}

@@ -1,9 +1,4 @@
-import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 //#region src/logger/index.ts
-var logger_exports = /* @__PURE__ */ __exportAll({
-	arcLog: () => arcLog,
-	configureArcLogger: () => configureArcLogger
-});
 let globalOptions = {};
 /**
 * Configure the Arc logger globally.
@@ -73,4 +68,4 @@ function isSuppressed() {
 	return env === "1" || env === "true";
 }
 //#endregion
-export { configureArcLogger as n, logger_exports as r, arcLog as t };
+export { arcLog, configureArcLogger };