@carno.js/live 1.8.0

package/src/shared/hash.ts

@@ -0,0 +1,31 @@
+const FNV_OFFSET_BASIS_A = 2166136261;
+const FNV_OFFSET_BASIS_B = 0x9e3779b9;
+const FNV_PRIME = 16777619;
+
+/**
+ * FNV-1a widened to 64 output bits by running two lanes with different offset
+ * bases, the second one position-sensitive.
+ *
+ * `packages/orm/src/cache/cache-key-generator.ts` uses the 32-bit variant,
+ * which is right for a cache — a collision there costs one stale entry. Here a
+ * content-hash collision means "data changed but no patch was sent", and 32
+ * bits reach 50% collision odds around 65k keys while `maxInstancesPerNode`
+ * alone is 50000. This lives in one module so it can be swapped for a stronger
+ * hash without touching anything else.
+ */
+export function fnv1a64(input: string): string {
+    let laneA = FNV_OFFSET_BASIS_A;
+    let laneB = FNV_OFFSET_BASIS_B;
+
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+
+        laneA ^= code;
+        laneA = Math.imul(laneA, FNV_PRIME);
+
+        laneB ^= code + i;
+        laneB = Math.imul(laneB, FNV_PRIME);
+    }
+
+    return (laneA >>> 0).toString(16).padStart(8, '0') + (laneB >>> 0).toString(16).padStart(8, '0');
+}

package/src/shared/inputs.ts

@@ -0,0 +1,20 @@
+/** Everything a resource compute is allowed to read from the caller. */
+export interface LiveInputs {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    /**
+     * Body of a @Post() live resource. Absent on @Get().
+     *
+     * It is part of the instance identity, not extra baggage: two clients
+     * posting different filters must not share one computed instance.
+     */
+    body?: unknown;
+}
+
+/** Ambient dimensions resolved on the server; never sent by the client. */
+export interface LiveScope {
+    principal?: string | number;
+    tenant?: string | number;
+    /** Optional request headers for replaying route middleware during compute. */
+    headers?: HeadersInit;
+}

package/src/shared/protocol.ts

@@ -0,0 +1,96 @@
+import type { PatchOp } from '../patch/types';
+import type { LiveInputs } from '../resource/types';
+
+export const LIVE_PROTOCOL_VERSION = 1;
+
+/** Headers used by the HTTP polling rung to carry the live auth contract. */
+export const LIVE_POLL_HEADER = 'X-Carno-Live-Poll';
+export const LIVE_CONNECTION_HEADER = 'X-Carno-Live-Connection';
+export const LIVE_RESOURCE_HEADER = 'X-Carno-Live-Resource';
+export const LIVE_TOKEN_HEADER = 'X-Carno-Live-Token';
+
+/** Sent once per connection, before any subscription. */
+export interface ClientHello {
+    t: 'hello';
+    v: number;
+    /** Opaque credential; the server's LiveScopeResolver interprets it. */
+    token?: string;
+}
+
+export interface ClientSub {
+    t: 'sub';
+    /** Client-chosen subscription id. The instance id never leaves the server. */
+    sid: string;
+    resource: string;
+    inputs: LiveInputs;
+    /** Content hash of what the client already has on screen, if anything. */
+    hash?: string;
+}
+
+export interface ClientUnsub {
+    t: 'unsub';
+    sid: string;
+}
+
+export interface ClientResync {
+    t: 'resync';
+    sid: string;
+    hash?: string;
+}
+
+export type ClientMessage = ClientHello | ClientSub | ClientUnsub | ClientResync;
+
+/** Full state. */
+export interface ServerSnapshot {
+    t: 'snapshot';
+    sid: string;
+    rev: number;
+    hash: string;
+    data: unknown;
+    /**
+     * The resource's `@Live({ key })`, if it declared one. The client needs it
+     * to apply keyed ops, and this is the only message that establishes state,
+     * so it is the only place it has to travel.
+     */
+    key?: string;
+}
+
+/** The client's hash matched what the server computed: nothing on the wire. */
+export interface ServerCurrent {
+    t: 'current';
+    sid: string;
+    rev: number;
+    hash: string;
+    /** Same reason as on `snapshot`: this also establishes state, on hydration. */
+    key?: string;
+}
+
+export interface ServerPatch {
+    t: 'patch';
+    sid: string;
+    from: number;
+    to: number;
+    hash: string;
+    ops: PatchOp[];
+}
+
+/**
+ * The server cannot vouch for this instance being current (a recompute is
+ * failing). The client keeps showing the last data and flags it, so the UI can
+ * say so.
+ */
+export interface ServerStale {
+    t: 'stale';
+    sid: string;
+    reason: string;
+}
+
+/** The subscription is invalid or not allowed; the client ends the instance. */
+export interface ServerError {
+    t: 'error';
+    sid: string;
+    code: string;
+    message: string;
+}
+
+export type ServerMessage = ServerSnapshot | ServerCurrent | ServerPatch | ServerStale | ServerError;

