@semics-tech/mongolite 1.2.0 → 1.4.0

package/dist/sync/protocol.js

@@ -0,0 +1,168 @@
+/**
+ * The wire format shared by the HTTP sink and the receiver that applies its messages.
+ *
+ * Both halves live in this package on purpose: a client and a receiver that disagree
+ * about the protocol lose data quietly, so they are versioned and released together.
+ *
+ * Bodies are **relaxed Extended JSON**, not plain JSON. Plain JSON would flatten
+ * `ObjectId` to a string and `Date` to an ISO string in transit — degrading exactly the
+ * BSON types the sync design goes to some trouble to preserve, and doing it invisibly.
+ *
+ * Relaxed rather than canonical, because canonical encodes every number as `$numberInt`
+ * or `$numberDouble` and revives it as a BSON wrapper object. A local `age: 31` would
+ * then be written upstream as an `Int32` over HTTP but as a double over a direct
+ * connection — the same change producing different stored types depending on transport.
+ * Relaxed keeps plain numbers plain while still preserving `Date`, `ObjectId`, `Binary`
+ * and `Decimal128`. The cost is that 64-bit integers beyond 2^53 lose precision, which
+ * the local store could not represent anyway.
+ */
+import { EJSON } from 'bson';
+/**
+ * Protocol version, sent with every request.
+ *
+ * A receiver rejects a version it does not understand rather than guessing, so an
+ * upgraded client talking to an old server fails loudly instead of silently writing
+ * something unintended.
+ */
+export const SYNC_PROTOCOL_VERSION = 1;
+/** Content type used for request and response bodies. */
+export const SYNC_CONTENT_TYPE = 'application/json';
+/** Raised when a payload is malformed or speaks a version we do not implement. */
+export class SyncProtocolError extends Error {
+    constructor(message, 
+    /** Suggested HTTP status for a receiver to return. */
+    status = 400) {
+        super(message);
+        this.status = status;
+        this.name = 'SyncProtocolError';
+    }
+}
+/** Serialises a body to relaxed Extended JSON. */
+export function encodeBody(value) {
+    return EJSON.stringify(value, { relaxed: true });
+}
+/** Parses a relaxed Extended JSON body back into BSON-typed values. */
+export function decodeBody(raw) {
+    if (typeof raw !== 'string') {
+        // Some frameworks parse JSON before we see it. Re-encoding is the only way to get
+        // Extended JSON revived into real BSON types.
+        return EJSON.parse(JSON.stringify(raw), { relaxed: true });
+    }
+    try {
+        return EJSON.parse(raw, { relaxed: true });
+    }
+    catch (err) {
+        throw new SyncProtocolError(`Malformed sync payload: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Converts an internal operation into its wire form. */
+export function toWireOperation(op, command) {
+    const wire = {
+        collection: op.collection,
+        documentId: op.documentId,
+        type: op.type,
+    };
+    if (op.baseVersion !== undefined)
+        wire.baseVersion = op.baseVersion;
+    if (op.diff)
+        wire.diff = op.diff;
+    if (op.document)
+        wire.document = op.document;
+    if (command)
+        wire.command = command;
+    return wire;
+}
+/**
+ * Validates a wire operation and converts it back into an internal one.
+ *
+ * Everything reaching a receiver is untrusted input, so this checks shape rather than
+ * assuming it. `index` and `sourceCollection` are reconstructed locally — a client does
+ * not get to choose them.
+ */
+export function fromWireOperation(value, index) {
+    if (typeof value !== 'object' || value === null) {
+        throw new SyncProtocolError(`operations[${index}] is not an object`);
+    }
+    const wire = value;
+    if (typeof wire.collection !== 'string' || wire.collection.length === 0) {
+        throw new SyncProtocolError(`operations[${index}].collection must be a non-empty string`);
+    }
+    if (typeof wire.documentId !== 'string' || wire.documentId.length === 0) {
+        throw new SyncProtocolError(`operations[${index}].documentId must be a non-empty string`);
+    }
+    if (wire.type !== 'upsert' && wire.type !== 'delete') {
+        throw new SyncProtocolError(`operations[${index}].type must be "upsert" or "delete"`);
+    }
+    if (wire.baseVersion !== undefined &&
+        wire.baseVersion !== null &&
+        typeof wire.baseVersion !== 'number') {
+        throw new SyncProtocolError(`operations[${index}].baseVersion must be a number or null`);
+    }
+    const op = {
+        collection: wire.collection,
+        sourceCollection: wire.collection,
+        documentId: wire.documentId,
+        type: wire.type,
+        outboxId: index,
+        baseVersion: wire.baseVersion ?? null,
+    };
+    if (isPlainRecord(wire.document))
+        op.document = wire.document;
+    if (wire.diff !== undefined) {
+        if (!isPlainRecord(wire.diff)) {
+            throw new SyncProtocolError(`operations[${index}].diff must be an object`);
+        }
+        const set = wire.diff.set;
+        const unset = wire.diff.unset;
+        if (!isPlainRecord(set) || !Array.isArray(unset) || unset.some((p) => typeof p !== 'string')) {
+            throw new SyncProtocolError(`operations[${index}].diff must be { set: object, unset: string[] }`);
+        }
+        op.diff = { set, unset: unset };
+    }
+    if (op.type === 'upsert' && !op.diff && !op.document) {
+        throw new SyncProtocolError(`operations[${index}] must carry a diff or a document`);
+    }
+    return op;
+}
+/** Validates the envelope of an apply request and returns its operations. */
+export function parseApplyRequest(body) {
+    const request = requireEnvelope(body);
+    const operations = request.operations;
+    if (!Array.isArray(operations)) {
+        throw new SyncProtocolError('`operations` must be an array');
+    }
+    return {
+        replicator: typeof request.replicator === 'string' ? request.replicator : 'unknown',
+        operations: operations.map((value, index) => fromWireOperation(value, index)),
+    };
+}
+/** Validates the envelope of a fetch request. */
+export function parseFetchRequest(body) {
+    const request = requireEnvelope(body);
+    if (typeof request.collection !== 'string' || request.collection.length === 0) {
+        throw new SyncProtocolError('`collection` must be a non-empty string');
+    }
+    if (!Array.isArray(request.documentIds) ||
+        request.documentIds.some((id) => typeof id !== 'string')) {
+        throw new SyncProtocolError('`documentIds` must be an array of strings');
+    }
+    return { collection: request.collection, documentIds: request.documentIds };
+}
+function requireEnvelope(body) {
+    if (!isPlainRecord(body)) {
+        throw new SyncProtocolError('Request body must be an object');
+    }
+    // Coerced rather than compared strictly: a proxy that re-encodes the body could hand
+    // us the version as a string or a BSON number wrapper, and refusing on that would be
+    // a confusing failure for something entirely cosmetic.
+    if (Number(body.protocol) !== SYNC_PROTOCOL_VERSION) {
+        throw new SyncProtocolError(`Unsupported sync protocol ${String(body.protocol)}; this receiver implements ${SYNC_PROTOCOL_VERSION}`, 
+        // 426 tells the client the fix is to upgrade, not to retry.
+        426);
+    }
+    return body;
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=protocol.js.map

package/dist/sync/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/sync/protocol.ts"],"names":[],"mappings":"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"}

package/dist/sync/replicator.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Drains the {@link SyncOutbox} into an upstream {@link SyncSink}.
+ *
+ * ## Delivery guarantees
+ *
+ * Delivery is **at-least-once**, and every operation the replicator emits is
+ * idempotent (`replaceOne` with `upsert`, or `deleteOne` by `_id`). Replaying a
+ * batch therefore converges on the same upstream state, which is what makes it
+ * safe to acknowledge *after* the upstream write rather than before: a crash in
+ * the window between the two costs a duplicate write, never a lost one.
+ *
+ * ## Ordering
+ *
+ * Changes are read in outbox order and coalesced per document, so the newest
+ * revision wins. Within a batch, operations touch distinct documents and are
+ * applied unordered for throughput; across batches, order is preserved.
+ */
+import { EventEmitter } from 'events';
+import type { IDatabaseAdapter } from '../db.js';
+import { SyncOutbox } from './outbox.js';
+import { SyncShadow } from './shadow.js';
+import type { SyncDeadLetter, SyncOptions, SyncSink, SyncStatus } from './types.js';
+export declare class SyncReplicator extends EventEmitter {
+    private readonly db;
+    private readonly sink;
+    private readonly outbox;
+    private readonly shadow;
+    private readonly opts;
+    private running;
+    private connected;
+    private loop;
+    private checkpoint;
+    private backfilled;
+    private watched;
+    private lastCollectionScan;
+    private appliedCount;
+    private retryCount;
+    private deadLetterCount;
+    private conflictCount;
+    private lastError;
+    /** Resolves the current sleep early when a local write arrives or `stop()` is called. */
+    private wake;
+    constructor(db: IDatabaseAdapter, sink: SyncSink, options?: SyncOptions);
+    /** The outbox backing this replicator — for dead-letter inspection and manual maintenance. */
+    get log(): SyncOutbox;
+    /** The shadow store holding last-known upstream state — for diagnostics and reseeding. */
+    get baseline(): SyncShadow;
+    /**
+     * Installs capture triggers, backfills existing documents if this replicator
+     * has never run, and starts streaming changes upstream.
+     *
+     * Resolves once replication is *running*, not once it has caught up — use
+     * {@link SyncReplicator.waitForDrain} for that.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops replication. Capture triggers stay installed, so changes made while
+     * stopped are still recorded and picked up on the next `start()`.
+     *
+     * @param options.flush Drain everything pending before stopping. Defaults to `false`.
+     */
+    stop(options?: {
+        flush?: boolean;
+    }): Promise<void>;
+    /**
+     * Nudges the replicator to check the outbox now instead of waiting for the
+     * next poll. Called by the client after local writes so replication latency
+     * is bounded by the upstream round trip, not the poll interval.
+     */
+    notify(): void;
+    /**
+     * Resolves once every change written *before this call* has reached the
+     * upstream. Rejects if replication stops with an error.
+     *
+     * The target is pinned to the outbox position at call time rather than
+     * "outbox is empty" — otherwise a concurrent writer could keep the outbox
+     * non-empty forever, and, worse, a `drained` event from a scan that began
+     * before the caller's own write would resolve it too early.
+     */
+    waitForDrain(): Promise<void>;
+    /** Current replication progress. */
+    status(): Promise<SyncStatus>;
+    /** Changes permanently rejected upstream. */
+    deadLetters(limit?: number): Promise<SyncDeadLetter[]>;
+    private pending;
+    /** `null` means "every collection"; an array restricts the outbox query. */
+    private collectionFilter;
+    /**
+     * Discovers collections to watch and installs their triggers.
+     *
+     * Re-run periodically so collections created after `start()` join replication
+     * without a restart.
+     */
+    private refreshCollections;
+    /**
+     * Seeds the upstream with documents that existed before replication started.
+     *
+     * The checkpoint is pinned *before* the scan begins, so a write racing the
+     * scan is either seen by the scan, or captured in the outbox above the
+     * checkpoint, or both — and "both" is harmless because upserts are idempotent.
+     */
+    private backfill;
+    /** The replication loop: read, coalesce, apply, checkpoint, repeat. */
+    private run;
+    /**
+     * Applies one batch.
+     * @returns `true` if there was work to do, `false` if the outbox was empty.
+     */
+    private drainOnce;
+    /** Acknowledges up to `id` and prunes rows no replicator needs any more. */
+    private advanceTo;
+    /**
+     * Collapses a run of changes into one operation per document.
+     *
+     * Records are in ascending outbox order, so the last one seen for a document
+     * is its current state — an upsert of the newest revision, or a delete.
+     */
+    private coalesce;
+    /**
+     * Turns coalesced records into upstream operations, attaching the base version and
+     * minimal diff from the shadow.
+     *
+     * Shadows load per collection in one query rather than per document, so a batch of
+     * 500 changes costs one extra read per collection, not 500.
+     */
+    private buildOperations;
+    /**
+     * Records the new upstream state for operations that landed.
+     *
+     * The post-write state is computed by applying the diff to the previous *server*
+     * document rather than by re-reading it — one fewer round trip, and it keeps the BSON
+     * values of untouched fields exactly as they were.
+     */
+    private commitShadows;
+    /**
+     * Reconciles a push that lost a race.
+     *
+     * The upstream state goes into the shadow first, so whatever happens next — a retry,
+     * or the application's own decision — is made against current reality rather than
+     * against the version that already lost.
+     */
+    private resolveConflict;
+    /**
+     * Writes the upstream version of a document into the local collection.
+     *
+     * The write trips the capture triggers and lands back in the outbox, which would
+     * normally mean pushing it straight back up. It does not, because the local row now
+     * matches the shadow exactly: the diff comes out empty and the echo is dropped in
+     * {@link SyncReplicator.buildOperations}. That is why the local copy is written from
+     * the same projection the diff compares against.
+     */
+    private adoptUpstream;
+    private fetchUpstream;
+    /** Maps an outbox record to an upstream operation, applying rename and transform. */
+    private toOperation;
+    /**
+     * Applies a batch, retrying transient failures with exponential backoff and
+     * jitter. Returns the operations the upstream rejected permanently, or `null`
+     * if the replicator was stopped before the batch landed.
+     *
+     * The checkpoint is never advanced while this is retrying, so an upstream
+     * outage simply parks the batch — the outbox absorbs the backlog.
+     */
+    private applyWithRetry;
+    private ensureConnected;
+    private recordDeadLetter;
+    /**
+     * Keeps the outbox from growing without bound during a long outage.
+     * Compaction is lossless here because replication is full-document
+     * last-write-wins: only superseded revisions are dropped.
+     */
+    private enforceOutboxLimit;
+    /** Sleeps, but returns early when `notify()` or `stop()` is called. */
+    private sleep;
+    private fail;
+    private log_;
+}