bunsane 0.2.9 → 0.3.0

package/tests/helpers/MockRedisClient.ts

@@ -0,0 +1,113 @@
+/**
+ * ioredis-shaped client backed by a MockRedisStreamServer.
+ *
+ * Cast the returned instance to `Redis` (from "ioredis") when passing into
+ * the remote subsystem via `redisFactory`. Only methods the remote layer
+ * touches are implemented; others throw on use.
+ */
+
+import type { MockRedisStreamServer } from "./MockRedisStreamServer";
+
+export class MockRedisClient {
+    private server: MockRedisStreamServer;
+    private connected = true;
+    private listeners = new Map<string, Array<(...args: any[]) => void>>();
+
+    constructor(server: MockRedisStreamServer) {
+        this.server = server;
+    }
+
+    on(event: string, listener: (...args: any[]) => void): this {
+        const arr = this.listeners.get(event) ?? [];
+        arr.push(listener);
+        this.listeners.set(event, arr);
+        return this;
+    }
+
+    async xadd(key: string, ...args: any[]): Promise<string | null> {
+        this.ensureConnected();
+        try {
+            return this.server.xadd(key, ...args);
+        } catch (err: any) {
+            throw err;
+        }
+    }
+
+    async xgroup(...args: any[]): Promise<string> {
+        this.ensureConnected();
+        const [op, key, group, id, mk] = args;
+        return this.server.xgroup(op, key, group, id, mk);
+    }
+
+    async xreadgroup(...args: any[]): Promise<any> {
+        this.ensureConnected();
+        return this.server.xreadgroup(...args);
+    }
+
+    async xread(...args: any[]): Promise<any> {
+        this.ensureConnected();
+        return this.server.xread(...args);
+    }
+
+    async xack(key: string, group: string, msgId: string): Promise<number> {
+        this.ensureConnected();
+        return this.server.xack(key, group, msgId);
+    }
+
+    async xpending(...args: any[]): Promise<any> {
+        this.ensureConnected();
+        const [key, group, ...rest] = args;
+        return this.server.xpending(key, group, ...rest);
+    }
+
+    async xautoclaim(...args: any[]): Promise<any> {
+        this.ensureConnected();
+        return this.server.xautoclaim(
+            args[0],
+            args[1],
+            args[2],
+            Number(args[3]),
+            args[4],
+            ...args.slice(5)
+        );
+    }
+
+    async xlen(key: string): Promise<number> {
+        this.ensureConnected();
+        return this.server.xlen(key);
+    }
+
+    async xrange(...args: any[]): Promise<any> {
+        this.ensureConnected();
+        return this.server.xrange(
+            args[0],
+            args[1],
+            args[2],
+            ...args.slice(3)
+        );
+    }
+
+    async ping(): Promise<string> {
+        this.ensureConnected();
+        return this.server.ping();
+    }
+
+    disconnect(): void {
+        this.connected = false;
+    }
+
+    async quit(): Promise<string> {
+        this.connected = false;
+        return "OK";
+    }
+
+    private ensureConnected(): void {
+        if (!this.connected) {
+            throw new Error("Connection is closed");
+        }
+    }
+}
+
+export function createMockRedisFactory(server: MockRedisStreamServer) {
+    return (_blocking: boolean) => new MockRedisClient(server);
+}

package/tests/helpers/MockRedisStreamServer.ts