package/src/transport/FanTransport.ts

@@ -0,0 +1,34 @@
+import type { LiveTransport } from '../LiveEngine';
+import type { ServerMessage } from '../shared/protocol';
+
+export interface OwnedTransport extends LiveTransport {
+    /** Whether this transport is the one holding that connection. */
+    owns(connectionId: string): boolean;
+}
+
+/**
+ * One engine, several pipes.
+ *
+ * The engine addresses connections by an opaque id and never asks how they are
+ * reached, which is exactly what makes SSE a transport rather than a second
+ * engine. This routes each send to whichever transport claims the id.
+ */
+export class FanTransport implements LiveTransport {
+    private readonly children: OwnedTransport[] = [];
+
+    add(child: OwnedTransport): void {
+        this.children.push(child);
+    }
+
+    send(connectionId: string, message: ServerMessage): number {
+        for (const child of this.children) {
+            if (child.owns(connectionId)) {
+                return child.send(connectionId, message);
+            }
+        }
+
+        // Nobody holds it any more. Zero is "dropped", which the engine already
+        // handles; throwing here would take a whole fan-out down with it.
+        return 0;
+    }
+}

package/src/transport/LiveGateway.ts

@@ -0,0 +1,124 @@
+import { CarnoSocket, Gateway, OnClose, OnMessage, OnOpen } from '@carno.js/websocket';
+import { getLiveRuntime } from '../runtime';
+import type { ClientMessage } from '../shared/protocol';
+
+export const LIVE_GATEWAY_PATH = '/live';
+
+/** Per-connection tail so `hello` finishes before a back-to-back `sub`. */
+const inbound = new Map<string, Promise<void>>();
+
+@Gateway(LIVE_GATEWAY_PATH)
+export class LiveGateway {
+    @OnOpen()
+    onOpen(socket: CarnoSocket): void {
+        const runtime = getLiveRuntime();
+        runtime.transport.add(socket);
+        runtime.handshakes.delete(socket.id);
+        // Until a `hello` arrives, the connection is its own principal: safe,
+        // shares nothing.
+        runtime.scopes.set(socket.id, { principal: socket.id });
+    }
+
+    @OnMessage()
+    onMessage(socket: CarnoSocket, raw: string | ArrayBuffer | Uint8Array): void {
+        if (typeof raw !== 'string') {
+            return;
+        }
+
+        void handleMessage(socket.id, raw).catch(() => {});
+    }
+
+    @OnClose()
+    onClose(socket: CarnoSocket): void {
+        dropLiveConnection(socket.id);
+        getLiveRuntime().transport.remove(socket.id);
+    }
+}
+
+/**
+ * Tear down a connection from any pipe.
+ *
+ * WebSocket and SSE must leave the engine, the inbound queue and the scope
+ * map in the same state: an in-flight `hello` cannot subscribe after the
+ * client has gone, and a cancelled stream cannot leak a principal.
+ */
+export function dropLiveConnection(connectionId: string): void {
+    inbound.delete(connectionId);
+    const runtime = getLiveRuntime();
+    runtime.engine.dropConnection(connectionId);
+    runtime.scopes.delete(connectionId);
+    runtime.handshakes.delete(connectionId);
+}
+
+export function handleMessage(connectionId: string, raw: string): Promise<void> {
+    const previous = inbound.get(connectionId) ?? Promise.resolve();
+    const next = previous.then(
+        () => dispatch(connectionId, raw),
+        () => dispatch(connectionId, raw)
+    );
+    inbound.set(connectionId, next);
+    return next;
+}
+
+async function dispatch(connectionId: string, raw: string): Promise<void> {
+    if (!inbound.has(connectionId)) {
+        return;
+    }
+
+    const runtime = getLiveRuntime();
+
+    let message: ClientMessage;
+
+    try {
+        message = JSON.parse(raw) as ClientMessage;
+    } catch {
+        return;
+    }
+
+    if (!message || typeof (message as { t?: unknown }).t !== 'string') {
+        return;
+    }
+
+    switch (message.t) {
+        case 'hello': {
+            if (runtime.handshakes.has(connectionId)) {
+                return;
+            }
+
+            const scope = await runtime.resolver.resolve({ connectionId, token: message.token });
+
+            if (!inbound.has(connectionId)) {
+                return;
+            }
+
+            runtime.scopes.set(connectionId, scope);
+            runtime.handshakes.add(connectionId);
+            return;
+        }
+
+        case 'sub': {
+            const scope = runtime.scopes.get(connectionId) ?? { principal: connectionId };
+            await runtime.engine.subscribe(
+                connectionId,
+                message.sid,
+                message.resource,
+                {
+                    params: message.inputs?.params ?? {},
+                    query: message.inputs?.query ?? {},
+                    body: message.inputs?.body
+                },
+                scope,
+                message.hash
+            );
+            return;
+        }
+
+        case 'unsub':
+            runtime.engine.unsubscribe(connectionId, message.sid);
+            return;
+
+        case 'resync':
+            await runtime.engine.resync(connectionId, message.sid, message.hash);
+            return;
+    }
+}

