@opengeni/storage 0.2.75 → 0.2.87

package/src/bounded-object-read.ts

@@ -0,0 +1,323 @@
+/**
+ * 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 const DEFAULT_BOUNDED_OBJECT_CHUNK_BYTES = 1024 * 1024;
+export const MAX_BOUNDED_OBJECT_CHUNK_BYTES = 8 * 1024 * 1024;
+
+export type BoundedObjectReadErrorCode =
+  | "aborted"
+  | "backend_failure"
+  | "invalid_request"
+  | "object_changed"
+  | "object_missing"
+  | "size_limit"
+  | "truncated";
+
+export class BoundedObjectReadError extends Error {
+  readonly code: BoundedObjectReadErrorCode;
+
+  constructor(code: BoundedObjectReadErrorCode) {
+    super(messageForCode(code));
+    this.name = "BoundedObjectReadError";
+    this.code = code;
+  }
+}
+
+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 function createBoundedObjectReadPort(
+  backend: VersionedRangeObjectBackend,
+): BoundedObjectReadPort {
+  return Object.freeze({
+    async open(input: {
+      opaqueReference: string;
+      maxBytes: number;
+      expectedByteSize?: number;
+      signal?: AbortSignal;
+    }): Promise<BoundedObjectRead> {
+      validateReference(input.opaqueReference);
+      assertPositiveSafeInteger(input.maxBytes);
+      if (input.expectedByteSize !== undefined) {
+        assertNonnegativeSafeInteger(input.expectedByteSize);
+      }
+      throwIfAborted(input.signal);
+      const description = await scrubBackendFailure(async () =>
+        backend.describe({
+          opaqueReference: input.opaqueReference,
+          ...(input.signal ? { signal: input.signal } : {}),
+        }),
+      );
+      // Provider adapters are allowed to receive AbortSignal, but correctness
+      // cannot depend on every SDK honouring it while an I/O promise is active.
+      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 !== undefined && description.byteSize !== input.expectedByteSize) {
+        throw new BoundedObjectReadError("truncated");
+      }
+      return new VersionPinnedBoundedObjectRead(backend, input.opaqueReference, description);
+    },
+  });
+}
+
+class VersionPinnedBoundedObjectRead implements BoundedObjectRead {
+  readonly byteSize: number;
+  readonly contentType: string | undefined;
+  readonly #backend: VersionedRangeObjectBackend;
+  readonly #opaqueReference: string;
+  readonly #versionToken: string;
+  #claimed = false;
+  #closed = false;
+
+  constructor(
+    backend: VersionedRangeObjectBackend,
+    opaqueReference: string,
+    description: VersionedObjectDescription,
+  ) {
+    this.#backend = backend;
+    this.#opaqueReference = opaqueReference;
+    this.#versionToken = description.versionToken;
+    this.byteSize = description.byteSize;
+    this.contentType = description.contentType;
+  }
+
+  chunks(
+    input: {
+      chunkBytes?: number;
+      signal?: AbortSignal;
+    } = {},
+  ): AsyncIterable<Uint8Array> {
+    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: number,
+    signal: AbortSignal | undefined,
+  ): AsyncIterableIterator<Uint8Array> {
+    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;
+        // Detach consumers from mutable provider buffers.
+        yield range.bytes.slice();
+      }
+      throwIfAborted(signal);
+      completed = true;
+    } finally {
+      // Keep a successfully consumed handle live for the mandatory final
+      // generation check. Early return, failure, and cancellation clean up
+      // immediately; normal callers close after assertUnchanged().
+      if (!completed) await this.close();
+    }
+  }
+
+  async assertUnchanged(signal?: AbortSignal): Promise<void> {
+    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(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (!this.#backend.close) return;
+    try {
+      await this.#backend.close({ opaqueReference: this.#opaqueReference });
+    } catch {
+      // Cleanup is best-effort and must not replace the verification result.
+    }
+  }
+}
+
+async function scrubBackendFailure<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof BoundedObjectReadError) throw error;
+    throw new BoundedObjectReadError("backend_failure");
+  }
+}
+
+function validateReference(value: string): void {
+  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: VersionedObjectDescription): void {
+  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 !== undefined &&
+    (value.contentType.length < 1 || value.contentType.length > 256)
+  ) {
+    throw new BoundedObjectReadError("backend_failure");
+  }
+}
+
+function assertPositiveSafeInteger(value: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new BoundedObjectReadError("invalid_request");
+  }
+}
+
+function assertNonnegativeSafeInteger(value: number): void {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new BoundedObjectReadError("invalid_request");
+  }
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new BoundedObjectReadError("aborted");
+}
+
+function messageForCode(code: BoundedObjectReadErrorCode): string {
+  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";
+  }
+}

package/src/bounded-object-write.ts

@@ -0,0 +1,269 @@
+import { createHash } from "node:crypto";
+import { MAX_BOUNDED_OBJECT_CHUNK_BYTES, type BoundedObjectReadPort } from "./bounded-object-read";
+
+export type BoundedObjectWriteErrorCode =
+  | "aborted"
+  | "backend_failure"
+  | "content_hash_mismatch"
+  | "invalid_request"
+  | "readback_mismatch"
+  | "size_limit"
+  | "truncated";
+
+export class BoundedObjectWriteError extends Error {
+  readonly code: BoundedObjectWriteErrorCode;
+
+  constructor(code: BoundedObjectWriteErrorCode) {
+    super(writeErrorMessage(code));
+    this.name = "BoundedObjectWriteError";
+    this.code = code;
+  }
+}
+
+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 function createBoundedImmutableObjectWritePort(input: {
+  backend: ImmutableContentAddressedWriteBackend;
+  readback: BoundedObjectReadPort;
+}): BoundedImmutableObjectWritePort {
+  return Object.freeze({
+    async write(request: {
+      chunks: AsyncIterable<Uint8Array>;
+      contentType: string;
+      maxBytes: number;
+      expectedByteSize?: number;
+      expectedContentHash?: string;
+      signal?: AbortSignal;
+    }): Promise<BoundedImmutableObjectWriteResult> {
+      validateWriteRequest(request);
+      throwIfAborted(request.signal);
+      let session: ImmutableContentAddressedWriteSession | undefined;
+      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) {
+          throwIfAborted(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));
+        }
+        // A backend may ignore AbortSignal and resolve the final write after the
+        // caller has cancelled. Recheck before publishing staged bytes; without
+        // this fence a one-chunk upload could still be committed after abort.
+        throwIfAborted(request.signal);
+        if (request.expectedByteSize !== undefined && byteSize !== request.expectedByteSize) {
+          throw new BoundedObjectWriteError("truncated");
+        }
+        const contentHash = `sha256:${digest.digest("hex")}`;
+        if (
+          request.expectedContentHash !== undefined &&
+          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;
+        // A provider may finish promotion after cancellation despite receiving
+        // the signal. The immutable object can be swept, but it must never be
+        // returned to a caller as a successful publication candidate.
+        throwIfAborted(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 !== undefined && 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);
+          throwIfAborted(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 {
+            // Best-effort staging cleanup; a sweeper remains the final guard.
+          }
+        }
+      }
+    },
+  });
+}
+
+function validateWriteRequest(input: {
+  contentType: string;
+  maxBytes: number;
+  expectedByteSize?: number;
+  expectedContentHash?: string;
+}): void {
+  if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes <= 0) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+  if (
+    input.expectedByteSize !== undefined &&
+    (!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 !== undefined &&
+    !/^sha256:[0-9a-f]{64}$/.test(input.expectedContentHash)
+  ) {
+    throw new BoundedObjectWriteError("invalid_request");
+  }
+}
+
+function validateOpaqueReference(value: string): void {
+  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<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof BoundedObjectWriteError) throw error;
+    throw new BoundedObjectWriteError("backend_failure");
+  }
+}
+
+function mapWriteFailure(error: unknown, signal: AbortSignal | undefined): BoundedObjectWriteError {
+  if (error instanceof BoundedObjectWriteError) return error;
+  if (signal?.aborted) return new BoundedObjectWriteError("aborted");
+  return new BoundedObjectWriteError("backend_failure");
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new BoundedObjectWriteError("aborted");
+}
+
+function writeErrorMessage(code: BoundedObjectWriteErrorCode): string {
+  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";
+  }
+}