@carno.js/live 1.8.0

package/test/shared.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+import { canonical, NonSerializableInputError } from '../src/shared/canonical';
+import { fnv1a64 } from '../src/shared/hash';
+
+describe('canonical', () => {
+    test('orders object keys so equal inputs produce equal strings', () => {
+        expect(canonical({ b: 1, a: 2 })).toBe(canonical({ a: 2, b: 1 }));
+        expect(canonical({ b: 1, a: 2 })).toBe('{"a":2,"b":1}');
+    });
+
+    test('preserves array order', () => {
+        expect(canonical([3, 1, 2])).toBe('[3,1,2]');
+    });
+
+    test('drops undefined properties but keeps null', () => {
+        expect(canonical({ a: undefined, b: null })).toBe('{"b":null}');
+    });
+
+    test('normalizes negative zero', () => {
+        expect(canonical(-0)).toBe(canonical(0));
+    });
+
+    test('rejects non-serializable inputs', () => {
+        expect(() => canonical(new Date())).toThrow(NonSerializableInputError);
+        expect(() => canonical({ a: () => 1 })).toThrow(NonSerializableInputError);
+        expect(() => canonical(Number.NaN)).toThrow(NonSerializableInputError);
+    });
+
+    test('reports the path of the offending value', () => {
+        try {
+            canonical({ filters: [{ since: new Date() }] });
+            throw new Error('should have thrown');
+        } catch (err) {
+            expect((err as NonSerializableInputError).path).toBe('$.filters[0].since');
+        }
+    });
+});
+
+describe('fnv1a64', () => {
+    test('is deterministic and 16 hex chars wide', () => {
+        const hash = fnv1a64('carno');
+        expect(hash).toMatch(/^[0-9a-f]{16}$/);
+        expect(fnv1a64('carno')).toBe(hash);
+    });
+
+    test('separates inputs that differ only by order', () => {
+        expect(fnv1a64('ab')).not.toBe(fnv1a64('ba'));
+    });
+
+    test('separates the empty string from a zero byte', () => {
+        expect(fnv1a64('')).not.toBe(fnv1a64(String.fromCharCode(0)));
+    });
+});

package/test/sse-routes.test.ts

