@foss.global/codefeed 5.3.0 → 5.5.0

package/ts/classes.giteasourcetransfer.ts

@@ -1,13 +1,15 @@
 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 { canonicalPackageDocument, swiftManifestVersionPattern } from './giteasourcetransfer.documents.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;
@@ -164,10 +166,6 @@ 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). */
@@ -501,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,
     );
@@ -554,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);
@@ -607,7 +606,7 @@ export class GiteaSourceTransfer {
     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');
+      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);
@@ -620,7 +619,7 @@ export class GiteaSourceTransfer {
       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);
+      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') {
       const url = new URL(`${registry}/cargo/${cargoIndexPath(selected.name)}`);
       read = async (signalArg) => {
@@ -666,43 +665,6 @@ export class GiteaSourceTransfer {
     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 {
-        location = response.location === null ? null : new URL(response.location, url);
-      } catch {
-        location = null;
-      }
-      if (response.status !== 303 || location === null || location.href !== expected.href) {
-        throw new validation.ForgeInventoryError('swift-manifest-redirect-unexpected');
-      }
-      return null;
-    }
-    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
@@ -735,62 +697,6 @@ export class GiteaSourceTransfer {
     throw new validation.ForgeInventoryError('cargo-search-over-bound');
   }
 
-  /**
-   * 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.
-   */
-  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');
-      }
-      body = response.body;
-    } catch (error) {
-      const failure = transfer.failure(error, 'package-content-download-failed');
-      transfer.end();
-      close();
-      throw failure;
-    }
-    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);
-  }
-
   /**
    * Reads the version by Gitea's v1 package API: it must still carry the
    * recorded version id, owner id, type and name, else

package/ts/forgeinventory.transfer.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
+import * as transport from './forgeinventory.transport.js';
 import * as validation from './forgeinventory.validation.js';
+import type { IForgeRequestMetrics } from './forgeinventory.client.js';
 
 /** Response bytes read from an unused answer before the rest is discarded. */
 const maxDiscardedResponseBytes = 64 * 1024;
@@ -201,3 +203,89 @@ export const createTransferStream = (
   });
   return stream;
 };
+
+/** Passes `sourceArg`'s chunks on, adding each one's bytes to `metricsArg` as it arrives. */
+async function* countedBytes(sourceArg: AsyncIterable<Uint8Array>, metricsArg: IForgeRequestMetrics): AsyncGenerator<Uint8Array, void, undefined> {
+  for await (const chunk of sourceArg) {
+    if (chunk instanceof Uint8Array) metricsArg.responseBytes += chunk.byteLength;
+    yield chunk;
+  }
+}
+
+/** The `heldBackChunks` codes of a package content download. */
+const packageContentCodes = {
+  invalidChunk: 'package-content-invalid-chunk', overrun: 'package-content-size-overrun', short: 'package-content-short-body',
+};
+
+/** The reader settings a verified package content download runs with. */
+export interface IVerifiedPackageDownloadOptions {
+  /** PEM certificates that replace the default trust store for the download's connection. */
+  caCertificates?: string[];
+  /** Wall-clock limit of the whole download, the closing `identifiedArg` read included. */
+  packageTransferTimeoutMs: number;
+  /** Idle limit of the download, re-armed on every chunk and before the closing `identifiedArg` read. */
+  requestTimeoutMs: number;
+  /** Counts the request, a 429 answer and every body byte that arrives, as `ForgeRequestClient` counts its reads. */
+  metrics?: IForgeRequestMetrics;
+}
+
+/**
+ * Streams one package content download verified against `contentArg`, sent
+ * over node:https with the caller's CA certificates: 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.
+ */
+export const verifiedPackageDownload = async (
+  optionsArg: IVerifiedPackageDownloadOptions, 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(optionsArg.caCertificates);
+  const close = () => agents.https?.destroy();
+  const transfer = createTransferBounds(signalArg, {
+    limitMs: optionsArg.packageTransferTimeoutMs, idleMs: optionsArg.requestTimeoutMs,
+    timedOutCode: 'package-content-transfer-timed-out', failedCode: 'package-content-transfer-failed',
+  });
+  const { metrics } = optionsArg;
+  let body: AsyncIterable<Uint8Array>;
+  try {
+    if (metrics) metrics.requests++;
+    const response = await transfer.run(() => transport.sendNodeRequest(urlArg, { method: 'GET', headers: headersArg, signal: transfer.signal, agents }));
+    if (metrics && response.status === 429) metrics.rateLimitedRequests++;
+    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');
+    }
+    body = metrics ? countedBytes(response.body, metrics) : response.body;
+  } catch (error) {
+    const failure = transfer.failure(error, 'package-content-download-failed');
+    transfer.end();
+    close();
+    throw failure;
+  }
+  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);
+};

