@lossless.org/client 2.4.1 → 2.6.0

package/ts/nosqldb/classes.exactpersistence.ts

@@ -9,6 +9,7 @@ import { registerCollectionReconnectHandler } from './classes.collectionlifecycl
 import {
   SmartdataSession,
   acquireSmartdataSession,
+  isOrdinarySessionInTransaction,
   needsSmartdataWriteTransaction,
   readPreviousWriteRevisions,
   reportSmartdataCollectionWrite,
@@ -19,6 +20,11 @@ import {
   trackSmartdataRead,
 } from './classes.session.js';
 import { runSmartdataWrite } from './classes.readtracker.js';
+import {
+  type ISmartdataEngineIdentity,
+  readFenceEngineRelease,
+  smartdataReadFence,
+} from './engineidentity.js';
 import {
   type SmartdataOperationDeadline,
   requireOperationSignal,
@@ -173,6 +179,22 @@ export type TExactDeleteResult =
       deletedCount: 0;
     };
 
+/**
+ * The result of an exact read fence: the identity is fenced for the commit of
+ * the session's active transaction.
+ */
+export type TExactReadFenceResult = {
+  status: 'fenced';
+};
+
+/**
+ * A model's identity in the form `findStoredOne()` takes it: its `reconcileBy`
+ * field and the value, `{ [reconcileBy]: value }`.
+ */
+export type TExactIdentity<TPersisted extends object> = Partial<
+  Record<TExactIdentityKey<TPersisted>, string>
+>;
+
 export type TExactPersistenceErrorCode =
   | 'ambiguous_write'
   | 'invalid_configuration'
@@ -236,7 +258,7 @@ export interface IExactReadOptions extends IExactSessionOptions {
 
 /**
  * Options of every exact call: `insert()`, `transition()`, `delete()`,
- * `count()`, `distinct()` and `findStoredOne()`, and through
+ * `readFence()`, `count()`, `distinct()` and `findStoredOne()`, and through
  * `IFindStoredOptions` `findStored()`.
  */
 export interface IExactBoundedOptions extends IExactReadOptions {
@@ -2132,8 +2154,106 @@ export class SmartdataExactCollection<
     );
     });
   }
