@anteros/core 0.0.39 → 0.0.41

package/tests/file-collection-replication.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+
+const TEST_TENANT = "files-repl";
+const SRC_DB = "mongodb://localhost:27017/_FILES_REPL_SRC";
+const DEST_DB = "mongodb://localhost:27017/_FILES_REPL_DEST";
+const SLUG = "photos";
+
+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: "backup", uri: DEST_DB }],
+            },
+        }],
+    });
+
+    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).fileCollections = [{
+        _tenant_: TEST_TENANT,
+        _isFileCollection_: true,
+        slug: SLUG,
+        fields: [{ name: "label", type: "string" }],
+        api: { access: { "*": true } },
+        // Opt the file collection's documents into the data replication engine.
+        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 (_) {}
+});
+
+const destDoc = (label: string) => destClient.db().collection(SLUG).findOne({ label });
+
+describe("file collection replication", () => {
+    it("replicates file-collection documents", async () => {
+        await rest.insertOne(SLUG, { label: "a", _file: { filename: "a.png" } });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destDoc("a");
+        expect(dest).toBeDefined();
+        expect((dest as any)._file.filename).toBe("a.png");
+    });
+
+    it("propagates deletions via tombstones", async () => {
+        const doc: any = await rest.insertOne(SLUG, { label: "del-me" });
+        await replicateTenant(TEST_TENANT);
+        expect(await destDoc("del-me")).toBeDefined();
+
+        await rest.deleteOne(SLUG, doc._id);
+        await replicateTenant(TEST_TENANT);
+        expect(await destDoc("del-me")).toBeNull();
+    });
+
+    it("does not replicate a file collection that did not opt in", async () => {
+        (cfg as any).fileCollections.push({
+            _tenant_: TEST_TENANT,
+            _isFileCollection_: true,
+            slug: "private-files",
+            fields: [],
+            api: { access: { "*": true } },
+        });
+
+        await rest.insertOne("private-files", { label: "secret" });
+        await replicateTenant(TEST_TENANT);
+
+        expect(await destClient.db().collection("private-files").findOne({ label: "secret" })).toBeNull();
+    });
+});

package/tests/fixtures/index-tenant/collections/variants.model.ts

@@ -1,8 +1,8 @@
 import { define } from "../../../../index";
 
 // Reproduces the Mongo error `sparse: null is not convertible to bool`:
-// `indexOptions.sparse` explicit à null doit être ignoré (jamais envoyé à Mongo),
-// et `unique` accepte le style Mongo 1/0 (coercé en vrai booléen).
+// an explicit `indexOptions.sparse: null` must be ignored (never sent to Mongo),
+// and `unique` accepts the Mongo 1/0 style (coerced to a real boolean).
 export default define.Collection({
     slug: "variants",
     fields: [

package/tests/fixtures/lc-disabled/lifecycle.ts

@@ -0,0 +1,11 @@
+// Test fixture — disabled lifecycle (must be skipped).
+const calls: string[] = [];
+(globalThis as any).__lcDisabled = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: false,
+    beforeBoot: async () => { calls.push("beforeBoot"); },
+    afterBoot: async () => { calls.push("afterBoot"); },
+    onDestroy: async () => { calls.push("onDestroy"); },
+};

package/tests/fixtures/lc-hang/lifecycle.ts

@@ -0,0 +1,13 @@
+// Test fixture — `onDestroy` never resolves (used to test destroyTimeout).
+const calls: string[] = [];
+(globalThis as any).__lcHang = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    destroyTimeout: 100,
+    onDestroy: async () => {
+        calls.push("onDestroy:start");
+        await new Promise(() => { /* never resolves */ });
+    },
+};

package/tests/fixtures/lc-normal/lifecycle.ts

@@ -0,0 +1,23 @@
+// Test fixture — records lifecycle calls on globalThis.
+const calls: string[] = [];
+(globalThis as any).__lcNormal = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    destroyTimeout: 200,
+    beforeBoot: async ({ replication }: any) => {
+        calls.push("beforeBoot");
+        // The API is tenant-bound (like `rest`) — no tenant id is passed, and the
+        // implicit tenant must match this lifecycle's tenant.
+        const seeded = await replication.seed("latest");
+        (globalThis as any).__lcReplicationApi =
+            typeof replication?.seed === "function" &&
+            typeof replication?.reset === "function" &&
+            typeof replication?.now === "function" &&
+            typeof replication?.state === "function" &&
+            seeded?.tenant === "normal";
+    },
+    afterBoot: async () => { calls.push("afterBoot"); },
+    onDestroy: async ({ reason }: any) => { calls.push(`onDestroy:${reason}`); },
+};

package/tests/fixtures/lc-throw/lifecycle.ts

@@ -0,0 +1,6 @@
+// Test fixture — `beforeBoot` throws.
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    beforeBoot: async () => { throw new Error("boom"); },
+};

