@opengeni/storage 0.2.75 → 0.2.87

package/src/index.ts

@@ -1,5 +1,7 @@
 import type { Settings } from "@opengeni/config";
 import { RETAINED_OUTPUT_MAX_PAGE_BYTES, type FileAsset } from "@opengeni/contracts";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import {
   BlobSASPermissions,
   BlobServiceClient,
@@ -23,14 +25,22 @@ import {
   type StorageOptions,
 } from "@google-cloud/storage";
 
+export * from "./bounded-object-read";
+export * from "./bounded-object-write";
+export * from "./object-storage-bounded";
+
 export const MAX_SINGLE_PUT_SIZE_BYTES = 5_000_000_000;
 export const UPLOAD_URL_TTL_SECONDS = 15 * 60;
 export const DOWNLOAD_URL_TTL_SECONDS = 5 * 60;
+const INTERNAL_STREAM_BUFFER_BYTES = 1024 * 1024;
+const INTERNAL_STREAM_CONCURRENCY = 2;
 
 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 = {
@@ -61,6 +71,14 @@ export type ObjectStorage = {
   ) => Promise<Uint8Array | null>;
   /** Fetch an object by raw storage key (not a tracked FileAsset). Returns null on 404/missing. */
   getObjectBytes: (key: string) => Promise<{ 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
@@ -79,6 +97,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
@@ -182,6 +219,44 @@ function createS3CompatibleObjectStorage(settings: Settings): ObjectStorage | nu
         }),
       );
     },
