@foss.global/codefeed 2.1.0 → 3.1.0

package/ts/classes.lfsbatchclient.ts

@@ -0,0 +1,614 @@
+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 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;
+}
+
+interface ILfsAction {
+  href: URL;
+  headers: Record<string, string>;
+  /** When the server stops honouring the href, in epoch milliseconds; null when it set no expiry. */
+  expiresAt: number | null;
+}
+
+type TLfsActionName = 'upload' | 'verify' | 'download';
+
+type TBatchEntry = ILfsObjectId & { actions: Record<string, ILfsAction>; errorCode: number | null };
+
+const lfsMediaType = 'application/vnd.git-lfs+json';
+/** Objects per batch request; the Git LFS reference server and Gitea accept 100. */
+const maxBatchSize = 100;
+/** Response bytes read from a PUT or verify answer before the rest is discarded. */
+const maxDiscardedResponseBytes = 64 * 1024;
+const maxActionHeaders = 32;
+const maxHeaderValueLength = 8 * 1024;
+const maxHrefLength = 8 * 1024;
+/** Request headers the client owns; an action that sets one is refused. */
+const reservedHeaderNames: ReadonlySet<string> = new Set(['host', 'content-length', 'transfer-encoding', 'connection', 'upgrade', 'te', 'trailer', 'keep-alive', 'expect']);
+const headerNamePattern = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** The longest safety margin before an action's expiry: an action that expires sooner is fetched again. */
+const maxExpiryMarginMs = 30_000;
+/** `expires_in` values beyond a century are refused, which keeps every expiry an exact epoch millisecond. */
+const maxExpiresInSeconds = 100 * 366 * 24 * 60 * 60;
+/** Go's zero `time.Time`, which the git-lfs client reads as no expiry. */
+const goZeroTime = '0001-01-01T00:00:00Z';
+
+/**
+ * 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 const isAllowedLfsUrl = (urlArg: URL): boolean => {
+  if (urlArg.username || urlArg.password || urlArg.hash) return false;
+  if (urlArg.protocol === 'https:') return urlArg.hostname !== '';
+  if (urlArg.protocol !== 'http:') return false;
+  // The URL parser normalizes every IPv4 spelling (`127.1`, `0x7f.0.0.1`) to dotted decimal and IPv6 to its short form.
+  if (urlArg.hostname === '[::1]') return true;
+  return plugins.net.isIPv4(urlArg.hostname) && urlArg.hostname.split('.')[0] === '127';
+};
+
+const objectIdPattern = /^[0-9a-f]{64}$/;
+
+const assertObjectId = (objectArg: ILfsObjectId): void => {
+  if (typeof objectArg?.oid !== 'string' || !objectIdPattern.test(objectArg.oid) || !Number.isSafeInteger(objectArg.size) || objectArg.size < 0) {
+    throw new validation.ForgeInventoryError('invalid-lfs-object');
+  }
+};
+
+/** Refuses empty lists and repeated oids. */
+const assertObjectList = (objectsArg: ILfsObjectId[]): void => {
+  if (!Array.isArray(objectsArg)) throw new validation.ForgeInventoryError('invalid-lfs-object');
+  const seen = new Set<string>();
+  for (const object of objectsArg) {
+    assertObjectId(object);
+    if (seen.has(object.oid)) throw new validation.ForgeInventoryError('duplicate-lfs-object');
+    seen.add(object.oid);
+  }
+};
+
+const credentialHeader = (credentialArg: TLfsBatchCredential): string => {
+  const unsafe = (valueArg: unknown) => typeof valueArg !== 'string' || !valueArg || /[\u0000-\u001f\u007f]/.test(valueArg);
+  if (credentialArg?.kind === 'basic') {
+    if (unsafe(credentialArg.username) || unsafe(credentialArg.password) || credentialArg.username.includes(':')) {
+      throw new validation.ForgeInventoryError('invalid-credential');
+    }
+    return `Basic ${Buffer.from(`${credentialArg.username}:${credentialArg.password}`).toString('base64')}`;
+  }
+  if (credentialArg?.kind === 'authorization') {
+    if (unsafe(credentialArg.value) || credentialArg.value.length > maxHeaderValueLength) throw new validation.ForgeInventoryError('invalid-credential');
+    return credentialArg.value;
+  }
+  throw new validation.ForgeInventoryError('invalid-credential');
+};
+
+/**
+ * An action's expiry in epoch milliseconds, or null without one. `expires_in`
+ * (whole seconds after the answer arrived) is preferred over `expires_at`
+ * (RFC 3339), as the batch API specifies. Like the git-lfs client, an
+ * `expires_in` of 0 and Go's zero time mean no expiry, because Go servers
+ * emit them for an unset value. Any other malformed value fails with
+ * `invalid-lfs-batch`.
+ */
+const actionExpiry = (actionArg: Record<string, unknown>, receivedAtArg: number): number | null => {
+  const expiresIn = actionArg.expires_in;
+  if (expiresIn !== undefined && expiresIn !== null) {
+    if (!Number.isSafeInteger(expiresIn) || Math.abs(expiresIn as number) > maxExpiresInSeconds) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+    if (expiresIn !== 0) return receivedAtArg + (expiresIn as number) * 1000;
+  }
+  const expiresAt = actionArg.expires_at;
+  if (expiresAt === undefined || expiresAt === null || expiresAt === goZeroTime) return null;
+  let text: string | null;
+  try {
+    text = validation.timestamp(expiresAt);
+  } catch {
+    throw new validation.ForgeInventoryError('invalid-lfs-batch');
+  }
+  if (text === null) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+  return Date.parse(text);
+};
+
+/**
+ * Passes the bytes of `sourceArg` on while it counts and hashes them. The last
+ * chunk is held back until the source ends with exactly `sizeArg` bytes whose
+ * SHA-256 is `oidArg`, so a consumer never receives a complete body that is
+ * wrong; otherwise it throws `lfs-size-overrun`, `lfs-short-body` or
+ * `lfs-digest-mismatch`.
+ */
+async function* verifiedChunks(sourceArg: AsyncIterable<Uint8Array>, oidArg: string, sizeArg: number): AsyncGenerator<Uint8Array, void, undefined> {
+  const hash = plugins.crypto.createHash('sha256');
+  let bytes = 0;
+  let held: Uint8Array | null = null;
+  for await (const chunk of sourceArg) {
+    if (!(chunk instanceof Uint8Array)) throw new validation.ForgeInventoryError('invalid-lfs-chunk');
+    if (chunk.byteLength === 0) continue;
+    bytes += chunk.byteLength;
+    if (bytes > sizeArg) throw new validation.ForgeInventoryError('lfs-size-overrun');
+    hash.update(chunk);
+    if (held) yield held;
+    held = chunk;
+  }
+  if (bytes !== sizeArg) throw new validation.ForgeInventoryError('lfs-short-body');
+  if (hash.digest('hex') !== oidArg) throw new validation.ForgeInventoryError('lfs-digest-mismatch');
+  if (held) yield held;
+}
+
+/**
+ * Reads and drops at most `maxDiscardedResponseBytes` of a response body that
+ * carries nothing the client uses, so its connection can be reused; a longer
+ * or failing body is discarded with its connection.
+ */
+const discardBody = async (bodyArg: AsyncIterable<Uint8Array> | null): Promise<void> => {
+  if (!bodyArg) return;
+  const chunks = bodyArg[Symbol.asyncIterator]();
+  let bytes = 0;
+  try {
+    while (bytes <= maxDiscardedResponseBytes) {
+      const result = await chunks.next();
+      if (result.done) return;
+      bytes += result.value.byteLength;
+    }
+  } catch {
+    // The status already decided the outcome.
+  } finally {
+    try { await chunks.return?.(); } catch { /* The connection is discarded. */ }
+  }
+};
+
+/**
+ * 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 class LfsBatchClient {
+  readonly #endpoint: URL;
+  readonly #batchUrl: URL;
+  readonly #agents: transport.INodeRequestAgents;
+  readonly #client: ForgeRequestClient;
+  readonly #limits: { requestTimeoutMs: number; transferTimeoutMs: number; batchSize: number; expiryMarginMs: number };
+
+  constructor(optionsArg: ILfsBatchClientOptions) {
+    let endpoint: URL;
+    try {
+      endpoint = new URL(optionsArg.endpoint);
+    } catch {
+      throw new validation.ForgeInventoryError('unsafe-lfs-url');
+    }
+    if (!isAllowedLfsUrl(endpoint) || endpoint.search) throw new validation.ForgeInventoryError('unsafe-lfs-url');
+    const authorization = credentialHeader(optionsArg.credential);
+    const limits = {
+      requestTimeoutMs: optionsArg.requestTimeoutMs ?? 60_000,
+      transferTimeoutMs: optionsArg.transferTimeoutMs ?? 30 * 60 * 1000,
+      maxResponseBytes: optionsArg.maxResponseBytes ?? 4 * 1024 * 1024,
+      batchSize: optionsArg.batchSize ?? maxBatchSize,
+    };
+    for (const [name, maximum] of [
+      ['requestTimeoutMs', 300_000], ['transferTimeoutMs', 6 * 60 * 60 * 1000], ['maxResponseBytes', 64 * 1024 * 1024], ['batchSize', maxBatchSize],
+    ] as const) {
+      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.#endpoint = new URL(endpoint.href.replace(/\/+$/, ''));
+    this.#batchUrl = new URL(`${this.#endpoint.href}/objects/batch`);
+    // Hrefs must keep the endpoint's protocol, so a plain-HTTP agent exists only for a loopback endpoint.
+    this.#agents = transport.createNodeAgents(caCertificates, endpoint.protocol === 'http:');
+    const agents = this.#agents;
+    this.#client = new ForgeRequestClient({
+      transport: async (urlArg, headersArg, signalArg, bodyArg) => {
+        const { sent: _sent, ...response } = await transport.sendNodeRequest(urlArg, { method: bodyArg ? 'POST' : 'GET', headers: headersArg, body: bodyArg, signal: signalArg, agents });
+        return response;
+      },
+      headers: { authorization },
+      requestTimeoutMs: limits.requestTimeoutMs,
+      maxResponseBytes: limits.maxResponseBytes,
+    });
+    this.#limits = {
+      requestTimeoutMs: limits.requestTimeoutMs, transferTimeoutMs: limits.transferTimeoutMs, batchSize: limits.batchSize,
+      // An action is used only while it stays valid for this margin, the time a request may take to reach the server.
+      expiryMarginMs: Math.min(maxExpiryMarginMs, limits.requestTimeoutMs),
+    };
+  }
+
+  /** Batch requests sent and their response bytes; object transfers are not counted. */
+  public get metrics(): IForgeRequestMetrics { return this.#client.metrics; }
+
+  /**
+   * 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.
+   */
+  public async upload(objectsArg: ILfsUploadObject[], optionsArg: ILfsRequestOptions = {}): Promise<ILfsUploadResult[]> {
+    assertObjectList(objectsArg);
+    for (const object of objectsArg) if (typeof object.open !== 'function') throw new validation.ForgeInventoryError('invalid-lfs-object');
+    const results: ILfsUploadResult[] = [];
+    for (let index = 0; index < objectsArg.length; index += this.#limits.batchSize) {
+      const chunk = objectsArg.slice(index, index + this.#limits.batchSize);
+      const entries = await this.#batch('upload', chunk, optionsArg.signal);
+      for (const object of chunk) {
+        let entry = entries.get(object.oid)!;
+        // Objects are sent one at a time, so a late object's actions may have expired since its batch answer.
+        if (!this.#current(entry, ['upload', 'verify'])) entry = await this.#rebatch('upload', object, ['upload', 'verify'], optionsArg.signal);
+        if (entry.errorCode !== null) throw new validation.ForgeInventoryError(`lfs-object-error-${entry.errorCode}`);
+        const upload = entry.actions.upload;
+        if (!upload) {
+          results.push({ oid: object.oid, size: object.size, outcome: 'present' });
+          continue;
+        }
+        await this.#put(object, upload, optionsArg.signal);
+        let verify = entry.actions.verify;
+        if (verify && !this.#current(entry, ['verify'])) {
+          // The PUT outlasted the verify action. A server that answers with an upload action again does not hold the object.
+          const fresh = await this.#rebatch('upload', object, ['verify'], optionsArg.signal);
+          if (fresh.errorCode !== null) throw new validation.ForgeInventoryError(`lfs-object-error-${fresh.errorCode}`);
+          if (fresh.actions.upload) throw new validation.ForgeInventoryError('lfs-action-expired');
+          verify = fresh.actions.verify;
+        }
+        if (verify) await this.#verify(object, verify, optionsArg.signal);
+        results.push({ oid: object.oid, size: object.size, outcome: 'uploaded' });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 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.
+   */
+  public async checkPresence(objectsArg: ILfsObjectId[], optionsArg: ILfsRequestOptions = {}): Promise<ILfsPresence[]> {
+    assertObjectList(objectsArg);
+    const results: ILfsPresence[] = [];
+    for (let index = 0; index < objectsArg.length; index += this.#limits.batchSize) {
+      const chunk = objectsArg.slice(index, index + this.#limits.batchSize);
+      const entries = await this.#batch('download', chunk, optionsArg.signal);
+      for (const object of chunk) {
+        results.push({ oid: object.oid, size: object.size, status: this.#downloadAction(entries.get(object.oid)!) === null ? 'missing' : 'held' });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 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.
+   */
+  public async download(objectArg: ILfsObjectId, optionsArg: ILfsRequestOptions = {}): Promise<TLfsDownload> {
+    assertObjectId(objectArg);
+    const { oid, size } = objectArg;
+    const { signal } = optionsArg;
+    let entry = (await this.#batch('download', [{ oid, size }], signal)).get(oid)!;
+    if (this.#downloadAction(entry) !== null && !this.#current(entry, ['download'])) entry = await this.#rebatch('download', { oid, size }, ['download'], signal);
+    const action = this.#downloadAction(entry);
+    if (action === null) return { oid, size, status: 'missing' };
+    const transfer = this.#transfer(signal);
+    try {
+      const response = await transfer.run(() => transport.sendNodeRequest(action.href, {
+        method: 'GET', headers: action.headers, signal: transfer.signal, agents: this.#agents,
+      }));
+      if (response.status !== 200 || !response.body) {
+        await discardBody(response.body);
+        throw new validation.ForgeInventoryError(`http-${response.status}`);
+      }
+      const length = response.headers.get('content-length');
+      if (length !== null && length.trim() !== String(size)) {
+        await discardBody(response.body);
+        throw new validation.ForgeInventoryError('lfs-size-mismatch');
+      }
+      const body = response.body;
+      const chunks = async function* (): AsyncGenerator<Uint8Array, void, undefined> {
+        try {
+          yield* verifiedChunks(transfer.watch(body), oid, size);
+        } catch (error) {
+          throw transfer.failure(error, 'lfs-download-failed');
+        } finally {
+          transfer.end();
+        }
+      };
+      const stream = plugins.stream.Readable.from(chunks(), { objectMode: false });
+      // A consumer that destroys the stream ends the download, also while a read is pending.
+      stream.once('close', () => transfer.end());
+      return { oid, size, status: 'available', stream };
+    } catch (error) {
+      transfer.end();
+      throw transfer.failure(error, 'lfs-download-failed');
+    }
+  }
+
+  /** Destroys this client's pooled connections. Idle ones close on their own after a few seconds. */
+  public close(): void {
+    this.#agents.http?.destroy();
+    this.#agents.https?.destroy();
+  }
+
+  /** A download action, or null for error 404. */
+  #downloadAction(entryArg: TBatchEntry): ILfsAction | null {
+    if (entryArg.errorCode === 404) return null;
+    if (entryArg.errorCode !== null) throw new validation.ForgeInventoryError(`lfs-object-error-${entryArg.errorCode}`);
+    const download = entryArg.actions.download;
+    if (!download) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+    return download;
+  }
+
+  /** One batch request; answers every requested object exactly once, keyed by oid. */
+  async #batch(operationArg: 'upload' | 'download', objectsArg: ILfsObjectId[], signalArg?: AbortSignal): Promise<Map<string, TBatchEntry>> {
+    const response = await this.#client.request(this.#batchUrl, {
+      signal: signalArg,
+      mediaType: lfsMediaType,
+      json: { operation: operationArg, transfers: ['basic'], objects: objectsArg.map((objectArg) => ({ oid: objectArg.oid, size: objectArg.size })) },
+    });
+    // `expires_in` counts from the moment the answer arrived.
+    const receivedAt = Date.now();
+    const body = validation.record(response.body);
+    if (body.transfer !== undefined && body.transfer !== null && body.transfer !== 'basic') throw new validation.ForgeInventoryError('unsupported-lfs-transfer');
+    if (!Array.isArray(body.objects) || body.objects.length !== objectsArg.length) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+    const requested = new Map(objectsArg.map((objectArg) => [objectArg.oid, objectArg.size]));
+    const entries = new Map<string, TBatchEntry>();
+    for (const value of body.objects) {
+      const object = validation.record(value);
+      const size = typeof object.oid === 'string' ? requested.get(object.oid) : undefined;
+      if (size === undefined || object.size !== size || entries.has(object.oid as string)) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+      let errorCode: number | null = null;
+      if (object.error !== undefined && object.error !== null) {
+        const code = validation.record(object.error).code;
+        if (!Number.isSafeInteger(code) || (code as number) < 100 || (code as number) > 599) throw new validation.ForgeInventoryError('invalid-lfs-batch');
+        errorCode = code as number;
+      }
+      const actions: Record<string, ILfsAction> = {};
+      if (errorCode === null && object.actions !== undefined && object.actions !== null) {
+        for (const [name, actionValue] of Object.entries(validation.record(object.actions))) {
+          if (name === 'upload' || name === 'verify' || name === 'download') actions[name] = this.#action(actionValue, receivedAt);
+        }
+      }
+      entries.set(object.oid as string, { oid: object.oid as string, size, actions, errorCode });
+    }
+    return entries;
+  }
+
+  /**
+   * An action's href and headers. The href must pass the URL policy and keep
+   * the endpoint's protocol, so a server cannot move a transfer to plain HTTP
+   * or, from a loopback endpoint, to a name; its headers may not set
+   * connection-level fields.
+   */
+  #action(valueArg: unknown, receivedAtArg: number): ILfsAction {
+    const action = validation.record(valueArg);
+    if (typeof action.href !== 'string' || action.href.length > maxHrefLength) throw new validation.ForgeInventoryError('invalid-lfs-action');
+    let href: URL;
+    try {
+      href = new URL(action.href);
+    } catch {
+      throw new validation.ForgeInventoryError('invalid-lfs-action');
+    }
+    if (!isAllowedLfsUrl(href) || href.protocol !== this.#endpoint.protocol) throw new validation.ForgeInventoryError('unsafe-lfs-href');
+    const headers: Record<string, string> = {};
+    if (action.header !== undefined && action.header !== null) {
+      const entries = Object.entries(validation.record(action.header));
+      if (entries.length > maxActionHeaders) throw new validation.ForgeInventoryError('invalid-lfs-action');
+      for (const [name, value] of entries) {
+        const key = name.toLowerCase();
+        if (!headerNamePattern.test(name) || reservedHeaderNames.has(key) || key in headers ||
+          typeof value !== 'string' || value.length > maxHeaderValueLength || /[\u0000\r\n]/.test(value)) {
+          throw new validation.ForgeInventoryError('invalid-lfs-action');
+        }
+        headers[key] = value;
+      }
+    }
+    return { href, headers, expiresAt: actionExpiry(action, receivedAtArg) };
+  }
+
+  /** Whether every named action the entry carries stays valid for at least the expiry margin. */
+  #current(entryArg: TBatchEntry, namesArg: TLfsActionName[]): boolean {
+    const deadline = Date.now() + this.#limits.expiryMarginMs;
+    return namesArg.every((nameArg) => {
+      const expiresAt = entryArg.actions[nameArg]?.expiresAt ?? null;
+      return expiresAt === null || expiresAt > deadline;
+    });
+  }
+
+  /**
+   * Asks for one object's actions again, once. An answer whose named actions
+   * would again expire within the margin fails with `lfs-action-expired`.
+   */
+  async #rebatch(operationArg: 'upload' | 'download', objectArg: ILfsObjectId, namesArg: TLfsActionName[], signalArg?: AbortSignal): Promise<TBatchEntry> {
+    const entry = (await this.#batch(operationArg, [{ oid: objectArg.oid, size: objectArg.size }], signalArg)).get(objectArg.oid)!;
+    if (entry.errorCode === null && !this.#current(entry, namesArg)) throw new validation.ForgeInventoryError('lfs-action-expired');
+    return entry;
+  }
+
+  async #put(objectArg: ILfsUploadObject, actionArg: ILfsAction, signalArg?: AbortSignal): Promise<void> {
+    const transfer = this.#transfer(signalArg);
+    let source: AsyncIterable<Uint8Array> | undefined;
+    try {
+      try {
+        source = await transfer.run(async () => objectArg.open(transfer.signal));
+      } catch (error) {
+        throw transfer.failure(error, 'lfs-source-failed');
+      }
+      const response = await transfer.run(() => transport.sendNodeRequest(actionArg.href, {
+        method: 'PUT',
+        headers: { ...actionArg.headers, 'content-type': 'application/octet-stream', 'content-length': String(objectArg.size) },
+        body: verifiedChunks(transfer.watch(source!), objectArg.oid, objectArg.size),
+        signal: transfer.signal,
+        agents: this.#agents,
+      }));
+      if (response.status < 200 || response.status > 299) {
+        await discardBody(response.body);
+        throw new validation.ForgeInventoryError(`http-${response.status}`);
+      }
+      // A server that answers before the body is complete has not stored the object.
+      await transfer.run(() => response.sent);
+      await transfer.run(() => discardBody(response.body));
+    } catch (error) {
+      throw transfer.failure(error, 'lfs-upload-failed');
+    } finally {
+      transfer.end();
+      if (source instanceof plugins.stream.Readable) source.destroy();
+    }
+  }
+
+  async #verify(objectArg: ILfsObjectId, actionArg: ILfsAction, signalArg?: AbortSignal): Promise<void> {
+    const transfer = this.#transfer(signalArg, this.#limits.requestTimeoutMs);
+    try {
+      const response = await transfer.run(() => transport.sendNodeRequest(actionArg.href, {
+        method: 'POST',
+        headers: { ...actionArg.headers, accept: lfsMediaType, 'content-type': lfsMediaType },
+        body: new TextEncoder().encode(JSON.stringify({ oid: objectArg.oid, size: objectArg.size })),
+        signal: transfer.signal,
+        agents: this.#agents,
+      }));
+      await transfer.run(() => discardBody(response.body));
+      if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
+    } catch (error) {
+      throw transfer.failure(error, 'lfs-verify-failed');
+    } finally {
+      transfer.end();
+    }
+  }
+
+  /**
+   * The bounds of one transfer: the caller's signal, a wall-clock limit and an
+   * idle limit that `watch` re-arms on every chunk. Whichever ends it first
+   * decides the failure code.
+   */
+  #transfer(signalArg: AbortSignal | undefined, limitMsArg = this.#limits.transferTimeoutMs) {
+    const controller = new AbortController();
+    let reason: string | null = null;
+    const stop = (reasonArg: string) => {
+      reason ??= reasonArg;
+      controller.abort();
+    };
+    const abort = () => stop('request-aborted');
+    if (signalArg?.aborted) abort();
+    signalArg?.addEventListener('abort', abort, { once: true });
+    const deadline = setTimeout(() => stop('lfs-transfer-timed-out'), limitMsArg);
+    let idle: ReturnType<typeof setTimeout> | undefined;
+    const rearm = () => {
+      clearTimeout(idle);
+      if (!controller.signal.aborted) idle = setTimeout(() => stop('lfs-transfer-timed-out'), this.#limits.requestTimeoutMs);
+    };
+    rearm();
+    const end = () => {
+      clearTimeout(deadline);
+      clearTimeout(idle);
+      signalArg?.removeEventListener('abort', abort);
+      stop('transfer-ended');
+    };
+    const failure = (errorArg: unknown, fallbackArg: string): validation.ForgeInventoryError => {
+      if (reason !== null && reason !== 'transfer-ended') return new validation.ForgeInventoryError(reason);
+      return errorArg instanceof validation.ForgeInventoryError ? errorArg : new validation.ForgeInventoryError(fallbackArg);
+    };
+    return {
+      signal: controller.signal,
+      end,
+      failure,
+      /** Runs one step of the transfer; it rejects as soon as the transfer ends, even if the step does not. */
+      run: async <T>(stepArg: () => Promise<T>): Promise<T> => {
+        if (controller.signal.aborted) throw failure(undefined, 'request-aborted');
+        let onAbort!: () => void;
+        const aborted = new Promise<never>((_resolve, reject) => {
+          onAbort = () => reject(failure(undefined, 'request-aborted'));
+          controller.signal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+          return await Promise.race([stepArg(), aborted]);
+        } finally {
+          controller.signal.removeEventListener('abort', onAbort);
+        }
+      },
+      /** Passes chunks on and re-arms the idle limit on each one. */
+      watch: async function* (sourceArg: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined> {
+        for await (const chunk of sourceArg) {
+          if (controller.signal.aborted) throw failure(undefined, 'lfs-transfer-failed');
+          rearm();
+          yield chunk;
+        }
+      },
+    };
+  }
+}

package/ts/forgeinventory.client.ts

@@ -21,6 +21,10 @@ export interface IForgeRequestOptions {
   maxResponseBytes?: number;
   /** Additional request headers, such as a provider's impersonation header. */
   headers?: Record<string, string>;
+  /** JSON media type sent as `accept` and required of the response; defaults to `application/json`. */
+  mediaType?: string;
+  /** Sends this value as a JSON body of `mediaType` in a POST instead of a GET, for reads that take a request body. */
+  json?: unknown;
 }
 
 export interface IForgeJsonResponse {
@@ -29,8 +33,9 @@ export interface IForgeJsonResponse {
 }
 
 /**
- * One bounded, credential-scoped JSON GET at a time: a per-request deadline, a
- * response-size budget and a strict JSON content type. Failures surface as
+ * One bounded, credential-scoped JSON read at a time, a GET or a POST with a
+ * JSON body: a per-request deadline, a response-size budget and a strict JSON
+ * content type. Failures surface as
  * `ForgeInventoryError` codes that never contain bodies, URLs or credentials.
  */
 export class ForgeRequestClient {
@@ -56,12 +61,14 @@ export class ForgeRequestClient {
     let bodyChunks: AsyncIterator<Uint8Array> | undefined;
     try {
       this.#metrics.requests++;
-      const headers = { accept: 'application/json', ...requestArg.headers, ...this.#options.headers };
-      const response = await this.#options.transport(url, headers, controller.signal);
+      const mediaType = requestArg.mediaType ?? 'application/json';
+      const requestBody = requestArg.json === undefined ? undefined : new TextEncoder().encode(JSON.stringify(requestArg.json));
+      const headers = { accept: mediaType, ...(requestBody ? { 'content-type': mediaType } : {}), ...requestArg.headers, ...this.#options.headers };
+      const response = await this.#options.transport(url, headers, controller.signal, requestBody);
       bodyChunks = response.body?.[Symbol.asyncIterator]();
       if (response.status === 429) this.#metrics.rateLimitedRequests++;
       if (response.status !== 200) throw new validation.ForgeInventoryError(`http-${response.status}`);
-      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json' || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
+      if (response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== mediaType || !bodyChunks) throw new validation.ForgeInventoryError('invalid-content-type');
       const chunks: Uint8Array[] = [];
       let bytes = 0;
       while (true) {