bunsane 0.2.9 → 0.3.0

package/tests/unit/remote/CircuitBreaker.test.ts

@@ -0,0 +1,159 @@
+import { describe, test, expect } from "bun:test";
+import {
+    CircuitBreaker,
+    CircuitOpenError,
+} from "../../../core/remote/CircuitBreaker";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("CircuitBreaker", () => {
+    describe("state transitions", () => {
+        test("starts closed", () => {
+            const cb = new CircuitBreaker();
+            expect(cb.getState()).toBe("closed");
+        });
+
+        test("stays closed below threshold", () => {
+            const cb = new CircuitBreaker({ threshold: 3 });
+            cb.recordFailure();
+            cb.recordFailure();
+            expect(cb.getState()).toBe("closed");
+        });
+
+        test("opens at threshold", () => {
+            const cb = new CircuitBreaker({ threshold: 3 });
+            cb.recordFailure();
+            cb.recordFailure();
+            cb.recordFailure();
+            expect(cb.getState()).toBe("open");
+        });
+
+        test("transitions to half-open after reset window", async () => {
+            const cb = new CircuitBreaker({ threshold: 1, resetTimeoutMs: 50 });
+            cb.recordFailure();
+            expect(cb.getState()).toBe("open");
+            await sleep(60);
+            expect(cb.getState()).toBe("half-open");
+        });
+
+        test("half-open success closes breaker", async () => {
+            const cb = new CircuitBreaker({ threshold: 1, resetTimeoutMs: 50 });
+            cb.recordFailure();
+            await sleep(60);
+            expect(cb.getState()).toBe("half-open");
+            cb.recordSuccess();
+            expect(cb.getState()).toBe("closed");
+        });
+
+        test("half-open failure reopens breaker", async () => {
+            const cb = new CircuitBreaker({ threshold: 1, resetTimeoutMs: 50 });
+            cb.recordFailure();
+            await sleep(60);
+            expect(cb.getState()).toBe("half-open");
+            cb.recordFailure();
+            expect(cb.getState()).toBe("open");
+        });
+
+        test("success in closed state zeroes failure count", () => {
+            const cb = new CircuitBreaker({ threshold: 3 });
+            cb.recordFailure();
+            cb.recordFailure();
+            cb.recordSuccess();
+            cb.recordFailure();
+            cb.recordFailure();
+            // Still closed — counter reset to 0 on success, only 2 new failures
+            expect(cb.getState()).toBe("closed");
+        });
+    });
+
+    describe("exec()", () => {
+        test("passes result on success", async () => {
+            const cb = new CircuitBreaker();
+            const result = await cb.exec(async () => 42);
+            expect(result).toBe(42);
+        });
+
+        test("records failure on thrown error", async () => {
+            const cb = new CircuitBreaker({ threshold: 2 });
+            await expect(
+                cb.exec(async () => {
+                    throw new Error("boom");
+                })
+            ).rejects.toThrow("boom");
+            expect(cb.getStats().failures).toBe(1);
+        });
+
+        test("rejects immediately when open", async () => {
+            const cb = new CircuitBreaker({ threshold: 1 });
+            await expect(
+                cb.exec(async () => {
+                    throw new Error("fail");
+                })
+            ).rejects.toThrow();
+            // Now open
+            await expect(cb.exec(async () => "should not run")).rejects.toBeInstanceOf(
+                CircuitOpenError
+            );
+        });
+
+        test("open-state rejection does not call fn", async () => {
+            const cb = new CircuitBreaker({ threshold: 1 });
+            await cb.exec(async () => { throw new Error("x"); }).catch(() => {});
+            let called = false;
+            await cb.exec(async () => { called = true; }).catch(() => {});
+            expect(called).toBe(false);
+        });
+    });
+
+    describe("hooks", () => {
+        test("onTrip fires once when opening", () => {
+            const cb = new CircuitBreaker({ threshold: 2 });
+            let trips = 0;
+            cb.onTrip = () => trips++;
+            cb.recordFailure();
+            expect(trips).toBe(0);
+            cb.recordFailure();
+            expect(trips).toBe(1);
+        });
+
+        test("onTrip fires again on half-open→open transition", async () => {
+            const cb = new CircuitBreaker({ threshold: 1, resetTimeoutMs: 30 });
+            let trips = 0;
+            cb.onTrip = () => trips++;
+            cb.recordFailure();
+            expect(trips).toBe(1);
+            await sleep(40);
+            // half-open trial fails
+            cb.recordFailure();
+            expect(trips).toBe(2);
+        });
+
+        test("onReject fires when exec rejected by open breaker", async () => {
+            const cb = new CircuitBreaker({ threshold: 1 });
+            let rejects = 0;
+            cb.onReject = () => rejects++;
+            await cb.exec(async () => { throw new Error("x"); }).catch(() => {});
+            await cb.exec(async () => 1).catch(() => {});
+            expect(rejects).toBe(1);
+        });
+    });
+
+    describe("reset()", () => {
+        test("force-closes an open breaker", () => {
+            const cb = new CircuitBreaker({ threshold: 1 });
+            cb.recordFailure();
+            expect(cb.getState()).toBe("open");
+            cb.reset();
+            expect(cb.getState()).toBe("closed");
+            expect(cb.getStats().failures).toBe(0);
+        });
+    });
+
+    describe("CircuitOpenError", () => {
+        test("has CIRCUIT_OPEN code", () => {
+            const err = new CircuitOpenError();
+            expect(err.code).toBe("CIRCUIT_OPEN");
+            expect(err).toBeInstanceOf(Error);
+        });
+    });
+});

