@foss.global/codefeed 5.2.0 → 5.3.0

package/ts/classes.giteasourcetransfer.ts

@@ -7,6 +7,8 @@ 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 { canonicalPackageDocument, swiftManifestVersionPattern } 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 +101,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 +133,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;
@@ -149,6 +170,11 @@ const packageContentCodes = {
 
 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}$/;
 
@@ -539,63 +565,174 @@ 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 (typeof swiftVersion !== 'string' || !swiftManifestVersionPattern.test(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 = `${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'];
+      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);
+      read = (signalArg) => this.#swiftManifest(selected, parts, 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;
+    await this.#versionIdentified(selected, version, signal);
+    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 };
+  }
+
+  /**
+   * A Swift release's `Package.swift`, or with `swiftVersionArg` its
+   * alternate manifest; null when Gitea redirects the alternate one to the
+   * release's own `Package.swift` (303), which is how it answers a version it
+   * holds no manifest for. No redirect is followed.
+   */
+  async #swiftManifest(
+    packageArg: TGiteaPackageSelector, partsArg: { scope: string; name: string }, versionArg: TGiteaPackageVersionSelector, swiftVersionArg: string | null,
+    signalArg: AbortSignal | undefined,
+  ): Promise<{ bytes: Buffer; mediaType: string } | null> {
+    const release = `${this.#options.baseUrl}/api/packages/${encodeURIComponent(packageArg.owner)}/swift/${encodeURIComponent(partsArg.scope)}/${
+      encodeURIComponent(partsArg.name)}/${encodeURIComponent(versionArg.version)}/Package.swift`;
+    const url = new URL(release);
+    if (swiftVersionArg !== null) url.searchParams.set('swift-version', swiftVersionArg);
+    const response = await this.#client.requestBytesOrRedirect(url, { accept: 'application/vnd.swift.registry.v1+swift', signal: signalArg });
+    if (response.kind === 'redirect') {
+      if (swiftVersionArg === null) throw new validation.ForgeInventoryError(`http-${response.status}`);
+      // Gitea's answer for a missing alternate manifest: 303 to the release's
+      // `Package.swift` under its configured root, with the owner lowercased
+      // and scope, name and version as the request named them.
+      const expected = new URL(`${this.#options.baseUrl}/api/packages/${packageArg.owner.toLowerCase()}/swift/${partsArg.scope}/${partsArg.name}/${
+        versionArg.version}/Package.swift`);
+      let location: URL | null = null;
       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);
+        location = response.location === null ? null : new URL(response.location, url);
       } catch {
-        throw new validation.ForgeInventoryError('invalid-cargo-index');
+        location = null;
       }
-      if (line === undefined) throw new validation.ForgeInventoryError('package-document-missing');
-      bytes = Buffer.from(line, 'utf8');
+      if (response.status !== 303 || location === null || location.href !== expected.href) {
+        throw new validation.ForgeInventoryError('swift-manifest-redirect-unexpected');
+      }
+      return null;
     }
-    await this.#versionIdentified(selected, version, signal);
-    return { kind: kindArg, versionId: version.id, bytes, sha256: sha256Hex(bytes), mediaType };
+    if (response.mediaType !== 'text/x-swift') throw new validation.ForgeInventoryError('invalid-content-type');
+    return { bytes: response.bytes, mediaType: 'text/x-swift' };
+  }
+
+  /**
+   * `{"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 #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' };
+      }
+      seen += body.crates.length;
+      if (body.crates.length === 0 || seen >= total) throw new validation.ForgeInventoryError('package-document-missing');
+    }
+    throw new validation.ForgeInventoryError('cargo-search-over-bound');
   }
 
   /**

package/ts/forgeinventory.client.ts

@@ -1,4 +1,4 @@
-import type * as transport from './forgeinventory.transport.js';
+import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
 
 export interface IForgeRequestMetrics {
@@ -50,6 +50,17 @@ export interface IForgeBytesResponse {
   headers: transport.IForgeTransportResponse['headers'];
 }
 
+/** A redirect a read returned instead of refusing: never followed, its body discarded. */
+export interface IForgeRedirectResponse {
+  /** One of 301, 302, 303, 307 and 308. */
+  status: number;
+  /** The `Location` header verbatim; null when the response sent none. */
+  location: string | null;
+}
+
+/** The answer of `requestBytesOrRedirect`: the body of a 200, or the redirect. */
+export type TForgeBytesOrRedirect = ({ kind: 'bytes' } & IForgeBytesResponse) | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
 interface IReadOptions {
   signal?: AbortSignal;
   maxResponseBytes?: number;
@@ -58,8 +69,14 @@ interface IReadOptions {
   /** The media type the response must carry, checked before its body is read; any when absent. */
   requiredMediaType?: string;
   body?: { mediaType: string; bytes: Uint8Array<ArrayBuffer> };
+  /** `return` resolves a redirect status as `redirect` instead of rejecting; defaults to `refuse`. */
+  redirect?: transport.TForgeRedirectMode;
 }
 
+type TReadResult =
+  | { kind: 'bytes'; bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }
+  | ({ kind: 'redirect' } & IForgeRedirectResponse);
+
 /**
  * One bounded, credential-scoped read at a time, a GET or a POST with a JSON
  * body: a per-request deadline, a response-size budget and, for JSON, a
@@ -78,7 +95,7 @@ export class ForgeRequestClient {
 
   public async request(url: URL, requestArg: IForgeRequestOptions = {}): Promise<IForgeJsonResponse> {
     const mediaType = requestArg.mediaType ?? 'application/json';
-    const response = await this.#read(url, {
+    const response = await this.#body(url, {
       signal: requestArg.signal, maxResponseBytes: requestArg.maxResponseBytes, headers: requestArg.headers, accept: mediaType, requiredMediaType: mediaType,
       ...(requestArg.json === undefined ? {} : { body: { mediaType, bytes: new TextEncoder().encode(JSON.stringify(requestArg.json)) } }),
     });
@@ -91,11 +108,32 @@ export class ForgeRequestClient {
 
   /** A GET whose body is returned as the bytes that arrived, with the media type the response declared. */
   public async requestBytes(url: URL, requestArg: IForgeBytesRequestOptions): Promise<IForgeBytesResponse> {
-    const response = await this.#read(url, requestArg);
+    const response = await this.#body(url, requestArg);
     return { bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
   }
 
-  async #read(url: URL, requestArg: IReadOptions): Promise<{ bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }> {
+  /**
+   * A GET like `requestBytes`, except that a redirect status resolves as
+   * `{ kind: 'redirect', status, location }` instead of rejecting. The
+   * redirect is never followed and its body is discarded unread; any status
+   * other than 200 and a redirect still rejects with `http-<status>`.
+   */
+  public async requestBytesOrRedirect(url: URL, requestArg: IForgeBytesRequestOptions): Promise<TForgeBytesOrRedirect> {
+    const response = await this.#read(url, { ...requestArg, redirect: 'return' });
+    return response.kind === 'redirect'
+      ? response
+      : { kind: 'bytes', bytes: response.bytes, mediaType: mediaTypeOf(response.headers), headers: response.headers };
+  }
+
+  /** A read that refuses redirects, so it always answers a body. */
+  async #body(url: URL, requestArg: Omit<IReadOptions, 'redirect'>): Promise<{ bytes: Buffer; headers: transport.IForgeTransportResponse['headers'] }> {
+    const response = await this.#read(url, requestArg);
+    // The transport refuses every redirect status in this mode, so a redirect never arrives here.
+    if (response.kind === 'redirect') throw new validation.ForgeInventoryError('request-or-json-failed');
+    return response;
+  }
+
+  async #read(url: URL, requestArg: IReadOptions): Promise<TReadResult> {
     const { signal } = requestArg;
     const maxBytes = requestArg.maxResponseBytes ?? this.#options.maxResponseBytes;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new validation.ForgeInventoryError('invalid-response-budget');
@@ -111,9 +149,13 @@ export class ForgeRequestClient {
       const headers = {
         accept: requestArg.accept, ...(requestArg.body ? { 'content-type': requestArg.body.mediaType } : {}), ...requestArg.headers, ...this.#options.headers,
       };
-      const response = await this.#options.transport(url, headers, controller.signal, requestArg.body?.bytes);
+      const response = await this.#options.transport(url, headers, controller.signal, requestArg.body?.bytes, { redirect: requestArg.redirect ?? 'refuse' });
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
+      if (requestArg.redirect === 'return' && transport.redirectStatuses.has(response.status)) {
+        // The body is discarded unread by the `finally` below.
+        return { kind: 'redirect', status: response.status, location: response.headers.get('location') };
+      }
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
       if ((requestArg.requiredMediaType !== undefined && mediaTypeOf(response.headers) !== requestArg.requiredMediaType) || !bodyChunks) {
         throw new validation.ForgeInventoryError('invalid-content-type');
@@ -129,7 +171,7 @@ export class ForgeRequestClient {
         chunks.push(result.value);
       }
       if (controller.signal.aborted || Date.now() >= deadline) throw new validation.ForgeInventoryError('request-aborted-or-timed-out');
-      return { bytes: Buffer.concat(chunks), headers: response.headers };
+      return { kind: 'bytes', bytes: Buffer.concat(chunks), headers: response.headers };
     } catch (error) {
       if (error instanceof validation.ForgeInventoryError) throw error;
       throw new validation.ForgeInventoryError(controller.signal.aborted ? 'request-aborted-or-timed-out' : 'request-or-json-failed');

package/ts/forgeinventory.transport.ts

@@ -8,16 +8,29 @@ export interface IForgeTransportResponse {
   body: AsyncIterable<Uint8Array> | null;
 }
 
+/**
+ * What a transport does with a redirect status: `refuse` rejects it, `return`
+ * resolves it as the response it is, `Location` included. Neither follows it.
+ */
+export type TForgeRedirectMode = 'refuse' | 'return';
+
+export interface IForgeTransportOptions {
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
+}
+
 /**
  * Sends one credential-scoped GET, or a POST of `body` when one is given, and
- * resolves once response headers arrive. A redirect status rejects and is
- * never followed; aborting `signal` discards the connection, also while the
- * body is still being read.
+ * resolves once response headers arrive. A redirect status is never followed:
+ * it rejects, unless `options.redirect` is `return`. Aborting `signal`
+ * discards the connection, also while the body is still being read.
  */
-export type TForgeTransport = (url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>) => Promise<IForgeTransportResponse>;
+export type TForgeTransport = (
+  url: URL, headers: Record<string, string>, signal: AbortSignal, body?: Uint8Array<ArrayBuffer>, options?: IForgeTransportOptions,
+) => Promise<IForgeTransportResponse>;
 
 /** The fetch statuses whose redirect mode `error` turns them into a network error. */
-const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
+export const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308]);
 
 /**
  * Idle keep-alive sockets close after this delay, or earlier when the server
@@ -27,8 +40,10 @@ const redirectStatuses: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
 const idleSocketTimeoutMs = 4_000;
 
 /** Node's global `fetch` with the process-wide default trust store. */
-export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body) => {
-  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect: 'error', credentials: 'omit', signal });
+export const globalFetchTransport: TForgeTransport = async (url, headers, signal, body, options) => {
+  // Node's fetch answers `manual` with the redirect response itself, status and `Location` included.
+  const redirect = options?.redirect === 'return' ? 'manual' : 'error';
+  const response = await fetch(url, { method: body ? 'POST' : 'GET', headers, body, redirect, credentials: 'omit', signal });
   return { status: response.status, headers: response.headers, body: response.body };
 };
 
