@maschinenlesbar.org/pegel-online-cli 0.2.0 → 0.3.0

package/dist/src/client/engine.js

@@ -1,10 +1,11 @@
 // The request engine: turns logical (method, path, query) calls into HTTP
 // requests via a Transport, applies retry/backoff for transient statuses
 // (429, 503), and decodes responses.
-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 { PegelApiError, PegelError, PegelParseError, redactUrl } from "./errors.js";
-import { assertValid, baseUrlProblem, headerValueProblem } from "./validate.js";
+import { PegelApiError, PegelError, PegelNetworkError, PegelParseError, PegelValidationError, credentialsIn, redactCredentials, redactUrl, } from "./errors.js";
+import { assertValid, baseUrlProblem, headerValueProblem, knownKeysProblem } from "./validate.js";
 export const DEFAULT_BASE_URL = "https://www.pegelonline.wsv.de";
 const DEFAULT_USER_AGENT = "pegel-online-cli";
 const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
@@ -21,10 +22,66 @@ function intOption(name, value, fallback, max) {
     if (value === undefined)
         return fallback;
     if (!Number.isSafeInteger(value) || value < 0 || value > max) {
-        throw new PegelError(`Invalid option ${name}: expected an integer from 0 to ${max}, got ${String(value)}.`);
+        throw new PegelValidationError(`Invalid option ${name}: expected an integer from 0 to ${max}, got ${typeof value === "number" ? String(value) : typeof value}.`);
     }
     return value;
 }
+/** Every EngineOptions key; any other is rejected (a JavaScript `timeout` for `timeoutMs`). */
+const OPTION_NAMES = [
+    "baseUrl",
+    "transport",
+    "userAgent",
+    "headers",
+    "timeoutMs",
+    "maxRetries",
+    "retryDelayMs",
+    "maxRedirects",
+    "maxResponseBytes",
+    "sleep",
+];
+/**
+ * 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 as a raw
+ * TypeError, and a bad `sleep` on the first retry.
+ */
+function functionOption(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "function") {
+        throw new PegelValidationError(`Invalid option ${name}: expected a function, got ${typeof value}.`);
+    }
+    return value;
+}
+/**
+ * Read the `headers` option: a plain object of header values, each one an HTTP header
+ * can carry (headerValueProblem). An array or a non-string value used to reach Node as
+ * an opaque TypeError at request time.
+ */
+function headersOption(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new PegelValidationError(`Invalid option headers: expected an object of header values, got ${Array.isArray(value) ? "an array" : typeof value}.`);
+    }
+    for (const [name, header] of Object.entries(value)) {
+        const reason = headerValueProblem(header);
+        if (reason !== undefined)
+            throw new PegelValidationError(`Invalid option headers: ${JSON.stringify(name)}: ${reason}`);
+    }
+    return { ...value };
+}
+/**
+ * Longest server text (in characters) kept for an error message: an error `detail`, a
+ * transport's error text or a redirect target. A longer one is cut and ends in "…", so a
+ * hostile or buggy body cannot flood stderr or a CI log with one huge line.
+ * `PegelApiError.body` keeps the full text.
+ */
+const MAX_DETAIL_LENGTH = 500;
+/** sanitizeServerText, then cut at MAX_DETAIL_LENGTH characters. */
+function cleanDetail(text) {
+    const clean = sanitizeServerText(text);
+    return clean.length > MAX_DETAIL_LENGTH ? `${clean.slice(0, MAX_DETAIL_LENGTH)}…` : clean;
+}
 /**
  * The redirect statuses the engine follows. 300 (a choice for the user), 304 (a
  * cache answer to a conditional request this client never sends) and 305/306
@@ -34,8 +91,10 @@ const FOLLOWED_REDIRECTS = new Set([301, 302, 303, 307, 308]);
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
- * once: retrying early would only land inside the window the server asked us to wait
- * out, and a hostile value must not stall the CLI.
+ * once, naming the requested wait (`PegelApiError.retryAfterMs`): retrying early would
+ * only land inside the window the server asked us to wait out, and a hostile value must
+ * not stall the CLI. A shorter `Retry-After` never makes a wait shorter than the normal
+ * backoff.
  */
 export const MAX_RETRY_AFTER_MS = 30_000;
 /** An IMF-fixdate (RFC 9110 §5.6.7), the one HTTP-date form senders must generate. */
