@carno.js/live 1.8.0

package/dist/client/transport.d.ts

@@ -0,0 +1,133 @@
+import type { LiveSocket } from './core';
+export interface TransportHandlers {
+    onOpen(): void;
+    onMessage(raw: string): void;
+    onClose(): void;
+}
+/**
+ * A pipe the client can speak the protocol over.
+ *
+ * The protocol does not change between implementations, and neither does the
+ * client's behaviour: a component cannot tell which one is in use, and the day
+ * an `if (kind === 'sse')` appears in a component, the abstraction has failed.
+ * `kind` exists to be logged.
+ */
+export interface ClientTransport {
+    readonly kind: 'websocket' | 'sse' | 'polling';
+    start(handlers: TransportHandlers): void;
+    send(raw: string): void;
+    close(): void;
+}
+export declare class WebSocketTransport implements ClientTransport {
+    private readonly url;
+    private readonly factory;
+    readonly kind: "websocket";
+    private socket;
+    private closed;
+    constructor(url: string, factory?: (url: string) => LiveSocket);
+    start(handlers: TransportHandlers): void;
+    send(raw: string): void;
+    close(): void;
+    private report;
+}
+export interface RoutePath {
+    method: string;
+    path: string;
+}
+export interface EventSourceLike {
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    close(): void;
+}
+/**
+ * Flatten the tree `@carno.js/client` generates into `resourceId -> path`.
+ *
+ * Polling needs a URL and the protocol carries a resource id, so without this
+ * the bottom rung cannot exist. Routes with no `@Live()` are skipped: polling
+ * one would be polling something nobody can subscribe to.
+ */
+export declare function routeIndex(routes: unknown): Record<string, RoutePath>;
+/**
+ * Try each rung in order, descend when one does not open.
+ *
+ * There is no promotion back up: a proxy that blocks WebSocket will keep
+ * blocking it, and retrying the top rung on every reconnect spends a round
+ * trip per cycle to fail forever. The next page load starts at the top again.
+ */
+export declare class LadderTransport implements ClientTransport {
+    private readonly rungs;
+    private readonly options;
+    private active;
+    private handlers;
+    private rung;
+    private settled;
+    private probe;
+    private closed;
+    constructor(rungs: (() => ClientTransport)[], options: {
+        probeMs: number;
+    });
+    get kind(): ClientTransport['kind'];
+    start(handlers: TransportHandlers): void;
+    send(raw: string): void;
+    close(): void;
+    private tryRung;
+    private descend;
+    private clearProbe;
+}
+/**
+ * The protocol over Server-Sent Events: down the stream, up by POST.
+ *
+ * The connection id arrives in the first frame and every client message
+ * carries it, because the control endpoint has no other way to know which
+ * stream a POST belongs to.
+ */
+export declare class SseClientTransport implements ClientTransport {
+    private readonly baseUrl;
+    private readonly options;
+    readonly kind: "sse";
+    private source;
+    private cid;
+    private queue;
+    private closed;
+    constructor(baseUrl: string, options?: {
+        streamPath?: string;
+        controlPath?: string;
+        fetch?: typeof fetch;
+        eventSourceFactory?: (url: string) => EventSourceLike;
+    });
+    start(handlers: TransportHandlers): void;
+    send(raw: string): void;
+    close(): void;
+}
+/**
+ * The floor: conditional GET on the route the resource already serves.
+ *
+ * There are no patches here, only snapshots and 304s. A patch would need the
+ * server to remember this client's previous revision, which is precisely the
+ * history §8.1 says does not exist.
+ */
+export declare class PollingTransport implements ClientTransport {
+    private readonly baseUrl;
+    private readonly routes;
+    private readonly options;
+    readonly kind: "polling";
+    private handlers;
+    private readonly polls;
+    private readonly connectionId;
+    private token;
+    private timer;
+    constructor(baseUrl: string, routes: Record<string, RoutePath>, options?: {
+        intervalMs?: number;
+        fetch?: typeof fetch;
+        token?: string;
+    });
+    start(handlers: TransportHandlers): void;
+    send(raw: string): void;
+    close(): void;
+    private tick;
+    private fetchOne;
+    private emit;
+}

package/dist/client/transport.js

