@carno.js/live 1.8.0

package/src/client/vanilla.ts

@@ -0,0 +1,165 @@
+import { canonical } from '../shared/canonical';
+import {
+    normalizeLiveInputs,
+    resourceIdOf,
+    type LiveDataOf,
+    type LiveDescriptor,
+    type LiveInputsOf
+} from '../shared/descriptor';
+import type { LiveInputs } from '../shared/inputs';
+import type { LiveClient, LiveState, LiveStore } from './core';
+
+/** A subscription held by something that is not a component. */
+export interface LiveHandle<T> {
+    /** Current state. Valid before, during and after a subscription. */
+    get(): LiveState<T>;
+    /**
+     * Start receiving. The listener fires on every change, never on
+     * registration -- read `get()` for the initial value.
+     *
+     * Returns the same function `close()` calls.
+     */
+    subscribe(listener: (state: LiveState<T>) => void): () => void;
+    /** Release this handle's hold. Other handles on the same data keep theirs. */
+    close(): void;
+}
+
+/**
+ * Resolve a descriptor or a resource id to the underlying store.
+ *
+ * Framework adapters go through here rather than through `liveStore()`: they
+ * already own their own teardown, and wrapping a second lifecycle around the
+ * one the framework gives them is how an adapter starts leaking.
+ */
+export function liveStoreOf(
+    client: LiveClient,
+    resource: string | LiveDescriptor<any>,
+    inputs: Record<string, any> = {}
+): LiveStore<unknown> {
+    const resourceId = typeof resource === 'string' ? resource : resourceIdOf(resource);
+
+    return client.store(resourceId, normalizeLiveInputs(inputs as Partial<LiveInputs>));
+}
+
+/**
+ * Canonical identity of a subscription, for adapters that need to know whether
+ * reactive inputs actually changed before tearing a subscription down.
+ */
+export function liveIdentity(
+    resource: string | LiveDescriptor<any>,
+    inputs: Record<string, any> = {}
+): string {
+    const resourceId = typeof resource === 'string' ? resource : resourceIdOf(resource);
+    const normalized = normalizeLiveInputs(inputs as Partial<LiveInputs>);
+
+    return `${resourceId}|${canonical({
+        params: normalized.params,
+        query: normalized.query,
+        body: normalized.body ?? null
+    })}`;
+}
+
+export function liveStore<R>(
+    client: LiveClient,
+    descriptor: LiveDescriptor<R>,
+    inputs?: LiveInputsOf<R>
+): LiveHandle<LiveDataOf<R>>;
+export function liveStore<T>(
+    client: LiveClient,
+    resourceId: string,
+    inputs?: Partial<LiveInputs>
+): LiveHandle<T>;
+
+/**
+ * Subscribe without a framework.
+ *
+ * This is the whole vanilla adapter, and it is small on purpose: everything
+ * hard -- dedupe, revisions, resync, reconnect, the optimistic stack -- is in
+ * the client, and an adapter that grows is logic leaking out of it.
+ */
+export function liveStore(
+    client: LiveClient,
+    resource: string | LiveDescriptor<any>,
+    // Loose on purpose, and invisible to callers: a descriptor's own `query`
+    // type is a plain object, which no index signature accepts. The overloads
+    // above are what anyone actually sees.
+    inputs: Record<string, any> = {}
+): LiveHandle<any> {
+    const store = liveStoreOf(client, resource, inputs);
+    const drops = new Set<() => void>();
+
+    return {
+        get: () => store.getSnapshot(),
+        subscribe(listener: (state: LiveState<any>) => void): () => void {
+            const drop = store.subscribe(() => listener(store.getSnapshot()));
+            drops.add(drop);
+
+            // Idempotent: calling this and then close() must not release the
+            // client's refcount twice, or an unrelated handle loses its data.
+            return () => {
+                if (drops.delete(drop)) {
+                    drop();
+                }
+            };
+        },
+        close(): void {
+            for (const drop of [...drops]) {
+                drops.delete(drop);
+                drop();
+            }
+        }
+    };
+}
+
+const EMPTY_STATE: LiveState<any> = { data: undefined, pending: true, error: null, stale: false };
+
+/**
+ * A subscription that points at one target at a time.
+ *
+ * Reactive frameworks re-run an expression when its inputs change, and for a
+ * live subscription that means "this component now wants a different instance".
+ * The rule that makes that safe has nothing to do with any framework, so it
+ * lives here: recomputing to the same inputs must not churn the subscription,
+ * and switching targets must release the old one *before* retaining the new
+ * one. Holding both across the switch is how a dragged filter walks a
+ * connection into `maxInstancesPerConnection`.
+ */
+export class LiveSlot<T> {
+    private identity: string | null = null;
+    private release: (() => void) | null = null;
+    private store: LiveStore<unknown> | null = null;
+
+    constructor(
+        private readonly client: LiveClient,
+        private readonly onState: (state: LiveState<T>) => void
+    ) {}
+
+    point(resource: string | LiveDescriptor<any>, inputs: Record<string, any> = {}): void {
+        const next = liveIdentity(resource, inputs);
+
+        if (next === this.identity) {
+            return;
+        }
+
+        this.release?.();
+        this.release = null;
+
+        this.identity = next;
+        this.store = liveStoreOf(this.client, resource, inputs);
+
+        const store = this.store;
+        this.release = store.subscribe(() => this.onState(store.getSnapshot() as LiveState<T>));
+        this.onState(store.getSnapshot() as LiveState<T>);
+    }
+
+    get(): LiveState<T> {
+        return (this.store?.getSnapshot() as LiveState<T> | undefined) ?? EMPTY_STATE;
+    }
+
+    close(): void {
+        this.release?.();
+        this.release = null;
+        this.store = null;
+        this.identity = null;
+    }
+}