package/tests/fixtures/repl-only/app.ts

@@ -0,0 +1,26 @@
+/**
+ * Fixture — boots the server through `bootApp`, to be launched with a boot mode
+ * flag (see `packages/core/tests/replication-only.test.ts`).
+ * Port and database URIs are overridable through the environment so the same
+ * fixture serves every mode without clashes.
+ *
+ * Run manually:
+ *   bun packages/core/tests/fixtures/repl-only/app.ts --replication-only
+ *   bun packages/core/tests/fixtures/repl-only/app.ts --no-replication
+ */
+import { bootApp } from "../../../server/boot";
+
+await bootApp({
+    server: { port: Number(Bun.env.RO_PORT ?? 5556) },
+    tenants: [{
+        id: "ro",
+        dir: "packages/core/tests/fixtures/repl-only/tenant",
+        database: { uri: Bun.env.RO_SRC ?? "mongodb://localhost:27017/_RO_SRC" },
+        replication: {
+            enabled: true,
+            runOnBoot: true,
+            schedule: { interval: "1h" },
+            destinations: [{ id: "backup", uri: Bun.env.RO_DST ?? "mongodb://localhost:27017/_RO_DST" }],
+        },
+    }],
+});

package/tests/fixtures/repl-only/tenant/collections/orders.model.ts

@@ -0,0 +1,14 @@
+// Test fixture — a replicable collection (plain object + marker, no import needed).
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "orders",
+    fields: [
+        { name: "ref", type: "string" },
+        { name: "total", type: "number" },
+    ],
+    api: { access: { "*": true } },
+    // Opt this collection into the data replication engine
+    replication: { enabled: true },
+};

package/tests/fixtures/repl-only/tenant/lifecycle.ts

@@ -0,0 +1,14 @@
+// Test fixture — `beforeBoot` / `onDestroy` must still run in replication-only
+// mode (the documented place to seed or reset a replication before it starts).
+// Each hook drops a marker file the test can assert on.
+// (`enabled` mirrors what `define.Lifecycle` sets by default.)
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    beforeBoot: async () => {
+        await Bun.write(new URL("./.markers/lifecycle.txt", import.meta.url), "beforeBoot");
+    },
+    onDestroy: async () => {
+        await Bun.write(new URL("./.markers/onDestroy.txt", import.meta.url), "onDestroy");
+    },
+};

package/tests/fixtures/repl-only/tenant/scripts/probe.run.ts

@@ -0,0 +1,8 @@
+// Test fixture — must NOT run in replication-only mode (no `runScripts`).
+export default {
+    _isScript_: true,
+    enabled: true,
+    exec: async () => {
+        await Bun.write(new URL("../.markers/script.txt", import.meta.url), "ran");
+    },
+};

package/tests/fixtures/vars-tenant/vars/config.var.ts

@@ -0,0 +1,23 @@
+// Test fixture — a `define.Vars` definition (plain object + marker).
+export default {
+    _isVars_: true,
+    namespace: "config",
+    scope: { name: "company", type: "relationship", relation: { to: "companies" } },
+    meta: [
+        { name: "note", type: "string" },
+        { name: "expiresAt", type: "datetime-local" },
+    ],
+    vars: {
+        licence: "RDX00",
+        maxUsers: { type: "number", defaultValue: 100 },
+        session: { type: "string", ttl: "1h" },
+    },
+    api: {
+        access: {
+            "*": true,
+            set: true,
+        },
+    },
+    // Opt this namespace into replication (per-namespace filter on `ns`).
+    replication: { enabled: true },
+};

package/tests/fixtures/vars-tenant/vars/private.var.ts

@@ -0,0 +1,6 @@
+// Test fixture — a namespace WITHOUT `api.access` (must be denied over HTTP).
+export default {
+    _isVars_: true,
+    namespace: "private",
+    vars: { secret: "shh" },
+};

package/tests/index-spec.test.ts

@@ -7,8 +7,8 @@ const TENANT = "idx-test";
 const DIR = "packages/core/tests/fixtures/index-tenant";
 const DB = "mongodb://localhost:27017/_DB_IDX_TEST";
 
