@carno.js/live 1.8.0

package/src/LivePlugin.ts

@@ -0,0 +1,253 @@
+import { Carno, ObservabilityService, type Container } from '@carno.js/core';
+import { Orm } from '@carno.js/orm';
+import { WebSocketPlugin, type WebSocketPluginConfig } from '@carno.js/websocket';
+import { AllowAllAuthorizer, type LiveAuthorizer } from './auth/authorizer';
+import { InProcessBus } from './bus/InProcessBus';
+import type { InvalidationBus } from './bus/InvalidationBus';
+import { PgNotifyBus } from './bus/PgNotifyBus';
+import { PgNotifyEmitter, type PgNotifyTable } from './emitters/pg-notify-emitter';
+import type { InvalidationEvent } from './graph/types';
+import { resolveLiveConfig, type LiveConfig } from './config';
+import { AppEmitter } from './emitters/AppEmitter';
+import { DependencyGraph } from './graph/DependencyGraph';
+import { SubscriptionRegistry } from './graph/SubscriptionRegistry';
+import { LiveEngine } from './LiveEngine';
+import { LiveMetrics } from './observability';
+import { LiveService } from './LiveService';
+import { ResourceRegistry } from './resource/ResourceRegistry';
+import { createLiveRouteExecutor } from './resource/route-executor';
+import { setLiveRuntime } from './runtime';
+import { LiveETagMiddleware } from './http/etag';
+import { FanTransport } from './transport/FanTransport';
+import { dropLiveConnection, LiveGateway } from './transport/LiveGateway';
+import { ConnectionScopeResolver, type LiveScopeResolver } from './transport/scope-resolver';
+import { SocketTransport } from './transport/SocketTransport';
+import { SseTransport } from './transport/SseTransport';
+import { createSseRoutes } from './transport/sse-routes';
+import { LIVE_CONNECTION_HEADER, LIVE_TOKEN_HEADER } from './shared/protocol';
+
+export interface LivePluginOptions {
+    /** Controllers holding @Live() handlers. Validated at bootstrap. */
+    controllers: (new (...args: any[]) => any)[];
+    /**
+     * Your own @Gateway classes. They must be listed here rather than passed to
+     * a second WebSocketPlugin: Carno.use() keeps only one WebSocket handler
+     * builder, so a second plugin silently wins and orphans the first.
+     */
+    gateways?: (new (...args: any[]) => any)[];
+    scopeResolver?: LiveScopeResolver;
+    /**
+     * Decides whether a connection may hold a subscription, and is re-asked
+     * whenever `LiveService.invalidate('auth:principal#<id>')` fires.
+     */
+    authorizer?: LiveAuthorizer;
+    /**
+     * Watch these tables with a Postgres trigger, so writes that never went
+     * through @carno.js/orm also invalidate. Requires PostgreSQL 11 or newer.
+     */
+    pgNotify?: {
+        tables: PgNotifyTable[];
+        /** Defaults to the ORM's own connection string. */
+        url?: string;
+        channel?: string;
+    };
+    /** Carry invalidations from this node to the others. */
+    distributed?: {
+        transport: 'pg-notify';
+        url?: string;
+        channel?: string;
+        nodeId?: string;
+    };
+    config?: Partial<LiveConfig>;
+    websocket?: WebSocketPluginConfig;
+    /**
+     * Content-hash ETag on live GET routes, so a client with neither
+     * WebSocket nor SSE can poll cheaply. On by default: it only ever adds a
+     * header, and it only touches routes that are live.
+     */
+    etag?: boolean;
+    /**
+     * Serve the protocol over Server-Sent Events as well, for clients whose
+     * proxy blocks WebSocket. Off by default: it adds two public routes.
+     */
+    sse?: boolean;
+}
+
+export class LivePlugin {
+    static create(options: LivePluginOptions): Carno {
+        const config = resolveLiveConfig(options.config);
+        const resources = new ResourceRegistry();
+        const graph = new DependencyGraph();
+        const subs = new SubscriptionRegistry();
+        const distributedBus = options.distributed
+            ? new PgNotifyBus({
+                url: options.distributed.url ?? '',
+                channel: options.distributed.channel,
+                nodeId: options.distributed.nodeId
+            })
+            : null;
+        const bus: InvalidationBus = distributedBus ?? new InProcessBus();
+        const sockets = new SocketTransport();
+        const fan = new FanTransport();
+        fan.add(sockets);
+        let sink: ObservabilityService | null = null;
+        const metrics = new LiveMetrics({
+            onMetric: (name, value, tags) => sink?.onMetric(name, value, tags)
+        });
+
+        const engine = new LiveEngine(
+            resources,
+            graph,
+            subs,
+            bus,
+            fan,
+            config,
+            options.authorizer ?? new AllowAllAuthorizer(),
+            metrics
+        );
+        const emitter = new AppEmitter(bus, config);
+        const scopeResolver = options.scopeResolver ?? new ConnectionScopeResolver();
+
+        const dispose: (() => Promise<void> | void)[] = [() => engine.stop()];
+
+        setLiveRuntime({
+            engine,
+            transport: sockets,
+            resolver: scopeResolver,
+            scopes: new Map(),
+            handshakes: new Set(),
+            resources,
+            dispose
+        });
+
+        const plugin = new Carno({ exports: [] });
+        plugin.controllers(options.controllers);
+        plugin.services([LiveService]);
+
+        if (options.sse) {
+            const sse = new SseTransport({
+                heartbeatMs: config.sseHeartbeatMs,
+                maxConnections: config.sseMaxConnections,
+                onDisconnect: dropLiveConnection
+            });
+
+            fan.add(sse);
+            dispose.push(() => sse.stop());
+
+            const routes = createSseRoutes({
+                transport: sse,
+                streamPath: config.ssePath,
+                controlPath: config.sseControlPath
+            });
+
+            plugin.route('GET', routes.streamPath, routes.stream);
+            plugin.route('POST', routes.controlPath, routes.control);
+        }
+
+        let teachEtag: ((paths: { method: string; path: string; resourceId?: string }[]) => void) | null = null;
+
+        // Registered now, taught later: `plugin.middlewares()` runs before
+        // bootstrap, and the resources are only known inside the builder.
+        // The middleware also gates polling, even when ETags are disabled.
+        const etag = new LiveETagMiddleware([], { enabled: options.etag !== false });
+        etag.setPollingGuard(async ({ resourceId, inputs, request }) => {
+            const connectionId = request.headers.get(LIVE_CONNECTION_HEADER);
+
+            if (!connectionId) {
+                return null;
+            }
+
+            let scope;
+
+            try {
+                scope = await scopeResolver.resolve({
+                    connectionId,
+                    token: request.headers.get(LIVE_TOKEN_HEADER) ?? undefined
+                });
+            } catch {
+                return null;
+            }
+
+            return await engine.authorizePolling(connectionId, resourceId, inputs, scope)
+                ? scope
+                : null;
+        });
+        plugin.middlewares([etag]);
+        teachEtag = paths => etag.setPaths(paths);
+
+        const websocket = WebSocketPlugin.create(
+            [LiveGateway, ...(options.gateways ?? [])],
+            options.websocket
+        );
+
+        const innerBuilder = websocket._wsHandlerBuilder!;
+        const upgradePaths = [...websocket._wsUpgradePaths];
+
+        plugin.use(websocket);
+
+        // The builder runs after bootstrap, when the container holds the
+        // controller instances and the ORM holds its connection — which is why
+        // everything that needs a database URL is started here and not above.
+        plugin.wsHandler((container: Container) => {
+            // Resolved here and not above: the container does not exist until
+            // bootstrap, and an app with no observability plugin never
+            // registers one.
+            sink = container.has(ObservabilityService) ? container.get(ObservabilityService) : null;
+            const routeExecutor = createLiveRouteExecutor(container.get(Carno));
+
+            for (const ControllerClass of options.controllers) {
+                resources.register(ControllerClass, container.get(ControllerClass), routeExecutor);
+            }
+
+            teachEtag?.(resources.livePaths());
+
+            if (options.pgNotify) {
+                const driver = Orm.getInstance().driverInstance;
+                const deliver = (events: InvalidationEvent[]): void => {
+                    // A trigger already notified every node. Publishing it on
+                    // the bus would send it around a second time.
+                    if (distributedBus) {
+                        distributedBus.publishLocal(events);
+                        return;
+                    }
+
+                    bus.publish(events);
+                };
+
+                const pgEmitter = new PgNotifyEmitter(deliver, {
+                    tables: options.pgNotify.tables,
+                    url: options.pgNotify.url ?? driver.connectionString,
+                    channel: options.pgNotify.channel,
+                    execute: sql => driver.executeSql(sql)
+                });
+
+                // Two emitters on one table would wake the same instance twice.
+                emitter.setCoveredTables(pgEmitter.coveredTables());
+                dispose.push(() => pgEmitter.detach());
+
+                void pgEmitter.attach().catch(error => {
+                    console.error('[carno:live] the Postgres emitter failed to attach', error);
+                });
+            }
+
+            if (distributedBus) {
+                if (!options.distributed?.url) {
+                    distributedBus.setUrl(Orm.getInstance().driverInstance.connectionString);
+                }
+
+                void distributedBus.start().catch(error => {
+                    console.error('[carno:live] the distributed bus failed to start', error);
+                });
+
+                dispose.push(() => distributedBus.stop());
+            }
+
+            emitter.attach();
+            engine.start();
+
+            return innerBuilder(container);
+        }, upgradePaths);
+
+        return plugin;
+    }
+}

