@maschinenlesbar.org/marktstammdatenregister-cli 0.1.0 → 0.2.0

package/dist/src/client/engine.d.ts

@@ -30,15 +30,17 @@ export interface EngineOptions {
      */
     timeoutMs?: number;
     /**
-     * Number of automatic retries for transient (429/503) responses, an integer
-     * 0..`MAX_RETRIES` (10); defaults to 2. Each waits the response's `Retry-After`
-     * (up to `MAX_RETRY_AFTER_MS`; a longer one is not retried), or else
-     * `retryDelayMs * attempt`.
+     * Number of automatic retries for transient (429/503) responses and reset
+     * connections (`isTransientNetworkError`), an integer
+     * 0..`MAX_RETRIES` (10); defaults to 2. Each waits `retryDelayMs * attempt`, or the
+     * response's `Retry-After` when that is longer. A `Retry-After` above
+     * `MAX_RETRY_AFTER_MS` is not retried: the MastrApiError names the requested wait.
      */
     maxRetries?: number;
     /**
-     * Base backoff between retries in milliseconds (grows linearly), a non-negative
-     * integer; used without a Retry-After. Defaults to 200.
+     * Base backoff between retries in milliseconds (grows linearly: `retryDelayMs * attempt`),
+     * an integer 0..`MAX_RETRY_AFTER_MS` (30 000). Defaults to 200. It is also the floor: a
+     * `Retry-After` can make a wait longer, never shorter.
      */
     retryDelayMs?: number;
     /**
@@ -96,13 +98,20 @@ export declare function isBidiControl(code: number): boolean;
  * Written as a code-point filter so no raw control byte appears in this source.
  */
 export declare function sanitizeServerText(text: string): string;
+/**
+ * Longest server text (in characters) an error message keeps: a hostile or buggy body
+ * must not flood stderr or a CI log with one huge line. `MastrApiError.body` keeps the
+ * full text.
+ */
+export declare const MAX_DETAIL_LENGTH = 500;
 /**
  * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
  * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
  * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
- * Returns `undefined` when nothing readable is left.
+ * Returns `undefined` when nothing readable is left. `clean` runs on each raw string
+ * first (the engine passes its credential scrubber).
  */
-export declare function describeMastrErrors(errors: unknown): string | undefined;
+export declare function describeMastrErrors(errors: unknown, clean?: (text: string) => string): string | undefined;
 /**
  * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
  * or control characters, not an absolute URL, a scheme other than `http:`/`https:`,
@@ -119,23 +128,63 @@ export declare function validateBaseUrl(raw: string): string;
  * `userAgent` and every `defaultHeaders` value before any request.
  */
 export declare function assertHeaderValue(name: string, value: string): string;
+/**
+ * True for a failure caused by a reset or aborted connection, which the engine retries —
+ * whichever transport raised it (a Node error, fetch's TypeError with an undici cause), the
+ * code anywhere in the `cause` chain. A refused connection, a DNS failure or a timeout is
+ * not transient in that sense and is not retried.
+ */
+export declare function isTransientNetworkError(err: unknown): boolean;
+/**
+ * Throw for a key that is not an option name. A JavaScript caller's typo (`timeout` for
+ * `timeoutMs`) was ignored silently and the default applied; TypeScript catches it at
+ * compile time, JavaScript does not. `extra` names options a wrapper (the client) adds.
+ */
+export declare function assertKnownOptions(options: object, extra?: readonly string[]): void;
+/** Engine options as given, or a MastrValidationError for a non-object (null counts as none). */
+export declare function optionsObject<T extends object>(options: T | null | undefined): T;
 export declare class RequestEngine {
-    private readonly baseUrl;
+    #private;
     private readonly transport;
     private readonly userAgent;
-    private readonly defaultHeaders;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly maxResponseBytes;
     private readonly sleep;
     constructor(options?: EngineOptions);
+    /**
+     * `text` without the base URL's credentials: server text (an error body that echoes the
+     * request URL) and transport text (fetch's "Failed to fetch <url>") can carry them. The
+     * client runs it on the `Errors` envelopes it turns into errors.
+     */
+    scrub(text: string): string;
+    /**
+     * A transport failure as the `cause` of the error the engine raises: the original when its
+     * text carries no credentials, otherwise a copy with them scrubbed (message, `code` and the
+     * cause chain kept), so logging the error with its causes can't reveal the base URL's
+     * password.
+     */
+    private scrubCause;
     /** Build a fully-qualified URL from a path and optional query parameters. */
     buildUrl(path: string, query?: QueryParams): string;
+    /**
+     * Call the transport under the overall deadline (`timeoutMs`): the request gets an
+     * AbortSignal that fires at the deadline, and the call rejects then whether the transport
+     * stops or not — a custom transport (fetch, a node:http wrapper) that ignores `timeoutMs`
+     * can't hang the caller. A synchronous throw becomes a rejection.
+     */
+    private callTransport;
     /**
      * Perform a GET with Accept negotiation and transient-error retries. Redirects
      * are NOT followed — the canonical host answers directly, so a 3xx (e.g. a bad
      * base URL bouncing to a portal page) surfaces as an error.
+     *
+     * The engine enforces the transport contract itself, so it holds for a custom
+     * transport too: `timeoutMs` (an AbortSignal deadline), `maxResponseBytes` (checked on
+     * the body it gets back), any byte-array body, `Headers`/`Map`/any-case headers. Whatever
+     * a transport throws becomes a `MastrNetworkError`, and so does a malformed response; a
+     * reset connection (`isTransientNetworkError`) is retried like a 503.
      */
     request(path: string, query?: QueryParams, accept?: string): Promise<RawResponse>;
     /**
@@ -144,5 +193,6 @@ export declare class RequestEngine {
      * `MastrParseError`, never a silent `null`.
      */
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
+    /** The MastrApiError for a non-2xx answer; `note` is appended to the detail. */
     private toApiError;
 }

package/dist/src/client/engine.js

@@ -2,9 +2,10 @@
 // a Transport, applies retry/backoff for transient statuses (429, 503), and decodes
 // JSON responses. MaStR's public search backend is an unauthenticated GET API whose
 // parameters travel in the query string.
-import { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
+import { TextDecoder } from "node:util";
+import { MAX_TIMEOUT_MS, nodeHttpTransport, sizeLimitMessage, } from "./http.js";
 import { buildQueryString } from "./query.js";
-import { MastrApiError, MastrParseError } from "./errors.js";
+import { MastrApiError, MastrError, MastrNetworkError, MastrParseError, MastrValidationError, credentialsIn, redactCredentials, redactUrl, } from "./errors.js";
 import { assertValid, baseUrlProblem, headerNameProblem, headerValueProblem, intRangeProblem, } from "./validate.js";
 export const DEFAULT_BASE_URL = "https://www.marktstammdatenregister.de/MaStR";
 const DEFAULT_USER_AGENT = "marktstammdatenregister-cli";
@@ -90,17 +91,28 @@ export function sanitizeServerText(text) {
     }
     return out.replace(/\s+/g, " ").trim();
 }
+/**
+ * Longest server text (in characters) an error message keeps: a hostile or buggy body
+ * must not flood stderr or a CI log with one huge line. `MastrApiError.body` keeps the
+ * full text.
+ */
+export const MAX_DETAIL_LENGTH = 500;
+/** `text` cut at MAX_DETAIL_LENGTH characters, ending in "…" when cut. */
+function cutDetail(text) {
+    return text.length > MAX_DETAIL_LENGTH ? `${text.slice(0, MAX_DETAIL_LENGTH)}…` : text;
+}
 /**
  * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
  * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
  * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
- * Returns `undefined` when nothing readable is left.
+ * Returns `undefined` when nothing readable is left. `clean` runs on each raw string
+ * first (the engine passes its credential scrubber).
  */
-export function describeMastrErrors(errors) {
+export function describeMastrErrors(errors, clean = (text) => text) {
     const found = [];
     const walk = (value, depth) => {
         if (typeof value === "string") {
-            const text = sanitizeServerText(value);
+            const text = sanitizeServerText(clean(value));
             if (text !== "" && !found.includes(text))
                 found.push(text);
         }
@@ -110,7 +122,7 @@ export function describeMastrErrors(errors) {
         }
     };
     walk(errors, 0);
-    return found.length > 0 ? found.join("; ") : undefined;
+    return found.length > 0 ? cutDetail(found.join("; ")) : undefined;
 }
 /**
  * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
@@ -134,6 +146,9 @@ export function assertHeaderValue(name, value) {
 }
 /** Check every `defaultHeaders` name (a token) and value; returns a copy. */
 function checkedHeaders(headers) {
+    if (typeof headers !== "object" || headers === null || Array.isArray(headers)) {
+        throw new MastrValidationError(`Invalid defaultHeaders: expected an object of header names and values, got ${describeType(headers)}.`);
+    }
     const out = {};
     for (const [name, value] of Object.entries(headers)) {
         assertValid("defaultHeaders name", name, headerNameProblem);
@@ -141,53 +156,271 @@ function checkedHeaders(headers) {
     }
     return out;
 }
+/** Why `value` is not a usable HttpResponse, or undefined when it is. */
+function responseProblem(value) {
+    if (typeof value !== "object" || value === null)
+        return "not an object";
+    const r = value;
+    if (typeof r.status !== "number" || !Number.isInteger(r.status) || r.status < 100 || r.status > 599) {
+        return "status is not an HTTP status code";
+    }
+    if (typeof r.headers !== "object" || r.headers === null || Array.isArray(r.headers))
+        return "headers is not an object";
+    if (bodyBytes(r.body) === undefined)
+        return "body is not a Buffer, Uint8Array, other ArrayBuffer view or ArrayBuffer";
+    return undefined;
+}
+/**
+ * The response body as a Buffer (a view, no copy): a Buffer, any ArrayBuffer view (a
+ * Uint8Array from fetch, a DataView) or an ArrayBuffer/SharedArrayBuffer — checked by internal
+ * slot, not `instanceof`, so a value from another realm (a vm context, a Jest test) counts.
+ * Undefined for anything else.
+ */
+function bodyBytes(value) {
+    if (Buffer.isBuffer(value))
+        return value;
+    if (ArrayBuffer.isView(value))
+        return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    const tag = Object.prototype.toString.call(value);
+    if (tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]")
+        return Buffer.from(value);
+    return undefined;
+}
+/**
+ * The response headers as a plain record with lower-case names. A transport built on
+ * `fetch` returns its `Headers` object, which has no plain properties (the engine then saw
+ * no Retry-After and no Content-Type at all); such an object, or a `Map` (anything with
+ * `get` and `forEach`), is copied into a record. A custom transport may also not
+ * lower-case the names ("Retry-After").
+ */
+function plainHeaders(headers) {
+    const h = headers;
+    const record = {};
+    if (typeof h.get === "function" && typeof h.forEach === "function") {
+        h.forEach.call(headers, (value, name) => {
+            record[String(name).toLowerCase()] = value;
+        });
+        return record;
+    }
+    for (const [name, value] of Object.entries(headers)) {
+        record[name.toLowerCase()] = value;
+    }
+    return record;
+}
+/**
+ * Error codes of a connection that broke off mid-request: Node's (`socket hang up` is
+ * ECONNRESET) and undici's (`fetch failed` with cause UND_ERR_SOCKET, "other side closed").
+ */
+const TRANSIENT_NETWORK_CODES = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "UND_ERR_SOCKET"]);
+/** True when `err` or an error in its `cause` chain has a transient connection code. */
+function hasTransientCode(err, depth = 0) {
+    if (typeof err !== "object" || err === null || depth > 4)
+        return false;
+    const code = err.code;
+    if (typeof code === "string" && TRANSIENT_NETWORK_CODES.has(code))
+        return true;
+    return hasTransientCode(err.cause, depth + 1);
+}
+/**
+ * True for a failure caused by a reset or aborted connection, which the engine retries —
+ * whichever transport raised it (a Node error, fetch's TypeError with an undici cause), the
+ * code anywhere in the `cause` chain. A refused connection, a DNS failure or a timeout is
+ * not transient in that sense and is not retried.
+ */
+export function isTransientNetworkError(err) {
+    return hasTransientCode(err);
+}
+/** A value's type for a validation message: "null", "an array", "a string", … */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return `a ${typeof value}`;
+}
+/** Every EngineOptions key. */
+const OPTION_NAMES = [
+    "baseUrl",
+    "transport",
+    "userAgent",
+    "defaultHeaders",
+    "timeoutMs",
+    "maxRetries",
+    "retryDelayMs",
+    "maxResponseBytes",
+    "sleep",
+];
+/**
+ * Throw for a key that is not an option name. A JavaScript caller's typo (`timeout` for
+ * `timeoutMs`) was ignored silently and the default applied; TypeScript catches it at
+ * compile time, JavaScript does not. `extra` names options a wrapper (the client) adds.
+ */
+export function assertKnownOptions(options, extra = []) {
+    const names = [...OPTION_NAMES, ...extra];
+    for (const [key, value] of Object.entries(options)) {
+        // An unset key (`proxy: undefined` from a spread config) changes nothing: skip it.
+        if (value === undefined || names.includes(key))
+            continue;
+        const lower = key.toLowerCase();
+        const hint = names.find((name) => name.toLowerCase().includes(lower) || lower.includes(name.toLowerCase()));
+        throw new MastrValidationError(`Unknown option ${JSON.stringify(key)}` +
+            (hint === undefined ? `; the options are ${names.join(", ")}.` : ` (did you mean ${hint}?).`));
+    }
+}
+/**
+ * Read a function option: `undefined` gives the default; anything else that is not a
+ * function throws. A string `transport` used to fail at the first request, and a bad
+ * `sleep` as a raw TypeError on the first retry.
+ */
+function functionOption(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "function") {
+        throw new MastrValidationError(`Invalid ${name}: expected a function, got ${describeType(value)}.`);
+    }
+    return value;
+}
+/** Engine options as given, or a MastrValidationError for a non-object (null counts as none). */
+export function optionsObject(options) {
+    if (options === undefined || options === null)
+        return {};
+    if (typeof options !== "object" || Array.isArray(options)) {
+        throw new MastrValidationError(`Invalid options: expected an object, got ${describeType(options)}.`);
+    }
+    return options;
+}
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class RequestEngine {
-    baseUrl;
+    // Real private fields (not TypeScript's `private`): util.inspect, console.log and
+    // JSON.stringify of a client never show them, so a password in the base URL (or a
+    // credential in a default header) can't be logged by accident.
+    #baseUrl;
+    /** The base URL's userinfo, raw and percent-decoded, for scrubbing server and transport text. */
+    #credentials;
     transport;
     userAgent;
-    defaultHeaders;
+    #defaultHeaders;
     timeoutMs;
     maxRetries;
     retryDelayMs;
     maxResponseBytes;
     sleep;
     constructor(options = {}) {
+        // A JavaScript caller may pass null for "no options"; anything else must be an object
+        // with known keys.
+        options = optionsObject(options);
+        assertKnownOptions(options);
         // The raw value is checked before the trailing-slash strip, so "https://h/ "
         // cannot slip past it; only an omitted baseUrl selects the default.
-        this.baseUrl = validateBaseUrl(options.baseUrl === undefined ? DEFAULT_BASE_URL : options.baseUrl);
-        this.transport = options.transport ?? nodeHttpTransport;
+        const baseUrl = options.baseUrl === undefined ? DEFAULT_BASE_URL : options.baseUrl;
+        this.#baseUrl = validateBaseUrl(baseUrl);
+        this.#credentials = credentialsIn(baseUrl).flatMap((raw) => {
+            try {
+                return [raw, decodeURIComponent(raw)];
+            }
+            catch {
+                return [raw];
+            }
+        });
+        this.transport = functionOption("transport", options.transport, nodeHttpTransport);
         // Header values are checked up front: a blank one would be sent as is, and a
         // CR/LF or a character above U+00FF would reach a custom transport raw or make
         // Node's HTTP layer throw an untyped ERR_INVALID_CHAR. Only an omitted
         // userAgent selects the default.
         this.userAgent =
             options.userAgent === undefined ? DEFAULT_USER_AGENT : assertHeaderValue("userAgent", options.userAgent);
