@lossless.org/client 0.1.0

package/ts/objectstorage/interfaces.ts

@@ -0,0 +1,389 @@
+import type { Readable } from 'node:stream';
+
+import type { Bucket } from './classes.bucket.js';
+import type { Directory } from './classes.directory.js';
+
+export interface IPathDecriptor {
+  path?: string;
+  directory?: Directory;
+}
+
+export interface IFastGetStreamOptions {
+  path: string;
+  signal?: AbortSignal;
+}
+
+export interface IFastPutStreamOptions {
+  path: string;
+  readableStream: Readable | ReadableStream;
+  contentLength?: number;
+  nativeMetadata?: Record<string, string>;
+  overwrite?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface IFastCopyOptions {
+  sourcePath: string;
+  destinationPath?: string;
+  targetBucket?: Bucket;
+  nativeMetadata?: Record<string, string>;
+  deleteExistingNativeMetadata?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface IFastRemoveOptions {
+  path: string;
+  signal?: AbortSignal;
+}
+
+export interface IFastExistsOptions {
+  path: string;
+  signal?: AbortSignal;
+}
+
+export interface IFastStatOptions extends IPathDecriptor {
+  signal?: AbortSignal;
+}
+
+export interface IDirectoryFastPutStreamOptions {
+  path: string;
+  stream: Readable;
+  contentLength?: number;
+  signal?: AbortSignal;
+}
+
+// ================================
+// SmartBucket Readiness Interfaces
+// ================================
+
+/**
+ * Options for a bounded, read-only bucket readiness check.
+ */
+export interface ISmartBucketReadinessOptions {
+  /** Probe deadline in milliseconds (default: 2000, maximum: 30000) */
+  timeoutMs?: number;
+  /** Optional caller-owned cancellation signal */
+  signal?: AbortSignal;
+}
+
+/**
+ * Sanitized reasons why a SmartBucket readiness probe is unavailable.
+ */
+export type TSmartBucketReadinessFailureReason =
+  | 'closing'
+  | 'closed'
+  | 'aborted'
+  | 'timeout'
+  | 'unavailable';
+
+/**
+ * Discriminated result returned by SmartBucket.checkReadiness().
+ */
+export type TSmartBucketReadinessResult =
+  | {
+      ready: true;
+      status: 'ready';
+      durationMs: number;
+    }
+  | {
+      ready: false;
+      status: 'unavailable';
+      reason: TSmartBucketReadinessFailureReason;
+      durationMs: number;
+    };
+
+// =====================================
+// Exact Streaming Upload Interfaces
+// =====================================
+
+declare const exactUploadCapabilityBrand: unique symbol;
+
+/**
+ * Opaque proof that the current bucket provider enforces the conditional
+ * operations required by Bucket.fastPutStreamExact().
+ *
+ * Capabilities can only be minted by Bucket.probeExactUploadCapability().
+ * They are bound to one exact Bucket object and its current SmartBucket,
+ * bucket name, S3 client, and lifecycle generation.
+ */
+export interface IExactUploadCapability {
+  readonly [exactUploadCapabilityBrand]: 'smartbucket-exact-upload-v1';
+}
+
+export interface IExactUploadCapabilityProbeOptions {
+  /** Optional caller-owned cancellation signal */
+  signal?: AbortSignal;
+}
+
+export type TExactUploadCapabilityProbeFailureReason =
+  | 'aborted'
+  | 'conditional-put-not-enforced'
+  | 'conditional-complete-not-enforced'
+  | 'cleanup-failed'
+  | 'unavailable';
+
+export type TExactUploadCapabilityProbeResult =
+  | {
+      supported: true;
+      capability: IExactUploadCapability;
+    }
+  | {
+      supported: false;
+      reason: TExactUploadCapabilityProbeFailureReason;
+      cause?: unknown;
+    };
+
+export interface IExactUploadResult {
+  destinationPath: string;
+  contentLength: number;
+  etag: string;
+  versionId?: string;
+  partCount: number;
+  peakBufferedBytes: number;
+  maximumBufferedBytes: number;
+}
+
+export interface IExactUploadNativeObjectProperties {
+  contentType?: string;
+}
+
+export interface IFastPutStreamExactOptions {
+  capability: IExactUploadCapability;
+  path: string;
+  /**
+   * Every emitted chunk must be no larger than the effective multipart part
+   * size (5 MiB by default).
+   */
+  readableStream: Readable | ReadableStream<Uint8Array>;
+  contentLength: number;
+  nativeMetadata?: Record<string, string>;
+  /**
+   * Native S3 object properties that must retain their semantic header
+   * identity instead of being encoded as x-amz-meta-* user metadata.
+   */
+  nativeObjectProperties?: IExactUploadNativeObjectProperties;
+  requestedPartSize?: number;
+  requestedConcurrency?: number;
+  /** Failure teardown wait before non-cooperative callbacks detach (max 30000). */
+  failureSettlementTimeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export type TExactUploadFailurePhase =
+  | 'capability'
+  | 'source'
+  | 'put-zero'
+  | 'create-multipart'
+  | 'upload-part'
+  | 'complete-multipart';
+
+export type TExactUploadMultipartCleanup =
+  | {
+      status: 'not-required';
+    }
+  | {
+      status: 'aborted';
+    }
+  | {
+      /**
+       * The provider reports that the multipart upload no longer exists. This
+       * does not prove whether an ambiguous completion published the object.
+       */
+      status: 'absent';
+    }
+  | {
+      status: 'abort-failed';
+      cause: unknown;
+    }
+  | {
+      /**
+       * One or more provider requests ignored cancellation. Multipart cleanup
+       * is deferred until those requests settle and remains unverified in this
+       * caller-visible result.
+       */
+      status: 'deferred';
+    };
+
+export interface IExactUploadFailureState {
+  phase: TExactUploadFailurePhase;
+  destinationPath: string;
+  expectedContentLength: number;
+  /**
+   * Whether this operation can prove that it did not publish the destination.
+   * A conditional PutObject or CompleteMultipartUpload response can be lost
+   * after the provider has committed the object, so those failures are
+   * intentionally reported as ambiguous.
+   */
+  destinationPublication: 'not-published' | 'ambiguous';
+  multipartUploadId?: string;
+  multipartCleanup: TExactUploadMultipartCleanup;
+}
+
+// =================================
+// Exact Path Purge Interfaces
+// =================================
+
+declare const exactPathPurgeCapabilityBrand: unique symbol;
+
+export type TExactPathPurgeVersioningMode =
+  | 'unversioned'
+  | 'enabled'
+  | 'suspended';
+
+/**
+ * Opaque proof that the current provider supports the exact conditional-delete
+ * and version-aware cleanup semantics required by Bucket.purgeExactPath().
+ */
+export interface IExactPathPurgeCapability {
+  readonly [exactPathPurgeCapabilityBrand]: 'smartbucket-exact-path-purge-v1';
+}
+
+export interface IExactPathPurgeCapabilityProbeOptions {
+  /** Probe deadline in milliseconds (default: 30000, maximum: 30000) */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export type TExactPathPurgeCapabilityProbeFailureReason =
+  | 'aborted'
+  | 'timeout'
+  | 'conditional-delete-not-enforced'
+  | 'cleanup-failed'
+  | 'versioning-mode-changed'
+  | 'unavailable';
+
+export type TExactPathPurgeCapabilityProbeResult =
+  | {
+      supported: true;
+      capability: IExactPathPurgeCapability;
+      versioningMode: TExactPathPurgeVersioningMode;
+    }
+  | {
+      supported: false;
+      reason: TExactPathPurgeCapabilityProbeFailureReason;
+      cause?: unknown;
+    };
+
+export interface IExactPathPurgeCounts {
+  unversionedObjects: number;
+  versions: number;
+  nullVersions: number;
+  deleteMarkers: number;
+}
+
+export interface IExactPathPurgeEvidence {
+  initialCounts: IExactPathPurgeCounts;
+  remainingCounts: IExactPathPurgeCounts;
+  initialFingerprint?: string;
+  remainingFingerprint?: string;
+  inventoryScansCompleted: number;
+  verificationScansCompleted: number;
+  pagesScanned: number;
+  neighborEntriesObserved: number;
+  deleteRequestsAttempted: number;
+  deleteRequestsAcknowledged: number;
+  verifiedAt?: string;
+}
+
+export interface IExactPathPurgeOptions {
+  capability: IExactPathPurgeCapability;
+  path: string;
+  /** Primary operation deadline (default: 30000, maximum: 300000) */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export interface IExactPathPurgeResult {
+  destinationPath: string;
+  status: 'purged' | 'already-absent';
+  versioningMode: TExactPathPurgeVersioningMode;
+  purgedCounts: IExactPathPurgeCounts;
+  evidence: IExactPathPurgeEvidence;
+}
+
+export type TExactPathPurgeFailurePhase =
+  | 'capability'
+  | 'inventory'
+  | 'consistency'
+  | 'delete'
+  | 'verification';
+
+export type TExactPathPurgeFailureReason =
+  | 'aborted'
+  | 'timeout'
+  | 'malformed-provider-response'
+  | 'inventory-limit-exceeded'
+  | 'concurrent-recreation'
+  | 'delete-unverified'
+  | 'verification-ambiguous'
+  | 'versioning-mode-changed'
+  | 'unavailable';
+
+export interface IExactPathPurgeFailureState {
+  phase: TExactPathPurgeFailurePhase;
+  reason: TExactPathPurgeFailureReason;
+  destinationPath: string;
+  versioningMode?: TExactPathPurgeVersioningMode;
+  evidence: IExactPathPurgeEvidence;
+}
+
+// ================================
+// Bucket Watcher Interfaces
+// ================================
+
+/**
+ * Internal state tracking for a storage object
+ */
+export interface IStorageObjectState {
+  key: string;
+  etag: string;
+  size: number;
+  lastModified: Date;
+}
+
+/**
+ * Change event emitted by BucketWatcher
+ */
+export interface IStorageChangeEvent {
+  type: 'add' | 'modify' | 'delete';
+  key: string;
+  size?: number;
+  etag?: string;
+  lastModified?: Date;
+  bucket: string;
+}
+
+/**
+ * Watcher mode - 'poll' is the default, 'websocket' reserved for future implementation
+ */
+export type TBucketWatcherMode = 'poll' | 'websocket';
+
+/**
+ * Options for creating a BucketWatcher
+ */
+export interface IBucketWatcherOptions {
+  /** Watcher mode: 'poll' (default) or 'websocket' (future) */
+  mode?: TBucketWatcherMode;
+  /** Prefix to filter objects (default: '' for all objects) */
+  prefix?: string;
+  /** Polling interval in milliseconds (default: 5000, poll mode only) */
+  pollIntervalMs?: number;
+  /** Optional RxJS buffering time in milliseconds */
+  bufferTimeMs?: number;
+  /** Emit initial state as 'add' events (default: false) */
+  includeInitial?: boolean;
+  /** Page size for listing operations (default: 1000) */
+  pageSize?: number;
+  // Future websocket options will be added here
+  // websocketUrl?: string;
+}
+
+// ================================
+// Deprecated aliases
+// ================================
+
+/** @deprecated Use IStorageObjectState instead */
+export type IS3ObjectState = IStorageObjectState;
+
+/** @deprecated Use IStorageChangeEvent instead */
+export type IS3ChangeEvent = IStorageChangeEvent;