package/src/transport/SocketTransport.ts

@@ -0,0 +1,43 @@
+import type { CarnoSocket } from '@carno.js/websocket';
+import type { ServerMessage } from '../shared/protocol';
+import type { OwnedTransport } from './FanTransport';
+
+/**
+ * Sends protocol messages over the raw socket.
+ *
+ * We use `socket.send()` rather than `socket.emit()` because emit wraps the
+ * payload in `{ event, data }` for the gateway's own event protocol, and this
+ * is a different protocol.
+ */
+export class SocketTransport implements OwnedTransport {
+    private readonly sockets = new Map<string, CarnoSocket>();
+
+    add(socket: CarnoSocket): void {
+        this.sockets.set(socket.id, socket);
+    }
+
+    remove(connectionId: string): void {
+        this.sockets.delete(connectionId);
+    }
+
+    owns(connectionId: string): boolean {
+        return this.sockets.has(connectionId);
+    }
+
+    /** <= 0 means back-pressured or dropped; the engine counts those. */
+    send(connectionId: string, message: ServerMessage): number {
+        const socket = this.sockets.get(connectionId);
+
+        if (!socket) {
+            return 0;
+        }
+
+        try {
+            return socket.send(JSON.stringify(message));
+        } catch {
+            // The socket closed between fan-out and send. Treat as dropped;
+            // the close handler will clean it up.
+            return 0;
+        }
+    }
+}

package/src/transport/SseTransport.ts

@@ -0,0 +1,112 @@
+import type { ServerMessage } from '../shared/protocol';
+import type { OwnedTransport } from './FanTransport';
+
+export interface SseTransportOptions {
+    /** 0 disables the heartbeat. Only tests want that. */
+    heartbeatMs: number;
+    maxConnections: number;
+    /** Called when the client goes away, so the engine can drop the connection. */
+    onDisconnect?: (connectionId: string) => void;
+}
+
+const ENCODER = new TextEncoder();
+const NativeReadableStream = ReadableStream;
+
+/**
+ * The downstream half of the SSE transport.
+ *
+ * Upstream is `POST /live/control`, which speaks the same protocol into the
+ * same handler the WebSocket gateway uses -- see `sse-routes.ts`. This half
+ * only writes frames, so the engine cannot tell it apart from a socket.
+ */
+export class SseTransport implements OwnedTransport {
+    private readonly streams = new Map<string, ReadableStreamDefaultController<Uint8Array>>();
+    private heartbeat: ReturnType<typeof setInterval> | null = null;
+
+    constructor(private readonly options: SseTransportOptions) {}
+
+    open(connectionId: string): ReadableStream<Uint8Array> {
+        if (this.streams.size >= this.options.maxConnections) {
+            throw new Error(`[carno:live] the SSE transport is at capacity (${this.options.maxConnections}).`);
+        }
+
+        return new NativeReadableStream<Uint8Array>({
+            start: controller => {
+                this.streams.set(connectionId, controller);
+                // The client cannot learn its own connection id any other way,
+                // and it needs it to address the control endpoint.
+                this.write(controller, `data: ${JSON.stringify({ t: 'ready', cid: connectionId })}\n\n`);
+                this.ensureHeartbeat();
+            },
+            cancel: () => {
+                this.streams.delete(connectionId);
+                this.options.onDisconnect?.(connectionId);
+            }
+        });
+    }
+
+    owns(connectionId: string): boolean {
+        return this.streams.has(connectionId);
+    }
+
+    send(connectionId: string, message: ServerMessage): number {
+        const controller = this.streams.get(connectionId);
+
+        if (!controller) {
+            return 0;
+        }
+
+        return this.write(controller, `data: ${JSON.stringify(message)}\n\n`);
+    }
+
+    close(connectionId: string): void {
+        const controller = this.streams.get(connectionId);
+        this.streams.delete(connectionId);
+
+        try {
+            controller?.close();
+        } catch {
+            // Already closed from the other end.
+        }
+    }
+
+    count(): number {
+        return this.streams.size;
+    }
+
+    stop(): void {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+
+        for (const connectionId of [...this.streams.keys()]) {
+            this.close(connectionId);
+        }
+    }
+
+    private ensureHeartbeat(): void {
+        if (this.heartbeat || this.options.heartbeatMs <= 0) {
+            return;
+        }
+
+        // A comment frame. EventSource ignores it; an idle-timeout proxy does
+        // not, which is the whole point.
+        this.heartbeat = setInterval(() => {
+            for (const controller of this.streams.values()) {
+                this.write(controller, ': ping\n\n');
+            }
+        }, this.options.heartbeatMs);
+
+        this.heartbeat.unref?.();
+    }
+
+    private write(controller: ReadableStreamDefaultController<Uint8Array>, frame: string): number {
+        try {
+            controller.enqueue(ENCODER.encode(frame));
+            return 1;
+        } catch {
+            return 0;
+        }
+    }
+}

