@carno.js/live 1.8.0 → 1.8.1

package/src/resource/ResourceRegistry.ts

@@ -1,178 +1,185 @@
-import 'reflect-metadata';
-import { CONTROLLER_META, PARAMS_META, ROUTES_META, type ParamMetadata } from '@carno.js/core';
-import type { Dependency } from '../graph/types';
-import { LIVE_META, type LiveMeta } from '../metadata';
-import { dependencyContext } from './dependency-context';
-import type {
-    LiveExecutionContext,
-    LiveInputs,
-    LiveResource,
-    LiveResourceExecutor
-} from './types';
-
-/**
- * Verbs that may carry @Live. The real criterion is idempotence, not the verb:
- * subscribing means re-running the handler whenever the data changes, and
- * re-running a write duplicates the side effect. GET and POST are the two the
- * web uses for reading; a PUT that only reads is an abuse of the protocol and
- * is not worth the API surface.
- */
-const ALLOWED_METHODS = new Set(['get', 'post']);
-
-/**
- * Parameters that would make the handler depend on a caller request rather
- * than its declared, replayable inputs. Middleware still receives a synthetic
- * request during every compute and may use it as a guard.
- */
-const FORBIDDEN_PARAMS: Record<string, string> = {
-    req: '@Req()',
-    ctx: '@Ctx()',
-    header: '@Header()',
-    locals: '@Locals()'
-};
-
-export class LiveValidationError extends Error {
-    constructor(message: string) {
-        super(message);
-        this.name = 'LiveValidationError';
-    }
-}
-
-interface RouteInfoLike {
-    method: string;
-    path: string;
-    handlerName: string;
-}
-
-export class ResourceRegistry {
-    private readonly resources = new Map<string, LiveResource>();
-
-    /**
-     * Scan a controller for @Live handlers and validate them.
-     *
-     * Validation runs at registration, which is bootstrap time: the core
-     * compiles everything at startup, so a misdeclared resource fails the boot
-     * instead of failing the first subscription in production.
-     */
-    register(
-        ControllerClass: new (...args: any[]) => any,
-        instance: any,
-        executor: LiveResourceExecutor
-    ): void {
-        const routes: RouteInfoLike[] = Reflect.getMetadata(ROUTES_META, ControllerClass) || [];
-        const controllerMeta: { path?: string } = Reflect.getMetadata(CONTROLLER_META, ControllerClass) || {};
-        const prefix = controllerMeta.path ?? '';
-
-        for (const route of routes) {
-            const meta: LiveMeta | undefined = Reflect.getMetadata(
-                LIVE_META,
-                ControllerClass,
-                route.handlerName
-            );
-
-            if (!meta) {
-                continue;
-            }
-
-            const id = `${ControllerClass.name}.${route.handlerName}`;
-            const where = `${ControllerClass.name}.${route.handlerName}()`;
-
-            if (!ALLOWED_METHODS.has(route.method)) {
-                throw new LiveValidationError(
-                    `${where} is decorated with @Live() on @${route.method.toUpperCase()}(). ` +
-                    `Subscribing means re-running the handler whenever the data changes, so it has ` +
-                    `to be idempotent. Only @Get() and @Post() may be live.`
-                );
-            }
-
-            const params: ParamMetadata[] =
-                Reflect.getMetadata(PARAMS_META, ControllerClass, route.handlerName) || [];
-
-            for (const type of ['req', 'ctx', 'header', 'locals']) {
-                const param = params.find(candidate => candidate.type === type);
-                const forbidden = param ? FORBIDDEN_PARAMS[param.type] : undefined;
-
-                if (forbidden) {
-                    throw new LiveValidationError(
-                        `${where} uses ${forbidden}, which is not a replayable live input. ` +
-                        `A live resource handler must be a pure function of its declared inputs.`
-                    );
-                }
-
-            }
-
-            if (route.method === 'get' && params.some(param => param.type === 'body')) {
-                throw new LiveValidationError(
-                    `${where} uses @Body() on @Get(). A GET subscription carries no body; ` +
-                    `declare the route as @Post() or read the value from @Query().`
-                );
-            }
-
-            if (meta.key !== undefined && (typeof meta.key !== 'string' || meta.key === '')) {
-                throw new LiveValidationError(`${where} declares an empty @Live({ key }).`);
-            }
-
-            if (this.resources.has(id)) {
-                throw new LiveValidationError(`Live resource "${id}" is already registered.`);
-            }
-
-            let resource: LiveResource;
-
-            resource = {
-                id,
-                controllerClass: ControllerClass,
-                controllerName: ControllerClass.name,
-                handlerName: route.handlerName,
-                meta,
-                params,
-                invoke: (inputs: LiveInputs, context: LiveExecutionContext = {}) =>
-                    executor(instance, resource, inputs, context),
-                httpPath: joinRoutePath(prefix, route.path),
-                httpMethod: route.method.toUpperCase()
-            };
-
-            this.resources.set(id, resource);
-        }
-    }
-
-    get(id: string): LiveResource | undefined {
-        return this.resources.get(id);
-    }
-
-    ids(): string[] {
-        return [...this.resources.keys()];
-    }
-
-    /** Every live route, as the HTTP layer addresses it. */
-    livePaths(): { method: string; path: string; resourceId: string }[] {
-        return [...this.resources.values()].map(resource => ({
-            method: resource.httpMethod,
-            path: resource.httpPath,
-            resourceId: resource.id
-        }));
-    }
-
-    /** Run the handler and report what it read. */
-    async compute(
-        resource: LiveResource,
-        inputs: LiveInputs,
-        context: LiveExecutionContext = {}
-    ): Promise<{ data: unknown; deps: Dependency[] }> {
-        const { result, deps } = await dependencyContext.run(collector => {
-            for (const key of resource.meta.dependsOn) {
-                collector.add({ key, columns: null });
-            }
-
-            return resource.invoke(inputs, context);
-        });
-
-        return { data: result, deps };
-    }
-}
-
-/** Same join the core router does: collapse the slashes, keep the root. */
-export function joinRoutePath(prefix: string, path: string): string {
-    const joined = `${prefix}${path}`.replace(/\/{2,}/g, '/');
-
-    return joined.length > 1 ? joined.replace(/\/$/, '') : (joined || '/');
-}
+import 'reflect-metadata';
+import { CONTROLLER_META, PARAMS_META, ROUTES_META, type ParamMetadata } from '@carno.js/core';
+import type { Dependency } from '../graph/types';
+import { LIVE_META, type LiveMeta, type LiveShared } from '../metadata';
+import { dependencyContext } from './dependency-context';
+import type {
+    LiveExecutionContext,
+    LiveInputs,
+    LiveResource,
+    LiveResourceExecutor
+} from './types';
+
+/**
+ * Verbs that may carry @Live. The real criterion is idempotence, not the verb:
+ * subscribing means re-running the handler whenever the data changes, and
+ * re-running a write duplicates the side effect. GET and POST are the two the
+ * web uses for reading; a PUT that only reads is an abuse of the protocol and
+ * is not worth the API surface.
+ */
+const ALLOWED_METHODS = new Set(['get', 'post']);
+
+/**
+ * Parameters that would make the handler depend on a caller request rather
+ * than its declared, replayable inputs. Middleware still receives a synthetic
+ * request during every compute and may use it as a guard.
+ */
+const FORBIDDEN_PARAMS: Record<string, string> = {
+    req: '@Req()',
+    ctx: '@Ctx()',
+    header: '@Header()',
+    locals: '@Locals()'
+};
+
+export class LiveValidationError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'LiveValidationError';
+    }
+}
+
+interface RouteInfoLike {
+    method: string;
+    path: string;
+    handlerName: string;
+}
+
+export class ResourceRegistry {
+    private readonly resources = new Map<string, LiveResource>();
+
+    /**
+     * Scan a controller for @Live handlers and validate them.
+     *
+     * Validation runs at registration, which is bootstrap time: the core
+     * compiles everything at startup, so a misdeclared resource fails the boot
+     * instead of failing the first subscription in production.
+     */
+    register(
+        ControllerClass: new (...args: any[]) => any,
+        instance: any,
+        executor: LiveResourceExecutor
+    ): void {
+        const routes: RouteInfoLike[] = Reflect.getMetadata(ROUTES_META, ControllerClass) || [];
+        const controllerMeta: { path?: string } = Reflect.getMetadata(CONTROLLER_META, ControllerClass) || {};
+        const prefix = controllerMeta.path ?? '';
+
+        for (const route of routes) {
+            const meta: LiveMeta | undefined = Reflect.getMetadata(
+                LIVE_META,
+                ControllerClass,
+                route.handlerName
+            );
+
+            if (!meta) {
+                continue;
+            }
+
+            const id = `${ControllerClass.name}.${route.handlerName}`;
+            const where = `${ControllerClass.name}.${route.handlerName}()`;
+
+            if (!ALLOWED_METHODS.has(route.method)) {
+                throw new LiveValidationError(
+                    `${where} is decorated with @Live() on @${route.method.toUpperCase()}(). ` +
+                    `Subscribing means re-running the handler whenever the data changes, so it has ` +
+                    `to be idempotent. Only @Get() and @Post() may be live.`
+                );
+            }
+
+            const params: ParamMetadata[] =
+                Reflect.getMetadata(PARAMS_META, ControllerClass, route.handlerName) || [];
+
+            for (const type of ['req', 'ctx', 'header', 'locals']) {
+                const param = params.find(candidate => candidate.type === type);
+                const forbidden = param ? FORBIDDEN_PARAMS[param.type] : undefined;
+
+                if (forbidden) {
+                    throw new LiveValidationError(
+                        `${where} uses ${forbidden}, which is not a replayable live input. ` +
+                        `A live resource handler must be a pure function of its declared inputs.`
+                    );
+                }
+
+            }
+
+            if (route.method === 'get' && params.some(param => param.type === 'body')) {
+                throw new LiveValidationError(
+                    `${where} uses @Body() on @Get(). A GET subscription carries no body; ` +
+                    `declare the route as @Post() or read the value from @Query().`
+                );
+            }
+
+            if (meta.key !== undefined && (typeof meta.key !== 'string' || meta.key === '')) {
+                throw new LiveValidationError(`${where} declares an empty @Live({ key }).`);
+            }
+
+            if (this.resources.has(id)) {
+                throw new LiveValidationError(`Live resource "${id}" is already registered.`);
+            }
+
+            let resource: LiveResource;
+
+            resource = {
+                id,
+                controllerClass: ControllerClass,
+                controllerName: ControllerClass.name,
+                handlerName: route.handlerName,
+                meta,
+                params,
+                invoke: (inputs: LiveInputs, context: LiveExecutionContext = {}) =>
+                    executor(instance, resource, inputs, context),
+                httpPath: joinRoutePath(prefix, route.path),
+                httpMethod: route.method.toUpperCase()
+            };
+
+            this.resources.set(id, resource);
+        }
+    }
+
+    get(id: string): LiveResource | undefined {
+        return this.resources.get(id);
+    }
+
+    ids(): string[] {
+        return [...this.resources.keys()];
+    }
+
+    /** Ids declared with this sharing mode, in registration order. */
+    idsShared(shared: LiveShared): string[] {
+        return [...this.resources.values()]
+            .filter(resource => resource.meta.shared === shared)
+            .map(resource => resource.id);
+    }
+
+    /** Every live route, as the HTTP layer addresses it. */
+    livePaths(): { method: string; path: string; resourceId: string }[] {
+        return [...this.resources.values()].map(resource => ({
+            method: resource.httpMethod,
+            path: resource.httpPath,
+            resourceId: resource.id
+        }));
+    }
+
+    /** Run the handler and report what it read. */
+    async compute(
+        resource: LiveResource,
+        inputs: LiveInputs,
+        context: LiveExecutionContext = {}
+    ): Promise<{ data: unknown; deps: Dependency[] }> {
+        const { result, deps } = await dependencyContext.run(collector => {
+            for (const key of resource.meta.dependsOn) {
+                collector.add({ key, columns: null });
+            }
+
+            return resource.invoke(inputs, context);
+        });
+
+        return { data: result, deps };
+    }
+}
+
+/** Same join the core router does: collapse the slashes, keep the root. */
+export function joinRoutePath(prefix: string, path: string): string {
+    const joined = `${prefix}${path}`.replace(/\/{2,}/g, '/');
+
+    return joined.length > 1 ? joined.replace(/\/$/, '') : (joined || '/');
+}