-        this.defaultHeaders = checkedHeaders(options.defaultHeaders ?? {});
+        this.#defaultHeaders = checkedHeaders(options.defaultHeaders ?? {});
         // Range-check the numeric options: a negative, NaN or fractional value would
         // otherwise silently disable the timeout or the size cap, and an unbounded
         // maxRetries would keep retrying against the production register.
         this.timeoutMs = intOption("timeoutMs", options.timeoutMs, MAX_TIMEOUT_MS, 30_000);
         this.maxRetries = intOption("maxRetries", options.maxRetries, MAX_RETRIES, 2);
-        this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, Number.MAX_SAFE_INTEGER, 200);
+        // Bounded like a Retry-After wait: a larger value would stall the CLI, and one above
+        // 2^31 - 1 ms would overflow Node's timer and retry after 1 ms.
+        this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, MAX_RETRY_AFTER_MS, 200);
         this.maxResponseBytes = intOption("maxResponseBytes", options.maxResponseBytes, Number.MAX_SAFE_INTEGER, DEFAULT_MAX_RESPONSE_BYTES);
-        this.sleep = options.sleep ?? realSleep;
+        this.sleep = functionOption("sleep", options.sleep, realSleep);
+    }
+    /**
+     * `text` without the base URL's credentials: server text (an error body that echoes the
+     * request URL) and transport text (fetch's "Failed to fetch <url>") can carry them. The
+     * client runs it on the `Errors` envelopes it turns into errors.
+     */
+    scrub(text) {
+        return this.#credentials.length === 0 ? text : redactCredentials(text, this.#credentials);
+    }
+    /**
+     * A transport failure as the `cause` of the error the engine raises: the original when its
+     * text carries no credentials, otherwise a copy with them scrubbed (message, `code` and the
+     * cause chain kept), so logging the error with its causes can't reveal the base URL's
+     * password.
+     */
+    scrubCause(cause, depth = 0) {
+        if (this.#credentials.length === 0 || depth > 5)
+            return cause;
+        if (typeof cause === "string")
+            return this.scrub(cause);
+        if (!(cause instanceof Error))
+            return cause;
+        const inner = this.scrubCause(cause.cause, depth + 1);
+        const message = this.scrub(cause.message);
+        if (message === cause.message && inner === cause.cause && !this.scrub(cause.stack ?? "").includes("***@")) {
+            return cause;
+        }
+        const copy = new Error(message, inner === undefined ? undefined : { cause: inner });
+        copy.name = cause.name;
+        const code = cause.code;
+        if (code !== undefined)
+            Object.assign(copy, { code });
+        return copy;
     }
     /** Build a fully-qualified URL from a path and optional query parameters. */
     buildUrl(path, query) {
         const normalizedPath = path.startsWith("/") ? path : `/${path}`;
         const qs = query ? buildQueryString(query) : "";
-        return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+        return `${this.#baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+    }
+    /**
+     * Call the transport under the overall deadline (`timeoutMs`): the request gets an
+     * AbortSignal that fires at the deadline, and the call rejects then whether the transport
+     * stops or not — a custom transport (fetch, a node:http wrapper) that ignores `timeoutMs`
+     * can't hang the caller. A synchronous throw becomes a rejection.
+     */
+    async callTransport(request) {
+        const call = (signal) => Promise.resolve().then(() => this.transport(signal === undefined ? request : { ...request, signal }));
+        if (this.timeoutMs === 0)
+            return call();
+        const controller = new AbortController();
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                const err = new MastrNetworkError(`Request timed out after ${this.timeoutMs}ms`);
+                controller.abort(err);
+                reject(err);
+            }, this.timeoutMs);
+        });
+        try {
+            return await Promise.race([call(controller.signal), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /**
      * Perform a GET with Accept negotiation and transient-error retries. Redirects
      * are NOT followed — the canonical host answers directly, so a 3xx (e.g. a bad
      * base URL bouncing to a portal page) surfaces as an error.
+     *
+     * The engine enforces the transport contract itself, so it holds for a custom
+     * transport too: `timeoutMs` (an AbortSignal deadline), `maxResponseBytes` (checked on
+     * the body it gets back), any byte-array body, `Headers`/`Map`/any-case headers. Whatever
+     * a transport throws becomes a `MastrNetworkError`, and so does a malformed response; a
+     * reset connection (`isTransientNetworkError`) is retried like a 503.
      */
     async request(path, query, accept = "application/json") {
         const url = this.buildUrl(path, query);
         const headers = {
-            ...this.defaultHeaders,
+            ...this.#defaultHeaders,
             Accept: accept,
             "User-Agent": this.userAgent,
             // The MaStR search backend is a Kendo/DataTables endpoint that expects an
@@ -196,30 +429,80 @@ export class RequestEngine {
         };
         let attempt = 0;
         for (;;) {
-            const response = await this.transport({
-                method: "GET",
-                url,
-                headers,
-                timeoutMs: this.timeoutMs,
-                ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
-            });
+            let response;
+            try {
+                response = await this.callTransport({
+                    method: "GET",
+                    url,
+                    headers,
+                    timeoutMs: this.timeoutMs,
+                    ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
+                });
+            }
+            catch (cause) {
+                // A connection the server (or a gateway) reset is the network-level twin of a 503:
+                // retry it, whichever transport reported it. Timeouts are not retried.
+                if (hasTransientCode(cause) && attempt < this.maxRetries) {
+                    attempt += 1;
+                    await this.sleep(this.retryDelayMs * attempt);
+                    continue;
+                }
+                // The default transport rejects with MastrNetworkError only; an injected one may
+                // throw anything (fetch's TypeError, a string, null). Keep the library's contract:
+                // every failure is a MastrError.
+                if (cause instanceof MastrNetworkError) {
+                    // Its text may echo the request URL; re-raise it scrubbed when it does.
+                    const message = this.scrub(cause.message);
+                    const inner = this.scrubCause(cause.cause);
+                    if (message === cause.message && inner === cause.cause)
+                        throw cause;
+                    throw new MastrNetworkError(message, inner === undefined ? undefined : { cause: inner });
+                }
+                if (cause instanceof MastrError)
+                    throw cause;
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                throw new MastrNetworkError(`GET ${redactUrl(url)} failed: ${sanitizeServerText(this.scrub(reason))}`, {
+                    cause: this.scrubCause(cause),
+                });
+            }
+            // An injected transport may resolve with anything; a malformed HttpResponse would
+            // otherwise surface as a raw TypeError, or a missing status as a success.
+            const invalid = responseProblem(response);
+            if (invalid !== undefined) {
+                throw new MastrNetworkError(`GET ${redactUrl(url)} failed: the transport returned an invalid response (${invalid}).`);
+            }
             const status = response.status;
+            const responseHeaders = plainHeaders(response.headers);
+            const body = bodyBytes(response.body);
+            // The size cap holds whatever the transport did: the default one aborts early, a
+            // custom one may have read everything.
+            if (this.maxResponseBytes > 0 && body.byteLength > this.maxResponseBytes) {
+                throw new MastrNetworkError(sizeLimitMessage(this.maxResponseBytes));
+            }
             const retryable = status === 429 || status === 503;
+            // A Retry-After beyond MAX_RETRY_AFTER_MS is not retried: retrying early would land
+            // inside the window the server asked us to wait out, and a hostile value must not stall
+            // the CLI. The error then names the requested wait, so a script knows when to try again.
+            const retryAfter = retryable ? parseRetryAfter(responseHeaders["retry-after"]) : undefined;
             if (retryable && attempt < this.maxRetries) {
-                // Honour Retry-After; without a usable one, back off linearly. A Retry-After
-                // beyond MAX_RETRY_AFTER_MS is not retried: the error below surfaces at once.
-                const retryAfter = parseRetryAfter(response.headers["retry-after"]);
                 if (retryAfter === undefined || retryAfter <= MAX_RETRY_AFTER_MS) {
                     attempt += 1;
-                    await this.sleep(retryAfter ?? this.retryDelayMs * attempt);
+                    // The linear backoff is the floor: a Retry-After can make a wait longer, never
+                    // shorter. `Retry-After: 0` or a date in the past turned the retries into a
+                    // zero-delay burst against a register that had just answered 429/503.
+                    const backoff = this.retryDelayMs * attempt;
+                    await this.sleep(retryAfter === undefined ? backoff : Math.max(retryAfter, backoff));
                     continue;
                 }
+                throw this.toApiError(url, status, body, `the server asked to wait ${Math.ceil(retryAfter / 1000)} s (Retry-After) before trying again, ` +
+                    `longer than the ${MAX_RETRY_AFTER_MS / 1000} s the client waits, so it was not retried; ` +
+                    "retrying sooner won't help");
             }
-            const contentType = String(response.headers["content-type"] ?? "");
+            const contentType = String(responseHeaders["content-type"] ?? "");
             if (status < 200 || status >= 300) {
-                throw this.toApiError(url, status, response.body);
+                throw this.toApiError(url, status, body);
             }
-            return { data: response.body, contentType, status };
+            return { data: body, contentType, status };
         }
     }
     /**
@@ -229,7 +512,7 @@ export class RequestEngine {
      */
     async getJson(path, query) {
         const res = await this.request(path, query);
-        const text = res.data.toString("utf8");
+        const text = decodeBody(res.data, res.contentType, path);
         if (res.status === 204 || text.trim().length === 0) {
             throw new MastrParseError(`Empty response body from ${path}`);
         }
@@ -240,8 +523,9 @@ export class RequestEngine {
             throw new MastrParseError(`Failed to parse JSON response from ${path}`, { cause });
         }
     }
-    toApiError(url, status, body) {
-        const text = body.toString("utf8");
+    /** The MastrApiError for a non-2xx answer; `note` is appended to the detail. */
+    toApiError(url, status, body, note) {
+        const text = this.scrub(body.toString("utf8"));
         let detail;
         try {
             const parsed = JSON.parse(text);
@@ -264,7 +548,26 @@ export class RequestEngine {
         // collapse above does not remove ESC, so strip control characters before it can
         // reach stderr and inject terminal escape sequences.
         if (detail !== undefined)
-            detail = sanitizeServerText(detail);
+            detail = cutDetail(sanitizeServerText(detail));
+        if (note !== undefined)
+            detail = detail === undefined || detail === "" ? note : `${detail}; ${note}`;
         return new MastrApiError({ status, url, method: "GET", body: text, detail });
     }
 }
+/**
+ * Decode a response body by the charset its Content-Type names (UTF-8 when it names none):
+ * a Latin-1 body from a re-encoding proxy or mirror became U+FFFD with `toString("utf8")`.
+ * TextDecoder also drops a leading byte order mark, which JSON.parse would reject. An
+ * unknown charset label is a MastrParseError.
+ */
+function decodeBody(body, contentType, path) {
+    const charset = /;\s*charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType)?.[1] ?? "utf-8";
+    let decoder;
+    try {
+        decoder = new TextDecoder(charset);
+    }
+    catch {
+        throw new MastrParseError(`Unsupported response charset "${sanitizeServerText(charset)}" from ${path}.`);
+    }
+    return decoder.decode(body);
+}

package/dist/src/client/errors.d.ts

@@ -4,6 +4,21 @@
  * A URL without userinfo, or one that does not parse, is returned unchanged.
  */
 export declare function redactUrl(url: string): string;
+/**
+ * The userinfo a URL-like value carries, exactly as written — `["alice:pa#ss"]` for
+ * `https://alice:pa#ss@host` — or `[]` when it carries none. It works on values that don't
+ * parse as a URL too, and on values with a prefix (`--base-url=https://u:p@h`): the userinfo
+ * is everything between `://` and the last `@` before the host. A value without a scheme
+ * counts when it reads `user:password@host`. Used to redact those exact strings from text
+ * that echoes the value (usage errors, help), whatever characters the password contains.
+ */
+export declare function credentialsIn(value: string): string[];
+/**
+ * `text` with every occurrence of each credential (as `credentialsIn` returns them) that is
+ * followed by `@` replaced by `***`. Matching the exact strings, not a pattern, covers
+ * passwords with spaces, quotes, `#`, `?` or `/` that no URL pattern can delimit.
+ */
+export declare function redactCredentials(text: string, credentials: readonly string[]): string;
 /** Base class for every error originating from this client. */
 export declare class MastrError extends Error {
     constructor(message: string, options?: {