@foss.global/codefeed 4.1.0 → 4.2.0

package/ts/classes.giteasourcetransfer.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
+import { createTransferBounds, createTransferStream, discardBody, heldBackChunks } from './forgeinventory.transfer.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import { LfsBatchClient } from './classes.lfsbatchclient.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
@@ -27,6 +28,8 @@ export interface IGiteaSourceTransferOptions {
   maxResponseBytes?: number;
   /** Wall-clock limit of one LFS object download; defaults to 30 minutes, at most six hours. */
   lfsTransferTimeoutMs?: number;
+  /** Wall-clock limit of one release asset download, its closing identity reads included; defaults to 30 minutes, at most six hours. */
+  releaseAssetTimeoutMs?: number;
 }
 
 /**
@@ -52,6 +55,31 @@ export interface IGiteaMirrorImportOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * A release asset as the source inventory recorded it: what a download asks
+ * for and checks Gitea still holds. The download count is not part of it.
+ */
+export type TGiteaReleaseAssetSelector = Pick<plugins.fossInterfaces.data.IForgeSourceReleaseAsset, 'id' | 'uuid' | 'name' | 'size'>;
+
+export interface IGiteaReleaseAssetDownloadOptions {
+  /** Aborts the download with `request-aborted`, also while the stream is read. */
+  signal?: AbortSignal;
+}
+
+export interface IGiteaReleaseAssetDownload {
+  releaseId: string;
+  asset: TGiteaReleaseAssetSelector;
+  /**
+   * The asset's bytes, never held whole. The last chunk is held back until
+   * exactly `asset.size` bytes have arrived and both identity reads have
+   * passed again. Destroying the stream ends the download.
+   */
+  stream: InstanceType<typeof plugins.stream.Readable>;
+}
+
+/** Gitea names attachment content by a random UUID in canonical lowercase form. */
+const attachmentUuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 export interface IGiteaMirrorImport {
   repository: plugins.TGitManagerRepositoryInfo;
   /** The repository size Gitea reported, in KiB, which sized the scratch reservation. */
@@ -61,14 +89,15 @@ export interface IGiteaMirrorImport {
 /**
  * Reads a Gitea repository's Git data and LFS objects for its one-time
  * migration, with the reader's login and token: a mirror clone into a
- * GitManager the caller supplies, and verified LFS object downloads. It never
- * writes to Gitea: Git is read only through `git-upload-pack`, LFS only
- * through batch `download` requests and their download actions.
+ * GitManager the caller supplies, verified LFS object downloads and release
+ * asset downloads. It never writes to Gitea: Git is read only through
+ * `git-upload-pack`, LFS only through batch `download` requests and their
+ * download actions, release assets only through GETs of their attachment.
  */
 export class GiteaSourceTransfer {
   readonly #options: {
     baseUrl: string; login: string; token: string; caCertificates?: string[];
-    gitTimeoutMs: number; requestTimeoutMs: number; maxResponseBytes: number; lfsTransferTimeoutMs: number;
+    gitTimeoutMs: number; requestTimeoutMs: number; maxResponseBytes: number; lfsTransferTimeoutMs: number; releaseAssetTimeoutMs: number;
   };
   readonly #client: ForgeRequestClient;
 
@@ -83,9 +112,11 @@ export class GiteaSourceTransfer {
       requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
       maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
       lfsTransferTimeoutMs: optionsArg.lfsTransferTimeoutMs ?? 30 * 60 * 1000,
+      releaseAssetTimeoutMs: optionsArg.releaseAssetTimeoutMs ?? 30 * 60 * 1000,
     };
     for (const [name, maximum] of [
       ['gitTimeoutMs', 6 * 60 * 60 * 1000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024], ['lfsTransferTimeoutMs', 6 * 60 * 60 * 1000],
+      ['releaseAssetTimeoutMs', 6 * 60 * 60 * 1000],
     ] as const) {
       const value = limits[name];
       if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
@@ -223,6 +254,94 @@ export class GiteaSourceTransfer {
     return download;
   }
 
+  /**
+   * Downloads one release asset by GET of `/attachments/{uuid}` with the
+   * reader's `token` authorization: no redirect is followed and no range is
+   * asked for, so only a 200 answer of the whole content is accepted, and a
+   * `content-length`, when sent, must equal `asset.size`. Before the request
+   * the repository is read by its id as for `importMirror`, then the release
+   * by its id: it must still carry an asset with the same `id`, `uuid`,
+   * `name` and `size`, otherwise the download rejects with
+   * `release-asset-identity-changed` (a replaced file carries another id and
+   * uuid). The bytes stream without a digest; the last chunk is held back
+   * until exactly `size` bytes have arrived and both identity reads have
+   * passed once more, so a consumer never receives a complete asset that is
+   * short, long or no longer the recorded one. Gitea exposes no content
+   * digest; a digest the caller needs comes from the content itself.
+   *
+   * Rejects, or errors the stream, with a fixed `ForgeInventoryError` code:
+   * `invalid-repository`, `release-asset-invalid`, `request-aborted`, a REST
+   * code such as `http-404` (also for a deleted release),
+   * `repository-identity-changed`, `release-asset-identity-changed`,
+   * `http-<status>` for any answer but 200, `release-asset-size-mismatch`,
+   * `release-asset-size-overrun`, `release-asset-short-body`,
+   * `release-asset-transfer-timed-out` (after `releaseAssetTimeoutMs`, or a
+   * stall of `requestTimeoutMs`), `release-asset-download-failed`, such as
+   * for a refused redirect, or `release-asset-transfer-failed` when body bytes
+   * still arrive after the download has ended; the download ends only once
+   * the stream is destroyed or finished, and a destroyed stream reports no
+   * error, so a reader does not see this code. A failed request is explained
+   * by the identity reads as for `downloadLfsObject`.
+   */
+  public async downloadReleaseAsset(
+    repositoryArg: IGiteaSourceRepository,
+    releaseIdArg: string,
+    assetArg: TGiteaReleaseAssetSelector,
+    optionsArg: IGiteaReleaseAssetDownloadOptions = {},
+  ): Promise<IGiteaReleaseAssetDownload> {
+    const repository = this.#repository(repositoryArg);
+    const { releaseId, asset, size } = this.#releaseAssetSelector(releaseIdArg, assetArg);
+    const { signal } = optionsArg;
+    if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+    await this.#releaseAssetIdentified(repository, releaseId, asset, signal);
+    const agents = transport.createNodeAgents(this.#options.caCertificates);
+    const close = () => agents.https?.destroy();
+    const transfer = createTransferBounds(signal, {
+      limitMs: this.#options.releaseAssetTimeoutMs, idleMs: this.#options.requestTimeoutMs,
+      timedOutCode: 'release-asset-transfer-timed-out', failedCode: 'release-asset-transfer-failed',
+    });
+    let body: AsyncIterable<Uint8Array>;
+    try {
+      const response = await transfer.run(() => transport.sendNodeRequest(new URL(`${this.#options.baseUrl}/attachments/${asset.uuid}`), {
+        method: 'GET', headers: { authorization: `token ${this.#options.token}` }, signal: transfer.signal, agents,
+      }));
+      if (response.status !== 200 || !response.body) {
+        await transfer.run(() => discardBody(response.body));
+        throw new validation.ForgeInventoryError(`http-${response.status}`);
+      }
+      const length = response.headers.get('content-length');
+      if (length !== null && length.trim() !== asset.size) {
+        await transfer.run(() => discardBody(response.body));
+        throw new validation.ForgeInventoryError('release-asset-size-mismatch');
+      }
+      body = response.body;
+    } catch (error) {
+      const failure = transfer.failure(error, 'release-asset-download-failed');
+      transfer.end();
+      close();
+      if (signal?.aborted) throw failure;
+      return this.#releaseAssetExplained(repository, releaseId, asset, failure, signal);
+    }
+    // After the last byte, before the held chunk: the repository and the asset are still the ones asked for.
+    const identified = async () => {
+      transfer.touch();
+      await transfer.run(() => this.#releaseAssetIdentified(repository, releaseId, asset, transfer.signal));
+    };
+    const chunks = async function* (): AsyncGenerator<Uint8Array, void, undefined> {
+      try {
+        yield* heldBackChunks(transfer.watch(body), size, {
+          invalidChunk: 'release-asset-invalid-chunk', overrun: 'release-asset-size-overrun', short: 'release-asset-short-body',
+        }, { complete: identified });
+      } catch (error) {
+        throw transfer.failure(error, 'release-asset-download-failed');
+      } finally {
+        transfer.end();
+      }
+    };
+    // Destroying the stream ends the download and closes its connections at once, also while a read is pending.
+    return { releaseId, asset, stream: createTransferStream(transfer, chunks(), close) };
+  }
+
   /**
    * Reads the repository by its id and checks that Gitea still names it
    * `owner/name`, without case as Gitea looks names up: other names reject
@@ -259,6 +378,65 @@ export class GiteaSourceTransfer {
     throw errorArg;
   }
 
+  /**
+   * Reads the repository by its id, then the release by its id under the
+   * repository's name: the release must still carry the asset with its id,
+   * uuid, name and size, else `release-asset-identity-changed`. A release
+   * read that fails is explained by the repository read as for `#explained`.
+   */
+  async #releaseAssetIdentified(
+    repositoryArg: IGiteaSourceRepository, releaseIdArg: string, assetArg: TGiteaReleaseAssetSelector, signalArg: AbortSignal | undefined,
+  ): Promise<void> {
+    await this.#identified(repositoryArg, signalArg);
+    let release: Record<string, unknown>;
+    try {
+      release = validation.record((await this.#client.request(new URL(
+        `${this.#options.baseUrl}/api/v1/repos/${encodeURIComponent(repositoryArg.owner)}/${encodeURIComponent(repositoryArg.name)}/releases/${releaseIdArg}`,
+      ), { signal: signalArg })).body);
+    } catch (error) {
+      if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
+      return this.#explained(repositoryArg, error, signalArg);
+    }
+    const assets = release.assets ?? [];
+    if (validation.decimal(release.id) !== releaseIdArg || !Array.isArray(assets)) throw new validation.ForgeInventoryError('release-asset-identity-changed');
+    const found = assets.map((itemArg: unknown) => validation.record(itemArg)).find((itemArg) => validation.decimal(itemArg.id) === assetArg.id);
+    if (!found || found.uuid !== assetArg.uuid || found.name !== assetArg.name || validation.decimal(found.size) !== assetArg.size) {
+      throw new validation.ForgeInventoryError('release-asset-identity-changed');
+    }
+  }
+
+  /**
+   * Rejects with `errorArg`, a failed asset download, unless the identity
+   * reads explain it: then with `repository-identity-changed`,
+   * `release-asset-identity-changed` or `http-404`.
+   */
+  async #releaseAssetExplained(
+    repositoryArg: IGiteaSourceRepository, releaseIdArg: string, assetArg: TGiteaReleaseAssetSelector, errorArg: unknown, signalArg: AbortSignal | undefined,
+  ): Promise<never> {
+    try {
+      await this.#releaseAssetIdentified(repositoryArg, releaseIdArg, assetArg, signalArg);
+    } catch (error) {
+      if (error instanceof validation.ForgeInventoryError
+        && ['repository-identity-changed', 'release-asset-identity-changed', 'http-404'].includes(error.code)) throw error;
+    }
+    throw errorArg;
+  }
+
+  /** The release id and asset of a download request, validated; sizes beyond `Number.MAX_SAFE_INTEGER` are refused. */
+  #releaseAssetSelector(releaseIdArg: unknown, assetArg: TGiteaReleaseAssetSelector): { releaseId: string; asset: TGiteaReleaseAssetSelector; size: number } {
+    try {
+      if (typeof releaseIdArg !== 'string' || typeof assetArg?.id !== 'string' || typeof assetArg.size !== 'string') throw new Error();
+      const releaseId = validation.decimal(releaseIdArg);
+      const asset = { id: validation.decimal(assetArg.id), uuid: assetArg.uuid, name: assetArg.name, size: validation.decimal(assetArg.size) };
+      const size = Number(asset.size);
+      if (typeof asset.uuid !== 'string' || !attachmentUuidPattern.test(asset.uuid) || typeof asset.name !== 'string' || !asset.name
+        || !Number.isSafeInteger(size)) throw new Error();
+      return { releaseId, asset, size };
+    } catch {
+      throw new validation.ForgeInventoryError('release-asset-invalid');
+    }
+  }
+
   #repository(repositoryArg: IGiteaSourceRepository): IGiteaSourceRepository {
     const single = (valueArg: unknown): string => {
       const segments = validation.segments(valueArg);

package/ts/classes.lfsbatchclient.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
+import { createTransferBounds, createTransferStream, discardBody, heldBackChunks } from './forgeinventory.transfer.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import type { IForgeRequestMetrics } from './forgeinventory.client.js';
 
@@ -82,8 +83,6 @@ type TBatchEntry = ILfsObjectId & { actions: Record<string, ILfsAction>; errorCo
 const lfsMediaType = 'application/vnd.git-lfs+json';
 /** Objects per batch request; the Git LFS reference server and Gitea accept 100. */
 const maxBatchSize = 100;
-/** Response bytes read from a PUT or verify answer before the rest is discarded. */
-const maxDiscardedResponseBytes = 64 * 1024;
 const maxActionHeaders = 32;
 const maxHeaderValueLength = 8 * 1024;
 const maxHrefLength = 8 * 1024;
@@ -179,44 +178,14 @@ const actionExpiry = (actionArg: Record<string, unknown>, receivedAtArg: number)
  * wrong; otherwise it throws `lfs-size-overrun`, `lfs-short-body` or
  * `lfs-digest-mismatch`.
  */
-async function* verifiedChunks(sourceArg: AsyncIterable<Uint8Array>, oidArg: string, sizeArg: number): AsyncGenerator<Uint8Array, void, undefined> {
+const verifiedChunks = (sourceArg: AsyncIterable<Uint8Array>, oidArg: string, sizeArg: number): AsyncGenerator<Uint8Array, void, undefined> => {
   const hash = plugins.crypto.createHash('sha256');
-  let bytes = 0;
-  let held: Uint8Array | null = null;
-  for await (const chunk of sourceArg) {
-    if (!(chunk instanceof Uint8Array)) throw new validation.ForgeInventoryError('invalid-lfs-chunk');
-    if (chunk.byteLength === 0) continue;
-    bytes += chunk.byteLength;
-    if (bytes > sizeArg) throw new validation.ForgeInventoryError('lfs-size-overrun');
-    hash.update(chunk);
-    if (held) yield held;
-    held = chunk;
-  }
-  if (bytes !== sizeArg) throw new validation.ForgeInventoryError('lfs-short-body');
-  if (hash.digest('hex') !== oidArg) throw new validation.ForgeInventoryError('lfs-digest-mismatch');
-  if (held) yield held;
-}
-
-/**
- * Reads and drops at most `maxDiscardedResponseBytes` of a response body that
- * carries nothing the client uses, so its connection can be reused; a longer
- * or failing body is discarded with its connection.
- */
-const discardBody = async (bodyArg: AsyncIterable<Uint8Array> | null): Promise<void> => {
-  if (!bodyArg) return;
-  const chunks = bodyArg[Symbol.asyncIterator]();
-  let bytes = 0;
-  try {
-    while (bytes <= maxDiscardedResponseBytes) {
-      const result = await chunks.next();
-      if (result.done) return;
-      bytes += result.value.byteLength;
-    }
-  } catch {
-    // The status already decided the outcome.
-  } finally {
-    try { await chunks.return?.(); } catch { /* The connection is discarded. */ }
-  }
+  return heldBackChunks(sourceArg, sizeArg, { invalidChunk: 'invalid-lfs-chunk', overrun: 'lfs-size-overrun', short: 'lfs-short-body' }, {
+    inspect: (chunkArg) => hash.update(chunkArg),
+    complete: () => {
+      if (hash.digest('hex') !== oidArg) throw new validation.ForgeInventoryError('lfs-digest-mismatch');
+    },
+  });
 };
 
 /**
@@ -390,10 +359,8 @@ export class LfsBatchClient {
           transfer.end();
         }
       };
-      const stream = plugins.stream.Readable.from(chunks(), { objectMode: false });
-      // A consumer that destroys the stream ends the download, also while a read is pending.
-      stream.once('close', () => transfer.end());
-      return { oid, size, status: 'available', stream };
+      // Destroying the stream ends the download and closes its connection at once, also while a read is pending.
+      return { oid, size, status: 'available', stream: createTransferStream(transfer, chunks()) };
     } catch (error) {
       transfer.end();
       throw transfer.failure(error, 'lfs-download-failed');
@@ -553,62 +520,12 @@ export class LfsBatchClient {
 
   /**
    * The bounds of one transfer: the caller's signal, a wall-clock limit and an
-   * idle limit that `watch` re-arms on every chunk. Whichever ends it first
-   * decides the failure code.
+   * idle limit of `requestTimeoutMs`; a passed limit fails with
+   * `lfs-transfer-timed-out`.
    */
   #transfer(signalArg: AbortSignal | undefined, limitMsArg = this.#limits.transferTimeoutMs) {
-    const controller = new AbortController();
-    let reason: string | null = null;
-    const stop = (reasonArg: string) => {
-      reason ??= reasonArg;
-      controller.abort();
-    };
-    const abort = () => stop('request-aborted');
-    if (signalArg?.aborted) abort();
-    signalArg?.addEventListener('abort', abort, { once: true });
-    const deadline = setTimeout(() => stop('lfs-transfer-timed-out'), limitMsArg);
-    let idle: ReturnType<typeof setTimeout> | undefined;
-    const rearm = () => {
-      clearTimeout(idle);
-      if (!controller.signal.aborted) idle = setTimeout(() => stop('lfs-transfer-timed-out'), this.#limits.requestTimeoutMs);
-    };
-    rearm();
-    const end = () => {
-      clearTimeout(deadline);
-      clearTimeout(idle);
-      signalArg?.removeEventListener('abort', abort);
-      stop('transfer-ended');
-    };
-    const failure = (errorArg: unknown, fallbackArg: string): validation.ForgeInventoryError => {
-      if (reason !== null && reason !== 'transfer-ended') return new validation.ForgeInventoryError(reason);
-      return errorArg instanceof validation.ForgeInventoryError ? errorArg : new validation.ForgeInventoryError(fallbackArg);
-    };
-    return {
-      signal: controller.signal,
-      end,
-      failure,
-      /** Runs one step of the transfer; it rejects as soon as the transfer ends, even if the step does not. */
-      run: async <T>(stepArg: () => Promise<T>): Promise<T> => {
-        if (controller.signal.aborted) throw failure(undefined, 'request-aborted');
-        let onAbort!: () => void;
-        const aborted = new Promise<never>((_resolve, reject) => {
-          onAbort = () => reject(failure(undefined, 'request-aborted'));
-          controller.signal.addEventListener('abort', onAbort, { once: true });
-        });
-        try {
-          return await Promise.race([stepArg(), aborted]);
-        } finally {
-          controller.signal.removeEventListener('abort', onAbort);
-        }
-      },
-      /** Passes chunks on and re-arms the idle limit on each one. */
-      watch: async function* (sourceArg: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined> {
-        for await (const chunk of sourceArg) {
-          if (controller.signal.aborted) throw failure(undefined, 'lfs-transfer-failed');
-          rearm();
-          yield chunk;
-        }
-      },
-    };
+    return createTransferBounds(signalArg, {
+      limitMs: limitMsArg, idleMs: this.#limits.requestTimeoutMs, timedOutCode: 'lfs-transfer-timed-out', failedCode: 'lfs-transfer-failed',
+    });
   }
 }

package/ts/forgeinventory.transfer.ts

@@ -0,0 +1,203 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+/** Response bytes read from an unused answer before the rest is discarded. */
+const maxDiscardedResponseBytes = 64 * 1024;
+
+/**
+ * Reads and drops at most 64 KiB of a response body that carries nothing the
+ * caller uses, so its connection can be reused; a longer or failing body is
+ * discarded with its connection.
+ */
+export const discardBody = async (bodyArg: AsyncIterable<Uint8Array> | null): Promise<void> => {
+  if (!bodyArg) return;
+  const chunks = bodyArg[Symbol.asyncIterator]();
+  let bytes = 0;
+  try {
+    while (bytes <= maxDiscardedResponseBytes) {
+      const result = await chunks.next();
+      if (result.done) return;
+      bytes += result.value.byteLength;
+    }
+  } catch {
+    // The status already decided the outcome.
+  } finally {
+    try { await chunks.return?.(); } catch { /* The connection is discarded. */ }
+  }
+};
+
+export interface ITransferBoundsOptions {
+  /** Wall-clock limit of the whole transfer. */
+  limitMs: number;
+  /** Longest gap between two chunks of a watched source. */
+  idleMs: number;
+  /** The code a passed wall-clock or idle limit fails with. */
+  timedOutCode: string;
+  /** The code a watched source that goes on after the transfer ended fails with. */
+  failedCode: string;
+}
+
+export interface ITransferBounds {
+  /** Aborts once the caller aborts, a limit passes or the transfer ends. */
+  signal: AbortSignal;
+  /** Ends the transfer: clears its timers and aborts `signal`. Idempotent. */
+  end: () => void;
+  /**
+   * The error the transfer fails with: the reason that ended it (`request-aborted`
+   * or the timeout code), else `errorArg` when it is a `ForgeInventoryError`,
+   * else `fallbackArg`.
+   */
+  failure: (errorArg: unknown, fallbackArg: string) => validation.ForgeInventoryError;
+  /** Runs one step of the transfer; it rejects as soon as the transfer ends, even if the step does not. */
+  run: <T>(stepArg: () => Promise<T>) => Promise<T>;
+  /** Re-arms the idle limit, before a step that waits on the network without a watched source. */
+  touch: () => void;
+  /** Passes chunks on and re-arms the idle limit on each one. */
+  watch: (sourceArg: AsyncIterable<Uint8Array>) => AsyncGenerator<Uint8Array, void, undefined>;
+}
+
+/**
+ * The bounds of one streamed transfer: the caller's signal, a wall-clock limit
+ * and an idle limit that `watch` re-arms on every chunk. Whichever ends it
+ * first decides the failure code. Every transfer must be ended with `end`.
+ */
+export const createTransferBounds = (signalArg: AbortSignal | undefined, optionsArg: ITransferBoundsOptions): ITransferBounds => {
+  const controller = new AbortController();
+  let reason: string | null = null;
+  const stop = (reasonArg: string) => {
+    reason ??= reasonArg;
+    controller.abort();
+  };
+  const abort = () => stop('request-aborted');
+  if (signalArg?.aborted) abort();
+  signalArg?.addEventListener('abort', abort, { once: true });
+  const deadline = setTimeout(() => stop(optionsArg.timedOutCode), optionsArg.limitMs);
+  let idle: ReturnType<typeof setTimeout> | undefined;
+  const rearm = () => {
+    clearTimeout(idle);
+    if (!controller.signal.aborted) idle = setTimeout(() => stop(optionsArg.timedOutCode), optionsArg.idleMs);
+  };
+  rearm();
+  const end = () => {
+    clearTimeout(deadline);
+    clearTimeout(idle);
+    signalArg?.removeEventListener('abort', abort);
+    stop('transfer-ended');
+  };
+  const failure = (errorArg: unknown, fallbackArg: string): validation.ForgeInventoryError => {
+    if (reason !== null && reason !== 'transfer-ended') return new validation.ForgeInventoryError(reason);
+    return errorArg instanceof validation.ForgeInventoryError ? errorArg : new validation.ForgeInventoryError(fallbackArg);
+  };
+  return {
+    signal: controller.signal,
+    end,
+    failure,
+    touch: rearm,
+    run: async <T>(stepArg: () => Promise<T>): Promise<T> => {
+      if (controller.signal.aborted) throw failure(undefined, 'request-aborted');
+      let onAbort!: () => void;
+      const aborted = new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(failure(undefined, 'request-aborted'));
+        controller.signal.addEventListener('abort', onAbort, { once: true });
+      });
+      try {
+        return await Promise.race([stepArg(), aborted]);
+      } finally {
+        controller.signal.removeEventListener('abort', onAbort);
+      }
+    },
+    watch: async function* (sourceArg: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined> {
+      for await (const chunk of sourceArg) {
+        if (controller.signal.aborted) throw failure(undefined, optionsArg.failedCode);
+        rearm();
+        yield chunk;
+      }
+    },
+  };
+};
+
+export interface IHeldBackCodes {
+  /** A chunk that is not a `Uint8Array`. */
+  invalidChunk: string;
+  /** More bytes than the declared size. */
+  overrun: string;
+  /** Fewer bytes than the declared size. */
+  short: string;
+}
+
+export interface IHeldBackChecks {
+  /** Sees every non-empty chunk in order, before it is passed on. */
+  inspect?: (chunkArg: Uint8Array) => void;
+  /** Runs once exactly `size` bytes have arrived, before the last chunk is passed on; a rejection keeps it back. */
+  complete?: () => void | Promise<void>;
+}
+
+/**
+ * Passes the bytes of `sourceArg` on while it counts them. The last chunk is
+ * held back until the source has ended with exactly `sizeArg` bytes and
+ * `checksArg.complete` has passed, so a consumer never receives a complete
+ * body that is wrong; otherwise it throws `codesArg.overrun` as soon as the
+ * size is exceeded, `codesArg.short` when the source ends early, or what
+ * `complete` threw.
+ */
+export async function* heldBackChunks(
+  sourceArg: AsyncIterable<Uint8Array>, sizeArg: number, codesArg: IHeldBackCodes, checksArg: IHeldBackChecks = {},
+): AsyncGenerator<Uint8Array, void, undefined> {
+  let bytes = 0;
+  let held: Uint8Array | null = null;
+  for await (const chunk of sourceArg) {
+    if (!(chunk instanceof Uint8Array)) throw new validation.ForgeInventoryError(codesArg.invalidChunk);
+    if (chunk.byteLength === 0) continue;
+    bytes += chunk.byteLength;
+    if (bytes > sizeArg) throw new validation.ForgeInventoryError(codesArg.overrun);
+    checksArg.inspect?.(chunk);
+    if (held) yield held;
+    held = chunk;
+  }
+  if (bytes !== sizeArg) throw new validation.ForgeInventoryError(codesArg.short);
+  await checksArg.complete?.();
+  if (held) yield held;
+}
+
+/**
+ * The readable stream of one transfer's bytes. It pulls `chunksArg` with
+ * backpressure and ends `boundsArg` and calls `onEndArg` as soon as it is
+ * destroyed, also while a pull is pending: ending the bounds aborts the
+ * request, which closes its connection, and the pending pull's result is
+ * dropped. (`Readable.from` waits for a pending pull before it finishes a
+ * destroy, so a stalled body would keep its connection until the idle limit.)
+ * The stream errors with what `chunksArg` throws.
+ */
+export const createTransferStream = (
+  boundsArg: ITransferBounds, chunksArg: AsyncGenerator<Uint8Array, void, undefined>, onEndArg?: () => void,
+): InstanceType<typeof plugins.stream.Readable> => {
+  let pulling = false;
+  const stream: InstanceType<typeof plugins.stream.Readable> = new plugins.stream.Readable({
+    read() {
+      if (pulling) return;
+      pulling = true;
+      void (async () => {
+        try {
+          while (!stream.destroyed) {
+            const result = await chunksArg.next();
+            if (stream.destroyed) return;
+            if (result.done) return void stream.push(null);
+            if (!stream.push(result.value)) return;
+          }
+        } catch (error) {
+          stream.destroy(error as Error);
+        } finally {
+          pulling = false;
+        }
+      })();
+    },
+    destroy(errorArg, callbackArg) {
+      boundsArg.end();
+      onEndArg?.();
+      // Runs the generator's cleanup once a pending pull has settled; nothing waits for it.
+      chunksArg.return(undefined).catch(() => undefined);
+      callbackArg(errorArg);
+    },
+  });
+  return stream;
+};