@anteros/core 0.0.39 → 0.0.41

package/tests/replication-only.test.ts

@@ -0,0 +1,358 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import { MongoClient } from "mongodb";
+import { parseBootFlags, resolveCapabilities, capabilitiesLabel, conflictingBootFlags, FULL_CAPABILITIES } from "../server/flags";
+
+const FIXTURE = "packages/core/tests/fixtures/repl-only";
+const MARKERS = path.join(FIXTURE, "tenant", ".markers");
+const SRC = "mongodb://localhost:27017/_RO_SRC";
+const DST = "mongodb://localhost:27017/_RO_DST";
+const PORT = 5556;
+
+let proc: any;
+let src: MongoClient;
+let dst: MongoClient;
+let output = "";
+
+/** Poll `check` until it returns true (or throw after `timeout`) */
+async function waitFor(check: () => Promise<boolean>, timeout = 20_000, step = 250): Promise<boolean> {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        if (await check()) return true;
+        await Bun.sleep(step);
+    }
+    return false;
+}
+
+describe("boot capabilities", () => {
+    const flags = (over: Partial<ReturnType<typeof parseBootFlags>> = {}) => ({
+        replicationOnly: false, noReplication: false, apiOnly: false, noScripts: false, noSockets: false,
+        ...over,
+    });
+
+    it("reads every flag (and its camelCase spelling)", () => {
+        expect(parseBootFlags(["bun", "index.ts", "--replication-only"]).replicationOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--replicationOnly"]).replicationOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--no-replication"]).noReplication).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--api-only"]).apiOnly).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--noScripts"]).noScripts).toBe(true);
+        expect(parseBootFlags(["bun", "index.ts", "--no-sockets"]).noSockets).toBe(true);
+
+        expect(parseBootFlags(["bun", "index.ts"])).toEqual(flags());
+    });
+
+    it("resolves the named modes", () => {
+        expect(resolveCapabilities(flags())).toEqual(FULL_CAPABILITIES);
+
+        expect(resolveCapabilities(flags(), "replication-only")).toEqual({
+            api: false, replication: true, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags(), "api-only")).toEqual({
+            api: true, replication: false, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags(), "no-replication")).toEqual({
+            api: true, replication: false, scripts: true, sockets: true,
+        });
+    });
+
+    it("lets the flags win over the configured mode", () => {
+        expect(resolveCapabilities(flags({ apiOnly: true }), "full")).toEqual({
+            api: true, replication: false, scripts: false, sockets: false,
+        });
+        expect(resolveCapabilities(flags({ replicationOnly: true }), "no-replication")).toEqual({
+            api: false, replication: true, scripts: false, sockets: false,
+        });
+        // the most restrictive flag wins
+        expect(resolveCapabilities(flags({ replicationOnly: true, apiOnly: true })).api).toBe(false);
+    });
+
+    it("disables one capability at a time", () => {
+        expect(resolveCapabilities(flags({ noScripts: true }))).toEqual({
+            api: true, replication: true, scripts: false, sockets: true,
+        });
+        expect(resolveCapabilities(flags({ noSockets: true }))).toEqual({
+            api: true, replication: true, scripts: true, sockets: false,
+        });
+        expect(resolveCapabilities(flags({ noReplication: true }))).toEqual({
+            api: true, replication: false, scripts: true, sockets: true,
+        });
+    });
+
+    it("labels the mode for the banner", () => {
+        expect(capabilitiesLabel(FULL_CAPABILITIES)).toBe("full");
+        expect(capabilitiesLabel({ api: false, replication: true, scripts: false, sockets: false })).toBe("replication-only");
+        expect(capabilitiesLabel({ api: true, replication: false, scripts: false, sockets: false })).toBe("api-only");
+        // granular flags stay in `full` — the banner lists what is off
+        expect(capabilitiesLabel({ api: true, replication: true, scripts: false, sockets: true })).toBe("full");
+    });
+
+    it("reports contradictory flags", () => {
+        expect(conflictingBootFlags(flags({ replicationOnly: true, noReplication: true }))).toBe(true);
+        expect(conflictingBootFlags(flags({ replicationOnly: true, apiOnly: true }))).toBe(true);
+        expect(conflictingBootFlags(flags({ replicationOnly: true }))).toBe(false);
+        expect(conflictingBootFlags(flags({ apiOnly: true, noScripts: true }))).toBe(false);
+    });
+});
+
+describe("replication-only boot", () => {
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        src = new MongoClient(SRC);
+        dst = new MongoClient(DST);
+        await src.connect();
+        await dst.connect();
+        await src.db().collection("orders").drop().catch(() => {});
+        await dst.db().collection("orders").drop().catch(() => {});
+        await dst.db().collection("_replication_").drop().catch(() => {});
+
+        proc = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--replication-only"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        // Drain the pipes (a full buffer would block the child)
+        for (const stream of [proc.stdout, proc.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    output += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        // A document written to the source must reach the destination on its own
+        await src.db().collection("orders").insertOne({ ref: "RO-1", total: 42 } as any);
+    });
+
+    afterAll(async () => {
+        try { proc?.kill(); } catch {}
+        try { await src?.close(); } catch {}
+        try { await dst?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("replicates the tenant data", async () => {
+        const replicated = await waitFor(async () =>
+            (await dst.db().collection("orders").countDocuments({ ref: "RO-1" })) === 1,
+        );
+        expect(replicated, `no replication after 20s — app output:\n${output}`).toBe(true);
+
+        const onTarget: any = await dst.db().collection("orders").findOne({ ref: "RO-1" });
+        expect(onTarget.total).toBe(42);
+    }, 30_000);
+
+    it("exposes no HTTP API", async () => {
+        // `/health` is registered by the framework — if anything were listening, it would answer
+        const refused = await fetch(`http://localhost:${PORT}/health`)
+            .then(() => false)
+            .catch(() => true);
+        expect(refused, "a server is listening on the configured port").toBe(true);
+    });
+
+    it("still runs the lifecycle hooks", async () => {
+        const ran = await waitFor(async () => fs.existsSync(path.join(MARKERS, "lifecycle.txt")));
+        expect(ran, `beforeBoot did not run — app output:\n${output}`).toBe(true);
+    }, 30_000);
+
+    it("does not run the tenant scripts", async () => {
+        // give the (skipped) scripts path a chance to fire
+        await Bun.sleep(500);
+        expect(fs.existsSync(path.join(MARKERS, "script.txt"))).toBe(false);
+    });
+
+    it("keeps the process alive (replication timers are unref'd)", async () => {
+        await Bun.sleep(300);
+        expect(proc.exitCode, `the process exited — output:\n${output}`).toBeNull();
+    });
+
+    it("stops replication cleanly on SIGTERM (onDestroy runs)", async () => {
+        proc.kill("SIGTERM");
+
+        const exited = await waitFor(async () => proc.exitCode !== null, 10_000, 100);
+        expect(exited, `the process did not exit — output:\n${output}`).toBe(true);
+        expect(proc.exitCode).toBe(0);
+
+        const destroyed = await waitFor(async () => fs.existsSync(path.join(MARKERS, "onDestroy.txt")));
+        expect(destroyed, `onDestroy did not run — output:\n${output}`).toBe(true);
+    }, 30_000);
+});
+
+describe("no-replication boot", () => {
+    const PORT = 5557;
+    const SRC = "mongodb://localhost:27017/_NOREP_SRC";
+    const DST = "mongodb://localhost:27017/_NOREP_DST";
+
+    let procNo: any;
+    let srcNo: MongoClient;
+    let dstNo: MongoClient;
+    let outputNo = "";
+
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        srcNo = new MongoClient(SRC);
+        dstNo = new MongoClient(DST);
+        await srcNo.connect();
+        await dstNo.connect();
+        await srcNo.db().collection("orders").drop().catch(() => {});
+        await dstNo.db().collection("orders").drop().catch(() => {});
+
+        procNo = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--no-replication"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        for (const stream of [procNo.stdout, procNo.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    outputNo += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        // Wait for the server to listen before writing to the source
+        await waitFor(async () => {
+            try {
+                await fetch(`http://localhost:${PORT}/health`);
+                return true;
+            } catch {
+                return false;
+            }
+        }, 20_000);
+
+        await srcNo.db().collection("orders").insertOne({ ref: "NOREP-1", total: 7 } as any);
+    });
+
+    afterAll(async () => {
+        try { procNo?.kill(); } catch {}
+        try { await srcNo?.close(); } catch {}
+        try { await dstNo?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("serves the HTTP API", async () => {
+        const res = await fetch(`http://localhost:${PORT}/health`);
+        expect(res.status).toBe(200);
+        expect(await res.json()).toBeDefined();
+    });
+
+    it("never starts the replication engine", async () => {
+        // give it more than enough time to replicate, if it were going to
+        await Bun.sleep(2_000);
+
+        expect(await dstNo.db().collection("orders").countDocuments({})).toBe(0);
+        // …and no replication state was created either
+        const state = await srcNo.db().listCollections({ name: "_replication_" }).toArray();
+        expect(state.length).toBe(0);
+    }, 15_000);
+
+    it("still serves the Socket.IO endpoint", async () => {
+        const res = await fetch(`http://localhost:${PORT}/socket.io/?EIO=4&transport=polling`);
+        expect(res.status).toBe(200);
+    }, 15_000);
+
+    it("is otherwise a full server (scripts run, lifecycle hooks run)", async () => {
+        const scripted = await waitFor(async () => fs.existsSync(path.join(MARKERS, "script.txt")));
+        const lifecycle = await waitFor(async () => fs.existsSync(path.join(MARKERS, "lifecycle.txt")));
+
+        expect(lifecycle, `beforeBoot did not run — output:\n${outputNo}`).toBe(true);
+        expect(scripted, `scripts did not run — output:\n${outputNo}`).toBe(true);
+    }, 20_000);
+});
+
+describe("api-only boot", () => {
+    const PORT = 5558;
+    const SRC = "mongodb://localhost:27017/_APIONLY_SRC";
+    const DST = "mongodb://localhost:27017/_APIONLY_DST";
+
+    let procApi: any;
+    let srcApi: MongoClient;
+    let dstApi: MongoClient;
+    let outputApi = "";
+
+    beforeAll(async () => {
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+
+        srcApi = new MongoClient(SRC);
+        dstApi = new MongoClient(DST);
+        await srcApi.connect();
+        await dstApi.connect();
+        await srcApi.db().collection("orders").drop().catch(() => {});
+        await dstApi.db().collection("orders").drop().catch(() => {});
+
+        procApi = Bun.spawn(["bun", `${FIXTURE}/app.ts`, "--api-only"], {
+            cwd: process.cwd(),
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { ...process.env, RO_PORT: String(PORT), RO_SRC: SRC, RO_DST: DST },
+        });
+
+        for (const stream of [procApi.stdout, procApi.stderr]) {
+            (async () => {
+                const reader = (stream as ReadableStream<Uint8Array>).getReader();
+                const decoder = new TextDecoder();
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    outputApi += decoder.decode(value, { stream: true });
+                }
+            })().catch(() => {});
+        }
+
+        await waitFor(async () => {
+            try {
+                await fetch(`http://localhost:${PORT}/health`);
+                return true;
+            } catch {
+                return false;
+            }
+        }, 20_000);
+
+        await srcApi.db().collection("orders").insertOne({ ref: "APIONLY-1", total: 3 } as any);
+    });
+
+    afterAll(async () => {
+        try { procApi?.kill(); } catch {}
+        try { await srcApi?.close(); } catch {}
+        try { await dstApi?.close(); } catch {}
+        fs.rmSync(MARKERS, { recursive: true, force: true });
+    });
+
+    it("serves the HTTP API", async () => {
+        const res = await fetch(`http://localhost:${PORT}/health`);
+        expect(res.status).toBe(200);
+    });
+
+    it("does not serve the Socket.IO endpoint", async () => {
+        const res = await fetch(`http://localhost:${PORT}/socket.io/?EIO=4&transport=polling`);
+        expect(res.status, `the socket endpoint answered — output:\n${outputApi}`).not.toBe(200);
+    }, 15_000);
+
+    it("does not run the tenant scripts", async () => {
+        // the scripts path would have fired ~150ms after boot — give it more
+        await Bun.sleep(1_500);
+        expect(fs.existsSync(path.join(MARKERS, "script.txt"))).toBe(false);
+        // …while the lifecycle still runs (it is part of a normal boot)
+        expect(fs.existsSync(path.join(MARKERS, "lifecycle.txt"))).toBe(true);
+    }, 15_000);
+
+    it("never starts the replication engine", async () => {
+        await Bun.sleep(1_500);
+        expect(await dstApi.db().collection("orders").countDocuments({})).toBe(0);
+        const state = await srcApi.db().listCollections({ name: "_replication_" }).toArray();
+        expect(state.length).toBe(0);
+    }, 15_000);
+});

package/tests/replication.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient, ObjectId } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import {
+    startReplication,
+    stopReplication,
+    replicateTenant,
+    getReplicationState,
+} from "../database/replication";
+
+const TEST_TENANT = "repl";
+const SRC_DB = "mongodb://localhost:27017/_REPL_TEST_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_TEST_DEST";
+const DEST_ID = "backup";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "src",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: DEST_ID, uri: DEST_DB }],
+            },
+        }],
+    });
+
+    // Connect the source DB manually with a short timeout so a missing MongoDB
+    // fails fast and clearly (instead of hanging or process.exit(1)).
+    sourceClient = new MongoClient(SRC_DB, { serverSelectionTimeoutMS: 3000 });
+    await sourceClient.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = sourceClient;
+    tenant.database.db = sourceClient.db();
+
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "orders",
+            fields: [
+                { name: "title", type: "string" },
+                { name: "status", type: "string" },
+                { name: "customer", type: "relationship", relation: { to: "customers" } },
+                { name: "paidAt", type: "date" },
+            ],
+            replication: { enabled: true },
+        },
+    ];
+
+    await startReplication();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+    destClient = new MongoClient(DEST_DB, { serverSelectionTimeoutMS: 3000 });
+    await destClient.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    try { await sourceClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.close(); } catch (_) {}
+    try { await sourceClient.close(); } catch (_) {}
+});
+
+describe("replication", () => {
+    it("replicates inserted documents", async () => {
+        const marker = `ins-${crypto.randomUUID()}`;
+        const source: any = await rest.insertOne("orders", { title: marker, status: "new" });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect((dest as any)?.status).toBe("new");
+        // The destination keeps the **same `_id`** (the upsert is keyed on it), same BSON type
+        expect((dest as any)?._id.toString()).toBe(source._id);
+        expect((dest as any)?._id).toBeInstanceOf(ObjectId);
+    });
+
+    it("keeps a custom `_id` type (string) as-is", async () => {
+        const marker = `custom-${crypto.randomUUID()}`;
+        const customId = `order-${crypto.randomUUID()}`; // not a 24-hex string
+        await sourceClient.db().collection("orders").insertOne({
+            _id: customId as any,
+            title: marker,
+            status: "new",
+            updatedAt: new Date(),
+        });
+        await replicateTenant(TEST_TENANT);
+
+        const dest: any = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect(dest._id).toBe(customId);
+        expect(typeof dest._id).toBe("string");
+    });
+
+    it("writes BSON types on the destination — ObjectId relations and Dates stay typed", async () => {
+        const marker = `bson-${crypto.randomUUID()}`;
+        const customerId = new ObjectId();
+        const paidAt = new Date("2026-03-04T05:06:07.000Z");
+
+        // Through the framework: the relation string and the ISO date are converted
+        // to BSON by `toBson` before hitting MongoDB.
+        const source: any = await rest.insertOne("orders", {
+            title: marker,
+            status: "paid",
+            customer: customerId.toHexString(),
+            paidAt: paidAt.toISOString(),
+        });
+        await replicateTenant(TEST_TENANT);
+
+        // …and the destination must hold the same BSON types, not strings
+        const dest: any = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+        expect(dest._id).toBeInstanceOf(ObjectId);
+        expect(dest._id.toString()).toBe(source._id);
+        expect(dest.customer).toBeInstanceOf(ObjectId);
+        expect(dest.customer.toString()).toBe(customerId.toHexString());
+        expect(dest.paidAt).toBeInstanceOf(Date);
+        expect(dest.paidAt.getTime()).toBe(paidAt.getTime());
+        expect(dest.createdAt).toBeInstanceOf(Date);
+        expect(dest.updatedAt).toBeInstanceOf(Date);
+
+        // The source itself stores the very same types (the copy is faithful)
+        const raw: any = await sourceClient.db().collection("orders").findOne({ title: marker });
+        expect(raw.customer).toBeInstanceOf(ObjectId);
+        expect(raw.paidAt).toBeInstanceOf(Date);
+        expect(typeof raw.customer).toBe(typeof dest.customer);
+    });
+
+    it("replicates updates", async () => {
+        const marker = `upd-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker, status: "draft" });
+        await replicateTenant(TEST_TENANT);
+
+        await rest.updateOne("orders", doc._id, { $set: { status: "paid" } });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect((dest as any)?.status).toBe("paid");
+    });
+
+    it("replicates deletes via tombstone", async () => {
+        const marker = `del-${crypto.randomUUID()}`;
+        const doc: any = await rest.insertOne("orders", { title: marker, status: "x" });
+        await replicateTenant(TEST_TENANT);
+
+        const before = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(before).toBeDefined();
+
+        await rest.deleteOne("orders", doc._id);
+        await replicateTenant(TEST_TENANT);
+
+        const after = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(after).toBeNull();
+    });
+
+    it("does not re-copy unchanged documents (cursor is persisted)", async () => {
+        const marker = `resume-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker, status: "new" });
+
+        const first = await replicateTenant(TEST_TENANT);
+        const second = await replicateTenant(TEST_TENANT);
+
+        const r1 = first.find((r) => r.collection === "orders" && r.destination === DEST_ID);
+        const r2 = second.find((r) => r.collection === "orders" && r.destination === DEST_ID);
+        expect(r1?.inserted).toBeGreaterThanOrEqual(1);
+        expect(r2?.inserted).toBe(0);
+        expect(r2?.updated).toBe(0);
+    });
+
+    it("stores state in _replication_", async () => {
+        await rest.insertOne("orders", { title: `state-${crypto.randomUUID()}`, status: "new" });
+        await replicateTenant(TEST_TENANT);
+
+        const state = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(state.length).toBe(1);
+        expect(state[0]!.status).toBe("success");
+        expect(state[0]!.cursor).toBeDefined();
+    });
+});