+
+  /**
+   * Fences a model identity for the commit of the session's active
+   * transaction, whether a document holds it or not: the engine refuses the
+   * commit as a transient write conflict, so `withTransaction()` re-runs the
+   * attempt, when after the transaction's snapshot a committed write inserted
+   * a document with that identity, or changed, deleted or re-inserted the one
+   * holding it. Fences claim nothing: two transactions that fence one
+   * identity both commit, and a fence never makes a writer wait or fail.
+   *
+   * `identityArg` names the identity as `findStoredOne()` does,
+   * `{ [reconcileBy]: value }`, and is sent as one key fence on the model's
+   * unique `reconcileBy` index, which preparation creates. Refused with
+   * `unsupported_operation` before any command is sent without a session in an
+   * active transaction, for a collection that is not prepared, and on an
+   * engine that is not identified as NoSQLDB 10.11.0 or later.
+   */
+  public async readFence(
+    identityArg: TExactIdentity<TPersisted>,
+    sessionOptionsArg: IExactBoundedOptions = {},
+  ): Promise<TExactReadFenceResult> {
+    const identity = this.readFenceIdentity(identityArg);
+    const session = sessionOptionsArg.session;
+    if (!session || !isOrdinarySessionInTransaction(session)) {
+      throw new SmartdataExactPersistenceError(
+        'unsupported_operation',
+        'Exact readFence needs a session in an active transaction: a fence only guards a transaction commit.',
+      );
+    }
+    const engine = this.collection.smartdataDb.engineIdentity;
+    if (!smartdataReadFence(engine)) {
+      throw new SmartdataExactPersistenceError(
+        'unsupported_operation',
+        `Exact readFence needs NoSQLDB ${readFenceEngineRelease} or later; `
+          + `the connected engine is ${describeEngine(engine)}.`,
+      );
+    }
+    return this.runOperation(sessionOptionsArg, async (sessionArg, deadlineArg) => {
+      // A transient error, such as an aborted transaction, reaches the
+      // driver's withTransaction unchanged.
+      await this.collection.smartdataDb.mongoDb.command(
+        {
+          readFence: this.collection.mongoDbCollection.collectionName,
+          key: this.reconcileBy,
+          values: [identity],
+        },
+        { session: sessionArg, ...deadlineArg.commandOptions() },
+      );
+      return { status: 'fenced' };
+    });
+  }
+
+  /**
+   * Validates `{ [reconcileBy]: value }` without invoking accessors or proxies:
+   * exactly one enumerable data property, the model's `reconcileBy`, holding
+   * a nonempty string.
+   */
+  private readFenceIdentity(identityArg: unknown): string {
+    if (
+      typeof identityArg !== 'object' ||
+      identityArg === null ||
+      plugins.nodeUtil.types.isProxy(identityArg) ||
+      !isPlainObject(identityArg)
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        `Exact readFence takes the identity as { ${this.reconcileBy}: value }.`,
+      );
+    }
+    const keys = Reflect.ownKeys(identityArg);
+    const descriptor = Object.getOwnPropertyDescriptor(identityArg, this.reconcileBy);
+    if (
+      keys.length !== 1 ||
+      keys[0] !== this.reconcileBy ||
+      !descriptor ||
+      !('value' in descriptor) ||
+      descriptor.enumerable !== true ||
+      typeof descriptor.value !== 'string' ||
+      descriptor.value.trim().length === 0
+    ) {
+      throw new SmartdataExactPersistenceError(
+        'invalid_document',
+        `Exact readFence takes the identity as one inert { ${this.reconcileBy}: nonempty string } property.`,
+      );
+    }
+    return descriptor.value;
+  }
 }
 