-// initializeOnDatabase est fire-and-forget dans syncCollections — on attend
-// que les index existent réellement en base.
+// initializeOnDatabase is fire-and-forget inside syncCollections — wait until the
+// indexes really exist in the database.
 async function waitForIndexes(colName: string): Promise<any[]> {
     const db = cfg.tenants?.[0]?.database?.db as any;
     const col = db.collection(colName);
@@ -40,13 +40,13 @@ describe("index spec construction", () => {
     it("drops null/undefined options and coerces Mongo-style 1/0 booleans", async () => {
         const idxs = await waitForIndexes("variants");
 
-        // name : indexOptions.sparse = null → ignoré (pas de sparse:null), index créé
+        // name: indexOptions.sparse = null → ignored (no sparse:null sent), index created
         const nameIdx = idxs.find((i) => i.name === "name_1");
         expect(nameIdx).toBeDefined();
         expect(nameIdx!.sparse).not.toBe(null);
-        expect(nameIdx!.sparse).not.toBe(true); // false / undefined — jamais null
+        expect(nameIdx!.sparse).not.toBe(true); // false / undefined — never null
 
-        // sku : unique: 1 (Mongo-style) → index unique réel
+        // sku: unique: 1 (Mongo-style) → a real unique index
         const skuIdx = idxs.find((i) => i.name === "sku_1");
         expect(skuIdx).toBeDefined();
         expect(skuIdx!.unique).toBe(true);

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/replication-control.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import {
+    startReplication,
+    stopReplication,
+    replicateTenant,
+    getReplicationState,
+    resetReplication,
+    seedReplication,
+} from "../database/replication";
+
+const TEST_TENANT = "replreset";
+const SRC_DB = "mongodb://localhost:27017/_REPL_RESET_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_RESET_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 }],
+            },
+        }],
+    });
+
+    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" }],
+            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 reset", () => {
+    it("clears state and re-runs from scratch", async () => {
+        await rest.insertOne("orders", { title: `reset-${crypto.randomUUID()}` });
+        await replicateTenant(TEST_TENANT);
+
+        const before = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(before.length).toBe(1);
+        expect(before[0]!.status).toBe("success");
+
+        const result = await resetReplication(TEST_TENANT);
+        expect(result.state).toBeGreaterThanOrEqual(1);
+
+        const after = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(after.length).toBe(0);
+
+        // Next run re-creates the state (fresh cursor)
+        await replicateTenant(TEST_TENANT);
+        const recreated = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(recreated.length).toBe(1);
+        expect(recreated[0]!.cursor.value).not.toBeNull();
+    });
+
+    it("supports scoping by destination", async () => {
+        await resetReplication(TEST_TENANT, { destination: DEST_ID });
+        const state = await getReplicationState(TEST_TENANT, DEST_ID);
+        expect(state.length).toBe(0);
+    });
+});
+
+describe("replication seed", () => {
+    const findDest = (title: string) => destClient.db().collection("orders").findOne({ title });
+
+    it("seeds 'latest' so pre-existing documents are skipped", async () => {
+        await resetReplication(TEST_TENANT);
+        const preMarker = `pre-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: preMarker });
+
+        const res = await seedReplication(TEST_TENANT, "latest");
+        expect(res.seeded).toBe(1);
+
+        await replicateTenant(TEST_TENANT);
+        expect(await findDest(preMarker)).toBeNull(); // nothing backfilled
+
+        await Bun.sleep(5);
+        const postMarker = `post-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: postMarker });
+        await replicateTenant(TEST_TENANT);
+
+        expect(await findDest(postMarker)).toBeDefined(); // only the new document
+    });
+
+    it("seeds from an explicit date", async () => {
+        await resetReplication(TEST_TENANT);
+        const res = await seedReplication(TEST_TENANT, "2020-01-01T00:00:00Z");
+        expect(res.seeded).toBe(1);
+
+        const state = await getReplicationState(TEST_TENANT, DEST_ID, "orders");
+        expect(state.length).toBe(1);
+        expect((state[0]!.cursor.value as any).toISOString()).toBe("2020-01-01T00:00:00.000Z");
+    });
+});

package/tests/replication-initial-sync.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+
+const TEST_TENANT = "replinit";
+const SRC_DB = "mongodb://localhost:27017/_REPL_INIT_SRC";
+const DEST_DB = "mongodb://localhost:27017/_REPL_INIT_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 }],
+            },
+        }],
+    });
+
+    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" },
+            ],
+            // Start at the latest document — skip everything that already exists.
+            replication: { enabled: true, initialSync: "latest" },
+        },
+    ];
+
+    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 initialSync", () => {
+    it("skips pre-existing documents with initialSync: 'latest'", async () => {
+        await rest.insertOne("orders", { title: `old-1-${crypto.randomUUID()}` });
+        await rest.insertOne("orders", { title: `old-2-${crypto.randomUUID()}` });
+
+        await replicateTenant(TEST_TENANT);
+
+        const count = await destClient.db().collection("orders").countDocuments();
+        expect(count).toBe(0); // existing docs are NOT backfilled
+    });
+
+    it("replicates documents added after the initial sync", async () => {
+        await Bun.sleep(5); // ensure the new doc has a strictly newer updatedAt
+
+        const marker = `new-${crypto.randomUUID()}`;
+        await rest.insertOne("orders", { title: marker });
+
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destClient.db().collection("orders").findOne({ title: marker });
+        expect(dest).toBeDefined();
+    });
+});