@carno.js/live 1.8.0

package/src/http/etag.ts

@@ -0,0 +1,144 @@
+import type { CarnoClosure, CarnoMiddleware, Context } from '@carno.js/core';
+import { canonical } from '../shared/canonical';
+import { fnv1a64 } from '../shared/hash';
+import { LIVE_POLL_HEADER, LIVE_RESOURCE_HEADER } from '../shared/protocol';
+import type { LiveInputs, LiveScope } from '../resource/types';
+
+export interface LiveRoutePath {
+    method: string;
+    path: string;
+    resourceId?: string;
+}
+
+export interface LivePollingRequest {
+    resourceId: string;
+    inputs: LiveInputs;
+    request: Request;
+}
+
+export type LivePollingGuard =
+    (request: LivePollingRequest) => LiveScope | null | Promise<LiveScope | null>;
+
+/** `/cards/:id` matches `/cards/42` and nothing deeper. */
+export function pathMatcher(pattern: string): RegExp {
+    const source = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/:[A-Za-z_][A-Za-z0-9_]*/g, '[^/]+');
+
+    return new RegExp(`^${source}$`);
+}
+
+/**
+ * Content-hash `ETag` on live GET routes, and `304` when the client already
+ * holds that content.
+ *
+ * This is the bottom rung of §8.4: a client with neither WebSocket nor SSE
+ * polls the same route the SPA calls, and pays for a body only when something
+ * changed. The hash is the canonical one -- the same function the engine uses
+ * to decide whether a recompute produced a patch -- so reordered JSON keys are
+ * the same content, not a change.
+ *
+ * Scoped to live routes on purpose. Putting an `ETag` on every GET in the
+ * application would change the behaviour of routes that asked for none of this.
+ */
+export class LiveETagMiddleware implements CarnoMiddleware {
+    private matchers: { matcher: RegExp; resourceId?: string }[] = [];
+    private pollingGuard: LivePollingGuard | null = null;
+
+    constructor(paths: LiveRoutePath[], private readonly options: { enabled?: boolean } = {}) {
+        this.setPaths(paths);
+    }
+
+    /** The plugin knows the live routes only after bootstrap. */
+    setPaths(paths: LiveRoutePath[]): void {
+        this.matchers = paths
+            .filter(entry => entry.method.toUpperCase() === 'GET')
+            .map(entry => ({ matcher: pathMatcher(entry.path), resourceId: entry.resourceId }));
+    }
+
+    setPollingGuard(guard: LivePollingGuard): void {
+        this.pollingGuard = guard;
+    }
+
+    async handle(ctx: Context, next: CarnoClosure): Promise<Response | void> {
+        const polling = ctx.req.headers.get(LIVE_POLL_HEADER) === '1';
+        const requestedResource = polling
+            ? ctx.req.headers.get(LIVE_RESOURCE_HEADER) ?? undefined
+            : undefined;
+        const route = ctx.method.toUpperCase() === 'GET'
+            ? this.routeFor(ctx.path, requestedResource)
+            : undefined;
+
+        if (polling && (!requestedResource || !route)) {
+            return new Response('Forbidden', { status: 403 });
+        }
+
+        if (!route) {
+            return next();
+        }
+
+        if (ctx.req.headers.get(LIVE_POLL_HEADER) === '1') {
+            const resourceId = route.resourceId;
+            const scope = resourceId && this.pollingGuard
+                ? await this.pollingGuard({
+                    resourceId,
+                    inputs: { params: ctx.params, query: ctx.query },
+                    request: ctx.req
+                })
+                : null;
+
+            if (!scope) {
+                return new Response('Forbidden', { status: 403 });
+            }
+
+            if (scope.headers) {
+                const headers = new Headers(ctx.req.headers);
+                new Headers(scope.headers).forEach((value, key) => headers.set(key, value));
+                (ctx as { req: Request }).req = new Request(ctx.req, { headers });
+            }
+        }
+
+        if (this.options.enabled === false) {
+            return next();
+        }
+
+        const response = await next();
+
+        if (response.status !== 200) {
+            return response;
+        }
+
+        const contentType = response.headers.get('Content-Type') ?? '';
+
+        if (!contentType.includes('application/json')) {
+            return response;
+        }
+
+        // Reading the body consumes the stream, so everything below hands the
+        // caller a rebuilt response rather than the one it just drained.
+        const body = await response.clone().text();
+        let tag: string;
+
+        try {
+            tag = `"${fnv1a64(canonical(JSON.parse(body)))}"`;
+        } catch {
+            // Content-Type said JSON and it is not. Not our problem to fix.
+            return response;
+        }
+
+        if (ctx.req.headers.get('If-None-Match') === tag) {
+            return new Response(null, { status: 304, headers: { ETag: tag } });
+        }
+
+        const headers = new Headers(response.headers);
+        headers.set('ETag', tag);
+
+        return new Response(body, { status: 200, headers });
+    }
+
+    private routeFor(path: string, resourceId?: string): { resourceId?: string } | undefined {
+        return this.matchers.find(route =>
+            route.matcher.test(path) && (resourceId === undefined || route.resourceId === resourceId)
+        );
+    }
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+import 'reflect-metadata';
+
+// Decorator and metadata
+export { Live } from './decorators/Live';
+export { LIVE_META } from './metadata';
+export type { LiveMeta, LiveOptions, LiveShared } from './metadata';
+
+// Plugin and services
+export { LivePlugin } from './LivePlugin';
+export type { LivePluginOptions } from './LivePlugin';
+export { closeLiveRuntime } from './runtime';
+export { LiveService } from './LiveService';
+export { LiveEngine } from './LiveEngine';
+export type { LiveTransport, LiveStats } from './LiveEngine';
+
+// Metrics
+export { LiveMetrics } from './observability';
+export type { MetricSink } from './observability';
+
+// Configuration
+export { DEFAULT_LIVE_CONFIG, resolveLiveConfig } from './config';
+export type { LiveConfig } from './config';
+
+// Scope
+export { ConnectionScopeResolver } from './transport/scope-resolver';
+export type { LiveHandshake, LiveScopeResolver } from './transport/scope-resolver';
+export type { LiveExecutionContext, LiveInputs, LiveResourceExecutor, LiveScope } from './resource/types';
+
+// Authorization
+export { AllowAllAuthorizer, authKeysOf, isAuthKey } from './auth/authorizer';
+export type { LiveAuthorizationRequest, LiveAuthorizer } from './auth/authorizer';
+
+// Invalidation
+export { InProcessBus } from './bus/InProcessBus';
+export type { InvalidationBus, InvalidationHandler } from './bus/InvalidationBus';
+export type { Dependency, InvalidationEvent } from './graph/types';
+export { ancestorsOf, rowKey, tableKey } from './graph/dep-key';
+export type { DepKey } from './graph/dep-key';
+export { WriteDuringComputeError } from './emitters/AppEmitter';
+export { PgNotifyBus, chunkEvents } from './bus/PgNotifyBus';
+export type { PgNotifyBusOptions } from './bus/PgNotifyBus';
+export { PgNotifyEmitter, eventsFromPayload } from './emitters/pg-notify-emitter';
+export type { PgNotifyEmitterOptions, PgNotifyTable } from './emitters/pg-notify-emitter';
+export { PgListener } from './emitters/pg-listener';
+export type { ListenableSql, PgListenerOptions } from './emitters/pg-listener';
+export { tableOfKey } from './graph/dep-key';
+
+// Protocol and patches, shared with the client
+export * from './shared/protocol';
+export type { PatchOp, PathSegment } from './patch/types';
+export { PatchEngine } from './patch/PatchEngine';
+export { canonical, NonSerializableInputError } from './shared/canonical';
+export { fnv1a64 } from './shared/hash';
+export { normalizeLiveInputs, resourceIdOf } from './shared/descriptor';
+export type { LiveDataOf, LiveDescriptor, LiveInputsOf } from './shared/descriptor';
+export type { OptimisticEntry, OptimisticList } from './client/optimistic';
+
+// Framework-free client adapter
+export { liveStore, liveStoreOf, liveIdentity, LiveSlot } from './client/vanilla';
+export type { LiveHandle } from './client/vanilla';
+
+export { WebSocketTransport, LadderTransport, PollingTransport, SseClientTransport, routeIndex } from './client/transport';
+export type { ClientTransport, TransportHandlers, EventSourceLike, RoutePath } from './client/transport';
+
+// Transports
+export { FanTransport } from './transport/FanTransport';
+export type { OwnedTransport } from './transport/FanTransport';
+export { SseTransport } from './transport/SseTransport';
+export type { SseTransportOptions } from './transport/SseTransport';
+export { createSseRoutes } from './transport/sse-routes';
+export type { SseRouteOptions } from './transport/sse-routes';
+
+// Conditional GET
+export { LiveETagMiddleware, pathMatcher } from './http/etag';
+export type { LivePollingGuard, LivePollingRequest, LiveRoutePath } from './http/etag';
+
+// First paint
+export { prefetchLive } from './resource/prefetch';
+export type { LivePayload } from './resource/prefetch';
+export { LiveRouteExecutionError } from './resource/route-executor';
+export { hydrationKey, toHydrateMap, readHydrationPayload, HYDRATION_ATTRIBUTE } from './client/hydrate';

package/src/metadata.ts

@@ -0,0 +1,21 @@
+export const LIVE_META = Symbol('carno:live');
+
+export type LiveShared = 'private' | 'tenant' | 'public';
+
+export interface LiveOptions {
+    /** Field that identifies a row of a returned collection. */
+    key?: string;
+
+    /** Who may share one computed instance. */
+    shared?: LiveShared;
+
+    /** Manual dependency keys for data the ORM cannot observe. */
+    dependsOn?: string[];
+}
+
+export interface LiveMeta {
+    key?: string;
+    shared: LiveShared;
+    dependsOn: string[];
+    handlerName: string;
+}

package/src/observability.ts

@@ -0,0 +1,54 @@
+/**
+ * The slice of `ObservabilityService` the live package needs.
+ *
+ * Declared structurally rather than imported so `@carno.js/core` stays an
+ * ordinary peer here and the metrics path is testable without one.
+ */
+export interface MetricSink {
+    onMetric(name: string, value: number, tags?: Record<string, string | number | boolean>): void;
+}
+
+/**
+ * Names the engine publishes, and the guard that keeps a broken metrics
+ * backend from breaking the engine.
+ *
+ * The engine calls this unconditionally; `none()` is what makes that safe when
+ * no observability plugin is installed, which is the default.
+ */
+export class LiveMetrics {
+    constructor(private readonly sink: MetricSink | null) {}
+
+    static none(): LiveMetrics {
+        return new LiveMetrics(null);
+    }
+
+    recompute(resource: string, producedPatch: boolean, ops: number, durationMs: number): void {
+        this.publish('live.recompute', 1, { resource, patched: producedPatch });
+        this.publish('live.recompute.ms', durationMs, { resource });
+
+        if (producedPatch) {
+            this.publish('live.patch.ops', ops, { resource });
+        }
+    }
+
+    invalidation(keys: number, fanout: number): void {
+        this.publish('live.invalidation.keys', keys);
+        this.publish('live.invalidation.fanout', fanout);
+    }
+
+    instances(count: number): void {
+        this.publish('live.instances', count);
+    }
+
+    private publish(name: string, value: number, tags?: Record<string, string | number | boolean>): void {
+        if (!this.sink) {
+            return;
+        }
+
+        try {
+            this.sink.onMetric(name, value, tags);
+        } catch {
+            // Losing a number is acceptable. Losing a recompute is not.
+        }
+    }
+}

package/src/patch/PatchEngine.ts

@@ -0,0 +1,235 @@
+import type { PatchOp, PathSegment } from './types';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function deepEqual(left: unknown, right: unknown): boolean {
+    if (left === right) {
+        return true;
+    }
+
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return left.length === right.length && left.every((item, i) => deepEqual(item, right[i]));
+    }
+
+    if (isPlainObject(left) && isPlainObject(right)) {
+        const leftKeys = Object.keys(left);
+
+        if (leftKeys.length !== Object.keys(right).length) {
+            return false;
+        }
+
+        return leftKeys.every(key =>
+            Object.prototype.hasOwnProperty.call(right, key) && deepEqual(left[key], right[key])
+        );
+    }
+
+    return false;
+}
+
+/**
+ * Snapshot → snapshot diffing, and patch application with structural sharing.
+ * Structural sharing keeps useSyncExternalStore snapshots referentially stable
+ * and lets framework memoization skip untouched branches.
+ */
+export class PatchEngine {
+    constructor(private readonly keyField?: string) {}
+
+    diff(prev: unknown, next: unknown): PatchOp[] {
+        const ops: PatchOp[] = [];
+        this.diffValue(prev, next, [], ops);
+        return ops;
+    }
+
+    apply(prev: unknown, ops: PatchOp[]): unknown {
+        if (ops.length === 0) {
+            return prev;
+        }
+
+        let root = prev;
+
+        for (const op of ops) {
+            root = this.applyOne(root, op);
+        }
+
+        return root;
+    }
+
+    private diffValue(prev: unknown, next: unknown, path: PathSegment[], ops: PatchOp[]): void {
+        if (prev === next) {
+            return;
+        }
+
+        if (Array.isArray(prev) && Array.isArray(next)) {
+            if (this.isKeyed(prev) && this.isKeyed(next)) {
+                this.diffKeyedArray(prev, next, path, ops);
+                return;
+            }
+
+            if (!deepEqual(prev, next)) {
+                ops.push({ op: 'set', path, value: next });
+            }
+            return;
+        }
+
+        if (isPlainObject(prev) && isPlainObject(next)) {
+            for (const key of Object.keys(prev)) {
+                if (!Object.prototype.hasOwnProperty.call(next, key)) {
+                    ops.push({ op: 'unset', path: [...path, key] });
+                }
+            }
+
+            for (const key of Object.keys(next)) {
+                if (!Object.prototype.hasOwnProperty.call(prev, key)) {
+                    ops.push({ op: 'set', path: [...path, key], value: next[key] });
+                    continue;
+                }
+
+                this.diffValue(prev[key], next[key], [...path, key], ops);
+            }
+            return;
+        }
+
+        if (!deepEqual(prev, next)) {
+            ops.push({ op: 'set', path, value: next });
+        }
+    }
+
+    private diffKeyedArray(
+        prev: unknown[],
+        next: unknown[],
+        path: PathSegment[],
+        ops: PatchOp[]
+    ): void {
+        const prevByKey = this.indexByKey(prev);
+        const nextByKey = this.indexByKey(next);
+
+        for (const key of prevByKey.keys()) {
+            if (!nextByKey.has(key)) {
+                ops.push({ op: 'remove', path, key });
+            }
+        }
+
+        next.forEach((row, index) => {
+            const key = this.keyOf(row)!;
+            const before = prevByKey.get(key);
+
+            if (before === undefined || !deepEqual(before, row)) {
+                ops.push({ op: 'upsert', path, key, index, value: row });
+            }
+        });
+
+        const survivingPrevKeys = [...prevByKey.keys()].filter(key => nextByKey.has(key));
+        const nextKeys = [...nextByKey.keys()];
+        const orderChanged =
+            survivingPrevKeys.length !== nextKeys.length ||
+            survivingPrevKeys.some((key, i) => key !== nextKeys[i]);
+
+        if (orderChanged) {
+            ops.push({ op: 'order', path, keys: nextKeys });
+        }
+    }
+
+    private isKeyed(value: unknown[]): boolean {
+        if (!this.keyField) {
+            return false;
+        }
+
+        return value.every(item => this.keyOf(item) !== undefined);
+    }
+
+    private keyOf(row: unknown): string | number | undefined {
+        if (!this.keyField || !isPlainObject(row)) {
+            return undefined;
+        }
+
+        const value = row[this.keyField];
+        return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+    }
+
+    private indexByKey(rows: unknown[]): Map<string | number, unknown> {
+        const index = new Map<string | number, unknown>();
+
+        for (const row of rows) {
+            index.set(this.keyOf(row)!, row);
+        }
+
+        return index;
+    }
+
+    private applyOne(root: unknown, op: PatchOp): unknown {
+        if (op.op === 'set') {
+            return this.replaceAt(root, op.path, () => op.value);
+        }
+
+        if (op.op === 'unset') {
+            const parentPath = op.path.slice(0, -1);
+            const key = op.path[op.path.length - 1];
+
+            return this.replaceAt(root, parentPath, current => {
+                if (!isPlainObject(current)) {
+                    return current;
+                }
+
+                const clone = { ...current };
+                delete clone[String(key)];
+                return clone;
+            });
+        }
+
+        return this.replaceAt(root, op.path, current => {
+            const rows = Array.isArray(current) ? current : [];
+
+            if (op.op === 'remove') {
+                return rows.filter(row => this.keyOf(row) !== op.key);
+            }
+
+            if (op.op === 'upsert') {
+                const index = rows.findIndex(row => this.keyOf(row) === op.key);
+
+                if (index === -1) {
+                    const clone = rows.slice();
+                    clone.splice(Math.min(op.index, clone.length), 0, op.value);
+                    return clone;
+                }
+
+                const clone = rows.slice();
+                clone[index] = op.value;
+                return clone;
+            }
+
+            const byKey = new Map(rows.map(row => [this.keyOf(row), row] as const));
+            return op.keys.map(key => byKey.get(key)).filter(row => row !== undefined);
+        });
+    }
+
+    /** Rebuild only the containers along `path`, preserving all other refs. */
+    private replaceAt(
+        root: unknown,
+        path: PathSegment[],
+        update: (current: unknown) => unknown
+    ): unknown {
+        if (path.length === 0) {
+            return update(root);
+        }
+
+        const [head, ...rest] = path;
+
+        if (Array.isArray(root)) {
+            const index = Number(head);
+            const clone = root.slice();
+            clone[index] = this.replaceAt(root[index], rest, update);
+            return clone;
+        }
+
+        const base = isPlainObject(root) ? root : {};
+        const key = String(head);
+        return { ...base, [key]: this.replaceAt(base[key], rest, update) };
+    }
+}

package/src/patch/types.ts

@@ -0,0 +1,39 @@
+export type PathSegment = string | number;
+
+/** Replace the value at `path`. */
+export interface SetOp {
+    op: 'set';
+    path: PathSegment[];
+    value: unknown;
+}
+
+/** Delete the property at `path`. */
+export interface UnsetOp {
+    op: 'unset';
+    path: PathSegment[];
+}
+
+/** Insert or replace one row of a keyed array at `path`. */
+export interface UpsertOp {
+    op: 'upsert';
+    path: PathSegment[];
+    key: string | number;
+    index: number;
+    value: unknown;
+}
+
+/** Remove one row, by key, from a keyed array at `path`. */
+export interface RemoveOp {
+    op: 'remove';
+    path: PathSegment[];
+    key: string | number;
+}
+
+/** Final key order of a keyed array at `path`. */
+export interface OrderOp {
+    op: 'order';
+    path: PathSegment[];
+    keys: (string | number)[];
+}
+
+export type PatchOp = SetOp | UnsetOp | UpsertOp | RemoveOp | OrderOp;