@carno.js/live 1.8.0

package/test/transport-ladder.test.ts

@@ -0,0 +1,293 @@
+import { describe, expect, test } from 'bun:test';
+import {
+    LadderTransport,
+    PollingTransport,
+    SseClientTransport,
+    routeIndex,
+    type ClientTransport,
+    type TransportHandlers
+} from '../src/client/transport';
+
+const GENERATED_ROUTES = {
+    cards: {
+        list: { method: 'get', path: '/cards', resourceId: 'CardsController.list', live: { shared: 'public' } },
+        one: { method: 'get', path: '/cards/:id', resourceId: 'CardsController.one', live: { shared: 'public' } }
+    },
+    health: {
+        check: { method: 'get', path: '/health' }
+    }
+};
+
+function stubTransport(kind: ClientTransport['kind'], behaviour: 'open' | 'fail'): ClientTransport & { started: number } {
+    const transport = {
+        kind,
+        started: 0,
+        start(handlers: TransportHandlers) {
+            transport.started += 1;
+            queueMicrotask(() => (behaviour === 'open' ? handlers.onOpen() : handlers.onClose()));
+        },
+        send() {},
+        close() {}
+    };
+
+    return transport;
+}
+
+describe('routeIndex', () => {
+    test('flattens the generated tree into resourceId to path', () => {
+        expect(routeIndex(GENERATED_ROUTES)).toEqual({
+            'CardsController.list': { method: 'get', path: '/cards' },
+            'CardsController.one': { method: 'get', path: '/cards/:id' }
+        });
+    });
+
+    test('skips routes that are not live, because polling one means nothing', () => {
+        expect(routeIndex(GENERATED_ROUTES)['HealthController.check']).toBeUndefined();
+    });
+
+    test('skips live POST routes because polling only has a GET body', () => {
+        expect(routeIndex({
+            search: {
+                run: { method: 'post', path: '/cards/search', resourceId: 'CardsController.search', live: {} }
+            }
+        })['CardsController.search']).toBeUndefined();
+    });
+
+    test('an empty or absent tree is an empty index, not a throw', () => {
+        expect(routeIndex(undefined)).toEqual({});
+        expect(routeIndex({})).toEqual({});
+    });
+});
+
+describe('LadderTransport', () => {
+    test('stays on the first rung when it opens', async () => {
+        const socket = stubTransport('websocket', 'open');
+        const sse = stubTransport('sse', 'open');
+        const ladder = new LadderTransport([() => socket, () => sse], { probeMs: 50 });
+        let opened = false;
+
+        ladder.start({ onOpen: () => { opened = true; }, onMessage: () => {}, onClose: () => {} });
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        expect(opened).toBe(true);
+        expect(ladder.kind).toBe('websocket');
+        expect(sse.started).toBe(0);
+    });
+
+    test('descends when a rung fails to open', async () => {
+        const socket = stubTransport('websocket', 'fail');
+        const sse = stubTransport('sse', 'open');
+        const ladder = new LadderTransport([() => socket, () => sse], { probeMs: 50 });
+        let opened = false;
+
+        ladder.start({ onOpen: () => { opened = true; }, onMessage: () => {}, onClose: () => {} });
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(opened).toBe(true);
+        expect(ladder.kind).toBe('sse');
+    });
+
+    test('descends when a rung neither opens nor fails within the probe window', async () => {
+        const stuck: ClientTransport = { kind: 'websocket', start() {}, send() {}, close() {} };
+        const sse = stubTransport('sse', 'open');
+        const ladder = new LadderTransport([() => stuck, () => sse], { probeMs: 10 });
+        let opened = false;
+
+        ladder.start({ onOpen: () => { opened = true; }, onMessage: () => {}, onClose: () => {} });
+        await new Promise(resolve => setTimeout(resolve, 40));
+
+        // A corporate proxy that swallows the upgrade without answering is
+        // the case that makes the timeout necessary rather than tidy.
+        expect(opened).toBe(true);
+        expect(ladder.kind).toBe('sse');
+    });
+
+    test('reports a real close once it is settled, so the client can reconnect', async () => {
+        let handlers: TransportHandlers | null = null;
+        const flaky: ClientTransport = {
+            kind: 'websocket',
+            start(next) { handlers = next; queueMicrotask(() => next.onOpen()); },
+            send() {},
+            close() {}
+        };
+        const ladder = new LadderTransport([() => flaky], { probeMs: 50 });
+        let closes = 0;
+
+        ladder.start({ onOpen: () => {}, onMessage: () => {}, onClose: () => { closes += 1; } });
+        await new Promise(resolve => setTimeout(resolve, 10));
+        handlers!.onClose();
+
+        expect(closes).toBe(1);
+    });
+
+    test('a ladder whose every rung fails reports one close, not one per rung', async () => {
+        const ladder = new LadderTransport(
+            [() => stubTransport('websocket', 'fail'), () => stubTransport('sse', 'fail')],
+            { probeMs: 10 }
+        );
+        let closes = 0;
+
+        ladder.start({ onOpen: () => {}, onMessage: () => {}, onClose: () => { closes += 1; } });
+        await new Promise(resolve => setTimeout(resolve, 40));
+
+        expect(closes).toBe(1);
+    });
+
+    test('reports one close when a rung fails synchronously', async () => {
+        const ladder = new LadderTransport([() => new SseClientTransport('http://x')], { probeMs: 10 });
+        let closes = 0;
+
+        ladder.start({ onOpen: () => {}, onMessage: () => {}, onClose: () => { closes += 1; } });
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(closes).toBe(1);
+    });
+});
+
+describe('SseClientTransport', () => {
+    test('reports an unavailable EventSource as a failed rung', () => {
+        const transport = new SseClientTransport('http://x');
+        let closes = 0;
+
+        expect(() => transport.start({
+            onOpen: () => {},
+            onMessage: () => {},
+            onClose: () => { closes += 1; }
+        })).not.toThrow();
+
+        expect(closes).toBe(1);
+    });
+});
+
+describe('PollingTransport', () => {
+    test('turns a sub into a conditional GET and the answer into a snapshot', async () => {
+        const calls: { url: string; headers: Record<string, string> }[] = [];
+        const fetchStub = (async (url: any, init: any) => {
+            calls.push({ url: String(url), headers: (init?.headers ?? {}) as Record<string, string> });
+            return new Response(JSON.stringify([{ id: 1 }]), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json', ETag: '"abc"' }
+            });
+        }) as unknown as typeof fetch;
+
+        const transport = new PollingTransport(
+            'http://x',
+            routeIndex(GENERATED_ROUTES),
+            { intervalMs: 10_000, fetch: fetchStub }
+        );
+
+        const received: any[] = [];
+        transport.start({ onOpen: () => {}, onMessage: raw => received.push(JSON.parse(raw)), onClose: () => {} });
+        transport.send(JSON.stringify({ t: 'hello', v: 1, token: 'poll-secret' }));
+        transport.send(JSON.stringify({
+            t: 'sub',
+            sid: 's1',
+            resource: 'CardsController.list',
+            inputs: { params: {}, query: { done: 'true' } }
+        }));
+
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(calls[0].url).toBe('http://x/cards?done=true');
+        expect(calls[0].headers['X-Carno-Live-Poll']).toBe('1');
+        expect(calls[0].headers['X-Carno-Live-Token']).toBe('poll-secret');
+        expect(calls[0].headers['X-Carno-Live-Connection']).toMatch(/^poll:/);
+        expect(received[0]).toMatchObject({ t: 'snapshot', sid: 's1', data: [{ id: 1 }], hash: 'abc' });
+        transport.close();
+    });
+
+    test('sends If-None-Match on the second poll and emits nothing on 304', async () => {
+        let call = 0;
+        const fetchStub = (async (_url: any, init: any) => {
+            call += 1;
+
+            if (call === 1) {
+                return new Response(JSON.stringify([{ id: 1 }]), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/json', ETag: '"abc"' }
+                });
+            }
+
+            expect((init.headers as Record<string, string>)['If-None-Match']).toBe('"abc"');
+            return new Response(null, { status: 304 });
+        }) as unknown as typeof fetch;
+
+        const transport = new PollingTransport(
+            'http://x',
+            routeIndex(GENERATED_ROUTES),
+            { intervalMs: 5, fetch: fetchStub }
+        );
+
+        const received: any[] = [];
+        transport.start({ onOpen: () => {}, onMessage: raw => received.push(JSON.parse(raw)), onClose: () => {} });
+        transport.send(JSON.stringify({
+            t: 'sub', sid: 's1', resource: 'CardsController.list', inputs: { params: {}, query: {} }
+        }));
+
+        await new Promise(resolve => setTimeout(resolve, 40));
+
+        // 304 means the screen is already right. Emitting a snapshot would
+        // hand the store a new object for identical content and re-render.
+        expect(received.filter(message => message.t === 'snapshot').length).toBe(1);
+        transport.close();
+    });
+
+    test('fills :params from the inputs', async () => {
+        const urls: string[] = [];
+        const fetchStub = (async (url: any) => {
+            urls.push(String(url));
+            return new Response('{}', { status: 200, headers: { 'Content-Type': 'application/json' } });
+        }) as unknown as typeof fetch;
+
+        const transport = new PollingTransport('http://x', routeIndex(GENERATED_ROUTES), { intervalMs: 10_000, fetch: fetchStub });
+        transport.start({ onOpen: () => {}, onMessage: () => {}, onClose: () => {} });
+        transport.send(JSON.stringify({
+            t: 'sub', sid: 's1', resource: 'CardsController.one', inputs: { params: { id: '42' }, query: {} }
+        }));
+
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(urls[0]).toBe('http://x/cards/42');
+        transport.close();
+    });
+
+    test('an unsub stops the polling for that subscription', async () => {
+        let calls = 0;
+        const fetchStub = (async () => {
+            calls += 1;
+            return new Response('[]', { status: 200, headers: { 'Content-Type': 'application/json' } });
+        }) as unknown as typeof fetch;
+
+        const transport = new PollingTransport('http://x', routeIndex(GENERATED_ROUTES), { intervalMs: 5, fetch: fetchStub });
+        transport.start({ onOpen: () => {}, onMessage: () => {}, onClose: () => {} });
+        transport.send(JSON.stringify({
+            t: 'sub', sid: 's1', resource: 'CardsController.list', inputs: { params: {}, query: {} }
+        }));
+
+        await new Promise(resolve => setTimeout(resolve, 20));
+        transport.send(JSON.stringify({ t: 'unsub', sid: 's1' }));
+        const afterUnsub = calls;
+        await new Promise(resolve => setTimeout(resolve, 20));
+
+        expect(calls).toBe(afterUnsub);
+        transport.close();
+    });
+
+    test('a resource the index does not know is an error the client can show', async () => {
+        const transport = new PollingTransport('http://x', {}, { intervalMs: 10_000 });
+        const received: any[] = [];
+
+        transport.start({ onOpen: () => {}, onMessage: raw => received.push(JSON.parse(raw)), onClose: () => {} });
+        transport.send(JSON.stringify({
+            t: 'sub', sid: 's1', resource: 'Unknown.thing', inputs: { params: {}, query: {} }
+        }));
+
+        await new Promise(resolve => setTimeout(resolve, 10));
+
+        // Silence here would be a screen that stays pending forever with no
+        // explanation. Say what is missing and how to supply it.
+        expect(received[0]).toMatchObject({ t: 'error', sid: 's1', code: 'no_route' });
+        expect(received[0].message).toMatch(/routes/);
+        transport.close();
+    });
+});