package/ts/giteasourceinventory.packages.ts

@@ -1,5 +1,7 @@
 import * as plugins from './plugins.js';
 import * as validation from './forgeinventory.validation.js';
+import type { ForgeRequestClient } from './forgeinventory.client.js';
+import { swiftManifestKey } from './giteasourcetransfer.documents.js';
 
 type TMeasure = plugins.fossInterfaces.data.TForgeSourceMeasure;
 type IPackageRef = plugins.fossInterfaces.data.IForgeSourcePackageRef;
@@ -64,6 +66,172 @@ export const swiftPackageParts = (nameArg: string): { scope: string; name: strin
   return { scope: match[1], name: match[2] };
 };
 
+/**
+ * A Swift release's `Package.swift`, or with `swiftVersionArg` its alternate
+ * manifest, read with `clientArg`'s `token` authorization; 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: any other redirect rejects with `swift-manifest-redirect-unexpected`,
+ * a redirect of `Package.swift` itself with `http-<status>`, and a body that
+ * is not `text/x-swift` with `invalid-content-type`. The read counts no
+ * download.
+ */
+export const readSwiftManifest = async (
+  clientArg: ForgeRequestClient, baseUrlArg: string, ownerArg: string, partsArg: { scope: string; name: string }, versionArg: string,
+  swiftVersionArg: string | null, signalArg: AbortSignal | undefined,
+): Promise<{ bytes: Buffer; mediaType: string } | null> => {
+  const url = new URL(`${baseUrlArg}/api/packages/${encodeURIComponent(ownerArg)}/swift/${encodeURIComponent(partsArg.scope)}/${
+    encodeURIComponent(partsArg.name)}/${encodeURIComponent(versionArg)}/Package.swift`);
+  if (swiftVersionArg !== null) url.searchParams.set('swift-version', swiftVersionArg);
+  const response = await clientArg.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(`${baseUrlArg}/api/packages/${ownerArg.toLowerCase()}/swift/${partsArg.scope}/${partsArg.name}/${versionArg}/Package.swift`);
+    let location: URL | null = null;
+    try {
+      location = response.location === null ? null : new URL(response.location, url);
+    } catch {
+      location = null;
+    }
+    if (response.status !== 303 || location === null || location.href !== expected.href) {
+      throw new validation.ForgeInventoryError('swift-manifest-redirect-unexpected');
+    }
+    return null;
+  }
+  if (response.mediaType !== 'text/x-swift') throw new validation.ForgeInventoryError('invalid-content-type');
+  return { bytes: response.bytes, mediaType: 'text/x-swift' };
+};
+
+/** Distinct manifest keys read per Swift version, `''` included; Gitea keeps at most 64 manifests (`maxManifestFiles`). */
+const maxSwiftManifestCandidates = 64;
+
+/**
+ * The name of every central-directory entry of a zip archive, in directory
+ * order, each byte one code unit (Go strings are bytes, and only ASCII names
+ * can match `manifestPattern`). It reads the directory as Go 1.27.2's
+ * `archive/zip` `NewReader` does, the archive/zip Gitea 28.2.0 builds with:
+ * - the end record is the last signature in the final 65 KiB whose comment
+ *   fits in the archive;
+ * - its zip64 locator and end record are used when a count, size or offset
+ *   is saturated and a locator for disk 0 of 1 sits right before it;
+ * - the base offset of data prepended to the archive is the end record's
+ *   position minus the directory's size and offset, unless a directory
+ *   header sits at the unadjusted offset;
+ * - headers are read one after another until one is malformed or cut off
+ *   (a zip64 field too short for the saturated sizes and offset it stands
+ *   for is malformed), and their count must agree with the end record's in
+ *   its low 16 bits.
+ * Anything Go refuses rejects with `swift-archive-invalid`.
+ */
+export const zipEntryNames = (archiveArg: Buffer): string[] => {
+  const invalid = () => new validation.ForgeInventoryError('swift-archive-invalid');
+  const size = archiveArg.byteLength;
+  const sizeBig = BigInt(size);
+  let endOffset = -1;
+  for (let index = size - 22; index >= Math.max(0, size - 65 * 1024); index--) {
+    if (archiveArg.readUInt32LE(index) === 0x06054b50) {
+      endOffset = index;
+      break;
+    }
+  }
+  if (endOffset < 0 || endOffset + 22 + archiveArg.readUInt16LE(endOffset + 20) > size) throw invalid();
+  let directoryEnd = BigInt(endOffset);
+  let records = BigInt(archiveArg.readUInt16LE(endOffset + 10));
+  let directorySize = BigInt(archiveArg.readUInt32LE(endOffset + 12));
+  let directoryOffset = BigInt(archiveArg.readUInt32LE(endOffset + 16));
+  if (records === 0xffffn || directorySize === 0xffffffffn || directoryOffset === 0xffffffffn) {
+    const locator = endOffset - 20;
+    if (locator >= 0 && archiveArg.readUInt32LE(locator) === 0x07064b50 && archiveArg.readUInt32LE(locator + 4) === 0
+      && archiveArg.readUInt32LE(locator + 16) === 1) {
+      // Go reads the offset as an int64: one past its range is negative and leaves the archive as zip32.
+      const record = archiveArg.readBigInt64LE(locator + 8);
+      if (record >= 0n) {
+        if (record + 56n > sizeBig || archiveArg.readUInt32LE(Number(record)) !== 0x06064b50) throw invalid();
+        directoryEnd = record;
+        records = archiveArg.readBigUInt64LE(Number(record) + 32);
+        directorySize = archiveArg.readBigUInt64LE(Number(record) + 40);
+        directoryOffset = archiveArg.readBigUInt64LE(Number(record) + 48);
+      }
+    }
+  }
+  if (directorySize > 0x7fffffffffffffffn || directoryOffset > 0x7fffffffffffffffn) throw invalid();
+  let baseOffset = directoryEnd - directorySize - directoryOffset;
+  if (baseOffset + directoryOffset < 0n || baseOffset + directoryOffset >= sizeBig) throw invalid();
+  if (baseOffset > 0n && directoryHeader(archiveArg, Number(directoryOffset)).kind === 'entry') baseOffset = 0n;
+  const names: string[] = [];
+  let offset = Number(baseOffset + directoryOffset);
+  while (true) {
+    const header = directoryHeader(archiveArg, offset);
+    if (header.kind === 'end') break;
+    // Go's `io.ReadFull` reports a read that gets no byte at all as `io.EOF`, which fails the archive.
+    if (header.kind === 'eof') throw invalid();
+    names.push(header.name);
+    offset = header.next;
+  }
+  if ((BigInt(names.length) & 0xffffn) !== (records & 0xffffn)) throw invalid();
+  return names;
+};
+
+/**
+ * The central-directory header at `offsetArg`, as Go 1.27.2's
+ * `readDirectoryHeader` reads it: `entry` with its name and the offset of the
+ * next header; `end` where Go stops reading headers (a header cut off by the
+ * archive's end, another signature, or a zip64 field shorter than 8 bytes for
+ * each saturated size and offset); `eof` where a read gets no byte at all.
+ */
+const directoryHeader = (archiveArg: Buffer, offsetArg: number):
+  { kind: 'entry'; name: string; next: number } | { kind: 'end' } | { kind: 'eof' } => {
+  const available = archiveArg.byteLength - offsetArg;
+  if (available <= 0) return { kind: 'eof' };
+  if (available < 46) return { kind: 'end' };
+  if (archiveArg.readUInt32LE(offsetArg) !== 0x02014b50) return { kind: 'end' };
+  const nameLength = archiveArg.readUInt16LE(offsetArg + 28);
+  const extraLength = archiveArg.readUInt16LE(offsetArg + 30);
+  const commentLength = archiveArg.readUInt16LE(offsetArg + 32);
+  const variable = nameLength + extraLength + commentLength;
+  if (variable > 0 && available === 46) return { kind: 'eof' };
+  if (available - 46 < variable) return { kind: 'end' };
+  const saturated = [20, 24, 42].filter((fieldArg) => archiveArg.readUInt32LE(offsetArg + fieldArg) === 0xffffffff).length;
+  let extra = offsetArg + 46 + nameLength;
+  const extraEnd = extra + extraLength;
+  while (extraEnd - extra >= 4) {
+    const tag = archiveArg.readUInt16LE(extra);
+    const fieldSize = archiveArg.readUInt16LE(extra + 2);
+    extra += 4;
+    if (extraEnd - extra < fieldSize) break;
+    // The zip64 field holds 8 bytes for each saturated field, in order.
+    if (tag === 0x0001 && fieldSize < 8 * saturated) return { kind: 'end' };
+    extra += fieldSize;
+  }
+  return { kind: 'entry', name: archiveArg.toString('latin1', offsetArg + 46, offsetArg + 46 + nameLength), next: offsetArg + 46 + variable };
+};
+
+/**
+ * The keys of the manifests Gitea 28.2.0 may hold for a Swift source
+ * archive, sorted in code-unit order: `''`, and the key of every
+ * central-directory entry, in any directory, whose name does not end in `/`
+ * and whose base name matches Gitea's `manifestPattern` and parses
+ * (`swiftManifestKey`). Gitea keeps only the manifests of the shallowest
+ * directory, so the keys are a superset of what it holds, and its answer for
+ * each key decides. More than `maxSwiftManifestCandidates` distinct keys
+ * reject with `swift-manifest-candidates-over-bound`; an archive Go's
+ * `archive/zip` refuses with `swift-archive-invalid`.
+ */
+export const swiftManifestCandidates = (archiveArg: Buffer): string[] => {
+  const keys = new Set<string>(['']);
+  for (const name of zipEntryNames(archiveArg)) {
+    if (name.endsWith('/')) continue;
+    const key = swiftManifestKey(name.slice(name.lastIndexOf('/') + 1));
+    if (key === null) continue;
+    keys.add(key);
+    if (keys.size > maxSwiftManifestCandidates) throw new validation.ForgeInventoryError('swift-manifest-candidates-over-bound');
+  }
+  return [...keys].sort(compareText);
+};
+
 /**
  * The digest of the manifest a container version holds: `sha256:` and the
  * SHA-256 of the blob holding the version's `manifest.json`; null for a

package/ts/giteasourcetransfer.documents.ts

@@ -90,8 +90,51 @@ export const canonicalPackageDocument = (kindArg: TGiteaCanonicalPackageDocument
 };
 
 /**
- * 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.
+ * The largest segment Gitea's version parser reads: hashicorp/go-version
+ * (v1.9.0 in Gitea 28.2.0) parses every segment as a signed 64-bit integer
+ * and refuses a larger one.
  */
