@carno.js/live 1.8.0 → 1.8.1

package/test/dependency-graph-index.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from 'bun:test';
+import { DependencyGraph } from '../src/graph/DependencyGraph';
+import type { Dependency, InvalidationEvent } from '../src/graph/types';
+
+/**
+ * `resolve` used to answer a table event by scanning every key in the graph
+ * with `startsWith`. The scan was replaced by an index, and an index can be
+ * wrong in two ways the old code could not: a missed insert silently drops an
+ * invalidation, and a missed delete silently leaks memory. Both are checked
+ * here against a model of the graph kept outside it.
+ */
+class Model {
+    private readonly deps = new Map<string, Dependency[]>();
+
+    set(instanceId: string, deps: Dependency[]): void {
+        if (deps.length === 0) {
+            this.deps.delete(instanceId);
+            return;
+        }
+
+        this.deps.set(instanceId, deps);
+    }
+
+    remove(instanceId: string): void {
+        this.deps.delete(instanceId);
+    }
+
+    /** The same answer, worked out by the rule rather than by an index. */
+    resolve(event: InvalidationEvent): string[] {
+        const separator = event.key.indexOf('#');
+        const table = separator === -1 ? null : event.key.slice(0, separator);
+        const descendantPrefix = `${event.key}#`;
+        const matched: string[] = [];
+
+        for (const [instanceId, deps] of this.deps) {
+            for (const key of new Set(deps.map(dep => dep.key))) {
+                const concerned = key === event.key
+                    || key === table
+                    || (separator === -1 && key.startsWith(descendantPrefix));
+
+                if (concerned && intersects(columnsFor(deps, key), event.columns)) {
+                    matched.push(instanceId);
+                    break;
+                }
+            }
+        }
+
+        return matched;
+    }
+}
+
+/** Mirrors how setDependencies merges repeated deps: null wins, else union. */
+function columnsFor(deps: Dependency[], key: string): string[] | null {
+    const union = new Set<string>();
+
+    for (const dep of deps) {
+        if (dep.key !== key) {
+            continue;
+        }
+
+        if (dep.columns === null) {
+            return null;
+        }
+
+        for (const column of dep.columns) {
+            union.add(column);
+        }
+    }
+
+    return [...union];
+}
+
+function intersects(read: string[] | null, written: string[] | null): boolean {
+    if (read === null || written === null) {
+        return true;
+    }
+
+    return written.some(column => read.includes(column));
+}
+
+function agree(graph: DependencyGraph, model: Model, event: InvalidationEvent): void {
+    expect(graph.resolve(event).sort()).toEqual(model.resolve(event).sort());
+}
+
+/** Deterministic PRNG, so a failure is reproducible from its seed alone. */
+function rng(seed: number): () => number {
+    let state = seed >>> 0;
+
+    return () => {
+        state = (state * 1664525 + 1013904223) >>> 0;
+        return state / 0x100000000;
+    };
+}
+
+const TABLES = ['orm:users', 'orm:tasks', 'orm:user', 'app:poc:tasks'];
+const COLUMNS = [null, ['id'], ['id', 'name'], ['name'], ['last_seen_at']];
+
+describe('the table-event index answers exactly what the scan answered', () => {
+    test('on a table whose name is a prefix of another', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('user-row', [{ key: 'orm:user#1', columns: null }]);
+        graph.setDependencies('users-row', [{ key: 'orm:users#1', columns: null }]);
+
+        // `orm:users#1`.startsWith('orm:user#') is false, and the index must
+        // agree: the parent of that key is `orm:users`, not `orm:user`.
+        expect(graph.resolve({ key: 'orm:user', columns: null })).toEqual(['user-row']);
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual(['users-row']);
+    });
+
+    test('on a row id that itself contains the separator', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('odd', [{ key: 'orm:users#4#2', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual(['odd']);
+        expect(graph.resolve({ key: 'orm:users#4', columns: null })).toEqual([]);
+    });
+
+    test('on a manual dependsOn key outside the orm namespace', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('scoped', [{ key: 'app:poc:tasks#7', columns: null }]);
+
+        expect(graph.resolve({ key: 'app:poc:tasks', columns: null })).toEqual(['scoped']);
+    });
+
+    test('still filters by column on the descendants it now finds by index', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('detail', [{ key: 'orm:users#42', columns: ['id', 'name'] }]);
+
+        expect(graph.resolve({ key: 'orm:users', columns: ['last_seen_at'] })).toEqual([]);
+        expect(graph.resolve({ key: 'orm:users', columns: ['name'] })).toEqual(['detail']);
+    });
+
+    test('drops a row from the table event once its last holder is gone', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('a', [{ key: 'orm:users#42', columns: null }]);
+        graph.setDependencies('b', [{ key: 'orm:users#42', columns: null }]);
+
+        graph.remove('a');
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual(['b']);
+
+        graph.remove('b');
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual([]);
+    });
+
+    test('follows an instance that moves from one row to another', () => {
+        const graph = new DependencyGraph();
+        graph.setDependencies('i', [{ key: 'orm:users#1', columns: null }]);
+        graph.setDependencies('i', [{ key: 'orm:users#2', columns: null }]);
+
+        expect(graph.resolve({ key: 'orm:users#1', columns: null })).toEqual([]);
+        expect(graph.resolve({ key: 'orm:users#2', columns: null })).toEqual(['i']);
+        expect(graph.resolve({ key: 'orm:users', columns: null })).toEqual(['i']);
+    });
+
+    test('under 3000 random writes and removals across 6 seeds', () => {
+        for (let seed = 1; seed <= 6; seed++) {
+            const next = rng(seed * 7919);
+            const graph = new DependencyGraph();
+            const model = new Model();
+            const live: string[] = [];
+
+            for (let step = 0; step < 500; step++) {
+                const instanceId = `i${Math.floor(next() * 40)}`;
+
+                if (live.includes(instanceId) && next() < 0.3) {
+                    graph.remove(instanceId);
+                    model.remove(instanceId);
+                    live.splice(live.indexOf(instanceId), 1);
+                } else {
+                    const deps: Dependency[] = [];
+                    const count = 1 + Math.floor(next() * 3);
+
+                    for (let d = 0; d < count; d++) {
+                        const table = TABLES[Math.floor(next() * TABLES.length)];
+                        const row = next() < 0.7 ? `#${Math.floor(next() * 12)}` : '';
+                        deps.push({
+                            key: `${table}${row}`,
+                            columns: COLUMNS[Math.floor(next() * COLUMNS.length)]
+                        });
+                    }
+
+                    graph.setDependencies(instanceId, deps);
+                    model.set(instanceId, deps);
+                    if (!live.includes(instanceId)) {
+                        live.push(instanceId);
+                    }
+                }
+
+                for (const table of TABLES) {
+                    agree(graph, model, { key: table, columns: null });
+                    agree(graph, model, { key: table, columns: ['name'] });
+                    agree(graph, model, { key: `${table}#${Math.floor(next() * 12)}`, columns: null });
+                }
+            }
+
+            // Every instance removed must leave the graph empty, index included.
+            for (const instanceId of [...live]) {
+                graph.remove(instanceId);
+            }
+
+            expect(graph.instanceCount()).toBe(0);
+            expect(graph.keyCount()).toBe(0);
+            expect(graph.parentCount()).toBe(0);
+        }
+    });
+});