@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Controller, Get } from '@carno.js/core';
+import { createTestHarness } from '../../core/dist/testing/TestHarness.js';
+import { Live } from '../src/decorators/Live';
+import { LivePlugin } from '../src/LivePlugin';
+import { closeLiveRuntime, getLiveRuntime } from '../src/runtime';
+
+// happy-dom (loaded by react-rerender.test.tsx) replaces global fetch with a
+// browser fetch that enforces CORS and buffers the body. These tests talk to
+// a real Bun.serve, so they use the native one captured before that register.
+const fetch =
+    (globalThis as { __carnoNativeFetch?: typeof globalThis.fetch }).__carnoNativeFetch
+    ?? globalThis.fetch;
+const NativeAbortController =
+    (globalThis as { __carnoNativeAbortController?: typeof AbortController }).__carnoNativeAbortController
+    ?? globalThis.AbortController;
+
+@Controller('/numbers')
+class NumbersController {
+    @Get('/')
+    @Live({ shared: 'public', dependsOn: ['app:numbers'] })
+    list() {
+        return [1, 2, 3];
+    }
+}
+
+/** Reads SSE frames off the response body, one `data:` payload at a time. */
+async function* frames(response: Response): AsyncGenerator<any> {
+    const reader = response.body!.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+        const { value, done } = await reader.read();
+
+        if (done) {
+            return;
+        }
+
+        buffer += decoder.decode(value, { stream: true });
+
+        let split = buffer.indexOf('\n\n');
+
+        while (split !== -1) {
+            const frame = buffer.slice(0, split);
+            buffer = buffer.slice(split + 2);
+
+            if (frame.startsWith('data: ')) {
+                yield JSON.parse(frame.slice(6));
+            }
+
+            split = buffer.indexOf('\n\n');
+        }
+    }
+}
+
+async function next(stream: AsyncGenerator<any>, predicate: (frame: any) => boolean, timeoutMs = 4000): Promise<any> {
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        const { value, done } = await stream.next();
+
+        if (done) {
+            throw new Error('the stream ended before the frame arrived');
+        }
+
+        if (predicate(value)) {
+            return value;
+        }
+    }
+
+    throw new Error('timed out waiting for a frame');
+}
+
+afterEach(async () => {
+    await closeLiveRuntime();
+});
+
+describe('SSE routes', () => {
+    test('a subscription over SSE receives a snapshot and then a patch', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({
+                controllers: [NumbersController],
+                sse: true,
+                config: { coalesceMs: 5, sseHeartbeatMs: 0 }
+            })],
+            listen: true
+        });
+
+        const response = await fetch(`http://127.0.0.1:${harness.port}/live/sse`);
+        expect(response.headers.get('content-type')).toContain('text/event-stream');
+
+        const stream = frames(response);
+        const ready = await next(stream, frame => frame.t === 'ready');
+        expect(typeof ready.cid).toBe('string');
+
+        const post = (message: unknown) => fetch(`http://127.0.0.1:${harness.port}/live/control`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ cid: ready.cid, message })
+        });
+
+        await post({ t: 'hello', v: 1 });
+        await post({ t: 'sub', sid: 's1', resource: 'NumbersController.list', inputs: { params: {}, query: {} } });
+
+        const snapshot = await next(stream, frame => frame.t === 'snapshot');
+        expect(snapshot.data).toEqual([1, 2, 3]);
+
+        await harness.close();
+    });
+
+    test('the control endpoint refuses an unknown connection id', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({ controllers: [NumbersController], sse: true })],
+            listen: true
+        });
+
+        const response = await fetch(`http://127.0.0.1:${harness.port}/live/control`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ cid: 'sse:not-a-real-one', message: { t: 'hello', v: 1 } })
+        });
+
+        // The cid is a bearer for a live connection. An unknown one is not a
+        // no-op to be swallowed; it is a request that must not be served.
+        expect(response.status).toBe(404);
+        await harness.close();
+    });
+
+    test('the control endpoint refuses a malformed body', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({ controllers: [NumbersController], sse: true })],
+            listen: true
+        });
+
+        const response = await fetch(`http://127.0.0.1:${harness.port}/live/control`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: 'not json'
+        });
+
+        expect(response.status).toBe(400);
+        await harness.close();
+    });
+
+    test('cancelling the stream drops the scope and refuses a late control message', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({
+                controllers: [NumbersController],
+                sse: true,
+                config: { sseHeartbeatMs: 0 }
+            })],
+            listen: true
+        });
+
+        const abort = new NativeAbortController();
+        const response = await fetch(`http://127.0.0.1:${harness.port}/live/sse`, { signal: abort.signal });
+        const reader = response.body!.getReader();
+        const ready = JSON.parse(
+            new TextDecoder().decode((await reader.read()).value).replace(/^data: /, '').trim()
+        );
+        expect(typeof ready.cid).toBe('string');
+
+        await fetch(`http://127.0.0.1:${harness.port}/live/control`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ cid: ready.cid, message: { t: 'hello', v: 1 } })
+        });
+        expect(getLiveRuntime().scopes.has(ready.cid)).toBe(true);
+
+        abort.abort();
+
+        const deadline = Date.now() + 1000;
+        while (getLiveRuntime().scopes.has(ready.cid) && Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 5));
+        }
+
+        expect(getLiveRuntime().scopes.has(ready.cid)).toBe(false);
+
+        const late = await fetch(`http://127.0.0.1:${harness.port}/live/control`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                cid: ready.cid,
+                message: { t: 'sub', sid: 's1', resource: 'NumbersController.list', inputs: { params: {}, query: {} } }
+            })
+        });
+        expect(late.status).toBe(404);
+
+        await harness.close();
+    });
+
+    test('no routes exist when sse is off', async () => {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({ controllers: [NumbersController] })],
+            listen: true
+        });
+
+        const response = await fetch(`http://127.0.0.1:${harness.port}/live/sse`);
+
+        expect(response.status).toBe(404);
+        await harness.close();
+    });
+});

