@carno.js/live 1.8.0

package/src/resource/ResourceRegistry.ts

@@ -0,0 +1,178 @@
+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 || '/');
+}

package/src/resource/dependency-context.ts

@@ -0,0 +1,48 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { Dependency } from '../graph/types';
+
+export class DependencyCollector {
+    private readonly deps: Dependency[] = [];
+
+    add(dep: Dependency): void {
+        this.deps.push(dep);
+    }
+
+    addAll(deps: Dependency[]): void {
+        for (const dep of deps) {
+            this.deps.push(dep);
+        }
+    }
+
+    drain(): Dependency[] {
+        return this.deps.slice();
+    }
+}
+
+/**
+ * Collects the reads performed during one resource compute.
+ *
+ * Same AsyncLocalStorage shape as identityMapContext, tenantContext and
+ * transactionContext in @carno.js/orm — concurrent computes each get their own
+ * collector without threading a parameter through user code.
+ */
+class DependencyContext {
+    private readonly storage = new AsyncLocalStorage<DependencyCollector>();
+
+    async run<T>(fn: (collector: DependencyCollector) => Promise<T> | T): Promise<{ result: T; deps: Dependency[] }> {
+        const collector = new DependencyCollector();
+        const result = await this.storage.run(collector, async () => fn(collector));
+
+        return { result, deps: collector.drain() };
+    }
+
+    current(): DependencyCollector | undefined {
+        return this.storage.getStore();
+    }
+
+    isActive(): boolean {
+        return this.storage.getStore() !== undefined;
+    }
+}
+
+export const dependencyContext = new DependencyContext();

package/src/resource/instance-id.ts

@@ -0,0 +1,65 @@
+import { canonical } from '../shared/canonical';
+import { fnv1a64 } from '../shared/hash';
+import type { LiveShared } from '../metadata';
+import type { LiveInputs, LiveScope } from '../shared/inputs';
+
+export class MissingScopeError extends Error {
+    constructor(public readonly dimension: 'tenant' | 'principal') {
+        super(
+            `Live resource requires a ${dimension} in scope but none was resolved. ` +
+            'Register a LiveScopeResolver, or declare the resource as @Live({ shared: \'public\' }).'
+        );
+        this.name = 'MissingScopeError';
+    }
+}
+
+export class InputTooLargeError extends Error {
+    constructor(public readonly size: number, public readonly limit: number) {
+        super(`Live subscription inputs are ${size} bytes, over the ${limit} byte limit.`);
+        this.name = 'InputTooLargeError';
+    }
+}
+
+/** The scope half of the instance identity, embedded literally and encoded. */
+export function scopeKeyOf(shared: LiveShared, scope: LiveScope): string {
+    if (shared === 'public') {
+        return 'pub';
+    }
+
+    if (shared === 'tenant') {
+        if (scope.tenant === undefined || scope.tenant === null || scope.tenant === '') {
+            throw new MissingScopeError('tenant');
+        }
+
+        return `t:${encodeURIComponent(String(scope.tenant))}`;
+    }
+
+    if (scope.principal === undefined || scope.principal === null || scope.principal === '') {
+        throw new MissingScopeError('principal');
+    }
+
+    return `p:${encodeURIComponent(String(scope.principal))}`;
+}
+
+/** Canonical form of inputs, guarded by the size ceiling. */
+export function canonicalInputs(inputs: LiveInputs, maxInputBytes: number): string {
+    const encoded = canonical({
+        params: inputs.params ?? {},
+        query: inputs.query ?? {},
+        // `canonical` renders undefined and null identically, so a GET (no
+        // body) and a POST with an empty body land on the same string.
+        body: inputs.body ?? null
+    });
+    const size = Buffer.byteLength(encoded, 'utf8');
+
+    if (size > maxInputBytes) {
+        throw new InputTooLargeError(size, maxInputBytes);
+    }
+
+    return encoded;
+}
+
+/** Same resource, scope and inputs means one compute, one diff and N sends. */
+export function instanceIdOf(resourceId: string, scopeKey: string, canonicalInputsValue: string): string {
+    return `${resourceId}|${scopeKey}|${fnv1a64(canonicalInputsValue)}`;
+}

