@foss.global/codefeed 2.1.0 → 3.1.0

package/dist_ts/classes.giteasourcetransfer.d.ts

@@ -0,0 +1,85 @@
+import * as plugins from './plugins.js';
+import type { ILfsRequestOptions, TLfsDownload } from './classes.lfsbatchclient.js';
+export interface IGiteaSourceTransferOptions {
+    /** Instance root, including an optional deployment subpath. HTTPS is required. */
+    baseUrl: string;
+    /** The reader's login, the user name of its Git and LFS credentials. */
+    login: string;
+    /**
+     * The reader's token, retained only in this reader's memory. It is sent only
+     * to `baseUrl`, and to Git only through `GIT_CONFIG_*` entries in the child
+     * process environment; it never appears in results, reasons or errors.
+     */
+    token: string;
+    /** PEM certificates that replace the default trust store for this reader's connections, Git transfers included. */
+    caCertificates?: string[];
+    /** Wall-clock limit of one mirror clone; defaults to 30 minutes, at most six hours. */
+    gitTimeoutMs?: number;
+    /** Deadline of one REST or LFS batch request, and the idle limit of an LFS download; defaults to 60 s, at most 300 s. */
+    requestTimeoutMs?: number;
+    /** Response-size budget of one REST or LFS batch answer; defaults to 16 MiB, at most 64 MiB. */
+    maxResponseBytes?: number;
+    /** Wall-clock limit of one LFS object download; defaults to 30 minutes, at most six hours. */
+    lfsTransferTimeoutMs?: number;
+}
+/** A source repository, by its owner's and its own name. */
+export interface IGiteaSourceRepository {
+    owner: string;
+    name: string;
+}
+export interface IGiteaMirrorImportOptions {
+    /** The repository the mirror becomes in the supplied GitManager. */
+    target: plugins.fossInterfaces.data.IGitManagerRepositorySelector;
+    /**
+     * Aborts the import with `request-aborted`. An abort while the clone runs
+     * cancels it through the GitManager transfer's own signal: the call settles
+     * once Git has exited, leaves no repository at `target`, and the GitManager
+     * keeps serving its other work.
+     */
+    signal?: AbortSignal;
+}
+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, and verified LFS object downloads. It never
+ * writes to Gitea: Git is read only through `git-upload-pack`, LFS only
+ * through batch `download` requests and their download actions.
+ */
+export declare class GiteaSourceTransfer {
+    #private;
+    constructor(optionsArg: IGiteaSourceTransferOptions);
+    /** Validated, normalized instance root; contains no credentials or API suffix. */
+    get baseUrl(): string;
+    /**
+     * Clones every ref of the repository into `options.target` of `gitManager`,
+     * a started GitManager the caller roots in its own scratch space. The size
+     * Gitea reports for the repository is read first; the clone starts only once
+     * its scratch reservation fits the free space of the file system holding
+     * the GitManager's data directory, in the process-wide `GitScratchBudget`,
+     * and the reservation is released once the clone has ended. While it runs
+     * the import holds `target`: writes to it through the GitManager fail there
+     * with `repositoryBusy`. Rejects with a fixed `ForgeInventoryError` code:
+     * `invalid-repository`, `invalid-target`, `gitmanager-not-running`, a REST
+     * code such as `http-404`, `git-workdir-failed`, `git-workdir-too-small`,
+     * `git-mirror-failed` (also when GitManager refuses `target`, such as with
+     * `repositoryBusy` while another transfer holds it) or `request-aborted`
+     * (an abort, or a GitManager stop that cancelled the clone). GitManager
+     * error text is never passed on.
+     */
+    importMirror(repositoryArg: IGiteaSourceRepository, gitManagerArg: plugins.TGitManager, optionsArg: IGiteaMirrorImportOptions): Promise<IGiteaMirrorImport>;
+    /**
+     * Downloads one LFS object of the repository: a batch `download` request
+     * with the reader's Basic credentials, then a GET of the action's href with
+     * the action's headers only. Resolves with `{ status: 'missing' }` when
+     * Gitea answers error 404, otherwise with a stream of the object verified
+     * against `oid` and `size` as described for `LfsBatchClient.download`.
+     * Rejects with a fixed code, such as `lfs-object-error-422` for a size Gitea
+     * disagrees with.
+     */
+    downloadLfsObject(repositoryArg: IGiteaSourceRepository, oidArg: string, sizeArg: number, optionsArg?: ILfsRequestOptions): Promise<TLfsDownload>;
+}