package/tests/unit/remote/RemoteError.test.ts

@@ -0,0 +1,55 @@
+import { describe, test, expect } from "bun:test";
+import { RemoteError } from "../../../core/remote/types";
+
+describe("RemoteError", () => {
+    test("carries message + code", () => {
+        const err = new RemoteError("boom", { code: "X" });
+        expect(err.message).toBe("boom");
+        expect(err.code).toBe("X");
+    });
+
+    test("default name is RemoteError", () => {
+        const err = new RemoteError("m", { code: "X" });
+        expect(err.name).toBe("RemoteError");
+    });
+
+    test("is instanceof Error", () => {
+        const err = new RemoteError("m", { code: "X" });
+        expect(err).toBeInstanceOf(Error);
+        expect(err).toBeInstanceOf(RemoteError);
+    });
+
+    test("sourceApp + extensions are optional", () => {
+        const err = new RemoteError("m", { code: "X" });
+        expect(err.sourceApp).toBeUndefined();
+        expect(err.extensions).toBeUndefined();
+    });
+
+    test("sourceApp + extensions propagate", () => {
+        const err = new RemoteError("m", {
+            code: "FORBIDDEN",
+            sourceApp: "orders",
+            extensions: { userId: "u1", reason: "not-owner" },
+        });
+        expect(err.sourceApp).toBe("orders");
+        expect(err.extensions).toEqual({ userId: "u1", reason: "not-owner" });
+    });
+
+    test("can be thrown + caught with instanceof narrowing", () => {
+        try {
+            throw new RemoteError("nope", { code: "NOT_FOUND" });
+        } catch (e) {
+            if (e instanceof RemoteError) {
+                expect(e.code).toBe("NOT_FOUND");
+                return;
+            }
+            throw new Error("did not narrow");
+        }
+    });
+
+    test("stack trace is preserved", () => {
+        const err = new RemoteError("m", { code: "X" });
+        expect(err.stack).toBeDefined();
+        expect(typeof err.stack).toBe("string");
+    });
+});

