@lossless.org/client 1.7.0 → 1.8.0

package/ts/objectstorage/classes.bucket.ts

@@ -18,6 +18,7 @@ import {
   purgeExactPath as purgeExactPathOperation,
 } from './internal.exactpathpurge.operations.js';
 import { beginBasicBucketOperation } from './internal.exactupload.capability.js';
+import { headBucketExists, runAccountRequest } from './internal.bucketrequests.js';
 
 export interface IListObjectKeysPageOptions {
   prefix?: string;
@@ -240,29 +241,45 @@ const destroyReadableAndWaitForSettlement = async (
  * operate on blobs of data in an S3-compatible object store.
  */
 export class Bucket {
-  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket> {
-    const command = new plugins.s3.ListBucketsCommand({});
-    const buckets = await smartbucketRef.storageClient.send(command);
-    const foundBucket = buckets.Buckets!.find((bucket) => bucket.Name === bucketNameArg);
-
-    if (foundBucket) {
-      console.log(`bucket with name ${bucketNameArg} exists.`);
-      console.log(`Taking this as base for new Bucket instance`);
-      return new this(smartbucketRef, bucketNameArg);
-    } else {
+  /**
+   * 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 static async getBucketByName(
+    smartbucketRef: SmartBucket,
+    bucketNameArg: string,
+    optionsArg: interfaces.IBucketRequestOptions = {},
+  ): Promise<Bucket> {
+    if (!(await headBucketExists(smartbucketRef, bucketNameArg, optionsArg.signal))) {
       throw new Error(`Bucket '${bucketNameArg}' not found.`);
     }
+    return new this(smartbucketRef, bucketNameArg);
   }
 
-  public static async createBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
-    const command = new plugins.s3.CreateBucketCommand({ Bucket: bucketName });
-    await smartbucketRef.storageClient.send(command);
+  public static async createBucketByName(
+    smartbucketRef: SmartBucket,
+    bucketName: string,
+    optionsArg: interfaces.IBucketRequestOptions = {},
+  ) {
+    await runAccountRequest(smartbucketRef, optionsArg.signal, (clientArg, abortSignalArg) =>
+      clientArg.send(new plugins.s3.CreateBucketCommand({ Bucket: bucketName }), {
+        abortSignal: abortSignalArg,
+      }),
+    );
     return new Bucket(smartbucketRef, bucketName);
   }
 
-  public static async removeBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
-    const command = new plugins.s3.DeleteBucketCommand({ Bucket: bucketName });
-    await smartbucketRef.storageClient.send(command);
+  public static async removeBucketByName(
+    smartbucketRef: SmartBucket,
+    bucketName: string,
+    optionsArg: interfaces.IBucketRequestOptions = {},
+  ) {
+    await runAccountRequest(smartbucketRef, optionsArg.signal, (clientArg, abortSignalArg) =>
+      clientArg.send(new plugins.s3.DeleteBucketCommand({ Bucket: bucketName }), {
+        abortSignal: abortSignalArg,
+      }),
+    );
   }
 
   public smartbucketRef: SmartBucket;
@@ -353,43 +370,32 @@ export class Bucket {
       overwrite?: boolean;
     }
   ): Promise<File> {
-    try {
-      const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
-      if (optionsArg.overwrite !== true) {
-        const exists = await this.fastExists({ path: reducedPath });
-
-        if (exists) {
-          throw new Error(
-            `Object already exists at path '${reducedPath}' in bucket '${this.name}'. ` +
-            `Set overwrite:true to replace it.`
-          );
-        } else {
-          console.log(`Creating new object at path '${reducedPath}' in bucket '${this.name}'.`);
-        }
+    const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
+    if (optionsArg.overwrite !== true) {
+      const exists = await this.fastExists({ path: reducedPath });
+
+      if (exists) {
+        throw new Error(
+          `Object already exists at path '${reducedPath}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
+        );
       }
-
-      const command = new plugins.s3.PutObjectCommand({
-        Bucket: this.name,
-        Key: reducedPath,
-        Body: optionsArg.contents,
-      });
-      await this.smartbucketRef.storageClient.send(command);
-
-      console.log(`Object '${reducedPath}' has been successfully stored in bucket '${this.name}'.`);
-      const parsedPath = plugins.path.parse(reducedPath);
-      return new File({
-        directoryRefArg: await this.getDirectoryFromPath({
-          path: parsedPath.dir,
-        }),
-        fileName: parsedPath.base,
-      });
-    } catch (error) {
-      console.error(
-        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
-        error
-      );
-      throw error;
     }
+
+    const command = new plugins.s3.PutObjectCommand({
+      Bucket: this.name,
+      Key: reducedPath,
+      Body: optionsArg.contents,
+    });
+    await this.smartbucketRef.storageClient.send(command);
+
+    const parsedPath = plugins.path.parse(reducedPath);
+    return new File({
+      directoryRefArg: await this.getDirectoryFromPath({
+        path: parsedPath.dir,
+      }),
+      fileName: parsedPath.base,
+    });
   }
 
 
@@ -714,8 +720,6 @@ export class Bucket {
             `Object already exists at path '${optionsArg.path}' in bucket '${this.name}'. ` +
             `Set overwrite:true to replace it.`
           );
-        } else {
-          console.log(`Creating new object at path '${optionsArg.path}' in bucket '${this.name}'.`);
         }
       }
 
@@ -734,18 +738,10 @@ export class Bucket {
       await operation.runProvider(
         () => operation.client.send(command, { abortSignal: operation.signal }),
       );
-
-      console.log(
-        `Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`
-      );
     } catch (error) {
       if (sourceOwnershipStarted || putDispatched || operation.signal.aborted) {
         await disposeSource();
       }
-      console.error(
-        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
-        error
-      );
       throw error;
     } finally {
       operation.finish();
@@ -809,9 +805,6 @@ export class Bucket {
       await operation.runProvider(
         () => operation.client.send(command, { abortSignal: operation.signal }),
       );
-    } catch (err) {
-      console.error('Error updating metadata:', err);
-      throw err; // rethrow to allow caller to handle
     } finally {
       operation.finish();
     }
@@ -826,40 +819,20 @@ export class Bucket {
     targetBucket?: Bucket;
     overwrite?: boolean;
   }): Promise<void> {
-    try {
-      const destinationBucket = optionsArg.targetBucket || this;
-      const exists = await destinationBucket.fastExists({
-        path: optionsArg.destinationPath,
-      });
-
-      if (exists && !optionsArg.overwrite) {
-        console.error(
-          `Object already exists at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
-        );
-        return;
-      } else if (exists && optionsArg.overwrite) {
-        console.log(
-          `Overwriting existing object at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
-        );
-      } else {
-        console.log(
-          `Moving object to path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
-        );
-      }
-
-      await this.fastCopy(optionsArg);
-      await this.fastRemove({ path: optionsArg.sourcePath });
+    const destinationBucket = optionsArg.targetBucket || this;
+    const exists = await destinationBucket.fastExists({
+      path: optionsArg.destinationPath,
+    });
 
-      console.log(
-        `Object '${optionsArg.sourcePath}' has been successfully moved to '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
-      );
-    } catch (error) {
+    if (exists && !optionsArg.overwrite) {
       console.error(
-        `Error moving object from '${optionsArg.sourcePath}' to '${optionsArg.destinationPath}':`,
-        error
+        `Object already exists at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
       );
-      throw error;
+      return;
     }
+
+    await this.fastCopy(optionsArg);
+    await this.fastRemove({ path: optionsArg.sourcePath });
   }
 
   /**
@@ -895,7 +868,6 @@ export class Bucket {
       await operation.runProvider(
         () => operation.client.send(command, { abortSignal: operation.signal }),
       );
-      console.log(`Object '${optionsArg.path}' exists in bucket '${this.name}'.`);
       return true;
     } catch (error: any) {
       try {
@@ -904,10 +876,8 @@ export class Bucket {
         throw abortError;
       }
       if (error?.name === 'NotFound') {
-        console.log(`Object '${optionsArg.path}' does not exist in bucket '${this.name}'.`);
         return false;
       } else {
-        console.error('Error checking object existence:', error);
         throw error; // Rethrow if it's not a NotFound error to handle unexpected issues
       }
     } finally {
@@ -967,27 +937,19 @@ export class Bucket {
   }
 
   public async getMagicBytes(optionsArg: { path: string; length: number }): Promise<Buffer> {
-    try {
-      const command = new plugins.s3.GetObjectCommand({
-        Bucket: this.name,
-        Key: optionsArg.path,
-        Range: `bytes=0-${optionsArg.length - 1}`,
-      });
-      const response = await this.smartbucketRef.storageClient.send(command);
-      const chunks: Buffer[] = [];
-      const stream = response.Body as any; // SdkStreamMixin includes readable stream
+    const command = new plugins.s3.GetObjectCommand({
+      Bucket: this.name,
+      Key: optionsArg.path,
+      Range: `bytes=0-${optionsArg.length - 1}`,
+    });
+    const response = await this.smartbucketRef.storageClient.send(command);
+    const chunks: Buffer[] = [];
+    const stream = response.Body as any; // SdkStreamMixin includes readable stream
 
-      for await (const chunk of stream) {
-        chunks.push(chunk);
-      }
-      return Buffer.concat(chunks);
-    } catch (error) {
-      console.error(
-        `Error retrieving magic bytes from object at path '${optionsArg.path}' in bucket '${this.name}':`,
-        error
-      );
-      throw error;
+    for await (const chunk of stream) {
+      chunks.push(chunk);
     }
+    return Buffer.concat(chunks);
   }
 
   // ==========================================
@@ -1240,50 +1202,41 @@ export class Bucket {
   }
 
   public async cleanAllContents(): Promise<void> {
-    try {
-      // Define the command type explicitly
-      const listCommandInput: plugins.s3.ListObjectsV2CommandInput = {
-        Bucket: this.name,
-      };
-  
-      let isTruncated = true;
-      let continuationToken: string | undefined = undefined;
-  
-      while (isTruncated) {
-        // Add the continuation token to the input if present
-        const listCommand = new plugins.s3.ListObjectsV2Command({
-          ...listCommandInput,
-          ContinuationToken: continuationToken,
+    // Define the command type explicitly
+    const listCommandInput: plugins.s3.ListObjectsV2CommandInput = {
+      Bucket: this.name,
+    };
+
+    let isTruncated = true;
+    let continuationToken: string | undefined = undefined;
+
+    while (isTruncated) {
+      // Add the continuation token to the input if present
+      const listCommand = new plugins.s3.ListObjectsV2Command({
+        ...listCommandInput,
+        ContinuationToken: continuationToken,
+      });
+
+      // Explicitly type the response
+      const response: plugins.s3.ListObjectsV2Output =
+        await this.smartbucketRef.storageClient.send(listCommand);
+
+      if (response.Contents && response.Contents.length > 0) {
+        // Delete objects in batches, mapping each item to { Key: string }
+        const deleteCommand = new plugins.s3.DeleteObjectsCommand({
+          Bucket: this.name,
+          Delete: {
+            Objects: response.Contents.map((item) => ({ Key: item.Key! })),
+            Quiet: true,
+          },
         });
-  
-        // Explicitly type the response
-        const response: plugins.s3.ListObjectsV2Output =
-          await this.smartbucketRef.storageClient.send(listCommand);
-        
-        console.log(`Cleaning contents of bucket '${this.name}': Now deleting ${response.Contents?.length} items...`);
-
-        if (response.Contents && response.Contents.length > 0) {
-          // Delete objects in batches, mapping each item to { Key: string }
-          const deleteCommand = new plugins.s3.DeleteObjectsCommand({
-            Bucket: this.name,
-            Delete: {
-              Objects: response.Contents.map((item) => ({ Key: item.Key! })),
-              Quiet: true,
-            },
-          });
-  
-          await this.smartbucketRef.storageClient.send(deleteCommand);
-        }
-  
-        // Update continuation token and truncation status
-        isTruncated = response.IsTruncated || false;
-        continuationToken = response.NextContinuationToken;
+
+        await this.smartbucketRef.storageClient.send(deleteCommand);
       }
-  
-      console.log(`All contents in bucket '${this.name}' have been deleted.`);
-    } catch (error) {
-      console.error(`Error cleaning contents of bucket '${this.name}':`, error);
-      throw error;
+
+      // Update continuation token and truncation status
+      isTruncated = response.IsTruncated || false;
+      continuationToken = response.NextContinuationToken;
     }
   }
 }

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;
+  }
+};