package/test/sse-transport.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test';
+import { SseTransport } from '../src/transport/SseTransport';
+import type { ServerMessage } from '../src/shared/protocol';
+
+const SNAPSHOT: ServerMessage = { t: 'snapshot', sid: 's1', rev: 1, hash: 'h1', data: [{ id: 1 }] };
+
+async function readOne(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<string> {
+    const { value } = await reader.read();
+    return new TextDecoder().decode(value);
+}
+
+describe('SseTransport', () => {
+    test('open() hands back a stream, and owns() claims the connection', () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        const stream = transport.open('sse:1');
+
+        expect(stream).toBeInstanceOf(ReadableStream);
+        expect(transport.owns('sse:1')).toBe(true);
+        expect(transport.owns('sse:2')).toBe(false);
+    });
+
+    test('the first frame carries the connection id, because the client has no other way to learn it', async () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        const reader = transport.open('sse:1').getReader();
+
+        expect(await readOne(reader)).toBe('data: {"t":"ready","cid":"sse:1"}\n\n');
+    });
+
+    test('a message is written as one SSE frame of JSON', async () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        const reader = transport.open('sse:1').getReader();
+        await readOne(reader);
+
+        expect(transport.send('sse:1', SNAPSHOT)).toBe(1);
+        expect(await readOne(reader)).toBe(`data: ${JSON.stringify(SNAPSHOT)}\n\n`);
+    });
+
+    test('sending to a closed connection is a drop, not a throw', () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        transport.open('sse:1');
+        transport.close('sse:1');
+
+        expect(transport.send('sse:1', SNAPSHOT)).toBe(0);
+        expect(transport.owns('sse:1')).toBe(false);
+    });
+
+    test('refuses to open past the ceiling', () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 1 });
+        transport.open('sse:1');
+
+        expect(() => transport.open('sse:2')).toThrow(/at capacity/);
+    });
+
+    test('a heartbeat keeps the connection from being reaped by a proxy', async () => {
+        const transport = new SseTransport({ heartbeatMs: 5, maxConnections: 10 });
+        const reader = transport.open('sse:1').getReader();
+        await readOne(reader);
+
+        // A comment frame: valid SSE, ignored by EventSource, enough traffic
+        // to stop an idle-timeout proxy from closing the stream.
+        expect(await readOne(reader)).toBe(': ping\n\n');
+        transport.stop();
+    });
+
+    test('stop() closes every stream it holds', () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        transport.open('sse:1');
+        transport.open('sse:2');
+
+        transport.stop();
+
+        expect(transport.count()).toBe(0);
+    });
+
+    test('the client cancelling the stream releases the connection', async () => {
+        const transport = new SseTransport({ heartbeatMs: 0, maxConnections: 10 });
+        const dropped: string[] = [];
+        const withHook = new SseTransport({
+            heartbeatMs: 0,
+            maxConnections: 10,
+            onDisconnect: id => dropped.push(id)
+        });
+        void transport;
+
+        const stream = withHook.open('sse:1');
+        await stream.cancel();
+
+        expect(dropped).toEqual(['sse:1']);
+        expect(withHook.owns('sse:1')).toBe(false);
+    });
+});