+    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 } : undefined,
+        );
+        return true;
+      } catch (error) {
+        if (isS3VersionMismatch(error)) return false;
+        throw error;
+      }
+    },
     async headFile(file) {
       const head = await requestClient.send(
         new HeadObjectCommand({
@@ -234,6 +309,43 @@ function createS3CompatibleObjectStorage(settings: Settings): ObjectStorage | nu
         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(
@@ -319,6 +431,15 @@ function isS3NotFound(error: unknown): boolean {
   return metadata?.httpStatusCode === 404;
 }
 
+function isS3VersionMismatch(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const metadata =
+    "$metadata" in error
+      ? (error as { $metadata?: { httpStatusCode?: number } }).$metadata
+      : undefined;
+  return metadata?.httpStatusCode === 412;
+}
+
 function createGcsObjectStorage(settings: Settings): ObjectStorage {
   const client = new GcsClient(gcsClientOptions(settings));
   const bucket = client.bucket(settings.objectStorageBucket);
@@ -365,6 +486,39 @@ function createGcsObjectStorage(settings: Settings): ObjectStorage {
         ...(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({
@@ -398,6 +552,35 @@ function createGcsObjectStorage(settings: Settings): ObjectStorage {
         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 === undefined ? undefined : 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();
@@ -420,6 +603,10 @@ function isGcsNotFound(error: unknown): boolean {
   return Boolean(error) && typeof error === "object" && (error as { code?: unknown }).code === 404;
 }
 
+function isGcsVersionMismatch(error: unknown): boolean {
+  return Boolean(error) && typeof error === "object" && (error as { code?: unknown }).code === 412;
+}
+
 function createAzureBlobObjectStorage(settings: Settings): ObjectStorage | null {
   const sharedKey = azureSharedKeyCredential(settings);
   const requestServiceClient = settings.objectStorageAzureConnectionString
@@ -490,6 +677,41 @@ function createAzureBlobObjectStorage(settings: Settings): ObjectStorage | null
         ...(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(),
@@ -522,6 +744,36 @@ function createAzureBlobObjectStorage(settings: Settings): ObjectStorage | null
         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();
@@ -549,6 +801,14 @@ function isAzureNotFound(error: unknown): boolean {
   );
 }
 
+function isAzureVersionMismatch(error: unknown): boolean {
+  return (
+    Boolean(error) &&
+    typeof error === "object" &&
+    (error as { statusCode?: unknown }).statusCode === 412
+  );
+}
+
 function azureSharedKeyCredential(settings: Settings): StorageSharedKeyCredential {
   if (settings.objectStorageAzureConnectionString) {
     const parsed = parseConnectionString(settings.objectStorageAzureConnectionString);
@@ -712,6 +972,25 @@ function assertFileByteRange(
   return length;
 }
 
+function assertRawObjectByteRange(key: string, start: number, endInclusive: number): number {
+  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: Uint8Array, objectKey: string, expectedBytes: number): Uint8Array {
   if (bytes.byteLength !== expectedBytes) {
     throw new Error(
@@ -725,11 +1004,13 @@ function objectHead(input: {
   contentLength?: number | undefined;
   contentType?: string | undefined;
   metadata?: Record<string, string> | undefined;
+  versionToken?: string | undefined;
 }): ObjectHead {
   return {
     ...(input.contentLength !== undefined ? { ContentLength: input.contentLength } : {}),
     ...(input.contentType !== undefined ? { ContentType: input.contentType } : {}),
     ...(input.metadata !== undefined ? { Metadata: input.metadata } : {}),
+    ...(input.versionToken !== undefined ? { VersionToken: input.versionToken } : {}),
   };
 }
 

package/src/object-storage-bounded.ts

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdtemp, open, rm, type FileHandle } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  createBoundedObjectReadPort,
+  type BoundedObjectReadPort,
+  type VersionedRangeObjectBackend,
+} from "./bounded-object-read";
+import {
+  createBoundedImmutableObjectWritePort,
+  type BoundedImmutableObjectWritePort,
+  type ImmutableContentAddressedWriteBackend,
+  type ImmutableContentAddressedWriteSession,
+} from "./bounded-object-write";
+import type { ObjectStorage } from "./index";
+
+const SNAPSHOT_KEY_PREFIX = "editable-artifacts/snapshots/sha256/";
+
+export type ObjectStorageBoundedPorts = Readonly<{
+  read: BoundedObjectReadPort;
+  write: BoundedImmutableObjectWritePort;
+}>;
+
+export type ObjectStorageBoundedPortsOptions = Readonly<{
+  /** Static trusted namespace ending in `/sha256/`. */
+  keyPrefix?: string;
+}>;
+
+/**
+ * Bounded immutable snapshot ports over the standalone object-storage driver.
+ * Reads are provider-version pinned. Writes use a canonical digest key and are
+ * independently range-read and hashed by the shared verification layer.
+ *
+ * Provider uploads and readback are streaming. Staging uses one private local
+ * file so content-addressed naming never requires retaining the object in RAM.
+ * There is no whole-object fallback when a provider lacks these primitives.
+ */
+export function createObjectStorageBoundedPorts(
+  storage: ObjectStorage,
+  options: ObjectStorageBoundedPortsOptions = {},
+): ObjectStorageBoundedPorts {
+  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: string) => 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: ObjectStorage,
+  hashForReferenceValue: (reference: string) => string,
+): VersionedRangeObjectBackend {
+  const headObject = storage.headObject!;
+  const getObjectRange = storage.getObjectRange!;
+  return Object.freeze({
+    async describe(input: Parameters<VersionedRangeObjectBackend["describe"]>[0]) {
+      const expectedHash = hashForReferenceValue(input.opaqueReference);
+      throwIfAborted(input.signal);
+      const head = await headObject(input.opaqueReference);
+      throwIfAborted(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 as const,
+        ...(head.ContentType ? { contentType: head.ContentType } : {}),
+      });
+    },
+    async readRange(input: Parameters<VersionedRangeObjectBackend["readRange"]>[0]) {
+      hashForReferenceValue(input.opaqueReference);
+      throwIfAborted(input.signal);
+      const result = await getObjectRange({
+        key: input.opaqueReference,
+        start: input.start,
+        endInclusive: input.endInclusive,
+        expectedVersionToken: input.expectedVersionToken,
+      });
+      throwIfAborted(input.signal);
+      if (!result) return null;
+      return Object.freeze({
+        bytes: result.bytes.slice(),
+        versionToken: result.versionToken,
+      });
+    },
+  });
+}
+
+function immutableWriteBackend(
+  storage: ObjectStorage,
+  keyPrefix: string,
+): ImmutableContentAddressedWriteBackend {
+  return Object.freeze({
+    async begin(
+      input: Parameters<ImmutableContentAddressedWriteBackend["begin"]>[0],
+    ): Promise<ImmutableContentAddressedWriteSession> {
+      validateContentType(input.contentType);
+      throwIfAborted(input.signal);
+      const stagingDirectory = await mkdtemp(join(tmpdir(), "opengeni-artifact-write-"));
+      const stagingPath = join(stagingDirectory, "payload");
+      let handle: FileHandle | null = null;
+      try {
+        await chmod(stagingDirectory, 0o700);
+        throwIfAborted(input.signal);
+        handle = await open(stagingPath, "wx", 0o600);
+      } catch (error) {
+        await rm(stagingDirectory, { recursive: true, force: true });
+        throw error;
+      }
+      let byteSize = 0;
+      let closed = false;
+      let cleaned = false;
+      const digest = createHash("sha256");
+      const cleanup = async () => {
+        if (cleaned) return;
+        cleaned = true;
+        if (handle) {
+          const closing = handle;
+          handle = null;
+          await closing.close().catch(() => undefined);
+        }
+        await rm(stagingDirectory, { recursive: true, force: true });
+      };
+      return {
+        async write(chunk: Uint8Array, signal?: AbortSignal) {
+          if (closed) throw new Error("Immutable write session is closed");
+          throwIfAborted(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: Parameters<ImmutableContentAddressedWriteSession["commit"]>[0]) {
+          if (closed) throw new Error("Immutable write session is closed");
+          closed = true;
+          try {
+            throwIfAborted(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);
+            }
+            throwIfAborted(commit.signal);
+            return Object.freeze({ opaqueReference });
+          } finally {
+            await cleanup();
+          }
+        },
+        async abort() {
+          closed = true;
+          byteSize = 0;
+          await cleanup();
+        },
+      };
+    },
+  });
+}
+
+function assertStoredObject(
+  head: Awaited<ReturnType<NonNullable<ObjectStorage["headObject"]>>>,
+  byteSize: number,
+  contentHash: string,
+  contentType: string,
+): void {
+  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: string, keyPrefix: string): string {
+  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: string): string {
+  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: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function validateContentType(value: string): void {
+  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: string,
+  expectedByteSize: number,
+  signal: AbortSignal | undefined,
+): AsyncIterableIterator<Uint8Array> {
+  const handle = await open(path, "r");
+  try {
+    const buffer = new Uint8Array(1024 * 1024);
+    let offset = 0;
+    while (offset < expectedByteSize) {
+      throwIfAborted(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: FileHandle, bytes: Uint8Array, position: number): Promise<void> {
+  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 throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new Error("Object storage operation was cancelled");
+}