@@ -0,0 +1,431 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PollingTransport = exports.SseClientTransport = exports.LadderTransport = exports.WebSocketTransport = void 0;
+exports.routeIndex = routeIndex;
+const protocol_1 = require("../shared/protocol");
+class WebSocketTransport {
+    constructor(url, factory = defaultSocketFactory) {
+        this.url = url;
+        this.factory = factory;
+        this.kind = 'websocket';
+        this.socket = null;
+        this.closed = false;
+    }
+    start(handlers) {
+        const socket = this.factory(this.url);
+        this.socket = socket;
+        socket.onopen = () => handlers.onOpen();
+        socket.onmessage = event => handlers.onMessage(event.data);
+        // An error and a close both mean the same thing here: the pipe is gone.
+        socket.onclose = () => this.report(handlers);
+        socket.onerror = () => this.report(handlers);
+    }
+    send(raw) {
+        this.socket?.send(raw);
+    }
+    close() {
+        this.closed = true;
+        this.socket?.close();
+        this.socket = null;
+    }
+    report(handlers) {
+        if (this.closed) {
+            // We closed it. Reporting it would schedule a reconnect to a
+            // client that has already given up.
+            // Also latches error-then-close so the ladder sees one death,
+            // not two descents that skip a rung.
+            return;
+        }
+        this.closed = true;
+        this.socket = null;
+        handlers.onClose();
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;
+function defaultSocketFactory(url) {
+    return new WebSocket(url);
+}
+/**
+ * Flatten the tree `@carno.js/client` generates into `resourceId -> path`.
+ *
+ * Polling needs a URL and the protocol carries a resource id, so without this
+ * the bottom rung cannot exist. Routes with no `@Live()` are skipped: polling
+ * one would be polling something nobody can subscribe to.
+ */
+function routeIndex(routes) {
+    const index = {};
+    const walk = (node) => {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        const candidate = node;
+        if (typeof candidate.method === 'string' && typeof candidate.path === 'string') {
+            if (candidate.method.toLowerCase() === 'get' &&
+                typeof candidate.resourceId === 'string' &&
+                candidate.live) {
+                index[candidate.resourceId] = { method: candidate.method, path: candidate.path };
+            }
+            return;
+        }
+        for (const value of Object.values(node)) {
+            walk(value);
+        }
+    };
+    walk(routes);
+    return index;
+}
+/**
+ * Try each rung in order, descend when one does not open.
+ *
+ * There is no promotion back up: a proxy that blocks WebSocket will keep
+ * blocking it, and retrying the top rung on every reconnect spends a round
+ * trip per cycle to fail forever. The next page load starts at the top again.
+ */
+class LadderTransport {
+    constructor(rungs, options) {
+        this.rungs = rungs;
+        this.options = options;
+        this.active = null;
+        this.handlers = null;
+        this.rung = 0;
+        this.settled = false;
+        this.probe = null;
+        this.closed = false;
+    }
+    get kind() {
+        return this.active?.kind ?? 'websocket';
+    }
+    start(handlers) {
+        this.handlers = handlers;
+        this.rung = 0;
+        this.settled = false;
+        this.tryRung();
+    }
+    send(raw) {
+        this.active?.send(raw);
+    }
+    close() {
+        this.closed = true;
+        this.clearProbe();
+        this.active?.close();
+        this.active = null;
+    }
+    tryRung() {
+        this.clearProbe();
+        if (this.closed) {
+            return;
+        }
+        if (this.rung >= this.rungs.length) {
+            // Every rung refused. One close, not one per rung, or the client
+            // schedules a reconnect storm against itself.
+            this.handlers?.onClose();
+            return;
+        }
+        const rung = this.rung;
+        const transport = this.rungs[rung]();
+        this.active = transport;
+        transport.start({
+            onOpen: () => {
+                this.clearProbe();
+                this.settled = true;
+                this.handlers?.onOpen();
+            },
+            onMessage: raw => this.handlers?.onMessage(raw),
+            onClose: () => {
+                if (this.active !== transport) {
+                    // A previous rung firing error then close. One death,
+                    // one descent — otherwise we skip the rung that just
+                    // became active.
+                    return;
+                }
+                if (this.settled) {
+                    // It worked and then dropped. That is an ordinary
+                    // disconnect and the client's backoff owns it.
+                    this.handlers?.onClose();
+                    return;
+                }
+                this.descend();
+            }
+        });
+        // A proxy that swallows the upgrade without answering never fires an
+        // error. Without this the ladder would wait for a close that never
+        // comes, on the rung that is exactly the one being blocked.
+        if (this.active === transport && this.rung === rung && !this.settled && !this.closed) {
+            this.probe = setTimeout(() => this.descend(), this.options.probeMs);
+            this.probe.unref?.();
+        }
+    }
+    descend() {
+        if (this.settled || this.closed) {
+            return;
+        }
+        this.clearProbe();
+        this.active?.close();
+        this.active = null;
+        this.rung += 1;
+        this.tryRung();
+    }
+    clearProbe() {
+        if (this.probe) {
+            clearTimeout(this.probe);
+            this.probe = null;
+        }
+    }
+}
+exports.LadderTransport = LadderTransport;
+/**
+ * The protocol over Server-Sent Events: down the stream, up by POST.
+ *
+ * The connection id arrives in the first frame and every client message
+ * carries it, because the control endpoint has no other way to know which
+ * stream a POST belongs to.
+ */
+class SseClientTransport {
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl;
+        this.options = options;
+        this.kind = 'sse';
+        this.source = null;
+        this.cid = null;
+        this.queue = [];
+        this.closed = false;
+    }
+    start(handlers) {
+        const streamUrl = `${this.baseUrl}${this.options.streamPath ?? '/live/sse'}`;
+        if (!this.options.eventSourceFactory && typeof EventSource === 'undefined') {
+            // SSR and Bun do not provide the browser EventSource API. Treat
+            // that as an unavailable rung so the ladder can continue to the
+            // next transport instead of throwing during construction.
+            handlers.onClose();
+            return;
+        }
+        const build = this.options.eventSourceFactory
+            ?? ((url) => new EventSource(url));
+        const source = build(streamUrl);
+        this.source = source;
+        source.onmessage = event => {
+            let frame;
+            try {
+                frame = JSON.parse(event.data);
+            }
+            catch {
+                return;
+            }
+            if (frame.t === 'ready' && typeof frame.cid === 'string') {
+                this.cid = frame.cid;
+                handlers.onOpen();
+                // Anything the client tried to say before the id arrived.
+                const queued = this.queue;
+                this.queue = [];
+                for (const raw of queued) {
+                    this.send(raw);
+                }
+                return;
+            }
+            handlers.onMessage(event.data);
+        };
+        source.onerror = () => {
+            if (this.closed) {
+                return;
+            }
+            this.closed = true;
+            this.source?.close();
+            this.source = null;
+            handlers.onClose();
+        };
+    }
+    send(raw) {
+        if (!this.cid) {
+            this.queue.push(raw);
+            return;
+        }
+        const post = this.options.fetch ?? fetch;
+        void post(`${this.baseUrl}${this.options.controlPath ?? '/live/control'}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ cid: this.cid, message: JSON.parse(raw) })
+        }).catch(() => {
+            // A failed control POST is not a dead stream. The stream's own
+            // error handler owns the disconnect.
+        });
+    }
+    close() {
+        this.closed = true;
+        this.source?.close();
+        this.source = null;
+        this.cid = null;
+    }
+}
+exports.SseClientTransport = SseClientTransport;
+/**
+ * The floor: conditional GET on the route the resource already serves.
+ *
+ * There are no patches here, only snapshots and 304s. A patch would need the
+ * server to remember this client's previous revision, which is precisely the
+ * history §8.1 says does not exist.
+ */
+class PollingTransport {
+    constructor(baseUrl, routes, options = {}) {
+        this.baseUrl = baseUrl;
+        this.routes = routes;
+        this.options = options;
+        this.kind = 'polling';
+        this.handlers = null;
+        this.polls = new Map();
+        this.connectionId = pollingConnectionId();
+        this.timer = null;
+        this.token = options.token;
+    }
+    start(handlers) {
+        this.handlers = handlers;
+        handlers.onOpen();
+        const interval = this.options.intervalMs ?? 5000;
+        this.timer = setInterval(() => this.tick(), interval);
+        this.timer.unref?.();
+    }
+    send(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.t === 'unsub') {
+            this.polls.delete(message.sid);
+            return;
+        }
+        if (message.t === 'hello') {
+            this.token = message.token;
+            return;
+        }
+        if (message.t !== 'sub') {
+            // `resync` is answered by the next tick anyway.
+            return;
+        }
+        const route = this.routes[message.resource];
+        if (!route) {
+            this.emit({
+                t: 'error',
+                sid: message.sid,
+                code: 'no_route',
+                message: `Polling cannot reach "${message.resource}": pass the generated \`routes\` ` +
+                    `to the LiveClient so it can turn a resource id into a URL.`
+            });
+            return;
+        }
+        const poll = {
+            sid: message.sid,
+            resourceId: message.resource,
+            url: buildUrl(this.baseUrl, route.path, message.inputs),
+            etag: message.hash ? `"${message.hash}"` : null,
+            revision: 0
+        };
+        this.polls.set(message.sid, poll);
+        void this.fetchOne(poll);
+    }
+    close() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.polls.clear();
+    }
+    tick() {
+        for (const poll of this.polls.values()) {
+            void this.fetchOne(poll);
+        }
+    }
+    async fetchOne(poll) {
+        const get = this.options.fetch ?? fetch;
+        const headers = {};
+        headers[protocol_1.LIVE_POLL_HEADER] = '1';
+        headers[protocol_1.LIVE_CONNECTION_HEADER] = this.connectionId;
+        headers[protocol_1.LIVE_RESOURCE_HEADER] = poll.resourceId;
+        if (this.token) {
+            headers[protocol_1.LIVE_TOKEN_HEADER] = this.token;
+        }
+        if (poll.etag) {
+            headers['If-None-Match'] = poll.etag;
+        }
+        let response;
+        try {
+            response = await get(poll.url, { headers });
+        }
+        catch (error) {
+            this.emit({ t: 'stale', sid: poll.sid, reason: error.message });
+            return;
+        }
+        if (response.status === 304) {
+            // Already right on screen. Emitting a snapshot would hand the
+            // store a new object for identical content and re-render for it.
+            return;
+        }
+        if (!response.ok) {
+            if (response.status === 401 || response.status === 403) {
+                this.polls.delete(poll.sid);
+                this.emit({
+                    t: 'error',
+                    sid: poll.sid,
+                    code: 'forbidden',
+                    message: 'Polling authorization failed.'
+                });
+                return;
+            }
+            if (response.status >= 400 && response.status < 500) {
+                this.polls.delete(poll.sid);
+                this.emit({
+                    t: 'error',
+                    sid: poll.sid,
+                    code: 'invalid_subscription',
+                    message: `Polling route returned HTTP ${response.status}.`
+                });
+                return;
+            }
+            this.emit({ t: 'stale', sid: poll.sid, reason: `HTTP ${response.status}` });
+            return;
+        }
+        const tag = response.headers.get('ETag');
+        poll.etag = tag;
+        poll.revision += 1;
+        this.emit({
+            t: 'snapshot',
+            sid: poll.sid,
+            rev: poll.revision,
+            hash: tag ? tag.replace(/"/g, '') : '',
+            data: await response.json()
+        });
+    }
+    emit(message) {
+        this.handlers?.onMessage(JSON.stringify(message));
+    }
+}
+exports.PollingTransport = PollingTransport;
+function pollingConnectionId() {
+    const uuid = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+        ? crypto.randomUUID()
+        : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    return `poll:${uuid}`;
+}
+function buildUrl(baseUrl, path, inputs) {
+    const filled = path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, name) => {
+        const value = inputs.params?.[name];
+        if (value === undefined) {
+            throw new Error(`Missing path parameter "${name}" for ${path}.`);
+        }
+        return encodeURIComponent(String(value));
+    });
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(inputs.query ?? {})) {
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                search.append(key, String(item));
+            }
+        }
+        else if (value !== undefined && value !== null) {
+            search.set(key, String(value));
+        }
+    }
+    const suffix = search.toString();
+    return `${baseUrl}${filled}${suffix ? `?${suffix}` : ''}`;
+}

package/dist/client/vanilla.d.ts

@@ -0,0 +1,54 @@
+import { 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 declare function liveStoreOf(client: LiveClient, resource: string | LiveDescriptor<any>, inputs?: Record<string, any>): LiveStore<unknown>;
+/**
+ * Canonical identity of a subscription, for adapters that need to know whether
+ * reactive inputs actually changed before tearing a subscription down.
+ */
+export declare function liveIdentity(resource: string | LiveDescriptor<any>, inputs?: Record<string, any>): string;
+export declare function liveStore<R>(client: LiveClient, descriptor: LiveDescriptor<R>, inputs?: LiveInputsOf<R>): LiveHandle<LiveDataOf<R>>;
+export declare function liveStore<T>(client: LiveClient, resourceId: string, inputs?: Partial<LiveInputs>): LiveHandle<T>;
+/**
+ * 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 declare class LiveSlot<T> {
+    private readonly client;
+    private readonly onState;
+    private identity;
+    private release;
+    private store;
+    constructor(client: LiveClient, onState: (state: LiveState<T>) => void);
+    point(resource: string | LiveDescriptor<any>, inputs?: Record<string, any>): void;
+    get(): LiveState<T>;
+    close(): void;
+}