package/src/resource/prefetch.ts

@@ -0,0 +1,49 @@
+import { canonical } from '../shared/canonical';
+import { normalizeLiveInputs } from '../shared/descriptor';
+import { fnv1a64 } from '../shared/hash';
+import type { LiveExecutionContext, LiveInputs } from './types';
+import type { ResourceRegistry } from './ResourceRegistry';
+
+/** What a server-rendered page hands the client so the first paint is full. */
+export interface LivePayload {
+    resourceId: string;
+    inputs: LiveInputs;
+    data: unknown;
+    hash: string;
+}
+
+/**
+ * Compute a live resource once, for the first paint.
+ *
+ * Deliberately not a subscription: nothing is registered in the dependency
+ * graph and no instance is created. Every rendered page would otherwise leave
+ * behind an instance being recomputed forever, including the ones nobody ever
+ * subscribes to -- the worst possible cost for the most common case. The
+ * instance is born when a client subscribes, and the hash returned here is
+ * what makes that subscription carry no data.
+ */
+export async function prefetchLive(
+    resources: ResourceRegistry,
+    resourceId: string,
+    inputs: Partial<LiveInputs> = {},
+    context: LiveExecutionContext = {}
+): Promise<LivePayload> {
+    const resource = resources.get(resourceId);
+
+    if (!resource) {
+        throw new Error(
+            `[carno:live] cannot prefetch "${resourceId}": no live resource by that name. ` +
+            `Is its controller listed in LivePlugin.create({ controllers })?`
+        );
+    }
+
+    const normalized = normalizeLiveInputs(inputs);
+    const { data } = await resources.compute(resource, normalized, context);
+
+    return {
+        resourceId,
+        inputs: normalized,
+        data,
+        hash: fnv1a64(canonical(data))
+    };
+}

package/src/resource/route-executor.ts

@@ -0,0 +1,134 @@
+import {
+    HttpException,
+    ValidationException,
+    type Carno
+} from '@carno.js/core';
+import type {
+    LiveExecutionContext,
+    LiveInputs,
+    LiveResource,
+    LiveResourceExecutor
+} from './types';
+
+export class LiveRouteExecutionError extends Error {
+    constructor(
+        public readonly statusCode: number,
+        message: string
+    ) {
+        super(message);
+        this.name = 'LiveRouteExecutionError';
+    }
+}
+
+export function isLiveAuthorizationFailure(error: unknown): boolean {
+    return error instanceof LiveRouteExecutionError &&
+        (error.statusCode === 401 || error.statusCode === 403);
+}
+
+/**
+ * Adapt the core's compiled HTTP route to a Live resource compute.  The
+ * adapter is created once at startup; only the synthetic request and response
+ * decoding happen per compute.
+ */
+export function createLiveRouteExecutor(carno: Carno): LiveResourceExecutor {
+    return async (
+        _controllerInstance: any,
+        resource: LiveResource,
+        inputs: LiveInputs,
+        context: LiveExecutionContext
+    ): Promise<unknown> => {
+        const request = createRequest(resource, inputs, context);
+        let response: Response;
+
+        try {
+            response = await carno.executeCompiledRoute(
+                resource.controllerClass,
+                resource.handlerName,
+                request,
+                inputs.params
+            );
+        } catch (error) {
+            if (error instanceof HttpException || error instanceof ValidationException) {
+                response = error.toResponse();
+            } else {
+                throw error;
+            }
+        }
+
+        if (response.status < 200 || response.status >= 300) {
+            const detail = await response.text().catch(() => '');
+            throw new LiveRouteExecutionError(
+                response.status,
+                detail || `Live route returned HTTP ${response.status}.`
+            );
+        }
+
+        return decodeResponse(response);
+    };
+}
+
+function createRequest(
+    resource: LiveResource,
+    inputs: LiveInputs,
+    context: LiveExecutionContext
+): Request {
+    const path = interpolatePath(resource.httpPath, inputs.params, resource.id);
+    const url = new URL(`http://carno.live${path}`);
+
+    for (const [key, value] of Object.entries(inputs.query)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            url.searchParams.append(key, item);
+        }
+    }
+
+    const headers = new Headers(context.scope?.headers);
+
+    if (context.headers) {
+        new Headers(context.headers).forEach((value, key) => headers.set(key, value));
+    }
+
+    const hasBody = resource.httpMethod === 'POST' && inputs.body !== undefined;
+
+    if (hasBody && !headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+
+    return new Request(url, {
+        method: resource.httpMethod,
+        headers,
+        body: hasBody ? JSON.stringify(inputs.body) : undefined
+    });
+}
+
+function interpolatePath(
+    path: string,
+    params: Record<string, string>,
+    resourceId: string
+): string {
+    return path.replace(/:([A-Za-z0-9_]+)/g, (_segment, key: string) => {
+        const value = params[key];
+
+        if (value === undefined) {
+            throw new LiveRouteExecutionError(
+                400,
+                `Live resource "${resourceId}" is missing route parameter "${key}".`
+            );
+        }
+
+        return encodeURIComponent(value);
+    });
+}
+
+async function decodeResponse(response: Response): Promise<unknown> {
+    if (response.status === 204) {
+        return undefined;
+    }
+
+    const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+
+    if (contentType.includes('json')) {
+        return response.json();
+    }
+
+    return response.text();
+}

