@anteros/core 0.0.39 → 0.0.41

package/types/collection.d.ts

@@ -8,6 +8,7 @@ import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
 import type { ActionsApiList, ApiAccess, ApiActions } from "./api";
 import type { Server as SocketIO } from "socket.io";
+import type { CollectionReplicationConfig } from "./replication";
 
 /** Context passed to a collection custom action (`define.Action`). */
 export type CollectionActionContext = {
@@ -85,6 +86,8 @@ export type Collection = {
         /** Default TTL for cached queries — human string ('5m', '2h') or ms */
         ttl?: string | number;
     };
+    /** Opt-in one-way replication to destination databases — see `ReplicationConfig`. */
+    replication?: CollectionReplicationConfig;
     /**
      * The tenant id of the collection
      * @type {string}

package/types/config.d.ts

@@ -7,6 +7,8 @@ import type { Service } from "./service";
 import type { Script } from "./scripts";
 import type { FileCollection } from "./file";
 import type { McpTool, McpResource } from "./mcp";
+import type { VarDefinition } from "./vars";
+import type { AuditFileConfig } from "../lib/audit";
 export type ServerConfig = {
     debug?: boolean;
     version?: string;
@@ -21,9 +23,70 @@ export type ServerConfig = {
         metricsPort?: number;
         /** When true, trusts proxy headers (CF-Connecting-IP / X-Forwarded-For) as the client IP. Default: false. */
         trustProxy?: boolean;
+        /**
+         * Audit trail defaults for every tenant. A tenant declaring its own
+         * `tenant.audit` always wins (even `false`).
+         */
+        audit?: {
+            /**
+             * How long `_audit_` entries are kept (MongoDB TTL on `ts`).
+             * Duration string: `'90d'`, `'24h'`.
+             * `false` → explicitly disabled (drops the TTL index if one exists).
+             * Omitted → untouched: entries are kept forever.
+             */
+            retention?: string | false;
+            /**
+             * Local append-only JSONL copy of the audit trail (one file per day,
+             * rotated on size, pruned by age).
+             * `true` → defaults, `string` → directory, object → full options.
+             * `false` / omitted → disabled.
+             */
+            file?: AuditFileConfig;
+            /**
+             * Object keys whose value is replaced by `"[redacted]"` in every audit
+             * entry (`operation.input`, `operation.result` and `meta`), at any depth,
+             * case-insensitively. `false` → disabled.
+             *
+             * Default: password, passwd, pwd, token, authorization, apikey, api_key,
+             * key, secret, cookie, otp, pin.
+             */
+            redact?: string[] | false;
+            /**
+             * What an audit entry keeps of the operation's **result**
+             * (default: `'summary'`).
+             *
+             * - `'summary'` (default) → the **generated identifiers** (`_id`,
+             *   `insertedIds`) plus the operational counters (`matchedCount`,
+             *   `modifiedCount`, `deletedCount`, `nIndexesWas`…). Never a document:
+             *   the data lives in the collection (and in its replications).
+             * - `'none'`    → the generated identifiers only.
+             * - `'full'`    → the raw result, documents included.
+             *
+             * Reads (`find`, `findOne`, `aggregate`, streams, `watch`) and custom
+             * actions/services never store a result, whatever this setting.
+             */
+            results?: 'none' | 'summary' | 'full';
+        };
         body?: {
             maxSize?: number;
         };
+        /**
+         * Boot mode (default: `'full'`).
+         *
+         * - `'full'` — HTTP API **and** the replication engine.
+         * - `'replication-only'` — a process dedicated to the replication engine: no
+         *   HTTP API, no websocket handlers, no scripts, no services, no MCP tools,
+         *   no middlewares. Loaded: tenant databases, collections, file collections,
+         *   variables and lifecycle hooks (`beforeBoot` / `onDestroy`).
+         * - `'no-replication'` — a full server that never starts the replication
+         *   engine (no scheduling, no tombstones, no `_replication_` state).
+         * - `'api-only'` — the HTTP API and nothing around it: no replication, no
+         *   scripts, no sockets.
+         *
+         * Flags always win over this setting: `--replication-only`, `--no-replication`,
+         * `--api-only`, `--no-scripts`, `--no-sockets`.
+         */
+        mode?: 'full' | 'replication-only' | 'no-replication' | 'api-only';
         cors?: {
             origin: string | string[] | ((ctx: { origin: string, c: Context }) => string | string[]);
             credentials?: boolean;
@@ -123,4 +186,5 @@ export type Config = ServerConfig & {
     fileCollections?: FileCollection[]
     mcpTools?: McpTool[]
     mcpResources?: McpResource[]
+    vars?: VarDefinition[]
 }

package/types/file.d.ts

@@ -4,6 +4,7 @@ import type { HooksCollection } from "./hook";
 import type Joi from "joi";
 import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
+import type { CollectionReplicationConfig } from "./replication";
 
 type FileAccessHandler = (ctx: {
     rest: InstanceType<typeof useRest>;
@@ -42,6 +43,8 @@ export type FileCollection = {
     };
     /** Metadata fields stored alongside the file document */
     fields?: Field[];
+    /** Opt this file collection into the data replication engine (its documents). */
+    replication?: CollectionReplicationConfig;
     /** Upload validation rules */
     upload?: {
         /** Allowed MIME types for upload.
@@ -103,7 +106,7 @@ export type FileCollection = {
             /** Private key path for SSH auth */
             privateKey?: string;
         }[];
-        /** Enregistrer les métadonnées du fichier en base. Défaut: true */
+        /** Save the file metadata in the database. Default: true */
         trackMetaData?: boolean;
     api?: {
         access?: FileApiAccess;

package/types/lifecycle.d.ts

@@ -0,0 +1,71 @@
+import type { useRest } from "../database/rest";
+import type { Tenant } from "./tenant";
+import type { Config } from "./config";
+import type { logger } from "../utils/logger";
+import type { Server as SocketIO } from "socket.io";
+import type { TenantReplicationApi } from "./replication";
+
+/** Signal that triggered the shutdown. */
+export type LifecycleReason = "SIGINT" | "SIGTERM";
+
+/** Base context shared by every lifecycle hook. `rest` is tenant-scoped. */
+export type LifecycleContext = {
+    tenant: Tenant;
+    rest: InstanceType<typeof useRest>;
+    logger: typeof logger;
+    cfg: Config;
+    /** Tenant-scoped replication API — `reset()`, `seed()`, `now()`, `state()` (no tenant id needed). */
+    replication: TenantReplicationApi;
+};
+
+/** Context of `beforeBoot` — runs before replication and before the HTTP server listens. */
+export type LifecycleBootContext = LifecycleContext;
+
+/** Context of `afterBoot` — runs once the server is listening. */
+export type LifecycleReadyContext = LifecycleContext & {
+    io: SocketIO;
+    server: ReturnType<typeof Bun.serve>;
+};
+
+/** Context of `onDestroy` — runs on SIGINT/SIGTERM, before replication stops and DB clients close. */
+export type LifecycleDestroyContext = LifecycleContext & {
+    reason: LifecycleReason;
+};
+
+/**
+ * Per-tenant lifecycle — one `lifecycle.ts` at the tenant root.
+ *
+ * @example
+ * ```ts
+ * export default define.Lifecycle({
+ *   beforeBoot: async ({ rest, tenant }) => { await rest.insertOne('settings', { tenant: tenant.id }) },
+ *   afterBoot: async ({ server, logger }) => { logger.info(`ready on :${server.port}`) },
+ *   onDestroy: async ({ reason }) => { await flushSomething(reason) },
+ * })
+ * ```
+ */
+export type Lifecycle = {
+    _isLifecycle_?: boolean;
+    /** Injected by the loader — the tenant this lifecycle belongs to. */
+    _tenant_?: string;
+    /** Turn this lifecycle off without removing the file (default: true). */
+    enabled?: boolean;
+    /**
+     * Blocking — runs after databases are connected and collections are loaded,
+     * before replication starts and before the HTTP server listens. Ideal for
+     * migrations, seeding, warmup. Throwing aborts the boot.
+     */
+    beforeBoot?: (ctx: LifecycleBootContext) => Promise<void> | void;
+    /**
+     * Runs once the server is listening (after `Bun.serve`). Ideal for
+     * notifications and cache warming. Errors are logged, never fatal.
+     */
+    afterBoot?: (ctx: LifecycleReadyContext) => Promise<void> | void;
+    /**
+     * Runs on SIGINT/SIGTERM, before replication stops and tenant DB clients
+     * close — so `rest` is still usable. Errors are logged; shutdown proceeds.
+     */
+    onDestroy?: (ctx: LifecycleDestroyContext) => Promise<void> | void;
+    /** Max time (ms) allowed for `onDestroy` before shutdown proceeds anyway (default: 10000). */
+    destroyTimeout?: number;
+};

package/types/replication.d.ts

@@ -0,0 +1,199 @@
+import type { MongoClientOptions } from "mongodb";
+
+/** When to run replication — either a cron expression or a fixed interval. */
+export type ReplicationSchedule =
+    | { cron: string }
+    | { interval: string | number };
+
+/**
+ * Initial synchronization mode — how replication starts when no `_replication_`
+ * state exists yet.
+ * - `"full"` — backfill everything (default)
+ * - `"skip"` — ignore existing documents, start from now
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationInitialSync = "full" | "skip" | "latest" | (string & {}) | Date;
+
+/** A destination database that receives replicated documents. */
+export type ReplicationDestination = {
+    /** Unique identifier — used as the `_replication_` state key (required). */
+    id: string;
+    /** MongoDB connection string (required). */
+    uri: string;
+    /** Database name override — defaults to the name in the URI. */
+    name?: string;
+    /** Extra MongoDB client options (pool size, timeouts…). */
+    options?: MongoClientOptions;
+    /** Restrict replication to these collection slugs (default: all enabled). */
+    collections?: string[];
+    /** Turn this destination off without removing it. */
+    enabled?: boolean;
+};
+
+/** Per-tenant replication configuration (source → destination, one-way). */
+export type ReplicationConfig = {
+    /** Enable/disable replication for this scope (default: true when `destinations` is non-empty). */
+    enabled?: boolean;
+    /** Scheduling — `{ cron }` or `{ interval }` (default: every 5 minutes). */
+    schedule?: ReplicationSchedule;
+    /** Date key used for incremental replication (default: `'updatedAt'`). */
+    key?: string;
+    /**
+     * Rewind the cursor by this many milliseconds on each run, so documents
+     * written slightly out of order (clock skew) are not missed (default: 0).
+     */
+    lookback?: number;
+    /** Documents transferred per batch (default: 1000). */
+    batchSize?: number;
+    /** Run a first replication right after boot (default: true). */
+    runOnBoot?: boolean;
+    /**
+     * How the initial synchronization starts when no `_replication_` state exists
+     * yet (default: `'full'`). Use `'skip'` or `'latest'` to avoid the full
+     * backfill when the destination is already pre-loaded (e.g. via `mongorestore`).
+     */
+    initialSync?: ReplicationInitialSync;
+    /** Destination databases (required). */
+    destinations: ReplicationDestination[];
+};
+
+/** Per-collection opt-in replication. */
+export type CollectionReplicationConfig = {
+    /** Opt this collection into replication (required). */
+    enabled: boolean;
+    /** Date key override — defaults to `replication.key`. */
+    key?: string;
+    /** Initial sync override — defaults to `replication.initialSync`. */
+    initialSync?: ReplicationInitialSync;
+};
+
+export type ReplicationStatus = "idle" | "running" | "success" | "error";
+
+/** Cursor of the last replicated document — `value` is the date key, `id` the tie-breaker. */
+export type ReplicationCursor = {
+    value: Date | null;
+    id: any;
+};
+
+export type ReplicationStats = {
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+};
+
+/** State document persisted in `_replication_`, one per (tenant, destination, collection). */
+export type ReplicationState = {
+    _id: string;
+    type: "state";
+    tenant: string;
+    destination: string;
+    collection: string;
+    key: string;
+    cursor: ReplicationCursor;
+    status: ReplicationStatus;
+    lastRunAt: Date | null;
+    lastError: string | null;
+    stats: ReplicationStats;
+    createdAt?: Date;
+    updatedAt: Date;
+};
+
+/** Tombstone document persisted in `_replication_` when a replicated document is deleted. */
+export type ReplicationDeleteMarker = {
+    _id: string;
+    type: "delete";
+    tenant: string;
+    collection: string;
+    docId: string;
+    deletedAt: Date;
+    /** Destination ids that already applied the delete. */
+    synced: string[];
+    updatedAt: Date;
+};
+
+/** Scope of a `replication.reset()` call. */
+export type ReplicationResetOptions = {
+    /** Only reset this destination id (default: every destination). */
+    destination?: string;
+    /** Only reset this collection slug (default: every replicated collection). */
+    collection?: string;
+    /**
+     * Also delete pending delete tombstones (default: true). Ignored when
+     * `destination` is set — tombstones are shared across destinations.
+     */
+    tombstones?: boolean;
+};
+
+/** Result of a `replication.reset()` call. */
+export type ReplicationResetResult = {
+    tenant: string;
+    /** State documents deleted (one per destination + collection). */
+    state: number;
+    /** Delete tombstones deleted. */
+    tombstones: number;
+};
+
+/**
+ * Where to (re)start replication from — accepted by `replication.seed()`.
+ * - `"now"` — start from now (same as `initialSync: 'skip'`)
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationSeedValue = "now" | "latest" | (string & {}) | Date;
+
+/** Scope of a `replication.seed()` call. */
+export type ReplicationSeedOptions = {
+    /** Only seed this destination id (default: every destination). */
+    destination?: string;
+    /** Only seed this collection slug (default: every replicated collection). */
+    collection?: string;
+    /** Optional `_id` tie-breaker for the cursor. */
+    id?: any;
+};
+
+/** Result of a `replication.seed()` call. */
+export type ReplicationSeedResult = {
+    tenant: string;
+    /** State documents written (one per destination + collection). */
+    seeded: number;
+};
+
+/** Shape of the `replication` namespace exported by the package (multi-tenant). */
+export type ReplicationApi = {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    now: (tenantId?: string) => Promise<ReplicationRunResult[]>;
+    state: (tenantId: string, destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (tenantId: string, opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (tenantId: string, value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/**
+ * Tenant-scoped replication API — like `rest`, the tenant is implicit. This is
+ * the `replication` passed to lifecycle hooks. Engine control (`start`/`stop`)
+ * stays on the global `ReplicationApi`.
+ */
+export type TenantReplicationApi = {
+    now: () => Promise<ReplicationRunResult[]>;
+    state: (destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/** Outcome of a single (tenant, destination, collection) replication. */
+export type ReplicationRunResult = {
+    tenant: string;
+    destination: string;
+    collection: string;
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+    error?: string;
+};

package/types/tenant.d.ts

@@ -1,9 +1,32 @@
 import type { Db, MongoClient, MongoClientOptions } from "mongodb";
+import type { ReplicationConfig } from "./replication";
+import type { AuditFileConfig } from "../lib/audit";
 export type Tenant = {
     id: string;
     name?: string;
     description?: string;
     dir: string;
+    /** Per-tenant replication — each tenant has its own destinations and schedule. */
+    replication?: ReplicationConfig;
+    /**
+     * Audit trail (`_audit_`) — query indexes are always ensured in the background,
+     * retention is opt-in.
+     */
+    audit?: {
+        /**
+         * How long audit entries are kept, as a MongoDB TTL index on `ts`.
+         * Duration string: `'90d'`, `'24h'`, `'30m'`.
+         * `false` → explicitly disabled (drops the TTL index if one exists).
+         * Omitted → untouched: entries are kept forever.
+         */
+        retention?: string | false;
+        /**
+         * Local append-only JSONL copy of this tenant's audit trail.
+         * `true` → defaults, `string` → directory, object → full options.
+         * `false` → explicitly disabled (overrides `server.audit.file`).
+         */
+        file?: AuditFileConfig;
+    };
     routes?: {
         prefix?: string;
     },

package/types/vars.d.ts

@@ -0,0 +1,147 @@
+import type { Field } from "./field";
+import type { useRest } from "../database/rest";
+import type { fn } from "../lib/error";
+import type { jwt } from "../utils/func";
+
+/** Actions exposed by the variables HTTP API (`POST /vars/:tenant_id/:action`). */
+export type VarsActions =
+    | "set"
+    | "setMany"
+    | "get"
+    | "entry"
+    | "entries"
+    | "all"
+    | "del"
+    | "has"
+    | "incr"
+    | "expire"
+    | "clear";
+
+/** Access rule context for a vars action. */
+export type VarsAccessContext = {
+    rest: InstanceType<typeof useRest>;
+    /** Namespace targeted by the request. */
+    namespace: string;
+    /** Raw request body. */
+    body: any;
+    error: typeof fn.error;
+    jwt: typeof jwt;
+    token: { value: string | null; decoded: Record<string, unknown> | null; provided: boolean; expired: boolean };
+};
+
+/** Per-action access rules — `'*'` wildcard, same pattern as collections. */
+export type VarsAccess = {
+    [key in VarsActions | (string & {})]?: boolean | ((ctx: VarsAccessContext) => boolean | Promise<boolean>);
+};
+
+/** HTTP API configuration of a vars namespace (declared in `define.Vars`). */
+export type VarsApi = {
+    /** Access rules per action — **no rules = denied** (secure by default). */
+    access?: VarsAccess;
+};
+
+/**
+ * Value spec for a variable — a `Field` (minus `name`) plus an optional default
+ * TTL. Use it when a variable needs a type / validation / a default value / a TTL:
+ *
+ * ```ts
+ * vars: {
+ *   maxUsers: 100,                                  // shorthand: raw default
+ *   licence: { type: 'string', defaultValue: 'RDX00', ttl: '30d' },
+ * }
+ * ```
+ */
+export type VarSpec = Omit<Field, "name"> & {
+    /** Default TTL for this variable — human string (`'30m'`, `'2h'`, `'1d'`) or ms. */
+    ttl?: string | number;
+};
+
+/** Per-namespace replication opt-in (`define.Vars({ replication: { enabled: true } })`). */
+export type VarsReplicationConfig = {
+    /** Replicate the `_vars_` documents of THIS namespace. */
+    enabled: boolean;
+};
+
+/**
+ * A tenant variable definition — `{tenant.dir}/vars/**\/*.var.ts`.
+ *
+ * - `scope` — **one** optional identity field (often a `relationship`): its value
+ *   is part of the entry key, so each company/branch/environment gets its own value.
+ * - `meta` — annotation fields: validated, stored alongside — **never** part of the key.
+ * - `vars` — values: a raw default, or a `VarSpec`.
+ */
+export type VarDefinition = {
+    _isVars_?: boolean;
+    /** Injected by the loader — the tenant this definition belongs to. */
+    _tenant_?: string;
+    /** Namespace grouping these variables (required). */
+    namespace: string;
+    /** Optional identity field — its value is part of the entry key. */
+    scope?: Field;
+    /** Annotation fields — validated, never part of the key. */
+    meta?: Field[];
+    /** Variables — a raw default value, or a `VarSpec`. */
+    vars: Record<string, any>;
+    /** HTTP API access rules — required to expose this namespace over `POST /vars/:tenant_id/:action`. */
+    api?: VarsApi;
+    /** Opt this namespace into replication — like a collection, but scoped to this namespace. */
+    replication?: VarsReplicationConfig;
+};
+
+/** A stored variable entry, as returned by `rest.vars.entry()` / `.entries()`. */
+export type VarEntry<T = any> = {
+    ns: string;
+    key: string;
+    scope: any;
+    value: T;
+    meta: Record<string, any>;
+    expiresAt: Date | null;
+    createdAt?: Date;
+    updatedAt: Date;
+};
+
+/** Scope option shared by every `rest.vars` method. */
+export type VarsOptions = { scope?: any };
+
+export type VarsSetOptions = VarsOptions & {
+    /** Annotation values — validated against the namespace `meta` fields. */
+    meta?: Record<string, any>;
+    /** Time-to-live — human string or ms. Pass `null` to clear an existing TTL. */
+    ttl?: string | number | null;
+};
+
+export type VarsAllOptions = VarsOptions & {
+    /** Filter on `meta` fields (e.g. `{ note: 'x' }` → `{ 'meta.note': 'x' }`). */
+    where?: Record<string, any>;
+};
+
+/**
+ * Tenant-scoped key/value store — `rest.vars` (like Redis, MongoDB-backed).
+ * The tenant is implicit (like every `rest.*` accessor).
+ */
+export type TenantVars = {
+    /** Set a value. `ttl` replaces the entry's TTL (omit to store without expiry). */
+    set(ns: string, key: string, value: any, opts?: VarsSetOptions): Promise<void>;
+    /** Set several keys at once (shared `meta` / `ttl`). */
+    setMany(ns: string, entries: Record<string, any>, opts?: VarsSetOptions): Promise<void>;
+    /** Read a value — `undefined` when missing or expired. */
+    get<T = any>(ns: string, key: string, opts?: VarsOptions): Promise<T | undefined>;
+    /** Read the full entry (value + meta + expiry). */
+    entry<T = any>(ns: string, key: string, opts?: VarsOptions): Promise<VarEntry<T> | undefined>;
+    /** All entries of a namespace (current scope). */
+    entries(ns: string, opts?: VarsAllOptions): Promise<VarEntry[]>;
+    /** All key/value pairs of a namespace (current scope). */
+    all(ns: string, opts?: VarsAllOptions): Promise<Record<string, any>>;
+    /** Delete a key — `true` when a key was removed. */
+    del(ns: string, key: string, opts?: VarsOptions): Promise<boolean>;
+    /** Whether a (non-expired) key exists. */
+    has(ns: string, key: string, opts?: VarsOptions): Promise<boolean>;
+    /** Atomic increment (default `1`) — does not clear an existing TTL. */
+    incr(ns: string, key: string, by?: number, opts?: VarsSetOptions): Promise<number>;
+    /** Set / renew the TTL of an existing key. */
+    expire(ns: string, key: string, ttl: string | number, opts?: VarsOptions): Promise<boolean>;
+    /** Delete every key of the namespace in the current scope. */
+    clear(ns: string, opts?: VarsOptions): Promise<number>;
+    /** Bound store with the scope pre-filled — `rest.vars.scope(companyId)`. */
+    scope(value: any): TenantVars;
+};