package/src/client/vue.ts

@@ -0,0 +1,67 @@
+import {
+    computed,
+    getCurrentInstance,
+    inject,
+    onScopeDispose,
+    provide,
+    shallowRef,
+    watchEffect,
+    type InjectionKey,
+    type ShallowRef
+} from 'vue';
+import type { LiveDataOf, LiveDescriptor, LiveInputsOf } from '../shared/descriptor';
+import type { LiveClient, LiveState } from './core';
+import { LiveSlot } from './vanilla';
+
+export const LIVE_CLIENT_KEY: InjectionKey<LiveClient> = Symbol('carno.live.client');
+
+/** Call once, high in the tree. Every useLiveQuery() below it finds the client. */
+export function provideLiveClient(client: LiveClient): void {
+    provide(LIVE_CLIENT_KEY, client);
+}
+
+const PENDING: LiveState<any> = { data: undefined, pending: true, error: null, stale: false };
+
+export function useLiveQuery<R>(
+    descriptor: LiveDescriptor<R>,
+    inputs?: () => LiveInputsOf<R>,
+    options?: { client?: LiveClient }
+): ShallowRef<LiveState<LiveDataOf<R>>>;
+export function useLiveQuery<T>(
+    resourceId: string,
+    inputs?: () => Record<string, any>,
+    options?: { client?: LiveClient }
+): ShallowRef<LiveState<T>>;
+
+/**
+ * Subscribe a component to server-owned state, as a shallow ref.
+ *
+ * Shallow because the server replaces the whole snapshot and nothing ever
+ * writes into it: a deep proxy would pay to track mutations that cannot
+ * happen. `inputs` is read inside a watchEffect, so a ref it touches
+ * re-points the subscription; the effect scope tears it down.
+ */
+export function useLiveQuery(
+    resource: string | LiveDescriptor<any>,
+    inputs: () => Record<string, any> = () => ({}),
+    options: { client?: LiveClient } = {}
+): ShallowRef<LiveState<any>> {
+    const client = options.client
+        ?? (getCurrentInstance() ? inject(LIVE_CLIENT_KEY, undefined) : undefined);
+
+    if (!client) {
+        throw new Error(
+            'useLiveQuery() found no LiveClient. Call provideLiveClient(client) in an ancestor ' +
+            'component, or pass { client } explicitly.'
+        );
+    }
+
+    const state = shallowRef<LiveState<any>>(PENDING);
+    const slot = new LiveSlot<any>(client, next => { state.value = next; });
+    const target = computed(() => inputs());
+
+    watchEffect(() => slot.point(resource, target.value));
+    onScopeDispose(() => slot.close());
+
+    return state;
+}

