@carno.js/live 1.8.0

package/test/dependency-graph.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+import { DependencyGraph } from '../src/graph/DependencyGraph';
+
+describe('DependencyGraph', () => {
+    test('resolves an instance that depends on the exact key', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i1', [{ key: 'orm:users#42', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users#42', columns: null })).toEqual(['i1']);
+    });
+
+    test('a row write wakes the table subscriber through the ancestor', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('list', [{ key: 'orm:users', columns: null }]);
+        graph.setDependencies('detail', [{ key: 'orm:users#42', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users#42', columns: null }).sort()).toEqual(['detail', 'list']);
+    });
+
+    test('a table write wakes row subscribers because it may touch any row', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('detail', [{ key: 'orm:users#42', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual(['detail']);
+    });
+
+    test('does not wake a row subscriber for a different row', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('detail', [{ key: 'orm:users#42', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users#7', columns: null })).toEqual([]);
+    });
+
+    test('skips an instance whose read columns do not intersect the write', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i1', [{ key: 'orm:users', columns: ['id', 'name'] }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: ['last_seen_at'] })).toEqual([]);
+        expect(graph.resolve({ key: 'orm:users', columns: ['name'] })).toEqual(['i1']);
+    });
+
+    test('a wildcard on either side always intersects', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('narrow', [{ key: 'orm:users', columns: ['id'] }]);
+        graph.setDependencies('wide', [{ key: 'orm:users', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: null }).sort()).toEqual(['narrow', 'wide']);
+        expect(graph.resolve({ key: 'orm:users', columns: ['zzz'] })).toEqual(['wide']);
+    });
+
+    test('returns each instance once even when several keys match', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i1', [
+            { key: 'orm:users', columns: null },
+            { key: 'orm:users#42', columns: null }
+        ]);
+
+        expect(graph.resolve({ key: 'orm:users#42', columns: null })).toEqual(['i1']);
+    });
+
+    test('replacing dependencies drops the previous ones', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i1', [{ key: 'orm:users', columns: null }]);
+        graph.setDependencies('i1', [{ key: 'orm:orders', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual([]);
+        expect(graph.resolve({ key: 'orm:orders', columns: null })).toEqual(['i1']);
+        expect(graph.keyCount()).toBe(1);
+    });
+
+    test('remove clears every key the instance held', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i1', [
+            { key: 'orm:users', columns: null },
+            { key: 'orm:orders', columns: null }
+        ]);
+        graph.remove('i1');
+
+        expect(graph.keyCount()).toBe(0);
+        expect(graph.instanceCount()).toBe(0);
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual([]);
+    });
+});

