@lossless.org/client 1.7.0 → 1.8.0

package/ts/objectstorage/internal.exactupload.capability.ts

@@ -23,6 +23,8 @@ interface IOwnedIndependentAbort {
 
 interface IActiveCapabilityOperation {
   abortController: AbortController;
+  /** Abort cause when the SmartBucket closes while the operation is active. */
+  closedDuringMessage: string;
   ownedIndependentAborts: Set<IOwnedIndependentAbort>;
   settlement: Promise<void>;
   settle: () => void;
@@ -38,14 +40,29 @@ interface ICapabilityLifecycleRecord {
   clientMutationReserved: boolean;
 }
 
-interface IExactCapabilityBinding {
-  bucketRef: IBucketCapabilityRef;
-  bucketName: string;
+interface ILifecycleBinding {
   smartbucketRef: ISmartBucketCapabilityRef;
   storageClient: plugins.s3.S3Client;
   lifecycleGeneration: number;
 }
 
+interface IExactCapabilityBinding extends ILifecycleBinding {
+  bucketRef: IBucketCapabilityRef;
+  bucketName: string;
+}
+
+/**
+ * What an operation is bound to beyond its lifecycle: a bucket reference that
+ * must keep its name and parent, or nothing for an account-scoped request.
+ * The messages describe the operation kind in lifecycle errors.
+ */
+interface IOperationIdentity {
+  isCurrent(): boolean;
+  staleMessage: string;
+  detachedMessage: string;
+  closedDuringMessage: string;
+}
+
 interface IExactPathPurgeCapabilityBinding extends IExactCapabilityBinding {
   versioningMode: TExactPathPurgeVersioningMode;
 }
@@ -76,6 +93,12 @@ export interface IExactPathPurgeOperation extends IExactUploadOperation {
   readonly versioningMode: TExactPathPurgeVersioningMode;
 }
 
+/**
+ * A lifecycle-managed provider request that addresses the storage account
+ * rather than one bucket reference, such as a bucket lookup or creation.
+ */
+export interface IAccountOperation extends Omit<IBasicBucketOperation, 'bucketName'> {}
+
 const lifecycleRecords = new WeakMap<
   ISmartBucketCapabilityRef,
   ICapabilityLifecycleRecord
@@ -102,14 +125,15 @@ const abortAndDisposeIndependentWork = (
   activeOperationArg.ownedIndependentAborts.clear();
 };
 
+const bucketDetachedMessage = 'The Bucket is not attached to a lifecycle-managed SmartBucket.';
+
 const getLifecycleRecord = (
   smartbucketRefArg: ISmartBucketCapabilityRef,
+  detachedMessageArg = bucketDetachedMessage,
 ): ICapabilityLifecycleRecord => {
   const lifecycleRecord = lifecycleRecords.get(smartbucketRefArg);
   if (!lifecycleRecord) {
-    throw new Error(
-      'The Bucket is not attached to a lifecycle-managed SmartBucket.',
-    );
+    throw new Error(detachedMessageArg);
   }
   return lifecycleRecord;
 };
@@ -189,11 +213,11 @@ export const beginOperationLifecycleClose = (
   }
   lifecycleRecord.state = 'closing';
   lifecycleRecord.generation++;
-  const lifecycleAbortCause = new Error(
-    'The SmartBucket lifecycle closed during an object operation.',
-  );
+  const lifecycleAbortCauses = new Map<IActiveCapabilityOperation, Error>();
   const activeSettlements: Promise<void>[] = [];
   for (const activeOperation of lifecycleRecord.activeOperations) {
+    const lifecycleAbortCause = new Error(activeOperation.closedDuringMessage);
+    lifecycleAbortCauses.set(activeOperation, lifecycleAbortCause);
     activeSettlements.push(activeOperation.settlement);
     activeOperation.abortController.abort(lifecycleAbortCause);
   }
@@ -206,7 +230,10 @@ export const beginOperationLifecycleClose = (
   return new Promise<void>((resolveArg) => {
     const settlementDeadline = setTimeout(() => {
       for (const activeOperation of lifecycleRecord.activeOperations) {
-        activeOperation.forceFinish(lifecycleAbortCause);
+        activeOperation.forceFinish(
+          lifecycleAbortCauses.get(activeOperation)
+            ?? new Error(activeOperation.closedDuringMessage),
+        );
       }
       resolveArg();
     }, operationCloseSettlementTimeoutMs);
@@ -230,28 +257,51 @@ export const completeOperationLifecycleClose = (
   lifecycleRecords.delete(smartbucketRefArg);
 };
 
+const bucketIdentity = (bindingArg: IExactCapabilityBinding): IOperationIdentity => ({
+  isCurrent: () =>
+    bindingArg.bucketRef.smartbucketRef === bindingArg.smartbucketRef &&
+    bindingArg.bucketRef.name === bindingArg.bucketName,
+  staleMessage: 'The exact upload capability is invalid or stale.',
+  detachedMessage: bucketDetachedMessage,
+  closedDuringMessage: 'The SmartBucket lifecycle closed during an object operation.',
+});
+
+const accountIdentity: IOperationIdentity = {
+  isCurrent: () => true,
+  staleMessage: 'The bucket request is stale.',
+  detachedMessage: 'The SmartBucket is closed; the bucket request was not sent.',
+  closedDuringMessage: 'The SmartBucket lifecycle closed during a bucket request.',
+};
+
 const assertBindingCurrent = (
-  bindingArg: IExactCapabilityBinding,
+  bindingArg: ILifecycleBinding,
+  identityArg: IOperationIdentity,
 ): void => {
-  const lifecycleRecord = getLifecycleRecord(bindingArg.smartbucketRef);
+  const lifecycleRecord = getLifecycleRecord(
+    bindingArg.smartbucketRef,
+    identityArg.detachedMessage,
+  );
   assertOpenLifecycle(lifecycleRecord);
   if (
-    bindingArg.bucketRef.smartbucketRef !== bindingArg.smartbucketRef ||
-    bindingArg.bucketRef.name !== bindingArg.bucketName ||
+    !identityArg.isCurrent() ||
     lifecycleRecord.generation !== bindingArg.lifecycleGeneration ||
     lifecycleRecord.storageClient !== bindingArg.storageClient ||
     bindingArg.smartbucketRef.storageClient !== bindingArg.storageClient
   ) {
-    throw new Error('The exact upload capability is invalid or stale.');
+    throw new Error(identityArg.staleMessage);
   }
 };
 
-const beginOperation = (
-  bindingArg: IExactCapabilityBinding,
+const beginLifecycleOperation = (
+  bindingArg: ILifecycleBinding,
+  identityArg: IOperationIdentity,
   callerSignalArg?: AbortSignal,
-): IBasicBucketOperation => {
-  assertBindingCurrent(bindingArg);
-  const lifecycleRecord = getLifecycleRecord(bindingArg.smartbucketRef);
+): IAccountOperation => {
+  assertBindingCurrent(bindingArg, identityArg);
+  const lifecycleRecord = getLifecycleRecord(
+    bindingArg.smartbucketRef,
+    identityArg.detachedMessage,
+  );
   const operationAbortController = new AbortController();
   let settleOperation!: () => void;
   const operationSettlement = new Promise<void>((resolveArg) => {
@@ -284,6 +334,7 @@ const beginOperation = (
   };
   const activeOperation: IActiveCapabilityOperation = {
     abortController: operationAbortController,
+    closedDuringMessage: identityArg.closedDuringMessage,
     ownedIndependentAborts: new Set(),
     settlement: operationSettlement,
     settle: settleOperation,
@@ -306,7 +357,6 @@ const beginOperation = (
   }
 
   return {
-    bucketName: bindingArg.bucketName,
     client: bindingArg.storageClient,
     signal: operationAbortController.signal,
     registerOwnedIndependentAbort(
@@ -332,8 +382,7 @@ const beginOperation = (
       if (
         lifecycleRecord.state === 'closed' ||
         !lifecycleRecord.activeOperations.has(activeOperation) ||
-        bindingArg.bucketRef.smartbucketRef !== bindingArg.smartbucketRef ||
-        bindingArg.bucketRef.name !== bindingArg.bucketName ||
+        !identityArg.isCurrent() ||
         lifecycleRecord.storageClient !== bindingArg.storageClient ||
         bindingArg.smartbucketRef.storageClient !== bindingArg.storageClient
       ) {
@@ -346,7 +395,7 @@ const beginOperation = (
       if (operationAbortController.signal.aborted) {
         throw operationAbortController.signal.reason;
       }
-      assertBindingCurrent(bindingArg);
+      assertBindingCurrent(bindingArg, identityArg);
     },
     runProvider<T>(
       sendArg: () => Promise<T>,
@@ -456,6 +505,38 @@ const beginOperation = (
   };
 };
 
+const beginOperation = (
+  bindingArg: IExactCapabilityBinding,
+  callerSignalArg?: AbortSignal,
+): IBasicBucketOperation => Object.assign(
+  beginLifecycleOperation(bindingArg, bucketIdentity(bindingArg), callerSignalArg),
+  { bucketName: bindingArg.bucketName },
+);
+
+/**
+ * Begins an account-scoped request under the SmartBucket lifecycle: the
+ * caller's signal and `SmartBucket.close()` both abort it, close waits for it,
+ * and the storage client cannot change while it is active.
+ */
+export const beginAccountOperation = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+  callerSignalArg?: AbortSignal,
+): IAccountOperation => {
+  const lifecycleRecord = getLifecycleRecord(
+    smartbucketRefArg,
+    accountIdentity.detachedMessage,
+  );
+  return beginLifecycleOperation(
+    {
+      smartbucketRef: smartbucketRefArg,
+      storageClient: lifecycleRecord.storageClient,
+      lifecycleGeneration: lifecycleRecord.generation,
+    },
+    accountIdentity,
+    callerSignalArg,
+  );
+};
+
 export const beginBasicBucketOperation = (
   bucketRefArg: IBucketCapabilityRef,
   callerSignalArg?: AbortSignal,