@foss.global/codefeed 5.2.0 → 5.4.0

package/ts/classes.giteasourceinventory.ts

@@ -3,9 +3,11 @@ import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import type { IForgeRequestMetrics, IForgeRequestOptions } from './forgeinventory.client.js';
+import { verifiedPackageDownload } from './forgeinventory.transfer.js';
 import { measureGiteaMirror } from './giteasourceinventory.git.js';
 import {
   cargoIndexPath, comparePackages, composeGiteaPackageContent, containerIndexMediaTypes, npmPackagePath, packageKey, packageTypePattern,
+  readSwiftManifest, swiftManifestCandidates, swiftPackageParts,
 } from './giteasourceinventory.packages.js';
 
 type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
@@ -32,6 +34,7 @@ type IPackageRef = plugins.fossInterfaces.data.IForgeSourcePackageRef;
 type IPackageRecord = plugins.fossInterfaces.data.IForgeSourcePackageInventory;
 type IPackageVersion = plugins.fossInterfaces.data.IForgeSourcePackageVersion;
 type IPackageBlob = plugins.fossInterfaces.data.IForgeSourcePackageBlob;
+type ISwiftManifest = plugins.fossInterfaces.data.IForgeSourceSwiftManifest;
 
 export interface IGiteaSourceInventoryOptions {
   /** Operator-assigned identity of the source instance. */
@@ -58,8 +61,18 @@ export interface IGiteaSourceInventoryOptions {
   pageSize?: number;
   /** Pages read per listing before the listing counts as partial. */
   maxPages?: number;
+  /** Deadline of one REST, registry or LFS batch request, and the idle limit of a Swift archive download; defaults to 60 s, at most 300 s. */
   requestTimeoutMs?: number;
   maxResponseBytes?: number;
+  /**
+   * The largest Swift source archive, in bytes, that the inventory reads for
+   * the version's `manifests`; defaults to 128 MiB, at most 1 GiB. A version
+   * whose recorded archive is larger is not read and records `manifests:
+   * null`. A consumer passes the cap its own store puts on an archive.
+   */
+  maxSwiftArchiveBytes?: number;
+  /** Wall-clock limit of one Swift archive download; defaults to 30 minutes, at most six hours. */
+  packageTransferTimeoutMs?: number;
 }
 
 /** A class of source data a run measures only when its discovery selects it. */
@@ -88,6 +101,9 @@ export type TGiteaSourceRepositoryLookup =
   | { status: 'present'; id: string; owner: string; name: string }
   | { status: 'absent'; id: string };
 
+/** A file of a version as its listing reports it: the name, and the content's SHA-256 and size as a canonical decimal. */
+interface IVersionFile { name: string; sha256: string; size: string }
+
 interface IListing {
   items: unknown[];
   /** A sanitized reason when the listing did not finish. */
@@ -415,11 +431,13 @@ const compareText = (aArg: string, bArg: string): number => aArg < bArg ? -1 : a
 export class GiteaSourceInventory {
   readonly #options: {
     instanceId: string; baseUrl: string; pageSize: number; maxPages: number; requestTimeoutMs: number; maxResponseBytes: number;
-    token: string; caCertificates?: string[]; gitWorkDir: string; gitTimeoutMs: number;
+    token: string; caCertificates?: string[]; gitWorkDir: string; gitTimeoutMs: number; maxSwiftArchiveBytes: number; packageTransferTimeoutMs: number;
   };
   readonly #transport: transport.TForgeTransport;
   readonly #client: ForgeRequestClient;
   #lfsClient: ForgeRequestClient | null = null;
+  /** The Swift archive GETs, which go through `verifiedPackageDownload` instead of a request client. */
+  readonly #archiveMetrics: IForgeRequestMetrics = { requests: 0, responseBytes: 0, rateLimitedRequests: 0 };
   #readerLogin: Promise<string> | null = null;
 
   constructor(optionsArg: IGiteaSourceInventoryOptions) {
@@ -435,9 +453,12 @@ export class GiteaSourceInventory {
       requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
       maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
       gitTimeoutMs: optionsArg.gitTimeoutMs ?? 30 * 60 * 1000,
+      maxSwiftArchiveBytes: optionsArg.maxSwiftArchiveBytes ?? 128 * 1024 * 1024,
+      packageTransferTimeoutMs: optionsArg.packageTransferTimeoutMs ?? 30 * 60 * 1000,
     };
     for (const [name, maximum] of [
       ['pageSize', 100], ['maxPages', 1_000_000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024], ['gitTimeoutMs', 6 * 60 * 60 * 1000],
+      ['maxSwiftArchiveBytes', 1024 * 1024 * 1024], ['packageTransferTimeoutMs', 6 * 60 * 60 * 1000],
     ] as const) {
       const value = limits[name];
       if (!Number.isSafeInteger(value) || value < 1 || value > maximum) throw new validation.ForgeInventoryError('invalid-limits');
@@ -459,14 +480,15 @@ export class GiteaSourceInventory {
   /** Validated, normalized instance root; contains no credentials or API suffix. */
   public get baseUrl(): string { return this.#options.baseUrl; }
 
-  /** REST and LFS batch requests together. */
+  /** REST, registry and LFS batch requests and Swift archive GETs together. */
   public get metrics(): IForgeRequestMetrics {
     const rest = this.#client.metrics;
     const lfs = this.#lfsClient?.metrics ?? { requests: 0, responseBytes: 0, rateLimitedRequests: 0 };
+    const archives = this.#archiveMetrics;
     return {
-      requests: rest.requests + lfs.requests,
-      responseBytes: rest.responseBytes + lfs.responseBytes,
-      rateLimitedRequests: rest.rateLimitedRequests + lfs.rateLimitedRequests,
+      requests: rest.requests + lfs.requests + archives.requests,
+      responseBytes: rest.responseBytes + lfs.responseBytes + archives.responseBytes,
+      rateLimitedRequests: rest.rateLimitedRequests + lfs.rateLimitedRequests + archives.rateLimitedRequests,
     };
   }
 
@@ -805,9 +827,11 @@ export class GiteaSourceInventory {
    * whose only file is `manifest.json`, are read by digest for their
    * references; no other manifest is read. npm packages add the dist-tags Gitea
    * serves (a derived `latest` included) and each version's deprecation,
-   * Cargo crates each version's yank from the sparse index. Every read is a
-   * GET; reading an index counts a download of its version, an accepted read
-   * stamp (S10 ruling, Addendum 1).
+   * Cargo crates each version's yank from the sparse index, Swift packages
+   * each version's manifests, read from its archive's file names and Gitea's
+   * manifest route. Every read is a GET; reading an index or a Swift archive
+   * counts a download of its version, an accepted read stamp (S10 ruling,
+   * Addendum 1; S10 C5 ruling, Addendum 2).
    */
   async #package(refArg: IPackageRef, signalArg?: AbortSignal): Promise<IPackageRecord> {
     const packagePath = `/packages/${encodeURIComponent(refArg.owner)}/${encodeURIComponent(refArg.type)}/${encodeURIComponent(refArg.name)}`;
@@ -838,11 +862,11 @@ export class GiteaSourceInventory {
     }
     versions.sort((aArg, bArg) => compareDecimal(aArg.id, bArg.id));
     const blobs = new Map<string, IPackageBlob>();
-    const filesByVersion = new Map<string, Array<{ name: string; sha256: string }>>();
+    const filesByVersion = new Map<string, IVersionFile[]>();
     for (const version of versions) {
       const files = (await this.#get(`${packagePath}/${encodeURIComponent(version.version)}/files`, { signal: signalArg })).body;
       if (!Array.isArray(files)) throw new validation.ForgeInventoryError('invalid-page');
-      const read: Array<{ name: string; sha256: string }> = [];
+      const read: IVersionFile[] = [];
       for (const fileArg of files) {
         const file = validation.record(fileArg);
         const sha256 = requiredString(file.sha256);
@@ -853,7 +877,7 @@ export class GiteaSourceInventory {
         const name = requiredString(file.name);
         blob.files.push({ versionId: version.id, id: validation.decimal(file.id), name });
         blobs.set(sha256, blob);
-        read.push({ name, sha256 });
+        read.push({ name, sha256, size });
       }
       filesByVersion.set(version.id, read);
     }
@@ -866,6 +890,7 @@ export class GiteaSourceInventory {
     if (record.type === 'container') await this.#containerReferences(record, filesByVersion, signalArg);
     if (record.type === 'npm') await this.#npmState(record, signalArg);
     if (record.type === 'cargo') await this.#cargoYanks(record, signalArg);
+    if (record.type === 'swift') await this.#swiftManifests(record, filesByVersion, signalArg);
     return record;
   }
 
@@ -876,9 +901,7 @@ export class GiteaSourceInventory {
    * bytes must hash to the listed SHA-256 and the response must be an index or
    * a manifest list, else the unit fails with `unexpected-manifest-shape`.
    */
-  async #containerReferences(
-    recordArg: IPackageRecord, filesArg: ReadonlyMap<string, Array<{ name: string; sha256: string }>>, signalArg?: AbortSignal,
-  ): Promise<void> {
+  async #containerReferences(recordArg: IPackageRecord, filesArg: ReadonlyMap<string, IVersionFile[]>, signalArg?: AbortSignal): Promise<void> {
     if (!/^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*)*$/.test(recordArg.name)) {
       throw new validation.ForgeInventoryError('invalid-image-name');
     }
@@ -911,6 +934,69 @@ export class GiteaSourceInventory {
     }
   }
 
+  /**
+   * Each Swift version's `manifests`. Gitea stores one file per version, its
+   * source archive, and anything else fails the unit with
+   * `swift-version-files-unexpected`. An archive over `maxSwiftArchiveBytes`
+   * by its recorded size is not read and records `null`. Otherwise the
+   * archive is read once and verified against its recorded size and SHA-256,
+   * its central directory gives the candidate keys (`swiftManifestCandidates`),
+   * and the manifest route is asked for each: a 200 is recorded with the size
+   * and SHA-256 of the bytes, the 303 to the release's `Package.swift` means
+   * Gitea holds no such manifest, and `''` must answer 200. A failed read
+   * fails the unit; it never records `null`.
+   */
+  async #swiftManifests(recordArg: IPackageRecord, filesArg: ReadonlyMap<string, IVersionFile[]>, signalArg?: AbortSignal): Promise<void> {
+    const parts = swiftPackageParts(recordArg.name);
+    for (const version of recordArg.versions) {
+      const files = filesArg.get(version.id)!;
+      if (files.length !== 1) throw new validation.ForgeInventoryError('swift-version-files-unexpected');
+      // The native store's comparison: an archive of exactly the bound is held.
+      if (BigInt(files[0].size) > BigInt(this.#options.maxSwiftArchiveBytes)) {
+        version.manifests = null;
+        continue;
+      }
+      const keys = swiftManifestCandidates(await this.#swiftArchive(recordArg, parts, version, files[0], signalArg));
+      const manifests: ISwiftManifest[] = [];
+      for (const key of keys) {
+        const manifest = await readSwiftManifest(this.#client, this.#options.baseUrl, recordArg.owner, parts, version.version, key === '' ? null : key, signalArg);
+        if (manifest === null) continue;
+        manifests.push({ key, size: manifest.bytes.byteLength, sha256: plugins.crypto.createHash('sha256').update(manifest.bytes).digest('hex') });
+      }
+      version.manifests = manifests;
+    }
+  }
+
+  /**
+   * A Swift version's source archive, read once with the reader's `token`
+   * authorization through `verifiedPackageDownload` (exact size, SHA-256
+   * before the last chunk) into one buffer of the recorded size. The read
+   * counts a download of the version, an accepted read stamp (S10 ruling
+   * item 8; S10 C5 ruling, Addendum 2).
+   */
+  async #swiftArchive(
+    recordArg: IPackageRecord, partsArg: { scope: string; name: string }, versionArg: IPackageVersion, fileArg: IVersionFile, signalArg?: AbortSignal,
+  ): Promise<Buffer> {
+    const url = new URL(`${this.#options.baseUrl}/api/packages/${encodeURIComponent(recordArg.owner)}/swift/${encodeURIComponent(partsArg.scope)}/${
+      encodeURIComponent(partsArg.name)}/${encodeURIComponent(versionArg.version)}.zip`);
+    const bytes = Number(fileArg.size);
+    const stream = await verifiedPackageDownload(
+      {
+        caCertificates: this.#options.caCertificates, packageTransferTimeoutMs: this.#options.packageTransferTimeoutMs,
+        requestTimeoutMs: this.#options.requestTimeoutMs, metrics: this.#archiveMetrics,
+      },
+      url, { authorization: `token ${this.#options.token}`, accept: 'application/vnd.swift.registry.v1+zip' },
+      { sha256: fileArg.sha256, size: fileArg.size, bytes }, signalArg, null,
+    );
+    const archive = Buffer.alloc(bytes);
+    let offset = 0;
+    for await (const chunk of stream as AsyncIterable<Uint8Array>) {
+      archive.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return archive;
+  }
+
   /** Every dist-tag Gitea serves, a `latest` it derives included, and each version's deprecation from the package document. */
   async #npmState(recordArg: IPackageRecord, signalArg?: AbortSignal): Promise<void> {
     const registry = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(recordArg.owner)}/npm`;

package/ts/classes.giteasourcetransfer.ts

@@ -1,12 +1,16 @@
 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 { createTransferBounds, createTransferStream, discardBody, heldBackChunks, verifiedPackageDownload } from './forgeinventory.transfer.js';
 import { ForgeRequestClient } from './forgeinventory.client.js';
 import { LfsBatchClient } from './classes.lfsbatchclient.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
 import { giteaCloneUrl, reserveMirrorScratch } from './giteasourceinventory.git.js';
-import { cargoIndexPath, containerManifestMediaTypes, npmPackagePath, packageTypePattern, swiftPackageParts } from './giteasourceinventory.packages.js';
+import {
+  cargoIndexPath, containerManifestMediaTypes, npmPackagePath, packageTypePattern, readSwiftManifest, swiftPackageParts,
+} from './giteasourceinventory.packages.js';
+import { canonicalPackageDocument, isSwiftManifestVersion } from './giteasourcetransfer.documents.js';
+import type { TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';
 
 type IPackageRecord = plugins.fossInterfaces.data.IForgeSourcePackageInventory;
 type IPackageVersion = plugins.fossInterfaces.data.IForgeSourcePackageVersion;
@@ -99,17 +103,29 @@ export interface IGiteaPackageFileSelector extends TGiteaPackageContentSelector
 }
 
 /**
- * Metadata a package version carries beside its files, read as Gitea serves
- * it: an npm version document, Swift release metadata, a Swift release's
- * `Package.swift`, or a crate version's line of the Cargo sparse index.
+ * Metadata a package version carries beside its files: an npm version
+ * document, Swift release metadata, a Swift release's manifest
+ * (`Package.swift`, or an alternate `Package@swift-<v>.swift`), a crate
+ * version's line of the Cargo sparse index, or the description the Cargo
+ * search serves for a crate's latest version.
  */
-export type TGiteaPackageDocumentKind = 'npm-version' | 'swift-release' | 'swift-manifest' | 'cargo-index-entry';
+export type TGiteaPackageDocumentKind = TGiteaCanonicalPackageDocumentKind | 'swift-manifest';
 
 export interface IGiteaPackageReadOptions {
   /** Aborts the read with `request-aborted`, also while a stream is read. */
   signal?: AbortSignal;
 }
 
+/** Reads an alternate Swift manifest. */
+export interface IGiteaSwiftManifestReadOptions extends IGiteaPackageReadOptions {
+  /**
+   * The Swift version Gitea keys the alternate manifest by, trimmed as its
+   * `TrimmedVersionString` writes it (`5.8`, `5.9.1`; the patch only when it
+   * is not zero).
+   */
+  swiftVersion: string;
+}
+
 /** A container manifest with the exact bytes and `Content-Type` Gitea serves. */
 export interface IGiteaContainerManifest {
   /** `sha256:` and the hex digest the bytes were checked against. */
@@ -119,12 +135,19 @@ export interface IGiteaContainerManifest {
   bytes: Buffer;
 }
 
-/** A version's metadata document with the exact bytes Gitea serves and their digest. */
+/**
+ * A version's metadata document and its digest: a JSON document in its
+ * canonical form (`canonicalPackageDocument`), a Swift manifest verbatim.
+ */
 export interface IGiteaPackageDocument {
   kind: TGiteaPackageDocumentKind;
   /** The id of the version the identity reads before and after the read confirmed. */
   versionId: string;
-  /** For `cargo-index-entry`, the version's line of the sparse index without its newline. */
+  /**
+   * The canonical JSON for every kind but `swift-manifest`, whose bytes are
+   * the stored manifest as Gitea serves it. The bytes Gitea served for a JSON
+   * document are not returned: their key order differs from read to read.
+   */
   bytes: Buffer;
   /** Lowercase hex SHA-256 of `bytes`. */
   sha256: string;
@@ -143,12 +166,13 @@ export interface IGiteaPackageDownload {
   stream: InstanceType<typeof plugins.stream.Readable>;
 }
 
-const packageContentCodes = {
-  invalidChunk: 'package-content-invalid-chunk', overrun: 'package-content-size-overrun', short: 'package-content-short-body',
-};
-
 const sha256Hex = (bytesArg: Uint8Array): string => plugins.crypto.createHash('sha256').update(bytesArg).digest('hex');
 
+/** Entries asked of one Cargo search page; Gitea serves at most its `MAX_RESPONSE_ITEMS` (50 by default). */
+const cargoSearchPageSize = 50;
+/** Search pages read for one crate's description before `cargo-search-over-bound`: 10,000 entries at 50 a page. */
+const cargoSearchMaxPages = 200;
+
 /** 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}$/;
 
@@ -475,7 +499,8 @@ export class GiteaSourceTransfer {
   ): Promise<IGiteaPackageDownload> {
     const selected = this.#containerPackage(packageArg);
     const content = this.#content(contentArg);
-    const stream = await this.#verifiedDownload(
+    const stream = await verifiedPackageDownload(
+      this.#options,
       new URL(`/v2/${selected.owner.toLowerCase()}/${selected.name}/blobs/sha256:${content.sha256}`, this.#options.baseUrl),
       { authorization: this.#basicAuthorization() }, content, optionsArg.signal, null,
     );
@@ -528,7 +553,7 @@ export class GiteaSourceTransfer {
     await this.#versionIdentified(selected, version, signal);
     let stream: InstanceType<typeof plugins.stream.Readable>;
     try {
-      stream = await this.#verifiedDownload(url, headers, content, signal, (signalArg) => this.#versionIdentified(selected, version, signalArg));
+      stream = await verifiedPackageDownload(this.#options, url, headers, content, signal, (signalArg) => this.#versionIdentified(selected, version, signalArg));
     } catch (error) {
       if (signal?.aborted) throw error;
       return this.#versionExplained(selected, version, error, signal);
@@ -539,119 +564,137 @@ export class GiteaSourceTransfer {
   /**
    * Reads one metadata document of a package version with the reader's
    * `token` authorization, bracketed by identity reads of the version as for
-   * `downloadPackageFile`: `npm-version` (the version document of an npm
-   * package), `swift-release` (Swift release metadata), `swift-manifest` (the
-   * release's `Package.swift`) or `cargo-index-entry` (the version's line of
-   * the crate's sparse index). The bytes are returned as Gitea serves them,
-   * with their SHA-256, which a consumer records beside the version id. None
-   * of these reads counts a download. A kind that does not belong to the
-   * package's type rejects with `package-document-kind-invalid`, a document
-   * of another media type with `invalid-content-type`, and a crate version
-   * missing from the index with `package-document-missing`.
+   * `downloadPackageFile`. None of these reads counts a download.
+   *
+   * - `npm-version`: the npm version document.
+   * - `swift-release`: Swift release metadata.
+   * - `swift-manifest`: the release's `Package.swift`, which must answer 200;
+   *   with `swiftVersion`, the alternate manifest Gitea keys by that version,
+   *   read without following a redirect. It resolves null only when Gitea
+   *   answers 303 to the release's own `Package.swift` URL, its way of saying
+   *   it holds no such manifest; a redirect anywhere else rejects with
+   *   `swift-manifest-redirect-unexpected`, any other status with
+   *   `http-<status>`.
+   * - `cargo-index-entry`: the version's line of the crate's sparse index;
+   *   `package-document-missing` when the index has none.
+   * - `cargo-description`: `{"description":…}` of the crate's entry in the
+   *   Cargo search (`q=<name>`, its exact name), which describes only the
+   *   version with the highest id: its `max_version` must be this version,
+   *   else `package-document-missing`, as when no entry has the name.
+   *
+   * A manifest comes back verbatim, every other document in its canonical
+   * form (`canonicalPackageDocument`, `document-not-canonical` when it has
+   * none), each with the SHA-256 of the returned bytes, which a consumer
+   * records beside the version id. A kind that does not belong to the
+   * package's type, or `swiftVersion` with another kind, rejects with
+   * `package-document-kind-invalid`, a `swiftVersion` Gitea would not key a
+   * manifest by with `swift-version-invalid`, both before any request; a
+   * document of another media type rejects with `invalid-content-type`.
    */
   public async readPackageDocument(
-    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg: IGiteaPackageReadOptions = {},
-  ): Promise<IGiteaPackageDocument> {
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: 'swift-manifest', optionsArg: IGiteaSwiftManifestReadOptions,
+  ): Promise<IGiteaPackageDocument | null>;
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg?: IGiteaPackageReadOptions,
+  ): Promise<IGiteaPackageDocument>;
+  public async readPackageDocument(
+    packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind,
+    optionsArg: IGiteaPackageReadOptions & { swiftVersion?: string } = {},
+  ): Promise<IGiteaPackageDocument | null> {
     const selected = this.#packageSelector(packageArg);
     const version = this.#versionSelector(versionArg);
+    const { signal, swiftVersion } = optionsArg;
+    if (swiftVersion !== undefined) {
+      if (kindArg !== 'swift-manifest') throw new validation.ForgeInventoryError('package-document-kind-invalid');
+      if (!isSwiftManifestVersion(swiftVersion)) throw new validation.ForgeInventoryError('swift-version-invalid');
+    }
     const registry = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(selected.owner)}`;
     const encodedVersion = encodeURIComponent(version.version);
-    let url: URL;
-    let accept: string;
-    let mediaType: string;
+    let read: (signalArg: AbortSignal | undefined) => Promise<{ bytes: Buffer; mediaType: string } | null>;
     if (kindArg === 'npm-version' && selected.type === 'npm') {
-      [url, accept, mediaType] = [new URL(`${registry}/npm/${npmPackagePath(selected.name)}/${encodedVersion}`), 'application/json', 'application/json'];
-    } else if ((kindArg === 'swift-release' || kindArg === 'swift-manifest') && selected.type === 'swift') {
+      read = (signalArg) => this.#documentBytes(new URL(`${registry}/npm/${npmPackagePath(selected.name)}/${encodedVersion}`), 'application/json', 'application/json', signalArg);
+    } else if (kindArg === 'swift-release' && selected.type === 'swift') {
+      const parts = swiftPackageParts(selected.name);
+      const release = new URL(`${registry}/swift/${encodeURIComponent(parts.scope)}/${encodeURIComponent(parts.name)}/${encodedVersion}`);
+      read = (signalArg) => this.#documentBytes(release, 'application/vnd.swift.registry.v1+json', 'application/json', signalArg);
+    } else if (kindArg === 'swift-manifest' && selected.type === 'swift') {
       const parts = swiftPackageParts(selected.name);
-      const release = `${registry}/swift/${encodeURIComponent(parts.scope)}/${encodeURIComponent(parts.name)}/${encodedVersion}`;
-      [url, accept, mediaType] = kindArg === 'swift-release'
-        ? [new URL(release), 'application/vnd.swift.registry.v1+json', 'application/json']
-        : [new URL(`${release}/Package.swift`), 'application/vnd.swift.registry.v1+swift', 'text/x-swift'];
+      read = (signalArg) => readSwiftManifest(this.#client, this.#options.baseUrl, selected.owner, parts, version.version, swiftVersion ?? null, signalArg);
     } else if (kindArg === 'cargo-index-entry' && selected.type === 'cargo') {
-      [url, accept, mediaType] = [new URL(`${registry}/cargo/${cargoIndexPath(selected.name)}`), 'text/plain', 'text/plain'];
+      const url = new URL(`${registry}/cargo/${cargoIndexPath(selected.name)}`);
+      read = async (signalArg) => {
+        const index = await this.#documentBytes(url, 'text/plain', 'text/plain', signalArg);
+        let line: string | undefined;
+        try {
+          line = new TextDecoder('utf-8', { fatal: true }).decode(index.bytes).split('\n')
+            .find((lineArg) => lineArg !== '' && validation.record(JSON.parse(lineArg) as unknown).vers === version.version);
+        } catch {
+          throw new validation.ForgeInventoryError('invalid-cargo-index');
+        }
+        if (line === undefined) throw new validation.ForgeInventoryError('package-document-missing');
+        return { bytes: Buffer.from(line, 'utf8'), mediaType: index.mediaType };
+      };
+    } else if (kindArg === 'cargo-description' && selected.type === 'cargo') {
+      // Gitea's crate name rule, checked before any request.
+      void cargoIndexPath(selected.name);
+      read = (signalArg) => this.#cargoDescription(registry, selected.name, version.version, signalArg);
     } else {
       throw new validation.ForgeInventoryError('package-document-kind-invalid');
     }
-    const { signal } = optionsArg;
     await this.#versionIdentified(selected, version, signal);
-    let response: Awaited<ReturnType<ForgeRequestClient['requestBytes']>>;
+    let document: { bytes: Buffer; mediaType: string } | null;
     try {
-      response = await this.#client.requestBytes(url, { accept, signal });
+      document = await read(signal);
     } catch (error) {
       if (signal?.aborted) throw new validation.ForgeInventoryError('request-aborted');
       return this.#versionExplained(selected, version, error, signal);
     }
-    if (response.mediaType !== mediaType) throw new validation.ForgeInventoryError('invalid-content-type');
-    let bytes = response.bytes;
-    if (kindArg === 'cargo-index-entry') {
-      let line: string | undefined;
-      try {
-        line = new TextDecoder('utf-8', { fatal: true }).decode(bytes).split('\n')
-          .find((lineArg) => lineArg !== '' && validation.record(JSON.parse(lineArg) as unknown).vers === version.version);
-      } catch {
-        throw new validation.ForgeInventoryError('invalid-cargo-index');
-      }
-      if (line === undefined) throw new validation.ForgeInventoryError('package-document-missing');
-      bytes = Buffer.from(line, 'utf8');
-    }
     await this.#versionIdentified(selected, version, signal);
-    return { kind: kindArg, versionId: version.id, bytes, sha256: sha256Hex(bytes), mediaType };
+    if (document === null) return null;
+    if (kindArg === 'swift-manifest') {
+      return { kind: kindArg, versionId: version.id, bytes: document.bytes, sha256: sha256Hex(document.bytes), mediaType: document.mediaType };
+    }
+    const canonical = canonicalPackageDocument(kindArg, document.bytes);
+    return { kind: kindArg, versionId: version.id, bytes: canonical.bytes, sha256: canonical.sha256, mediaType: document.mediaType };
+  }
+
+  /** A document's body, which must carry `mediaTypeArg`. */
+  async #documentBytes(urlArg: URL, acceptArg: string, mediaTypeArg: string, signalArg: AbortSignal | undefined): Promise<{ bytes: Buffer; mediaType: string }> {
+    const response = await this.#client.requestBytes(urlArg, { accept: acceptArg, signal: signalArg });
+    if (response.mediaType !== mediaTypeArg) throw new validation.ForgeInventoryError('invalid-content-type');
+    return { bytes: response.bytes, mediaType: mediaTypeArg };
   }
 
   /**
-   * Streams one download verified against `contentArg`: the response must be a
-   * 200 whose `content-length`, when sent, is the size; the last chunk is held
-   * back until the size and SHA-256 match and `identifiedArg`, when given, has
-   * passed once more.
+   * `{"description":…}` of the crate's entry in the Cargo search, read page by
+   * page until the entry with exactly `nameArg` turns up. Gitea's search
+   * matches names by substring and serves one entry per crate, describing its
+   * version with the highest id, whose version `max_version` names.
    */
-  async #verifiedDownload(
-    urlArg: URL, headersArg: Record<string, string>, contentArg: { sha256: string; size: string; bytes: number }, signalArg: AbortSignal | undefined,
-    identifiedArg: ((signalArg: AbortSignal) => Promise<void>) | null,
-  ): Promise<InstanceType<typeof plugins.stream.Readable>> {
-    if (signalArg?.aborted) throw new validation.ForgeInventoryError('request-aborted');
-    const agents = transport.createNodeAgents(this.#options.caCertificates);
-    const close = () => agents.https?.destroy();
-    const transfer = createTransferBounds(signalArg, {
-      limitMs: this.#options.packageTransferTimeoutMs, idleMs: this.#options.requestTimeoutMs,
-      timedOutCode: 'package-content-transfer-timed-out', failedCode: 'package-content-transfer-failed',
-    });
-    let body: AsyncIterable<Uint8Array>;
-    try {
-      const response = await transfer.run(() => transport.sendNodeRequest(urlArg, { method: 'GET', headers: headersArg, 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() !== contentArg.size) {
-        await transfer.run(() => discardBody(response.body));
-        throw new validation.ForgeInventoryError('package-content-size-mismatch');
+  async #cargoDescription(registryArg: string, nameArg: string, versionArg: string, signalArg: AbortSignal | undefined): Promise<{ bytes: Buffer; mediaType: string }> {
+    let seen = 0;
+    for (let page = 1; page <= cargoSearchMaxPages; page++) {
+      const url = new URL(`${registryArg}/cargo/api/v1/crates`);
+      url.searchParams.set('q', nameArg);
+      url.searchParams.set('page', String(page));
+      url.searchParams.set('per_page', String(cargoSearchPageSize));
+      const body = validation.record((await this.#client.request(url, { signal: signalArg })).body);
+      if (!Array.isArray(body.crates)) throw new validation.ForgeInventoryError('invalid-cargo-search');
+      const total = validation.record(body.meta).total;
+      if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 0) throw new validation.ForgeInventoryError('invalid-cargo-search');
+      for (const entry of body.crates) {
+        const crate = validation.record(entry);
+        if (typeof crate.name !== 'string' || typeof crate.max_version !== 'string' || typeof crate.description !== 'string') {
+          throw new validation.ForgeInventoryError('invalid-cargo-search');
+        }
+        if (crate.name !== nameArg) continue;
+        if (crate.max_version !== versionArg) throw new validation.ForgeInventoryError('package-document-missing');
+        return { bytes: Buffer.from(JSON.stringify({ description: crate.description }), 'utf8'), mediaType: 'application/json' };
       }
-      body = response.body;
-    } catch (error) {
-      const failure = transfer.failure(error, 'package-content-download-failed');
-      transfer.end();
-      close();
-      throw failure;
+      seen += body.crates.length;
+      if (body.crates.length === 0 || seen >= total) throw new validation.ForgeInventoryError('package-document-missing');
     }
-    const hash = plugins.crypto.createHash('sha256');
-    const complete = async () => {
-      if (hash.digest('hex') !== contentArg.sha256) throw new validation.ForgeInventoryError('package-content-digest-mismatch');
-      if (identifiedArg) {
-        transfer.touch();
-        await transfer.run(() => identifiedArg(transfer.signal));
-      }
-    };
-    const chunks = async function* (): AsyncGenerator<Uint8Array, void, undefined> {
-      try {
-        yield* heldBackChunks(transfer.watch(body), contentArg.bytes, packageContentCodes, { inspect: (chunkArg) => hash.update(chunkArg), complete });
-      } catch (error) {
-        throw transfer.failure(error, 'package-content-download-failed');
-      } finally {
-        transfer.end();
-      }
-    };
-    return createTransferStream(transfer, chunks(), close);
+    throw new validation.ForgeInventoryError('cargo-search-over-bound');
   }
 
   /**