package/src/resource/types.ts

@@ -0,0 +1,35 @@
+import type { ParamMetadata } from '@carno.js/core';
+import type { LiveMeta } from '../metadata';
+
+export type { LiveInputs, LiveScope } from '../shared/inputs';
+import type { LiveInputs, LiveScope } from '../shared/inputs';
+
+export interface LiveExecutionContext {
+    /** Scope resolved for a subscription, including optional middleware headers. */
+    scope?: LiveScope;
+    /** Explicit headers, useful when prefetching from an authenticated SSR request. */
+    headers?: HeadersInit;
+}
+
+export interface LiveResourceExecutor {
+    (
+        controllerInstance: any,
+        resource: LiveResource,
+        inputs: LiveInputs,
+        context: LiveExecutionContext
+    ): Promise<unknown>;
+}
+
+export interface LiveResource {
+    /** `${controllerName}.${handlerName}` */
+    id: string;
+    controllerClass: new (...args: any[]) => any;
+    controllerName: string;
+    handlerName: string;
+    meta: LiveMeta;
+    params: ParamMetadata[];
+    invoke(inputs: LiveInputs, context?: LiveExecutionContext): Promise<unknown>;
+    /** Full HTTP path, controller prefix included. Used by the ETag layer. */
+    httpPath: string;
+    httpMethod: string;
+}

package/src/runtime.ts

@@ -0,0 +1,69 @@
+import type { LiveEngine } from './LiveEngine';
+import type { SocketTransport } from './transport/SocketTransport';
+import type { LiveScopeResolver } from './transport/scope-resolver';
+import type { LiveScope } from './shared/inputs';
+import type { ResourceRegistry } from './resource/ResourceRegistry';
+
+export interface LiveRuntime {
+    engine: LiveEngine;
+    transport: SocketTransport;
+    resolver: LiveScopeResolver;
+    scopes: Map<string, LiveScope>;
+    /** Connections that have completed their single allowed hello. */
+    handshakes: Set<string>;
+    /** Needed by prefetch(), which computes without subscribing. */
+    resources: ResourceRegistry;
+    /**
+     * Everything the plugin opened and nothing else knows about: the dedicated
+     * LISTEN connections of the Postgres emitter and of the distributed bus,
+     * plus the engine's timers.
+     */
+    dispose?: (() => Promise<void> | void)[];
+}
+
+let current: LiveRuntime | null = null;
+
+/**
+ * Process-wide holder, same shape as `Orm.getInstance()`.
+ *
+ * The gateway is instantiated by the core container, which has no factory
+ * providers, so constructor-injecting a hand-built engine would need a
+ * registration dance that exists only to satisfy the container.
+ */
+export function setLiveRuntime(runtime: LiveRuntime): void {
+    current = runtime;
+}
+
+export function getLiveRuntime(): LiveRuntime {
+    if (!current) {
+        throw new Error('[carno:live] LivePlugin.create() has not run yet.');
+    }
+
+    return current;
+}
+
+/**
+ * Close whatever the plugin opened, then forget the runtime.
+ *
+ * Dropping the reference alone is not enough: a LISTEN connection is a socket
+ * held open by nothing the container can see, so a process that builds and
+ * tears down several Carno instances — a test suite, most obviously — runs the
+ * database out of client slots.
+ */
+export async function closeLiveRuntime(): Promise<void> {
+    const runtime = current;
+    current = null;
+
+    for (const close of runtime?.dispose ?? []) {
+        try {
+            await close();
+        } catch (error) {
+            console.error('[carno:live] failed to close a live connection', error);
+        }
+    }
+}
+
+/** Synchronous form. Prefer `closeLiveRuntime()` when you can await. */
+export function resetLiveRuntime(): void {
+    void closeLiveRuntime();
+}