package/src/LiveService.ts

@@ -0,0 +1,47 @@
+import { Service } from '@carno.js/core';
+import { getLiveRuntime } from './runtime';
+import { prefetchLive, type LivePayload } from './resource/prefetch';
+import { resourceIdOf, type LiveDescriptor } from './shared/descriptor';
+import type { LiveExecutionContext, LiveInputs } from './resource/types';
+
+/**
+ * Manual invalidation — the third emitter of §4.4, for data the ORM cannot
+ * see: a rebuilt report, a webhook, an external cache.
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * export class ReportJob {
+ *     constructor(private readonly live: LiveService) {}
+ *
+ *     @Cron('0 * * * *')
+ *     async run() {
+ *         await this.rebuild();
+ *         this.live.invalidate('app:report:current');
+ *     }
+ * }
+ * ```
+ */
+@Service()
+export class LiveService {
+    invalidate(key: string): void {
+        getLiveRuntime().engine.invalidate(key);
+    }
+
+    /**
+     * Compute a live resource for a server-rendered first paint.
+     *
+     * Hand the payload to the template; the client starts full and its
+     * subscription carries only the hash, so the first screen costs one
+     * request instead of two and the data is never sent twice.
+     */
+    prefetch(
+        resource: string | LiveDescriptor<any>,
+        inputs: Partial<LiveInputs> = {},
+        context: LiveExecutionContext = {}
+    ): Promise<LivePayload> {
+        const resourceId = typeof resource === 'string' ? resource : resourceIdOf(resource);
+
+        return prefetchLive(getLiveRuntime().resources, resourceId, inputs, context);
+    }
+}

