@lossless.org/client 1.18.1 → 1.18.3

package/ts/nosqldb/classes.exactpersistence.ts

@@ -261,22 +261,19 @@ interface IExactModelConstructor<
   prototype: TModel;
 }
 
+/** A proven stored row: a fresh canonical decoding and its body's canonical bytes. */
+interface IExactStoredRow<TPersisted extends object> {
+  document: TStoredDocument<TPersisted>;
+  bodyBytes: Uint8Array;
+}
+
 const exactCollectionCache = new WeakMap<
   object,
   WeakMap<object, SmartdataExactCollection<any, any>>
 >();
 
-const bytesEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean => {
-  if (leftArg.byteLength !== rightArg.byteLength) {
-    return false;
-  }
-  for (let index = 0; index < leftArg.byteLength; index++) {
-    if (leftArg[index] !== rightArg[index]) {
-      return false;
-    }
-  }
-  return true;
-};
+const bytesEqual = (leftArg: Uint8Array, rightArg: Uint8Array): boolean =>
+  Buffer.compare(leftArg, rightArg) === 0;
 
 const hasOwn = (documentArg: object, keyArg: PropertyKey): boolean =>
   Object.prototype.hasOwnProperty.call(documentArg, keyArg);
@@ -1150,21 +1147,39 @@ export class SmartdataExactCollection<
     );
   }
 
-  private canonicalizeDocument<TDocument extends object>(
-    documentArg: TDocument,
-    labelArg: string,
+  /** The collection's one BSON encoder: every encoding of a row passes here. */
+  private encodeBson(documentArg: object): Uint8Array {
+    return plugins.mongodb.BSON.serialize(documentArg);
+  }
+
+  /** The collection's one BSON decoder: every decoding of a row passes here. */
+  private decodeBson(bytesArg: Uint8Array): plugins.mongodb.Document {
+    return plugins.mongodb.BSON.deserialize(bytesArg);
+  }
+
+  /** Decodes proven canonical bytes into a fresh canonical document. */
+  private decodeCanonical<TDocument extends object>(
+    bytesArg: Uint8Array,
   ): TDocument {
-    let canonicalInput: TDocument;
+    return canonicalizeValue(this.decodeBson(bytesArg) as TDocument);
+  }
+
+  /**
+   * The exactness proof: the document's sorted encoding must decode and
+   * encode again to the same bytes. Returns those canonical bytes and the
+   * decoding the proof produced, which no caller has seen yet.
+   */
+  private canonicalizeDocument(
+    documentArg: object,
+    labelArg: string,
+  ): { document: Record<string, unknown>; bytes: Uint8Array } {
     let serialized: Uint8Array;
-    let canonical: TDocument;
+    let canonical: Record<string, unknown>;
     let reserialized: Uint8Array;
     try {
-      canonicalInput = canonicalizeValue(documentArg);
-      serialized = plugins.mongodb.BSON.serialize(canonicalInput);
-      canonical = canonicalizeValue(
-        plugins.mongodb.BSON.deserialize(serialized) as TDocument,
-      );
-      reserialized = plugins.mongodb.BSON.serialize(canonical);
+      serialized = this.encodeBson(canonicalizeValue(documentArg));
+      canonical = canonicalizeValue(this.decodeBson(serialized));
+      reserialized = this.encodeBson(canonical);
     } catch (errorArg) {
       throw new SmartdataExactPersistenceError(
         'invalid_document',
@@ -1178,7 +1193,23 @@ export class SmartdataExactCollection<
         `${labelArg} is not byte-stable across a BSON roundtrip.`,
       );
     }
-    return canonical;
+    return { document: canonical, bytes: serialized };
+  }
+
+  /**
+   * Whether a document encodes canonically to bytes an earlier proof
+   * produced. Equal bytes carry that proof and its assertion over, so the
+   * caller needs neither again; on a mismatch the caller runs the full proof
+   * to report what is wrong.
+   */
+  private encodesAs(documentArg: object, provenBytesArg: Uint8Array): boolean {
+    let bytes: Uint8Array;
+    try {
+      bytes = this.encodeBson(canonicalizeValue(documentArg));
+    } catch {
+      return false;
+    }
+    return bytesEqual(bytes, provenBytesArg);
   }
 
   private assertAllowedTopLevelKeys(
@@ -1209,29 +1240,47 @@ export class SmartdataExactCollection<
     }
   }
 
