@lossless.org/client 0.1.0

package/dist_ts/objectstorage/interfaces.d.ts

@@ -0,0 +1,276 @@
+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;
+}
+/**
+ * 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;
+};
+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;
+}
+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;
+}
+/**
+ * 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;
+}
+/** @deprecated Use IStorageObjectState instead */
+export type IS3ObjectState = IStorageObjectState;
+/** @deprecated Use IStorageChangeEvent instead */
+export type IS3ChangeEvent = IStorageChangeEvent;
+export {};

package/dist_ts/objectstorage/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL29iamVjdHN0b3JhZ2UvaW50ZXJmYWNlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/objectstorage/internal.exactpathpurge.operations.d.ts

@@ -0,0 +1,11 @@
+import * as plugins from './plugins.js';
+import type { IExactPathPurgeCapabilityProbeOptions, IExactPathPurgeOptions, IExactPathPurgeResult, TExactPathPurgeCapabilityProbeResult } from './interfaces.js';
+interface IExactPathPurgeBucketRef {
+    name: string;
+    smartbucketRef: {
+        readonly storageClient: plugins.s3.S3Client;
+    };
+}
+export declare const probeExactPathPurgeCapability: (bucketRefArg: IExactPathPurgeBucketRef, optionsArg: IExactPathPurgeCapabilityProbeOptions) => Promise<TExactPathPurgeCapabilityProbeResult>;
+export declare const purgeExactPath: (bucketRefArg: IExactPathPurgeBucketRef, optionsArg: IExactPathPurgeOptions) => Promise<IExactPathPurgeResult>;
+export {};