package/tests/unit/remote/decorators.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import {
+    RemoteEvent,
+    RemoteRpc,
+    registerRemoteHandlers,
+} from "../../../core/remote/decorators";
+import {
+    setRemoteManager,
+    getRemoteManager,
+} from "../../../core/remote/RemoteManager";
+import type { RemoteHandler, RpcHandler } from "../../../core/remote/types";
+
+describe("@RemoteEvent + @RemoteRpc decorators", () => {
+    test("RemoteEvent stores handler metadata on constructor", () => {
+        class S {
+            @RemoteEvent({ event: "foo.bar" })
+            handleFooBar() {}
+        }
+        const meta = (S as any).__remoteHandlers;
+        expect(meta).toHaveLength(1);
+        expect(meta[0]).toMatchObject({
+            event: "foo.bar",
+            methodName: "handleFooBar",
+            kind: "event",
+        });
+        expect(meta[0].handlerId).toBe("S.handleFooBar");
+    });
+
+    test("RemoteRpc stores handler metadata with rpc_request kind", () => {
+        class R {
+            @RemoteRpc({ event: "order.get" })
+            getOrder() {
+                return { id: "x" };
+            }
+        }
+        const meta = (R as any).__remoteHandlers;
+        expect(meta).toHaveLength(1);
+        expect(meta[0].kind).toBe("rpc_request");
+        expect(meta[0].event).toBe("order.get");
+    });
+
+    test("custom id overrides default", () => {
+        class S {
+            @RemoteEvent({ event: "a", id: "custom-id" })
+            h() {}
+        }
+        const meta = (S as any).__remoteHandlers;
+        expect(meta[0].handlerId).toBe("custom-id");
+    });
+
+    test("duplicate handler id on same class is skipped", () => {
+        class S {
+            @RemoteEvent({ event: "a", id: "dup" })
+            h1() {}
+            @RemoteEvent({ event: "b", id: "dup" })
+            h2() {}
+        }
+        const meta = (S as any).__remoteHandlers;
+        expect(meta).toHaveLength(1);
+        expect(meta[0].event).toBe("a"); // first wins
+    });
+
+    test("mixed RemoteEvent + RemoteRpc coexist on one class", () => {
+        class S {
+            @RemoteEvent({ event: "e1" })
+            onE1() {}
+            @RemoteRpc({ event: "r1" })
+            handleR1() {
+                return 1;
+            }
+        }
+        const meta = (S as any).__remoteHandlers;
+        expect(meta).toHaveLength(2);
+        expect(meta.map((m: any) => m.kind).sort()).toEqual([
+            "event",
+            "rpc_request",
+        ]);
+    });
+
+    test("metadata is isolated per class constructor", () => {
+        class A {
+            @RemoteEvent({ event: "a.evt" })
+            h() {}
+        }
+        class B {
+            @RemoteEvent({ event: "b.evt" })
+            h() {}
+        }
+        expect((A as any).__remoteHandlers).toHaveLength(1);
+        expect((B as any).__remoteHandlers).toHaveLength(1);
+        expect((A as any).__remoteHandlers[0].event).toBe("a.evt");
+        expect((B as any).__remoteHandlers[0].event).toBe("b.evt");
+    });
+});
+
+describe("registerRemoteHandlers", () => {
+    beforeEach(() => {
+        setRemoteManager(null);
+    });
+
+    afterEach(() => {
+        setRemoteManager(null);
+    });
+
+    test("no-op when service has no decorated handlers", () => {
+        class S {}
+        // Should not throw, should not touch manager
+        registerRemoteHandlers(new S());
+        expect(getRemoteManager()).toBeNull();
+    });
+
+    test("skips registration when manager is not initialized", () => {
+        class S {
+            @RemoteEvent({ event: "x" })
+            h() {}
+        }
+        // No manager set — should warn but not throw
+        expect(() => registerRemoteHandlers(new S())).not.toThrow();
+    });
+
+    test("routes event handlers to manager.on()", () => {
+        const calls: Array<{
+            event: string;
+            handlerId: string;
+            kind: "event" | "rpc";
+        }> = [];
+        const mockManager = {
+            on(event: string, _fn: RemoteHandler, handlerId: string) {
+                calls.push({ event, handlerId, kind: "event" });
+            },
+            onRpc(event: string, _fn: RpcHandler, handlerId: string) {
+                calls.push({ event, handlerId, kind: "rpc" });
+            },
+        } as any;
+        setRemoteManager(mockManager);
+
+        class S {
+            @RemoteEvent({ event: "e1" })
+            ehandler() {}
+            @RemoteRpc({ event: "r1" })
+            rhandler() {
+                return 1;
+            }
+        }
+
+        registerRemoteHandlers(new S());
+
+        expect(calls).toHaveLength(2);
+        expect(calls.find((c) => c.event === "e1")?.kind).toBe("event");
+        expect(calls.find((c) => c.event === "r1")?.kind).toBe("rpc");
+    });
+
+    test("handler bound to service instance", async () => {
+        let receivedThis: any = null;
+        const mockManager = {
+            on(_event: string, fn: RemoteHandler, _id: string) {
+                // Invoke right away to verify binding
+                fn({} as any, {} as any);
+            },
+            onRpc() {},
+        } as any;
+        setRemoteManager(mockManager);
+
+        class S {
+            tag = "instance-tag";
+            @RemoteEvent({ event: "e1" })
+            handler() {
+                receivedThis = this.tag;
+            }
+        }
+
+        registerRemoteHandlers(new S());
+        // Give microtask for any await inside handler to settle
+        await Promise.resolve();
+        expect(receivedThis).toBe("instance-tag");
+    });
+
+    test("missing method on instance is skipped (no throw)", () => {
+        const mockManager = { on() {}, onRpc() {} } as any;
+        setRemoteManager(mockManager);
+
+        class S {}
+        // Inject fake metadata referencing a non-existent method
+        (S as any).__remoteHandlers = [
+            {
+                event: "e1",
+                methodName: "doesNotExist",
+                handlerId: "S.doesNotExist",
+                kind: "event",
+            },
+        ];
+
+        expect(() => registerRemoteHandlers(new S())).not.toThrow();
+    });
+});

