@foss.global/codefeed 4.1.0 → 4.3.0

package/ts/classes.giteasourceinventory.ts

@@ -13,6 +13,9 @@ type IInstance = plugins.fossInterfaces.data.IForgeSourceInstanceInventory;
 type TOwner = plugins.fossInterfaces.data.TForgeSourceOwnerInventory;
 type IRepository = plugins.fossInterfaces.data.IForgeSourceRepositoryInventory;
 type IPackageTypeCounts = plugins.fossInterfaces.data.IForgeSourcePackageTypeCounts;
+type IRelease = plugins.fossInterfaces.data.IForgeSourceRelease;
+type IBranchProtection = plugins.fossInterfaces.data.IForgeSourceBranchProtection;
+type ITagProtection = plugins.fossInterfaces.data.IForgeSourceTagProtection;
 type IInventory = plugins.fossInterfaces.data.IForgeSourceInventory;
 
 export interface IGiteaSourceInventoryOptions {
@@ -119,6 +122,35 @@ const requiredString = (valueArg: unknown): string => {
   return value;
 };
 
+/** A string the forge may leave empty, such as a release body. */
+const text = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string') throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg;
+};
+
+/** A list of names; Gitea answers an empty one as `null`. */
+const texts = (valueArg: unknown): string[] => {
+  if (valueArg === null) return [];
+  if (!Array.isArray(valueArg)) throw new validation.ForgeInventoryError('invalid-string');
+  return valueArg.map(text);
+};
+
+/** A signed account id; Gitea's placeholder for a deleted account is -1. */
+const accountId = (valueArg: unknown): string => {
+  if (typeof valueArg === 'number' && Number.isSafeInteger(valueArg)) return String(valueArg);
+  throw new validation.ForgeInventoryError('invalid-or-imprecise-integer');
+};
+
+/** An RFC 3339 time as the forge reports it. */
+const requiredTimestamp = (valueArg: unknown): string => {
+  const value = validation.timestamp(valueArg);
+  if (value === null) throw new validation.ForgeInventoryError('invalid-timestamp');
+  return value;
+};
+
+/** Orders canonical nonnegative decimal strings numerically. */
+const compareDecimal = (aArg: string, bArg: string): number => aArg.length - bArg.length || compareText(aArg, bArg);
+
 /** One provider path segment, as an owner or repository name. */
 const segment = (valueArg: unknown): string => {
   const segments = validation.segments(valueArg);
@@ -142,6 +174,83 @@ const assets = (valueArg: unknown): { count: bigint; bytes: bigint } => {
   }), { count: 0n, bytes: 0n });
 };
 
