@lossless.org/client 0.1.0

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

@@ -0,0 +1,580 @@
+import * as plugins from './plugins.js';
+import type {
+  IExactPathPurgeCapability,
+  IExactUploadCapability,
+  TExactPathPurgeVersioningMode,
+} from './interfaces.js';
+
+interface ISmartBucketCapabilityRef {
+  readonly storageClient: plugins.s3.S3Client;
+}
+
+interface IBucketCapabilityRef {
+  name: string;
+  smartbucketRef: ISmartBucketCapabilityRef;
+}
+
+type TCapabilityLifecycleState = 'open' | 'closing' | 'closed';
+
+interface IOwnedIndependentAbort {
+  abortController: AbortController;
+  dispose: () => void;
+}
+
+interface IActiveCapabilityOperation {
+  abortController: AbortController;
+  ownedIndependentAborts: Set<IOwnedIndependentAbort>;
+  settlement: Promise<void>;
+  settle: () => void;
+  releaseCallerAbortListener: () => void;
+  forceFinish: (causeArg: unknown) => void;
+}
+
+interface ICapabilityLifecycleRecord {
+  state: TCapabilityLifecycleState;
+  generation: number;
+  storageClient: plugins.s3.S3Client;
+  activeOperations: Set<IActiveCapabilityOperation>;
+  clientMutationReserved: boolean;
+}
+
+interface IExactCapabilityBinding {
+  bucketRef: IBucketCapabilityRef;
+  bucketName: string;
+  smartbucketRef: ISmartBucketCapabilityRef;
+  storageClient: plugins.s3.S3Client;
+  lifecycleGeneration: number;
+}
+
+interface IExactPathPurgeCapabilityBinding extends IExactCapabilityBinding {
+  versioningMode: TExactPathPurgeVersioningMode;
+}
+
+export interface IExactUploadOperation {
+  readonly bucketName: string;
+  readonly client: plugins.s3.S3Client;
+  readonly signal: AbortSignal;
+  registerOwnedIndependentAbort(
+    abortControllerArg: AbortController,
+    disposeArg: () => void,
+  ): () => void;
+  assertLifecycleCurrent(): void;
+  assertCurrent(): void;
+  finish(): void;
+}
+
+export interface IBasicBucketOperation extends IExactUploadOperation {
+  runProvider<T>(
+    sendArg: () => Promise<T>,
+    optionsArg?: {
+      disposeLateResult?: (resultArg: T) => void | Promise<void>;
+    },
+  ): Promise<T>;
+}
+
+export interface IExactPathPurgeOperation extends IExactUploadOperation {
+  readonly versioningMode: TExactPathPurgeVersioningMode;
+}
+
+const lifecycleRecords = new WeakMap<
+  ISmartBucketCapabilityRef,
+  ICapabilityLifecycleRecord
+>();
+const capabilityBindings = new WeakMap<
+  IExactUploadCapability,
+  IExactCapabilityBinding
+>();
+const purgeCapabilityBindings = new WeakMap<
+  IExactPathPurgeCapability,
+  IExactPathPurgeCapabilityBinding
+>();
+const operationCloseSettlementTimeoutMs = 35_000;
+const basicOperationLateDisposalTimeoutMs = 5_000;
+
+const abortAndDisposeIndependentWork = (
+  activeOperationArg: IActiveCapabilityOperation,
+  causeArg: unknown,
+): void => {
+  for (const ownedAbort of activeOperationArg.ownedIndependentAborts) {
+    ownedAbort.abortController.abort(causeArg);
+    ownedAbort.dispose();
+  }
+  activeOperationArg.ownedIndependentAborts.clear();
+};
+
+const getLifecycleRecord = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+): ICapabilityLifecycleRecord => {
+  const lifecycleRecord = lifecycleRecords.get(smartbucketRefArg);
+  if (!lifecycleRecord) {
+    throw new Error(
+      'The Bucket is not attached to a lifecycle-managed SmartBucket.',
+    );
+  }
+  return lifecycleRecord;
+};
+
+const assertOpenLifecycle = (
+  lifecycleRecordArg: ICapabilityLifecycleRecord,
+): void => {
+  if (lifecycleRecordArg.state !== 'open') {
+    throw new Error(
+      `The SmartBucket operation lifecycle is ${lifecycleRecordArg.state}.`,
+    );
+  }
+  if (lifecycleRecordArg.clientMutationReserved) {
+    throw new Error('The SmartBucket storageClient is changing.');
+  }
+};
+
+export const registerOperationLifecycle = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+  storageClientArg: plugins.s3.S3Client,
+): void => {
+  if (lifecycleRecords.has(smartbucketRefArg)) {
+    throw new Error(
+      'The SmartBucket operation lifecycle is already registered.',
+    );
+  }
+  lifecycleRecords.set(smartbucketRefArg, {
+    state: 'open',
+    generation: 0,
+    storageClient: storageClientArg,
+    activeOperations: new Set(),
+    clientMutationReserved: false,
+  });
+};
+
+export const reserveOperationLifecycleClientMutation = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+): void => {
+  const lifecycleRecord = getLifecycleRecord(smartbucketRefArg);
+  assertOpenLifecycle(lifecycleRecord);
+  if (lifecycleRecord.activeOperations.size > 0) {
+    throw new Error(
+      'Cannot change storageClient while a lifecycle-managed operation is active.',
+    );
+  }
+  lifecycleRecord.clientMutationReserved = true;
+};
+
+export const commitOperationLifecycleClient = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+  storageClientArg: plugins.s3.S3Client,
+): void => {
+  const lifecycleRecord = getLifecycleRecord(smartbucketRefArg);
+  if (lifecycleRecord.state !== 'open' || !lifecycleRecord.clientMutationReserved) {
+    throw new Error('The SmartBucket storageClient mutation was not reserved.');
+  }
+  lifecycleRecord.generation++;
+  lifecycleRecord.storageClient = storageClientArg;
+  lifecycleRecord.clientMutationReserved = false;
+};
+
+export const rollbackOperationLifecycleClientMutation = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+): void => {
+  const lifecycleRecord = getLifecycleRecord(smartbucketRefArg);
+  if (lifecycleRecord.state === 'open') {
+    lifecycleRecord.clientMutationReserved = false;
+  }
+};
+
+export const beginOperationLifecycleClose = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+): Promise<void> | undefined => {
+  const lifecycleRecord = getLifecycleRecord(smartbucketRefArg);
+  if (lifecycleRecord.state === 'closed') {
+    return undefined;
+  }
+  lifecycleRecord.state = 'closing';
+  lifecycleRecord.generation++;
+  const lifecycleAbortCause = new Error(
+    'The SmartBucket lifecycle closed during an object operation.',
+  );
+  const activeSettlements: Promise<void>[] = [];
+  for (const activeOperation of lifecycleRecord.activeOperations) {
+    activeSettlements.push(activeOperation.settlement);
+    activeOperation.abortController.abort(lifecycleAbortCause);
+  }
+  if (activeSettlements.length === 0) {
+    return undefined;
+  }
+  const settleAllOperations = Promise.allSettled(activeSettlements).then(
+    () => undefined,
+  );
+  return new Promise<void>((resolveArg) => {
+    const settlementDeadline = setTimeout(() => {
+      for (const activeOperation of lifecycleRecord.activeOperations) {
+        activeOperation.forceFinish(lifecycleAbortCause);
+      }
+      resolveArg();
+    }, operationCloseSettlementTimeoutMs);
+    void settleAllOperations.then(() => {
+      clearTimeout(settlementDeadline);
+      resolveArg();
+    });
+  });
+};
+
+export const completeOperationLifecycleClose = (
+  smartbucketRefArg: ISmartBucketCapabilityRef,
+): void => {
+  const lifecycleRecord = getLifecycleRecord(smartbucketRefArg);
+  lifecycleRecord.state = 'closed';
+  for (const activeOperation of lifecycleRecord.activeOperations) {
+    activeOperation.forceFinish(
+      new Error('The SmartBucket operation lifecycle is closed.'),
+    );
+  }
+  lifecycleRecords.delete(smartbucketRefArg);
+};
+
+const assertBindingCurrent = (
+  bindingArg: IExactCapabilityBinding,
+): void => {
+  const lifecycleRecord = getLifecycleRecord(bindingArg.smartbucketRef);
+  assertOpenLifecycle(lifecycleRecord);
+  if (
+    bindingArg.bucketRef.smartbucketRef !== bindingArg.smartbucketRef ||
+    bindingArg.bucketRef.name !== bindingArg.bucketName ||
+    lifecycleRecord.generation !== bindingArg.lifecycleGeneration ||
+    lifecycleRecord.storageClient !== bindingArg.storageClient ||
+    bindingArg.smartbucketRef.storageClient !== bindingArg.storageClient
+  ) {
+    throw new Error('The exact upload capability is invalid or stale.');
+  }
+};
+
+const beginOperation = (
+  bindingArg: IExactCapabilityBinding,
+  callerSignalArg?: AbortSignal,
+): IBasicBucketOperation => {
+  assertBindingCurrent(bindingArg);
+  const lifecycleRecord = getLifecycleRecord(bindingArg.smartbucketRef);
+  const operationAbortController = new AbortController();
+  let settleOperation!: () => void;
+  const operationSettlement = new Promise<void>((resolveArg) => {
+    settleOperation = resolveArg;
+  });
+  const abortForCaller = (): void => {
+    operationAbortController.abort(
+      callerSignalArg?.reason ?? new Error('The object operation was aborted.'),
+    );
+  };
+  let callerAbortListenerReleased = false;
+  const releaseCallerAbortListener = (): void => {
+    if (callerAbortListenerReleased) {
+      return;
+    }
+    callerAbortListenerReleased = true;
+    callerSignalArg?.removeEventListener('abort', abortForCaller);
+  };
+  let finishRequested = false;
+  let pendingProviderCount = 0;
+  let settled = false;
+  const settleIfFinished = (): void => {
+    if (!finishRequested || pendingProviderCount > 0 || settled) {
+      return;
+    }
+    settled = true;
+    activeOperation.releaseCallerAbortListener();
+    lifecycleRecord.activeOperations.delete(activeOperation);
+    activeOperation.settle();
+  };
+  const activeOperation: IActiveCapabilityOperation = {
+    abortController: operationAbortController,
+    ownedIndependentAborts: new Set(),
+    settlement: operationSettlement,
+    settle: settleOperation,
+    releaseCallerAbortListener,
+    forceFinish: (causeArg: unknown): void => {
+      if (settled) {
+        return;
+      }
+      finishRequested = true;
+      pendingProviderCount = 0;
+      abortAndDisposeIndependentWork(activeOperation, causeArg);
+      settleIfFinished();
+    },
+  };
+  lifecycleRecord.activeOperations.add(activeOperation);
+
+  callerSignalArg?.addEventListener('abort', abortForCaller, { once: true });
+  if (callerSignalArg?.aborted) {
+    abortForCaller();
+  }
+
+  return {
+    bucketName: bindingArg.bucketName,
+    client: bindingArg.storageClient,
+    signal: operationAbortController.signal,
+    registerOwnedIndependentAbort(
+      abortControllerArg: AbortController,
+      disposeArg: () => void,
+    ): () => void {
+      this.assertLifecycleCurrent();
+      const ownedAbort: IOwnedIndependentAbort = {
+        abortController: abortControllerArg,
+        dispose: disposeArg,
+      };
+      activeOperation.ownedIndependentAborts.add(ownedAbort);
+      let released = false;
+      return (): void => {
+        if (released) {
+          return;
+        }
+        released = true;
+        activeOperation.ownedIndependentAborts.delete(ownedAbort);
+      };
+    },
+    assertLifecycleCurrent(): void {
+      if (
+        lifecycleRecord.state === 'closed' ||
+        !lifecycleRecord.activeOperations.has(activeOperation) ||
+        bindingArg.bucketRef.smartbucketRef !== bindingArg.smartbucketRef ||
+        bindingArg.bucketRef.name !== bindingArg.bucketName ||
+        lifecycleRecord.storageClient !== bindingArg.storageClient ||
+        bindingArg.smartbucketRef.storageClient !== bindingArg.storageClient
+      ) {
+        throw new Error(
+          'The object operation lifecycle or storage client is stale.',
+        );
+      }
+    },
+    assertCurrent(): void {
+      if (operationAbortController.signal.aborted) {
+        throw operationAbortController.signal.reason;
+      }
+      assertBindingCurrent(bindingArg);
+    },
+    runProvider<T>(
+      sendArg: () => Promise<T>,
+      optionsArg: {
+        disposeLateResult?: (resultArg: T) => void | Promise<void>;
+      } = {},
+    ): Promise<T> {
+      this.assertCurrent();
+      pendingProviderCount++;
+      return new Promise<T>((resolveArg, rejectArg) => {
+        let publicSettled = false;
+        const settlePublic = (
+          outcomeArg: { result: T } | { error: unknown },
+        ): void => {
+          if (publicSettled) {
+            return;
+          }
+          publicSettled = true;
+          operationAbortController.signal.removeEventListener('abort', abortPublicWait);
+          if ('result' in outcomeArg) {
+            resolveArg(outcomeArg.result);
+          } else {
+            rejectArg(outcomeArg.error);
+          }
+        };
+        const abortPublicWait = (): void => {
+          settlePublic({
+            error: operationAbortController.signal.reason
+              ?? new Error('The bucket operation was aborted.'),
+          });
+        };
+        operationAbortController.signal.addEventListener('abort', abortPublicWait, {
+          once: true,
+        });
+
+        let providerPromise: Promise<T>;
+        try {
+          providerPromise = sendArg();
+        } catch (error) {
+          pendingProviderCount--;
+          settleIfFinished();
+          settlePublic({ error });
+          return;
+        }
+
+        void providerPromise.then(
+          async (resultArg) => {
+            if (
+              operationAbortController.signal.aborted
+              && optionsArg.disposeLateResult
+            ) {
+              const disposal = Promise.resolve()
+                .then(() => optionsArg.disposeLateResult!(resultArg));
+              void disposal.catch(() => undefined);
+              let disposalDeadline: ReturnType<typeof setTimeout> | undefined;
+              try {
+                await Promise.race([
+                  disposal.catch(() => undefined),
+                  new Promise<void>((resolveDisposalArg) => {
+                    disposalDeadline = setTimeout(
+                      resolveDisposalArg,
+                      basicOperationLateDisposalTimeoutMs,
+                    );
+                  }),
+                ]);
+              } finally {
+                if (disposalDeadline) {
+                  clearTimeout(disposalDeadline);
+                }
+              }
+            }
+            pendingProviderCount--;
+            settleIfFinished();
+            if (operationAbortController.signal.aborted) {
+              abortPublicWait();
+            } else {
+              settlePublic({ result: resultArg });
+            }
+          },
+          (errorArg: unknown) => {
+            pendingProviderCount--;
+            settleIfFinished();
+            if (operationAbortController.signal.aborted) {
+              abortPublicWait();
+            } else {
+              settlePublic({ error: errorArg });
+            }
+          },
+        );
+
+        if (operationAbortController.signal.aborted) {
+          abortPublicWait();
+        }
+      });
+    },
+    finish(): void {
+      if (finishRequested) {
+        return;
+      }
+      finishRequested = true;
+      abortAndDisposeIndependentWork(
+        activeOperation,
+        new Error('The object operation finished.'),
+      );
+      settleIfFinished();
+    },
+  };
+};
+
+export const beginBasicBucketOperation = (
+  bucketRefArg: IBucketCapabilityRef,
+  callerSignalArg?: AbortSignal,
+): IBasicBucketOperation => {
+  const smartbucketRef = bucketRefArg.smartbucketRef;
+  const lifecycleRecord = getLifecycleRecord(smartbucketRef);
+  const binding: IExactCapabilityBinding = {
+    bucketRef: bucketRefArg,
+    bucketName: bucketRefArg.name,
+    smartbucketRef,
+    storageClient: lifecycleRecord.storageClient,
+    lifecycleGeneration: lifecycleRecord.generation,
+  };
+  return beginOperation(binding, callerSignalArg);
+};
+
+export const beginExactUploadProbeOperation = (
+  bucketRefArg: IBucketCapabilityRef,
+  callerSignalArg?: AbortSignal,
+): IExactUploadOperation => {
+  const smartbucketRef = bucketRefArg.smartbucketRef;
+  const lifecycleRecord = getLifecycleRecord(smartbucketRef);
+  const binding: IExactCapabilityBinding = {
+    bucketRef: bucketRefArg,
+    bucketName: bucketRefArg.name,
+    smartbucketRef,
+    storageClient: lifecycleRecord.storageClient,
+    lifecycleGeneration: lifecycleRecord.generation,
+  };
+  return beginOperation(binding, callerSignalArg);
+};
+
+export const beginExactPathPurgeProbeOperation = (
+  bucketRefArg: IBucketCapabilityRef,
+  callerSignalArg?: AbortSignal,
+): IExactUploadOperation => {
+  const smartbucketRef = bucketRefArg.smartbucketRef;
+  const lifecycleRecord = getLifecycleRecord(smartbucketRef);
+  const binding: IExactCapabilityBinding = {
+    bucketRef: bucketRefArg,
+    bucketName: bucketRefArg.name,
+    smartbucketRef,
+    storageClient: lifecycleRecord.storageClient,
+    lifecycleGeneration: lifecycleRecord.generation,
+  };
+  return beginOperation(binding, callerSignalArg);
+};
+
+export const mintExactUploadCapability = (
+  bucketRefArg: IBucketCapabilityRef,
+  operationArg: IExactUploadOperation,
+): IExactUploadCapability => {
+  operationArg.assertCurrent();
+  const smartbucketRef = bucketRefArg.smartbucketRef;
+  const lifecycleRecord = getLifecycleRecord(smartbucketRef);
+  const capability = Object.freeze({}) as IExactUploadCapability;
+  capabilityBindings.set(capability, {
+    bucketRef: bucketRefArg,
+    bucketName: operationArg.bucketName,
+    smartbucketRef,
+    storageClient: operationArg.client,
+    lifecycleGeneration: lifecycleRecord.generation,
+  });
+  return capability;
+};
+
+export const beginExactUploadCapabilityOperation = (
+  bucketRefArg: IBucketCapabilityRef,
+  capabilityArg: IExactUploadCapability,
+  callerSignalArg?: AbortSignal,
+): IExactUploadOperation => {
+  if (
+    typeof capabilityArg !== 'object' ||
+    capabilityArg === null
+  ) {
+    throw new Error('The exact upload capability is invalid or stale.');
+  }
+  const binding = capabilityBindings.get(capabilityArg);
+  if (!binding || binding.bucketRef !== bucketRefArg) {
+    throw new Error('The exact upload capability is invalid or stale.');
+  }
+  return beginOperation(binding, callerSignalArg);
+};
+
+export const mintExactPathPurgeCapability = (
+  bucketRefArg: IBucketCapabilityRef,
+  operationArg: IExactUploadOperation,
+  versioningModeArg: TExactPathPurgeVersioningMode,
+): IExactPathPurgeCapability => {
+  operationArg.assertCurrent();
+  const smartbucketRef = bucketRefArg.smartbucketRef;
+  const lifecycleRecord = getLifecycleRecord(smartbucketRef);
+  const capability = Object.freeze({}) as IExactPathPurgeCapability;
+  purgeCapabilityBindings.set(capability, {
+    bucketRef: bucketRefArg,
+    bucketName: operationArg.bucketName,
+    smartbucketRef,
+    storageClient: operationArg.client,
+    lifecycleGeneration: lifecycleRecord.generation,
+    versioningMode: versioningModeArg,
+  });
+  return capability;
+};
+
+export const beginExactPathPurgeCapabilityOperation = (
+  bucketRefArg: IBucketCapabilityRef,
+  capabilityArg: IExactPathPurgeCapability,
+  callerSignalArg?: AbortSignal,
+): IExactPathPurgeOperation => {
+  if (typeof capabilityArg !== 'object' || capabilityArg === null) {
+    throw new Error('The exact-path purge capability is invalid or stale.');
+  }
+  const binding = purgeCapabilityBindings.get(capabilityArg);
+  if (!binding || binding.bucketRef !== bucketRefArg) {
+    throw new Error('The exact-path purge capability is invalid or stale.');
+  }
+  const operation = beginOperation(binding, callerSignalArg);
+  return {
+    ...operation,
+    versioningMode: binding.versioningMode,
+  };
+};