package/tests/unit/remote/metrics.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { RemoteMetrics } from "../../../core/remote/metrics";
+
+describe("RemoteMetrics", () => {
+    let m: RemoteMetrics;
+    beforeEach(() => {
+        m = new RemoteMetrics();
+    });
+
+    test("fresh snapshot is all zeros", () => {
+        const snap = m.getSnapshot();
+        expect(snap.emit).toEqual({ direct: 0, outbox: 0, failed: 0 });
+        expect(snap.events).toEqual({
+            received: 0,
+            handled: 0,
+            handlerFailed: 0,
+            noHandler: 0,
+            dlq: 0,
+        });
+        expect(snap.rpc).toEqual({
+            called: 0,
+            succeeded: 0,
+            failed: 0,
+            timedOut: 0,
+            handlerExecuted: 0,
+            handlerFailed: 0,
+            pastDeadline: 0,
+        });
+        expect(snap.outbox).toEqual({ claimed: 0, published: 0, publishFailed: 0 });
+        expect(snap.circuitBreaker).toEqual({ trips: 0, rejected: 0 });
+    });
+
+    test("emit counters", () => {
+        m.emitDirect();
+        m.emitDirect();
+        m.emitOutbox();
+        m.emitFailed();
+        const s = m.getSnapshot();
+        expect(s.emit.direct).toBe(2);
+        expect(s.emit.outbox).toBe(1);
+        expect(s.emit.failed).toBe(1);
+    });
+
+    test("event counters", () => {
+        m.eventReceived();
+        m.eventHandled();
+        m.eventHandlerFailed();
+        m.eventNoHandler();
+        m.eventDlq();
+        const s = m.getSnapshot();
+        expect(s.events).toEqual({
+            received: 1,
+            handled: 1,
+            handlerFailed: 1,
+            noHandler: 1,
+            dlq: 1,
+        });
+    });
+
+    test("rpc counters", () => {
+        m.rpcCalled();
+        m.rpcSucceeded();
+        m.rpcFailed();
+        m.rpcTimedOut();
+        m.rpcHandlerExecuted();
+        m.rpcHandlerFailed();
+        m.rpcPastDeadline();
+        const s = m.getSnapshot();
+        expect(s.rpc.called).toBe(1);
+        expect(s.rpc.succeeded).toBe(1);
+        expect(s.rpc.failed).toBe(1);
+        expect(s.rpc.timedOut).toBe(1);
+        expect(s.rpc.handlerExecuted).toBe(1);
+        expect(s.rpc.handlerFailed).toBe(1);
+        expect(s.rpc.pastDeadline).toBe(1);
+    });
+
+    test("outbox claimed is summable, not +1", () => {
+        m.outboxClaimed(5);
+        m.outboxClaimed(3);
+        m.outboxPublished(4);
+        m.outboxPublishFailed();
+        const s = m.getSnapshot();
+        expect(s.outbox.claimed).toBe(8);
+        expect(s.outbox.published).toBe(4);
+        expect(s.outbox.publishFailed).toBe(1);
+    });
+
+    test("circuit breaker counters", () => {
+        m.cbTripped();
+        m.cbRejected();
+        m.cbRejected();
+        const s = m.getSnapshot();
+        expect(s.circuitBreaker).toEqual({ trips: 1, rejected: 2 });
+    });
+
+    test("snapshot is a deep copy", () => {
+        m.emitDirect();
+        const s1 = m.getSnapshot();
+        s1.emit.direct = 9999;
+        const s2 = m.getSnapshot();
+        expect(s2.emit.direct).toBe(1);
+    });
+
+    test("reset zeroes all counters", () => {
+        m.emitDirect();
+        m.rpcFailed();
+        m.eventDlq();
+        m.reset();
+        const s = m.getSnapshot();
+        expect(s.emit.direct).toBe(0);
+        expect(s.rpc.failed).toBe(0);
+        expect(s.events.dlq).toBe(0);
+    });
+});