+/** A release as Gitea reads it, drafts included, with its assets by numeric id. */
+const releaseRecord = (itemArg: unknown): IRelease => {
+  const item = validation.record(itemArg);
+  const author = validation.record(item.author);
+  const itemAssets = item.assets ?? [];
+  if (!Array.isArray(itemAssets)) throw new validation.ForgeInventoryError('invalid-assets');
+  return {
+    id: validation.decimal(item.id),
+    tagName: requiredString(item.tag_name),
+    targetCommitish: text(item.target_commitish),
+    name: text(item.name),
+    body: text(item.body),
+    draft: requiredBoolean(item.draft),
+    prerelease: requiredBoolean(item.prerelease),
+    createdAt: requiredTimestamp(item.created_at),
+    publishedAt: requiredTimestamp(item.published_at),
+    author: { id: accountId(author.id), login: requiredString(author.login) },
+    assets: itemAssets.map((assetArg: unknown) => {
+      const asset = validation.record(assetArg);
+      return {
+        id: validation.decimal(asset.id),
+        uuid: requiredString(asset.uuid),
+        name: requiredString(asset.name),
+        size: validation.decimal(asset.size),
+        downloadCount: validation.decimal(asset.download_count),
+        createdAt: requiredTimestamp(asset.created_at),
+      };
+    }).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+  };
+};
+
+const allowlist = (usernamesArg: unknown, teamsArg: unknown) => ({ usernames: texts(usernamesArg), teams: texts(teamsArg) });
+
+/** A branch protection rule with every restriction Gitea reads back. */
+const branchProtection = (itemArg: unknown): IBranchProtection => {
+  const item = validation.record(itemArg);
+  return {
+    ruleName: requiredString(item.rule_name),
+    priority: validation.decimal(item.priority),
+    enablePush: requiredBoolean(item.enable_push),
+    enablePushAllowlist: requiredBoolean(item.enable_push_whitelist),
+    pushAllowlist: allowlist(item.push_whitelist_usernames, item.push_whitelist_teams),
+    pushAllowlistDeployKeys: requiredBoolean(item.push_whitelist_deploy_keys),
+    enableForcePush: requiredBoolean(item.enable_force_push),
+    enableForcePushAllowlist: requiredBoolean(item.enable_force_push_allowlist),
+    forcePushAllowlist: allowlist(item.force_push_allowlist_usernames, item.force_push_allowlist_teams),
+    forcePushAllowlistDeployKeys: requiredBoolean(item.force_push_allowlist_deploy_keys),
+    enableMergeAllowlist: requiredBoolean(item.enable_merge_whitelist),
+    mergeAllowlist: allowlist(item.merge_whitelist_usernames, item.merge_whitelist_teams),
+    enableBypassAllowlist: requiredBoolean(item.enable_bypass_allowlist),
+    bypassAllowlist: allowlist(item.bypass_allowlist_usernames, item.bypass_allowlist_teams),
+    enableStatusCheck: requiredBoolean(item.enable_status_check),
+    statusCheckContexts: texts(item.status_check_contexts),
+    requiredApprovals: validation.decimal(item.required_approvals),
+    enableApprovalsAllowlist: requiredBoolean(item.enable_approvals_whitelist),
+    approvalsAllowlist: allowlist(item.approvals_whitelist_username, item.approvals_whitelist_teams),
+    blockOnRejectedReviews: requiredBoolean(item.block_on_rejected_reviews),
+    blockOnOfficialReviewRequests: requiredBoolean(item.block_on_official_review_requests),
+    blockOnOutdatedBranch: requiredBoolean(item.block_on_outdated_branch),
+    dismissStaleApprovals: requiredBoolean(item.dismiss_stale_approvals),
+    ignoreStaleApprovals: requiredBoolean(item.ignore_stale_approvals),
+    blockAdminMergeOverride: requiredBoolean(item.block_admin_merge_override),
+    requireSignedCommits: requiredBoolean(item.require_signed_commits),
+    protectedFilePatterns: text(item.protected_file_patterns),
+    unprotectedFilePatterns: text(item.unprotected_file_patterns),
+  };
+};
+
+const tagProtection = (itemArg: unknown): ITagProtection => {
+  const item = validation.record(itemArg);
+  return {
+    id: validation.decimal(item.id),
+    namePattern: requiredString(item.name_pattern),
+    allowlist: allowlist(item.whitelist_usernames, item.whitelist_teams),
+  };
+};
+
 /** A `{ <rows>, total_count }` envelope whose rows must match its total. */
 const countedEnvelope = (bodyArg: unknown, rowsKeyArg: string): { rows: unknown[]; failure: string | null } => {
   const body = validation.record(bodyArg);
@@ -516,6 +625,8 @@ export class GiteaSourceInventory {
     const parent = item.parent === undefined || item.parent === null ? null : requiredString(validation.record(item.parent).full_name);
     if (fork !== (parent !== null)) throw new validation.ForgeInventoryError('inconsistent-fork-parent');
     const options = { signal: signalArg };
+    const branchRules = await this.#unpaged(`${path}/branch_protections`, options);
+    const tagRules = await this.#unpaged(`${path}/tag_protections`, options);
     return {
       owner: ownerArg,
       name: nameArg,
@@ -533,17 +644,21 @@ export class GiteaSourceInventory {
       ...await this.#git(ownerArg, nameArg, item, signalArg),
       collaboration: await this.#collaboration(path, features, signalArg),
       // Releases stay readable while their unit is disabled; a disabled wiki answers 404.
-      releases: await this.#releases(path, signalArg),
+      ...await this.#releases(path, signalArg),
       wikiPages: features.wiki ? await this.#count(`${path}/wiki/pages`, { ...options, missingIsEmpty: true }) : unitDisabled('wiki'),
       access: {
         collaborators: await this.#count(`${path}/collaborators`, options),
         teams: await this.#repositoryTeams(path, options),
         deployKeys: await this.#count(`${path}/keys`, options),
         webhooks: await this.#count(`${path}/hooks`, options),
-        branchProtections: await this.#unpagedCount(`${path}/branch_protections`, options),
-        tagProtections: await this.#unpagedCount(`${path}/tag_protections`, options),
+        branchProtections: branchRules.measure,
+        tagProtections: tagRules.measure,
         pushMirrors: await this.#count(`${path}/push_mirrors`, options),
       },
+      protections: branchRules.rows === null || tagRules.rows === null ? null : {
+        branches: branchRules.rows.map(branchProtection).sort((aArg, bArg) => compareText(aArg.ruleName, bArg.ruleName)),
+        tags: tagRules.rows.map(tagProtection).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id)),
+      },
       actions: await this.#actions(path, empty, signalArg),
     };
   }