-export const swiftManifestVersionPattern = /^(?:0|[1-9]\d{0,17})\.(?:0|[1-9]\d{0,17})(?:\.[1-9]\d{0,17})?$/;
+const maxSwiftVersionSegment = 9223372036854775807n;
+
+/** Major and minor, and an optional patch, in decimal without leading zeros. */
+const trimmedSwiftVersionShape = /^(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.([1-9]\d*))?$/;
+
+/**
+ * Whether `valueArg` is a Swift version Gitea 28.2.0 can key an alternate
+ * manifest (`Package@swift-<v>.swift`) by. Gitea parses the file name's
+ * version with go-version's `NewSemver`, refuses an archive whose version
+ * does not parse (`ErrInvalidManifestVersion`), and keys the manifest by
+ * `TrimmedVersionString`: major and minor, and the patch only when it is not
+ * zero, each in decimal without leading zeros (`modules/packages/swift/metadata.go`).
+ * So a key has two or three segments, no leading zeros, no zero patch, and
+ * every segment at most 9223372036854775807, compared by value.
+ */
+export const isSwiftManifestVersion = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') return false;
+  const match = trimmedSwiftVersionShape.exec(valueArg);
+  if (!match) return false;
+  return match.slice(1).every((segmentArg) => segmentArg === undefined || BigInt(segmentArg) <= maxSwiftVersionSegment);
+};
+
+/** Gitea 28.2.0's `manifestPattern` (`modules/packages/swift/metadata.go:27`), matched against a file's base name. */
+const swiftManifestNamePattern = /^Package(?:@swift-(\d+(?:\.\d+)?(?:\.\d+)?))?\.swift$/;
+
+/**
+ * The key Gitea 28.2.0 would hold a manifest with base name `baseNameArg`
+ * by: `''` for `Package.swift`; for `Package@swift-<v>.swift`, `<v>` parsed
+ * as go-version's `NewSemver` parses it (leading zeros allowed, every segment
+ * a signed 64-bit integer, missing segments zero) and written as
+ * `TrimmedVersionString` writes it, a key `isSwiftManifestVersion` accepts.
+ * Null when the name is not a manifest name, or when a segment is over int64,
+ * which `NewSemver` refuses, so Gitea can never hold the key.
+ */
+export const swiftManifestKey = (baseNameArg: string): string | null => {
+  const match = swiftManifestNamePattern.exec(baseNameArg);
+  if (!match) return null;
+  if (match[1] === undefined) return '';
+  const segments = match[1].split('.').map((segmentArg) => BigInt(segmentArg));
+  if (segments.some((segmentArg) => segmentArg > maxSwiftVersionSegment)) return null;
+  const [major, minor = 0n, patch = 0n] = segments;
+  const key = patch === 0n ? `${major}.${minor}` : `${major}.${minor}.${patch}`;
+  return isSwiftManifestVersion(key) ? key : null;
+};