package/src/auth/authorizer.ts

@@ -0,0 +1,56 @@
+import type { LiveMeta } from '../metadata';
+import type { LiveInputs, LiveScope } from '../shared/inputs';
+
+export interface LiveAuthorizationRequest {
+    resourceId: string;
+    controllerName: string;
+    handlerName: string;
+    meta: LiveMeta;
+    inputs: LiveInputs;
+    scope: LiveScope;
+    connectionId: string;
+}
+
+/**
+ * Decides whether one connection may hold one subscription.
+ *
+ * Called when the subscription is created and again whenever the connection's
+ * `auth:` key is invalidated. Returning false ends that connection's
+ * subscription; it never affects the other subscribers of a shared instance.
+ */
+export interface LiveAuthorizer {
+    authorize(request: LiveAuthorizationRequest): boolean | Promise<boolean>;
+}
+
+/** Default. The scope already isolates instances, so nothing extra is refused. */
+export class AllowAllAuthorizer implements LiveAuthorizer {
+    authorize(): boolean {
+        return true;
+    }
+}
+
+const AUTH_PREFIX = 'auth:';
+
+export function isAuthKey(key: string): boolean {
+    return key.startsWith(AUTH_PREFIX);
+}
+
+/**
+ * The authorization keys a connection with this scope answers to.
+ *
+ * Same two-level shape as the ORM keys: `auth:principal#42` is contained by
+ * `auth:principal`, so invalidating the parent re-checks everyone.
+ */
+export function authKeysOf(scope: LiveScope): string[] {
+    const keys: string[] = [];
+
+    if (scope.principal !== undefined && scope.principal !== null && scope.principal !== '') {
+        keys.push(`${AUTH_PREFIX}principal#${scope.principal}`);
+    }
+
+    if (scope.tenant !== undefined && scope.tenant !== null && scope.tenant !== '') {
+        keys.push(`${AUTH_PREFIX}tenant#${scope.tenant}`);
+    }
+
+    return keys;
+}