-  private canonicalizePersistedDocument(
-    documentArg: object,
-  ): TExactPersistedDocument<TPersisted> {
+  /**
+   * Proves an application body canonical and runs the assertion once, on the
+   * proof's own decoding, which is never handed out. Returns the canonical
+   * bytes of the body.
+   */
+  private provePersistedDocument(documentArg: object): Uint8Array {
     this.assertAllowedTopLevelKeys(documentArg, [], 'Persisted document');
-    const canonical = this.canonicalizeDocument(
+    const { document, bytes } = this.canonicalizeDocument(
       documentArg,
       'Persisted document',
     );
-    this.assertWithoutMutation(canonical, 'Persisted document');
-    return canonical as TExactPersistedDocument<TPersisted>;
+    this.assertAllowedTopLevelKeys(document, [], 'Persisted document');
+    this.assertWithoutMutation(document, bytes, 'Persisted document');
+    return bytes;
   }
 
-  private canonicalizeStoredDocument(
+  /**
+   * Proves a stored envelope canonical, checks its storage metadata and runs
+   * the assertion once on its body. The body is the proof's own decoding with
+   * the metadata removed, so the assertion never sees a document a caller
+   * receives. Returns the canonical bytes of the envelope and of its body.
+   */
+  private proveStoredDocument(
     documentArg: object,
-  ): TStoredDocument<TPersisted> {
+  ): { bytes: Uint8Array; bodyBytes: Uint8Array } {
     this.assertAllowedTopLevelKeys(
       documentArg,
       storageMetadataKeys,
       'Stored document',
     );
-    const canonical = this.canonicalizeDocument(documentArg, 'Stored document');
-    const revision = (canonical as Record<string, unknown>)._smartdataRevision;
-    if (!isMongoObjectId((canonical as Record<string, unknown>)._id)) {
+    const { document, bytes } = this.canonicalizeDocument(
+      documentArg,
+      'Stored document',
+    );
+    this.assertAllowedTopLevelKeys(
+      document,
+      storageMetadataKeys,
+      'Stored document',
+    );
+    const revision = document._smartdataRevision;
+    if (!isMongoObjectId(document._id)) {
       throw new SmartdataExactPersistenceError(
         'invalid_document',
         'Stored document _id must be a MongoDB ObjectId.',
@@ -1246,15 +1295,55 @@ export class SmartdataExactCollection<
         'Stored document _smartdataRevision must be a nonempty string when present.',
       );
     }
-    this.getPersistedBody(canonical as TStoredDocument<TPersisted>);
-    return canonical as TStoredDocument<TPersisted>;
+    for (const key of storageMetadataKeys) {
+      delete document[key];
+    }
+    const bodyBytes = this.encodeBson(document);
+    this.assertWithoutMutation(document, bodyBytes, 'Persisted document');
+    return { bytes, bodyBytes };
+  }
+
+  /** Proves a stored envelope and returns a fresh canonical decoding of it. */
+  private readStoredDocument(documentArg: object): IExactStoredRow<TPersisted> {
+    const { bytes, bodyBytes } = this.proveStoredDocument(documentArg);
+    return {
+      document: this.decodeCanonical<TStoredDocument<TPersisted>>(bytes),
+      bodyBytes,
+    };
+  }
+
+  /**
+   * The canonical envelope of a proven body. BSON encodes every element on
+   * its own, so a proven body with inert metadata is canonical as a whole;
+   * only the canonical key order has to be restored.
+   */
+  private composeStoredDocument(
+    bodyArg: TExactPersistedDocument<TPersisted>,
+    metadataArg: { _id: plugins.mongodb.ObjectId; _smartdataRevision?: string },
+  ): TStoredDocument<TPersisted> {
+    const fields = new Map<string, unknown>(Object.entries(bodyArg));
+    fields.set('_id', metadataArg._id);
+    if (metadataArg._smartdataRevision !== undefined) {
+      fields.set('_smartdataRevision', metadataArg._smartdataRevision);
+    }
+    const envelope = Object.create(null) as Record<string, unknown>;
+    for (const key of [...fields.keys()].sort()) {
+      envelope[key] = fields.get(key);
+    }
+    return envelope as TStoredDocument<TPersisted>;
   }
 
   private assertWithoutMutation(
     documentArg: object,
+    beforeArg: Uint8Array,
     labelArg: string,
   ): void {
-    assertBsonWithoutMutation(documentArg, this.options.assertDocument, (reasonArg, causeArg) =>
+    assertBsonWithoutMutation(
+      documentArg,
+      beforeArg,
+      (documentToEncodeArg) => this.encodeBson(documentToEncodeArg),
+      this.options.assertDocument,
+      (reasonArg, causeArg) =>
       new SmartdataExactPersistenceError('invalid_document', `${labelArg} ${
         reasonArg === 'assertion' ? 'assertion failed.' :
         reasonArg === 'bson' ? 'validator produced a non-BSON document.' :
@@ -1262,46 +1351,8 @@ export class SmartdataExactCollection<
       }`, causeArg === undefined ? undefined : { cause: causeArg }));
   }
 
-  private getPersistedBody(
-    storedDocumentArg: TStoredDocument<TPersisted>,
-  ): TExactPersistedDocument<TPersisted> {
-    const body = Object.create(null) as Record<string, unknown>;
-    for (const key of Object.keys(storedDocumentArg)) {
-      if (!reservedKeys.includes(key as TReservedKey)) {
-        body[key] = (storedDocumentArg as Record<string, unknown>)[key];
-      }
-    }
-    return this.canonicalizePersistedDocument(body);
-  }
-
-  private persistedDocumentsEqual(
-    leftArg: TExactPersistedDocument<TPersisted>,
-    rightArg: TExactPersistedDocument<TPersisted>,
-  ): boolean {
-    return bytesEqual(
-      plugins.mongodb.BSON.serialize(leftArg),
-      plugins.mongodb.BSON.serialize(rightArg),
-    );
-  }
-
-  private storedDocumentsEqual(
-    leftArg: TStoredDocument<TPersisted>,
-    rightArg: TStoredDocument<TPersisted>,
-  ): boolean {
-    if (!leftArg._id.equals(rightArg._id)) {
-      return false;
-    }
-    if (leftArg._smartdataRevision !== rightArg._smartdataRevision) {
-      return false;
-    }
-    return this.persistedDocumentsEqual(
-      this.getPersistedBody(leftArg),
-      this.getPersistedBody(rightArg),
-    );
-  }
-
   private validateReconcileIdentity(
-    documentArg: TExactPersistedDocument<TPersisted>,
+    documentArg: TExactPersistedDocument<TPersisted> | TStoredDocument<TPersisted>,
   ): string {
     const value = (documentArg as Record<string, unknown>)[this.reconcileBy];
     if (typeof value !== 'string' || value.trim().length === 0) {
@@ -1313,9 +1364,10 @@ export class SmartdataExactCollection<
     return value;
   }
 
+  /** The persisted body a model serializes to, before any proof. */
   private async serializeModel(
     modelArg: TModel,
-  ): Promise<TExactPersistedDocument<TPersisted>> {
+  ): Promise<Record<string, unknown>> {
     const serialized = (await modelArg.createSavableObject()) as Record<
       string,
       unknown
@@ -1353,12 +1405,13 @@ export class SmartdataExactCollection<
         body[key] = serialized[key];
       }
     }
-    return this.canonicalizePersistedDocument(body);
+    return body;
   }
 
+  /** Proves an insert input and returns the canonical bytes of its body. */
   private async createPersistedDocument(
     documentArg: TModel | TExactPersistedDocument<TPersisted>,
-  ): Promise<TExactPersistedDocument<TPersisted>> {
+  ): Promise<Uint8Array> {
     if (typeof documentArg !== 'object' || documentArg === null) {
       throw new SmartdataExactPersistenceError(
         'invalid_document',
@@ -1366,9 +1419,9 @@ export class SmartdataExactCollection<
       );
     }
     if (documentArg instanceof this.modelConstructor) {
-      return this.serializeModel(documentArg);
+      return this.provePersistedDocument(await this.serializeModel(documentArg));
     }
-    return this.canonicalizePersistedDocument(documentArg);
+    return this.provePersistedDocument(documentArg);
   }
 
   private hydrateStoredDocument(
@@ -1383,12 +1436,12 @@ export class SmartdataExactCollection<
     identityArg: string,
     sessionArg: plugins.mongodb.ClientSession | undefined,
     deadlineArg: SmartdataOperationDeadline,
-  ): Promise<TStoredDocument<TPersisted> | null> {
+  ): Promise<IExactStoredRow<TPersisted> | null> {
     const rawDocument = await this.collection.mongoDbCollection.findOne({
       [this.reconcileBy]: identityArg,
     }, { session: sessionArg, ...deadlineArg.commandOptions() });
     return rawDocument
-      ? this.canonicalizeStoredDocument(rawDocument)
+      ? this.readStoredDocument(rawDocument)
       : null;
   }
 
@@ -1438,12 +1491,10 @@ export class SmartdataExactCollection<
       currentDescriptor.value,
       'Exact delete current',
     );
-    const current = this.canonicalizeStoredDocument(
+    const { document: current } = this.readStoredDocument(
       currentSnapshot as object,
     );
-    const identity = this.validateReconcileIdentity(
-      this.getPersistedBody(current),
-    );
+    const identity = this.validateReconcileIdentity(current);
     return { current, identity };
   }
 
@@ -1454,7 +1505,7 @@ export class SmartdataExactCollection<
     sessionArg: plugins.mongodb.ClientSession | undefined,
     deadlineArg: SmartdataOperationDeadline,
   ): Promise<TExactDeleteResult> {
-    let reconciled: TStoredDocument<TPersisted> | null;
+    let reconciled: IExactStoredRow<TPersisted> | null;
     try {
       reconciled = await this.findByReconcileIdentity(identityArg, sessionArg, deadlineArg);
     } catch (errorArg) {
@@ -1466,7 +1517,7 @@ export class SmartdataExactCollection<
         causeArg,
       );
     }
-    if (reconciled && reconciled._id.equals(currentArg._id)) {
+    if (reconciled && reconciled.document._id.equals(currentArg._id)) {
       return { status: 'concurrent_change', deletedCount: 0 };
     }
     throw this.ambiguousWriteError(
@@ -1480,21 +1531,21 @@ export class SmartdataExactCollection<
     optionsArg: IExactBoundedOptions = {},
   ): Promise<TExactInsertResult<TPersisted>> {
     return this.runOperation(optionsArg, async (sessionArg, deadlineArg) => {
-    const persistedDocument = await this.createPersistedDocument(documentArg);
+    const persistedBytes = await this.createPersistedDocument(documentArg);
+    const persistedDocument = this.decodeCanonical<
+      TExactPersistedDocument<TPersisted>
+    >(persistedBytes);
     const identity = this.validateReconcileIdentity(persistedDocument);
-    const expectedStoredDocument = this.canonicalizeStoredDocument({
-      _id: new plugins.mongodb.ObjectId(),
-      ...persistedDocument,
-    });
+    const expectedStoredDocument = this.composeStoredDocument(
+      persistedDocument,
+      { _id: new plugins.mongodb.ObjectId() },
+    );
     if (hasActiveTransaction(sessionArg)) {
       const existing = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       if (existing) {
-        return this.persistedDocumentsEqual(
-          this.getPersistedBody(existing),
-          persistedDocument,
-        )
-          ? { status: 'already_committed', document: existing }
-          : { status: 'conflict', document: existing };
+        return bytesEqual(existing.bodyBytes, persistedBytes)
+          ? { status: 'already_committed', document: existing.document }
+          : { status: 'conflict', document: existing.document };
       }
     }
 
@@ -1522,7 +1573,7 @@ export class SmartdataExactCollection<
       if (deadlineArg.interrupted(errorArg)) {
         throw this.interruptedWriteError('Exact insert', errorArg);
       }
-      let reconciled: TStoredDocument<TPersisted> | null;
+      let reconciled: IExactStoredRow<TPersisted> | null;
       try {
         reconciled = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       } catch (reconciliationError) {
@@ -1542,16 +1593,11 @@ export class SmartdataExactCollection<
         );
       }
       if (reconciled) {
-        if (
-          this.persistedDocumentsEqual(
-            this.getPersistedBody(reconciled),
-            persistedDocument,
-          )
-        ) {
-          return { status: 'already_committed', document: reconciled };
+        if (bytesEqual(reconciled.bodyBytes, persistedBytes)) {
+          return { status: 'already_committed', document: reconciled.document };
         }
         if (isDuplicateKeyError(errorArg)) {
-          return { status: 'conflict', document: reconciled };
+          return { status: 'conflict', document: reconciled.document };
         }
       }
       if (isDuplicateKeyError(errorArg)) {
@@ -1574,7 +1620,7 @@ export class SmartdataExactCollection<
           result,
         );
       }
-      let reconciled: TStoredDocument<TPersisted> | null;
+      let reconciled: IExactStoredRow<TPersisted> | null;
       try {
         reconciled = await this.findByReconcileIdentity(identity, sessionArg, deadlineArg);
       } catch (errorArg) {
@@ -1586,14 +1632,8 @@ export class SmartdataExactCollection<
           result,
         );
       }
-      if (
-        reconciled &&
-        this.persistedDocumentsEqual(
-          this.getPersistedBody(reconciled),
-          persistedDocument,
-        )
-      ) {
-        return { status: 'already_committed', document: reconciled };
+      if (reconciled && bytesEqual(reconciled.bodyBytes, persistedBytes)) {
+        return { status: 'already_committed', document: reconciled.document };
       }
       throw this.ambiguousWriteError(
         'Exact insert was not acknowledged and could not be reconciled.',
@@ -1607,19 +1647,15 @@ export class SmartdataExactCollection<
   public toPersisted(
     storedDocumentArg: TStoredDocument<TPersisted>,
   ): TExactPersistedDocument<TPersisted> {
-    const storedDocument = this.canonicalizeStoredDocument(storedDocumentArg);
-    const persistedDocument = this.getPersistedBody(storedDocument);
-    return plugins.mongodb.BSON.deserialize(
-      plugins.mongodb.BSON.serialize(persistedDocument),
-    ) as TExactPersistedDocument<TPersisted>;
+    const { bodyBytes } = this.proveStoredDocument(storedDocumentArg);
+    // A plain decoding: ordinary application objects, not canonical ones.
+    return this.decodeBson(bodyBytes) as TExactPersistedDocument<TPersisted>;
   }
 
   public canonicalBytes(
     persistedDocumentArg: TExactPersistedDocument<TPersisted>,
   ): Uint8Array {
-    return plugins.mongodb.BSON.serialize(
-      this.canonicalizePersistedDocument(persistedDocumentArg),
-    );
+    return this.provePersistedDocument(persistedDocumentArg);
   }
 
   public async findStoredOne(
@@ -1645,7 +1681,7 @@ export class SmartdataExactCollection<
     try {
       const rawDocument = await cursor.next();
       storedDocument = rawDocument
-        ? this.canonicalizeStoredDocument(rawDocument)
+        ? this.readStoredDocument(rawDocument).document
         : null;
     } catch (errorArg) {
       try {
@@ -1689,7 +1725,7 @@ export class SmartdataExactCollection<
       }
       const rawDocuments = await cursor.toArray();
       storedDocuments = rawDocuments.map((documentArg) =>
-        this.canonicalizeStoredDocument(documentArg),
+        this.readStoredDocument(documentArg).document,
       );
     } catch (errorArg) {
       try {
@@ -1744,12 +1780,14 @@ export class SmartdataExactCollection<
     sessionOptionsArg: IExactBoundedOptions = {},
   ): Promise<TExactTransitionResult<TPersisted>> {
     return this.runOperation(sessionOptionsArg, async (sessionArg, deadlineArg) => {
-    const current = this.canonicalizeStoredDocument(optionsArg.current);
-    const currentBody = this.getPersistedBody(current);
-    const currentIdentity = this.validateReconcileIdentity(currentBody);
+    const { document: current, bodyBytes: currentBodyBytes } =
+      this.readStoredDocument(optionsArg.current);
+    const currentIdentity = this.validateReconcileIdentity(current);
     const model = this.hydrateStoredDocument(current);
     const untouchedBody = await this.serializeModel(model);
-    if (!this.persistedDocumentsEqual(currentBody, untouchedBody)) {
+    if (!this.encodesAs(untouchedBody, currentBodyBytes)) {
+      // A body that is not even canonical reports its own proof failure.
+      this.provePersistedDocument(untouchedBody);
       throw new SmartdataExactPersistenceError(
         'noncanonical_document',
         'Stored document does not survive an untouched model serialization roundtrip.',
@@ -1769,7 +1807,9 @@ export class SmartdataExactCollection<
       );
     }
 
-    const candidateBody = await this.serializeModel(model);
+    const candidateBody = this.decodeCanonical<
+      TExactPersistedDocument<TPersisted>
+    >(this.provePersistedDocument(await this.serializeModel(model)));
     const candidateIdentity = this.validateReconcileIdentity(candidateBody);
     if (candidateIdentity !== currentIdentity) {
       throw new SmartdataExactPersistenceError(
@@ -1778,11 +1818,11 @@ export class SmartdataExactCollection<
       );
     }
     const newRevision = globalThis.crypto.randomUUID();
-    const expectedStoredDocument = this.canonicalizeStoredDocument({
+    const expectedStoredDocument = this.composeStoredDocument(candidateBody, {
       _id: current._id,
-      ...candidateBody,
       _smartdataRevision: newRevision,
     });
+    const expectedBytes = this.encodeBson(expectedStoredDocument);
     const selector = current._smartdataRevision !== undefined
       ? { _id: current._id, _smartdataRevision: current._smartdataRevision }
       : { _id: current._id, _smartdataRevision: { $exists: false } };
@@ -1803,14 +1843,15 @@ export class SmartdataExactCollection<
       if (!postimage) {
         return { status: 'concurrent_change' };
       }
-      const canonicalPostimage = this.canonicalizeStoredDocument(postimage);
-      if (!this.storedDocumentsEqual(canonicalPostimage, expectedStoredDocument)) {
+      if (!this.encodesAs(postimage, expectedBytes)) {
+        // A postimage that is not even a valid stored document reports why.
+        this.proveStoredDocument(postimage);
         throw new SmartdataExactPersistenceError(
           'ambiguous_write',
           'Exact transition returned a postimage different from the requested state.',
         );
       }
-      return { status: 'transitioned', document: canonicalPostimage };
+      return { status: 'transitioned', document: expectedStoredDocument };
     } catch (errorArg) {
       if (isTransientTransactionError(errorArg, sessionArg)) {
         throw errorArg;
@@ -1833,13 +1874,11 @@ export class SmartdataExactCollection<
           _id: current._id,
         }, { session: sessionArg, ...deadlineArg.commandOptions() });
         if (reconciledRaw) {
-          const reconciled = this.canonicalizeStoredDocument(reconciledRaw);
-          if (
-            reconciled._smartdataRevision === newRevision &&
-            this.storedDocumentsEqual(reconciled, expectedStoredDocument)
-          ) {
-            return { status: 'transitioned', document: reconciled };
+          if (this.encodesAs(reconciledRaw, expectedBytes)) {
+            return { status: 'transitioned', document: expectedStoredDocument };
           }
+          // A malformed document fails the reconciliation itself.
+          this.proveStoredDocument(reconciledRaw);
         }
       } catch (reconciliationError) {
         if (isTransientTransactionError(reconciliationError, sessionArg)) {

package/ts/nosqldb/classes.ordinarypersistence.ts

@@ -94,7 +94,8 @@ export const validateOrdinaryStoredDocument = (
     : !(clone._id instanceof plugins.mongodb.ObjectId)) throw invalid();
   if (policyArg.timestamps === 'managed' &&
     (typeof clone._createdAt !== 'string' || typeof clone._updatedAt !== 'string')) throw invalid();
-  assertBsonWithoutMutation(clone, policyArg.assertStoredDocument, invalid);
+  assertBsonWithoutMutation(clone, plugins.mongodb.BSON.serialize(clone),
+    (documentArg) => plugins.mongodb.BSON.serialize(documentArg), policyArg.assertStoredDocument, invalid);
   // The assertion must not retain authority to mutate the returned document.
   return plugins.mongodb.BSON.deserialize(plugins.mongodb.BSON.serialize(clone));
 };