@@ -0,0 +1,448 @@
+/**
+ * In-memory Redis Streams shim for Tier 2 integration tests.
+ *
+ * Implements only the commands the remote subsystem issues:
+ *   xadd, xreadgroup, xread, xack, xgroup CREATE, xpending,
+ *   xautoclaim, xlen, xrange, ping
+ *
+ * Shared server: multiple MockRedisClient instances pointing at the same
+ * server simulate separate app processes talking to one Redis.
+ */
+
+interface StreamEntry {
+    id: string;
+    fields: string[]; // flat [k,v,k,v,...]
+}
+
+interface PelEntry {
+    msgId: string;
+    consumer: string;
+    deliveredAt: number;
+    deliveryCount: number;
+}
+
+interface ConsumerGroup {
+    name: string;
+    consumers: Set<string>;
+    pel: Map<string, PelEntry>;
+    /** Highest ID delivered via ">" — next read starts after this. */
+    lastDeliveredId: string;
+}
+
+interface Stream {
+    key: string;
+    entries: StreamEntry[];
+    groups: Map<string, ConsumerGroup>;
+    lastGeneratedTs: number;
+    seqWithinMs: number;
+}
+
+const MIN_ID = "0-0";
+
+function parseId(id: string): [number, number] {
+    const dash = id.indexOf("-");
+    if (dash < 0) return [Number(id), 0];
+    return [Number(id.slice(0, dash)), Number(id.slice(dash + 1))];
+}
+
+function idLess(a: string, b: string): boolean {
+    const [at, as] = parseId(a);
+    const [bt, bs] = parseId(b);
+    if (at !== bt) return at < bt;
+    return as < bs;
+}
+
+function idGreater(a: string, b: string): boolean {
+    const [at, as] = parseId(a);
+    const [bt, bs] = parseId(b);
+    if (at !== bt) return at > bt;
+    return as > bs;
+}
+
+export class MockRedisStreamServer {
+    private streams = new Map<string, Stream>();
+    /** Fault injection for tests that need to simulate XADD failures. */
+    public xaddShouldFail = false;
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+
+    private getOrCreateStream(key: string): Stream {
+        let s = this.streams.get(key);
+        if (!s) {
+            s = {
+                key,
+                entries: [],
+                groups: new Map(),
+                lastGeneratedTs: 0,
+                seqWithinMs: 0,
+            };
+            this.streams.set(key, s);
+        }
+        return s;
+    }
+
+    private generateId(stream: Stream): string {
+        const now = Date.now();
+        if (now === stream.lastGeneratedTs) {
+            stream.seqWithinMs++;
+        } else {
+            stream.lastGeneratedTs = now;
+            stream.seqWithinMs = 0;
+        }
+        return `${now}-${stream.seqWithinMs}`;
+    }
+
+    /**
+     * XADD key [MAXLEN [~] N] * field value [field value ...]
+     * Returns the generated id.
+     */
+    xadd(key: string, ...args: any[]): string {
+        if (this.xaddShouldFail) {
+            throw new Error("MOCK_XADD_FAIL");
+        }
+        const stream = this.getOrCreateStream(key);
+
+        // Parse leading options
+        let i = 0;
+        let maxLen: number | null = null;
+        if (args[i] === "MAXLEN") {
+            i++;
+            if (args[i] === "~" || args[i] === "=") i++;
+            maxLen = Number(args[i]);
+            i++;
+        }
+
+        // Expect "*"
+        if (args[i] !== "*") {
+            throw new Error(`MockRedis xadd: only "*" auto-id supported, got ${args[i]}`);
+        }
+        i++;
+
+        const fields: string[] = [];
+        for (; i < args.length; i++) {
+            fields.push(String(args[i]));
+        }
+
+        const id = this.generateId(stream);
+        stream.entries.push({ id, fields });
+
+        if (maxLen !== null && stream.entries.length > maxLen) {
+            stream.entries.splice(0, stream.entries.length - maxLen);
+        }
+
+        return id;
+    }
+
+    /**
+     * XGROUP CREATE stream group id [MKSTREAM]
+     * id "$" = start from latest, "0" / "0-0" = start from beginning.
+     */
+    xgroup(op: string, key: string, groupName: string, startId: string, mkstream?: string): string {
+        if (op !== "CREATE") {
+            throw new Error(`MockRedis xgroup: op "${op}" not supported`);
+        }
+        const hasStream = this.streams.has(key);
+        if (!hasStream && mkstream !== "MKSTREAM") {
+            throw new Error("ERR no such key");
+        }
+        const stream = this.getOrCreateStream(key);
+        if (stream.groups.has(groupName)) {
+            const err = new Error(
+                `BUSYGROUP Consumer Group name already exists`
+            );
+            throw err;
+        }
+        const lastDeliveredId =
+            startId === "$"
+                ? stream.entries.length > 0
+                    ? stream.entries[stream.entries.length - 1]!.id
+                    : MIN_ID
+                : startId === "0" || startId === "0-0"
+                  ? MIN_ID
+                  : startId;
+        stream.groups.set(groupName, {
+            name: groupName,
+            consumers: new Set(),
+            pel: new Map(),
+            lastDeliveredId,
+        });
+        return "OK";
+    }
+
+    /**
+     * XREADGROUP GROUP g consumer [COUNT n] [BLOCK ms] STREAMS s ">"
+     * Returns [[streamKey, [[id, fields], ...]]] or null on timeout.
+     */
+    async xreadgroup(...args: any[]): Promise<any> {
+        let i = 0;
+        if (args[i] !== "GROUP") throw new Error("expected GROUP");
+        i++;
+        const groupName = String(args[i++]);
+        const consumer = String(args[i++]);
+        let count = Infinity;
+        let blockMs = 0;
+        while (args[i] !== "STREAMS") {
+            const opt = String(args[i++]).toUpperCase();
+            if (opt === "COUNT") count = Number(args[i++]);
+            else if (opt === "BLOCK") blockMs = Number(args[i++]);
+            else throw new Error(`unknown XREADGROUP opt ${opt}`);
+        }
+        i++; // skip STREAMS
+        const streams: string[] = [];
+        const ids: string[] = [];
+        const remaining = args.slice(i);
+        const half = remaining.length / 2;
+        for (let k = 0; k < half; k++) {
+            streams.push(String(remaining[k]));
+            ids.push(String(remaining[k + half]));
+        }
+
+        const deadline = Date.now() + blockMs;
+        while (true) {
+            const result = this.readGroupOnce(groupName, consumer, count, streams, ids);
+            if (result) return result;
+            if (Date.now() >= deadline) return null;
+            await this.sleep(10);
+        }
+    }
+
+    private readGroupOnce(
+        groupName: string,
+        consumer: string,
+        count: number,
+        streams: string[],
+        ids: string[]
+    ): any[] | null {
+        const out: any[] = [];
+        for (let s = 0; s < streams.length; s++) {
+            const streamKey = streams[s]!;
+            const id = ids[s]!;
+            const stream = this.streams.get(streamKey);
+            if (!stream) continue;
+            const group = stream.groups.get(groupName);
+            if (!group) continue;
+            group.consumers.add(consumer);
+
+            let newEntries: StreamEntry[];
+            if (id === ">") {
+                // New messages only
+                newEntries = stream.entries.filter((e) =>
+                    idGreater(e.id, group.lastDeliveredId)
+                );
+                if (newEntries.length > count) {
+                    newEntries = newEntries.slice(0, count);
+                }
+                for (const entry of newEntries) {
+                    group.lastDeliveredId = entry.id;
+                    const existing = group.pel.get(entry.id);
+                    if (existing) {
+                        existing.deliveryCount++;
+                        existing.deliveredAt = Date.now();
+                        existing.consumer = consumer;
+                    } else {
+                        group.pel.set(entry.id, {
+                            msgId: entry.id,
+                            consumer,
+                            deliveredAt: Date.now(),
+                            deliveryCount: 1,
+                        });
+                    }
+                }
+            } else {
+                // Re-read this consumer's PEL
+                newEntries = stream.entries.filter((e) => {
+                    const p = group.pel.get(e.id);
+                    return p && p.consumer === consumer && idGreater(e.id, id);
+                });
+                if (newEntries.length > count) {
+                    newEntries = newEntries.slice(0, count);
+                }
+            }
+
+            if (newEntries.length > 0) {
+                out.push([
+                    streamKey,
+                    newEntries.map((e) => [e.id, e.fields]),
+                ]);
+            }
+        }
+        return out.length > 0 ? out : null;
+    }
+
+    /**
+     * XREAD [COUNT n] [BLOCK ms] STREAMS s id
+     */
+    async xread(...args: any[]): Promise<any> {
+        let i = 0;
+        let count = Infinity;
+        let blockMs = 0;
+        while (args[i] !== "STREAMS") {
+            const opt = String(args[i++]).toUpperCase();
+            if (opt === "COUNT") count = Number(args[i++]);
+            else if (opt === "BLOCK") blockMs = Number(args[i++]);
+            else throw new Error(`unknown XREAD opt ${opt}`);
+        }
+        i++;
+        const remaining = args.slice(i);
+        const half = remaining.length / 2;
+        const streams: string[] = [];
+        const ids: string[] = [];
+        for (let k = 0; k < half; k++) {
+            streams.push(String(remaining[k]));
+            ids.push(String(remaining[k + half]));
+        }
+
+        // Resolve "$" to the current last id per stream once, up front.
+        // Subsequent polls compare against that snapshot so new entries get
+        // delivered exactly once.
+        const resolvedIds = ids.map((id, k) => {
+            if (id !== "$") return id;
+            const stream = this.streams.get(streams[k]!);
+            if (!stream || stream.entries.length === 0) return MIN_ID;
+            return stream.entries[stream.entries.length - 1]!.id;
+        });
+
+        const deadline = Date.now() + blockMs;
+        while (true) {
+            const out: any[] = [];
+            for (let s = 0; s < streams.length; s++) {
+                const streamKey = streams[s]!;
+                const afterId = resolvedIds[s]!;
+                const stream = this.streams.get(streamKey);
+                if (!stream) continue;
+                const matching = stream.entries
+                    .filter((e) => idGreater(e.id, afterId))
+                    .slice(0, count);
+                if (matching.length > 0) {
+                    out.push([
+                        streamKey,
+                        matching.map((e) => [e.id, e.fields]),
+                    ]);
+                }
+            }
+            if (out.length > 0) return out;
+            if (Date.now() >= deadline) return null;
+            await this.sleep(10);
+        }
+    }
+
+    xack(key: string, groupName: string, msgId: string): number {
+        const stream = this.streams.get(key);
+        if (!stream) return 0;
+        const group = stream.groups.get(groupName);
+        if (!group) return 0;
+        return group.pel.delete(msgId) ? 1 : 0;
+    }
+
+    /**
+     * Two forms:
+     *   XPENDING key group                              -> summary
+     *   XPENDING key group minId maxId count [consumer] -> detail
+     */
+    xpending(key: string, groupName: string, ...args: any[]): any {
+        const stream = this.streams.get(key);
+        if (!stream) return [0, null, null, null];
+        const group = stream.groups.get(groupName);
+        if (!group) return [0, null, null, null];
+
+        if (args.length === 0) {
+            // Summary
+            const ids = Array.from(group.pel.keys()).sort((a, b) =>
+                idLess(a, b) ? -1 : idGreater(a, b) ? 1 : 0
+            );
+            if (ids.length === 0) return [0, null, null, null];
+            const byConsumer = new Map<string, number>();
+            for (const p of group.pel.values()) {
+                byConsumer.set(
+                    p.consumer,
+                    (byConsumer.get(p.consumer) ?? 0) + 1
+                );
+            }
+            return [
+                ids.length,
+                ids[0],
+                ids[ids.length - 1],
+                Array.from(byConsumer.entries()).map(([c, n]) => [c, String(n)]),
+            ];
+        }
+
+        const [minId, maxId, _count] = args;
+        const out: any[] = [];
+        for (const p of group.pel.values()) {
+            if (idLess(p.msgId, minId) || idGreater(p.msgId, maxId)) continue;
+            out.push([
+                p.msgId,
+                p.consumer,
+                Date.now() - p.deliveredAt,
+                p.deliveryCount,
+            ]);
+        }
+        return out;
+    }
+
+    /**
+     * XAUTOCLAIM stream group consumer idleMs cursor [COUNT n]
+     * Returns [nextCursor, entries]
+     */
+    xautoclaim(
+        key: string,
+        groupName: string,
+        consumer: string,
+        idleMs: number,
+        cursor: string,
+        ..._rest: any[]
+    ): any {
+        const stream = this.streams.get(key);
+        if (!stream) return ["0-0", []];
+        const group = stream.groups.get(groupName);
+        if (!group) return ["0-0", []];
+
+        const now = Date.now();
+        const claimed: any[] = [];
+        for (const p of group.pel.values()) {
+            if (now - p.deliveredAt < idleMs) continue;
+            if (idLess(p.msgId, cursor) && cursor !== "0-0") continue;
+            p.consumer = consumer;
+            p.deliveryCount++;
+            p.deliveredAt = now;
+            const entry = stream.entries.find((e) => e.id === p.msgId);
+            if (entry) claimed.push([entry.id, entry.fields]);
+        }
+        return ["0-0", claimed];
+    }
+
+    xlen(key: string): number {
+        return this.streams.get(key)?.entries.length ?? 0;
+    }
+
+    xrange(key: string, start: string, end: string, ..._rest: any[]): any[] {
+        const stream = this.streams.get(key);
+        if (!stream) return [];
+        const lo = start === "-" ? MIN_ID : start;
+        const hi = end === "+" ? "9999999999999-9999" : end;
+        return stream.entries
+            .filter(
+                (e) =>
+                    !idLess(e.id, lo) && !idGreater(e.id, hi)
+            )
+            .map((e) => [e.id, e.fields]);
+    }
+
+    ping(): string {
+        return "PONG";
+    }
+
+    /** Helper for tests: total PEL entries across a group. */
+    getPelSize(streamKey: string, groupName: string): number {
+        return (
+            this.streams.get(streamKey)?.groups.get(groupName)?.pel.size ?? 0
+        );
+    }
+
+    /** Helper for tests: raw stream entry count ignoring groups. */
+    getStreamLength(key: string): number {
+        return this.xlen(key);
+    }
+}

