@carno.js/live 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carno.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/LiveEngine.d.ts

@@ -0,0 +1,89 @@
+import { type LiveAuthorizer } from './auth/authorizer';
+import type { InvalidationBus } from './bus/InvalidationBus';
+import type { LiveConfig } from './config';
+import { DependencyGraph } from './graph/DependencyGraph';
+import { SubscriptionRegistry } from './graph/SubscriptionRegistry';
+import type { ServerMessage } from './shared/protocol';
+import type { ResourceRegistry } from './resource/ResourceRegistry';
+import type { LiveInputs, LiveScope } from './resource/types';
+import { LiveMetrics } from './observability';
+export interface LiveTransport {
+    /**
+     * Send one message. The return value is the underlying socket's: Bun's
+     * `ServerWebSocket.send()` answers -1 under back-pressure and 0 when the
+     * message was dropped. Anything <= 0 counts as back-pressure here.
+     */
+    send(connectionId: string, message: ServerMessage): number;
+}
+export interface LiveStats {
+    instances: number;
+    recomputes: number;
+    /**
+     * Recomputes that produced no patch. The most important number in the
+     * system: it measures the precision of the invalidation granularity
+     * directly. Climbing means the graph is waking instances for nothing.
+     */
+    recomputesWithoutPatch: number;
+}
+export declare class LiveEngine {
+    private readonly resources;
+    private readonly graph;
+    private readonly subs;
+    private readonly bus;
+    private readonly transport;
+    private readonly config;
+    private readonly authorizer;
+    private readonly metrics;
+    private readonly instances;
+    /** One promise per instance under construction; also reserves node capacity. */
+    private readonly creating;
+    /** connectionId → sid → instanceId. Addressing only; refcount lives in the registry. */
+    private readonly bindings;
+    private readonly backpressure;
+    private readonly pending;
+    /** Scope of each connection, as resolved at subscribe time. */
+    private readonly scopes;
+    /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
+    private readonly authorized;
+    private flushTimer;
+    private unsubscribeBus;
+    private recomputes;
+    private recomputesWithoutPatch;
+    constructor(resources: ResourceRegistry, graph: DependencyGraph, subs: SubscriptionRegistry, bus: InvalidationBus, transport: LiveTransport, config: LiveConfig, authorizer?: LiveAuthorizer, metrics?: LiveMetrics);
+    start(): void;
+    stop(): void;
+    subscribe(connectionId: string, sid: string, resourceId: string, inputs: LiveInputs, scope: LiveScope, clientHash?: string): Promise<void>;
+    unsubscribe(connectionId: string, sid: string): void;
+    resync(connectionId: string, sid: string, clientHash?: string): Promise<void>;
+    dropConnection(connectionId: string): void;
+    /** Manual invalidation — the third emitter of §4.4. */
+    invalidate(key: string): void;
+    stats(): LiveStats;
+    /**
+     * Polling has no server-side subscription to cache an authorization
+     * decision against, so it must ask the live authorizer on every request.
+     */
+    authorizePolling(connectionId: string, resourceId: string, inputs: LiveInputs, scope: LiveScope): Promise<boolean>;
+    private bind;
+    private release;
+    private checkAuthorization;
+    /** An `auth:` key fired: drop the cached decisions it covers and re-ask. */
+    private reauthorize;
+    /** End one connection's hold on one instance, telling it why. */
+    private revoke;
+    private scheduleDrop;
+    private startInstanceCreation;
+    private clearInstanceCreation;
+    private createInstance;
+    private sendState;
+    private onInvalidation;
+    private flush;
+    private recompute;
+    private runCompute;
+    private broadcast;
+    private revokeInstance;
+    private sidsFor;
+    private isBackedUp;
+    private send;
+    private fail;
+}

package/dist/LiveEngine.js

