@opengeni/storage 0.2.75 → 0.2.93

package/dist/index.js

@@ -1,5 +1,7 @@
 // src/index.ts
 import { RETAINED_OUTPUT_MAX_PAGE_BYTES } from "@opengeni/contracts";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
 import {
   BlobSASPermissions,
   BlobServiceClient,
@@ -17,9 +19,576 @@ import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import {
   Storage as GcsClient
 } from "@google-cloud/storage";
+
+// src/bounded-object-read.ts
+var DEFAULT_BOUNDED_OBJECT_CHUNK_BYTES = 1024 * 1024;
+var MAX_BOUNDED_OBJECT_CHUNK_BYTES = 8 * 1024 * 1024;
+var BoundedObjectReadError = class extends Error {
+  code;
+  constructor(code) {
+    super(messageForCode(code));
+    this.name = "BoundedObjectReadError";
+    this.code = code;
+  }
+};
+function createBoundedObjectReadPort(backend) {
+  return Object.freeze({
+    async open(input) {
+      validateReference(input.opaqueReference);
+      assertPositiveSafeInteger(input.maxBytes);
+      if (input.expectedByteSize !== void 0) {
+        assertNonnegativeSafeInteger(input.expectedByteSize);
+      }
+      throwIfAborted(input.signal);
+      const description = await scrubBackendFailure(
+        async () => backend.describe({
+          opaqueReference: input.opaqueReference,
+          ...input.signal ? { signal: input.signal } : {}
+        })
+      );
+      throwIfAborted(input.signal);
+      if (!description) throw new BoundedObjectReadError("object_missing");
+      validateDescription(description);
+      if (description.byteSize > input.maxBytes) {
+        throw new BoundedObjectReadError("size_limit");
+      }
+      if (input.expectedByteSize !== void 0 && description.byteSize !== input.expectedByteSize) {
+        throw new BoundedObjectReadError("truncated");
+      }
+      return new VersionPinnedBoundedObjectRead(backend, input.opaqueReference, description);
+    }
+  });
+}
+var VersionPinnedBoundedObjectRead = class {
+  byteSize;
+  contentType;
+  #backend;
+  #opaqueReference;
+  #versionToken;
+  #claimed = false;
+  #closed = false;
+  constructor(backend, opaqueReference, description) {
+    this.#backend = backend;
+    this.#opaqueReference = opaqueReference;
+    this.#versionToken = description.versionToken;
+    this.byteSize = description.byteSize;
+    this.contentType = description.contentType;
+  }
+  chunks(input = {}) {
+    if (this.#closed || this.#claimed) {
+      throw new BoundedObjectReadError("invalid_request");
+    }
+    const chunkBytes = input.chunkBytes ?? DEFAULT_BOUNDED_OBJECT_CHUNK_BYTES;
+    assertPositiveSafeInteger(chunkBytes);
+    if (chunkBytes > MAX_BOUNDED_OBJECT_CHUNK_BYTES) {
+      throw new BoundedObjectReadError("size_limit");
+    }
+    this.#claimed = true;
+    return this.#streamChunks(chunkBytes, input.signal);
+  }
+  async *#streamChunks(chunkBytes, signal) {
+    let offset = 0;
+    let completed = false;
+    try {
+      while (offset < this.byteSize) {
+        throwIfAborted(signal);
+        if (this.#closed) {
+          throw new BoundedObjectReadError("invalid_request");
+        }
+        const endInclusive = Math.min(this.byteSize - 1, offset + chunkBytes - 1);
+        const range = await scrubBackendFailure(
+          async () => this.#backend.readRange({
+            opaqueReference: this.#opaqueReference,
+            start: offset,
+            endInclusive,
+            expectedVersionToken: this.#versionToken,
+            ...signal ? { signal } : {}
+          })
+        );
+        throwIfAborted(signal);
+        if (!range) {
+          throw new BoundedObjectReadError("object_changed");
+        }
+        if (range.versionToken !== this.#versionToken) {
+          throw new BoundedObjectReadError("object_changed");
+        }
+        const expectedLength = endInclusive - offset + 1;
+        if (range.bytes.byteLength !== expectedLength) {
+          throw new BoundedObjectReadError("truncated");
+        }
+        offset += range.bytes.byteLength;
+        yield range.bytes.slice();
+      }
+      throwIfAborted(signal);
+      completed = true;
+    } finally {
+      if (!completed) await this.close();
+    }
+  }
+  async assertUnchanged(signal) {
+    if (this.#closed) {
+      throw new BoundedObjectReadError("invalid_request");
+    }
+    throwIfAborted(signal);
+    const current = await scrubBackendFailure(
+      async () => this.#backend.describe({
+        opaqueReference: this.#opaqueReference,
+        ...signal ? { signal } : {}
+      })
+    );
+    throwIfAborted(signal);
+    if (!current || current.versionToken !== this.#versionToken || current.byteSize !== this.byteSize) {
+      throw new BoundedObjectReadError("object_changed");
+    }
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (!this.#backend.close) return;
+    try {
+      await this.#backend.close({ opaqueReference: this.#opaqueReference });
+    } catch {
+    }
+  }
+};
+async function scrubBackendFailure(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof BoundedObjectReadError) throw error;
+    throw new BoundedObjectReadError("backend_failure");
+  }
+}
+function validateReference(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 2048 || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new BoundedObjectReadError("invalid_request");
+  }
+}
+function validateDescription(value) {
+  assertNonnegativeSafeInteger(value.byteSize);
+  if (value.immutableReference !== true) {
+    throw new BoundedObjectReadError("backend_failure");
+  }
+  if (typeof value.versionToken !== "string" || value.versionToken.length < 1 || value.versionToken.length > 2048) {
+    throw new BoundedObjectReadError("backend_failure");
+  }
+  if (value.contentType !== void 0 && (value.contentType.length < 1 || value.contentType.length > 256)) {
+    throw new BoundedObjectReadError("backend_failure");
+  }
+}
+function assertPositiveSafeInteger(value) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new BoundedObjectReadError("invalid_request");
+  }
+}
+function assertNonnegativeSafeInteger(value) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new BoundedObjectReadError("invalid_request");
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw new BoundedObjectReadError("aborted");
+}
+function messageForCode(code) {
+  switch (code) {
+    case "aborted":
+      return "Bounded object read was cancelled";
+    case "backend_failure":
+      return "Bounded object read failed";
+    case "invalid_request":
+      return "Bounded object read request is invalid";
+    case "object_changed":
+      return "Bounded object changed during verification";
+    case "object_missing":
+      return "Bounded object is unavailable";
+    case "size_limit":
+      return "Bounded object exceeds the configured limit";
+    case "truncated":
+      return "Bounded object length does not match its immutable metadata";
+  }
+}
+
+// src/bounded-object-write.ts
+import { createHash } from "crypto";
+var BoundedObjectWriteError = class extends Error {
+  code;
+  constructor(code) {
+    super(writeErrorMessage(code));
+    this.name = "BoundedObjectWriteError";
+    this.code = code;
+  }
+};
+function createBoundedImmutableObjectWritePort(input) {
+  return Object.freeze({
+    async write(request) {
+      validateWriteRequest(request);
+      throwIfAborted2(request.signal);
+      let session;
+      let committed = false;
+      try {
+        session = await scrubWriteBackend(
+          async () => input.backend.begin({
+            contentType: request.contentType,
+            ...request.signal ? { signal: request.signal } : {}
+          })
+        );
+        const digest = createHash("sha256");
+        let byteSize = 0;
+        for await (const sourceChunk of request.chunks) {
+          throwIfAborted2(request.signal);
+          if (!(sourceChunk instanceof Uint8Array) || sourceChunk.byteLength === 0) {
+            throw new BoundedObjectWriteError("truncated");
+          }
+          if (sourceChunk.byteLength > MAX_BOUNDED_OBJECT_CHUNK_BYTES) {
+            throw new BoundedObjectWriteError("size_limit");
+          }
+          byteSize += sourceChunk.byteLength;
+          if (byteSize > request.maxBytes) {
+            throw new BoundedObjectWriteError("size_limit");
+          }
+          const chunk = sourceChunk.slice();
+          digest.update(chunk);
+          await scrubWriteBackend(async () => session.write(chunk, request.signal));
+        }
+        throwIfAborted2(request.signal);
+        if (request.expectedByteSize !== void 0 && byteSize !== request.expectedByteSize) {
+          throw new BoundedObjectWriteError("truncated");
+        }
+        const contentHash = `sha256:${digest.digest("hex")}`;
+        if (request.expectedContentHash !== void 0 && contentHash !== request.expectedContentHash) {
+          throw new BoundedObjectWriteError("content_hash_mismatch");
+        }
+        const promoted = await scrubWriteBackend(
+          async () => session.commit({
+            byteSize,
+            contentHash,
+            contentType: request.contentType,
+            ...request.signal ? { signal: request.signal } : {}
+          })
+        );
+        validateOpaqueReference(promoted.opaqueReference);
+        committed = true;
+        throwIfAborted2(request.signal);
+        const reader = await input.readback.open({
+          opaqueReference: promoted.opaqueReference,
+          maxBytes: request.maxBytes,
+          expectedByteSize: byteSize,
+          ...request.signal ? { signal: request.signal } : {}
+        });
+        try {
+          if (reader.contentType !== void 0 && reader.contentType !== request.contentType) {
+            throw new BoundedObjectWriteError("readback_mismatch");
+          }
+          const readbackHash = createHash("sha256");
+          let readbackBytes = 0;
+          for await (const chunk of reader.chunks({
+            ...request.signal ? { signal: request.signal } : {}
+          })) {
+            readbackBytes += chunk.byteLength;
+            if (readbackBytes > byteSize) {
+              throw new BoundedObjectWriteError("readback_mismatch");
+            }
+            readbackHash.update(chunk);
+          }
+          const readbackContentHash = `sha256:${readbackHash.digest("hex")}`;
+          if (readbackBytes !== byteSize || readbackContentHash !== contentHash) {
+            throw new BoundedObjectWriteError("readback_mismatch");
+          }
+          await reader.assertUnchanged(request.signal);
+          throwIfAborted2(request.signal);
+        } finally {
+          await reader.close();
+        }
+        return Object.freeze({
+          opaqueReference: promoted.opaqueReference,
+          byteSize,
+          contentHash,
+          contentType: request.contentType
+        });
+      } catch (error) {
+        throw mapWriteFailure(error, request.signal);
+      } finally {
+        if (session && !committed) {
+          try {
+            await session.abort();
+          } catch {
+          }
+        }
+      }
+    }
+  });
+}
+function validateWriteRequest(input) {
+  if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes <= 0) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+  if (input.expectedByteSize !== void 0 && (!Number.isSafeInteger(input.expectedByteSize) || input.expectedByteSize < 0)) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+  if (typeof input.contentType !== "string" || input.contentType.length < 1 || input.contentType.length > 256 || /[\u0000-\u001f\u007f]/.test(input.contentType)) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+  if (input.expectedContentHash !== void 0 && !/^sha256:[0-9a-f]{64}$/.test(input.expectedContentHash)) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+}
+function validateOpaqueReference(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 2048 || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new BoundedObjectWriteError("backend_failure");
+  }
+}
+async function scrubWriteBackend(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof BoundedObjectWriteError) throw error;
+    throw new BoundedObjectWriteError("backend_failure");
+  }
+}
+function mapWriteFailure(error, signal) {
+  if (error instanceof BoundedObjectWriteError) return error;
+  if (signal?.aborted) return new BoundedObjectWriteError("aborted");
+  return new BoundedObjectWriteError("backend_failure");
+}
+function throwIfAborted2(signal) {
+  if (signal?.aborted) throw new BoundedObjectWriteError("aborted");
+}
+function writeErrorMessage(code) {
+  switch (code) {
+    case "aborted":
+      return "Bounded object write was cancelled";
+    case "backend_failure":
+      return "Bounded object write failed";
+    case "content_hash_mismatch":
+      return "Bounded object digest does not match expected canonical bytes";
+    case "invalid_request":
+      return "Bounded object write request is invalid";
+    case "readback_mismatch":
+      return "Immutable object read-back verification failed";
+    case "size_limit":
+      return "Bounded object write exceeds the configured limit";
+    case "truncated":
+      return "Bounded object write length does not match expected canonical bytes";
+  }
+}
+
+// src/object-storage-bounded.ts
+import { createHash as createHash2 } from "crypto";
+import { chmod, mkdtemp, open, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+var SNAPSHOT_KEY_PREFIX = "editable-artifacts/snapshots/sha256/";
+function createObjectStorageBoundedPorts(storage, options = {}) {
+  if (!storage.headObject || !storage.getObjectRange || !storage.putObjectStreamIfAbsent) {
+    throw new Error("Object storage lacks streaming immutable create/versioned range primitives");
+  }
+  const keyPrefix = validateKeyPrefix(options.keyPrefix ?? SNAPSHOT_KEY_PREFIX);
+  const referenceHash = (reference) => hashForReference(reference, keyPrefix);
+  const read = createBoundedObjectReadPort(versionedBackend(storage, referenceHash));
+  const write = createBoundedImmutableObjectWritePort({
+    backend: immutableWriteBackend(storage, keyPrefix),
+    readback: read
+  });
+  return Object.freeze({ read, write });
+}
+function versionedBackend(storage, hashForReferenceValue) {
+  const headObject = storage.headObject;
+  const getObjectRange = storage.getObjectRange;
+  return Object.freeze({
+    async describe(input) {
+      const expectedHash = hashForReferenceValue(input.opaqueReference);
+      throwIfAborted3(input.signal);
+      const head = await headObject(input.opaqueReference);
+      throwIfAborted3(input.signal);
+      if (!head) return null;
+      if (!Number.isSafeInteger(head.ContentLength) || head.ContentLength < 0 || typeof head.VersionToken !== "string" || head.VersionToken.length < 1 || head.VersionToken.length > 2048 || head.Metadata?.sha256 !== expectedHash) {
+        throw new Error("Immutable object metadata is invalid");
+      }
+      return Object.freeze({
+        byteSize: head.ContentLength,
+        versionToken: head.VersionToken,
+        immutableReference: true,
+        ...head.ContentType ? { contentType: head.ContentType } : {}
+      });
+    },
+    async readRange(input) {
+      hashForReferenceValue(input.opaqueReference);
+      throwIfAborted3(input.signal);
+      const result = await getObjectRange({
+        key: input.opaqueReference,
+        start: input.start,
+        endInclusive: input.endInclusive,
+        expectedVersionToken: input.expectedVersionToken
+      });
+      throwIfAborted3(input.signal);
+      if (!result) return null;
+      return Object.freeze({
+        bytes: result.bytes.slice(),
+        versionToken: result.versionToken
+      });
+    }
+  });
+}
+function immutableWriteBackend(storage, keyPrefix) {
+  return Object.freeze({
+    async begin(input) {
+      validateContentType(input.contentType);
+      throwIfAborted3(input.signal);
+      const stagingDirectory = await mkdtemp(join(tmpdir(), "opengeni-artifact-write-"));
+      const stagingPath = join(stagingDirectory, "payload");
+      let handle = null;
+      try {
+        await chmod(stagingDirectory, 448);
+        throwIfAborted3(input.signal);
+        handle = await open(stagingPath, "wx", 384);
+      } catch (error) {
+        await rm(stagingDirectory, { recursive: true, force: true });
+        throw error;
+      }
+      let byteSize = 0;
+      let closed = false;
+      let cleaned = false;
+      const digest = createHash2("sha256");
+      const cleanup = async () => {
+        if (cleaned) return;
+        cleaned = true;
+        if (handle) {
+          const closing = handle;
+          handle = null;
+          await closing.close().catch(() => void 0);
+        }
+        await rm(stagingDirectory, { recursive: true, force: true });
+      };
+      return {
+        async write(chunk, signal) {
+          if (closed) throw new Error("Immutable write session is closed");
+          throwIfAborted3(signal);
+          if (!(chunk instanceof Uint8Array) || chunk.byteLength === 0) {
+            throw new Error("Immutable write chunk is invalid");
+          }
+          await writeAll(handle, chunk, byteSize);
+          digest.update(chunk);
+          byteSize += chunk.byteLength;
+        },
+        async commit(commit) {
+          if (closed) throw new Error("Immutable write session is closed");
+          closed = true;
+          try {
+            throwIfAborted3(commit.signal);
+            if (commit.contentType !== input.contentType || commit.byteSize !== byteSize) {
+              throw new Error("Immutable write commit metadata changed");
+            }
+            const contentHash = `sha256:${digest.digest("hex")}`;
+            if (contentHash !== commit.contentHash) {
+              throw new Error("Immutable write digest changed");
+            }
+            const opaqueReference = `${keyPrefix}${contentHash.slice("sha256:".length)}`;
+            const closing = handle;
+            handle = null;
+            await closing.close();
+            const existing = await storage.headObject(opaqueReference);
+            if (existing) {
+              assertStoredObject(existing, byteSize, contentHash, input.contentType);
+            } else {
+              await storage.putObjectStreamIfAbsent({
+                key: opaqueReference,
+                contentType: input.contentType,
+                chunks: fileChunks(stagingPath, byteSize, commit.signal),
+                byteSize,
+                sha256: contentHash,
+                ...commit.signal ? { signal: commit.signal } : {}
+              });
+              const stored = await storage.headObject(opaqueReference);
+              if (!stored) throw new Error("Immutable object was not visible after write");
+              assertStoredObject(stored, byteSize, contentHash, input.contentType);
+            }
+            throwIfAborted3(commit.signal);
+            return Object.freeze({ opaqueReference });
+          } finally {
+            await cleanup();
+          }
+        },
+        async abort() {
+          closed = true;
+          byteSize = 0;
+          await cleanup();
+        }
+      };
+    }
+  });
+}
+function assertStoredObject(head, byteSize, contentHash, contentType) {
+  if (!head || head.ContentLength !== byteSize || head.Metadata?.sha256 !== contentHash || head.ContentType !== contentType || typeof head.VersionToken !== "string" || head.VersionToken.length < 1) {
+    throw new Error("Immutable content-addressed object conflicts with stored metadata");
+  }
+}
+function hashForReference(reference, keyPrefix) {
+  const match = new RegExp(`^${escapeRegExp(keyPrefix)}([0-9a-f]{64})$`, "u").exec(reference);
+  if (!match) throw new Error("Immutable snapshot reference is malformed");
+  return `sha256:${match[1]}`;
+}
+function validateKeyPrefix(value) {
+  if (typeof value !== "string" || !/^editable-artifacts\/[a-z0-9/-]+\/sha256\/$/u.test(value) || value.includes("//") || value.includes("..")) {
+    throw new Error("Immutable object key prefix is invalid");
+  }
+  return value;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function validateContentType(value) {
+  if (typeof value !== "string" || value.length < 1 || value.length > 256 || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error("Immutable object content type is invalid");
+  }
+}
+async function* fileChunks(path, expectedByteSize, signal) {
+  const handle = await open(path, "r");
+  try {
+    const buffer = new Uint8Array(1024 * 1024);
+    let offset = 0;
+    while (offset < expectedByteSize) {
+      throwIfAborted3(signal);
+      const length = Math.min(buffer.byteLength, expectedByteSize - offset);
+      let filled = 0;
+      while (filled < length) {
+        const { bytesRead } = await handle.read(buffer, filled, length - filled, offset + filled);
+        if (bytesRead <= 0) throw new Error("Immutable staging file was truncated");
+        filled += bytesRead;
+      }
+      offset += filled;
+      yield buffer.slice(0, filled);
+    }
+    const extra = new Uint8Array(1);
+    if ((await handle.read(extra, 0, 1, expectedByteSize)).bytesRead !== 0) {
+      throw new Error("Immutable staging file exceeded its committed size");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+async function writeAll(handle, bytes, position) {
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    const { bytesWritten } = await handle.write(
+      bytes,
+      offset,
+      bytes.byteLength - offset,
+      position + offset
+    );
+    if (bytesWritten <= 0) throw new Error("Immutable staging write was truncated");
+    offset += bytesWritten;
+  }
+}
+function throwIfAborted3(signal) {
+  if (signal?.aborted) throw new Error("Object storage operation was cancelled");
+}
+
+// src/index.ts
 var MAX_SINGLE_PUT_SIZE_BYTES = 5e9;
 var UPLOAD_URL_TTL_SECONDS = 15 * 60;
 var DOWNLOAD_URL_TTL_SECONDS = 5 * 60;
+var INTERNAL_STREAM_BUFFER_BYTES = 1024 * 1024;
+var INTERNAL_STREAM_CONCURRENCY = 2;
 function createObjectStorage(settings) {
   if (settings.objectStorageBackend === "azure-blob") {
     return createAzureBlobObjectStorage(settings);
@@ -48,6 +617,10 @@ function createS3CompatibleObjectStorage(settings) {
     ...sharedClientConfig,
     ...settings.objectStorageEndpoint ? { endpoint: settings.objectStorageEndpoint } : {}
   });
+  const sandboxPresignClient = settings.objectStorageSandboxEndpoint ? new S3Client({
+    ...sharedClientConfig,
+    endpoint: settings.objectStorageSandboxEndpoint
+  }) : presignClient;
   const requestClient = settings.objectStorageInternalEndpoint ? new S3Client({
     ...sharedClientConfig,
     endpoint: settings.objectStorageInternalEndpoint
@@ -68,7 +641,13 @@ function createS3CompatibleObjectStorage(settings) {
         Metadata: args.sha256 ? { sha256: args.sha256 } : void 0
       });
       return {
-        url: await getSignedUrl(presignClient, command, { expiresIn }),
+        url: await getSignedUrl(
+          args.audience === "sandbox" ? sandboxPresignClient : presignClient,
+          command,
+          {
+            expiresIn
+          }
+        ),
         requiredHeaders,
         expiresAt: new Date(Date.now() + expiresIn * 1e3)
       };
@@ -77,7 +656,7 @@ function createS3CompatibleObjectStorage(settings) {
       const expiresIn = args.expiresInSeconds ?? DOWNLOAD_URL_TTL_SECONDS;
       return {
         url: await getSignedUrl(
-          presignClient,
+          args.audience === "sandbox" ? sandboxPresignClient : presignClient,
           new GetObjectCommand({
             Bucket: settings.objectStorageBucket,
             Key: args.key
@@ -98,6 +677,44 @@ function createS3CompatibleObjectStorage(settings) {
         })
       );
     },
+    async putObjectIfAbsent(args) {
+      try {
+        await requestClient.send(
+          new PutObjectCommand({
+            Bucket: settings.objectStorageBucket,
+            Key: args.key,
+            ContentType: args.contentType,
+            Body: args.body,
+            Metadata: { sha256: args.sha256 },
+            IfNoneMatch: "*"
+          })
+        );
+        return true;
+      } catch (error) {
+        if (isS3VersionMismatch(error)) return false;
+        throw error;
+      }
+    },
+    async putObjectStreamIfAbsent(args) {
+      try {
+        await requestClient.send(
+          new PutObjectCommand({
+            Bucket: settings.objectStorageBucket,
+            Key: args.key,
+            ContentType: args.contentType,
+            ContentLength: args.byteSize,
+            Body: Readable.from(args.chunks),
+            Metadata: { sha256: args.sha256 },
+            IfNoneMatch: "*"
+          }),
+          args.signal ? { abortSignal: args.signal } : void 0
+        );
+        return true;
+      } catch (error) {
+        if (isS3VersionMismatch(error)) return false;
+        throw error;
+      }
+    },
     async headFile(file) {
       const head = await requestClient.send(
         new HeadObjectCommand({
@@ -150,6 +767,43 @@ function createS3CompatibleObjectStorage(settings) {
         throw error;
       }
     },
+    async headObject(key) {
+      try {
+        const head = await requestClient.send(
+          new HeadObjectCommand({ Bucket: settings.objectStorageBucket, Key: key })
+        );
+        return objectHead({
+          contentLength: head.ContentLength,
+          contentType: head.ContentType,
+          metadata: head.Metadata,
+          versionToken: head.ETag
+        });
+      } catch (error) {
+        if (isS3NotFound(error)) return null;
+        throw error;
+      }
+    },
+    async getObjectRange(args) {
+      const length = assertRawObjectByteRange(args.key, args.start, args.endInclusive);
+      try {
+        const result = await requestClient.send(
+          new GetObjectCommand({
+            Bucket: settings.objectStorageBucket,
+            Key: args.key,
+            Range: `bytes=${args.start}-${args.endInclusive}`,
+            IfMatch: args.expectedVersionToken
+          })
+        );
+        if (!result.ETag || result.ETag !== args.expectedVersionToken) return null;
+        return {
+          bytes: await s3BodyToBoundedBytes(result.Body, args.key, length),
+          versionToken: result.ETag
+        };
+      } catch (error) {
+        if (isS3NotFound(error) || isS3VersionMismatch(error)) return null;
+        throw error;
+      }
+    },
     async getObjectBytes(key) {
       try {
         const result = await requestClient.send(
@@ -223,6 +877,11 @@ function isS3NotFound(error) {
   const metadata = "$metadata" in error ? error.$metadata : void 0;
   return metadata?.httpStatusCode === 404;
 }
+function isS3VersionMismatch(error) {
+  if (!error || typeof error !== "object") return false;
+  const metadata = "$metadata" in error ? error.$metadata : void 0;
+  return metadata?.httpStatusCode === 412;
+}
 function createGcsObjectStorage(settings) {
   const client = new GcsClient(gcsClientOptions(settings));
   const bucket = client.bucket(settings.objectStorageBucket);
@@ -268,6 +927,39 @@ function createGcsObjectStorage(settings) {
         ...args.sha256 ? { metadata: { metadata: { sha256: args.sha256 } } } : {}
       });
     },
+    async putObjectIfAbsent(args) {
+      try {
+        await bucket.file(args.key).save(Buffer.from(args.body), {
+          contentType: args.contentType,
+          metadata: { metadata: { sha256: args.sha256 } },
+          preconditionOpts: { ifGenerationMatch: 0 }
+        });
+        return true;
+      } catch (error) {
+        if (isGcsVersionMismatch(error)) return false;
+        throw error;
+      }
+    },
+    async putObjectStreamIfAbsent(args) {
+      const destination = bucket.file(args.key).createWriteStream({
+        resumable: false,
+        contentType: args.contentType,
+        highWaterMark: INTERNAL_STREAM_BUFFER_BYTES,
+        metadata: { metadata: { sha256: args.sha256 } },
+        preconditionOpts: { ifGenerationMatch: 0 }
+      });
+      try {
+        if (args.signal) {
+          await pipeline(Readable.from(args.chunks), destination, { signal: args.signal });
+        } else {
+          await pipeline(Readable.from(args.chunks), destination);
+        }
+        return true;
+      } catch (error) {
+        if (isGcsVersionMismatch(error)) return false;
+        throw error;
+      }
+    },
     async headFile(file) {
       const [metadata] = await bucket.file(file.objectKey).getMetadata();
       return objectHead({
@@ -299,6 +991,33 @@ function createGcsObjectStorage(settings) {
         throw error;
       }
     },
+    async headObject(key) {
+      try {
+        const [metadata] = await bucket.file(key).getMetadata();
+        return objectHead({
+          contentLength: parseContentLength(metadata.size),
+          contentType: metadata.contentType,
+          metadata: stringMetadata(metadata.metadata),
+          versionToken: metadata.generation === void 0 ? void 0 : String(metadata.generation)
+        });
+      } catch (error) {
+        if (isGcsNotFound(error)) return null;
+        throw error;
+      }
+    },
+    async getObjectRange(args) {
+      const length = assertRawObjectByteRange(args.key, args.start, args.endInclusive);
+      try {
+        const [bytes] = await bucket.file(args.key, { generation: args.expectedVersionToken }).download({ start: args.start, end: args.endInclusive });
+        return {
+          bytes: exactRangeBytes(bytes, args.key, length),
+          versionToken: args.expectedVersionToken
+        };
+      } catch (error) {
+        if (isGcsNotFound(error) || isGcsVersionMismatch(error)) return null;
+        throw error;
+      }
+    },
     async getObjectBytes(key) {
       try {
         const [bytes] = await bucket.file(key).download();
@@ -318,6 +1037,9 @@ function createGcsObjectStorage(settings) {
 function isGcsNotFound(error) {
   return Boolean(error) && typeof error === "object" && error.code === 404;
 }
+function isGcsVersionMismatch(error) {
+  return Boolean(error) && typeof error === "object" && error.code === 412;
+}
 function createAzureBlobObjectStorage(settings) {
   const sharedKey = azureSharedKeyCredential(settings);
   const requestServiceClient = settings.objectStorageAzureConnectionString ? BlobServiceClient.fromConnectionString(settings.objectStorageAzureConnectionString) : new BlobServiceClient(azureBlobServiceUrl(settings), sharedKey);
@@ -382,6 +1104,41 @@ function createAzureBlobObjectStorage(settings) {
         ...args.sha256 ? { metadata: { sha256: args.sha256 } } : {}
       });
     },
+    async putObjectIfAbsent(args) {
+      const blobClient = requestContainerClient.getBlockBlobClient(args.key);
+      const body = Buffer.from(args.body);
+      try {
+        await blobClient.upload(body, body.byteLength, {
+          blobHTTPHeaders: { blobContentType: args.contentType },
+          metadata: { sha256: args.sha256 },
+          conditions: { ifNoneMatch: "*" }
+        });
+        return true;
+      } catch (error) {
+        if (isAzureVersionMismatch(error)) return false;
+        throw error;
+      }
+    },
+    async putObjectStreamIfAbsent(args) {
+      const blobClient = requestContainerClient.getBlockBlobClient(args.key);
+      try {
+        await blobClient.uploadStream(
+          Readable.from(args.chunks),
+          INTERNAL_STREAM_BUFFER_BYTES,
+          INTERNAL_STREAM_CONCURRENCY,
+          {
+            blobHTTPHeaders: { blobContentType: args.contentType },
+            metadata: { sha256: args.sha256 },
+            conditions: { ifNoneMatch: "*" },
+            ...args.signal ? { abortSignal: args.signal } : {}
+          }
+        );
+        return true;
+      } catch (error) {
+        if (isAzureVersionMismatch(error)) return false;
+        throw error;
+      }
+    },
     async headFile(file) {
       return azureHeadToObjectHead(
         await requestContainerClient.getBlobClient(file.objectKey).getProperties()
@@ -414,6 +1171,34 @@ function createAzureBlobObjectStorage(settings) {
         throw error;
       }
     },
+    async headObject(key) {
+      try {
+        const properties = await requestContainerClient.getBlobClient(key).getProperties();
+        return objectHead({
+          contentLength: properties.contentLength,
+          contentType: properties.contentType,
+          metadata: properties.metadata,
+          versionToken: properties.etag
+        });
+      } catch (error) {
+        if (isAzureNotFound(error)) return null;
+        throw error;
+      }
+    },
+    async getObjectRange(args) {
+      const length = assertRawObjectByteRange(args.key, args.start, args.endInclusive);
+      try {
+        const download = await requestContainerClient.getBlobClient(args.key).download(args.start, length, { conditions: { ifMatch: args.expectedVersionToken } });
+        if (!download.etag || download.etag !== args.expectedVersionToken) return null;
+        return {
+          bytes: await azureDownloadToBoundedBytes(download, args.key, length),
+          versionToken: download.etag
+        };
+      } catch (error) {
+        if (isAzureNotFound(error) || isAzureVersionMismatch(error)) return null;
+        throw error;
+      }
+    },
     async getObjectBytes(key) {
       try {
         const download = await requestContainerClient.getBlobClient(key).download();
@@ -434,6 +1219,9 @@ function createAzureBlobObjectStorage(settings) {
 function isAzureNotFound(error) {
   return Boolean(error) && typeof error === "object" && error.statusCode === 404;
 }
+function isAzureVersionMismatch(error) {
+  return Boolean(error) && typeof error === "object" && error.statusCode === 412;
+}
 function azureSharedKeyCredential(settings) {
   if (settings.objectStorageAzureConnectionString) {
     const parsed = parseConnectionString(settings.objectStorageAzureConnectionString);
@@ -557,6 +1345,16 @@ function assertFileByteRange(file, range) {
   }
   return length;
 }
+function assertRawObjectByteRange(key, start, endInclusive) {
+  if (typeof key !== "string" || key.length < 1 || key.length > 2048 || !Number.isSafeInteger(start) || !Number.isSafeInteger(endInclusive) || start < 0 || endInclusive < start) {
+    throw new RangeError("Invalid raw object byte range");
+  }
+  const length = endInclusive - start + 1;
+  if (length > RETAINED_OUTPUT_MAX_PAGE_BYTES) {
+    throw new RangeError("Raw object byte range exceeds the bounded page limit");
+  }
+  return length;
+}
 function exactRangeBytes(bytes, objectKey, expectedBytes) {
   if (bytes.byteLength !== expectedBytes) {
     throw new Error(
@@ -569,17 +1367,25 @@ function objectHead(input) {
   return {
     ...input.contentLength !== void 0 ? { ContentLength: input.contentLength } : {},
     ...input.contentType !== void 0 ? { ContentType: input.contentType } : {},
-    ...input.metadata !== void 0 ? { Metadata: input.metadata } : {}
+    ...input.metadata !== void 0 ? { Metadata: input.metadata } : {},
+    ...input.versionToken !== void 0 ? { VersionToken: input.versionToken } : {}
   };
 }
 function bytesToDataUrl(bytes, contentType) {
   return `data:${contentType};base64,${Buffer.from(bytes).toString("base64")}`;
 }
 export {
+  BoundedObjectReadError,
+  BoundedObjectWriteError,
+  DEFAULT_BOUNDED_OBJECT_CHUNK_BYTES,
   DOWNLOAD_URL_TTL_SECONDS,
+  MAX_BOUNDED_OBJECT_CHUNK_BYTES,
   MAX_SINGLE_PUT_SIZE_BYTES,
   UPLOAD_URL_TTL_SECONDS,
   bytesToDataUrl,
-  createObjectStorage
+  createBoundedImmutableObjectWritePort,
+  createBoundedObjectReadPort,
+  createObjectStorage,
+  createObjectStorageBoundedPorts
 };
 //# sourceMappingURL=index.js.map