@lossless.org/client 0.1.0

package/ts/objectstorage/classes.smartbucket.ts

@@ -0,0 +1,445 @@
+// classes.smartbucket.ts
+
+import * as plugins from './plugins.js';
+import { Bucket } from './classes.bucket.js';
+import { normalizeStorageDescriptor } from './helpers.js';
+import {
+  beginOperationLifecycleClose,
+  commitOperationLifecycleClient,
+  completeOperationLifecycleClose,
+  registerOperationLifecycle,
+  reserveOperationLifecycleClientMutation,
+  rollbackOperationLifecycleClientMutation,
+} from './internal.exactupload.capability.js';
+import type {
+  ISmartBucketReadinessOptions,
+  TSmartBucketReadinessFailureReason,
+  TSmartBucketReadinessResult,
+} from './interfaces.js';
+
+type TSmartBucketLifecycleState = 'open' | 'closing' | 'closed';
+type TSmartBucketReadinessAbortSource = 'caller' | 'deadline';
+type TSmartBucketReadinessSendOutcome = 'ready' | 'aborted' | 'unavailable';
+
+const readinessDefaultTimeoutMs = 2_000;
+const readinessMaximumTimeoutMs = 30_000;
+
+export class SmartBucket {
+  public config: plugins.tsclass.storage.IStorageDescriptor;
+
+  private currentStorageClient: plugins.s3.S3Client;
+  private ownedStorageClient: plugins.s3.S3Client;
+  private lifecycleState: TSmartBucketLifecycleState = 'open';
+  private lifecycleEpoch = 0;
+  private activeReadinessControllers = new Set<AbortController>();
+  private retiredStorageClients = new WeakSet<plugins.s3.S3Client>();
+  private storageClientMutationInProgress = false;
+  private closePromise: Promise<void> | undefined;
+  private operationCloseStarted = false;
+  private operationCloseSettlement: Promise<void> | undefined;
+
+  /**
+   * The current S3 client used by bucket operations.
+   */
+  public get storageClient(): plugins.s3.S3Client {
+    return this.currentStorageClient;
+  }
+
+  /**
+   * Changes the current S3 client without transferring lifecycle ownership.
+   */
+  public set storageClient(storageClientArg: plugins.s3.S3Client) {
+    if (!this.isStorageClient(storageClientArg)) {
+      throw new TypeError('storageClient must provide send() and destroy() methods.');
+    }
+    if (this.lifecycleState !== 'open') {
+      throw new Error(`Cannot assign storageClient while SmartBucket is ${this.lifecycleState}.`);
+    }
+    if (this.storageClientMutationInProgress) {
+      throw new Error('Cannot assign storageClient during another client change.');
+    }
+    if (storageClientArg === this.currentStorageClient) {
+      return;
+    }
+    if (this.retiredStorageClients.has(storageClientArg)) {
+      throw new Error('Cannot reuse a storageClient retired by this SmartBucket.');
+    }
+
+    this.storageClientMutationInProgress = true;
+    let mutationReserved = false;
+    try {
+      reserveOperationLifecycleClientMutation(this);
+      mutationReserved = true;
+      this.lifecycleEpoch++;
+      this.abortActiveReadinessProbes();
+      this.currentStorageClient = storageClientArg;
+      commitOperationLifecycleClient(this, storageClientArg);
+      mutationReserved = false;
+    } finally {
+      if (mutationReserved) {
+        rollbackOperationLifecycleClientMutation(this);
+      }
+      this.storageClientMutationInProgress = false;
+    }
+  }
+
+  /** @deprecated Use storageClient instead */
+  public get s3Client(): plugins.s3.S3Client {
+    return this.currentStorageClient;
+  }
+
+  /**
+   * the constructor of SmartBucket
+   */
+  constructor(configArg: plugins.tsclass.storage.IStorageDescriptor, clientOptions: { forcePathStyle?: boolean } = {}) {
+    this.config = configArg;
+
+    // Use the normalizer to handle various endpoint formats
+    const { normalized } = normalizeStorageDescriptor(configArg);
+
+    this.currentStorageClient = new plugins.s3.S3Client({
+      endpoint: normalized.endpointUrl,
+      region: normalized.region,
+      credentials: normalized.credentials,
+      forcePathStyle: clientOptions.forcePathStyle ?? normalized.forcePathStyle,
+    });
+    this.ownedStorageClient = this.currentStorageClient;
+    registerOperationLifecycle(this, this.currentStorageClient);
+  }
+
+  public async createBucket(bucketNameArg: string) {
+    const bucket = await Bucket.createBucketByName(this, bucketNameArg);
+    return bucket;
+  }
+
+  public async removeBucket(bucketName: string) {
+    await Bucket.removeBucketByName(this, bucketName);
+  }
+
+  public async getBucketByName(bucketNameArg: string) {
+    return Bucket.getBucketByName(this, bucketNameArg);
+  }
+
+  /**
+   * Check if a bucket exists
+   */
+  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;
+  }
+
+  /**
+   * Transfers exclusive lifecycle ownership of an S3 client to this SmartBucket.
+   */
+  public replaceStorageClient(storageClientArg: plugins.s3.S3Client): void {
+    if (!this.isStorageClient(storageClientArg)) {
+      throw new TypeError('storageClient must provide send() and destroy() methods.');
+    }
+    if (this.lifecycleState !== 'open') {
+      throw new Error(`Cannot replace storageClient while SmartBucket is ${this.lifecycleState}.`);
+    }
+    if (this.storageClientMutationInProgress) {
+      throw new Error('Cannot replace storageClient during another client change.');
+    }
+    if (this.retiredStorageClients.has(storageClientArg)) {
+      throw new Error('Cannot reuse a storageClient retired by this SmartBucket.');
+    }
+    if (
+      storageClientArg === this.currentStorageClient &&
+      storageClientArg === this.ownedStorageClient
+    ) {
+      return;
+    }
+
+    this.storageClientMutationInProgress = true;
+    let mutationReserved = false;
+    try {
+      reserveOperationLifecycleClientMutation(this);
+      mutationReserved = true;
+      if (storageClientArg !== this.ownedStorageClient) {
+        const previousOwnedStorageClient = this.ownedStorageClient;
+        try {
+          previousOwnedStorageClient.destroy();
+        } catch (error) {
+          // A throwing destroy has an unknown partial-teardown outcome. Keep
+          // the lifecycle reserved so no later operation can reuse it.
+          mutationReserved = false;
+          this.lifecycleState = 'closing';
+          this.lifecycleEpoch++;
+          this.abortActiveReadinessProbes();
+          this.operationCloseSettlement = beginOperationLifecycleClose(this);
+          this.operationCloseStarted = true;
+          throw error;
+        }
+        this.retiredStorageClients.add(previousOwnedStorageClient);
+        this.ownedStorageClient = storageClientArg;
+      }
+      this.currentStorageClient = storageClientArg;
+      commitOperationLifecycleClient(this, storageClientArg);
+      mutationReserved = false;
+      this.lifecycleEpoch++;
+      this.abortActiveReadinessProbes();
+    } finally {
+      if (mutationReserved) {
+        rollbackOperationLifecycleClientMutation(this);
+      }
+      this.storageClientMutationInProgress = false;
+    }
+  }
+
+  /**
+   * Performs a bounded, read-only round trip to verify bucket readiness.
+   */
+  public async checkReadiness(
+    bucketNameArg: string,
+    optionsArg: ISmartBucketReadinessOptions = {},
+  ): Promise<TSmartBucketReadinessResult> {
+    const startedAt = performance.now();
+    if (
+      typeof bucketNameArg !== 'string' ||
+      bucketNameArg.length === 0 ||
+      bucketNameArg.trim() !== bucketNameArg
+    ) {
+      throw new TypeError('Readiness bucketName must be a non-empty trimmed string.');
+    }
+
+    const timeoutMs = optionsArg.timeoutMs ?? readinessDefaultTimeoutMs;
+    if (
+      !Number.isSafeInteger(timeoutMs) ||
+      timeoutMs <= 0 ||
+      timeoutMs > readinessMaximumTimeoutMs
+    ) {
+      throw new TypeError(
+        `Readiness timeoutMs must be a positive safe integer no greater than ${readinessMaximumTimeoutMs}.`,
+      );
+    }
+
+    const lifecycleReason = this.getReadinessLifecycleReason();
+    if (lifecycleReason) {
+      return this.createReadinessFailure(lifecycleReason, startedAt);
+    }
+    if (this.storageClientMutationInProgress) {
+      return this.createReadinessFailure('unavailable', startedAt);
+    }
+
+    const callerSignal = optionsArg.signal;
+    if (callerSignal?.aborted) {
+      return this.createReadinessFailure('aborted', startedAt);
+    }
+
+    const lifecycleEpoch = this.lifecycleEpoch;
+    const storageClient = this.currentStorageClient;
+    const readinessController = new AbortController();
+    let abortSource: TSmartBucketReadinessAbortSource | undefined;
+
+    const abortForCaller = (): void => {
+      if (!abortSource) {
+        abortSource = 'caller';
+      }
+      readinessController.abort();
+    };
+
+    callerSignal?.addEventListener('abort', abortForCaller, { once: true });
+    const deadlineTimer = setTimeout(() => {
+      if (!abortSource) {
+        abortSource = 'deadline';
+      }
+      readinessController.abort();
+    }, timeoutMs);
+    this.activeReadinessControllers.add(readinessController);
+
+    let sendOutcome: TSmartBucketReadinessSendOutcome;
+    try {
+      sendOutcome = await this.sendReadinessProbe(
+        storageClient,
+        bucketNameArg,
+        readinessController.signal,
+      );
+    } finally {
+      clearTimeout(deadlineTimer);
+      callerSignal?.removeEventListener('abort', abortForCaller);
+      this.activeReadinessControllers.delete(readinessController);
+    }
+
+    const staleReason = this.getStaleReadinessReason(lifecycleEpoch, storageClient);
+    if (staleReason) {
+      return this.createReadinessFailure(staleReason, startedAt);
+    }
+    if (sendOutcome === 'aborted') {
+      if (abortSource === 'caller') {
+        return this.createReadinessFailure('aborted', startedAt);
+      }
+      if (abortSource === 'deadline') {
+        return this.createReadinessFailure('timeout', startedAt);
+      }
+      return this.createReadinessFailure('unavailable', startedAt);
+    }
+    if (sendOutcome === 'unavailable') {
+      return this.createReadinessFailure('unavailable', startedAt);
+    }
+
+    return {
+      ready: true,
+      status: 'ready',
+      durationMs: performance.now() - startedAt,
+    };
+  }
+
+  /**
+   * Cancels active readiness and object operations before closing the owned S3 client.
+   */
+  public close(): Promise<void> {
+    if (this.storageClientMutationInProgress) {
+      throw new Error('Cannot close SmartBucket during a storageClient change.');
+    }
+    if (this.closePromise) {
+      return this.closePromise;
+    }
+
+    let resolveClose!: () => void;
+    let rejectClose!: (errorArg: unknown) => void;
+    const closePromise = new Promise<void>((resolve, reject) => {
+      resolveClose = resolve;
+      rejectClose = reject;
+    });
+    this.closePromise = closePromise;
+
+    if (!this.operationCloseStarted) {
+      this.lifecycleState = 'closing';
+      this.lifecycleEpoch++;
+      this.abortActiveReadinessProbes();
+      this.operationCloseSettlement = beginOperationLifecycleClose(this);
+      this.operationCloseStarted = true;
+    }
+
+    const finishClose = (): void => {
+      try {
+        this.ownedStorageClient.destroy();
+        completeOperationLifecycleClose(this);
+        this.lifecycleState = 'closed';
+        resolveClose();
+      } catch (error) {
+        rejectClose(error);
+      }
+    };
+    if (this.operationCloseSettlement) {
+      void this.operationCloseSettlement.then(finishClose);
+    } else {
+      finishClose();
+    }
+    void closePromise.catch(() => {
+      if (this.closePromise === closePromise) {
+        this.closePromise = undefined;
+      }
+    });
+
+    return closePromise;
+  }
+
+  private isStorageClient(storageClientArg: unknown): storageClientArg is plugins.s3.S3Client {
+    if (typeof storageClientArg !== 'object' || storageClientArg === null) {
+      return false;
+    }
+    const storageClientCandidate = storageClientArg as {
+      send?: unknown;
+      destroy?: unknown;
+    };
+    return (
+      typeof storageClientCandidate.send === 'function' &&
+      typeof storageClientCandidate.destroy === 'function'
+    );
+  }
+
+  private abortActiveReadinessProbes(): void {
+    for (const readinessController of [...this.activeReadinessControllers]) {
+      readinessController.abort();
+    }
+  }
+
+  private sendReadinessProbe(
+    storageClientArg: plugins.s3.S3Client,
+    bucketNameArg: string,
+    signalArg: AbortSignal,
+  ): Promise<TSmartBucketReadinessSendOutcome> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const settle = (outcomeArg: TSmartBucketReadinessSendOutcome): void => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        signalArg.removeEventListener('abort', abortReadinessProbe);
+        resolve(outcomeArg);
+      };
+      const abortReadinessProbe = (): void => {
+        settle('aborted');
+      };
+
+      signalArg.addEventListener('abort', abortReadinessProbe, { once: true });
+      if (signalArg.aborted) {
+        abortReadinessProbe();
+        return;
+      }
+
+      try {
+        const providerPromise = storageClientArg.send(
+          new plugins.s3.HeadBucketCommand({
+            Bucket: bucketNameArg,
+          }),
+          {
+            abortSignal: signalArg,
+          },
+        );
+        void providerPromise.then(
+          () => settle('ready'),
+          () => settle('unavailable'),
+        );
+      } catch {
+        settle('unavailable');
+      }
+    });
+  }
+
+  private getReadinessLifecycleReason():
+    | Extract<TSmartBucketReadinessFailureReason, 'closing' | 'closed'>
+    | undefined {
+    switch (this.lifecycleState) {
+      case 'open':
+        return undefined;
+      case 'closing':
+        return 'closing';
+      case 'closed':
+        return 'closed';
+    }
+  }
+
+  private getStaleReadinessReason(
+    lifecycleEpochArg: number,
+    storageClientArg: plugins.s3.S3Client,
+  ): TSmartBucketReadinessFailureReason | undefined {
+    const lifecycleReason = this.getReadinessLifecycleReason();
+    if (lifecycleReason) {
+      return lifecycleReason;
+    }
+    if (
+      this.lifecycleEpoch !== lifecycleEpochArg ||
+      this.currentStorageClient !== storageClientArg
+    ) {
+      return 'unavailable';
+    }
+    return undefined;
+  }
+
+  private createReadinessFailure(
+    reasonArg: TSmartBucketReadinessFailureReason,
+    startedAtArg: number,
+  ): TSmartBucketReadinessResult {
+    return {
+      ready: false,
+      status: 'unavailable',
+      reason: reasonArg,
+      durationMs: performance.now() - startedAtArg,
+    };
+  }
+}

package/ts/objectstorage/classes.trash.ts

@@ -0,0 +1,30 @@
+import * as plugins from './plugins.js';
+import * as interfaces from './interfaces.js';
+import * as helpers from './helpers.js';
+import type { Bucket } from './classes.bucket.js';
+import type { Directory } from './classes.directory.js';
+import type { File } from './classes.file.js';
+
+
+export class Trash {
+  public bucketRef: Bucket;
+
+  constructor(bucketRefArg: Bucket) {
+    this.bucketRef = bucketRefArg;
+  }
+
+  public async getTrashDir() {
+    return this.bucketRef.getDirectoryFromPath({ path: '.trash' });
+  }
+
+  public async getTrashedFileByOriginalName(pathDescriptor: interfaces.IPathDecriptor): Promise<File> {
+    const trashDir = await this.getTrashDir();
+    const originalPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const trashKey = await this.getTrashKeyByOriginalBasePath(originalPath);
+    return trashDir.getFile({ path: trashKey });
+  }
+
+  public async getTrashKeyByOriginalBasePath (originalPath: string): Promise<string> {
+    return plugins.smartstring.base64.encode(originalPath);
+  }
+}