package/test/statement-keys.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'bun:test';
+import type { Statement } from '@carno.js/orm';
+import { ancestorsOf, rowKey, tableKey } from '../src/graph/dep-key';
+import { normalizeColumns, readDependencies, writeEvents } from '../src/emitters/statement-keys';
+
+const MAX = 64;
+
+function select(overrides: Partial<Statement<any>>): Statement<any> {
+    return { statement: 'select', table: 'users', alias: 'u', primaryKeyColumnName: 'id', ...overrides };
+}
+
+describe('dep-key', () => {
+    test('builds table and row keys', () => {
+        expect(tableKey('users')).toBe('orm:users');
+        expect(rowKey('users', 42)).toBe('orm:users#42');
+    });
+
+    test('a row key has its table as ancestor', () => {
+        expect(ancestorsOf('orm:users#42')).toEqual(['orm:users#42', 'orm:users']);
+    });
+
+    test('a table key has only itself', () => {
+        expect(ancestorsOf('orm:users')).toEqual(['orm:users']);
+    });
+
+    test('an arbitrary app key is not split on colons', () => {
+        expect(ancestorsOf('app:report:2026-08')).toEqual(['app:report:2026-08']);
+    });
+});
+
+describe('normalizeColumns', () => {
+    test('strips alias, quotes and the AS clause the ORM generates', () => {
+        expect(normalizeColumns(['u."name" as "u_name"', 'u."id" as "u_id"'])).toEqual(['id', 'name']);
+    });
+
+    test('treats a star select as wildcard', () => {
+        expect(normalizeColumns(['*'])).toBeNull();
+        expect(normalizeColumns(undefined)).toBeNull();
+    });
+});
+
+describe('readDependencies', () => {
+    test('a primary-key lookup depends on the row', () => {
+        const deps = readDependencies(select({ where: 'u."id" = 42', columns: ['u."name" as "u_name"'] }), MAX);
+        expect(deps).toEqual([{ key: 'orm:users#42', columns: ['name'] }]);
+    });
+
+    test('a filtered list depends on the table', () => {
+        const deps = readDependencies(select({ where: "u.\"status\" = 'active'", columns: ['u."id" as "u_id"'] }), MAX);
+        expect(deps).toEqual([{ key: 'orm:users', columns: ['id'] }]);
+    });
+
+    test('an IN list produces one row key per id', () => {
+        const deps = readDependencies(select({ where: 'u."id" IN (1, 2, 3)' }), MAX);
+        expect(deps.map(d => d.key)).toEqual(['orm:users#1', 'orm:users#2', 'orm:users#3']);
+    });
+
+    test('collapses to the table when the IN list exceeds maxKeysPerRead', () => {
+        const ids = Array.from({ length: 5 }, (_, i) => i + 1).join(', ');
+        const deps = readDependencies(select({ where: `u."id" IN (${ids})` }), 4);
+        expect(deps.map(d => d.key)).toEqual(['orm:users']);
+    });
+
+    test('a join adds the joined table as its own dependency', () => {
+        const statement = select({
+            where: 'u."id" = 7',
+            join: [{ joinTable: 'orders', joinAlias: 'o', type: 'INNER', on: 'o.user_id = u.id' } as any]
+        });
+        expect(readDependencies(statement, MAX).map(d => d.key)).toEqual(['orm:users#7', 'orm:orders']);
+    });
+
+    test('a select-strategy join adds every child table as a dependency', () => {
+        const statement = select({
+            where: 'u."id" = 7',
+            selectJoin: [{
+                statement: 'select',
+                table: '"public"."orders"',
+                alias: 'o',
+                columns: ['o."id"'],
+                where: 'o.user_id IN (7)'
+            }]
+        });
+
+        expect(readDependencies(statement, MAX).map(d => d.key)).toEqual(['orm:users#7', 'orm:orders']);
+    });
+
+    test('normalizes a qualified ORM table name', () => {
+        expect(readDependencies(select({ table: '"public"."users"' }), MAX)[0].key).toBe('orm:users');
+    });
+
+    test('ignores write statements', () => {
+        expect(readDependencies(select({ statement: 'update', values: { name: 'x' } }), MAX)).toEqual([]);
+    });
+});
+
+describe('writeEvents', () => {
+    test('an update by id emits the row key carrying the written columns', () => {
+        const statement = select({ statement: 'update', where: 'u."id" = 42', values: { name: 'Ada' } });
+        expect(writeEvents(statement, MAX)).toEqual([{ key: 'orm:users#42', columns: ['name'] }]);
+    });
+
+    test('an update by predicate emits the table key', () => {
+        const statement = select({ statement: 'update', where: "u.\"created_at\" < '2020-01-01'", values: { archived: true } });
+        expect(writeEvents(statement, MAX)).toEqual([{ key: 'orm:users', columns: ['archived'] }]);
+    });
+
+    test('a delete emits a wildcard because the whole row is gone', () => {
+        const statement = select({ statement: 'delete', where: 'u."id" = 9' });
+        expect(writeEvents(statement, MAX)).toEqual([{ key: 'orm:users#9', columns: null }]);
+    });
+
+    test('an insert emits the row key so table subscribers wake through the ancestor', () => {
+        const statement = select({ statement: 'insert', values: { id: 5, name: 'Ada' } });
+        expect(writeEvents(statement, MAX)).toEqual([{ key: 'orm:users#5', columns: ['id', 'name'] }]);
+    });
+
+    test('an insert without a primary key falls back to the table', () => {
+        const statement = select({ statement: 'insert', values: { name: 'Ada' } });
+        expect(writeEvents(statement, MAX)).toEqual([{ key: 'orm:users', columns: ['name'] }]);
+    });
+
+    test('a bulk insert emits one key per row', () => {
+        const statement = select({ statement: 'insert', bulk: true, values: [{ id: 1 }, { id: 2 }] });
+        expect(writeEvents(statement, MAX).map(e => e.key)).toEqual(['orm:users#1', 'orm:users#2']);
+    });
+});