package/src/config.ts

@@ -0,0 +1,49 @@
+/**
+ * Tunables from §10.1 of the design. These are starting points to calibrate
+ * against the recompute-without-patch metric, not measured values.
+ */
+export interface LiveConfig {
+    /** Window in ms over which invalidations for one instance are grouped. */
+    coalesceMs: number;
+    /** Above this many row keys, one read collapses to its table key. */
+    maxKeysPerRead: number;
+    /** Ceiling on the canonicalized inputs of a single subscription. */
+    maxInputBytes: number;
+    /** Grace period before dropping an instance whose refcount hit zero. */
+    unsubGraceMs: number;
+    /** Consecutive back-pressured sends before collapsing to a snapshot. */
+    maxPendingPatches: number;
+    /** Above this fan-out, recompute is queued instead of run inline. */
+    fanoutQueueThreshold: number;
+    /** Ceiling on live instances held by a single connection. */
+    maxInstancesPerConnection: number;
+    /** Ceiling on live instances held by this process. */
+    maxInstancesPerNode: number;
+    /** Path of the SSE downstream, when the SSE transport is on. */
+    ssePath: string;
+    /** Path client messages are posted to, when the SSE transport is on. */
+    sseControlPath: string;
+    /** Comment frame interval that keeps idle-timeout proxies from reaping. */
+    sseHeartbeatMs: number;
+    /** Ceiling on concurrent SSE streams held by this process. */
+    sseMaxConnections: number;
+}
+
+export const DEFAULT_LIVE_CONFIG: LiveConfig = {
+    coalesceMs: 16,
+    maxKeysPerRead: 64,
+    maxInputBytes: 8192,
+    unsubGraceMs: 5000,
+    maxPendingPatches: 32,
+    fanoutQueueThreshold: 500,
+    maxInstancesPerConnection: 64,
+    maxInstancesPerNode: 50000,
+    ssePath: '/live/sse',
+    sseControlPath: '/live/control',
+    sseHeartbeatMs: 15000,
+    sseMaxConnections: 10000
+};
+
+export function resolveLiveConfig(overrides: Partial<LiveConfig> = {}): LiveConfig {
+    return { ...DEFAULT_LIVE_CONFIG, ...overrides };
+}

package/src/decorators/Live.ts

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+import { LIVE_META, type LiveMeta, type LiveOptions } from '../metadata';
+
+/** Marks an existing route as subscribable while keeping it a normal HTTP route. */
+export function Live(options: LiveOptions = {}): MethodDecorator {
+    return function (target: any, propertyKey: string | symbol): void {
+        const meta: LiveMeta = {
+            key: options.key,
+            shared: options.shared ?? 'private',
+            dependsOn: options.dependsOn ?? [],
+            handlerName: String(propertyKey)
+        };
+
+        Reflect.defineMetadata(LIVE_META, meta, target.constructor, String(propertyKey));
+    };
+}

package/src/emitters/AppEmitter.ts