@@ -560,8 +675,8 @@ export class GiteaSourceInventory {
     }
   }
 
-  /** HEAD, refs, objects and LFS objects, read from a mirror clone; only the reported size comes from the API. */
-  async #git(ownerArg: string, nameArg: string, itemArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<Pick<IRepository, 'git' | 'lfs' | 'head'>> {
+  /** HEAD, ref digests, refs, objects and LFS objects, read from a mirror clone; only the reported size comes from the API. */
+  async #git(ownerArg: string, nameArg: string, itemArg: Record<string, unknown>, signalArg?: AbortSignal): Promise<Pick<IRepository, 'git' | 'lfs' | 'head' | 'refDigests'>> {
     const sizeKiB = BigInt(validation.decimal(itemArg.size));
     const username = await this.#login(signalArg);
     const measured = await measureGiteaMirror({
@@ -570,7 +685,7 @@ export class GiteaSourceInventory {
       timeoutMs: this.#options.gitTimeoutMs,
       lfsClient: this.#lfs(username), signal: signalArg,
     });
-    return { git: { reportedSizeKiB: complete(sizeKiB), ...measured.git }, lfs: measured.lfs, head: measured.head };
+    return { git: { reportedSizeKiB: complete(sizeKiB), ...measured.git }, lfs: measured.lfs, head: measured.head, refDigests: measured.refDigests };
   }
 
   /** The reader's login, the user name of its Git and LFS credentials. */
@@ -655,7 +770,8 @@ export class GiteaSourceInventory {
     };
   }
 
-  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<IRepository['releases']> {
+  /** The release counts, and the release records once the listing is complete. */
+  async #releases(pathArg: string, signalArg?: AbortSignal): Promise<Pick<IRepository, 'releases' | 'releaseRecords'>> {
     // An administrator's listing includes drafts.
     const releases = await this.#list(`${pathArg}/releases`, { signal: signalArg });
     let drafts = 0n;
@@ -667,10 +783,15 @@ export class GiteaSourceInventory {
       releaseAssets = { count: releaseAssets.count + itemAssets.count, bytes: releaseAssets.bytes + itemAssets.bytes };
     }
     return {
-      releases: listingMeasure(releases),
-      drafts: listingMeasure(releases, drafts),
-      assets: listingMeasure(releases, releaseAssets.count),
-      assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      releases: {
+        releases: listingMeasure(releases),
+        drafts: listingMeasure(releases, drafts),
+        assets: listingMeasure(releases, releaseAssets.count),
+        assetBytes: listingMeasure(releases, releaseAssets.bytes),
+      },
+      releaseRecords: releases.failure === null
+        ? releases.items.map(releaseRecord).sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id))
+        : null,
     };
   }
 
@@ -725,13 +846,18 @@ export class GiteaSourceInventory {
   }
 
   async #unpagedCount(pathArg: string, optionsArg: IListOptions): Promise<TMeasure> {
+    return (await this.#unpaged(pathArg, optionsArg)).measure;
+  }
+
+  /** A listing Gitea does not page: its count, and its rows when the read succeeded. */
+  async #unpaged(pathArg: string, optionsArg: IListOptions): Promise<{ measure: TMeasure; rows: unknown[] | null }> {
     try {
       const response = (await this.#get(pathArg, optionsArg)).body;
       const body = response === null && optionsArg.nullIsEmpty ? [] : response;
       if (!Array.isArray(body)) throw new validation.ForgeInventoryError('invalid-page');
-      return complete(body.length);
+      return { measure: complete(body.length), rows: body };
     } catch (error) {
-      return partial(0, reason(error));
+      return { measure: partial(0, reason(error)), rows: null };
     }
   }
 

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',
+    });
   }
 }