package/test/etag.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, test } from 'bun:test';
+import { Context, Controller, Get, Post } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+import { LiveETagMiddleware, pathMatcher } from '../src/http/etag';
+import { ResourceRegistry } from '../src/resource/ResourceRegistry';
+import { directResourceExecutor } from './resource-registry-helper';
+
+const LIVE_PATHS = [
+    { method: 'GET', path: '/cards' },
+    { method: 'GET', path: '/cards/:id' },
+    { method: 'POST', path: '/cards/search' }
+];
+
+function contextFor(url: string, headers: Record<string, string> = {}, method = 'GET'): Context {
+    return new Context(new Request(url, { method, headers }));
+}
+
+function jsonResponse(body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+    });
+}
+
+describe('pathMatcher', () => {
+    test('a :param matches exactly one segment', () => {
+        const matcher = pathMatcher('/cards/:id');
+
+        expect(matcher.test('/cards/42')).toBe(true);
+        expect(matcher.test('/cards')).toBe(false);
+        expect(matcher.test('/cards/42/comments')).toBe(false);
+    });
+
+    test('a literal path matches only itself', () => {
+        const matcher = pathMatcher('/cards');
+
+        expect(matcher.test('/cards')).toBe(true);
+        expect(matcher.test('/cardsx')).toBe(false);
+    });
+});
+
+describe('LiveETagMiddleware', () => {
+    test('adds an ETag to a live GET', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(contextFor('http://x/cards'), async () =>
+            jsonResponse([{ id: 1 }])
+        );
+
+        expect((response as Response).headers.get('ETag')).toMatch(/^"[0-9a-f]+"$/);
+    });
+
+    test('answers 304 with no body when If-None-Match matches', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const first = await middleware.handle(contextFor('http://x/cards'), async () =>
+            jsonResponse([{ id: 1 }])
+        ) as Response;
+        const tag = first.headers.get('ETag')!;
+
+        const second = await middleware.handle(
+            contextFor('http://x/cards', { 'If-None-Match': tag }),
+            async () => jsonResponse([{ id: 1 }])
+        ) as Response;
+
+        expect(second.status).toBe(304);
+        expect(await second.text()).toBe('');
+        expect(second.headers.get('ETag')).toBe(tag);
+    });
+
+    test('answers 200 when the content changed', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const first = await middleware.handle(contextFor('http://x/cards'), async () =>
+            jsonResponse([{ id: 1 }])
+        ) as Response;
+
+        const second = await middleware.handle(
+            contextFor('http://x/cards', { 'If-None-Match': first.headers.get('ETag')! }),
+            async () => jsonResponse([{ id: 1 }, { id: 2 }])
+        ) as Response;
+
+        expect(second.status).toBe(200);
+        expect(await second.json()).toEqual([{ id: 1 }, { id: 2 }]);
+    });
+
+    test('the hash is of the canonical content, not of the byte order', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const ordered = await middleware.handle(contextFor('http://x/cards'), async () =>
+            jsonResponse({ a: 1, b: 2 })
+        ) as Response;
+
+        const reordered = await middleware.handle(
+            contextFor('http://x/cards', { 'If-None-Match': ordered.headers.get('ETag')! }),
+            async () => jsonResponse({ b: 2, a: 1 })
+        ) as Response;
+
+        // Same content, different key order. A byte hash would send it again.
+        expect(reordered.status).toBe(304);
+    });
+
+    test('a path that is not live is left alone', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(contextFor('http://x/health'), async () =>
+            jsonResponse({ ok: true })
+        ) as Response;
+
+        expect(response.headers.get('ETag')).toBeNull();
+    });
+
+    test('a live POST is left alone', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(
+            contextFor('http://x/cards/search', {}, 'POST'),
+            async () => jsonResponse([])
+        ) as Response;
+
+        // POST is not cacheable, and conditional polling on it means nothing.
+        expect(response.headers.get('ETag')).toBeNull();
+    });
+
+    test('rejects a polling request without its resource id', async () => {
+        let downstream = false;
+        const middleware = new LiveETagMiddleware([
+            { method: 'GET', path: '/cards', resourceId: 'CardsController.list' }
+        ]);
+        middleware.setPollingGuard(() => ({ principal: 'ada' }));
+
+        const response = await middleware.handle(
+            contextFor('http://x/cards', { 'X-Carno-Live-Poll': '1' }),
+            async () => {
+                downstream = true;
+                return jsonResponse([]);
+            }
+        ) as Response;
+
+        expect(response.status).toBe(403);
+        expect(downstream).toBe(false);
+    });
+
+    test('a non-200 is left alone', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(contextFor('http://x/cards'), async () =>
+            new Response('nope', { status: 500 })
+        ) as Response;
+
+        expect(response.headers.get('ETag')).toBeNull();
+    });
+
+    test('a non-JSON body is left alone', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(contextFor('http://x/cards'), async () =>
+            new Response('<html></html>', { status: 200, headers: { 'Content-Type': 'text/html' } })
+        ) as Response;
+
+        expect(response.headers.get('ETag')).toBeNull();
+    });
+
+    test('the downstream response is still readable by the caller', async () => {
+        const middleware = new LiveETagMiddleware(LIVE_PATHS);
+        const response = await middleware.handle(contextFor('http://x/cards'), async () =>
+            jsonResponse([{ id: 7 }])
+        ) as Response;
+
+        // Hashing consumed the body once; the caller has to get a fresh one.
+        expect(await response.json()).toEqual([{ id: 7 }]);
+    });
+});
+
+describe('ResourceRegistry.livePaths', () => {
+    test('joins the controller prefix with the handler path', () => {
+        @Controller('/cards')
+        class CardsController {
+            @Get('/')
+            @Live({ shared: 'public' })
+            list() { return []; }
+
+            @Get('/:id')
+            @Live({ shared: 'public' })
+            one() { return {}; }
+
+            @Post('/search')
+            @Live({ shared: 'public' })
+            search() { return []; }
+        }
+
+        const registry = new ResourceRegistry();
+        registry.register(CardsController, new CardsController(), directResourceExecutor);
+
+        expect(registry.livePaths().sort((a, b) => a.path.localeCompare(b.path))).toEqual([
+            { method: 'GET', path: '/cards', resourceId: 'CardsController.list' },
+            { method: 'GET', path: '/cards/:id', resourceId: 'CardsController.one' },
+            { method: 'POST', path: '/cards/search', resourceId: 'CardsController.search' }
+        ]);
+    });
+});