package/test/subscription-registry.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+import { SubscriptionRegistry } from '../src/graph/SubscriptionRegistry';
+
+describe('SubscriptionRegistry', () => {
+    test('tracks one connection subscribing once', () => {
+        const registry = new SubscriptionRegistry();
+
+        expect(registry.subscribe('c1', 'i1')).toBe(1);
+        expect(registry.connectionsOf('i1')).toEqual(['c1']);
+        expect(registry.instanceCount()).toBe(1);
+    });
+
+    test('refcounts repeated subscriptions from the same connection', () => {
+        const registry = new SubscriptionRegistry();
+        registry.subscribe('c1', 'i1');
+
+        expect(registry.subscribe('c1', 'i1')).toBe(2);
+        expect(registry.connectionsOf('i1')).toEqual(['c1']);
+        expect(registry.unsubscribe('c1', 'i1')).toBe(1);
+        expect(registry.hasSubscribers('i1')).toBe(true);
+        expect(registry.unsubscribe('c1', 'i1')).toBe(0);
+        expect(registry.hasSubscribers('i1')).toBe(false);
+    });
+
+    test('two connections share one instance', () => {
+        const registry = new SubscriptionRegistry();
+        registry.subscribe('c1', 'i1');
+        registry.subscribe('c2', 'i1');
+
+        expect(registry.connectionsOf('i1').sort()).toEqual(['c1', 'c2']);
+        registry.unsubscribe('c1', 'i1');
+        expect(registry.hasSubscribers('i1')).toBe(true);
+    });
+
+    test('counts distinct instances per connection for the per-connection ceiling', () => {
+        const registry = new SubscriptionRegistry();
+        registry.subscribe('c1', 'i1');
+        registry.subscribe('c1', 'i1');
+        registry.subscribe('c1', 'i2');
+
+        expect(registry.countForConnection('c1')).toBe(2);
+    });
+
+    test('dropping a connection returns the instances left with no subscriber', () => {
+        const registry = new SubscriptionRegistry();
+        registry.subscribe('c1', 'i1');
+        registry.subscribe('c1', 'i2');
+        registry.subscribe('c2', 'i2');
+
+        expect(registry.dropConnection('c1').sort()).toEqual(['i1']);
+        expect(registry.hasSubscribers('i2')).toBe(true);
+        expect(registry.countForConnection('c1')).toBe(0);
+    });
+
+    test('unsubscribing something never subscribed is a no-op', () => {
+        const registry = new SubscriptionRegistry();
+
+        expect(registry.unsubscribe('c1', 'i1')).toBe(0);
+        expect(registry.dropConnection('nope')).toEqual([]);
+    });
+});