package/src/transport/scope-resolver.ts

@@ -0,0 +1,25 @@
+import type { LiveScope } from '../shared/inputs';
+
+export interface LiveHandshake {
+    connectionId: string;
+    /** Opaque credential from the client's `hello`. */
+    token?: string;
+}
+
+export interface LiveScopeResolver {
+    resolve(handshake: LiveHandshake): LiveScope | Promise<LiveScope>;
+}
+
+/**
+ * Default resolver: every connection is its own principal.
+ *
+ * Safe by construction — nothing is ever shared between connections, so no
+ * application can leak one user's data to another by forgetting to configure
+ * this. Applications that want `shared: 'tenant'` or a real user identity
+ * replace it.
+ */
+export class ConnectionScopeResolver implements LiveScopeResolver {
+    resolve(handshake: LiveHandshake): LiveScope {
+        return { principal: handshake.connectionId };
+    }
+}

package/src/transport/sse-routes.ts

@@ -0,0 +1,94 @@
+import { getLiveRuntime } from '../runtime';
+import { dropLiveConnection, handleMessage } from './LiveGateway';
+import type { SseTransport } from './SseTransport';
+
+export interface SseRouteOptions {
+    transport: SseTransport;
+    streamPath: string;
+    controlPath: string;
+}
+
+// Captured at load so a later happy-dom register cannot replace the
+// constructor Bun.serve requires of a route handler.
+const NativeResponse = Response;
+
+const SSE_HEADERS = {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    // Nginx buffers proxied responses by default, which turns a live stream
+    // into a stream that arrives all at once, at the end.
+    'X-Accel-Buffering': 'no'
+};
+
+/**
+ * The two halves of the SSE transport, as HTTP.
+ *
+ * `GET streamPath` opens the downstream and names the connection; every
+ * client message goes up through `POST controlPath` and into the same
+ * `handleMessage` the WebSocket gateway uses. There is no second protocol
+ * here, and there must never be one.
+ *
+ * Handlers registered through `Carno.route()` receive a Bun `Request`, not a
+ * `Context` -- the docstring on that method says otherwise, the runtime does
+ * not.
+ */
+export function createSseRoutes(options: SseRouteOptions) {
+    const { transport, streamPath, controlPath } = options;
+
+    const stream = (request: Request): Response => {
+        // Unguessable on purpose: the id is a bearer for this connection, and
+        // whoever holds it can subscribe as it.
+        const connectionId = `sse:${crypto.randomUUID()}`;
+
+        try {
+            const body = transport.open(connectionId);
+            const runtime = getLiveRuntime();
+            // Until a `hello` arrives, the connection is its own principal:
+            // safe, shares nothing. Same rule as the gateway's onOpen.
+            runtime.scopes.set(connectionId, { principal: connectionId });
+            runtime.handshakes.delete(connectionId);
+
+            // Cancelling the client reader does not always reach the stream's
+            // `cancel`; aborting the request does, and is what a closed
+            // EventSource looks like on the wire.
+            request.signal.addEventListener('abort', () => {
+                transport.close(connectionId);
+
+                try {
+                    dropLiveConnection(connectionId);
+                } catch {
+                    // closeLiveRuntime nulls the runtime before dispose.
+                }
+            });
+
+            return new NativeResponse(body, { status: 200, headers: SSE_HEADERS });
+        } catch (error) {
+            return new NativeResponse((error as Error).message, { status: 503 });
+        }
+    };
+
+    const control = async (request: Request): Promise<Response> => {
+        let payload: { cid?: unknown; message?: unknown };
+
+        try {
+            payload = await request.json() as { cid?: unknown; message?: unknown };
+        } catch {
+            return new NativeResponse('malformed body', { status: 400 });
+        }
+
+        if (typeof payload.cid !== 'string' || !payload.message) {
+            return new NativeResponse('cid and message are required', { status: 400 });
+        }
+
+        if (!transport.owns(payload.cid)) {
+            return new NativeResponse('unknown connection', { status: 404 });
+        }
+
+        await handleMessage(payload.cid, JSON.stringify(payload.message));
+
+        return new NativeResponse(null, { status: 204 });
+    };
+
+    return { streamPath, controlPath, stream, control };
+}