@anteros/core 0.0.40 → 0.0.42

package/tests/fixtures/workflow-engine/workflows/failing.workflow.ts

@@ -0,0 +1,34 @@
+// Test fixture — `b` always fails, `a` must be compensated (once, never twice).
+// Also proves the step ctx `rest` is a real tenant client.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "failing",
+    name: "Failing",
+    version: 1,
+    steps: [
+        {
+            id: "a",
+            exec: async ({ rest }: any) => {
+                state.log.push(`failing:a:rest=${typeof rest?.find === "function" ? "client" : "engine"}`);
+                // A sub-workflow, through the client handed to the step
+                await rest.workflow.run("simple", { echo: "sub" });
+                state.log.push("failing:a:sub-workflow-done");
+                return { a: 1 };
+            },
+        },
+        { id: "b", exec: async () => { state.log.push("failing:b"); throw new Error("boom-b"); } },
+        { id: "c", exec: async () => { state.log.push("failing:c"); return { c: 1 }; } },
+    ],
+    compensations: [
+        {
+            id: "undo-a",
+            depend: ["a"],
+            exec: async () => {
+                state.attempts["undo-a"] = (state.attempts["undo-a"] ?? 0) + 1;
+                state.log.push(`failing:undo-a:${state.attempts["undo-a"]}`);
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/flaky.workflow.ts

@@ -0,0 +1,23 @@
+// Test fixture — a step that fails until `data.failUntil` attempts are reached,
+// with retries. Used to prove a transient failure does not roll the saga back.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "flaky",
+    name: "Flaky",
+    version: 1,
+    steps: [
+        {
+            id: "unstable",
+            retries: 2,
+            backoffMs: 1,
+            exec: async ({ data }: any) => {
+                const n = (state.attempts.unstable = (state.attempts.unstable ?? 0) + 1);
+                state.log.push(`flaky:attempt:${n}`);
+                if (n <= (data?.failUntil ?? 0)) throw new Error(`transient failure ${n}`);
+                return { attempts: n };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/hang.workflow.ts

@@ -0,0 +1,17 @@
+// Test fixture — a step that outlives its `timeout` (150ms vs 1s by default).
+export default {
+    _isWorkflow_: true,
+    id: "hang",
+    name: "Hang",
+    version: 1,
+    steps: [
+        {
+            id: "hang",
+            timeout: "150ms",
+            exec: async ({ data }: any) => {
+                await new Promise((resolve) => setTimeout(resolve, data?.ms ?? 1000));
+                return { done: true };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/simple.workflow.ts

@@ -0,0 +1,19 @@
+// Test fixture — one step, always succeeds. Shared in-process state:
+// `globalThis.__wfEngine = { log: string[], attempts: Record<string, number> }`
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "simple",
+    name: "Simple",
+    version: 1,
+    steps: [
+        {
+            id: "one",
+            exec: async ({ data }: any) => {
+                state.log.push("simple:one");
+                return { echo: data?.echo ?? null };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/slow.workflow.ts

@@ -0,0 +1,23 @@
+// Test fixture — three steps, the middle one slow: lets a test pause or cancel
+// the run while it is executing (and check that the last step never runs).
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "slow",
+    name: "Slow",
+    version: 1,
+    steps: [
+        { id: "fast", exec: async () => { state.log.push("slow:fast"); return { fast: true }; } },
+        {
+            id: "slow",
+            exec: async ({ data }: any) => {
+                state.log.push("slow:slow:start");
+                await new Promise((resolve) => setTimeout(resolve, data?.ms ?? 300));
+                state.log.push("slow:slow:end");
+                return { slow: true };
+            },
+        },
+        { id: "last", exec: async () => { state.log.push("slow:last"); return { last: true }; } },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/versioned.workflow.ts

@@ -0,0 +1,19 @@
+// Test fixture — used to check the resume version guard: the test mutates
+// `version` on the registered definition after a run has started.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "versioned",
+    name: "Versioned",
+    version: 1,
+    steps: [
+        {
+            id: "v",
+            exec: async () => {
+                state.log.push("versioned:v");
+                return { ok: true };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-tenant/workflows/broken.workflow.ts

@@ -0,0 +1,3 @@
+// Test fixture — throws while being imported: the loader must isolate the
+// failure and keep loading the other workflows of the tenant.
+throw new Error("boom — broken workflow fixture");

package/tests/fixtures/workflow-tenant/workflows/disabled.workflow.ts

@@ -0,0 +1,8 @@
+// Test fixture — `enabled: false` must not be registered.
+export default {
+    _isWorkflow_: true,
+    enabled: false,
+    id: "nightly",
+    name: "Nightly",
+    steps: [{ id: "run", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/invoice.workflow.ts

@@ -0,0 +1,21 @@
+// Test fixture — a second valid workflow, with a different `version` so tests
+// can assert on a definition that is not the duplicated `order`.
+export default {
+    _isWorkflow_: true,
+    id: "invoice",
+    name: "Invoices",
+    version: 3,
+    context: {
+        companyId: { type: "string", index: true },   // → index context.companyId_1
+        processedAt: { type: "date" },                 // validated + coerced to a Date
+    },
+    // Beyond `context.index`: compound, unique, sparse, named
+    indexes: [
+        { key: { "context.companyId": 1, status: 1 } },
+        { key: { "context.batchId": 1 }, unique: true, sparse: true, name: "uniq_batch" },
+    ],
+    steps: [
+        { id: "generate", exec: async ({ data }: any) => ({ generated: data?.ref ?? null }) },
+        { id: "send", exec: async () => ({ sent: true }) },
+    ],
+};

package/tests/fixtures/workflow-tenant/workflows/no-id.workflow.ts

@@ -0,0 +1,7 @@
+// Test fixture — no `id`: must be ignored (with a warning), not registered
+// under a bogus `undefined` key.
+export default {
+    _isWorkflow_: true,
+    name: "Anonymous",
+    steps: [{ id: "run", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/order-duplicate.workflow.ts

@@ -0,0 +1,13 @@
+// Test fixture — same `id` as order.workflow.ts: the duplicate must be reported
+// and only one definition kept (never two entries, never a crash). The context
+// declaration is identical on purpose: whichever file wins, the indexes exist.
+export default {
+    _isWorkflow_: true,
+    id: "order",
+    name: "Orders (duplicate definition)",
+    context: {
+        customerId: { type: "string", index: true },
+        total: { type: "number", index: -1 },
+    },
+    steps: [{ id: "charge", exec: async () => ({ charged: false }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/order.workflow.ts

@@ -0,0 +1,17 @@
+// Test fixture — a valid, enabled workflow with declared context fields.
+export default {
+    _isWorkflow_: true,
+    enabled: true,
+    id: "order",
+    name: "Orders",
+    version: 2,
+    context: {
+        customerId: { type: "string", index: true },   // → index context.customerId_1
+        total: { type: "number", index: -1 },          // → index context.total_-1
+        note: { type: "string" },                      // not indexed
+    },
+    steps: [
+        { id: "charge", exec: async ({ data }: any) => ({ charged: data?.ref ?? null }) },
+        { id: "notify", exec: async () => ({ notified: true }) },
+    ],
+};

package/tests/hono.test.ts

@@ -182,16 +182,19 @@ describe("rate limiting (in-memory)", () => {
     it("login limiter uses a distinct counter (not blocked by global)", async () => {
         cfg.server.rateLimit = { enabled: true, windowMs: 60_000, max: 100, login: { max: 2 } };
         const app = createApp();
-        app.post("/api/x/login", (c) => c.json({ ok: true }));
         app.get("/echo", (c) => c.json({ ok: true }));
         const server = Bun.serve({ port: 0, fetch: app.fetch });
         const url = `${base(server)}`;
 
+        // The login limiter has its own bucket: the third call is refused even though
+        // the global limit (100) is nowhere near. What the framework answers before
+        // that (unknown tenant here) is not the point.
         const statuses: number[] = [];
         for (let i = 0; i < 3; i++) {
-            statuses.push((await fetch(`${url}/api/x/login`, { method: "POST" })).status);
+            statuses.push((await fetch(`${url}/api/x/collections/users/login`, { method: "POST" })).status);
         }
-        expect(statuses).toEqual([200, 200, 429]);
+        expect(statuses.slice(0, 2).some((status) => status === 429)).toBe(false);
+        expect(statuses[2]).toBe(429);
 
         // same IP on a normal route → still allowed (distinct key)
         expect((await fetch(`${url}/echo`)).status).toBe(200);

package/tests/lifecycle.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { formatConfig } from "../server/config";
+import { loadLifecycles, runBeforeBoot, runAfterBoot, runOnDestroy } from "../lib/lifecycle";
+import { define } from "../lib/define";
+
+const DIRS: Record<string, string> = {
+    normal: "packages/core/tests/fixtures/lc-normal",
+    thrower: "packages/core/tests/fixtures/lc-throw",
+    hang: "packages/core/tests/fixtures/lc-hang",
+    disabled: "packages/core/tests/fixtures/lc-disabled",
+};
+
+/** Configure cfg with a single tenant pointing at the given fixture dir. */
+function useFixture(id: string) {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id, dir: DIRS[id]!, database: { uri: "mongodb://localhost:27017/_LC_TEST" } }],
+    });
+}
+
+const callsOf = (key: string): string[] => ((globalThis as any)[key] ??= []);
+
+beforeEach(() => {
+    (globalThis as any).__lcNormal = [];
+    (globalThis as any).__lcHang = [];
+    (globalThis as any).__lcDisabled = [];
+});
+
+describe("define.Lifecycle", () => {
+    it("marks the config and defaults enabled to true", () => {
+        const lc = define.Lifecycle({ beforeBoot: () => {} });
+        expect(lc._isLifecycle_).toBe(true);
+        expect(lc.enabled).toBe(true);
+    });
+
+    it("keeps an explicit enabled: false", () => {
+        const lc = define.Lifecycle({ enabled: false });
+        expect(lc.enabled).toBe(false);
+    });
+});
+
+describe("lifecycle hooks", () => {
+    it("runs beforeBoot, afterBoot and onDestroy in order", async () => {
+        useFixture("normal");
+        await loadLifecycles();
+
+        await runBeforeBoot();
+        await runAfterBoot({ port: 4000 } as any, {} as any);
+        await runOnDestroy("SIGTERM");
+
+        expect(callsOf("__lcNormal")).toEqual(["beforeBoot", "afterBoot", "onDestroy:SIGTERM"]);
+        // `replication` is tenant-bound in the hook context (like `rest`)
+        expect((globalThis as any).__lcReplicationApi).toBe(true);
+    });
+
+    it("aborts the boot when beforeBoot throws (fail-fast)", async () => {
+        useFixture("thrower");
+        await loadLifecycles();
+
+        await expect(runBeforeBoot()).rejects.toThrow(/boom/);
+    });
+
+    it("bounds onDestroy with destroyTimeout instead of hanging", async () => {
+        useFixture("hang");
+        await loadLifecycles();
+
+        const started = Date.now();
+        await runOnDestroy("SIGINT"); // must resolve despite a hook that never resolves
+        const elapsed = Date.now() - started;
+
+        expect(callsOf("__lcHang")).toEqual(["onDestroy:start"]);
+        expect(elapsed).toBeGreaterThanOrEqual(100);
+        expect(elapsed).toBeLessThan(2000);
+    });
+
+    it("skips a disabled lifecycle", async () => {
+        useFixture("disabled");
+        await loadLifecycles();
+
+        await runBeforeBoot();
+        await runAfterBoot({} as any, {} as any);
+        await runOnDestroy("SIGINT");
+
+        expect(callsOf("__lcDisabled")).toEqual([]);
+    });
+
+    it("tolerates a tenant without a lifecycle.ts file", async () => {
+        formatConfig({
+            server: { port: 4000 },
+            tenants: [{ id: "nofile", dir: "packages/core/tests/fixtures/does-not-exist", database: { uri: "mongodb://localhost:27017/_LC_TEST" } }],
+        });
+        await loadLifecycles();
+        await expect(runBeforeBoot()).resolves.toBeUndefined();
+        await expect(runOnDestroy("SIGTERM")).resolves.toBeUndefined();
+    });
+});

package/tests/locks.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import os from "node:os";
+import { useRest } from "../database/rest";
+import { formatConfig } from "../server/config";
+import { syncTenants } from "../database/tenant";
+
+const TENANT = "locks-test";
+const DB = "mongodb://localhost:27017/_LOCKS_TEST";
+
+let rest: InstanceType<typeof useRest>;
+
+/** Write a lock document as if another process had taken it */
+async function seedLock(name: string, opts: { pid?: number; hostname?: string; expiresAt: number }) {
+    await rest.db.collection("_locks_").insertOne({
+        _id: `${TENANT}:${name}` as any,
+        tid: TENANT,
+        name,
+        acquiredAt: Date.now() - 1000,
+        expiresAt: opts.expiresAt,
+        ...(opts.pid !== undefined ? { pid: opts.pid } : {}),
+        ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    } as any);
+}
+
+const lockDoc = (name: string) => rest.db.collection("_locks_").findOne({ _id: `${TENANT}:${name}` as any });
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: "src", database: { uri: DB } }],
+    });
+    await syncTenants();
+    rest = new useRest({ tenant_id: TENANT, internal: true });
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("_locks_").drop(); } catch (_) {}
+    try { await rest.db.collection("_workflows_").drop(); } catch (_) {}
+    try { await rest.db.collection("_replication_").drop(); } catch (_) {}
+});
+
+describe("distributed lock", () => {
+    it("records the owning pid and hostname", async () => {
+        await rest.lock("l-pid");
+        const doc: any = await lockDoc("l-pid");
+        expect(doc.pid).toBe(process.pid);
+        expect(doc.hostname).toBe(os.hostname());
+        await rest.unlock("l-pid");
+    });
+
+    it("refuses a second acquisition from the same process (its own pid is not stale)", async () => {
+        await rest.lock("l-self");
+        await expect(rest.lock("l-self")).rejects.toThrow(/already held/);
+        await rest.unlock("l-self");
+    });
+
+    it("takes over a lock whose local process is gone, without waiting for the TTL", async () => {
+        // A process that has exited: its pid no longer exists
+        const dead = Bun.spawn(["true"]);
+        const deadPid = dead.pid;
+        await dead.exited;
+
+        await seedLock("l-dead", { pid: deadPid, hostname: os.hostname(), expiresAt: Date.now() + 60_000 });
+
+        await rest.lock("l-dead");
+        const doc: any = await lockDoc("l-dead");
+        expect(doc.pid).toBe(process.pid);
+        await rest.unlock("l-dead");
+    });
+
+    it("waits for a lock whose local process is still alive", async () => {
+        const alive = Bun.spawn(["sleep", "5"]);
+        try {
+            await seedLock("l-alive", { pid: alive.pid, hostname: os.hostname(), expiresAt: Date.now() + 60_000 });
+
+            await expect(rest.lock("l-alive")).rejects.toThrow(/already held/);
+
+            // …and the lock is taken over as soon as that process is gone
+            alive.kill();
+            await alive.exited;
+
+            await rest.lock("l-alive");
+            const doc: any = await lockDoc("l-alive");
+            expect(doc.pid).toBe(process.pid);
+            await rest.unlock("l-alive");
+        } finally {
+            try { alive.kill(); } catch (_) {}
+        }
+    }, 20_000);
+
+    it("takes over an expired lock", async () => {
+        await seedLock("l-expired", { pid: 999_999, hostname: "another-host", expiresAt: Date.now() - 1000 });
+
+        await rest.lock("l-expired");
+        const doc: any = await lockDoc("l-expired");
+        expect(doc.pid).toBe(process.pid);
+        await rest.unlock("l-expired");
+    });
+
+    it("never releases a lock owned by another process", async () => {
+        await seedLock("l-other", { pid: 4242, hostname: "another-host", expiresAt: Date.now() + 60_000 });
+
+        await rest.unlock("l-other"); // not ours
+        expect(await lockDoc("l-other")).not.toBeNull();
+
+        // Ours is released
+        await rest.lock("l-ours");
+        await rest.unlock("l-ours");
+        expect(await lockDoc("l-ours")).toBeNull();
+
+        await rest.db.collection("_locks_").deleteOne({ name: "l-other" });
+    });
+
+    it("only takes over a remote lock when it expired (a foreign pid cannot be probed)", async () => {
+        await seedLock("l-remote", { pid: 1, hostname: "some-other-host", expiresAt: Date.now() + 60_000 });
+
+        await expect(rest.lock("l-remote")).rejects.toThrow(/already held/);
+        await rest.db.collection("_locks_").deleteOne({ name: "l-remote" });
+    });
+});

package/tests/mcp.test.ts

@@ -62,7 +62,7 @@ describe("syncMcpTools", () => {
     });
 });
 
-describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
+describe("MCP protocol (GET/POST /api/:tenant_id/mcp)", () => {
     it("serves tools/list and tools/call over JSON-RPC", async () => {
         cfg.tenants = [{ id: TENANT, dir: TENANT_DIR, database: { uri: "mongodb://localhost:27017/none" } }];
         await syncMcpTools();
@@ -72,7 +72,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         const url = server.url.href.replace(/\/$/, "");
 
         // 1. tools/list
-        const listRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const listRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
@@ -84,7 +84,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(tools.some((t: any) => t.name === "badge")).toBe(true);
 
         // 1b. resources/list — static resources
-        const resListRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const resListRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 9, method: "resources/list", params: {} }),
@@ -94,7 +94,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(resources.some((r: any) => r.uri === "orders://summary")).toBe(true);
 
         // 1c. resources/templates/list
-        const tmplRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const tmplRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 10, method: "resources/templates/list", params: {} }),
@@ -104,7 +104,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(templates.some((t: any) => t.uriTemplate === "users://{id}")).toBe(true);
 
         // 1d. resources/read — static URI
-        const readRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "orders://summary" } }),
@@ -114,7 +114,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readText).toContain("\"total\":42");
 
         // 1e. resources/read — template URI with params
-        const readTplRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readTplRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 12, method: "resources/read", params: { uri: "users://abc123" } }),
@@ -123,7 +123,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readTpl?.result?.contents?.[0]?.text ?? "").toContain("\"id\":\"abc123\"");
 
         // 1f. resources/read — unknown URI → error
-        const readBadRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readBadRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 13, method: "resources/read", params: { uri: "nope://x" } }),
@@ -132,7 +132,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readBad?.error).toBeDefined();
 
         // 2. tools/call (valid args + Joi defaults)
-        const callRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const callRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -148,7 +148,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(block.text ?? "").toContain("\"times\":1");
 
         // 2b. protocol content blocks pass through unchanged (image block)
-        const badgeRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const badgeRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -161,7 +161,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(badge?.result?.content?.[0]?.mimeType).toBe("image/png");
 
         // 2b. invalid args → isError (Joi validation)
-        const badRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const badRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -174,7 +174,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(bad?.result?.content?.[0]?.text ?? "").toContain("Invalid arguments");
 
         // 3. unknown tenant → 404
-        const notFound = await fetch(`${url}/mcp/ghost`, {
+        const notFound = await fetch(`${url}/api/ghost/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 4, method: "tools/list", params: {} }),