@@ -61,6 +120,88 @@ export function parseRetryAfter(header, now = Date.now()) {
     const when = Date.parse(value);
     return Number.isNaN(when) ? undefined : Math.max(0, when - now);
 }
+/** 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. (`Uint8Array#toString` ignores an encoding
+ * argument and yields "123,34,…", which is how a fetch body used to fail to parse.)
+ */
+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` naturally returns its `Headers` object, which has no plain properties, and a
+ * custom one may write `Retry-After` or `Location` capitalised: the engine then saw no
+ * Retry-After (and retried at once) and no Location (and failed the redirect). Such an
+ * object (anything with `get` and `forEach`, a `Map` included) is copied; a plain record
+ * gets its names lower-cased.
+ */
+function plainHeaders(headers) {
+    const h = headers;
+    if (typeof h.get === "function" && typeof h.forEach === "function") {
+        const record = {};
+        h.forEach.call(headers, (value, name) => {
+            // Headers#forEach gives (value, name), and so does Map#forEach.
+            record[String(name).toLowerCase()] = String(value);
+        });
+        return record;
+    }
+    const record = {};
+    for (const [name, value] of Object.entries(headers)) {
+        record[name.toLowerCase()] = value;
+    }
+    return record;
+}
+/** One header value as a string (the first of a repeated one), or undefined. */
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * 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 PegelNetworkError 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). A refused connection, a DNS failure or a timeout is not transient
+ * in that sense and is not retried.
+ */
+export function isTransientNetworkError(err) {
+    return err instanceof PegelNetworkError && hasTransientCode(err.cause);
+}
 /**
  * Credential-bearing headers that must never be carried across an origin boundary
  * on a redirect. Stored lower-cased and compared case-insensitively so a header
@@ -79,10 +220,34 @@ const CREDENTIAL_HEADERS = new Set([
  * guarantee correct regardless of the casing the caller used.
  */
 function stripSensitiveHeaders(headers) {
+    let stripped = false;
     for (const key of Object.keys(headers)) {
-        if (CREDENTIAL_HEADERS.has(key.toLowerCase()))
+        if (CREDENTIAL_HEADERS.has(key.toLowerCase())) {
             delete headers[key];
+            stripped = true;
+        }
+    }
+    return stripped;
+}
+/** True when `a` and `b` parse and share scheme, host and port; false otherwise. */
+function sameOrigin(a, b) {
+    try {
+        return new URL(a).origin === new URL(b).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why a 401/403 after a redirect to another origin may not be the credentials' fault:
+ * the engine did not send them there. An http->https upgrade on the same host gets its
+ * own advice.
+ */
+function credentialsDroppedHint(from, to) {
+    if (from.protocol === "http:" && to.protocol === "https:" && from.hostname === to.hostname) {
+        return "the server redirected http to https, so the credentials were not sent there; use an https base URL";
     }
+    return `the server redirected to another origin (${to.origin}), so the credentials were not sent there; use that origin as the base URL if it should get them`;
 }
 /**
  * Strip control characters (all C0/C1 controls except tab and newline, plus DEL)
@@ -117,10 +282,16 @@ export function validateBaseUrl(raw) {
 }
 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 an
+    // Authorization header a caller added, can't be logged by accident. Messages show the
+    // base URL through redactUrl.
+    #baseUrl;
+    /** The base URL's userinfo, raw and percent-decoded, for scrubbing server and transport text. */
+    #credentials;
+    #extraHeaders;
     transport;
     userAgent;
-    extraHeaders;
     timeoutMs;
     maxRetries;
     retryDelayMs;
@@ -128,10 +299,22 @@ export class RequestEngine {
     maxResponseBytes;
     sleep;
     constructor(options = {}) {
+        // A JavaScript caller may pass null for "no options"; treat it like undefined.
+        options = options ?? {};
+        // A typo (`timeout` for `timeoutMs`) used to be ignored and the default applied.
+        assertValid("options", options, knownKeysProblem(OPTION_NAMES));
         // The raw value, before the slash strip: the engine glues it into every URL, so
         // "https://h/ " must not lose its slash first and slip past the check.
-        this.baseUrl = validateBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
-        this.transport = options.transport ?? nodeHttpTransport;
+        this.#baseUrl = validateBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.#credentials = credentialsIn(this.#baseUrl).flatMap((raw) => {
+            try {
+                return [raw, decodeURIComponent(raw)];
+            }
+            catch {
+                return [raw];
+            }
+        });
+        this.transport = functionOption("transport", options.transport, nodeHttpTransport);
         // Only `undefined` selects the default. An explicit value must be one an HTTP
         // header can carry (headerValueProblem): not blank, which would replace the
         // default with an empty header, and no control character (CR/LF in particular,
@@ -141,18 +324,18 @@ export class RequestEngine {
             options.userAgent === undefined
                 ? DEFAULT_USER_AGENT
                 : assertValid("User-Agent", options.userAgent, headerValueProblem);
-        this.extraHeaders = options.headers ?? {};
+        this.#extraHeaders = headersOption(options.headers);
         this.timeoutMs = intOption("timeoutMs", options.timeoutMs, 30_000, MAX_TIMEOUT_MS);
         this.maxRetries = intOption("maxRetries", options.maxRetries, 2, MAX_RETRIES);
         this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, 200, MAX_RETRY_AFTER_MS);
         this.maxRedirects = intOption("maxRedirects", options.maxRedirects, 5, MAX_REDIRECTS);
         this.maxResponseBytes = intOption("maxResponseBytes", options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, Number.MAX_SAFE_INTEGER);
-        this.sleep = options.sleep ?? realSleep;
+        this.sleep = functionOption("sleep", options.sleep, realSleep);
     }
     /**
      * Build a fully-qualified URL from a path and optional query parameters.
      *
-     * Throws a PegelError for a path with a "." or ".." segment. The resource methods
+     * Throws a PegelValidationError for a path with a "." or ".." segment. The resource methods
      * put ids into the path with `encodeURIComponent`, which leaves those two
      * unchanged, and URL parsing then resolves them: `currentMeasurement("BONN", "..")`
      * would request `/stations/currentmeasurement.json` (a station of that name).
@@ -163,58 +346,184 @@ export class RequestEngine {
         const normalizedPath = path.startsWith("/") ? path : `/${path}`;
         const dotSegment = normalizedPath.split("/").find((s) => s === "." || s === "..");
         if (dotSegment !== undefined) {
-            throw new PegelError(`Invalid path segment "${dotSegment}" in ${normalizedPath}: "." and ".." cannot be used as an id.`);
+            throw new PegelValidationError(`Invalid path segment "${dotSegment}" in ${normalizedPath}: "." and ".." cannot be used as an id.`);
         }
         const qs = query ? buildQueryString(query) : "";
-        return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+        return `${this.#baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+    }
+    /**
+     * `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.
+     */
+    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;
+    }
+    /**
+     * 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 PegelNetworkError(`Request timed out after ${this.timeoutMs}ms`);
+                controller.abort(err);
+                reject(err);
+            }, this.timeoutMs);
+            timer.unref?.();
+        });
+        try {
+            return await Promise.race([call(controller.signal), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /** Perform a request with Accept negotiation and transient-error retries. */
     async request(method, path, options = { accept: "application/json" }) {
         let url = this.buildUrl(path, options.query);
         const headers = {
-            ...this.extraHeaders,
+            ...this.#extraHeaders,
             Accept: options.accept,
             "User-Agent": this.userAgent,
         };
+        // Only an idempotent request is sent again after a reset: request() is public, and
+        // a POST re-sent after a broken connection may be applied twice. The client itself
+        // sends GETs only.
+        const idempotent = /^(GET|HEAD)$/i.test(method);
         let attempt = 0;
         let redirects = 0;
+        /** Where a redirect to another origin dropped the credentials, for the 401/403 hint. */
+        let droppedCredentialsAt;
         // attempts = initial try + maxRetries (redirects are counted separately)
         for (;;) {
-            const response = await this.transport({
-                method,
-                url,
-                headers,
-                timeoutMs: this.timeoutMs,
-                ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
-            });
+            let response;
+            try {
+                response = await this.callTransport({
+                    method,
+                    url,
+                    headers,
+                    redirect: "manual",
+                    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 the GET, whichever transport reported it. Timeouts are not retried
+                // — a slow upstream should not be asked again at once.
+                if (idempotent && hasTransientCode(cause) && attempt < this.maxRetries) {
+                    attempt += 1;
+                    await this.sleep(this.retryDelayMs * attempt);
+                    continue;
+                }
+                // The default transport rejects with PegelNetworkError only; an injected one may
+                // throw anything (a string, a TypeError, null). Keep the error contract for both:
+                // every failure is a PegelError. The message names the request — Node's text
+                // ("socket hang up") says nothing about which host or gauge failed — and the
+                // original is the `cause`. Any other PegelError passes through.
+                if (cause instanceof PegelError && !(cause instanceof PegelNetworkError))
+                    throw cause;
+                const reason = cause instanceof Error ? cause.message : String(cause);
+                const retried = attempt > 0 ? ` (after ${attempt} ${attempt === 1 ? "retry" : "retries"})` : "";
+                throw new PegelNetworkError(`${method} ${redactUrl(url)} failed: ${cleanDetail(this.scrub(reason))}${retried}`, { cause: this.scrubCause(cause) });
+            }
+            // An injected transport may resolve with anything; a malformed HttpResponse would
+            // otherwise surface below as a raw TypeError, outside the PegelError contract.
+            const invalid = responseProblem(response);
+            if (invalid !== undefined) {
+                throw new PegelNetworkError(`${method} ${redactUrl(url)} failed: the transport returned an invalid response (${invalid}).`);
+            }
+            // Transports must not follow redirects (HttpRequest.redirect is "manual"); fetch does
+            // by default. One that reports a final URL on another origin has carried the
+            // request — and maybe a credential header fetch doesn't strip — somewhere the
+            // engine never vetted, so its answer is not trusted.
+            const finalUrl = response.url;
+            if (typeof finalUrl === "string" && finalUrl !== "" && !sameOrigin(finalUrl, url)) {
+                throw new PegelNetworkError(`${method} ${redactUrl(url)} failed: the transport followed a redirect to another origin ` +
+                    `(${cleanDetail(redactUrl(finalUrl))}); a transport must not follow redirects (HttpRequest.redirect is "manual").`);
+            }
             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 PegelNetworkError(`${method} ${redactUrl(url)} failed: ${sizeLimitMessage(this.maxResponseBytes)}`);
+            }
             const retryable = status === 429 || status === 503;
+            // A Retry-After beyond MAX_RETRY_AFTER_MS is not retried: the error below surfaces
+            // at once and names the wait the server asked for.
+            let refusedWaitMs;
             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"]);
+                // Back off linearly (retryDelayMs × attempt). A Retry-After can make the wait
+                // longer, never shorter: `Retry-After: 0` or a date in the past used to turn the
+                // retries into a zero-delay burst against a server that had just asked for less.
+                const retryAfter = parseRetryAfter(responseHeaders["retry-after"]);
                 if (retryAfter === undefined || retryAfter <= MAX_RETRY_AFTER_MS) {
                     attempt += 1;
-                    await this.sleep(retryAfter ?? this.retryDelayMs * attempt);
+                    const backoff = this.retryDelayMs * attempt;
+                    await this.sleep(retryAfter === undefined ? backoff : Math.max(retryAfter, backoff));
                     continue;
                 }
+                refusedWaitMs = retryAfter;
             }
             // Follow redirects, resolving the Location relative to the current URL.
-            const location = response.headers["location"];
+            const location = headerValue(responseHeaders["location"]);
             const next = FOLLOWED_REDIRECTS.has(status) ? resolveLocation(location, url) : undefined;
             if (next !== undefined && redirects >= this.maxRedirects) {
                 // A loop (or a long chain): say how far it got rather than a bare 3xx.
                 // (With maxRedirects 0 nothing was followed; the plain text says enough.)
-                throw this.toApiError(method, url, status, response.body, location, redirects || undefined);
+                throw this.toApiError(method, url, status, body, location, redirects || undefined);
             }
             if (next !== undefined) {
-                // Security: never carry credential-bearing headers across an origin
-                // boundary. The CLI sends none today, but this guards a future
-                // Authorization/Cookie/X-Api-Key header from leaking to an
-                // attacker-controlled redirect target. Comparing full origin (scheme +
-                // host + port) also strips on a same-host https->http downgrade.
-                if (next.origin !== new URL(url).origin) {
-                    stripSensitiveHeaders(headers);
+                const current = new URL(url);
+                if (next.origin !== current.origin) {
+                    // Security: never carry credentials across an origin boundary — neither
+                    // credential-bearing headers (a caller's Authorization/Cookie/X-Api-Key) nor
+                    // the base URL's userinfo, which an absolute Location to another host doesn't
+                    // carry. Comparing full origin (scheme + host + port) also covers a same-host
+                    // https->http downgrade and an http->https upgrade.
+                    if (stripSensitiveHeaders(headers) || current.username !== "" || current.password !== "") {
+                        droppedCredentialsAt = { from: current, to: next };
+                    }
+                }
+                else if (next.username === "" && next.password === "") {
+                    // Same origin: keep the base URL's userinfo. A relative Location inherits it
+                    // when resolved; an absolute one (`Location: https://same-host/…`) used to
+                    // drop it and turn a mirror login into a 401.
+                    next.username = current.username;
+                    next.password = current.password;
                 }
                 url = next.toString();
                 redirects += 1;
@@ -222,17 +531,20 @@ export class RequestEngine {
             }
             // Any other 3xx — not a followed status, or no usable Location — falls
             // through and surfaces as a PegelApiError naming the target.
-            const contentType = String(response.headers["content-type"] ?? "");
+            const contentType = String(headerValue(responseHeaders["content-type"]) ?? "");
             if (status < 200 || status >= 300) {
-                throw this.toApiError(method, url, status, response.body, location);
+                const hint = (status === 401 || status === 403) && droppedCredentialsAt !== undefined
+                    ? credentialsDroppedHint(droppedCredentialsAt.from, droppedCredentialsAt.to)
+                    : undefined;
+                throw this.toApiError(method, url, status, body, location, undefined, refusedWaitMs, hint);
             }
-            return { data: response.body, contentType, status };
+            return { data: body, contentType, status };
         }
     }
     /** Perform a GET expecting JSON and parse it into `T`. */
     async getJson(path, query) {
         const res = await this.request("GET", path, { query, accept: "application/json" });
-        const text = res.data.toString("utf8");
+        const text = decodeBody(res.data, res.contentType, path);
         try {
             return JSON.parse(text);
         }
@@ -240,8 +552,8 @@ export class RequestEngine {
             throw new PegelParseError(`Failed to parse JSON response from ${path}`, { cause });
         }
     }
-    toApiError(method, url, status, body, locationHeader, redirectsFollowed) {
-        const text = body.toString("utf8");
+    toApiError(method, url, status, body, locationHeader, redirectsFollowed, retryAfterMs, hint) {
+        const text = this.scrub(body.toString("utf8"));
         let detail;
         try {
             const parsed = JSON.parse(text);
@@ -256,7 +568,7 @@ export class RequestEngine {
         // `detail` came from the response body; strip control characters so a hostile
         // endpoint cannot inject terminal escape sequences via the stderr error message.
         if (detail !== undefined)
-            detail = sanitizeServerText(detail);
+            detail = cleanDetail(detail);
         // Name the target of a redirect that was not followed.
         const location = status >= 300 && status < 400 && locationHeader ? redirectTarget(url, locationHeader) : undefined;
         return new PegelApiError({
@@ -267,15 +579,41 @@ export class RequestEngine {
             detail,
             ...(location !== undefined ? { location } : {}),
             ...(redirectsFollowed !== undefined ? { redirectsFollowed } : {}),
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            ...(hint !== undefined ? { hint } : {}),
         });
     }
 }
-/** Resolve a Location header against the current URL; undefined if missing or malformed. */
+/**
+ * Decode a response body by the charset its Content-Type names (UTF-8 when it names
+ * none). A proxy or mirror that answers in ISO-8859-1 used to come out as "K\uFFFDLN"
+ * with exit 0. TextDecoder also drops a leading byte order mark, which
+ * Buffer#toString keeps and JSON.parse then rejects. An unknown charset label is a
+ * PegelParseError.
+ */
+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 PegelParseError(`Unsupported response charset "${sanitizeServerText(charset)}" from ${path}.`);
+    }
+    return decoder.decode(body);
+}
+/**
+ * Resolve a Location header against the current URL; undefined if missing, malformed
+ * or not http(s). A `file:`, `data:` or `javascript:` target is refused here, before
+ * any transport sees it (the default transport would refuse it too; a custom one may
+ * not), and surfaces as a PegelApiError naming the target.
+ */
 function resolveLocation(location, base) {
     if (location === undefined || location === "")
         return undefined;
     try {
-        return new URL(location, base);
+        const next = new URL(location, base);
+        return next.protocol === "http:" || next.protocol === "https:" ? next : undefined;
     }
     catch {
         return undefined;
@@ -288,6 +626,6 @@ function resolveLocation(location, base) {
  */
 function redirectTarget(requestUrl, location) {
     const resolved = resolveLocation(location, requestUrl);
-    const clean = sanitizeServerText(resolved ? redactUrl(resolved.href) : location).trim();
+    const clean = cleanDetail(resolved ? redactUrl(resolved.href) : location).trim();
     return clean === "" ? undefined : clean;
 }

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

@@ -7,9 +7,29 @@ export declare class PegelError extends Error {
 /**
  * Replace the userinfo of a URL (`https://user:secret@host/...`) with `***`, so a
  * credential in a base URL never reaches an error message, a log or CI output.
- * A URL without userinfo, or one that does not parse, is returned unchanged.
+ * A value that does not parse as a URL (a port typo, an unencoded "#" in the
+ * password) or has no scheme (`user:pw@host`) is cut by text instead
+ * (`credentialsIn` + `redactCredentials`); one without userinfo 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. The percent-encoded form (`alice%3Apw%40`, as a URL typed where a
+ * station id belongs ends up in a request path) is replaced too.
+ */
+export declare function redactCredentials(text: string, credentials: readonly string[]): string;
 /**
  * The API responded with a non-2xx status code. `detail` holds a human-readable
  * message extracted from the response body when one is present.
@@ -26,6 +46,12 @@ export declare class PegelApiError extends PegelError {
      * redacted. The message names it.
      */
     readonly location: string | undefined;
+    /**
+     * For a 429/503 that was not retried because its `Retry-After` asked for longer than
+     * the client waits (`MAX_RETRY_AFTER_MS`, 30 s): the wait the server asked for, in
+     * milliseconds. Retrying before then won't help.
+     */
+    readonly retryAfterMs: number | undefined;
     constructor(args: {
         status: number;
         url: string;
@@ -35,6 +61,10 @@ export declare class PegelApiError extends PegelError {
         location?: string;
         /** Redirects already followed when the limit stopped this one (> 0 only). */
         redirectsFollowed?: number;
+        /** A Retry-After longer than the client waits (not retried). */
+        retryAfterMs?: number;
+        /** Advice appended to the message (e.g. that a redirect dropped the credentials). */
+        hint?: string;
     });
     /** True for statuses the API documents as transient and retry-able. */
     get isRetryable(): boolean;