package/src/scope-warning.ts

@@ -0,0 +1,58 @@
+/**
+ * The one trap the default configuration sets, reported at boot.
+ *
+ * `@Live()` defaults to `shared: 'private'` and `ConnectionScopeResolver`
+ * makes the connection id the principal, so with neither configured the
+ * instance identity carries a connection id: two tabs of one user are two
+ * instances, and N viewers of the same data are N computes, N diffs and N
+ * queries. That is the safe default — nothing can leak between connections —
+ * but it scales in connections rather than in data, and it is silent.
+ *
+ * Both halves are known at bootstrap, so this is a fact rather than a
+ * heuristic: no sampling of a live instance rate is needed to state it.
+ */
+
+/** Resource ids listed inline before the message collapses to a count. */
+const MAX_LISTED = 8;
+
+export interface DefaultScopeWarningInput {
+    /** Ids of the resources that resolved to `shared: 'private'`. */
+    privateResourceIds: string[];
+    /** False as soon as the application passes any resolver of its own. */
+    usingDefaultResolver: boolean;
+    /** `LiveConfig.maxInstancesPerNode`, the ceiling this default runs into. */
+    maxInstancesPerNode: number;
+}
+
+/**
+ * The warning text, or null when there is nothing to warn about.
+ *
+ * Returned rather than printed so the decision is testable without capturing
+ * the console.
+ */
+export function defaultScopeWarning(input: DefaultScopeWarningInput): string | null {
+    if (!input.usingDefaultResolver || input.privateResourceIds.length === 0) {
+        return null;
+    }
+
+    const count = input.privateResourceIds.length;
+    const listed = input.privateResourceIds.slice(0, MAX_LISTED).join(', ');
+    const rest = count - Math.min(count, MAX_LISTED);
+    const names = rest > 0 ? `${listed} and ${rest} more` : listed;
+    const noun = count === 1 ? 'live resource is' : 'live resources are';
+
+    return [
+        '[carno:live] No `scopeResolver` was passed to LivePlugin.create(), so the default',
+        'ConnectionScopeResolver keys every instance by connection id.',
+        `  ${count} ${noun} private (the @Live() default) and will get one instance per`,
+        '  connection rather than one per user:',
+        `    ${names}`,
+        '  Two tabs of the same user are two instances, and N viewers of the same data are N',
+        `  computes, N diffs and N queries — against the ceiling of ${input.maxInstancesPerNode} instances per node`,
+        '  (LiveConfig.maxInstancesPerNode), past which subscriptions are refused.',
+        '  Fix: pass a `scopeResolver` whose principal is a user id, or declare the resources',
+        '  that are genuinely shared as @Live({ shared: \'public\' }) or @Live({ shared: \'tenant\' }).',
+        '  To keep per-connection instances and silence this, pass',
+        '  `scopeResolver: new ConnectionScopeResolver()` explicitly.'
+    ].join('\n');
+}