package/src/shared/canonical.ts

@@ -0,0 +1,63 @@
+/**
+ * Deterministic JSON canonicalization, shared verbatim by client and server.
+ *
+ * Both sides MUST produce byte-identical output for the same logical value:
+ * the instance id and the content hash are derived from it, so a divergence
+ * silently breaks subscription dedupe and the hydration handshake instead of
+ * failing loudly.
+ */
+export class NonSerializableInputError extends Error {
+    constructor(
+        public readonly path: string,
+        public readonly received: string
+    ) {
+        super(`Live input at "${path}" is not serializable (received ${received}).`);
+        this.name = 'NonSerializableInputError';
+    }
+}
+
+export function canonical(value: unknown, path: string = '$'): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new NonSerializableInputError(path, String(value));
+            }
+            // -0 and 0 are the same input as far as a query is concerned.
+            return Object.is(value, -0) ? '0' : String(value);
+        case 'string':
+            return JSON.stringify(value);
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new NonSerializableInputError(path, typeof value);
+    }
+
+    if (Array.isArray(value)) {
+        const items = value.map((item, index) => canonical(item, `${path}[${index}]`));
+        return `[${items.join(',')}]`;
+    }
+
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        // Date, Map, Set, class instances: no agreed wire form, so refuse
+        // rather than guess one the client would canonicalize differently.
+        const name = (value as object).constructor?.name ?? 'object';
+        throw new NonSerializableInputError(path, name);
+    }
+
+    const entries = Object.entries(value as Record<string, unknown>)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+
+    const body = entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, `${path}.${key}`)}`)
+        .join(',');
+
+    return `{${body}}`;
+}

package/src/shared/descriptor.ts

@@ -0,0 +1,44 @@
+import type { LiveInputs } from './inputs';
+
+/**
+ * Structural twin of the descriptor @carno.js/client emits.
+ *
+ * The generated file imports nothing, on purpose, so the two definitions meet
+ * through TypeScript's structural typing. Keep the field names identical.
+ */
+export interface LiveDescriptor<R = unknown> {
+    readonly method: string;
+    readonly path: string;
+    readonly resourceId?: string;
+    readonly live?: { readonly shared: 'private' | 'tenant' | 'public'; readonly key?: string };
+    readonly __route?: R;
+}
+
+/** What the route answers, as the client sees it. */
+export type LiveDataOf<R> = R extends { response: infer S } ? Exclude<S, undefined | void> : unknown;
+
+/** What the route takes, as a subscription sends it. */
+export type LiveInputsOf<R> =
+    (R extends { params: infer P } ? { params: P } : { params?: Record<string, string> })
+    & (R extends { query: infer Q } ? { query: Q } : { query?: Record<string, string | string[]> })
+    & (R extends { body: infer B } ? { body: B } : { body?: undefined });
+
+export function resourceIdOf(descriptor: LiveDescriptor<any>): string {
+    if (!descriptor.resourceId || !descriptor.live) {
+        throw new Error(
+            `${descriptor.method.toUpperCase()} ${descriptor.path} is not a live resource. ` +
+            `Add @Live() to the handler and re-run the client codegen.`
+        );
+    }
+
+    return descriptor.resourceId;
+}
+
+/** Fill the three input slots, whichever of them the caller bothered with. */
+export function normalizeLiveInputs(inputs: Partial<LiveInputs> = {}): LiveInputs {
+    return {
+        params: inputs.params ?? {},
+        query: inputs.query ?? {},
+        body: inputs.body
+    };
+}