@lossless.org/client 1.6.0 → 1.8.0

package/ts/objectstorage/classes.directory.ts

@@ -179,30 +179,25 @@ export class Directory {
    * lists all folders
    */
   public async listDirectories(): Promise<Directory[]> {
-    try {
-      const { commonPrefixes } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
-      const directoryArray: Directory[] = [];
-  
-      if (commonPrefixes) {
-        commonPrefixes.forEach((item) => {
-          if (item.Prefix) {
-            const subtractedPath = item.Prefix.replace(this.getBasePath(), '');
-            if (subtractedPath.endsWith('/')) {
-              const dirName = subtractedPath.slice(0, -1);
-              // Ensure the directory name is not empty (which would indicate the base directory itself)
-              if (dirName) {
-                directoryArray.push(new Directory(this.bucketRef, this, dirName));
-              }
+    const { commonPrefixes } = await this.listObjectsV2AllPages(this.getBasePath(), '/');
+    const directoryArray: Directory[] = [];
+
+    if (commonPrefixes) {
+      commonPrefixes.forEach((item) => {
+        if (item.Prefix) {
+          const subtractedPath = item.Prefix.replace(this.getBasePath(), '');
+          if (subtractedPath.endsWith('/')) {
+            const dirName = subtractedPath.slice(0, -1);
+            // Ensure the directory name is not empty (which would indicate the base directory itself)
+            if (dirName) {
+              directoryArray.push(new Directory(this.bucketRef, this, dirName));
             }
           }
-        });
-      }
-  
-      return directoryArray;
-    } catch (error) {
-      console.error('Error listing directories:', error);
-      throw error;
+        }
+      });
     }
+
+    return directoryArray;
   }
 
   /**
@@ -409,12 +404,8 @@ export class Directory {
   }) {
     const deleteDirectory = async (directoryArg: Directory) => {
       const childDirectories = await directoryArg.listDirectories();
-      if (childDirectories.length === 0) {
-        console.log('Directory empty! Path complete!');
-      } else {
-        for (const childDir of childDirectories) {
-          await deleteDirectory(childDir);
-        }
+      for (const childDir of childDirectories) {
+        await deleteDirectory(childDir);
       }
       const files = await directoryArg.listFiles();
       for (const file of files) {

package/ts/objectstorage/classes.smartbucket.ts

@@ -3,6 +3,7 @@
 import * as plugins from './plugins.js';
 import { Bucket } from './classes.bucket.js';
 import { normalizeStorageDescriptor } from './helpers.js';
+import { headBucketExists } from './internal.bucketrequests.js';
 import {
   beginOperationLifecycleClose,
   commitOperationLifecycleClient,
@@ -12,6 +13,7 @@ import {
   rollbackOperationLifecycleClientMutation,
 } from './internal.exactupload.capability.js';
 import type {
+  IBucketRequestOptions,
   ISmartBucketReadinessOptions,
   TSmartBucketReadinessFailureReason,
   TSmartBucketReadinessResult,
@@ -107,26 +109,34 @@ export class SmartBucket {
     registerOperationLifecycle(this, this.currentStorageClient);
   }
 
-  public async createBucket(bucketNameArg: string) {
-    const bucket = await Bucket.createBucketByName(this, bucketNameArg);
+  public async createBucket(bucketNameArg: string, optionsArg: IBucketRequestOptions = {}) {
+    const bucket = await Bucket.createBucketByName(this, bucketNameArg, optionsArg);
     return bucket;
   }
 
-  public async removeBucket(bucketName: string) {
-    await Bucket.removeBucketByName(this, bucketName);
+  public async removeBucket(bucketName: string, optionsArg: IBucketRequestOptions = {}) {
+    await Bucket.removeBucketByName(this, bucketName, optionsArg);
   }
 
-  public async getBucketByName(bucketNameArg: string) {
-    return Bucket.getBucketByName(this, bucketNameArg);
+  /**
+   * Returns a reference to an existing bucket, checked with one HeadBucket
+   * request. Rejects when the bucket does not exist or the credentials may
+   * not access it.
+   */
+  public async getBucketByName(bucketNameArg: string, optionsArg: IBucketRequestOptions = {}) {
+    return Bucket.getBucketByName(this, bucketNameArg, optionsArg);
   }
 
   /**
-   * Check if a bucket exists
+   * Checks with one HeadBucket request whether a bucket exists. Resolves
+   * `false` for a missing bucket and rejects when the credentials may not
+   * access it.
    */
-  public async bucketExists(bucketNameArg: string): Promise<boolean> {
-    const command = new plugins.s3.ListBucketsCommand({});
-    const buckets = await this.currentStorageClient.send(command);
-    return buckets.Buckets?.some(bucket => bucket.Name === bucketNameArg) ?? false;
+  public async bucketExists(
+    bucketNameArg: string,
+    optionsArg: IBucketRequestOptions = {},
+  ): Promise<boolean> {
+    return headBucketExists(this, bucketNameArg, optionsArg.signal);
   }
 
   /**

package/ts/objectstorage/classes.watcher.ts

@@ -83,7 +83,6 @@ export class BucketWatcher extends EventEmitter {
    */
   public async start(): Promise<void> {
     if (this.pollIntervalId !== null) {
-      console.log('BucketWatcher is already running');
       return;
     }
 

package/ts/objectstorage/interfaces.ts

@@ -52,6 +52,15 @@ export interface IDirectoryFastPutStreamOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for a request about a bucket itself: `getBucketByName()`,
+ * `bucketExists()`, `createBucket()` and `removeBucket()`.
+ */
+export interface IBucketRequestOptions {
+  /** Optional caller-owned cancellation signal */
+  signal?: AbortSignal;
+}
+
 // ================================
 // SmartBucket Readiness Interfaces
 // ================================

package/ts/objectstorage/internal.bucketrequests.ts

@@ -0,0 +1,70 @@
+import * as plugins from './plugins.js';
+import type { SmartBucket } from './classes.smartbucket.js';
+import { beginAccountOperation } from './internal.exactupload.capability.js';
+
+/**
+ * Sends one account-scoped request under the SmartBucket lifecycle. The
+ * caller's signal and `SmartBucket.close()` abort the in-flight SDK request.
+ */
+export const runAccountRequest = async <T>(
+  smartbucketRefArg: SmartBucket,
+  signalArg: AbortSignal | undefined,
+  sendArg: (clientArg: plugins.s3.S3Client, abortSignalArg: AbortSignal) => Promise<T>,
+): Promise<T> => {
+  const operation = beginAccountOperation(smartbucketRefArg, signalArg);
+  try {
+    return await operation.runProvider(() => sendArg(operation.client, operation.signal));
+  } finally {
+    operation.finish();
+  }
+};
+
+const getProviderStatus = (errorArg: unknown): { name?: string; httpStatusCode?: number } => {
+  if (typeof errorArg !== 'object' || errorArg === null) {
+    return {};
+  }
+  const providerError = errorArg as {
+    name?: unknown;
+    $metadata?: { httpStatusCode?: unknown };
+  };
+  return {
+    name: typeof providerError.name === 'string' ? providerError.name : undefined,
+    httpStatusCode: typeof providerError.$metadata?.httpStatusCode === 'number'
+      ? providerError.$metadata.httpStatusCode
+      : undefined,
+  };
+};
+
+/**
+ * Answers whether the bucket exists with one HeadBucket request, which a
+ * bucket-scoped credential may send for its own bucket. A missing bucket
+ * resolves `false`; a bucket the credentials may not access rejects, because
+ * S3 does not say whether it exists.
+ */
+export const headBucketExists = async (
+  smartbucketRefArg: SmartBucket,
+  bucketNameArg: string,
+  signalArg: AbortSignal | undefined,
+): Promise<boolean> => {
+  try {
+    await runAccountRequest(smartbucketRefArg, signalArg, (clientArg, abortSignalArg) =>
+      clientArg.send(new plugins.s3.HeadBucketCommand({ Bucket: bucketNameArg }), {
+        abortSignal: abortSignalArg,
+      }),
+    );
+    return true;
+  } catch (error) {
+    const { name, httpStatusCode } = getProviderStatus(error);
+    if (httpStatusCode === 404 || name === 'NotFound' || name === 'NoSuchBucket') {
+      return false;
+    }
+    if (httpStatusCode === 403 || name === 'Forbidden' || name === 'AccessDenied') {
+      throw new Error(
+        `Access to bucket '${bucketNameArg}' was denied (HTTP 403): the credentials may not ` +
+        `read this bucket, or it belongs to another account.`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+};

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,