@semics-tech/mongolite 1.3.0 → 1.4.0

package/dist/cjs/sync/protocol.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncProtocolError = exports.SYNC_CONTENT_TYPE = exports.SYNC_PROTOCOL_VERSION = void 0;
+exports.encodeBody = encodeBody;
+exports.decodeBody = decodeBody;
+exports.toWireOperation = toWireOperation;
+exports.fromWireOperation = fromWireOperation;
+exports.parseApplyRequest = parseApplyRequest;
+exports.parseFetchRequest = parseFetchRequest;
+/**
+ * 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.
+ */
+const bson_1 = require("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.
+ */
+exports.SYNC_PROTOCOL_VERSION = 1;
+/** Content type used for request and response bodies. */
+exports.SYNC_CONTENT_TYPE = 'application/json';
+/** Raised when a payload is malformed or speaks a version we do not implement. */
+class SyncProtocolError extends Error {
+    constructor(message, 
+    /** Suggested HTTP status for a receiver to return. */
+    status = 400) {
+        super(message);
+        this.status = status;
+        this.name = 'SyncProtocolError';
+    }
+}
+exports.SyncProtocolError = SyncProtocolError;
+/** Serialises a body to relaxed Extended JSON. */
+function encodeBody(value) {
+    return bson_1.EJSON.stringify(value, { relaxed: true });
+}
+/** Parses a relaxed Extended JSON body back into BSON-typed values. */
+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 bson_1.EJSON.parse(JSON.stringify(raw), { relaxed: true });
+    }
+    try {
+        return bson_1.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. */
+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.
+ */
+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. */
+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. */
+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) !== exports.SYNC_PROTOCOL_VERSION) {
+        throw new SyncProtocolError(`Unsupported sync protocol ${String(body.protocol)}; this receiver implements ${exports.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);
+}