@pipelex/sdk 0.47.0 → 0.48.0

package/dist/method-trees.d.ts

@@ -1,41 +1,91 @@
 /**
- * A saved method's tree on the client side (see `docs/method-trees.md`): the source a save reads a
- * tree from, how that tree becomes the `files` map a save sends, inline or by hash, the blob routes
- * that let a large tree travel by hash (mthds/docs/spec/protocol.md, "Sending files by hash"), the
- * upload of a blob the platform lacks, and the writing of a saved tree to disk.
+ * A method's tree on the client side (see `docs/method-trees.md`): the forms a caller gives a
+ * method's tree in, the listing of a directory through the `mthds` package's own lister, how a
+ * tree becomes the `files` map a request sends, inline or by hash, the blob routes that let a
+ * large tree travel by hash (mthds/docs/spec/protocol.md, "Sending files by hash"), the upload of
+ * a blob the receiver lacks, and the writing of a saved tree to disk.
  *
- * The tree-sending part mirrors the `mthds` npm package's own helpers, which its published
- * `mthds/protocol` subpath does not export yet. This SDK imports `mthds` through that subpath alone,
- * so it carries this copy, held to the same rule: the same inline threshold, the same text-or-Base64
- * choice per file, and each file added as an own property. It needs no Node built-in: SHA-256 is Web
- * Crypto's, and Base64 is written here. Only `writeMethodTreeTo` needs Node, which it loads when
- * called.
- */
-import type { FileEntry, MethodFiles } from "mthds/protocol";
-import { type MethodFileTransferCode } from "./errors.js";
+ * The wire types (`MethodTreeSource`, `BlobRef`, `MissingBlob` and the rest) are the standard's,
+ * imported from `mthds/protocol`. A directory is listed by `mthds`'s `listMethodTree`, the
+ * standard's lister with its membership rule, which this module loads by a dynamic import when a
+ * directory is given, so the SDK's static import graph keeps no Node built-in. The choice between
+ * inline and by hash follows `mthds`'s `MthdsApiClient` rule exactly, but its helpers are not
+ * exported on a subpath free of Node built-ins, so this module carries its own copy of them: the
+ * same threshold, the same weighing of the inline map, the same text-or-Base64 choice per file.
+ * SHA-256 is Web Crypto's, and Base64 is written here. Only `writeMethodTreeTo` and
+ * `listDirectoryTree` need Node, which each loads when called.
+ */
+import type { BlobRef, FileEntry, MethodFiles, MethodTreeSource, MethodTreeSourceFile, MissingBlob } from "mthds/protocol";
+import { RequestArgumentError, type MethodFileTransferCode } from "./errors.js";
 import type { SavedMethodFile } from "./product-models.js";