@@ -0,0 +1,520 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveEngine = void 0;
+const authorizer_1 = require("./auth/authorizer");
+const dep_key_1 = require("./graph/dep-key");
+const PatchEngine_1 = require("./patch/PatchEngine");
+const canonical_1 = require("./shared/canonical");
+const hash_1 = require("./shared/hash");
+const instance_id_1 = require("./resource/instance-id");
+const route_executor_1 = require("./resource/route-executor");
+const observability_1 = require("./observability");
+class LiveEngine {
+    constructor(resources, graph, subs, bus, transport, config, authorizer = new authorizer_1.AllowAllAuthorizer(), metrics = observability_1.LiveMetrics.none()) {
+        this.resources = resources;
+        this.graph = graph;
+        this.subs = subs;
+        this.bus = bus;
+        this.transport = transport;
+        this.config = config;
+        this.authorizer = authorizer;
+        this.metrics = metrics;
+        this.instances = new Map();
+        /** One promise per instance under construction; also reserves node capacity. */
+        this.creating = new Map();
+        /** connectionId → sid → instanceId. Addressing only; refcount lives in the registry. */
+        this.bindings = new Map();
+        this.backpressure = new Map();
+        this.pending = new Set();
+        /** Scope of each connection, as resolved at subscribe time. */
+        this.scopes = new Map();
+        /** connectionId → instanceId → decision. Cleared when an `auth:` key fires. */
+        this.authorized = new Map();
+        this.flushTimer = null;
+        this.unsubscribeBus = null;
+        this.recomputes = 0;
+        this.recomputesWithoutPatch = 0;
+    }
+    start() {
+        if (this.unsubscribeBus) {
+            return;
+        }
+        this.unsubscribeBus = this.bus.subscribe(events => this.onInvalidation(events));
+    }
+    stop() {
+        this.unsubscribeBus?.();
+        this.unsubscribeBus = null;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        for (const instance of this.instances.values()) {
+            if (instance.dropTimer) {
+                clearTimeout(instance.dropTimer);
+            }
+        }
+    }
+    async subscribe(connectionId, sid, resourceId, inputs, scope, clientHash) {
+        const resource = this.resources.get(resourceId);
+        if (!resource) {
+            this.fail(connectionId, sid, 'unknown_resource', `No live resource named "${resourceId}".`);
+            return;
+        }
+        let instanceId;
+        try {
+            const scopeKey = (0, instance_id_1.scopeKeyOf)(resource.meta.shared, scope);
+            instanceId = (0, instance_id_1.instanceIdOf)(resource.id, scopeKey, (0, instance_id_1.canonicalInputs)(inputs, this.config.maxInputBytes));
+        }
+        catch (error) {
+            this.fail(connectionId, sid, 'invalid_subscription', error.message);
+            return;
+        }
+        this.scopes.set(connectionId, scope);
+        const allowed = await this.checkAuthorization(connectionId, instanceId, resource, inputs, scope);
+        if (!allowed) {
+            this.fail(connectionId, sid, 'forbidden', `This connection is not allowed to subscribe to "${resourceId}".`);
+            return;
+        }
+        const known = this.instances.has(instanceId);
+        const creating = this.creating.has(instanceId);
+        const heldByConnection = this.subs.countForConnection(connectionId);
+        if (!this.bindings.get(connectionId)?.has(sid) && heldByConnection >= this.config.maxInstancesPerConnection) {
+            this.fail(connectionId, sid, 'too_many_instances', `A connection may hold at most ${this.config.maxInstancesPerConnection} live instances.`);
+            return;
+        }
+        if (!known && !creating && this.instances.size + this.creating.size >= this.config.maxInstancesPerNode) {
+            this.fail(connectionId, sid, 'node_at_capacity', 'This node is at its live instance ceiling.');
+            return;
+        }
+        const previous = this.bindings.get(connectionId)?.get(sid);
+        if (previous !== instanceId) {
+            if (previous !== undefined) {
+                this.release(connectionId, sid);
+            }
+            this.bind(connectionId, sid, instanceId);
+            this.subs.subscribe(connectionId, instanceId);
+        }
+        let instance = this.instances.get(instanceId);
+        if (instance?.dropTimer) {
+            clearTimeout(instance.dropTimer);
+            instance.dropTimer = null;
+        }
+        if (!instance) {
+            const creation = this.creating.get(instanceId)
+                ?? this.startInstanceCreation(instanceId, resource, inputs, scope);
+            try {
+                instance = await creation;
+            }
+            catch (error) {
+                this.release(connectionId, sid);
+                const code = error instanceof route_executor_1.LiveRouteExecutionError
+                    ? error.statusCode === 401 || error.statusCode === 403
+                        ? 'forbidden'
+                        : error.statusCode >= 400 && error.statusCode < 500
+                            ? 'invalid_subscription'
+                            : 'compute_failed'
+                    : 'compute_failed';
+                this.fail(connectionId, sid, code, error.message);
+                return;
+            }
+        }
+        if (this.bindings.get(connectionId)?.get(sid) !== instanceId) {
+            this.scheduleDrop(instanceId);
+            return;
+        }
+        this.sendState(connectionId, sid, instance, clientHash);
+    }
+    unsubscribe(connectionId, sid) {
+        this.release(connectionId, sid);
+    }
+    async resync(connectionId, sid, clientHash) {
+        const instanceId = this.bindings.get(connectionId)?.get(sid);
+        const instance = instanceId ? this.instances.get(instanceId) : undefined;
+        if (!instance) {
+            this.fail(connectionId, sid, 'unknown_subscription', 'Resync for a subscription this node does not hold.');
+            return;
+        }
+        this.sendState(connectionId, sid, instance, clientHash);
+    }
+    dropConnection(connectionId) {
+        const owned = this.bindings.get(connectionId);
+        if (owned) {
+            for (const sid of [...owned.keys()]) {
+                this.release(connectionId, sid);
+            }
+        }
+        this.bindings.delete(connectionId);
+        this.backpressure.delete(connectionId);
+        this.scopes.delete(connectionId);
+        this.authorized.delete(connectionId);
+    }
+    /** Manual invalidation — the third emitter of §4.4. */
+    invalidate(key) {
+        this.bus.publish([{ key, columns: null }]);
+    }
+    stats() {
+        return {
+            instances: this.instances.size,
+            recomputes: this.recomputes,
+            recomputesWithoutPatch: this.recomputesWithoutPatch
+        };
+    }
+    /**
+     * Polling has no server-side subscription to cache an authorization
+     * decision against, so it must ask the live authorizer on every request.
+     */
+    async authorizePolling(connectionId, resourceId, inputs, scope) {
+        const resource = this.resources.get(resourceId);
+        if (!resource) {
+            return false;
+        }
+        try {
+            (0, instance_id_1.scopeKeyOf)(resource.meta.shared, scope);
+        }
+        catch {
+            return false;
+        }
+        try {
+            return await this.authorizer.authorize({
+                resourceId: resource.id,
+                controllerName: resource.controllerName,
+                handlerName: resource.handlerName,
+                meta: resource.meta,
+                inputs,
+                scope,
+                connectionId
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    // ------------------------------------------------------------ internals
+    bind(connectionId, sid, instanceId) {
+        let owned = this.bindings.get(connectionId);
+        if (!owned) {
+            owned = new Map();
+            this.bindings.set(connectionId, owned);
+        }
+        owned.set(sid, instanceId);
+    }
+    release(connectionId, sid) {
+        const owned = this.bindings.get(connectionId);
+        const instanceId = owned?.get(sid);
+        if (!owned || !instanceId) {
+            return;
+        }
+        owned.delete(sid);
+        this.authorized.get(connectionId)?.delete(instanceId);
+        this.subs.unsubscribe(connectionId, instanceId);
+        this.scheduleDrop(instanceId);
+    }
+    async checkAuthorization(connectionId, instanceId, resource, inputs, scope) {
+        let perConnection = this.authorized.get(connectionId);
+        if (!perConnection) {
+            perConnection = new Map();
+            this.authorized.set(connectionId, perConnection);
+        }
+        const cached = perConnection.get(instanceId);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let allowed;
+        try {
+            allowed = await this.authorizer.authorize({
+                resourceId: resource.id,
+                controllerName: resource.controllerName,
+                handlerName: resource.handlerName,
+                meta: resource.meta,
+                inputs,
+                scope,
+                connectionId
+            });
+        }
+        catch {
+            // An authorizer that throws is a denial. Failing open here would
+            // hand out data on a bug in application code.
+            allowed = false;
+        }
+        perConnection.set(instanceId, allowed);
+        return allowed;
+    }
+    /** An `auth:` key fired: drop the cached decisions it covers and re-ask. */
+    reauthorize(key) {
+        for (const [connectionId, scope] of this.scopes) {
+            const affected = (0, authorizer_1.authKeysOf)(scope).some(owned => (0, dep_key_1.ancestorsOf)(owned).includes(key));
+            if (!affected) {
+                continue;
+            }
+            this.authorized.delete(connectionId);
+            const owned = this.bindings.get(connectionId);
+            if (!owned) {
+                continue;
+            }
+            for (const instanceId of new Set(owned.values())) {
+                const instance = this.instances.get(instanceId);
+                if (!instance) {
+                    continue;
+                }
+                void this.checkAuthorization(connectionId, instanceId, instance.resource, instance.inputs, scope)
+                    .then(allowed => {
+                    if (!allowed) {
+                        this.revoke(connectionId, instanceId);
+                    }
+                });
+            }
+        }
+    }
+    /** End one connection's hold on one instance, telling it why. */
+    revoke(connectionId, instanceId) {
+        for (const sid of this.sidsFor(connectionId, instanceId)) {
+            this.send(connectionId, {
+                t: 'error',
+                sid,
+                code: 'forbidden',
+                message: 'This subscription is no longer authorized for this connection.'
+            });
+            this.release(connectionId, sid);
+        }
+    }
+    scheduleDrop(instanceId) {
+        if (this.subs.hasSubscribers(instanceId)) {
+            return;
+        }
+        const instance = this.instances.get(instanceId);
+        if (!instance || instance.dropTimer) {
+            return;
+        }
+        // Grace period so coming back from a navigation does not recompute
+        // everything the page had a moment ago.
+        instance.dropTimer = setTimeout(() => {
+            if (!this.subs.hasSubscribers(instanceId)) {
+                this.instances.delete(instanceId);
+                this.graph.remove(instanceId);
+            }
+        }, this.config.unsubGraceMs);
+    }
+    startInstanceCreation(instanceId, resource, inputs, scope) {
+        let resolveCreation;
+        let rejectCreation;
+        const creation = new Promise((resolve, reject) => {
+            resolveCreation = resolve;
+            rejectCreation = reject;
+        });
+        this.creating.set(instanceId, creation);
+        void this.createInstance(instanceId, resource, inputs, scope).then(instance => {
+            this.clearInstanceCreation(instanceId, creation);
+            resolveCreation(instance);
+        }, error => {
+            this.clearInstanceCreation(instanceId, creation);
+            rejectCreation(error);
+        });
+        return creation;
+    }
+    clearInstanceCreation(instanceId, creation) {
+        if (this.creating.get(instanceId) === creation) {
+            this.creating.delete(instanceId);
+        }
+    }
+    async createInstance(instanceId, resource, inputs, scope) {
+        const { data, deps } = await this.resources.compute(resource, inputs, { scope });
+        this.recomputes++;
+        this.graph.setDependencies(instanceId, deps);
+        const instance = {
+            id: instanceId,
+            resource,
+            inputs,
+            scope,
+            patcher: new PatchEngine_1.PatchEngine(resource.meta.key),
+            data,
+            hash: (0, hash_1.fnv1a64)((0, canonical_1.canonical)(data)),
+            revision: 1,
+            computing: null,
+            dirty: false,
+            dropTimer: null
+        };
+        this.instances.set(instanceId, instance);
+        return instance;
+    }
+    sendState(connectionId, sid, instance, clientHash) {
+        if (clientHash && clientHash === instance.hash) {
+            // The screen already holds this exact content. Nothing on the wire.
+            this.send(connectionId, {
+                t: 'current',
+                sid,
+                rev: instance.revision,
+                hash: instance.hash,
+                key: instance.resource.meta.key
+            });
+            return;
+        }
+        this.send(connectionId, {
+            t: 'snapshot',
+            sid,
+            rev: instance.revision,
+            hash: instance.hash,
+            data: instance.data,
+            key: instance.resource.meta.key
+        });
+    }
+    onInvalidation(events) {
+        const before = this.pending.size;
+        for (const event of events) {
+            if ((0, authorizer_1.isAuthKey)(event.key)) {
+                // Not data: nothing to recompute, only permissions to re-check.
+                this.reauthorize(event.key);
+                continue;
+            }
+            for (const instanceId of this.graph.resolve(event)) {
+                // Grace-held instances have no subscribers but are still cached.
+                if (this.instances.has(instanceId)) {
+                    this.pending.add(instanceId);
+                }
+            }
+        }
+        // Newly pending, not total pending: an invalidation that woke nothing
+        // because the instances were already queued did not cost a fan-out.
+        this.metrics.invalidation(events.length, this.pending.size - before);
+        if (this.pending.size === 0 || this.flushTimer) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, this.config.coalesceMs);
+    }
+    async flush() {
+        const batch = [...this.pending];
+        this.pending.clear();
+        this.metrics.instances(this.instances.size);
+        for (let i = 0; i < batch.length; i += this.config.fanoutQueueThreshold) {
+            const slice = batch.slice(i, i + this.config.fanoutQueueThreshold);
+            await Promise.all(slice.map(instanceId => this.recompute(instanceId)));
+            if (i + this.config.fanoutQueueThreshold < batch.length) {
+                // Yield between slices so a large fan-out does not monopolize
+                // the loop and stall unrelated requests.
+                await new Promise(resolve => setTimeout(resolve, 0));
+            }
+        }
+    }
+    recompute(instanceId) {
+        const instance = this.instances.get(instanceId);
+        if (!instance) {
+            return Promise.resolve();
+        }
+        if (instance.computing) {
+            // Single-flight: N invalidations arriving during one recompute cost
+            // exactly one more recompute, not N.
+            instance.dirty = true;
+            return instance.computing;
+        }
+        instance.computing = this.runCompute(instance).finally(() => {
+            instance.computing = null;
+            if (instance.dirty) {
+                instance.dirty = false;
+                void this.recompute(instanceId);
+            }
+        });
+        return instance.computing;
+    }
+    async runCompute(instance) {
+        const startedAt = performance.now();
+        let data;
+        let deps;
+        try {
+            ({ data, deps } = await this.resources.compute(instance.resource, instance.inputs, { scope: instance.scope }));
+        }
+        catch (error) {
+            if ((0, route_executor_1.isLiveAuthorizationFailure)(error)) {
+                this.revokeInstance(instance.id);
+                return;
+            }
+            await this.broadcast(instance, sid => ({ t: 'stale', sid, reason: error.message }));
+            return;
+        }
+        this.recomputes++;
+        this.graph.setDependencies(instance.id, deps);
+        const hash = (0, hash_1.fnv1a64)((0, canonical_1.canonical)(data));
+        if (hash === instance.hash) {
+            // Recompute is not a patch. Coarse invalidation costs CPU, never
+            // traffic and never a re-render. This is the number of §10.
+            this.recomputesWithoutPatch++;
+            this.metrics.recompute(instance.resource.id, false, 0, performance.now() - startedAt);
+            return;
+        }
+        const ops = instance.patcher.diff(instance.data, data);
+        const from = instance.revision;
+        instance.data = data;
+        instance.hash = hash;
+        instance.revision += 1;
+        this.metrics.recompute(instance.resource.id, true, ops.length, performance.now() - startedAt);
+        await this.broadcast(instance, sid => ({
+            t: 'patch',
+            sid,
+            from,
+            to: instance.revision,
+            hash,
+            ops
+        }));
+    }
+    async broadcast(instance, build) {
+        for (const connectionId of [...this.subs.connectionsOf(instance.id)]) {
+            const scope = this.scopes.get(connectionId);
+            const allowed = scope
+                ? await this.checkAuthorization(connectionId, instance.id, instance.resource, instance.inputs, scope)
+                : false;
+            if (!allowed) {
+                this.revoke(connectionId, instance.id);
+                continue;
+            }
+            for (const sid of this.sidsFor(connectionId, instance.id)) {
+                const message = build(sid);
+                if (message.t === 'patch' && this.isBackedUp(connectionId)) {
+                    // The client is behind. Collapse instead of queueing more.
+                    this.send(connectionId, {
+                        t: 'snapshot',
+                        sid,
+                        rev: instance.revision,
+                        hash: instance.hash,
+                        data: instance.data,
+                        key: instance.resource.meta.key
+                    });
+                    this.backpressure.set(connectionId, 0);
+                    continue;
+                }
+                this.send(connectionId, message);
+            }
+        }
+    }
+    revokeInstance(instanceId) {
+        const connections = new Set(this.subs.connectionsOf(instanceId));
+        for (const connectionId of connections) {
+            this.revoke(connectionId, instanceId);
+        }
+    }
+    sidsFor(connectionId, instanceId) {
+        const owned = this.bindings.get(connectionId);
+        if (!owned) {
+            return [];
+        }
+        const sids = [];
+        for (const [sid, boundInstance] of owned) {
+            if (boundInstance === instanceId) {
+                sids.push(sid);
+            }
+        }
+        return sids;
+    }
+    isBackedUp(connectionId) {
+        return (this.backpressure.get(connectionId) ?? 0) >= this.config.maxPendingPatches;
+    }
+    send(connectionId, message) {
+        const result = this.transport.send(connectionId, message);
+        const current = this.backpressure.get(connectionId) ?? 0;
+        this.backpressure.set(connectionId, result > 0 ? 0 : current + 1);
+    }
+    fail(connectionId, sid, code, message) {
+        this.send(connectionId, { t: 'error', sid, code, message });
+    }
+}
+exports.LiveEngine = LiveEngine;

package/dist/LivePlugin.d.ts

@@ -0,0 +1,55 @@
+import { Carno } from '@carno.js/core';
+import { type WebSocketPluginConfig } from '@carno.js/websocket';
+import { type LiveAuthorizer } from './auth/authorizer';
+import { type PgNotifyTable } from './emitters/pg-notify-emitter';
+import { type LiveConfig } from './config';
+import { type LiveScopeResolver } from './transport/scope-resolver';
+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 declare class LivePlugin {
+    static create(options: LivePluginOptions): Carno;
+}