@foss.global/codefeed 3.0.0 → 3.2.0

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;
+}