@foss.global/codefeed 5.1.0 → 5.3.0

package/dist_ts/classes.giteasourcetransfer.d.ts

@@ -1,5 +1,9 @@
 import * as plugins from './plugins.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
+import type { TGiteaCanonicalPackageDocumentKind } from './giteasourcetransfer.documents.js';
+type IPackageRecord = plugins.fossInterfaces.data.IForgeSourcePackageInventory;
+type IPackageVersion = plugins.fossInterfaces.data.IForgeSourcePackageVersion;
+type IPackageBlob = plugins.fossInterfaces.data.IForgeSourcePackageBlob;
 export interface IGiteaSourceTransferOptions {
     /** Instance root, including an optional deployment subpath. HTTPS is required. */
     baseUrl: string;
@@ -23,6 +27,8 @@ export interface IGiteaSourceTransferOptions {
     lfsTransferTimeoutMs?: number;
     /** Wall-clock limit of one release asset download, its closing identity reads included; defaults to 30 minutes, at most six hours. */
     releaseAssetTimeoutMs?: number;
+    /** Wall-clock limit of one package blob or file download, its closing identity read included; defaults to 30 minutes, at most six hours. */
+    packageTransferTimeoutMs?: number;
 }
 /**
  * A source repository: its owner's and its own name, which Git and LFS reach
@@ -64,18 +70,89 @@ export interface IGiteaReleaseAssetDownload {
      */
     stream: InstanceType<typeof plugins.stream.Readable>;
 }
+/** A package as the source inventory recorded it: what a read names, and the owner id it checks Gitea still holds. */
+export type TGiteaPackageSelector = Pick<IPackageRecord, 'owner' | 'ownerId' | 'type' | 'name'>;
+/** A version as the source inventory recorded it; its id identifies it, so a tag pushed again is another version. */
+export type TGiteaPackageVersionSelector = Pick<IPackageVersion, 'id' | 'version'>;
+/** Content as the source inventory recorded it: the SHA-256 and size of a blob. */
+export type TGiteaPackageContentSelector = Pick<IPackageBlob, 'sha256' | 'size'>;
+/** A file of a version as the source inventory recorded it: its name and the content it holds. */
+export interface IGiteaPackageFileSelector extends TGiteaPackageContentSelector {
+    name: string;
+}
+/**
+ * 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 = 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. */
+    digest: string;
+    /** The `Content-Type` header verbatim: the media type the manifest was pushed with. */
+    mediaType: string;
+    bytes: Buffer;
+}
+/**
+ * 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;
+    /**
+     * 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;
+    /** The media type Gitea declared, without parameters. */
+    mediaType: string;
+}
+export interface IGiteaPackageDownload {
+    content: TGiteaPackageContentSelector;
+    /**
+     * The content's bytes, never held whole. The last chunk is held back until
+     * exactly `content.size` bytes have arrived, their SHA-256 equals
+     * `content.sha256` and, for a version's file, the closing identity read has
+     * passed. Destroying the stream ends the download.
+     */
+    stream: InstanceType<typeof plugins.stream.Readable>;
+}
 export interface IGiteaMirrorImport {
     repository: plugins.TGitManagerRepositoryInfo;
     /** The repository size Gitea reported, in KiB, which sized the scratch reservation. */
     reportedSizeKiB: string;
 }
 /**
- * Reads a Gitea repository's Git data and LFS objects for its one-time
- * migration, with the reader's login and token: a mirror clone into a
- * GitManager the caller supplies, verified LFS object downloads and release
- * asset downloads. It never writes to Gitea: Git is read only through
- * `git-upload-pack`, LFS only through batch `download` requests and their
- * download actions, release assets only through GETs of their attachment.
+ * Reads a Gitea repository's Git data and LFS objects, and package content,
+ * for its one-time migration, with the reader's login and token: a mirror
+ * clone into a GitManager the caller supplies, verified LFS object downloads,
+ * release asset downloads, container manifests and blobs, package files and
+ * package metadata documents. It never writes to Gitea: Git is read only
+ * through `git-upload-pack`, LFS only through batch `download` requests and
+ * their download actions, release assets only through GETs of their
+ * attachment, packages only through GETs of the registries and the v1 package
+ * API.
  */
 export declare class GiteaSourceTransfer {
     #private;
@@ -150,4 +227,72 @@ export declare class GiteaSourceTransfer {
      * by the identity reads as for `downloadLfsObject`.
      */
     downloadReleaseAsset(repositoryArg: IGiteaSourceRepository, releaseIdArg: string, assetArg: TGiteaReleaseAssetSelector, optionsArg?: IGiteaReleaseAssetDownloadOptions): Promise<IGiteaReleaseAssetDownload>;
+    /**
+     * Reads one container manifest by digest from the registry with the
+     * reader's Basic credentials: its exact bytes, which must hash to `digest`
+     * (`package-manifest-digest-mismatch`), and its `Content-Type` verbatim,
+     * which must be an OCI or Docker image manifest, index or manifest list
+     * (`package-manifest-media-type-invalid`). A manifest is content-addressed,
+     * so no identity read is needed. Reading it counts a download of the version
+     * holding it, an accepted read stamp (S10 ruling, item 8).
+     */
+    readContainerManifest(packageArg: TGiteaPackageSelector, digestArg: string, optionsArg?: IGiteaPackageReadOptions): Promise<IGiteaContainerManifest>;
+    /**
+     * Downloads one container blob, a config or a layer, by digest from the
+     * registry with the reader's Basic credentials. The bytes stream verified:
+     * the last chunk is held back until exactly `content.size` bytes have
+     * arrived and their SHA-256 equals `content.sha256`. A blob is
+     * content-addressed, so no identity read is needed, and reading one counts
+     * no download. Rejects, or errors the stream, with a fixed code such as
+     * `http-<status>`, `package-content-size-mismatch` (a `content-length` that
+     * is not the size), `package-content-size-overrun`, `package-content-short-body`,
+     * `package-content-digest-mismatch` or `package-content-transfer-timed-out`.
+     */
+    downloadContainerBlob(packageArg: TGiteaPackageSelector, contentArg: TGiteaPackageContentSelector, optionsArg?: IGiteaPackageReadOptions): Promise<IGiteaPackageDownload>;
+    /**
+     * Downloads one file of a package version: a generic file, an npm tarball
+     * (`{package}/-/{version}/{file}`), a Swift source archive or a crate, by the
+     * route of the package's type with the reader's `token` authorization;
+     * container content is read with `readContainerManifest` and
+     * `downloadContainerBlob` (`package-type-unsupported`). The version is read
+     * by its id before the download and again after the last byte: it must
+     * still be the recorded version of the recorded owner, else
+     * `package-version-identity-changed`, or `http-404` once deleted. The bytes
+     * stream verified as for `downloadContainerBlob`. Reading a file counts a
+     * download of its version, an accepted read stamp (S10 ruling, item 8).
+     */
+    downloadPackageFile(packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, fileArg: IGiteaPackageFileSelector, optionsArg?: IGiteaPackageReadOptions): Promise<IGiteaPackageDownload>;
+    /**
+     * Reads one metadata document of a package version with the reader's
+     * `token` authorization, bracketed by identity reads of the version as for
+     * `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`.
+     */
+    readPackageDocument(packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: 'swift-manifest', optionsArg: IGiteaSwiftManifestReadOptions): Promise<IGiteaPackageDocument | null>;
+    readPackageDocument(packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg?: IGiteaPackageReadOptions): Promise<IGiteaPackageDocument>;
 }
+export {};