+const describeEngine = (identityArg: ISmartdataEngineIdentity): string => {
+  switch (identityArg.product) {
+    case 'NoSQLDB':
+      return `NoSQLDB ${identityArg.version ?? 'of an unstated version'}`;
+    case 'MongoDB':
+      return 'MongoDB';
+    case 'unknown':
+      return 'unidentified';
+  }
+};
+
 export function exactPersistence<
   TAssertion extends TExactDocumentAssertion<object>,
 >(

package/ts/nosqldb/engineidentity.ts

@@ -38,6 +38,13 @@ const compositeGroupingEngineRelease = '10.5.0';
  */
 const commitJournalEngineRelease = '10.9.0';
 
+/**
+ * The NoSQLDB release that answers the `readFence` transaction statement:
+ * @lossless.org/nosqldb 10.11.0. A minimum release, like every gate here:
+ * every later release supports it.
+ */
+export const readFenceEngineRelease = '10.11.0';
+
 const parseEngineVersion = (versionArg: string): readonly number[] | undefined => {
   const parts = versionArg.split('.');
   if (parts.length !== 3) {
@@ -107,6 +114,17 @@ export const smartdataCommitJournal = (identityArg: ISmartdataEngineIdentity): b
   && identityArg.version !== null
   && engineVersionReaches(identityArg.version, commitJournalEngineRelease);
 
+/**
+ * Whether the identified engine answers `readFence`: fences documents a
+ * transaction read so that its commit is refused when one of them changed
+ * after the transaction's snapshot. Only NoSQLDB does, from 10.11.0 on;
+ * MongoDB has no such statement, and an unidentified engine enables nothing.
+ */
+export const smartdataReadFence = (identityArg: ISmartdataEngineIdentity): boolean =>
+  identityArg.product === 'NoSQLDB'
+  && identityArg.version !== null
+  && engineVersionReaches(identityArg.version, readFenceEngineRelease);
+
 export const composeSmartdataCapabilities = (
   backendArg: TSmartdataEngineBackend,
   compositeGroupingArg: TCompositeGrouping,

package/ts/objectstorage/classes.bucket.ts

@@ -935,14 +935,21 @@ export class Bucket {
   }
 
   /**
-   * Creates an object from a stream while enforcing the declared byte length
-   * and create-only destination semantics.
+   * Stores an object from a stream while enforcing the declared byte length
+   * (or the maximum of an undeclared one) and the destination mode: create-only
+   * with a `capability` from probeExactUploadCapability(), or replace with
+   * `overwrite: true`, which sends no `If-None-Match` and needs no capability.
+   * A replaced object stays readable and unchanged until the final
+   * CompleteMultipartUpload (or the PutObject of an empty source) replaces it
+   * in one step.
    *
    * Non-empty inputs always use multipart upload and never fall back to a
-   * single streaming PutObject request. Memory is bounded by the returned
+   * single streaming PutObject request, so each part is its own request,
+   * bounded by `requestTimeoutMs` on its own. Memory is bounded by the returned
    * multipart plan. Every source chunk must be no larger than the effective
    * multipart part size (5 MiB by default, or requestedPartSize after protocol
-   * normalization).
+   * normalization). Any failure aborts the multipart upload instead of
+   * completing it.
    */
   public fastPutStreamExact(
     optionsArg: interfaces.IFastPutStreamExactOptions,

package/ts/objectstorage/classes.exactuploaderror.ts

@@ -6,10 +6,10 @@ import type {
 const phaseMessages: Record<TExactUploadFailurePhase, string> = {
   capability: 'The exact upload capability is invalid or stale.',
   source: 'The exact upload source could not be consumed.',
-  'put-zero': 'The conditional zero-byte object upload failed.',
+  'put-zero': 'The zero-byte object upload failed.',
   'create-multipart': 'The multipart upload could not be created.',
   'upload-part': 'A multipart upload part failed.',
-  'complete-multipart': 'The conditional multipart completion failed.',
+  'complete-multipart': 'The multipart completion failed.',
 };
 
 export class ExactUploadError extends Error {

package/ts/objectstorage/interfaces.ts

@@ -214,7 +214,7 @@ declare const exactUploadCapabilityBrand: unique symbol;
 
 /**
  * Opaque proof that the current bucket provider enforces the conditional
- * operations required by Bucket.fastPutStreamExact().
+ * operations required by a create-only Bucket.fastPutStreamExact().
  *
  * Capabilities can only be minted by Bucket.probeExactUploadCapability().
  * They are bound to one exact Bucket object and its current SmartBucket,
@@ -262,7 +262,25 @@ export interface IExactUploadNativeObjectProperties {
 }
 
 export interface IFastPutStreamExactOptions {
-  capability: IExactUploadCapability;
+  /**
+   * Create-only upload: a capability from
+   * Bucket.probeExactUploadCapability(). The PutObject and
+   * CompleteMultipartUpload are sent with `If-None-Match: *`, so the upload
+   * fails instead of replacing an existing object. Exactly one of
+   * `capability` and `overwrite: true` must be given.
+   */
+  capability?: IExactUploadCapability;
+  /**
+   * Replace upload: `true` stores the object whether or not the key exists,
+   * with the same multipart plan, part bounds, buffering limit, failure
+   * phases and abort-on-failure cleanup as a create-only upload, but without
+   * `If-None-Match` and without a capability. An existing object stays
+   * readable and unchanged until the final CompleteMultipartUpload (or the
+   * PutObject of an empty source) replaces it in one step; a failure before
+   * that request leaves it as it was. Exactly one of `capability` and
+   * `overwrite: true` must be given.
+   */
+  overwrite?: boolean;
   path: string;
   /**
    * Every emitted chunk must be no larger than the effective multipart part
@@ -294,6 +312,10 @@ export interface IFastPutStreamExactOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * The step an exact upload failed in. A replace upload (`overwrite: true`)
+ * has no capability step and never fails in `'capability'`.
+ */
 export type TExactUploadFailurePhase =
   | 'capability'
   | 'source'
@@ -338,9 +360,16 @@ export interface IExactUploadFailureState {
   maxContentLength?: number;
   /**
    * Whether this operation can prove that it did not publish the destination.
-   * A conditional PutObject or CompleteMultipartUpload response can be lost
-   * after the provider has committed the object, so those failures are
-   * intentionally reported as ambiguous.
+   * A PutObject or CompleteMultipartUpload response can be lost after the
+   * provider has committed the object, so those failures are intentionally
+   * reported as ambiguous. A create-only upload reports a definitive
+   * conditional rejection (HTTP 409 or 412) as not published.
+   *
+   * For a replace upload (`overwrite: true`), `'not-published'` means the
+   * destination is as it was before the upload, the old object included, and
+   * `'ambiguous'` means either the old object or the new one is visible; every
+   * failed PutObject or CompleteMultipartUpload that was sent is ambiguous,
+   * since no precondition was sent whose rejection would prove otherwise.
    */
   destinationPublication: 'not-published' | 'ambiguous';
   multipartUploadId?: string;

package/ts/objectstorage/internal.exactupload.operations.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import { ExactUploadError } from './classes.exactuploaderror.js';
 import type {
+  IExactUploadCapability,
   IExactUploadCapabilityProbeOptions,
   IExactUploadResult,
   IFastPutStreamExactOptions,
@@ -10,6 +11,7 @@ import type {
   TExactUploadMultipartCleanup,
 } from './interfaces.js';
 import {
+  beginBasicBucketOperation,
   beginExactUploadCapabilityOperation,
   beginExactUploadProbeOperation,
   mintExactUploadCapability,
@@ -1345,10 +1347,48 @@ const planExactUpload = (optionsArg: IFastPutStreamExactOptions) => {
   };
 };
 
-const sendConditionalZeroPut = (
+type TExactUploadDestinationMode =
+  | {
+      replace: false;
+      capability: IExactUploadCapability;
+    }
+  | {
+      replace: true;
+    };
+
+/**
+ * Reads the destination mode: create-only with a capability, or replace with
+ * `overwrite: true`. Exactly one of the two must be given.
+ */
+const resolveDestinationMode = (
+  optionsArg: IFastPutStreamExactOptions,
+): TExactUploadDestinationMode => {
+  if (
+    optionsArg.overwrite !== undefined
+    && typeof optionsArg.overwrite !== 'boolean'
+  ) {
+    throw new TypeError('overwrite must be a boolean.');
+  }
+  const replace = optionsArg.overwrite === true;
+  if (replace === (optionsArg.capability !== undefined)) {
+    throw new TypeError(
+      'Exactly one of capability and overwrite: true must be given.',
+    );
+  }
+  return optionsArg.capability === undefined
+    ? { replace: true }
+    : { replace: false, capability: optionsArg.capability };
+};
+
+/**
+ * Sends the PutObject of an empty source, create-only with
+ * `If-None-Match: *` unless the upload replaces.
+ */
+const sendZeroPut = (
   operationArg: IExactUploadOperation,
   optionsArg: IFastPutStreamExactOptions,
   contentTypeArg: string | undefined,
+  replaceArg: boolean,
   onAttemptArg: () => void,
 ) => {
   return sendOperationCommand(
@@ -1363,7 +1403,7 @@ const sendConditionalZeroPut = (
           ContentLength: 0,
           Metadata: optionsArg.nativeMetadata,
           ContentType: contentTypeArg,
-          IfNoneMatch: '*',
+          ...(replaceArg ? {} : { IfNoneMatch: '*' }),
         }),
         {
           abortSignal: signalArg,
@@ -1380,31 +1420,43 @@ export const fastPutStreamExact = async (
   if (typeof optionsArg.path !== 'string' || optionsArg.path.length === 0) {
     throw new TypeError('path must be a non-empty string.');
   }
+  const destinationMode = resolveDestinationMode(optionsArg);
+  const replace = destinationMode.replace;
   const nativeObjectProperties = snapshotNativeObjectProperties(
     optionsArg.nativeObjectProperties,
   );
   const { plan, lengthState } = planExactUpload(optionsArg);
+  // Only a create-only upload sends a precondition, so only its definitive
+  // rejection proves that the request did not publish the destination.
+  const provesNotPublished = (errorArg: unknown): boolean =>
+    !replace && isDefinitiveConditionalWriteRejection(errorArg);
 
   let operation: IExactUploadOperation;
-  try {
-    operation = beginExactUploadCapabilityOperation(
-      bucketRefArg,
-      optionsArg.capability,
-      optionsArg.signal,
-    );
-  } catch (error) {
-    throw new ExactUploadError(
-      {
-        phase: 'capability',
-        destinationPath: optionsArg.path,
-        ...lengthState,
-        destinationPublication: 'not-published',
-        multipartCleanup: {
-          status: 'not-required',
+  if (destinationMode.replace) {
+    // A replace upload has no capability step: it starts like every other
+    // bucket request, which refuses an invalid signal or a closed SmartBucket.
+    operation = beginBasicBucketOperation(bucketRefArg, optionsArg.signal);
+  } else {
+    try {
+      operation = beginExactUploadCapabilityOperation(
+        bucketRefArg,
+        destinationMode.capability,
+        optionsArg.signal,
+      );
+    } catch (error) {
+      throw new ExactUploadError(
+        {
+          phase: 'capability',
+          destinationPath: optionsArg.path,
+          ...lengthState,
+          destinationPublication: 'not-published',
+          multipartCleanup: {
+            status: 'not-required',
+          },
         },
-      },
-      error,
-    );
+        error,
+      );
+    }
   }
 
   let readableStream: ReadableStream<Uint8Array>;
@@ -1467,10 +1519,11 @@ export const fastPutStreamExact = async (
       }
 
       try {
-        const putOutput = await sendConditionalZeroPut(
+        const putOutput = await sendZeroPut(
           operation,
           optionsArg,
           nativeObjectProperties?.contentType,
+          replace,
           () => {
             putRequestAttempted = true;
           },
@@ -1494,8 +1547,7 @@ export const fastPutStreamExact = async (
             destinationPath: optionsArg.path,
             ...lengthState,
             destinationPublication:
-              putRequestAttempted &&
-              !isDefinitiveConditionalWriteRejection(error)
+              putRequestAttempted && !provesNotPublished(error)
                 ? 'ambiguous'
                 : 'not-published',
             multipartCleanup: {
@@ -1638,10 +1690,11 @@ export const fastPutStreamExact = async (
     if (!multipartUploadCreation) {
       // Only an empty source of undeclared length reaches this point.
       phase = 'put-zero';
-      const putOutput = await sendConditionalZeroPut(
+      const putOutput = await sendZeroPut(
         operation,
         optionsArg,
         nativeObjectProperties?.contentType,
+        replace,
         () => {
           zeroPutAttempted = true;
         },
@@ -1670,7 +1723,7 @@ export const fastPutStreamExact = async (
             MultipartUpload: {
               Parts: completedParts,
             },
-            IfNoneMatch: '*',
+            ...(replace ? {} : { IfNoneMatch: '*' }),
             MpuObjectSize: consumptionResult.bytesConsumed,
           }),
           {
@@ -1789,7 +1842,7 @@ export const fastPutStreamExact = async (
             (phase === 'complete-multipart' && completeRequestAttempted) ||
             (phase === 'put-zero' && zeroPutAttempted)
           ) &&
-          !isDefinitiveConditionalWriteRejection(error)
+          !provesNotPublished(error)
             ? 'ambiguous'
             : 'not-published',
         multipartUploadId: uploadId,