@absolutejs/sync 1.23.0 → 1.25.0

package/dist/engine/migrate.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Tenant migration primitives. Closes G7 from the deep-research
+ * audit: "move a tenant from engine A to engine B."
+ *
+ * The substrate offers three composable verbs:
+ *
+ * - **`engine.fence({ reason })`** — pause new mutations on the
+ *   source so its captured state stops drifting. Subscribers continue
+ *   to read; only `runMutation` rejects (with
+ *   {@link EngineFencedError}). Returns a {@link FenceHandle} with
+ *   `lift()` to undo.
+ * - **`engine.exportSnapshot({ tables?, ctx? })`** — walk the
+ *   registered readers and return a portable
+ *   {@link EngineSnapshot} carrying the source `instanceId`,
+ *   `version`, and current rows per table. Cheap and synchronous from
+ *   the operator's POV.
+ * - **`engine.importSnapshot(snapshot, options?)`** — on the target,
+ *   bulk-load the rows via each table's registered writer. Tracks
+ *   per-table progress. Returns a {@link MigrationImportResult} with
+ *   row counts.
+ *
+ * The intended choreography for a cross-region tenant move:
+ *
+ * ```ts
+ * // ── on the source ──
+ * const fence = source.fence({ reason: 'tenant-7 → us-east-2' });
+ * try {
+ *   const snapshot = await source.exportSnapshot();
+ *   await transport(snapshot); // S3, message bus, etc.
+ *   // ── on the target ──
+ *   await target.importSnapshot(snapshot, {
+ *     onProgress: (table, done, total) =>
+ *       console.log(`${table}: ${done}/${total}`)
+ *   });
+ *   await cutoverDns(); // direct clients at target
+ * } finally {
+ *   fence.lift();
+ * }
+ * ```
+ *
+ * Out of scope: out-of-band writes (CDC drivers, raw SQL) — the
+ * caller is responsible for pausing those before fencing, otherwise
+ * the captured snapshot drifts.
+ *
+ * Added in 1.24.0.
+ */
+/**
+ * Portable per-tenant state captured by
+ * {@link SyncEngine.exportSnapshot}. Consumed by
+ * {@link SyncEngine.importSnapshot} on the target engine.
+ */
+export type EngineSnapshot = {
+    /** The exporting engine's `instanceId` (for audit / forensics). */
+    sourceInstanceId: string;
+    /** Source engine's monotonic version at snapshot time. */
+    version: number;
+    /** `Date.now()` at export — used by hosts for staleness checks. */
+    exportedAt: number;
+    /** Current rows per table, read from each table's registered reader. */
+    tables: Record<string, ReadonlyArray<unknown>>;
+};
+/**
+ * Returned by {@link SyncEngine.importSnapshot}.
+ */
+export type MigrationImportResult = {
+    /** Number of tables that had at least one row imported. */
+    tablesImported: number;
+    /** Total rows inserted across all tables. */
+    rowsImported: number;
+    /** Rows inserted per table. Tables with zero rows are still listed. */
+    perTable: Record<string, number>;
+    /**
+     * Tables present in the snapshot that the target engine has no
+     * registered writer for — skipped silently. Surface this to
+     * operators so they can catch "I forgot to register `tasks` on
+     * the new shard" cleanly.
+     */
+    skipped: ReadonlyArray<string>;
+};
+/**
+ * Returned by {@link SyncEngine.fence}. Hold this and call `lift()`
+ * to re-enable mutations. Holding multiple fences is supported — the
+ * engine stays fenced until every handle has been lifted.
+ */
+export type FenceHandle = {
+    /** `Date.now()` at fence time. */
+    fencedAt: number;
+    /** Human-readable reason — surfaced on {@link EngineFencedError}. */
+    reason: string;
+    /** Re-enable mutations. Idempotent (later calls are no-ops). */
+    lift: () => void;
+};
+export type ExportSnapshotOptions = {
+    /**
+     * Narrow the export to a subset of registered tables. Useful for
+     * per-tenant cuts when readers expose `ctx`-scoped data.
+     */
+    tables?: ReadonlyArray<string>;
+    /**
+     * Context passed to each reader's `all(ctx)`. The default `{}`
+     * works for engines whose readers ignore context.
+     */
+    ctx?: unknown;
+};
+export type ImportSnapshotOptions = {
+    /**
+     * Narrow the import to a subset of tables in the snapshot.
+     * Tables outside the filter are skipped (NOT recorded in
+     * `skipped`; that field is for tables with no writer).
+     */
+    tables?: ReadonlyArray<string>;
+    /**
+     * Called for each row insertion. Fires synchronously inside the
+     * import loop; keep it cheap or schedule heavy work elsewhere.
+     */
+    onProgress?: (table: string, done: number, total: number) => void;
+    /**
+     * Context passed to each writer's `insert(data, ctx, tx)`. The
+     * default `{}` works for writers that ignore context.
+     */
+    ctx?: unknown;
+};
+/**
+ * Thrown by `runMutation` when the engine is fenced. The reason
+ * carries through so operators can correlate denied calls to the
+ * fence that caused them.
+ */
+export declare class EngineFencedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}