@@ -0,0 +1,69 @@
+import { statementObserver, type Statement } from '@carno.js/orm';
+import type { InvalidationBus } from '../bus/InvalidationBus';
+import type { LiveConfig } from '../config';
+import { tableOfKey } from '../graph/dep-key';
+import { dependencyContext } from '../resource/dependency-context';
+import { readDependencies, writeEvents } from './statement-keys';
+
+export class WriteDuringComputeError extends Error {
+    constructor(table: string | undefined, operation: string | undefined) {
+        super(
+            `A live resource compute attempted a ${operation ?? 'write'} on "${table ?? 'unknown'}". ` +
+            `A resource reads; an action writes. Re-running the handler on every change would ` +
+            `duplicate the side effect, so the write is refused.`
+        );
+        this.name = 'WriteDuringComputeError';
+    }
+}
+
+/**
+ * First of the three invalidation sources in §4.4: writes issued through
+ * @carno.js/orm. Costs no infrastructure, and covers everything the
+ * application itself writes.
+ */
+export class AppEmitter {
+    /** Tables announced by another emitter, so we do not announce them twice. */
+    private covered = new Set<string>();
+
+    constructor(
+        private readonly bus: InvalidationBus,
+        private readonly config: LiveConfig
+    ) {}
+
+    setCoveredTables(tables: Iterable<string>): void {
+        this.covered = new Set(tables);
+    }
+
+    attach(): void {
+        statementObserver.onRead((statement: Statement<any>) => {
+            const collector = dependencyContext.current();
+
+            if (!collector) {
+                // A read outside any compute: an ordinary request. Nothing to record.
+                return;
+            }
+
+            collector.addAll(readDependencies(statement, this.config.maxKeysPerRead));
+        });
+
+        statementObserver.onWriteAttempt((statement: Statement<any>) => {
+            if (dependencyContext.isActive()) {
+                throw new WriteDuringComputeError(statement.table, statement.statement);
+            }
+        });
+
+        statementObserver.onWrite((statement: Statement<any>) => {
+            const events = writeEvents(statement, this.config.maxKeysPerRead);
+            // A table watched by the Postgres emitter already announces itself
+            // through the trigger, on every node at once. Publishing here too
+            // would only buy a duplicate recompute.
+            const ours = events.filter(event => !this.covered.has(tableOfKey(event.key) ?? ''));
+
+            this.bus.publish(ours);
+        });
+    }
+
+    detach(): void {
+        statementObserver.reset();
+    }
+}

package/src/emitters/pg-listener.ts