package/test/fan-transport.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import { FanTransport, type OwnedTransport } from '../src/transport/FanTransport';
+import type { ServerMessage } from '../src/shared/protocol';
+
+function child(prefix: string): OwnedTransport & { sent: { id: string; message: ServerMessage }[] } {
+    const sent: { id: string; message: ServerMessage }[] = [];
+
+    return {
+        sent,
+        owns: (connectionId: string) => connectionId.startsWith(prefix),
+        send(connectionId: string, message: ServerMessage) {
+            sent.push({ id: connectionId, message });
+            return 1;
+        }
+    };
+}
+
+const HELLO: ServerMessage = { t: 'current', sid: 's1', rev: 1, hash: 'h' };
+
+describe('FanTransport', () => {
+    test('delivers to the child that owns the connection', () => {
+        const sockets = child('ws:');
+        const streams = child('sse:');
+        const fan = new FanTransport();
+        fan.add(sockets);
+        fan.add(streams);
+
+        fan.send('sse:abc', HELLO);
+
+        expect(streams.sent.length).toBe(1);
+        expect(sockets.sent.length).toBe(0);
+    });
+
+    test('an unowned connection is a dropped send, not a throw', () => {
+        const fan = new FanTransport();
+        fan.add(child('ws:'));
+
+        // The engine treats <= 0 as back-pressure or drop, and cleans up on
+        // its own schedule. Throwing here would take a whole fan-out down.
+        expect(fan.send('sse:gone', HELLO)).toBe(0);
+    });
+
+    test('the first owner wins, so a stale child cannot shadow a live one', () => {
+        const first = child('c');
+        const second = child('c');
+        const fan = new FanTransport();
+        fan.add(first);
+        fan.add(second);
+
+        fan.send('c1', HELLO);
+
+        expect(first.sent.length).toBe(1);
+        expect(second.sent.length).toBe(0);
+    });
+
+    test('reports back-pressure from the child verbatim', () => {
+        const fan = new FanTransport();
+        fan.add({ owns: () => true, send: () => -1 });
+
+        expect(fan.send('anything', HELLO)).toBe(-1);
+    });
+});

package/test/happydom.ts

@@ -0,0 +1,24 @@
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+import { afterAll } from 'bun:test';
+
+/**
+ * Native fetch, captured before happy-dom replaces it.
+ *
+ * HTTP tests that talk to a real Bun.serve (SSE streams, CORS-free POSTs)
+ * must use this: happy-dom's fetch enforces same-origin and buffers the body.
+ */
+(globalThis as { __carnoNativeFetch?: typeof fetch }).__carnoNativeFetch = globalThis.fetch;
+(globalThis as { __carnoNativeAbortController?: typeof AbortController }).__carnoNativeAbortController =
+    globalThis.AbortController;
+
+if (!(globalThis as { document?: unknown }).document) {
+    GlobalRegistrator.register();
+}
+
+// Do not leak happy-dom's Response/Request constructors into later tests
+// that start a real Bun.serve instance.
+afterAll(() => {
+    if ((globalThis as { document?: unknown }).document) {
+        GlobalRegistrator.unregister();
+    }
+});