package/dist/engine/syncEngine.d.ts

@@ -10,6 +10,7 @@ import type { SearchCollectionDefinition } from './search';
 import type { ScheduleDefinition } from './schedule';
 import type { EngineActivity, EngineInspection, EngineMetrics } from './devtools';
 import type { SchemaDefinition, TableSchema } from './schema';
+import { type EngineSnapshot, type ExportSnapshotOptions, type FenceHandle, type ImportSnapshotOptions, type MigrationImportResult } from './migrate';
 import type { CrdtMergeable } from '../crdt';
 import type { ClusterBus } from './cluster';
 import type { ChangeSource, RowChange, ViewDiff } from './types';
@@ -324,6 +325,61 @@ export type SyncEngine = {
      * ```
      */
     replayTo: (options: ReplayOptions) => Promise<ReplayResult>;
+    /**
+     * Pause new mutations on the engine — the source half of the G7 tenant
+     * migration contract. While at least one fence is held, `runMutation`
+     * rejects with {@link EngineFencedError}; subscribe/hydrate continue to
+     * work, so live readers stay served while the snapshot is in flight.
+     *
+     * Multiple fence handles compose — the engine stays fenced until every
+     * handle has been `lift()`-ed. Lifting is idempotent.
+     *
+     * Out of scope: out-of-band writes (CDC drivers, raw SQL). The caller
+     * is responsible for halting those before fencing, otherwise the
+     * snapshot will drift between `exportSnapshot` and import on the target.
+     *
+     * Added in 1.24.0.
+     */
+    fence: (options: {
+        reason: string;
+    }) => FenceHandle;
+    /**
+     * Capture the engine's current per-table state into a portable
+     * {@link EngineSnapshot}. Walks every registered reader's `all(ctx)`
+     * and collects the rows. Used to ship a tenant between engines (G7).
+     *
+     * Pair with `fence()` on the source to stop drift, then
+     * `importSnapshot()` on the target. The shape is intentionally
+     * detached from `ChangeLogSnapshot` — snapshots carry live state, not
+     * history. Use `exportChangeLog()` separately if you need forensic
+     * continuity at the target instanceId.
+     *
+     * Added in 1.24.0.
+     *
+     * @example
+     * const fence = source.fence({ reason: 'tenant move' });
+     * try {
+     *   const snapshot = await source.exportSnapshot();
+     *   await target.importSnapshot(snapshot);
+     * } finally { fence.lift(); }
+     */
+    exportSnapshot: (options?: ExportSnapshotOptions) => Promise<EngineSnapshot>;
+    /**
+     * Bulk-load an {@link EngineSnapshot} into this engine via each table's
+     * registered writer. Tables present in the snapshot but missing a
+     * writer here are surfaced in `result.skipped` so the operator can
+     * detect a misconfigured target. The target half of the G7 migration
+     * contract.
+     *
+     * Inserts do NOT emit change events to subscribers — the import is
+     * meant to land on a fresh target whose clients will re-hydrate after
+     * the DNS cutover. If you need to fan changes out (e.g. mid-flight
+     * cutover), drain the change log via `streamChanges()` and
+     * `applyChange()` separately.
+     *
+     * Added in 1.24.0.
+     */
+    importSnapshot: (snapshot: EngineSnapshot, options?: ImportSnapshotOptions) => Promise<MigrationImportResult>;
     /**
      * Subscribe to the live engine activity stream (changes, mutation outcomes,
      * subscribe/unsubscribe). Returns an unsubscribe. Powers the devtools feed.

package/dist/index.js

@@ -139,51 +139,54 @@ var sync = ({
   path = "/sync",
   resolveTopics = defaultResolveTopics,
   heartbeatMs = 25000
-}) => new Elysia({ name: "@absolutejs/sync" }).get(path, (context) => {
-  const topics = resolveTopics({
-    query: context.query,
-    request: context.request
-  });
-  const encoder = new TextEncoder;
-  const stream = new ReadableStream({
-    start(controller) {
-      const write = (chunk) => {
-        try {
-          controller.enqueue(encoder.encode(chunk));
-        } catch {}
-      };
-      const send = (event) => {
-        write(`data: ${JSON.stringify(event)}
+}) => {
+  const app = new Elysia({ name: "@absolutejs/sync" }).get(path, (context) => {
+    const topics = resolveTopics({
+      query: context.query,
+      request: context.request
+    });
+    const encoder = new TextEncoder;
+    const stream = new ReadableStream({
+      start(controller) {
+        const write = (chunk) => {
+          try {
+            controller.enqueue(encoder.encode(chunk));
+          } catch {}
+        };
+        const send = (event) => {
+          write(`data: ${JSON.stringify(event)}
 
 `);
-      };
-      send({
-        topic: SYNC_OPEN_TOPIC,
-        at: Date.now(),
-        payload: { topics }
-      });
-      const unsubscribe = topics.length > 0 ? hub.subscribe(topics, send) : () => {};
-      const heartbeat = setInterval(() => write(`: ping
+        };
+        send({
+          topic: SYNC_OPEN_TOPIC,
+          at: Date.now(),
+          payload: { topics }
+        });
+        const unsubscribe = topics.length > 0 ? hub.subscribe(topics, send) : () => {};
+        const heartbeat = setInterval(() => write(`: ping
 
 `), heartbeatMs);
-      context.request.signal.addEventListener("abort", () => {
-        clearInterval(heartbeat);
-        unsubscribe();
-        try {
-          controller.close();
-        } catch {}
-      }, { once: true });
-    }
-  });
-  return new Response(stream, {
-    headers: {
-      "cache-control": "no-cache, no-transform",
-      connection: "keep-alive",
-      "content-type": "text/event-stream",
-      "x-accel-buffering": "no"
-    }
+        context.request.signal.addEventListener("abort", () => {
+          clearInterval(heartbeat);
+          unsubscribe();
+          try {
+            controller.close();
+          } catch {}
+        }, { once: true });
+      }
+    });
+    return new Response(stream, {
+      headers: {
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+        "content-type": "text/event-stream",
+        "x-accel-buffering": "no"
+      }
+    });
   });
-});
+  return app;
+};
 // src/engine/socket.ts
 import { Elysia as Elysia2 } from "elysia";
 
@@ -1143,6 +1146,16 @@ var defineSearchCollection = (definition) => ({
   kind: "search"
 });
 
+// src/engine/migrate.ts
+class EngineFencedError extends Error {
+  reason;
+  constructor(reason) {
+    super(`[sync] Engine is fenced for migration: ${reason}`);
+    this.name = "EngineFencedError";
+    this.reason = reason;
+  }
+}
+
 // src/engine/syncEngine.ts
 class UnauthorizedError extends Error {
   constructor(subject) {
@@ -1345,6 +1358,7 @@ var createSyncEngine = (options = {}) => {
   let mutationsInFlight = 0;
   const mutationWaiters = [];
   let mutationsQueued = 0;
+  const activeFences = new Set;
   const acquireMutationSlot = async () => {
     const limit = options.mutationConcurrency;
     if (limit === undefined) {
@@ -1471,7 +1485,11 @@ var createSyncEngine = (options = {}) => {
   }
   const broadcast = (changes, originVersion) => {
     if (clusterBus !== undefined && changes.length > 0) {
-      clusterBus.publish({ changes, origin: instanceId, originVersion });
+      clusterBus.publish({
+        changes,
+        origin: instanceId,
+        originVersion
+      });
     }
   };
   const subsFor = (collection) => {
@@ -2234,7 +2252,14 @@ var createSyncEngine = (options = {}) => {
     registerSearch: (collection) => {
       registry.set(collection.name, collection);
     },
-    subscribe: async ({ collection, params, ctx, onDiff, since, signal }) => {
+    subscribe: async ({
+      collection,
+      params,
+      ctx,
+      onDiff,
+      since,
+      signal
+    }) => {
       const subscribeSpan = tracer.startSpan("sync.subscribe", {
         attributes: {
           [ABS_ATTRS.engineId]: instanceId,
@@ -2263,7 +2288,10 @@ var createSyncEngine = (options = {}) => {
               releaseSubscriptionSlot(tenantSlot);
               innerUnsubscribe();
             };
-            const wrapped = { ...sub, unsubscribe: wrappedUnsubscribe };
+            const wrapped = {
+              ...sub,
+              unsubscribe: wrappedUnsubscribe
+            };
             linkAbortToUnsubscribe(signal, wrappedUnsubscribe);
             slotHandedOff = true;
             return wrapped;
@@ -2298,7 +2326,9 @@ var createSyncEngine = (options = {}) => {
           const scopedTable = tables.length === 1 ? tables[0] : undefined;
           const readRule = scopedTable !== undefined ? readRuleFor(scopedTable) : undefined;
           const rehydrate = async () => {
-            const raw = [...await definition.hydrate(params, ctx)];
+            const raw = [
+              ...await definition.hydrate(params, ctx)
+            ];
             const rows = scopedTable !== undefined ? raw.map((row) => migrateRow(scopedTable, row)) : raw;
             return readRule ? rows.filter((row) => readRule(ctx, row)) : rows;
           };
@@ -2463,6 +2493,10 @@ var createSyncEngine = (options = {}) => {
         }
       });
       try {
+        if (activeFences.size > 0) {
+          const oldest = activeFences.values().next().value;
+          throw new EngineFencedError(oldest.reason);
+        }
         const mutation = mutations.get(name);
         if (mutation === undefined) {
           throw new Error(`Unknown mutation "${name}"`);
@@ -2838,6 +2872,73 @@ var createSyncEngine = (options = {}) => {
       }
       return { asOfAt, asOfVersion, rows, truncated };
     },
+    fence: ({ reason }) => {
+      const handle = {
+        fencedAt: Date.now(),
+        reason,
+        lift: () => {
+          activeFences.delete(handle);
+        }
+      };
+      activeFences.add(handle);
+      return handle;
+    },
+    exportSnapshot: async ({
+      tables,
+      ctx = {}
+    } = {}) => {
+      const tableFilter = tables !== undefined ? new Set(tables) : undefined;
+      const rows = {};
+      for (const [table, reader] of readers) {
+        if (tableFilter !== undefined && !tableFilter.has(table)) {
+          continue;
+        }
+        const iterable = await reader.all(ctx);
+        rows[table] = [...iterable];
+      }
+      return {
+        exportedAt: Date.now(),
+        sourceInstanceId: instanceId,
+        tables: rows,
+        version
+      };
+    },
+    importSnapshot: async (snapshot, { tables, onProgress, ctx = {} } = {}) => {
+      const tableFilter = tables !== undefined ? new Set(tables) : undefined;
+      const perTable = {};
+      const skipped = [];
+      let tablesImported = 0;
+      let rowsImported = 0;
+      for (const [table, snapshotRows] of Object.entries(snapshot.tables)) {
+        if (tableFilter !== undefined && !tableFilter.has(table)) {
+          continue;
+        }
+        const writer = writers.get(table);
+        if (writer === undefined) {
+          skipped.push(table);
+          continue;
+        }
+        const total = snapshotRows.length;
+        let done = 0;
+        for (const row of snapshotRows) {
+          await writer.insert(row, ctx, undefined);
+          done += 1;
+          rowsImported += 1;
+          if (onProgress !== undefined) {
+            onProgress(table, done, total);
+          }
+        }
+        perTable[table] = done;
+        if (done > 0)
+          tablesImported += 1;
+      }
+      return {
+        perTable,
+        rowsImported,
+        skipped,
+        tablesImported
+      };
+    },
     metrics: () => {
       const now = Date.now();
       const byCollection = {};
@@ -3366,5 +3467,5 @@ export {
   createPresenceHub
 };
 
-//# debugId=9662318FD91E917A64756E2164756E21
+//# debugId=62313B55CB7C7F6064756E2164756E21
 //# sourceMappingURL=index.js.map