package/test/transport.test.ts

@@ -0,0 +1,274 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { dropLiveConnection, handleMessage, LiveGateway } from '../src/transport/LiveGateway';
+import { SocketTransport } from '../src/transport/SocketTransport';
+import { ConnectionScopeResolver } from '../src/transport/scope-resolver';
+import { getLiveRuntime, resetLiveRuntime, setLiveRuntime } from '../src/runtime';
+import type { LiveScope } from '../src/shared/inputs';
+import type { ServerMessage } from '../src/shared/protocol';
+
+class FakeSocket {
+    sent: string[] = [];
+    result = 7;
+
+    constructor(public readonly id: string) {}
+
+    send(message: string): number {
+        this.sent.push(message);
+        return this.result;
+    }
+}
+
+const MESSAGE: ServerMessage = { t: 'stale', sid: 's1', reason: 'test' };
+
+describe('SocketTransport', () => {
+    test('serializes the message to the registered socket', () => {
+        const transport = new SocketTransport();
+        const socket = new FakeSocket('c1');
+        transport.add(socket as any);
+
+        expect(transport.send('c1', MESSAGE)).toBe(7);
+        expect(JSON.parse(socket.sent[0])).toEqual(MESSAGE as any);
+    });
+
+    test('reports a dropped send for an unknown connection', () => {
+        expect(new SocketTransport().send('ghost', MESSAGE)).toBe(0);
+    });
+
+    test('reports a dropped send when the socket throws', () => {
+        const transport = new SocketTransport();
+        transport.add({ id: 'c1', send: () => { throw new Error('closed'); } } as any);
+
+        expect(transport.send('c1', MESSAGE)).toBe(0);
+    });
+
+    test('remove stops delivery', () => {
+        const transport = new SocketTransport();
+        const socket = new FakeSocket('c1');
+        transport.add(socket as any);
+        transport.remove('c1');
+
+        expect(transport.send('c1', MESSAGE)).toBe(0);
+    });
+});
+
+describe('ConnectionScopeResolver', () => {
+    test('makes each connection its own principal, which shares nothing', async () => {
+        const resolver = new ConnectionScopeResolver();
+
+        expect(await resolver.resolve({ connectionId: 'c1' })).toEqual({ principal: 'c1' });
+        expect(await resolver.resolve({ connectionId: 'c2' })).toEqual({ principal: 'c2' });
+    });
+});
+
+describe('LiveGateway', () => {
+    afterEach(() => {
+        resetLiveRuntime();
+    });
+
+    test('a sub sent immediately after hello uses the resolved scope', async () => {
+        let releaseHello!: () => void;
+        const helloGate = new Promise<void>(resolve => {
+            releaseHello = resolve;
+        });
+
+        let releaseSub!: () => void;
+        const subSeen = new Promise<void>(resolve => {
+            releaseSub = resolve;
+        });
+
+        let usedScope: LiveScope | undefined;
+
+        setLiveRuntime({
+            engine: {
+                subscribe: async (_connectionId: string, _sid: string, _resource: string, _inputs: unknown, scope: LiveScope) => {
+                    usedScope = scope;
+                    releaseSub();
+                },
+                unsubscribe() {},
+                dropConnection() {},
+                resync: async () => {}
+            } as any,
+            transport: new SocketTransport(),
+            resolver: {
+                resolve: async () => {
+                    await helloGate;
+                    return { principal: 'user-1', tenant: 'acme' };
+                }
+            },
+            scopes: new Map(),
+            handshakes: new Set()
+        });
+
+        const gateway = new LiveGateway();
+        const socket = new FakeSocket('c1');
+        gateway.onOpen(socket as any);
+        gateway.onMessage(socket as any, JSON.stringify({ t: 'hello', v: 1, token: 't' }));
+        gateway.onMessage(
+            socket as any,
+            JSON.stringify({ t: 'sub', sid: 's1', resource: 'UsersController.list', inputs: { params: {}, query: {} } })
+        );
+
+        // Let both handlers start. Hello parks on the resolver; without
+        // per-connection ordering, sub would already have subscribed.
+        await new Promise(resolve => setTimeout(resolve, 0));
+        releaseHello();
+        await subSeen;
+
+        expect(usedScope).toEqual({ principal: 'user-1', tenant: 'acme' });
+        gateway.onClose(socket as any);
+    });
+
+    test('rejects a second hello without replacing the scope of existing bindings', async () => {
+        let resolverCalls = 0;
+        const usedScopes: LiveScope[] = [];
+
+        setLiveRuntime({
+            engine: {
+                subscribe: async (
+                    _connectionId: string,
+                    _sid: string,
+                    _resource: string,
+                    _inputs: unknown,
+                    scope: LiveScope
+                ) => {
+                    usedScopes.push(scope);
+                },
+                unsubscribe() {},
+                dropConnection() {},
+                resync: async () => {}
+            } as any,
+            transport: new SocketTransport(),
+            resolver: {
+                resolve: async ({ token }) => {
+                    resolverCalls++;
+                    return { principal: token ?? 'anonymous' };
+                }
+            },
+            scopes: new Map(),
+            handshakes: new Set()
+        });
+
+        const gateway = new LiveGateway();
+        const socket = new FakeSocket('c-repeat');
+        gateway.onOpen(socket as any);
+
+        await handleMessage('c-repeat', JSON.stringify({ t: 'hello', v: 1, token: 'first' }));
+        await handleMessage(
+            'c-repeat',
+            JSON.stringify({
+                t: 'sub',
+                sid: 's1',
+                resource: 'UsersController.list',
+                inputs: { params: {}, query: {} }
+            })
+        );
+        await handleMessage('c-repeat', JSON.stringify({ t: 'hello', v: 1, token: 'second' }));
+        await handleMessage(
+            'c-repeat',
+            JSON.stringify({
+                t: 'sub',
+                sid: 's2',
+                resource: 'UsersController.list',
+                inputs: { params: {}, query: {} }
+            })
+        );
+
+        expect(resolverCalls).toBe(1);
+        expect(getLiveRuntime().scopes.get('c-repeat')).toEqual({ principal: 'first' });
+        expect(usedScopes).toEqual([
+            { principal: 'first' },
+            { principal: 'first' }
+        ]);
+
+        gateway.onClose(socket as any);
+    });
+
+    test('close drops a queued sub so a slow hello cannot resurrect the connection', async () => {
+        let releaseHello!: () => void;
+        const helloGate = new Promise<void>(resolve => {
+            releaseHello = resolve;
+        });
+
+        let subscribed = false;
+
+        setLiveRuntime({
+            engine: {
+                subscribe: async () => {
+                    subscribed = true;
+                },
+                unsubscribe() {},
+                dropConnection() {},
+                resync: async () => {}
+            } as any,
+            transport: new SocketTransport(),
+            resolver: {
+                resolve: async () => {
+                    await helloGate;
+                    return { principal: 'user-1' };
+                }
+            },
+            scopes: new Map(),
+            handshakes: new Set()
+        });
+
+        const gateway = new LiveGateway();
+        const socket = new FakeSocket('c1');
+        gateway.onOpen(socket as any);
+        gateway.onMessage(socket as any, JSON.stringify({ t: 'hello', v: 1, token: 't' }));
+        gateway.onMessage(
+            socket as any,
+            JSON.stringify({ t: 'sub', sid: 's1', resource: 'UsersController.list', inputs: { params: {}, query: {} } })
+        );
+
+        await new Promise(resolve => setTimeout(resolve, 0));
+        gateway.onClose(socket as any);
+        releaseHello();
+        await new Promise(resolve => setTimeout(resolve, 0));
+
+        expect(subscribed).toBe(false);
+        expect(getLiveRuntime().scopes.has('c1')).toBe(false);
+    });
+
+    test('dropLiveConnection drops a queued sub, which is what SSE cancel uses', async () => {
+        let releaseHello!: () => void;
+        const helloGate = new Promise<void>(resolve => {
+            releaseHello = resolve;
+        });
+
+        let subscribed = false;
+
+        setLiveRuntime({
+            engine: {
+                subscribe: async () => {
+                    subscribed = true;
+                },
+                unsubscribe() {},
+                dropConnection() {},
+                resync: async () => {}
+            } as any,
+            transport: new SocketTransport(),
+            resolver: {
+                resolve: async () => {
+                    await helloGate;
+                    return { principal: 'user-1' };
+                }
+            },
+            scopes: new Map([['sse:1', { principal: 'sse:1' }]]),
+            handshakes: new Set()
+        });
+
+        void handleMessage('sse:1', JSON.stringify({ t: 'hello', v: 1, token: 't' }));
+        void handleMessage(
+            'sse:1',
+            JSON.stringify({ t: 'sub', sid: 's1', resource: 'UsersController.list', inputs: { params: {}, query: {} } })
+        );
+
+        await new Promise(resolve => setTimeout(resolve, 0));
+        dropLiveConnection('sse:1');
+        releaseHello();
+        await new Promise(resolve => setTimeout(resolve, 0));
+
+        expect(subscribed).toBe(false);
+        expect(getLiveRuntime().scopes.has('sse:1')).toBe(false);
+    });
+});

package/test/types/optimistic-types.ts

@@ -0,0 +1,34 @@
+import { useLive, useLiveAction } from '../../src/client/react';
+import type { LiveDescriptor } from '../../src/shared/descriptor';
+
+interface Card {
+    id: string;
+    title: string;
+}
+
+interface CreateCardDto {
+    title: string;
+}
+
+declare const list: LiveDescriptor<{ query: { status?: string }; response: Card[] }>;
+declare const create: (dto: CreateCardDto) => Promise<Card>;
+
+export function typeChecks(): void {
+    const state = useLive(list, { query: { status: 'open' } });
+
+    // `data` is Card[] | undefined, so this compiles and `title` is a string.
+    const first: string | undefined = state.data?.[0]?.title;
+    void first;
+
+    const send = useLiveAction(create, {
+        optimistic: [{
+            on: list,
+            apply: (draft, dto) => {
+                // `draft` is Card[] and `dto` is CreateCardDto, both inferred.
+                draft.push({ id: 'temp', title: dto.title });
+            }
+        }]
+    });
+
+    void send({ title: 'inferred' });
+}