@foss.global/codefeed 5.0.0 → 5.2.0

package/dist_ts/classes.giteasourcetransfer.d.ts

@@ -1,5 +1,8 @@
 import * as plugins from './plugins.js';
 import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.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 +26,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 +69,71 @@ 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, 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.
+ */
+export type TGiteaPackageDocumentKind = 'npm-version' | 'swift-release' | 'swift-manifest' | 'cargo-index-entry';
+export interface IGiteaPackageReadOptions {
+    /** Aborts the read with `request-aborted`, also while a stream is read. */
+    signal?: AbortSignal;
+}
+/** 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 with the exact bytes Gitea serves and their digest. */
+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. */
+    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 +208,54 @@ 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`: `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`.
+     */
+    readPackageDocument(packageArg: TGiteaPackageSelector, versionArg: TGiteaPackageVersionSelector, kindArg: TGiteaPackageDocumentKind, optionsArg?: IGiteaPackageReadOptions): Promise<IGiteaPackageDocument>;
 }
+export {};