-/** A file of a {@link MethodTreeSource}. */
-export interface MethodTreeSourceFile {
-    /** Its tree path. */
-    readonly path: string;
-    /** Its length in bytes. */
-    readonly size: number;
-    /** The SHA-256 of its bytes, in lowercase hexadecimal. */
-    readonly sha256: string;
+/**
+ * A method's tree, given in exactly one of four forms. Every route that takes a method's tree
+ * takes these: the runs (`execute`, `start`, `startAndWaitForResult`), `validate`, the crate
+ * routes (`resolve`, `codegen`, `pipeIo`), `prepareInputs` and the saves (`createMethod`,
+ * `writeDraft`).
+ *
+ * - `directory`, a path on disk, listed by the `mthds` package's lister under the MTHDS
+ *   standard's membership rule: rooted at the nearest `METHODS.toml` at or above it, else at the
+ *   directory itself, every file the rule keeps, a run's inputs file (`inputs.json`,
+ *   `inputs.toml`) never among them, under the limits the deployment announces. A `.mthds` file
+ *   named alone is a one-file tree unless a `METHODS.toml` above it roots a larger one. Node only.
+ * - `contents`, each file's bytes or its text by tree path, a map held in memory.
+ * - `tree`, a listed source such as the `MethodTree` `listMethodTree` returns.
+ * - `files`, the protocol's map of file entries, sent as given.
+ *
+ * A `directory`, `contents` or `tree` travels inline when small and by hash otherwise, after the
+ * files the receiver lacks are uploaded (`docs/method-trees.md`).
+ */
+export interface MethodTreeForms {
+    /** The method's directory, listed by the standard's lister. Node only. */
+    directory?: string | null;
+    /** Each file's bytes or text, by tree path. */
+    contents?: Readonly<Record<string, Uint8Array | string>> | null;
+    /** A listed tree, such as the `MethodTree` `listMethodTree` returns. */
+    tree?: MethodTreeSource | null;
+    /** The protocol's map of file entries, sent as given. */
+    files?: MethodFiles | null;
 }
 /**
- * A method tree a save reads from: its files, its digest, and a way to read each file's bytes. The
- * `MethodTree` the `mthds` package's `listMethodTree` returns is one, so a tree listed from a
- * directory, under the limits `methodTreeLimits` reports, is passed as it is.
- */
-export interface MethodTreeSource {
-    /** Every file of the tree, each tree path once. */
-    readonly files: readonly MethodTreeSourceFile[];
-    /** The tree digest, `sha256:` and 64 lowercase hexadecimal digits. */
-    readonly digest: string;
-    /** The bytes of the file at `treePath`, which must hash to the SHA-256 the listing gives it. */
-    readFile(treePath: string): Promise<Uint8Array>;
+ * A method's tree in exactly one of the four forms of `MethodTreeForms`, each pinning the other
+ * three to `never`, so giving two is a compile error. The calls that take the tree beside a
+ * selector it excludes (`validate`, `prepareInputs`) take it in this shape.
+ */
+export type MethodTreeForm = {
+    directory: string;
+    contents?: never;
+    tree?: never;
+    files?: never;
+} | {
+    contents: Readonly<Record<string, Uint8Array | string>>;
+    directory?: never;
+    tree?: never;
+    files?: never;
+} | {
+    tree: MethodTreeSource;
+    directory?: never;
+    contents?: never;
+    files?: never;
+} | {
+    files: MethodFiles;
+    directory?: never;
+    contents?: never;
+    tree?: never;
+};
+/** The four forms of the tree, each pinned to `never`, for a shape that takes no tree. */
+export interface NoMethodTree {
+    directory?: never;
+    contents?: never;
+    tree?: never;
+    files?: never;
 }
+/**
+ * What keeps `value` from being a listed tree as far as the client reads one before any request,
+ * an object with a `files` list, a `digest` string and a `readFile` function, in words for a
+ * refusal ("a list", "an object without them", or its type); `undefined` when it is one. A tree
+ * holding no file passes here, and is refused where it would be sent.
+ */
+export declare function treeShapeFault(value: unknown): string | undefined;
 /**
  * The limits a deployment holds a tree to, in the shape the `mthds` package's `listMethodTree`
  * takes as its `limits` option, so a lister stops at the first breach before hashing anything. A
@@ -49,50 +99,75 @@ export interface MethodTreeLimits {
     /** The largest all the files together may be, in bytes. */
     readonly maxTotalSize?: number;
 }
-/** A blob a sender is about to send by hash, named by its SHA-256 and its size. */
-export interface BlobRef {
-    sha256: string;
-    size: number;
-}
 /**
- * Body of `POST /v1/blobs/missing`: the blobs a sender is about to send by hash, each hash listed
- * once, and the digest of the tree they make up, which lets a platform that holds that tree whole
- * answer at once.
+ * Every limit a deployment's handshake announces for a tree under `limits.method_tree`, in bytes
+ * for the sizes, named as `mthds`'s `AnnouncedTreeLimits` names them. A limit not announced is
+ * absent.
  */
-export interface MissingBlobsRequest {
-    blobs: BlobRef[];
-    digest?: string;
+export interface AnnouncedTreeLimits {
+    /** The files of one tree. */
+    readonly maxFiles?: number;
+    /** One file of it. */
+    readonly maxFileBytes?: number;
+    /** All its files together. */
+    readonly maxTotalBytes?: number;
+    /** The bytes a request carries inline for its tree: its text and Base64 entries. */
+    readonly maxInlineBytes?: number;
 }
 /**
- * Where to upload one blob: its bytes as the whole body of a request with this method to this URL,
- * carrying exactly these headers. The URL is signed by storage and is a bearer credential.
+ * The heaviest inline map, in bytes of its JSON serialization in UTF-8, that a request or a save
+ * sends inline to a deployment keeping a blob store, when the deployment announces no lower inline
+ * limit. Below it a tree is cheaper to send whole than to check and upload; above it every file
+ * travels by hash. `mthds`'s clients use the same threshold.
  */
-export interface UploadTarget {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
-    [extension: string]: unknown;
-}
-/** A blob the platform lacks, with where to upload it. */
-export interface MissingBlob {
-    sha256: string;
-    size: number;
-    upload: UploadTarget;
-    [extension: string]: unknown;
+export declare const INLINE_TREE_MAX_BYTES: number;
+/**
+ * How long a version handshake is trusted before the client asks again, `mthds`'s
+ * `HANDSHAKE_TTL_MS`: a deployment's blob store and tree limits change only with a deploy, so a
+ * client asks once per this span rather than before every request, and drops the answer sooner
+ * when a refusal shows it stale (`POST /v1/blobs/missing` gone, a tree refused as too large).
+ */
+export declare const HANDSHAKE_TTL_MS: number;
+/** How many blobs a request or a save uploads at once, and how many files `writeMethodTree` downloads at once. */
+export declare const MAX_CONCURRENT_TRANSFERS = 8;
+/**
+ * What a tree is prepared for, as its refusals and its failed uploads say it: a save of a method, or
+ * a request that runs or reads one (a run, `validate`, `resolve`, `codegen`, `pipeIo`).
+ */
+export interface TreeSending {
+    /** What did not happen because an upload failed, ending its message. */
+    readonly unsent: string;
+    /** What to give instead of a tree holding no file, when there is something. */
+    readonly emptyRemedy?: string;
 }
-/** The `200` answer of `POST /v1/blobs/missing`; an empty `missing` means nothing to upload. */
-export interface MissingBlobsResult {
-    missing: MissingBlob[];
-    [extension: string]: unknown;
+/** A save's: a tree holding no file is given as `files: null`, which empties a draft. */
+export declare const SAVE_SENDING: TreeSending;
+/** A request's: a method has at least one file, so there is nothing to give instead. */
+export declare const REQUEST_SENDING: TreeSending;
+/** How a request prepares its tree, beyond what a save needs. */
+export interface TreeSendOptions {
+    /**
+     * Read before each step the tree costs: each file read, the version handshake's use, the blob
+     * route and each upload. Once it has aborted, none of them starts and the abort is thrown; a
+     * request already sent runs to its end.
+     */
+    readonly signal?: AbortSignal | undefined;
+    /**
+     * The request's `read_scope`, under which the blob route is asked which blobs are missing, so
+     * the blobs are uploaded into the store the request's hash entries are read from. The upload
+     * targets the route names are signed for that scope already.
+     */
+    readonly readScope?: string | undefined;
 }
 /**
- * The heaviest inline map, in bytes of its JSON serialization in UTF-8, that a save sends inline
- * to a deployment keeping a blob store. Below it a tree is cheaper to send whole than to check and
- * upload; above it every file travels by hash. `mthds`'s clients use the same threshold.
+ * A map a crate request was given, or `undefined` when it selects or sends nothing: absent, `null`,
+ * or a plain object holding no key, the empty-as-absent rule of the run options and of the Python
+ * SDK. Any other value is kept as given, so the server refuses a `files` that is not a map as the
+ * shape it is rather than reading it as absent.
  */
-export declare const INLINE_TREE_MAX_BYTES: number;
-/** How many blobs a save uploads at once, and how many files `writeMethodTree` downloads at once. */
-export declare const MAX_CONCURRENT_TRANSFERS = 8;
+export declare function presentMap<T>(value: T | null | undefined): T | undefined;
+/** The refusal of a tree holding no file, `call` naming the caller's method. */
+export declare function emptyTreeRefusal(call: string, what: string, sending: TreeSending): RequestArgumentError;
 /** Whether a version handshake declares a blob store (`blob_store: true`). */
 export declare function declaresBlobStore(version: object): boolean;
 /**
@@ -100,13 +175,30 @@ export declare function declaresBlobStore(version: object): boolean;
  * positive safe integer is left out rather than trusted, and a limit not announced is absent, so a
  * bare runner, which announces none, yields no limit.
  */
-export declare function announcedTreeLimits(version: object): MethodTreeLimits;
+export declare function announcedTreeLimits(version: object): AnnouncedTreeLimits;
+/** The announced limits as the lister takes them, so it stops at the first breach before hashing. */
+export declare function listerLimitsOf(announced: AnnouncedTreeLimits): MethodTreeLimits;
+/**
+ * The inline threshold a tree is held to against a receiver keeping a blob store: the lower of
+ * `INLINE_TREE_MAX_BYTES` and the inline limit the receiver announces, as `mthds`'s
+ * `MthdsApiClient` reads it.
+ */
+export declare function inlineThreshold(announced: AnnouncedTreeLimits): number;
 /** What an inline map spends in a request: its JSON serialization with no whitespace, in UTF-8. */
 export declare function inlineMapBytes(files: MethodFiles): number;
 /** The total of a tree's file sizes, in bytes. */
 export declare function treeTotalSize(tree: MethodTreeSource): number;
-/** Every file's bytes, by tree path, each read and checked by the tree, one file at a time. */
-export declare function readTreeBytes(tree: MethodTreeSource): Promise<Map<string, Uint8Array>>;
+/**
+ * Every file's bytes, by tree path, each read and checked by the tree, one file at a time. `signal`
+ * is read before each file: once it has aborted, no further file is read and the abort is thrown.
+ */
+export declare function readTreeBytes(tree: MethodTreeSource, signal?: AbortSignal): Promise<Map<string, Uint8Array>>;
+/**
+ * Every file's bytes, by tree path, read into `read`: a file already there is not read again, so
+ * a request that weighs a tree and then uploads from it, or prepares it a second time, reads each
+ * file once. `signal` is read before each file read, as `readTreeBytes` reads it.
+ */
+export declare function readTreeBytesInto(tree: MethodTreeSource, read: Map<string, Uint8Array>, signal?: AbortSignal): Promise<Map<string, Uint8Array>>;
 /** The whole tree as inline entries, from bytes already read by `readTreeBytes`. */
 export declare function inlineFilesOf(tree: MethodTreeSource, bytesByPath: ReadonlyMap<string, Uint8Array>): MethodFiles;
 /** The whole tree as hash entries, which the platform resolves in the organization's blobs. */
@@ -121,15 +213,56 @@ export declare function fileByBlob(tree: MethodTreeSource): Map<string, MethodTr
  * early, and once they have settled the first failure is thrown.
  */
 export declare function forEachConcurrently<T>(items: readonly T[], limit: number, task: (item: T, signal: AbortSignal) => Promise<void>): Promise<void>;
+/**
+ * Whether an answer refuses a tree as past one of the receiver's limits, as `mthds`'s
+ * `MthdsApiClient` reads one: a `422` whose problem is the core registry's
+ * `method.package_invalid` carrying its numeric `limit` parameter, the hosted platform's
+ * `method_tree_too_large` code, or pipelex-api's `MethodTreeTooLarge` error type.
+ */
+export declare function isMethodTreeTooLarge(status: number, body: string): boolean;
+/**
+ * The blobs a `422` lists as missing, as `mthds`'s `MthdsApiClient` reads them: the
+ * `params.missing_blobs` of a problem coded `request.blobs_missing`, or `undefined` when the
+ * answer is no such problem or the list holds anything but strings.
+ */
+export declare function missingBlobsOf(status: number, body: string): string[] | undefined;
+/**
+ * A signal that aborts when either does, with the reason of the first to abort, and `dispose`,
+ * which detaches it from both once it is no longer needed, so a long-lived signal does not keep
+ * a listener per call. `second` absent gives `first` itself. Built by hand rather than with
+ * `AbortSignal.any`, which older browsers lack.
+ */
+export declare function eitherSignal(first: AbortSignal, second: AbortSignal | undefined): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
 /**
  * The tree whose files are `contents`, each file's bytes or its text by tree path, a text encoded
  * in UTF-8. The keys are sent as they are, and the platform refuses one that is not a tree path,
  * with the `422` `invalid_method_files` naming it. `call` names the caller's method in a refusal.
  *
  * Throws `RequestArgumentError` for `contents` holding no file, for a value that is neither a
- * string nor bytes, and for a text holding a lone surrogate, which no file can hold.
+ * string nor bytes, and for a text holding a lone surrogate, which no file can hold. `sending` says
+ * what the tree is for, which the refusal of an empty one names.
+ */
+export declare function contentsTreeSource(contents: Readonly<Record<string, Uint8Array | string>>, call: string, sending: TreeSending): Promise<MethodTreeSource>;
+/** A tree listed from the file system: its files, and the absolute path of its root. */
+export interface ListedMethodTree extends MethodTreeSource {
+    /** The absolute path of the root, or `null` for the one-file tree of a `.mthds` file alone. */
+    readonly root: string | null;
+}
+/**
+ * The tree of the method directory `directory`, listed by the `mthds` package's `listMethodTree`
+ * under the MTHDS standard's membership rule and Manifest Discovery, stopping at the first of
+ * `limits` it breaches, before any file is hashed. A run's inputs file is never in it. Node only:
+ * `mthds`'s root entry, which reads the file system, is loaded by this call alone.
+ *
+ * Throws `RequestArgumentError` naming `call` when the directory cannot be listed as a tree, the
+ * `mthds` package's `MethodTreeError` as its `cause` with its `code` (`not_found`,
+ * `symbolic_link`, `limit_exceeded`, `empty_tree` and the rest): a path that names nothing, a
+ * symbolic link or a special file in the tree, a tree past one of `limits`, a tree holding no file.
  */
-export declare function contentsTreeSource(contents: Readonly<Record<string, Uint8Array | string>>, call: string): Promise<MethodTreeSource>;
+export declare function listDirectoryTree(directory: string, limits: MethodTreeLimits, call: string): Promise<ListedMethodTree>;
 /**
  * The tree digest of a tree's files: `sha256:` and the SHA-256 of its listing, one line
  * `<sha256>  <path>` per file, in tree path order.
@@ -162,11 +295,13 @@ export declare function encodeBase64(bytes: Uint8Array): string;
  *
  * Throws `MethodFileTransferError` (`operation` `upload`) when storage gives no answer within
  * `timeoutMs` or answers any other non-2xx; neither its message nor any member carries the URL,
- * nor storage's error body, which can echo the signed request.
+ * nor storage's error body, which can echo the signed request. Its message ends with what did not
+ * happen because of it, `options.unsent`.
  */
 export declare function uploadBlob(blob: MissingBlob, bytes: Uint8Array, options: {
     timeoutMs: number;
     signal?: AbortSignal;
+    unsent: string;
 }): Promise<void>;
 /**
  * The code of a transfer storage answered with a non-2xx `status`: `storage_error` for one the