package/test/recompute-concurrency.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from 'bun:test';
+import { Controller, Get, Query } from '@carno.js/core';
+import { InProcessBus } from '../src/bus/InProcessBus';
+import { resolveLiveConfig } from '../src/config';
+import { Live } from '../src/decorators/Live';
+import { DependencyGraph } from '../src/graph/DependencyGraph';
+import { SubscriptionRegistry } from '../src/graph/SubscriptionRegistry';
+import { LiveEngine, type LiveTransport } from '../src/LiveEngine';
+import { dependencyContext } from '../src/resource/dependency-context';
+import { ResourceRegistry } from '../src/resource/ResourceRegistry';
+import type { ServerMessage } from '../src/shared/protocol';
+import { directResourceExecutor } from './resource-registry-helper';
+
+/**
+ * Watches how many computes are in flight at once.
+ *
+ * Every compute runs the resource's route and so its queries, against a
+ * database pool of ten by default. The engine used to start a whole slice of
+ * five hundred at a time, which does not make them finish sooner -- the driver
+ * queues the excess -- but does put hundreds of live queries in front of every
+ * ordinary HTTP request waiting for the same pool.
+ */
+class Concurrency {
+    current = 0;
+    peak = 0;
+    total = 0;
+
+    async run<T>(work: () => Promise<T>): Promise<T> {
+        this.current++;
+        this.total++;
+        this.peak = Math.max(this.peak, this.current);
+
+        try {
+            return await work();
+        } finally {
+            this.current--;
+        }
+    }
+
+    reset(): void {
+        this.current = 0;
+        this.peak = 0;
+        this.total = 0;
+    }
+}
+
+const probe = new Concurrency();
+
+@Controller('/probe')
+class ProbeController {
+    @Get('/')
+    @Live({ shared: 'public' })
+    async read(@Query('q') q?: string) {
+        dependencyContext.current()?.add({ key: 'orm:probe', columns: null });
+
+        // Asynchronous on purpose: a compute that never yields cannot overlap
+        // another, and would make any limit look respected.
+        return await probe.run(async () => {
+            await new Promise(resolve => setTimeout(resolve, 1));
+            return { q: q ?? '' };
+        });
+    }
+}
+
+class NullTransport implements LiveTransport {
+    send(): number {
+        return 1;
+    }
+}
+
+function build(overrides: Record<string, unknown> = {}) {
+    const resources = new ResourceRegistry();
+    resources.register(ProbeController, new ProbeController(), directResourceExecutor);
+
+    const bus = new InProcessBus();
+    const engine = new LiveEngine(
+        resources,
+        new DependencyGraph(),
+        new SubscriptionRegistry(),
+        bus,
+        new NullTransport(),
+        resolveLiveConfig({ coalesceMs: 1, unsubGraceMs: 5000, ...overrides })
+    );
+    engine.start();
+
+    return { engine, bus };
+}
+
+/** Subscribe `count` distinct instances of the one resource. */
+async function subscribeMany(engine: LiveEngine, count: number): Promise<void> {
+    const pending: Promise<void>[] = [];
+
+    for (let i = 0; i < count; i++) {
+        pending.push(engine.subscribe(
+            'c1',
+            `s${i}`,
+            'ProbeController.read',
+            { params: {}, query: { q: String(i) } },
+            {}
+        ));
+    }
+
+    await Promise.all(pending);
+}
+
+const settle = () => new Promise(resolve => setTimeout(resolve, 400));
+
+describe('recompute concurrency', () => {
+    test('a fan-out never runs more computes at once than the limit allows', async () => {
+        const { engine, bus } = build({ maxConcurrentRecomputes: 3 });
+        await subscribeMany(engine, 40);
+
+        probe.reset();
+        bus.publish([{ key: 'orm:probe', columns: null }]);
+        await settle();
+
+        expect(probe.peak).toBeLessThanOrEqual(3);
+        // And every instance was still recomputed, not merely throttled away.
+        expect(probe.total).toBe(40);
+        expect(probe.current).toBe(0);
+        engine.stop();
+    });
+
+    test('the limit holds across two flushes overlapping', async () => {
+        const { engine, bus } = build({ maxConcurrentRecomputes: 2, coalesceMs: 1 });
+        await subscribeMany(engine, 30);
+
+        probe.reset();
+        bus.publish([{ key: 'orm:probe', columns: null }]);
+        // A second batch while the first is still draining: the cap belongs to
+        // the engine, not to one flush, so two flushes cannot double it.
+        await new Promise(resolve => setTimeout(resolve, 5));
+        bus.publish([{ key: 'orm:probe', columns: null }]);
+        await settle();
+
+        expect(probe.peak).toBeLessThanOrEqual(2);
+        expect(probe.current).toBe(0);
+        engine.stop();
+    });
+
+    test('a burst of first subscriptions is bounded too', async () => {
+        const { engine } = build({ maxConcurrentRecomputes: 3 });
+
+        probe.reset();
+        await subscribeMany(engine, 25);
+
+        // createInstance runs the same query against the same pool; leaving it
+        // out would have left the cap open on the path a deploy hits hardest.
+        expect(probe.peak).toBeLessThanOrEqual(3);
+        expect(probe.total).toBe(25);
+        engine.stop();
+    });
+
+    test('the default keeps room in the pool for ordinary requests', () => {
+        // Bun's SQL pool defaults to ten connections. A default at or above
+        // that would let a fan-out take every one of them.
+        expect(resolveLiveConfig().maxConcurrentRecomputes).toBeLessThan(10);
+    });
+
+    test('stopping releases whoever was queued for a permit', async () => {
+        const { engine, bus } = build({ maxConcurrentRecomputes: 1 });
+        await subscribeMany(engine, 12);
+
+        probe.reset();
+        bus.publish([{ key: 'orm:probe', columns: null }]);
+        await new Promise(resolve => setTimeout(resolve, 3));
+        engine.stop();
+        await settle();
+
+        // Nothing is left holding a permit or waiting for one forever.
+        expect(probe.current).toBe(0);
+        expect(probe.total).toBe(12);
+
+        // And the permit accounting balanced, so restarting still bounds.
+        probe.reset();
+        engine.start();
+        bus.publish([{ key: 'orm:probe', columns: null }]);
+        await settle();
+
+        expect(probe.peak).toBeLessThanOrEqual(1);
+        engine.stop();
+    });
+});