package/tests/integration/entity/Entity.saveTimeout.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Integration tests for Entity.save timeout and cancellation behavior.
+ *
+ * Regression coverage for the production incident where Entity.save's wall-
+ * clock timeout rejected the outer Promise but left the underlying Bun SQL
+ * transaction mid-flight. Under pgbouncer transaction-mode pooling this
+ * leaked backend PostgreSQL sessions into `idle in transaction` state,
+ * exhausting the pool.
+ *
+ * These tests prove the invariants the fix must uphold:
+ *   1. An aborted save leaves no partial rows — Bun SQL's transaction callback
+ *      throws, auto-ROLLBACK fires, backend connection is released.
+ *   2. The connection pool stays healthy after repeated aborts — subsequent
+ *      saves on fresh entities still succeed.
+ *   3. A save with no abort still commits normally.
+ *
+ * The wall-clock DB_QUERY_TIMEOUT path is module-cached at import time so it
+ * is not exercised here directly. Manual verification on a real Postgres +
+ * pgbouncer stack (with query_wait_timeout short enough to fire) should
+ * confirm pg_stat_activity shows no `idle in transaction` backends after
+ * this test suite runs. See the handoff doc (2026-04-18) for the repro steps.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import db from '../../../database';
+import { TestUser } from '../../fixtures/components';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+describe('Entity.save timeout and cancellation', () => {
+    const ctx = createTestContext();
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser);
+    });
+
+    test('aborted doSave does not leave partial rows (transaction rolls back)', async () => {
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'aborted', email: 'a@example.com', age: 1 });
+
+        const controller = new AbortController();
+        // Abort immediately — the first in-flight query will be cancelled,
+        // the transaction callback throws, Bun SQL issues ROLLBACK.
+        queueMicrotask(() => controller.abort(new Error('simulated save timeout')));
+
+        const result = db.transaction(async (trx) => {
+            await entity.doSave(trx, controller.signal);
+        });
+
+        await expect(result).rejects.toBeDefined();
+
+        // Entity must NOT exist — rollback invariant.
+        const rows = await db`SELECT id FROM entities WHERE id = ${entity.id}`;
+        expect(rows.length).toBe(0);
+    });
+
+    test('connection pool stays healthy after multiple aborted saves', async () => {
+        // Repeatedly abort saves — if connections leaked, subsequent saves
+        // would eventually block on pool acquire.
+        for (let i = 0; i < 8; i++) {
+            const entity = Entity.Create();
+            entity.add(TestUser, { name: `aborted-${i}`, email: `a${i}@e.com`, age: i });
+
+            const controller = new AbortController();
+            queueMicrotask(() => controller.abort(new Error('simulated timeout')));
+
+            await db.transaction(async (trx) => {
+                await entity.doSave(trx, controller.signal);
+            }).catch(() => { /* expected */ });
+        }
+
+        // A fresh save must still succeed on the pool that serviced the aborts.
+        const healthy = ctx.tracker.create();
+        healthy.add(TestUser, { name: 'healthy', email: 'h@e.com', age: 99 });
+        await healthy.save();
+
+        expect(healthy._persisted).toBe(true);
+
+        const rows = await db`SELECT id FROM entities WHERE id = ${healthy.id}`;
+        expect(rows.length).toBe(1);
+    });
+
+    test('doSave without signal behaves normally (backwards compatible)', async () => {
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'no-signal', email: 'n@e.com', age: 5 });
+
+        await db.transaction(async (trx) => {
+            await entity.doSave(trx); // no signal passed
+        });
+
+        const rows = await db`SELECT id FROM entities WHERE id = ${entity.id}`;
+        expect(rows.length).toBe(1);
+    });
+
+    test('save() resolves even if post-commit cache work is slow (fire-and-forget)', async () => {
+        // Cache handler is queued via queueMicrotask; save() must resolve as
+        // soon as the DB transaction commits. We assert save resolves quickly
+        // even though handleCacheAfterSave is awaited separately.
+        const entity = ctx.tracker.create();
+        entity.add(TestUser, { name: 'fast', email: 'f@e.com', age: 10 });
+
+        const start = performance.now();
+        await entity.save();
+        const elapsed = performance.now() - start;
+
+        expect(entity._persisted).toBe(true);
+        // Generous bound — if cache were blocking save, timings under load
+        // could stretch past the budget. This just guards gross regressions.
+        expect(elapsed).toBeLessThan(5000);
+    });
+});