package/tests/unit/remote/mockRedisStreamServer.test.ts

@@ -0,0 +1,104 @@
+import { describe, test, expect } from "bun:test";
+import { MockRedisStreamServer } from "../../helpers/MockRedisStreamServer";
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+describe("MockRedisStreamServer", () => {
+    test("xadd + xlen + xrange basics", () => {
+        const s = new MockRedisStreamServer();
+        const id1 = s.xadd("k", "*", "data", "v1");
+        const id2 = s.xadd("k", "*", "data", "v2");
+        expect(s.xlen("k")).toBe(2);
+        const r = s.xrange("k", "-", "+");
+        expect(r.length).toBe(2);
+        expect(r[0][0]).toBe(id1);
+        expect(r[1][0]).toBe(id2);
+    });
+
+    test("xgroup CREATE MKSTREAM + xreadgroup with > delivers entries", async () => {
+        const s = new MockRedisStreamServer();
+        s.xgroup("CREATE", "k", "g", "$", "MKSTREAM");
+        s.xadd("k", "*", "data", "v1");
+        const r: any = await s.xreadgroup(
+            "GROUP", "g", "c1",
+            "COUNT", 10,
+            "BLOCK", 50,
+            "STREAMS", "k", ">"
+        );
+        expect(r).not.toBeNull();
+        expect(r[0][0]).toBe("k");
+        expect(r[0][1][0][1]).toEqual(["data", "v1"]);
+    });
+
+    test("xack removes from PEL", async () => {
+        const s = new MockRedisStreamServer();
+        s.xgroup("CREATE", "k", "g", "$", "MKSTREAM");
+        s.xadd("k", "*", "data", "v1");
+        const r: any = await s.xreadgroup(
+            "GROUP", "g", "c1",
+            "COUNT", 10,
+            "BLOCK", 50,
+            "STREAMS", "k", ">"
+        );
+        const msgId = r[0][1][0][0];
+        expect(s.getPelSize("k", "g")).toBe(1);
+        s.xack("k", "g", msgId);
+        expect(s.getPelSize("k", "g")).toBe(0);
+    });
+
+    test("xautoclaim claims PEL entries past idle, increments deliveryCount", async () => {
+        const s = new MockRedisStreamServer();
+        s.xgroup("CREATE", "k", "g", "$", "MKSTREAM");
+        s.xadd("k", "*", "data", "v1");
+        await s.xreadgroup(
+            "GROUP", "g", "c1",
+            "COUNT", 10,
+            "BLOCK", 50,
+            "STREAMS", "k", ">"
+        );
+        await wait(20);
+        const result: any = s.xautoclaim("k", "g", "c2", 1, "0-0");
+        expect(result[0]).toBe("0-0");
+        expect(result[1]).toHaveLength(1);
+
+        const pending: any = s.xpending("k", "g", "-", "+", 100);
+        expect(pending.length).toBe(1);
+        expect(pending[0][1]).toBe("c2");
+        expect(pending[0][3]).toBe(2);
+    });
+
+    test("xpending detail form returns delivery count", async () => {
+        const s = new MockRedisStreamServer();
+        s.xgroup("CREATE", "k", "g", "$", "MKSTREAM");
+        s.xadd("k", "*", "data", "v1");
+        const r: any = await s.xreadgroup(
+            "GROUP", "g", "c1",
+            "COUNT", 10,
+            "BLOCK", 50,
+            "STREAMS", "k", ">"
+        );
+        const msgId = r[0][1][0][0];
+        const detail: any = s.xpending("k", "g", msgId, msgId, 1);
+        expect(detail[0][0]).toBe(msgId);
+        expect(detail[0][3]).toBe(1);
+    });
+
+    test("MAXLEN trims old entries", () => {
+        const s = new MockRedisStreamServer();
+        for (let i = 0; i < 5; i++) {
+            s.xadd("k", "MAXLEN", "~", 2, "*", "data", `v${i}`);
+        }
+        expect(s.xlen("k")).toBe(2);
+    });
+
+    test("xread with $ blocks until new entry", async () => {
+        const s = new MockRedisStreamServer();
+        s.xadd("k", "*", "data", "before");
+        const readPromise = s.xread("COUNT", 10, "BLOCK", 200, "STREAMS", "k", "$");
+        await wait(30);
+        s.xadd("k", "*", "data", "after");
+        const r: any = await readPromise;
+        expect(r).not.toBeNull();
+        expect(r[0][1][0][1]).toEqual(["data", "after"]);
+    });
+});

package/tests/unit/storage/S3StorageProvider.test.ts

@@ -378,11 +378,9 @@ describe("S3StorageProvider", () => {
 
         it("returns false on failure", async () => {
             const client = createMockS3Client({
-                file: mock(() => ({
-                    arrayBuffer: async () => {
-                        throw new Error("Read failed");
-                    },
-                })),
+                stat: mock(async () => {
+                    throw new Error("Stat failed");
+                }),
             });
             const provider = new S3StorageProvider(
                 { bucket: "my-bucket" },
@@ -413,11 +411,9 @@ describe("S3StorageProvider", () => {
 
         it("returns false if copy fails", async () => {
             const client = createMockS3Client({
-                file: mock(() => ({
-                    arrayBuffer: async () => {
-                        throw new Error("Read failed");
-                    },
-                })),
+                stat: mock(async () => {
+                    throw new Error("Stat failed");
+                }),
             });
             const provider = new S3StorageProvider(
                 { bucket: "my-bucket" },