package/test/inputs-body.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'bun:test';
+import { DEFAULT_LIVE_CONFIG } from '../src/config';
+import { canonicalInputs, instanceIdOf } from '../src/resource/instance-id';
+import { LiveClient, storeKey, type LiveSocket } from '../src/client/core';
+
+const LIMIT = DEFAULT_LIVE_CONFIG.maxInputBytes;
+
+describe('body as part of the instance identity', () => {
+    test('the same body written in a different key order is the same input', () => {
+        const first = canonicalInputs(
+            { params: {}, query: {}, body: { status: 'active', page: 2 } },
+            LIMIT
+        );
+        const second = canonicalInputs(
+            { params: {}, query: {}, body: { page: 2, status: 'active' } },
+            LIMIT
+        );
+
+        expect(first).toBe(second);
+    });
+
+    test('a different body is a different instance', () => {
+        const active = instanceIdOf(
+            'ReportsController.run',
+            'pub',
+            canonicalInputs({ params: {}, query: {}, body: { status: 'active' } }, LIMIT)
+        );
+        const archived = instanceIdOf(
+            'ReportsController.run',
+            'pub',
+            canonicalInputs({ params: {}, query: {}, body: { status: 'archived' } }, LIMIT)
+        );
+
+        expect(active).not.toBe(archived);
+    });
+
+    test('an absent body and an empty body are the same instance', () => {
+        const absent = canonicalInputs({ params: {}, query: {} }, LIMIT);
+        const explicitNull = canonicalInputs({ params: {}, query: {}, body: null }, LIMIT);
+
+        expect(absent).toBe(explicitNull);
+    });
+
+    test('an oversized body is refused before it becomes an instance', () => {
+        expect(() =>
+            canonicalInputs({ params: {}, query: {}, body: { blob: 'x'.repeat(LIMIT) } }, LIMIT)
+        ).toThrow(/over the 8192 byte limit/);
+    });
+
+    test('a body that cannot be canonicalized is refused', () => {
+        expect(() =>
+            canonicalInputs({ params: {}, query: {}, body: { when: new Date() } }, LIMIT)
+        ).toThrow(/not serializable/);
+    });
+});
+
+describe('client store identity', () => {
+    class FakeSocket implements LiveSocket {
+        onopen: (() => void) | null = null;
+        onmessage: ((event: { data: string }) => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: ((error: unknown) => void) | null = null;
+        send(): void {}
+        close(): void {}
+    }
+
+    test('storeKey separates two bodies', () => {
+        const one = storeKey('R.run', { params: {}, query: {}, body: { page: 1 } });
+        const two = storeKey('R.run', { params: {}, query: {}, body: { page: 2 } });
+
+        expect(one).not.toBe(two);
+    });
+
+    test('the same body reuses the same store', () => {
+        const client = new LiveClient({ url: 'ws://test/live', socketFactory: () => new FakeSocket() });
+        const first = client.store('R.run', { params: {}, query: {}, body: { page: 1 } });
+        const second = client.store('R.run', { params: {}, query: {}, body: { page: 1 } });
+
+        expect(first).toBe(second);
+    });
+});

package/test/instance-id.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from 'bun:test';
+import { Controller, Get } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+import { LIVE_META, type LiveMeta } from '../src/metadata';
+import {
+    canonicalInputs,
+    InputTooLargeError,
+    instanceIdOf,
+    MissingScopeError,
+    scopeKeyOf
+} from '../src/resource/instance-id';
+
+@Controller('/users')
+class UsersController {
+    @Get('/')
+    @Live({ key: 'id' })
+    list() {
+        return [];
+    }
+
+    @Get('/:id')
+    @Live({ shared: 'tenant' })
+    get() {
+        return {};
+    }
+
+    @Get('/stats')
+    plain() {
+        return {};
+    }
+}
+
+function metaOf(handler: string): LiveMeta | undefined {
+    return Reflect.getMetadata(LIVE_META, UsersController, handler);
+}
+
+describe('@Live', () => {
+    test('defaults to private scope and records the handler name', () => {
+        expect(metaOf('list')).toEqual({ key: 'id', shared: 'private', dependsOn: [], handlerName: 'list' });
+    });
+
+    test('carries an explicit shared scope', () => {
+        expect(metaOf('get')?.shared).toBe('tenant');
+    });
+
+    test('leaves undecorated handlers alone', () => {
+        expect(metaOf('plain')).toBeUndefined();
+    });
+});
+
+describe('scopeKeyOf', () => {
+    test('public collapses to a single shared bucket', () => {
+        expect(scopeKeyOf('public', {})).toBe('pub');
+    });
+
+    test('tenant and principal are embedded literally, never hashed', () => {
+        expect(scopeKeyOf('tenant', { tenant: 'acme' })).toBe('t:acme');
+        expect(scopeKeyOf('private', { principal: 42 })).toBe('p:42');
+    });
+
+    test('encodes separators so two tenants cannot forge each other keys', () => {
+        expect(scopeKeyOf('tenant', { tenant: 'a|b' })).toBe('t:a%7Cb');
+    });
+
+    test('refuses a scope it cannot resolve rather than falling back', () => {
+        expect(() => scopeKeyOf('tenant', {})).toThrow(MissingScopeError);
+        expect(() => scopeKeyOf('private', {})).toThrow(MissingScopeError);
+    });
+});
+
+describe('instanceIdOf', () => {
+    const inputs = { params: {}, query: { status: 'active' } };
+
+    test('is stable for the same resource, scope and inputs', () => {
+        const a = instanceIdOf('UsersController.list', 'pub', canonicalInputs(inputs, 8192));
+        const b = instanceIdOf('UsersController.list', 'pub', canonicalInputs({ query: { status: 'active' }, params: {} }, 8192));
+
+        expect(a).toBe(b);
+    });
+
+    test('two tenants never share an instance', () => {
+        const canonical = canonicalInputs(inputs, 8192);
+        const a = instanceIdOf('UsersController.list', scopeKeyOf('tenant', { tenant: 'acme' }), canonical);
+        const b = instanceIdOf('UsersController.list', scopeKeyOf('tenant', { tenant: 'globex' }), canonical);
+
+        expect(a).not.toBe(b);
+        expect(a.startsWith('UsersController.list|t:acme|')).toBe(true);
+    });
+
+    test('different inputs produce different instances', () => {
+        const a = instanceIdOf('r', 'pub', canonicalInputs({ params: {}, query: { s: 'a' } }, 8192));
+        const b = instanceIdOf('r', 'pub', canonicalInputs({ params: {}, query: { s: 'b' } }, 8192));
+
+        expect(a).not.toBe(b);
+    });
+});
+
+describe('canonicalInputs', () => {
+    test('rejects inputs above the ceiling', () => {
+        const inputs = { params: {}, query: { q: 'x'.repeat(9000) } };
+
+        expect(() => canonicalInputs(inputs, 8192)).toThrow(InputTooLargeError);
+    });
+});