@@ -0,0 +1,171 @@
+import { SQL } from 'bun';
+
+/**
+ * The slice of Bun's Postgres client this module needs.
+ *
+ * Bun 1.4 implements `listen` and `notify` at runtime, but `@types/bun` does
+ * not declare them and the published docs still list them as unimplemented.
+ * Declaring the slice here keeps the cast in one place, and makes the whole
+ * thing injectable so the unit tests need no database.
+ */
+export interface ListenableSql {
+    listen(channel: string, onNotify: (payload: string) => void): Promise<unknown>;
+    notify(channel: string, payload?: string): Promise<unknown>;
+    unsafe(query: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+
+export interface PgListenerOptions {
+    url: string;
+    /** Liveness check interval. Zero disables the timer; `check()` still works. */
+    heartbeatMs?: number;
+    /** Delay between reconnection attempts. */
+    retryMs?: number;
+    /** Injected in tests. Defaults to a dedicated single Bun connection. */
+    sqlFactory?: (url: string) => ListenableSql;
+    /**
+     * Fired after the connection came back and every channel was re-listened.
+     *
+     * Whatever was published while the socket was down is gone with no trace,
+     * so the caller has to assume the worst — see PgNotifyEmitter.
+     */
+    onReconnect?: () => void;
+}
+
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_RETRY_MS = 1000;
+
+function defaultSqlFactory(url: string): ListenableSql {
+    // A LISTEN connection cannot be shared with the query pool: it sits open
+    // waiting for asynchronous notifications, so it gets its own socket.
+    return new SQL({ url, max: 1 }) as unknown as ListenableSql;
+}
+
+const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/** One dedicated Postgres connection held open for LISTEN, with reconnection. */
+export class PgListener {
+    private sql: ListenableSql | null = null;
+    private readonly channels = new Map<string, (payload: string) => void>();
+    private timer: ReturnType<typeof setInterval> | null = null;
+    private opening: Promise<void> | null = null;
+    private closed = false;
+
+    constructor(private readonly options: PgListenerOptions) {}
+
+    async listen(channel: string, onNotify: (payload: string) => void): Promise<void> {
+        const known = this.channels.has(channel);
+        this.channels.set(channel, onNotify);
+
+        if (!this.sql) {
+            // `open()` subscribes every registered channel, this one included.
+            await this.connect();
+            return;
+        }
+
+        if (!known) {
+            await this.sql.listen(channel, onNotify);
+        }
+    }
+
+    async notify(channel: string, payload: string): Promise<void> {
+        await this.connect();
+        await this.sql?.notify(channel, payload);
+    }
+
+    /** One liveness probe. Called by the heartbeat and directly by tests. */
+    async check(): Promise<void> {
+        if (this.closed || !this.sql) {
+            return;
+        }
+
+        try {
+            await this.sql.unsafe('SELECT 1');
+        } catch {
+            await this.reconnect();
+        }
+    }
+
+    async close(): Promise<void> {
+        this.closed = true;
+
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+
+        const sql = this.sql;
+        this.sql = null;
+
+        try {
+            await sql?.close();
+        } catch {
+            // Already gone. Nothing to do and nothing to report.
+        }
+    }
+
+    // ------------------------------------------------------------ internals
+
+    private factory(): (url: string) => ListenableSql {
+        return this.options.sqlFactory ?? defaultSqlFactory;
+    }
+
+    private async connect(): Promise<void> {
+        if (this.sql || this.closed) {
+            return;
+        }
+
+        if (!this.opening) {
+            this.opening = this.open().finally(() => {
+                this.opening = null;
+            });
+        }
+
+        await this.opening;
+    }
+
+    private async open(): Promise<void> {
+        const sql = this.factory()(this.options.url);
+
+        for (const [channel, handler] of this.channels) {
+            await sql.listen(channel, handler);
+        }
+
+        this.sql = sql;
+        this.startHeartbeat();
+    }
+
+    private startHeartbeat(): void {
+        const interval = this.options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+
+        if (this.timer || interval <= 0) {
+            return;
+        }
+
+        this.timer = setInterval(() => {
+            void this.check();
+        }, interval);
+    }
+
+    private async reconnect(): Promise<void> {
+        const previous = this.sql;
+        this.sql = null;
+
+        try {
+            await previous?.close();
+        } catch {
+            // The socket is what just failed; closing it is best effort.
+        }
+
+        while (!this.closed) {
+            try {
+                await this.open();
+                this.options.onReconnect?.();
+                return;
+            } catch {
+                this.sql = null;
+                await delay(this.options.retryMs ?? DEFAULT_RETRY_MS);
+            }
+        }
+    }
+}

package/src/emitters/pg-notify-emitter.ts

@@ -0,0 +1,143 @@
+import { rowKey, tableKey } from '../graph/dep-key';
+import type { InvalidationEvent } from '../graph/types';
+import { PgListener } from './pg-listener';
+import { createFunctionSql, createTriggerSql, dropTriggerSql } from './pg-trigger-sql';
+
+export interface PgNotifyTable {
+    /** Table name as it exists in the database, unqualified. */
+    table: string;
+    /** Primary key column, as it exists in the database. */
+    primaryKey: string;
+}
+
+export interface PgNotifyEmitterOptions {
+    tables: PgNotifyTable[];
+    /** Connection string. Defaults to the ORM's own. */
+    url: string;
+    /** Runs the DDL. Defaults to the ORM driver's `executeSql`. */
+    execute: (sql: string) => Promise<unknown>;
+    channel?: string;
+    maxPayloadBytes?: number;
+    heartbeatMs?: number;
+    retryMs?: number;
+    /** Injected in tests. */
+    listener?: PgListener;
+}
+
+export const DEFAULT_PG_CHANNEL = 'carno_live';
+export const DEFAULT_PG_MAX_PAYLOAD_BYTES = 7000;
+
+/**
+ * Turn one trigger payload into invalidation events.
+ *
+ * Exported on its own because it is the whole translation layer between
+ * Postgres and the graph, and it is worth testing without a database.
+ */
+export function eventsFromPayload(raw: string): InvalidationEvent[] {
+    let parsed: { t?: unknown; i?: unknown; c?: unknown };
+
+    try {
+        parsed = JSON.parse(raw) as { t?: unknown; i?: unknown; c?: unknown };
+    } catch {
+        // Someone else is using our channel. Not our problem, and not a crash.
+        return [];
+    }
+
+    if (!parsed || typeof parsed.t !== 'string' || parsed.t === '') {
+        return [];
+    }
+
+    const table = parsed.t;
+    const columns = Array.isArray(parsed.c)
+        ? (parsed.c.filter(item => typeof item === 'string') as string[])
+        : [];
+    const id = typeof parsed.i === 'string' || typeof parsed.i === 'number' ? parsed.i : null;
+
+    return [{
+        key: id === null ? tableKey(table) : rowKey(table, id),
+        // An empty list is "we do not know which columns", not "no columns".
+        columns: columns.length > 0 ? columns : null
+    }];
+}
+
+/**
+ * The second emitter of §4.4: writes that never went through @carno.js/orm.
+ *
+ * A trigger per watched table produces table + primary key + changed columns,
+ * which is the same key vocabulary the application emitter produces. The graph
+ * cannot tell them apart, and does not need to.
+ */
+export class PgNotifyEmitter {
+    private readonly listener: PgListener;
+    private readonly channel: string;
+    private attached = false;
+
+    constructor(
+        private readonly deliver: (events: InvalidationEvent[]) => void,
+        private readonly options: PgNotifyEmitterOptions
+    ) {
+        this.channel = options.channel ?? DEFAULT_PG_CHANNEL;
+        this.listener = options.listener ?? new PgListener({
+            url: options.url,
+            heartbeatMs: options.heartbeatMs,
+            retryMs: options.retryMs,
+            onReconnect: () => this.onReconnect()
+        });
+    }
+
+    /** Tables this emitter announces, so the ORM emitter can skip them. */
+    coveredTables(): Set<string> {
+        return new Set(this.options.tables.map(entry => entry.table));
+    }
+
+    /** Install the trigger function and one trigger per watched table. */
+    async install(): Promise<void> {
+        await this.options.execute(
+            createFunctionSql(this.options.maxPayloadBytes ?? DEFAULT_PG_MAX_PAYLOAD_BYTES)
+        );
+
+        for (const entry of this.options.tables) {
+            await this.options.execute(createTriggerSql(entry.table, entry.primaryKey, this.channel));
+        }
+    }
+
+    async attach(): Promise<void> {
+        if (this.attached) {
+            return;
+        }
+
+        this.attached = true;
+        await this.install();
+        await this.listener.listen(this.channel, payload => {
+            const events = eventsFromPayload(payload);
+
+            if (events.length > 0) {
+                this.deliver(events);
+            }
+        });
+    }
+
+    async detach(): Promise<void> {
+        this.attached = false;
+        await this.listener.close();
+    }
+
+    /** Remove the triggers. The function is left in place; it is harmless. */
+    async uninstall(): Promise<void> {
+        for (const entry of this.options.tables) {
+            await this.options.execute(dropTriggerSql(entry.table));
+        }
+    }
+
+    /**
+     * Whatever was written while the socket was down arrived nowhere, and there
+     * is no way to ask Postgres what we missed. The only correct move is to
+     * assume everything watched is stale.
+     */
+    private onReconnect(): void {
+        this.deliver(this.options.tables.map(entry => ({
+            key: tableKey(entry.table),
+            columns: null
+        })));
+    }
+}