@opengeni/storage 0.2.75 → 0.2.87

package/dist/bounded-object-read.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Version-pinned, bounded object reads for large trusted-server workloads.
+ *
+ * This surface deliberately deals in opaque references. Provider keys, bucket
+ * names, signed URLs, and provider diagnostics stay behind the backend
+ * callback and are never included in returned values or public errors.
+ */
+export declare const DEFAULT_BOUNDED_OBJECT_CHUNK_BYTES: number;
+export declare const MAX_BOUNDED_OBJECT_CHUNK_BYTES: number;
+export type BoundedObjectReadErrorCode = "aborted" | "backend_failure" | "invalid_request" | "object_changed" | "object_missing" | "size_limit" | "truncated";
+export declare class BoundedObjectReadError extends Error {
+    readonly code: BoundedObjectReadErrorCode;
+    constructor(code: BoundedObjectReadErrorCode);
+}
+export type VersionedObjectDescription = Readonly<{
+    byteSize: number;
+    /** Opaque provider generation/etag token. It never crosses this package. */
+    versionToken: string;
+    /**
+     * Explicit adapter assertion that the opaque reference resolves forever to
+     * this provider generation (for example a version id or immutable
+     * content-addressed object). Mutable raw keys must never set this flag.
+     */
+    immutableReference: true;
+    contentType?: string;
+}>;
+export type VersionedObjectRange = Readonly<{
+    bytes: Uint8Array;
+    versionToken: string;
+}>;
+/**
+ * Provider adapter used by the range reader. Implementations should use a
+ * provider-native generation/version/If-Match condition whenever available.
+ * Returning a different version is treated as replacement, never as data.
+ */
+export interface VersionedRangeObjectBackend {
+    describe(input: {
+        opaqueReference: string;
+        signal?: AbortSignal;
+    }): Promise<VersionedObjectDescription | null>;
+    readRange(input: {
+        opaqueReference: string;
+        start: number;
+        endInclusive: number;
+        expectedVersionToken: string;
+        signal?: AbortSignal;
+    }): Promise<VersionedObjectRange | null>;
+    close?(input: {
+        opaqueReference: string;
+    }): void | Promise<void>;
+}
+export interface BoundedObjectRead {
+    readonly byteSize: number;
+    readonly contentType: string | undefined;
+    /** A read handle is intentionally single-use. */
+    chunks(input?: {
+        chunkBytes?: number;
+        signal?: AbortSignal;
+    }): AsyncIterable<Uint8Array>;
+    /** Revalidate the immutable provider generation after all consumers finish. */
+    assertUnchanged(signal?: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}
+export interface BoundedObjectReadPort {
+    open(input: {
+        opaqueReference: string;
+        maxBytes: number;
+        expectedByteSize?: number;
+        signal?: AbortSignal;
+    }): Promise<BoundedObjectRead>;
+}
+/**
+ * Adds uniform limits, exact-range checks, replacement fencing, cancellation,
+ * and diagnostic scrubbing around a provider-specific range backend.
+ */
+export declare function createBoundedObjectReadPort(backend: VersionedRangeObjectBackend): BoundedObjectReadPort;

package/dist/bounded-object-write.d.ts

@@ -0,0 +1,53 @@
+import { type BoundedObjectReadPort } from "./bounded-object-read.js";
+export type BoundedObjectWriteErrorCode = "aborted" | "backend_failure" | "content_hash_mismatch" | "invalid_request" | "readback_mismatch" | "size_limit" | "truncated";
+export declare class BoundedObjectWriteError extends Error {
+    readonly code: BoundedObjectWriteErrorCode;
+    constructor(code: BoundedObjectWriteErrorCode);
+}
+export interface ImmutableContentAddressedWriteSession {
+    write(chunk: Uint8Array, signal?: AbortSignal): Promise<void>;
+    /**
+     * Atomically promotes staged bytes to an immutable content-addressed object.
+     * The returned reference must resolve forever to this exact generation.
+     */
+    commit(input: {
+        byteSize: number;
+        contentHash: string;
+        contentType: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        opaqueReference: string;
+    }>;
+    abort(): void | Promise<void>;
+}
+export interface ImmutableContentAddressedWriteBackend {
+    begin(input: {
+        contentType: string;
+        signal?: AbortSignal;
+    }): Promise<ImmutableContentAddressedWriteSession>;
+}
+export type BoundedImmutableObjectWriteResult = Readonly<{
+    opaqueReference: string;
+    byteSize: number;
+    contentHash: string;
+    contentType: string;
+}>;
+export interface BoundedImmutableObjectWritePort {
+    write(input: {
+        chunks: AsyncIterable<Uint8Array>;
+        contentType: string;
+        maxBytes: number;
+        expectedByteSize?: number;
+        expectedContentHash?: string;
+        signal?: AbortSignal;
+    }): Promise<BoundedImmutableObjectWriteResult>;
+}
+/**
+ * Streams to provider staging, atomically promotes by digest, then streams the
+ * immutable object back and hashes it independently before returning its
+ * opaque reference. Neither direction accumulates the complete object.
+ */
+export declare function createBoundedImmutableObjectWritePort(input: {
+    backend: ImmutableContentAddressedWriteBackend;
+    readback: BoundedObjectReadPort;
+}): BoundedImmutableObjectWritePort;

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type { Settings } from "@opengeni/config";
 import { type FileAsset } from "@opengeni/contracts";
+export * from "./bounded-object-read.js";
+export * from "./bounded-object-write.js";
+export * from "./object-storage-bounded.js";
 export declare const MAX_SINGLE_PUT_SIZE_BYTES = 5000000000;
 export declare const UPLOAD_URL_TTL_SECONDS: number;
 export declare const DOWNLOAD_URL_TTL_SECONDS: number;
@@ -7,6 +10,8 @@ export type ObjectHead = {
     ContentLength?: number;
     ContentType?: string;
     Metadata?: Record<string, string>;
+    /** Opaque provider generation/etag used only for conditional internal reads. */
+    VersionToken?: string;
 };
 export type ObjectStorage = {
     bucket: string;
@@ -46,6 +51,17 @@ export type ObjectStorage = {
         bytes: Uint8Array;
         contentType?: string;
     } | null>;
+    /** Provider-versioned raw-key primitives used by bounded immutable adapters. */
+    headObject?: (key: string) => Promise<ObjectHead | null>;
+    getObjectRange?: (args: {
+        key: string;
+        start: number;
+        endInclusive: number;
+        expectedVersionToken: string;
+    }) => Promise<{
+        bytes: Uint8Array;
+        versionToken: string;
+    } | null>;
     /**
      * SERVER-SIDE authenticated direct PUT (no presign + browser fetch). For an
      * in-process upload from a trusted holder of the storage credentials (e.g. the
@@ -64,6 +80,25 @@ export type ObjectStorage = {
         body: Uint8Array;
         sha256?: string | null;
     }) => Promise<void>;
+    /** Atomic create-only raw PUT. Returns false when the key already exists. */
+    putObjectIfAbsent?: (args: {
+        key: string;
+        contentType: string;
+        body: Uint8Array;
+        sha256: string;
+    }) => Promise<boolean>;
+    /**
+     * Atomic create-only raw upload from a bounded asynchronous byte stream.
+     * Providers may buffer a small fixed number of chunks, never the whole body.
+     */
+    putObjectStreamIfAbsent?: (args: {
+        key: string;
+        contentType: string;
+        chunks: AsyncIterable<Uint8Array>;
+        byteSize: number;
+        sha256: string;
+        signal?: AbortSignal;
+    }) => Promise<boolean>;
     /**
      * SERVER-SIDE authenticated delete of a single object by raw storage key.
      * Idempotent: a missing key is a no-op (S3/GCS/Azure delete-by-key does not