@@ -45,6 +60,8 @@ export interface INodeRequest {
   body?: Uint8Array | AsyncIterable<Uint8Array>;
   signal: AbortSignal;
   agents: INodeRequestAgents;
+  /** Defaults to `refuse`. */
+  redirect?: TForgeRedirectMode;
 }
 
 export interface INodeResponse extends IForgeTransportResponse {
@@ -74,9 +91,10 @@ const drained = (requestArg: InstanceType<typeof plugins.http.ClientRequest>): P
 
 /**
  * Sends one request through `node:http` or `node:https` and resolves once
- * response headers arrive. A redirect status rejects and is never followed;
- * aborting `signal` discards the connection, also while a body is still being
- * sent or read. A streamed body that fails destroys the request and rejects.
+ * response headers arrive. A redirect status is never followed: it rejects,
+ * unless `redirect` is `return`. Aborting `signal` discards the connection,
+ * also while a body is still being sent or read. A streamed body that fails
+ * destroys the request and rejects.
  */
 export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INodeResponse> => new Promise<INodeResponse>((resolve, reject) => {
   const { signal } = requestArg;
@@ -126,7 +144,7 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
   request.on('response', (response) => {
     try {
       const status = response.statusCode ?? 0;
-      if (redirectStatuses.has(status)) throw new Error('Refused redirect.');
+      if (redirectStatuses.has(status) && requestArg.redirect !== 'return') throw new Error('Refused redirect.');
       // Same combination rules as fetch: repeated fields join with ", ".
       const responseHeaders = new Headers();
       for (let index = 0; index < response.rawHeaders.length; index += 2) {
@@ -149,8 +167,10 @@ export const sendNodeRequest = (url: URL, requestArg: INodeRequest): Promise<INo
  */
 export const createHttpsTransport = (caCertificates: string[]): TForgeTransport => {
   const agents = createNodeAgents(caCertificates);
-  return async (url, headers, signal, body) => {
-    const { sent: _sent, ...response } = await sendNodeRequest(url, { method: body ? 'POST' : 'GET', headers, body, signal, agents });
+  return async (url, headers, signal, body, options) => {
+    const { sent: _sent, ...response } = await sendNodeRequest(url, {
+      method: body ? 'POST' : 'GET', headers, body, signal, agents, redirect: options?.redirect,
+    });
     return response;
   };
 };

package/ts/giteasourcetransfer.documents.ts

@@ -0,0 +1,97 @@
+import * as plugins from './plugins.js';
+import * as validation from './forgeinventory.validation.js';
+
+/**
+ * Package metadata documents that are JSON, which `canonicalPackageDocument`
+ * brings into one form: an npm version document, Swift release metadata, a
+ * crate version's line of the Cargo sparse index, and `{"description":…}`
+ * of a crate's latest version as the Cargo search serves it.
+ */
+export type TGiteaCanonicalPackageDocumentKind = 'npm-version' | 'swift-release' | 'cargo-index-entry' | 'cargo-description';
+
+export interface IGiteaCanonicalPackageDocument {
+  /** The canonical JSON, UTF-8. */
+  bytes: Buffer;
+  /** Lowercase hex SHA-256 of `bytes`. */
+  sha256: string;
+}
+
+/**
+ * The top-level member each kind removes: state the forge changes without
+ * replacing the version, which the source inventory records apart (a Cargo
+ * version's `yanked`, an npm version's `deprecated`).
+ */
+const mutableStateMembers: Readonly<Record<TGiteaCanonicalPackageDocumentKind, string | null>> = Object.freeze({
+  'npm-version': 'deprecated',
+  'swift-release': null,
+  'cargo-index-entry': 'yanked',
+  'cargo-description': null,
+});
+
+/**
+ * Orders two strings by Unicode code point. UTF-16 code-unit order (the
+ * default sort) differs from it where a surrogate pair meets U+E000 to U+FFFF.
+ */
+const compareCodePoints = (leftArg: string, rightArg: string): number => {
+  let left = 0;
+  let right = 0;
+  while (left < leftArg.length && right < rightArg.length) {
+    const leftPoint = leftArg.codePointAt(left)!;
+    const rightPoint = rightArg.codePointAt(right)!;
+    if (leftPoint !== rightPoint) return leftPoint - rightPoint;
+    left += leftPoint > 0xffff ? 2 : 1;
+    right += rightPoint > 0xffff ? 2 : 1;
+  }
+  return (leftArg.length - left) - (rightArg.length - right);
+};
+
+/** Compact JSON with object keys in code-point order at every depth, arrays in order and only safe integers as numbers. */
+const canonicalJson = (valueArg: unknown): string => {
+  if (valueArg === null || typeof valueArg === 'boolean' || typeof valueArg === 'string') return JSON.stringify(valueArg);
+  if (typeof valueArg === 'number') {
+    if (!Number.isSafeInteger(valueArg)) throw new validation.ForgeInventoryError('document-not-canonical');
+    return JSON.stringify(valueArg);
+  }
+  if (Array.isArray(valueArg)) return `[${valueArg.map(canonicalJson).join(',')}]`;
+  const record = valueArg as Record<string, unknown>;
+  return `{${Object.keys(record).sort(compareCodePoints).map((keyArg) => `${JSON.stringify(keyArg)}:${canonicalJson(record[keyArg])}`).join(',')}}`;
+};
+
+/**
+ * The canonical form of a package metadata document and its SHA-256, which a
+ * consumer records and compares instead of the bytes Gitea served: Gitea 28
+ * writes JSON objects held in maps (a crate's `features`, npm's maps) in a
+ * different key order on every read, and documents carry state that changes
+ * without a new version. In this order: decode as UTF-8 (fatal), parse as a
+ * JSON object, remove the kind's top-level mutable-state member (`yanked`
+ * for `cargo-index-entry`, `deprecated` for `npm-version`), and write it
+ * compact, object keys sorted by code point at every depth, arrays in their
+ * order, strings and safe integers as `JSON.stringify` writes them. Anything
+ * else, a number that is not a safe integer included, rejects with
+ * `document-not-canonical`; an unknown kind with
+ * `package-document-kind-invalid`. The same document gives the same bytes
+ * whatever order its keys arrived in.
+ */
+export const canonicalPackageDocument = (kindArg: TGiteaCanonicalPackageDocumentKind, bytesArg: Uint8Array): IGiteaCanonicalPackageDocument => {
+  if (!Object.hasOwn(mutableStateMembers, kindArg)) throw new validation.ForgeInventoryError('package-document-kind-invalid');
+  let canonical: string;
+  try {
+    const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytesArg)) as unknown;
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new validation.ForgeInventoryError('document-not-canonical');
+    const member = mutableStateMembers[kindArg];
+    if (member !== null) delete (parsed as Record<string, unknown>)[member];
+    canonical = canonicalJson(parsed);
+  } catch {
+    // Invalid UTF-8 or JSON, a non-object, an unsafe number, or nesting deeper than the stack.
+    throw new validation.ForgeInventoryError('document-not-canonical');
+  }
+  const bytes = Buffer.from(canonical, 'utf8');
+  return { bytes, sha256: plugins.crypto.createHash('sha256').update(bytes).digest('hex') };
+};
+
+/**
+ * A Swift version as Gitea keys an alternate manifest (`Package@swift-<v>.swift`),
+ * trimmed by its `TrimmedVersionString`: major and minor, and the patch only
+ * when it is not zero.
+ */
+export const swiftManifestVersionPattern = /^(?:0|[1-9]\d{0,17})\.(?:0|[1-9]\d{0,17})(?:\.[1-9]\d{0,17})?$/;

package/ts/index.ts

@@ -492,3 +492,5 @@ export * from './classes.giteasourcetransfer.js';
 export * from './classes.lfsbatchclient.js';
 export { GitScratchBudget, mirrorScratchBytes } from './giteasourceinventory.git.js';
 export { composeGiteaPackageContent } from './giteasourceinventory.packages.js';
+export { canonicalPackageDocument } from './giteasourcetransfer.documents.js';
+export type { IGiteaCanonicalPackageDocument, TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';