package/test/scope-warning.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { Controller, Get, createTestHarness } from '@carno.js/core';
+import { Live } from '../src/decorators/Live';
+import { LivePlugin } from '../src/LivePlugin';
+import { ResourceRegistry } from '../src/resource/ResourceRegistry';
+import { closeLiveRuntime } from '../src/runtime';
+import { defaultScopeWarning } from '../src/scope-warning';
+import { ConnectionScopeResolver } from '../src/transport/scope-resolver';
+import { directResourceExecutor } from './resource-registry-helper';
+
+@Controller('/mixed')
+class MixedController {
+    @Get('/inbox')
+    @Live()
+    inbox() {
+        return [];
+    }
+
+    @Get('/me')
+    @Live({ shared: 'private' })
+    me() {
+        return {};
+    }
+
+    @Get('/catalogue')
+    @Live({ shared: 'public' })
+    catalogue() {
+        return [];
+    }
+
+    @Get('/org')
+    @Live({ shared: 'tenant' })
+    org() {
+        return [];
+    }
+}
+
+function registry(): ResourceRegistry {
+    const resources = new ResourceRegistry();
+    resources.register(MixedController, new MixedController(), directResourceExecutor);
+
+    return resources;
+}
+
+describe('ResourceRegistry.idsShared', () => {
+    test('counts an undeclared @Live() as private', () => {
+        expect(registry().idsShared('private')).toEqual([
+            'MixedController.inbox',
+            'MixedController.me'
+        ]);
+    });
+
+    test('separates the shared modes', () => {
+        expect(registry().idsShared('public')).toEqual(['MixedController.catalogue']);
+        expect(registry().idsShared('tenant')).toEqual(['MixedController.org']);
+    });
+});
+
+describe('the default-scope boot warning', () => {
+    test('names the private resources and the node ceiling', () => {
+        const warning = defaultScopeWarning({
+            privateResourceIds: registry().idsShared('private'),
+            usingDefaultResolver: true,
+            maxInstancesPerNode: 50000
+        });
+
+        expect(warning).toContain('MixedController.inbox');
+        expect(warning).toContain('MixedController.me');
+        expect(warning).toContain('50000');
+        expect(warning).toContain('scopeResolver');
+        // The modes that do not scale in connections stay out of it.
+        expect(warning).not.toContain('MixedController.catalogue');
+        expect(warning).not.toContain('MixedController.org');
+    });
+
+    test('says nothing once the application brings its own resolver', () => {
+        expect(defaultScopeWarning({
+            privateResourceIds: ['A.list'],
+            usingDefaultResolver: false,
+            maxInstancesPerNode: 50000
+        })).toBeNull();
+    });
+
+    test('says nothing when no resource is private', () => {
+        expect(defaultScopeWarning({
+            privateResourceIds: [],
+            usingDefaultResolver: true,
+            maxInstancesPerNode: 50000
+        })).toBeNull();
+    });
+
+    test('collapses a long list to a count', () => {
+        const ids = Array.from({ length: 12 }, (_, index) => `C.r${index}`);
+        const warning = defaultScopeWarning({
+            privateResourceIds: ids,
+            usingDefaultResolver: true,
+            maxInstancesPerNode: 50000
+        });
+
+        expect(warning).toContain('C.r7');
+        expect(warning).not.toContain('C.r8');
+        expect(warning).toContain('and 4 more');
+    });
+
+    test('agrees in number with a single resource', () => {
+        const warning = defaultScopeWarning({
+            privateResourceIds: ['A.list'],
+            usingDefaultResolver: true,
+            maxInstancesPerNode: 50000
+        });
+
+        expect(warning).toContain('1 live resource is private');
+    });
+});
+
+@Controller('/inbox')
+class InboxController {
+    @Get('/')
+    @Live()
+    read() {
+        return { unread: 0 };
+    }
+}
+
+/** Boot an app and return what it wrote to the console while starting. */
+async function bootLogs(options: { scopeResolver?: ConnectionScopeResolver } = {}): Promise<string> {
+    const written: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => { written.push(args.map(String).join(' ')); };
+
+    try {
+        const harness = await createTestHarness({
+            plugins: [LivePlugin.create({ controllers: [InboxController], ...options })],
+            listen: true
+        });
+
+        await harness.close();
+    } finally {
+        console.warn = original;
+    }
+
+    return written.join('\n');
+}
+
+describe('the warning as the application sees it', () => {
+    afterEach(async () => {
+        await closeLiveRuntime();
+    });
+
+    test('a private resource with no resolver warns at boot', async () => {
+        expect(await bootLogs()).toContain('InboxController.read');
+    });
+
+    test('an explicit ConnectionScopeResolver is taken as the answer', async () => {
+        expect(await bootLogs({ scopeResolver: new ConnectionScopeResolver() })).toBe('');
+    });
+});