package/src/bus/InProcessBus.ts

@@ -0,0 +1,28 @@
+import type { InvalidationBus, InvalidationHandler } from './InvalidationBus';
+import type { InvalidationEvent } from '../graph/types';
+
+/** Single-process bus. Correct for one node; phase 2 adds the distributed ones. */
+export class InProcessBus implements InvalidationBus {
+    private readonly handlers = new Set<InvalidationHandler>();
+
+    publish(events: InvalidationEvent[]): void {
+        if (events.length === 0) {
+            return;
+        }
+
+        for (const handler of this.handlers) {
+            try {
+                handler(events);
+            } catch (error) {
+                // One broken subscriber must not swallow invalidations for the
+                // others: a dropped invalidation is a screen frozen on stale data.
+                console.error('[carno:live] invalidation handler failed', error);
+            }
+        }
+    }
+
+    subscribe(handler: InvalidationHandler): () => void {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+}

package/src/bus/InvalidationBus.ts

@@ -0,0 +1,17 @@
+import type { InvalidationEvent } from '../graph/types';
+
+export type InvalidationHandler = (events: InvalidationEvent[]) => void;
+
+/**
+ * Carries invalidations from an emitter to the nodes holding subscriptions.
+ *
+ * The graph does not care where an invalidation came from, which is why the
+ * ORM emitter, the Postgres emitter and manual invalidation are three
+ * implementations feeding one interface. Phase 1 ships the in-process one;
+ * Redis and pg_notify buses arrive in phase 2 without touching the graph.
+ */
+export interface InvalidationBus {
+    publish(events: InvalidationEvent[]): void;
+    /** Returns an unsubscribe function. */
+    subscribe(handler: InvalidationHandler): () => void;
+}

package/src/bus/PgNotifyBus.ts

@@ -0,0 +1,188 @@
+import { tableKey, tableOfKey } from '../graph/dep-key';
+import type { InvalidationEvent } from '../graph/types';
+import { PgListener } from '../emitters/pg-listener';
+import type { InvalidationBus, InvalidationHandler } from './InvalidationBus';
+
+export const DEFAULT_PG_BUS_CHANNEL = 'carno_live_bus';
+export const DEFAULT_PG_BUS_MAX_PAYLOAD_BYTES = 7000;
+
+export interface PgNotifyBusOptions {
+    /** May be empty at construction; `setUrl` fills it before `start()`. */
+    url: string;
+    channel?: string;
+    /** Identifies this process so its own echo can be dropped. */
+    nodeId?: string;
+    maxPayloadBytes?: number;
+    heartbeatMs?: number;
+    retryMs?: number;
+    /** Injected in tests. */
+    listener?: PgListener;
+}
+
+interface WireFrame {
+    n: string;
+    e: InvalidationEvent[];
+}
+
+/**
+ * Split events into `pg_notify` frames under the payload ceiling.
+ *
+ * A single event that does not fit on its own degrades to its table key: a
+ * coarse invalidation costs CPU, a dropped one costs a screen frozen on stale
+ * data.
+ */
+export function chunkEvents(
+    events: InvalidationEvent[],
+    nodeId: string,
+    maxPayloadBytes: number
+): string[] {
+    const encode = (items: InvalidationEvent[]): string => JSON.stringify({ n: nodeId, e: items });
+    const frames: string[] = [];
+    let batch: InvalidationEvent[] = [];
+
+    for (const event of events) {
+        let item = event;
+
+        if (Buffer.byteLength(encode([item]), 'utf8') > maxPayloadBytes) {
+            const table = tableOfKey(item.key);
+            item = { key: table ? tableKey(table) : item.key, columns: null };
+        }
+
+        if (batch.length > 0 && Buffer.byteLength(encode([...batch, item]), 'utf8') > maxPayloadBytes) {
+            frames.push(encode(batch));
+            batch = [item];
+            continue;
+        }
+
+        batch.push(item);
+    }
+
+    if (batch.length > 0) {
+        frames.push(encode(batch));
+    }
+
+    return frames;
+}
+
+/**
+ * Invalidation bus across nodes, over `LISTEN/NOTIFY`.
+ *
+ * Two entry points, on purpose. `publish` is for a source local to this node —
+ * the ORM emitter, `LiveService.invalidate()` — and has to reach the others.
+ * `publishLocal` is for a source that already reached every node, which is what
+ * a Postgres trigger is; re-publishing that would multiply one write by the
+ * size of the cluster.
+ */
+export class PgNotifyBus implements InvalidationBus {
+    readonly nodeId: string;
+
+    private readonly handlers = new Set<InvalidationHandler>();
+    private readonly channel: string;
+    private readonly maxPayloadBytes: number;
+    private listener: PgListener | null;
+    private url: string;
+
+    constructor(private readonly options: PgNotifyBusOptions) {
+        this.nodeId = options.nodeId ?? crypto.randomUUID();
+        this.channel = options.channel ?? DEFAULT_PG_BUS_CHANNEL;
+        this.maxPayloadBytes = options.maxPayloadBytes ?? DEFAULT_PG_BUS_MAX_PAYLOAD_BYTES;
+        this.listener = options.listener ?? null;
+        this.url = options.url;
+    }
+
+    /** Called by the plugin once the ORM knows where the database is. */
+    setUrl(url: string): void {
+        this.url = url;
+    }
+
+    async start(): Promise<void> {
+        if (!this.listener) {
+            this.listener = new PgListener({
+                url: this.url,
+                heartbeatMs: this.options.heartbeatMs,
+                retryMs: this.options.retryMs
+            });
+        }
+
+        await this.listener.listen(this.channel, raw => this.onFrame(raw));
+    }
+
+    async stop(): Promise<void> {
+        await this.listener?.close();
+    }
+
+    publish(events: InvalidationEvent[]): void {
+        if (events.length === 0) {
+            return;
+        }
+
+        this.deliver(events);
+        void this.broadcast(events);
+    }
+
+    /** Deliver here only: the source already reached every node. */
+    publishLocal(events: InvalidationEvent[]): void {
+        if (events.length === 0) {
+            return;
+        }
+
+        this.deliver(events);
+    }
+
+    subscribe(handler: InvalidationHandler): () => void {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+
+    // ------------------------------------------------------------ internals
+
+    private async broadcast(events: InvalidationEvent[]): Promise<void> {
+        const listener = this.listener;
+
+        if (!listener) {
+            console.error('[carno:live] the distributed bus is not started; invalidation stayed local');
+            return;
+        }
+
+        for (const frame of chunkEvents(events, this.nodeId, this.maxPayloadBytes)) {
+            try {
+                await listener.notify(this.channel, frame);
+            } catch (error) {
+                // The other nodes will miss this one. Loud, because the symptom
+                // over there is a screen that simply stops updating.
+                console.error('[carno:live] failed to broadcast an invalidation', error);
+            }
+        }
+    }
+
+    private onFrame(raw: string): void {
+        let frame: WireFrame;
+
+        try {
+            frame = JSON.parse(raw) as WireFrame;
+        } catch {
+            return;
+        }
+
+        if (!frame || typeof frame.n !== 'string' || !Array.isArray(frame.e)) {
+            return;
+        }
+
+        if (frame.n === this.nodeId) {
+            // Our own echo. These were delivered locally before being sent.
+            return;
+        }
+
+        this.deliver(frame.e);
+    }
+
+    private deliver(events: InvalidationEvent[]): void {
+        for (const handler of this.handlers) {
+            try {
+                handler(events);
+            } catch (error) {
+                console.error('[carno:live] invalidation handler failed', error);
+            }
+        }
+    }
+}