package/dist_ts/classes.giteasourcetransfer.js

@@ -0,0 +1,164 @@
+import * as plugins from './plugins.js';
+import * as transport from './forgeinventory.transport.js';
+import * as validation from './forgeinventory.validation.js';
+import { ForgeRequestClient } from './forgeinventory.client.js';
+import { LfsBatchClient } from './classes.lfsbatchclient.js';
+import { giteaCloneUrl, reserveMirrorScratch } from './giteasourceinventory.git.js';
+/**
+ * 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, and verified LFS object downloads. It never
+ * writes to Gitea: Git is read only through `git-upload-pack`, LFS only
+ * through batch `download` requests and their download actions.
+ */
+export class GiteaSourceTransfer {
+    #options;
+    #client;
+    constructor(optionsArg) {
+        const baseUrl = validation.httpUrl(optionsArg.baseUrl);
+        const unsafe = (valueArg) => typeof valueArg !== 'string' || !valueArg || /[\s\u0000-\u001f\u007f]/.test(valueArg);
+        if (!baseUrl || !baseUrl.startsWith('https:') || unsafe(optionsArg.token) || unsafe(optionsArg.login) || optionsArg.login.includes(':')) {
+            throw new validation.ForgeInventoryError('invalid-options');
+        }
+        const limits = {
+            gitTimeoutMs: optionsArg.gitTimeoutMs ?? 30 * 60 * 1000,
+            requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
+            maxResponseBytes: optionsArg.maxResponseBytes ?? 16 * 1024 * 1024,
+            lfsTransferTimeoutMs: optionsArg.lfsTransferTimeoutMs ?? 30 * 60 * 1000,
+        };
+        for (const [name, maximum] of [
+            ['gitTimeoutMs', 6 * 60 * 60 * 1000], ['requestTimeoutMs', 300_000], ['maxResponseBytes', 64 * 1024 * 1024], ['lfsTransferTimeoutMs', 6 * 60 * 60 * 1000],
+        ]) {
+            const value = limits[name];
+            if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+                throw new validation.ForgeInventoryError('invalid-limits');
+        }
+        const caCertificates = optionsArg.caCertificates === undefined ? undefined : validation.caCertificates(optionsArg.caCertificates);
+        this.#options = { baseUrl: baseUrl.replace(/\/+$/, ''), login: optionsArg.login, token: optionsArg.token, caCertificates, ...limits };
+        this.#client = new ForgeRequestClient({
+            transport: caCertificates === undefined ? transport.globalFetchTransport : transport.createHttpsTransport(caCertificates),
+            headers: { authorization: `token ${optionsArg.token}` },
+            requestTimeoutMs: limits.requestTimeoutMs,
+            maxResponseBytes: limits.maxResponseBytes,
+        });
+    }
+    /** Validated, normalized instance root; contains no credentials or API suffix. */
+    get baseUrl() { return this.#options.baseUrl; }
+    /**
+     * Clones every ref of the repository into `options.target` of `gitManager`,
+     * a started GitManager the caller roots in its own scratch space. The size
+     * Gitea reports for the repository is read first; the clone starts only once
+     * its scratch reservation fits the free space of the file system holding
+     * the GitManager's data directory, in the process-wide `GitScratchBudget`,
+     * and the reservation is released once the clone has ended. While it runs
+     * the import holds `target`: writes to it through the GitManager fail there
+     * with `repositoryBusy`. Rejects with a fixed `ForgeInventoryError` code:
+     * `invalid-repository`, `invalid-target`, `gitmanager-not-running`, a REST
+     * code such as `http-404`, `git-workdir-failed`, `git-workdir-too-small`,
+     * `git-mirror-failed` (also when GitManager refuses `target`, such as with
+     * `repositoryBusy` while another transfer holds it) or `request-aborted`
+     * (an abort, or a GitManager stop that cancelled the clone). GitManager
+     * error text is never passed on.
+     */
+    async importMirror(repositoryArg, gitManagerArg, optionsArg) {
+        const { owner, name } = this.#repository(repositoryArg);
+        const target = optionsArg?.target;
+        if (typeof target?.org !== 'string' || typeof target?.repo !== 'string')
+            throw new validation.ForgeInventoryError('invalid-target');
+        const { signal } = optionsArg;
+        if (signal?.aborted)
+            throw new validation.ForgeInventoryError('request-aborted');
+        if (!gitManagerArg.running)
+            throw new validation.ForgeInventoryError('gitmanager-not-running');
+        let reportedSizeKiB;
+        try {
+            const repository = validation.record((await this.#client.request(new URL(`${this.#options.baseUrl}/api/v1/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`), { signal })).body);
+            reportedSizeKiB = BigInt(validation.decimal(repository.size));
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new validation.ForgeInventoryError('request-aborted');
+            throw error;
+        }
+        let dataDir;
+        try {
+            dataDir = (await gitManagerArg.getStatus()).dataDir;
+        }
+        catch {
+            throw new validation.ForgeInventoryError('git-workdir-failed');
+        }
+        const release = await reserveMirrorScratch(dataDir, reportedSizeKiB, signal);
+        try {
+            const imported = await gitManagerArg.importMirror({
+                org: target.org,
+                repo: target.repo,
+                remoteUrl: giteaCloneUrl(this.#options.baseUrl, owner, name),
+                credential: { kind: 'basic', username: this.#options.login, password: this.#options.token },
+                caCertificates: this.#options.caCertificates,
+                timeoutMs: this.#options.gitTimeoutMs,
+            }, { signal });
+            return { repository: imported, reportedSizeKiB: reportedSizeKiB.toString() };
+        }
+        catch (error) {
+            const { GitManagerError } = await plugins.getGitManager();
+            const aborted = signal?.aborted || (error instanceof GitManagerError && error.code === 'transferAborted');
+            // GitManager errors are redacted, but still remote text.
+            throw new validation.ForgeInventoryError(aborted ? 'request-aborted' : 'git-mirror-failed');
+        }
+        finally {
+            // The import settles only after Git has exited, so the scratch is free again.
+            release();
+        }
+    }
+    /**
+     * Downloads one LFS object of the repository: a batch `download` request
+     * with the reader's Basic credentials, then a GET of the action's href with
+     * the action's headers only. Resolves with `{ status: 'missing' }` when
+     * Gitea answers error 404, otherwise with a stream of the object verified
+     * against `oid` and `size` as described for `LfsBatchClient.download`.
+     * Rejects with a fixed code, such as `lfs-object-error-422` for a size Gitea
+     * disagrees with.
+     */
+    async downloadLfsObject(repositoryArg, oidArg, sizeArg, optionsArg = {}) {
+        const { owner, name } = this.#repository(repositoryArg);
+        const client = new LfsBatchClient({
+            endpoint: `${giteaCloneUrl(this.#options.baseUrl, owner, name)}/info/lfs`,
+            // Gitea's LFS routes take the token as a Basic password, not as a `token` authorization.
+            credential: { kind: 'basic', username: this.#options.login, password: this.#options.token },
+            caCertificates: this.#options.caCertificates,
+            requestTimeoutMs: this.#options.requestTimeoutMs,
+            transferTimeoutMs: this.#options.lfsTransferTimeoutMs,
+            maxResponseBytes: this.#options.maxResponseBytes,
+            batchSize: 1,
+        });
+        try {
+            const download = await client.download({ oid: oidArg, size: sizeArg }, optionsArg);
+            if (download.status === 'available') {
+                download.stream.once('close', () => client.close());
+            }
+            else {
+                client.close();
+            }
+            return download;
+        }
+        catch (error) {
+            client.close();
+            throw error;
+        }
+    }
+    #repository(repositoryArg) {
+        const single = (valueArg) => {
+            const segments = validation.segments(valueArg);
+            if (segments.length !== 1)
+                throw new validation.ForgeInventoryError('invalid-repository');
+            return segments[0];
+        };
+        try {
+            return { owner: single(repositoryArg?.owner), name: single(repositoryArg?.name) };
+        }
+        catch {
+            throw new validation.ForgeInventoryError('invalid-repository');
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5naXRlYXNvdXJjZXRyYW5zZmVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvY2xhc3Nlcy5naXRlYXNvdXJjZXRyYW5zZmVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxTQUFTLE1BQU0sK0JBQStCLENBQUM7QUFDM0QsT0FBTyxLQUFLLFVBQVUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUM3RCxPQUFPLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSw0QkFBNEIsQ0FBQztBQUNoRSxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFFN0QsT0FBTyxFQUFFLGFBQWEsRUFBRSxvQkFBb0IsRUFBRSxNQUFNLCtCQUErQixDQUFDO0FBaURwRjs7Ozs7O0dBTUc7QUFDSCxNQUFNLE9BQU8sbUJBQW1CO0lBQ3JCLFFBQVEsQ0FHZjtJQUNPLE9BQU8sQ0FBcUI7SUFFckMsWUFBWSxVQUF1QztRQUNqRCxNQUFNLE9BQU8sR0FBRyxVQUFVLENBQUMsT0FBTyxDQUFDLFVBQVUsQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUN2RCxNQUFNLE1BQU0sR0FBRyxDQUFDLFFBQWlCLEVBQUUsRUFBRSxDQUFDLE9BQU8sUUFBUSxLQUFLLFFBQVEsSUFBSSxDQUFDLFFBQVEsSUFBSSx5QkFBeUIsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLENBQUM7UUFDNUgsSUFBSSxDQUFDLE9BQU8sSUFBSSxDQUFDLE9BQU8sQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLElBQUksTUFBTSxDQUFDLFVBQVUsQ0FBQyxLQUFLLENBQUMsSUFBSSxNQUFNLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQyxJQUFJLFVBQVUsQ0FBQyxLQUFLLENBQUMsUUFBUSxDQUFDLEdBQUcsQ0FBQyxFQUFFLENBQUM7WUFDeEksTUFBTSxJQUFJLFVBQVUsQ0FBQyxtQkFBbUIsQ0FBQyxpQkFBaUIsQ0FBQyxDQUFDO1FBQzlELENBQUM7UUFDRCxNQUFNLE1BQU0sR0FBRztZQUNiLFlBQVksRUFBRSxVQUFVLENBQUMsWUFBWSxJQUFJLEVBQUUsR0FBRyxFQUFFLEdBQUcsSUFBSTtZQUN2RCxnQkFBZ0IsRUFBRSxVQUFVLENBQUMsZ0JBQWdCLElBQUksTUFBTTtZQUN2RCxnQkFBZ0IsRUFBRSxVQUFVLENBQUMsZ0JBQWdCLElBQUksRUFBRSxHQUFHLElBQUksR0FBRyxJQUFJO1lBQ2pFLG9CQUFvQixFQUFFLFVBQVUsQ0FBQyxvQkFBb0IsSUFBSSxFQUFFLEdBQUcsRUFBRSxHQUFHLElBQUk7U0FDeEUsQ0FBQztRQUNGLEtBQUssTUFBTSxDQUFDLElBQUksRUFBRSxPQUFPLENBQUMsSUFBSTtZQUM1QixDQUFDLGNBQWMsRUFBRSxDQUFDLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUMsRUFBRSxDQUFDLGtCQUFrQixFQUFFLE9BQU8sQ0FBQyxFQUFFLENBQUMsa0JBQWtCLEVBQUUsRUFBRSxHQUFHLElBQUksR0FBRyxJQUFJLENBQUMsRUFBRSxDQUFDLHNCQUFzQixFQUFFLENBQUMsR0FBRyxFQUFFLEdBQUcsRUFBRSxHQUFHLElBQUksQ0FBQztTQUNqSixFQUFFLENBQUM7WUFDWCxNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLENBQUM7WUFDM0IsSUFBSSxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxHQUFHLENBQUMsSUFBSSxLQUFLLEdBQUcsT0FBTztnQkFBRSxNQUFNLElBQUksVUFBVSxDQUFDLG1CQUFtQixDQUFDLGdCQUFnQixDQUFDLENBQUM7UUFDL0gsQ0FBQztRQUNELE1BQU0sY0FBYyxHQUFHLFVBQVUsQ0FBQyxjQUFjLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxjQUFjLENBQUMsVUFBVSxDQUFDLGNBQWMsQ0FBQyxDQUFDO1FBQ2xJLElBQUksQ0FBQyxRQUFRLEdBQUcsRUFBRSxPQUFPLEVBQUUsT0FBTyxDQUFDLE9BQU8sQ0FBQyxNQUFNLEVBQUUsRUFBRSxDQUFDLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxLQUFLLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxLQUFLLEVBQUUsY0FBYyxFQUFFLEdBQUcsTUFBTSxFQUFFLENBQUM7UUFDdEksSUFBSSxDQUFDLE9BQU8sR0FBRyxJQUFJLGtCQUFrQixDQUFDO1lBQ3BDLFNBQVMsRUFBRSxjQUFjLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsb0JBQW9CLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxvQkFBb0IsQ0FBQyxjQUFjLENBQUM7WUFDekgsT0FBTyxFQUFFLEVBQUUsYUFBYSxFQUFFLFNBQVMsVUFBVSxDQUFDLEtBQUssRUFBRSxFQUFFO1lBQ3ZELGdCQUFnQixFQUFFLE1BQU0sQ0FBQyxnQkFBZ0I7WUFDekMsZ0JBQWdCLEVBQUUsTUFBTSxDQUFDLGdCQUFnQjtTQUMxQyxDQUFDLENBQUM7SUFDTCxDQUFDO0lBRUQsa0ZBQWtGO0lBQ2xGLElBQVcsT0FBTyxLQUFhLE9BQU8sSUFBSSxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsQ0FBQyxDQUFDO0lBRTlEOzs7Ozs7Ozs7Ozs7Ozs7T0FlRztJQUNJLEtBQUssQ0FBQyxZQUFZLENBQ3ZCLGFBQXFDLEVBQ3JDLGFBQWtDLEVBQ2xDLFVBQXFDO1FBRXJDLE1BQU0sRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLEdBQUcsSUFBSSxDQUFDLFdBQVcsQ0FBQyxhQUFhLENBQUMsQ0FBQztRQUN4RCxNQUFNLE1BQU0sR0FBRyxVQUFVLEVBQUUsTUFBTSxDQUFDO1FBQ2xDLElBQUksT0FBTyxNQUFNLEVBQUUsR0FBRyxLQUFLLFFBQVEsSUFBSSxPQUFPLE1BQU0sRUFBRSxJQUFJLEtBQUssUUFBUTtZQUFFLE1BQU0sSUFBSSxVQUFVLENBQUMsbUJBQW1CLENBQUMsZ0JBQWdCLENBQUMsQ0FBQztRQUNwSSxNQUFNLEVBQUUsTUFBTSxFQUFFLEdBQUcsVUFBVSxDQUFDO1FBQzlCLElBQUksTUFBTSxFQUFFLE9BQU87WUFBRSxNQUFNLElBQUksVUFBVSxDQUFDLG1CQUFtQixDQUFDLGlCQUFpQixDQUFDLENBQUM7UUFDakYsSUFBSSxDQUFDLGFBQWEsQ0FBQyxPQUFPO1lBQUUsTUFBTSxJQUFJLFVBQVUsQ0FBQyxtQkFBbUIsQ0FBQyx3QkFBd0IsQ0FBQyxDQUFDO1FBQy9GLElBQUksZUFBdUIsQ0FBQztRQUM1QixJQUFJLENBQUM7WUFDSCxNQUFNLFVBQVUsR0FBRyxVQUFVLENBQUMsTUFBTSxDQUFDLENBQUMsTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FDOUQsSUFBSSxHQUFHLENBQUMsR0FBRyxJQUFJLENBQUMsUUFBUSxDQUFDLE9BQU8saUJBQWlCLGtCQUFrQixDQUFDLEtBQUssQ0FBQyxJQUFJLGtCQUFrQixDQUFDLElBQUksQ0FBQyxFQUFFLENBQUMsRUFBRSxFQUFFLE1BQU0sRUFBRSxDQUN0SCxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUM7WUFDVCxlQUFlLEdBQUcsTUFBTSxDQUFDLFVBQVUsQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUM7UUFDaEUsQ0FBQztRQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7WUFDZixJQUFJLE1BQU0sRUFBRSxPQUFPO2dCQUFFLE1BQU0sSUFBSSxVQUFVLENBQUMsbUJBQW1CLENBQUMsaUJBQWlCLENBQUMsQ0FBQztZQUNqRixNQUFNLEtBQUssQ0FBQztRQUNkLENBQUM7UUFDRCxJQUFJLE9BQWUsQ0FBQztRQUNwQixJQUFJLENBQUM7WUFDSCxPQUFPLEdBQUcsQ0FBQyxNQUFNLGFBQWEsQ0FBQyxTQUFTLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQztRQUN0RCxDQUFDO1FBQUMsTUFBTSxDQUFDO1lBQ1AsTUFBTSxJQUFJLFVBQVUsQ0FBQyxtQkFBbUIsQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO1FBQ2pFLENBQUM7UUFDRCxNQUFNLE9BQU8sR0FBRyxNQUFNLG9CQUFvQixDQUFDLE9BQU8sRUFBRSxlQUFlLEVBQUUsTUFBTSxDQUFDLENBQUM7UUFDN0UsSUFBSSxDQUFDO1lBQ0gsTUFBTSxRQUFRLEdBQUcsTUFBTSxhQUFhLENBQUMsWUFBWSxDQUFDO2dCQUNoRCxHQUFHLEVBQUUsTUFBTSxDQUFDLEdBQUc7Z0JBQ2YsSUFBSSxFQUFFLE1BQU0sQ0FBQyxJQUFJO2dCQUNqQixTQUFTLEVBQUUsYUFBYSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsT0FBTyxFQUFFLEtBQUssRUFBRSxJQUFJLENBQUM7Z0JBQzVELFVBQVUsRUFBRSxFQUFFLElBQUksRUFBRSxPQUFPLEVBQUUsUUFBUSxFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsS0FBSyxFQUFFLFFBQVEsRUFBRSxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssRUFBRTtnQkFDM0YsY0FBYyxFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsY0FBYztnQkFDNUMsU0FBUyxFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsWUFBWTthQUN0QyxFQUFFLEVBQUUsTUFBTSxFQUFFLENBQUMsQ0FBQztZQUNmLE9BQU8sRUFBRSxVQUFVLEVBQUUsUUFBUSxFQUFFLGVBQWUsRUFBRSxlQUFlLENBQUMsUUFBUSxFQUFFLEVBQUUsQ0FBQztRQUMvRSxDQUFDO1FBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztZQUNmLE1BQU0sRUFBRSxlQUFlLEVBQUUsR0FBRyxNQUFNLE9BQU8sQ0FBQyxhQUFhLEVBQUUsQ0FBQztZQUMxRCxNQUFNLE9BQU8sR0FBRyxNQUFNLEVBQUUsT0FBTyxJQUFJLENBQUMsS0FBSyxZQUFZLGVBQWUsSUFBSSxLQUFLLENBQUMsSUFBSSxLQUFLLGlCQUFpQixDQUFDLENBQUM7WUFDMUcseURBQXlEO1lBQ3pELE1BQU0sSUFBSSxVQUFVLENBQUMsbUJBQW1CLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxpQkFBaUIsQ0FBQyxDQUFDLENBQUMsbUJBQW1CLENBQUMsQ0FBQztRQUM5RixDQUFDO2dCQUFTLENBQUM7WUFDVCw4RUFBOEU7WUFDOUUsT0FBTyxFQUFFLENBQUM7UUFDWixDQUFDO0lBQ0gsQ0FBQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0ksS0FBSyxDQUFDLGlCQUFpQixDQUFDLGFBQXFDLEVBQUUsTUFBYyxFQUFFLE9BQWUsRUFBRSxVQUFVLEdBQXVCLEVBQUU7UUFDeEksTUFBTSxFQUFFLEtBQUssRUFBRSxJQUFJLEVBQUUsR0FBRyxJQUFJLENBQUMsV0FBVyxDQUFDLGFBQWEsQ0FBQyxDQUFDO1FBQ3hELE1BQU0sTUFBTSxHQUFHLElBQUksY0FBYyxDQUFDO1lBQ2hDLFFBQVEsRUFBRSxHQUFHLGFBQWEsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLE9BQU8sRUFBRSxLQUFLLEVBQUUsSUFBSSxDQUFDLFdBQVc7WUFDekUseUZBQXlGO1lBQ3pGLFVBQVUsRUFBRSxFQUFFLElBQUksRUFBRSxPQUFPLEVBQUUsUUFBUSxFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsS0FBSyxFQUFFLFFBQVEsRUFBRSxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssRUFBRTtZQUMzRixjQUFjLEVBQUUsSUFBSSxDQUFDLFFBQVEsQ0FBQyxjQUFjO1lBQzVDLGdCQUFnQixFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsZ0JBQWdCO1lBQ2hELGlCQUFpQixFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsb0JBQW9CO1lBQ3JELGdCQUFnQixFQUFFLElBQUksQ0FBQyxRQUFRLENBQUMsZ0JBQWdCO1lBQ2hELFNBQVMsRUFBRSxDQUFDO1NBQ2IsQ0FBQyxDQUFDO1FBQ0gsSUFBSSxDQUFDO1lBQ0gsTUFBTSxRQUFRLEdBQUcsTUFBTSxNQUFNLENBQUMsUUFBUSxDQUFDLEVBQUUsR0FBRyxFQUFFLE1BQU0sRUFBRSxJQUFJLEVBQUUsT0FBTyxFQUFFLEVBQUUsVUFBVSxDQUFDLENBQUM7WUFDbkYsSUFBSSxRQUFRLENBQUMsTUFBTSxLQUFLLFdBQVcsRUFBRSxDQUFDO2dCQUNwQyxRQUFRLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxPQUFPLEVBQUUsR0FBRyxFQUFFLENBQUMsTUFBTSxDQUFDLEtBQUssRUFBRSxDQUFDLENBQUM7WUFDdEQsQ0FBQztpQkFBTSxDQUFDO2dCQUNOLE1BQU0sQ0FBQyxLQUFLLEVBQUUsQ0FBQztZQUNqQixDQUFDO1lBQ0QsT0FBTyxRQUFRLENBQUM7UUFDbEIsQ0FBQztRQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7WUFDZixNQUFNLENBQUMsS0FBSyxFQUFFLENBQUM7WUFDZixNQUFNLEtBQUssQ0FBQztRQUNkLENBQUM7SUFDSCxDQUFDO0lBRUQsV0FBVyxDQUFDLGFBQXFDO1FBQy9DLE1BQU0sTUFBTSxHQUFHLENBQUMsUUFBaUIsRUFBVSxFQUFFO1lBQzNDLE1BQU0sUUFBUSxHQUFHLFVBQVUsQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFDLENBQUM7WUFDL0MsSUFBSSxRQUFRLENBQUMsTUFBTSxLQUFLLENBQUM7Z0JBQUUsTUFBTSxJQUFJLFVBQVUsQ0FBQyxtQkFBbUIsQ0FBQyxvQkFBb0IsQ0FBQyxDQUFDO1lBQzFGLE9BQU8sUUFBUSxDQUFDLENBQUMsQ0FBQyxDQUFDO1FBQ3JCLENBQUMsQ0FBQztRQUNGLElBQUksQ0FBQztZQUNILE9BQU8sRUFBRSxLQUFLLEVBQUUsTUFBTSxDQUFDLGFBQWEsRUFBRSxLQUFLLENBQUMsRUFBRSxJQUFJLEVBQUUsTUFBTSxDQUFDLGFBQWEsRUFBRSxJQUFJLENBQUMsRUFBRSxDQUFDO1FBQ3BGLENBQUM7UUFBQyxNQUFNLENBQUM7WUFDUCxNQUFNLElBQUksVUFBVSxDQUFDLG1CQUFtQixDQUFDLG9CQUFvQixDQUFDLENBQUM7UUFDakUsQ0FBQztJQUNILENBQUM7Q0FDRiJ9

package/dist_ts/classes.lfsbatchclient.d.ts

@@ -0,0 +1,126 @@
+import * as plugins from './plugins.js';
+import type { IForgeRequestMetrics } from './forgeinventory.client.js';
+/**
+ * The credential of an LFS endpoint. It is sent only as the `Authorization`
+ * header of batch requests to the configured endpoint, never to action hrefs
+ * and never in a URL, error or result.
+ */
+export type TLfsBatchCredential = 
+/** HTTP Basic, such as a forge login with an access token as the password. */
+{
+    kind: 'basic';
+    username: string;
+    password: string;
+}
+/** A complete `Authorization` header value, such as `Bearer <token>`. */
+ | {
+    kind: 'authorization';
+    value: string;
+};
+export interface ILfsBatchClientOptions {
+    /**
+     * The repository's LFS endpoint, normally `<repository>.git/info/lfs`:
+     * `https://`, or `http://` only to an IP literal in 127.0.0.0/8 or `[::1]`.
+     * No user information, query or fragment.
+     */
+    endpoint: string;
+    credential: TLfsBatchCredential;
+    /** PEM certificates that replace the default trust store for this client's HTTPS connections. */
+    caCertificates?: string[];
+    /** Deadline of a batch or verify request, and of the response headers and every idle gap of a transfer; defaults to 60 s, at most 300 s. */
+    requestTimeoutMs?: number;
+    /** Wall-clock limit of one object's upload or download; defaults to 30 minutes, at most six hours. */
+    transferTimeoutMs?: number;
+    /** Response-size budget of a batch answer; defaults to 4 MiB, at most 64 MiB. */
+    maxResponseBytes?: number;
+    /** Objects per batch request; defaults to 100, at most 100. */
+    batchSize?: number;
+}
+/** One LFS object: its SHA-256 as 64 lowercase hex digits and its size in bytes. */
+export interface ILfsObjectId {
+    oid: string;
+    size: number;
+}
+export interface ILfsUploadObject extends ILfsObjectId {
+    /**
+     * Opens the object's bytes, called only when the server asks for them. The
+     * source must end when `signalArg` aborts; a Node.js `Readable` is also
+     * destroyed when the upload ends early.
+     */
+    open: (signalArg: AbortSignal) => AsyncIterable<Uint8Array> | Promise<AsyncIterable<Uint8Array>>;
+}
+export interface ILfsUploadResult extends ILfsObjectId {
+    /** `uploaded` when this call sent the object, `present` when the server already held it. */
+    outcome: 'uploaded' | 'present';
+}
+export interface ILfsPresence extends ILfsObjectId {
+    status: 'held' | 'missing';
+}
+/** A download: a stream of the verified object, or `missing` when the server answered error 404. */
+export type TLfsDownload = (ILfsObjectId & {
+    status: 'available';
+    stream: InstanceType<typeof plugins.stream.Readable>;
+}) | (ILfsObjectId & {
+    status: 'missing';
+});
+export interface ILfsRequestOptions {
+    signal?: AbortSignal;
+}
+/**
+ * The client's URL policy, for the endpoint and for every action href: an
+ * `https:` URL, or an `http:` URL whose host is an IP literal in 127.0.0.0/8
+ * or `[::1]`, without user information or fragment. Host names over HTTP,
+ * `localhost` included, are refused, because a name can resolve elsewhere.
+ */
+export declare const isAllowedLfsUrl: (urlArg: URL) => boolean;
+/**
+ * A provider-neutral Git LFS batch API client with the `basic` transfer
+ * adapter, bound to one LFS endpoint and its credential: uploads objects the
+ * server lacks, checks which objects it holds and downloads verified objects.
+ * Every request is bounded by deadlines, size budgets and an optional
+ * `AbortSignal`; redirects are never followed; errors are fixed
+ * `ForgeInventoryError` codes that carry no URL, header, credential or
+ * response text.
+ */
+export declare class LfsBatchClient {
+    #private;
+    constructor(optionsArg: ILfsBatchClientOptions);
+    /** Batch requests sent and their response bytes; object transfers are not counted. */
+    get metrics(): IForgeRequestMetrics;
+    /**
+     * Uploads every object the server lacks: one batch `upload` request per
+     * `batchSize` objects, then for each object with an `upload` action a PUT of
+     * exactly `size` bytes, verified against `oid` while they stream, and the
+     * `verify` action when the server sent one. An object without an `upload`
+     * action is already present. Objects are sent one at a time after their
+     * batch answer; an object whose upload or verify action would expire within
+     * the expiry margin (30 s, or `requestTimeoutMs` when that is shorter) is
+     * asked for again alone, once, and fails with `lfs-action-expired` when the
+     * fresh answer is again too short-lived. Rejects on the first object that
+     * fails.
+     */
+    upload(objectsArg: ILfsUploadObject[], optionsArg?: ILfsRequestOptions): Promise<ILfsUploadResult[]>;
+    /**
+     * Asks the server through batch `download` requests which objects it holds,
+     * without downloading them: a download action means `held`, error 404
+     * `missing`. Any other object error rejects with `lfs-object-error-<code>`.
+     * The actions are not used, so their expiry is validated but not enforced.
+     */
+    checkPresence(objectsArg: ILfsObjectId[], optionsArg?: ILfsRequestOptions): Promise<ILfsPresence[]>;
+    /**
+     * Downloads one object: a batch `download` request, then a GET of the
+     * action's href with the action's headers; a download action that would
+     * expire within the expiry margin is asked for again once, as for `upload`.
+     * Resolves with `missing` when the
+     * server answered error 404, otherwise with a stream of the object that
+     * never holds it whole. The stream errors with `lfs-size-overrun`,
+     * `lfs-short-body` or `lfs-digest-mismatch` before its last chunk when the
+     * bytes are not the object, with `request-aborted` when `signal` aborts and
+     * with `lfs-transfer-timed-out` when the transfer exceeds
+     * `transferTimeoutMs` or stalls for `requestTimeoutMs`. Destroying the
+     * stream ends the download.
+     */
+    download(objectArg: ILfsObjectId, optionsArg?: ILfsRequestOptions): Promise<TLfsDownload>;
+    /** Destroys this client's pooled connections. Idle ones close on their own after a few seconds. */
+    close(): void;
+}