@pipelex/sdk 0.46.0 → 0.47.0

package/dist/method-trees.js

@@ -0,0 +1,689 @@
+/**
+ * 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.
+ *
+ * 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 { fallbackVerdict } from "./error-verdicts.js";
+import { MethodFileTransferError, RequestArgumentError, } from "./errors.js";
+// ── Choosing how a tree travels ──────────────────────────────────────
+/**
+ * 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.
+ */
+export const INLINE_TREE_MAX_BYTES = 256 * 1024;
+/** How many blobs a save uploads at once, and how many files `writeMethodTree` downloads at once. */
+export const MAX_CONCURRENT_TRANSFERS = 8;
+/** Whether a version handshake declares a blob store (`blob_store: true`). */
+export function declaresBlobStore(version) {
+    return version.blob_store === true;
+}
+/**
+ * The tree limits a version handshake announces under `limits.method_tree`. A value that is not a
+ * 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 function announcedTreeLimits(version) {
+    const limits = objectMember(version, "limits");
+    const tree = limits === undefined ? undefined : objectMember(limits, "method_tree");
+    if (tree === undefined)
+        return {};
+    const read = (name) => {
+        const value = tree[name];
+        return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+            ? value
+            : undefined;
+    };
+    const announced = {};
+    const maxFileCount = read("max_files");
+    const maxFileSize = read("max_file_bytes");
+    const maxTotalSize = read("max_total_bytes");
+    if (maxFileCount !== undefined)
+        announced.maxFileCount = maxFileCount;
+    if (maxFileSize !== undefined)
+        announced.maxFileSize = maxFileSize;
+    if (maxTotalSize !== undefined)
+        announced.maxTotalSize = maxTotalSize;
+    return announced;
+}
+/** What an inline map spends in a request: its JSON serialization with no whitespace, in UTF-8. */
+export function inlineMapBytes(files) {
+    return UTF8_ENCODER.encode(JSON.stringify(files)).length;
+}
+/** The total of a tree's file sizes, in bytes. */
+export function treeTotalSize(tree) {
+    return tree.files.reduce((total, file) => total + file.size, 0);
+}
+/** Every file's bytes, by tree path, each read and checked by the tree, one file at a time. */
+export async function readTreeBytes(tree) {
+    const bytes = new Map();
+    for (const file of tree.files) {
+        bytes.set(file.path, await tree.readFile(file.path));
+    }
+    return bytes;
+}
+/** The whole tree as inline entries, from bytes already read by `readTreeBytes`. */
+export function inlineFilesOf(tree, bytesByPath) {
+    const files = {};
+    for (const file of tree.files) {
+        const bytes = bytesByPath.get(file.path);
+        if (bytes === undefined)
+            throw new Error(`No bytes were read for '${file.path}'.`);
+        defineFileEntry(files, file.path, inlineFileEntry(bytes));
+    }
+    return files;
+}
+/** The whole tree as hash entries, which the platform resolves in the organization's blobs. */
+export function hashMethodFiles(tree) {
+    const files = {};
+    for (const file of tree.files) {
+        defineFileEntry(files, file.path, { sha256: file.sha256, size: file.size });
+    }
+    return files;
+}
+/** Each blob of the tree once, in the tree's order: files with the same bytes share one blob. */
+export function uniqueBlobs(tree) {
+    const seen = new Set();
+    const blobs = [];
+    for (const file of tree.files) {
+        if (seen.has(file.sha256))
+            continue;
+        seen.add(file.sha256);
+        blobs.push({ sha256: file.sha256, size: file.size });
+    }
+    return blobs;
+}
+/** A file of the tree holding each blob, so a missing blob's bytes can be read and uploaded. */
+export function fileByBlob(tree) {
+    const files = new Map();
+    for (const file of tree.files) {
+        if (!files.has(file.sha256))
+            files.set(file.sha256, file);
+    }
+    return files;
+}
+/**
+ * Run `task` over `items`, at most `limit` at a time. The first task to fail stops the run: no
+ * queued item is handed out after it, `signal` is aborted so the tasks still in flight can stop
+ * early, and once they have settled the first failure is thrown.
+ */
+export async function forEachConcurrently(items, limit, task) {
+    const controller = new AbortController();
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        while (failure === undefined && next < items.length) {
+            const item = items[next];
+            next += 1;
+            try {
+                await task(item, controller.signal);
+            }
+            catch (error) {
+                if (failure === undefined) {
+                    failure = { error };
+                    controller.abort(error);
+                }
+                return;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    if (failure !== undefined)
+        throw failure.error;
+}
+// ── A tree from bytes in memory ──────────────────────────────────────
+/**
+ * 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.
+ */
+export async function contentsTreeSource(contents, call) {
+    const bytesByPath = new Map();
+    for (const [treePath, content] of Object.entries(contents)) {
+        if (typeof content === "string") {
+            if (LONE_SURROGATE.test(content)) {
+                throw new RequestArgumentError(`${call}() got contents['${treePath}'] holding a lone surrogate, which is no text a file ` +
+                    "can hold: give its bytes instead.");
+            }
+            bytesByPath.set(treePath, UTF8_ENCODER.encode(content));
+        }
+        else if (content instanceof Uint8Array) {
+            bytesByPath.set(treePath, content);
+        }
+        else {
+            throw new RequestArgumentError(`${call}() got contents['${treePath}'] that is neither a string nor a Uint8Array.`);
+        }
+    }
+    if (bytesByPath.size === 0) {
+        throw new RequestArgumentError(`${call}() got contents holding no file, and a method tree holds at least one; give ` +
+            "files: null for an empty draft.");
+    }
+    const files = [];
+    for (const [treePath, bytes] of bytesByPath) {
+        files.push({ path: treePath, size: bytes.length, sha256: await sha256Hex(bytes) });
+    }
+    files.sort((left, right) => compareUtf8(left.path, right.path));
+    const digest = await treeDigestOf(files);
+    return {
+        files,
+        digest,
+        readFile: async (treePath) => {
+            const bytes = bytesByPath.get(treePath);
+            if (bytes === undefined)
+                throw new Error(`The tree holds no file '${treePath}'.`);
+            return bytes;
+        },
+    };
+}
+/**
+ * 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.
+ */
+export async function treeDigestOf(files) {
+    const sorted = [...files].sort((left, right) => compareUtf8(left.path, right.path));
+    const listing = sorted.map((file) => `${file.sha256}  ${file.path}\n`).join("");
+    return `sha256:${await sha256Hex(UTF8_ENCODER.encode(listing))}`;
+}
+/** The SHA-256 of `bytes`, in lowercase hexadecimal, by Web Crypto. */
+export async function sha256Hex(bytes) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Compare two strings byte for byte on their UTF-8 encoding, the order tree paths are sorted in.
+ * JavaScript's own string order compares UTF-16 code units, which puts a character above U+FFFF
+ * before one between U+E000 and U+FFFF, where UTF-8 puts it after.
+ */
+export function compareUtf8(left, right) {
+    if (left === right)
+        return 0;
+    const leftBytes = UTF8_ENCODER.encode(left);
+    const rightBytes = UTF8_ENCODER.encode(right);
+    const shared = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < shared; index += 1) {
+        const difference = leftBytes[index] - rightBytes[index];
+        if (difference !== 0)
+            return difference;
+    }
+    return leftBytes.length - rightBytes.length;
+}
+// ── File entries ─────────────────────────────────────────────────────
+/** The entry a file travels as inline: its text when its bytes are UTF-8, its Base64 otherwise. */
+export function inlineFileEntry(bytes) {
+    const text = utf8TextOf(bytes);
+    return text ?? { base64: encodeBase64(bytes) };
+}
+/**
+ * Add a file to a map of file entries as an own property, since assigning to a key such as
+ * `__proto__`, a tree path like any other, would set the object's prototype instead of adding the
+ * file.
+ */
+export function defineFileEntry(files, treePath, entry) {
+    Object.defineProperty(files, treePath, {
+        value: entry,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+/** The bytes as text when they are UTF-8, or `null` when they are not. */
+function utf8TextOf(bytes) {
+    try {
+        return STRICT_UTF8.decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+/** Canonical padded standard Base64 (RFC 4648), with no line break and its pad bits zero. */
+export function encodeBase64(bytes) {
+    const chunks = [];
+    let line = "";
+    const full = bytes.length - (bytes.length % 3);
+    for (let index = 0; index < full; index += 3) {
+        const triple = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+        line +=
+            BASE64_ALPHABET[(triple >> 18) & 63] +
+                BASE64_ALPHABET[(triple >> 12) & 63] +
+                BASE64_ALPHABET[(triple >> 6) & 63] +
+                BASE64_ALPHABET[triple & 63];
+        // Flush now and then, so a file of many megabytes is not one string grown a character at a time.
+        if (line.length >= 8192) {
+            chunks.push(line);
+            line = "";
+        }
+    }
+    const rest = bytes.length - full;
+    if (rest === 1) {
+        const value = bytes[full] << 16;
+        line += BASE64_ALPHABET[(value >> 18) & 63] + BASE64_ALPHABET[(value >> 12) & 63] + "==";
+    }
+    else if (rest === 2) {
+        const value = (bytes[full] << 16) | (bytes[full + 1] << 8);
+        line +=
+            BASE64_ALPHABET[(value >> 18) & 63] +
+                BASE64_ALPHABET[(value >> 12) & 63] +
+                BASE64_ALPHABET[(value >> 6) & 63] +
+                "=";
+    }
+    chunks.push(line);
+    return chunks.join("");
+}
+// ── Moving a file to and from storage ────────────────────────────────
+/**
+ * Upload one blob's bytes to the target `POST /v1/blobs/missing` named: the bytes as the whole body
+ * of a request with the target's method to its URL, carrying exactly the target's headers and no
+ * credential of the client, since the signed URL authorizes the upload itself. A `412` from a
+ * target asking for a create-only write (`If-None-Match`) means the bytes are already stored, and
+ * counts as uploaded.
+ *
+ * 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.
+ */
+export async function uploadBlob(blob, bytes, options) {
+    const { sha256, upload } = blob;
+    const host = hostOf(upload.url);
+    await storageExchange(upload.url, {
+        method: upload.method,
+        headers: { ...upload.headers },
+        body: bytes,
+    }, options, (code) => new MethodFileTransferError(`Uploading the file with SHA-256 ${sha256} to ${host} failed: no answer came back ` +
+        `(${code}), so the method was not saved.`, { operation: "upload", code: "unreachable", sha256 }), async (response) => {
+        // Storage's body is read and dropped: it can echo the signed request.
+        await response.arrayBuffer().catch(() => undefined);
+        if (response.ok || (response.status === 412 && isCreateOnly(upload.headers)))
+            return;
+        throw new MethodFileTransferError(`Uploading the file with SHA-256 ${sha256} to ${host} failed (${statusLine(response)}), ` +
+            "so the method was not saved.", {
+            operation: "upload",
+            code: methodFileTransferCodeOfStatus(response.status),
+            sha256,
+            status: response.status,
+        });
+    });
+}
+/**
+ * The code of a transfer storage answered with a non-2xx `status`: `storage_error` for one the
+ * fallback table calls retryable (`408`, `429`, a `5xx` other than `501`), `refused` otherwise.
+ */
+export function methodFileTransferCodeOfStatus(status) {
+    return fallbackVerdict(status, undefined, true).retryable ? "storage_error" : "refused";
+}
+/**
+ * Write a saved tree to disk, each file of `files` at its tree path under `destination`; see
+ * `PipelexApiClient.writeMethodTree`. Node only: the file system modules are loaded when it runs.
+ */
+export async function writeMethodTreeTo(files, destination, options) {
+    refuseUnwritableListing(files);
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const target = path.resolve(destination);
+    await refuseOccupiedDestination(fs, target);
+    const parent = path.dirname(target);
+    await fs.mkdir(parent, { recursive: true });
+    const staging = path.join(parent, `.${path.basename(target)}.${randomHex(8)}.writing`);
+    await fs.mkdir(staging);
+    let inPlace = false;
+    try {
+        await forEachConcurrently(files, MAX_CONCURRENT_TRANSFERS, async (file, signal) => {
+            const bytes = await downloadMethodFile(file, { timeoutMs: options.timeoutMs, signal });
+            const filePath = path.join(staging, ...file.path.split("/"));
+            await fs.mkdir(path.dirname(filePath), { recursive: true });
+            await fs.writeFile(filePath, bytes, { flag: "wx" });
+        });
+        // `rmdir` removes only an empty directory, so a file written there meanwhile is never lost.
+        if (await isDirectory(fs, target))
+            await fs.rmdir(target);
+        await fs.rename(staging, target);
+        inPlace = true;
+    }
+    finally {
+        if (!inPlace)
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Download one file of a listing and check its bytes against it, reading no more than its listed
+ * size and one byte. Throws `MethodFileTransferError` (`operation` `download`) when storage gives no
+ * answer, refuses the request, or serves bytes that are not the file listed.
+ */
+async function downloadMethodFile(file, options) {
+    const host = hostOf(file.url);
+    const unreachable = (code) => new MethodFileTransferError(`Downloading '${file.path}' from ${host} failed: no answer came back (${code}).`, { operation: "download", code: "unreachable", sha256: file.sha256, path: file.path });
+    const received = await storageExchange(file.url, { method: "GET" }, options, unreachable, async (response, failureCode) => {
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new MethodFileTransferError(`Downloading '${file.path}' from ${host} failed (${statusLine(response)}). A refused ` +
+                "link may have expired: read the method again for fresh links.", {
+                operation: "download",
+                code: methodFileTransferCodeOfStatus(response.status),
+                sha256: file.sha256,
+                path: file.path,
+                status: response.status,
+            });
+        }
+        try {
+            return await readAtMost(response, file.size + 1);
+        }
+        catch (cause) {
+            throw unreachable(failureCode(cause));
+        }
+    });
+    const receivedSha256 = await sha256Hex(received);
+    if (received.length !== file.size || receivedSha256 !== file.sha256) {
+        const cameBack = received.length > file.size
+            ? "more than that came back."
+            : `${received.length} bytes came back, hashing to ${receivedSha256}.`;
+        throw new MethodFileTransferError(`The bytes downloaded for '${file.path}' are not the file listed: the listing names ` +
+            `${file.size} bytes hashing to ${file.sha256}, and ${cameBack}`, { operation: "download", code: "mismatch", sha256: file.sha256, path: file.path });
+    }
+    return received;
+}
+/**
+ * One exchange with storage: send the request with no credential of the client, then `consume` the
+ * answer, the whole of it bounded by `timeoutMs` and stopped by `signal`, so a body that stalls
+ * times out as a request with no answer does. A redirect is not followed, since a signed link names
+ * its object, so it reads as a refusal. A request that gets no answer throws what `unreachable`
+ * builds from the network code alone, with no cause: the failure fetch throws can quote the URL,
+ * whose query is a credential. `consume` is handed the code that names a body read that failed:
+ * `ABORT_TIMEOUT` once the exchange's own time limit ran out, whatever error the aborted read
+ * raised, `stopped` once the caller stopped it, and the network code of the failure otherwise.
+ */
+async function storageExchange(url, init, options, unreachable, consume) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort(new DOMException("The transfer timed out.", "TimeoutError"));
+    }, options.timeoutMs);
+    const callerSignal = options.signal;
+    const onCallerAbort = () => controller.abort(callerSignal?.reason);
+    if (callerSignal?.aborted === true)
+        controller.abort(callerSignal.reason);
+    else
+        callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+    // The time limit is read before the caller's signal: an abort the timer made is a timeout, and
+    // the error the aborted request or read raises says nothing reliable about which abort it was.
+    const failureCode = (cause) => {
+        if (timedOut)
+            return "ABORT_TIMEOUT";
+        if (callerSignal?.aborted === true)
+            return "stopped";
+        return networkCodeOf(cause);
+    };
+    try {
+        let response;
+        try {
+            response = await fetch(url, {
+                ...init,
+                credentials: "omit",
+                redirect: "manual",
+                signal: controller.signal,
+            });
+        }
+        catch (cause) {
+            throw unreachable(failureCode(cause));
+        }
+        return await consume(response, failureCode);
+    }
+    finally {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener("abort", onCallerAbort);
+    }
+}
+/** A response's bytes, stopped once more than `limit` bytes came in. */
+async function readAtMost(response, limit) {
+    const body = response.body;
+    if (body === null)
+        return new Uint8Array(0);
+    const reader = body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+            length += value.length;
+            if (length >= limit)
+                break;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return bytes;
+}
+// ── A listing written to disk ────────────────────────────────────────
+/**
+ * Refuse a listing whose paths could not be written as a tree, before anything is downloaded. A
+ * platform's listing holds tree paths that never collide; the check guards the disk against any
+ * other listing a caller hands over, such as one built by hand, since a path such as `../x` would
+ * be written outside the destination. Throws `RequestArgumentError`.
+ */
+export function refuseUnwritableListing(files) {
+    const seen = new Set();
+    for (const file of files) {
+        const violation = treePathViolation(file.path);
+        if (violation !== null) {
+            throw new RequestArgumentError(`The listing holds '${file.path}', which is not a tree path (${violation}), so the tree ` +
+                "cannot be written.");
+        }
+        if (seen.has(file.path)) {
+            throw new RequestArgumentError(`The listing holds '${file.path}' twice, so the tree cannot be written.`);
+        }
+        seen.add(file.path);
+    }
+    const colliding = pathCollisions([...seen]);
+    if (colliding.length > 0) {
+        throw new RequestArgumentError("The listing holds paths that collide once case-folded, or where one names a directory of " +
+            `another: ${colliding.join(", ")}.`);
+    }
+}
+/**
+ * Why `candidate` is not a tree path, or `null` when it is one (mthds/docs/spec/method-tree.md,
+ * "Tree Paths"), the rule the `mthds` package's `treePathViolation` holds.
+ */
+export function treePathViolation(candidate) {
+    if (candidate === "")
+        return "the path is empty";
+    if (LONE_SURROGATE.test(candidate))
+        return "the path holds a code point UTF-8 cannot encode";
+    if (candidate.startsWith("/") || candidate.endsWith("/")) {
+        return "the path starts or ends with '/'";
+    }
+    for (const segment of candidate.split("/")) {
+        if (segment === "")
+            return "the path holds an empty segment";
+        if (segment === "." || segment === "..")
+            return `the path holds the segment '${segment}'`;
+        if (segment.includes("\\"))
+            return "the path holds a backslash";
+        if (segment.includes(":"))
+            return "the path holds a colon";
+        if (CONTROL_CHARACTER.test(segment))
+            return "the path holds a control character";
+        if (UTF8_ENCODER.encode(segment).length > MAX_SEGMENT_BYTES) {
+            return `a segment is longer than ${MAX_SEGMENT_BYTES} bytes`;
+        }
+    }
+    if (candidate.normalize("NFC") !== candidate) {
+        return "the path is not in Unicode Normalization Form C";
+    }
+    if (UTF8_ENCODER.encode(candidate).length > MAX_TREE_PATH_BYTES) {
+        return `the path is longer than ${MAX_TREE_PATH_BYTES} bytes`;
+    }
+    return null;
+}
+/**
+ * The paths that collide: those equal to another once case-folded, and those naming, once
+ * case-folded, a directory of another, with the paths under it, sorted byte for byte. The fold is
+ * `toUpperCase().toLowerCase()`, which agrees with Unicode full case folding on the scripts a file
+ * name uses; a pair it misses still fails the write, which never writes over a file.
+ */
+export function pathCollisions(treePaths) {
+    const fold = (text) => text.toUpperCase().toLowerCase();
+    const byFolded = new Map();
+    const underFoldedDirectory = new Map();
+    for (const treePath of treePaths) {
+        const folded = fold(treePath);
+        const group = byFolded.get(folded) ?? new Set();
+        group.add(treePath);
+        byFolded.set(folded, group);
+        const segments = treePath.split("/");
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            const directory = fold(segments.slice(0, depth).join("/"));
+            const under = underFoldedDirectory.get(directory) ?? new Set();
+            under.add(treePath);
+            underFoldedDirectory.set(directory, under);
+        }
+    }
+    const colliding = new Set();
+    for (const group of byFolded.values()) {
+        if (group.size > 1)
+            for (const treePath of group)
+                colliding.add(treePath);
+    }
+    for (const treePath of treePaths) {
+        const under = underFoldedDirectory.get(fold(treePath));
+        if (under !== undefined) {
+            colliding.add(treePath);
+            for (const other of under)
+                colliding.add(other);
+        }
+    }
+    return [...colliding].sort(compareUtf8);
+}
+/** Refuse a destination that exists and is not an empty directory. Throws `RequestArgumentError`. */
+async function refuseOccupiedDestination(fs, target) {
+    let entries;
+    try {
+        const found = await fs.lstat(target);
+        if (!found.isDirectory())
+            throw occupied(target);
+        entries = await fs.readdir(target);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    if (entries.length > 0)
+        throw occupied(target);
+}
+function occupied(target) {
+    return new RequestArgumentError(`Cannot write a method tree at '${target}': it already exists and is not an empty ` +
+        "directory, and a written tree holds nothing but its files.");
+}
+async function isDirectory(fs, target) {
+    try {
+        return (await fs.lstat(target)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────
+const UTF8_ENCODER = new TextEncoder();
+// `ignoreBOM` keeps a leading byte order mark in the text, so the entry gives back every byte.
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+// With the `u` flag a surrogate pair is one code point, so only a lone surrogate matches.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+const CONTROL_CHARACTER = /\p{Cc}/u;
+const MAX_SEGMENT_BYTES = 255;
+const REDACTED = "[redacted]";
+// A link up to its query, then its query, which a redaction replaces.
+const LINK_QUERY = /(\bhttps?:\/\/[^\s"'<>?#]*)\?[^\s"'<>]*/gi;
+const MAX_TREE_PATH_BYTES = 1024;
+function objectMember(holder, name) {
+    const value = holder[name];
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Whether an upload target asks for a create-only write, whose `412` means already stored. */
+function isCreateOnly(headers) {
+    return Object.keys(headers).some((name) => name.toLowerCase() === "if-none-match");
+}
+/** The host a link names, for a message: never the link itself, whose query is a credential. */
+function hostOf(url) {
+    try {
+        return new URL(url).host || "storage";
+    }
+    catch {
+        return "storage";
+    }
+}
+/**
+ * `text`, an answer that carries signed links, with every link hidden, for an error to hold: in a
+ * JSON body every `url` member, at any depth, is replaced whole, and in any text, JSON or not, a
+ * truncated body included, the query of every `http(s)` link is replaced, since a signed link's
+ * signature rides its query. A link is a bearer credential, so no error, message or member may
+ * carry one.
+ */
+export function redactSignedLinks(text) {
+    let redacted = text;
+    try {
+        redacted = JSON.stringify(withUrlMembersRedacted(JSON.parse(text)));
+    }
+    catch {
+        // Not JSON: the pattern below still hides every link's query.
+    }
+    return redacted.replace(LINK_QUERY, "$1?[redacted]");
+}
+function withUrlMembersRedacted(value) {
+    if (Array.isArray(value))
+        return value.map(withUrlMembersRedacted);
+    if (value !== null && typeof value === "object") {
+        // `fromEntries` defines each member as an own property, so a `__proto__` member stays one.
+        return Object.fromEntries(Object.entries(value).map(([name, member]) => [
+            name,
+            name === "url" ? REDACTED : withUrlMembersRedacted(member),
+        ]));
+    }
+    return value;
+}
+function statusLine(response) {
+    return `${response.status} ${response.statusText}`.trimEnd();
+}
+/** The network code of a failed fetch, as the client's own requests report it. */
+function networkCodeOf(err) {
+    if (err instanceof DOMException && err.name === "TimeoutError")
+        return "ABORT_TIMEOUT";
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause !== null && typeof cause === "object" && "code" in cause) {
+            const code = cause.code;
+            if (typeof code === "string")
+                return code;
+        }
+        if (err.name === "TimeoutError")
+            return "ABORT_TIMEOUT";
+    }
+    return "network error";
+}
+function randomHex(byteCount) {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(byteCount));
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=method-trees.js.map