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

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

@@ -9,7 +9,9 @@ export interface RawResponse {
 /**
  * Options for {@link RequestEngine} and the client. The numeric options must be
  * integers within their documented range; anything else (negative, fractional,
- * NaN, Infinity, too large) makes the constructor throw a PegelError.
+ * NaN, Infinity, too large) makes the constructor throw a PegelValidationError, as
+ * does a `transport` or `sleep` that is not a function and a `headers` value an HTTP
+ * header can't carry.
  */
 export interface EngineOptions {
     /** Base URL of the API. Defaults to https://www.pegelonline.wsv.de */
@@ -32,15 +34,16 @@ export interface EngineOptions {
      */
     timeoutMs?: number;
     /**
-     * Number of automatic retries for transient (429/503) responses, 0..`MAX_RETRIES`
-     * (10). 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 (ECONNRESET, EPIPE, ECONNABORTED, undici's UND_ERR_SOCKET, anywhere in
+     * the error's `cause` chain; GET and HEAD only), 0..`MAX_RETRIES` (10). Each waits
+     * `retryDelayMs * attempt`, or longer when the response's `Retry-After` asks (up to
+     * `MAX_RETRY_AFTER_MS`; a longer one is not retried). Timeouts are not retried.
      */
     maxRetries?: number;
     /**
-     * Base backoff between retries in milliseconds (grows linearly); used without a
-     * Retry-After. At most `MAX_RETRY_AFTER_MS`.
+     * Base backoff between retries in milliseconds (grows linearly); the floor of every
+     * wait, Retry-After or not. At most `MAX_RETRY_AFTER_MS`.
      */
     retryDelayMs?: number;
     /**
@@ -62,8 +65,10 @@ export declare const MAX_RETRIES = 10;
 /**
  * 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 declare const MAX_RETRY_AFTER_MS = 30000;
 /**
@@ -77,6 +82,13 @@ export declare const MAX_RETRY_AFTER_MS = 30000;
  * read `"1.5"` as a date in 2001 and retry at once.
  */
 export declare function parseRetryAfter(header: string | string[] | undefined, now?: number): number | undefined;
+/**
+ * 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 declare function isTransientNetworkError(err: unknown): boolean;
 /**
  * Check a base URL against the library's rules (baseUrlProblem: no whitespace or
  * control characters, an absolute http(s) URL, no query or fragment) and return it
@@ -87,10 +99,9 @@ export declare function parseRetryAfter(header: string | string[] | undefined, n
  */
 export declare function validateBaseUrl(raw: string): string;
 export declare class RequestEngine {
-    private readonly baseUrl;
+    #private;
     private readonly transport;
     private readonly userAgent;
-    private readonly extraHeaders;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly retryDelayMs;
@@ -101,7 +112,7 @@ export declare class RequestEngine {
     /**
      * 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).
@@ -109,6 +120,25 @@ export declare class RequestEngine {
      * encodeURIComponent turns their "%" into "%25".)
      */
     buildUrl(path: string, query?: QueryParams): string;
+    /**
+     * `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.
+     */
+    private scrub;
+    /**
+     * 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;
+    /**
+     * 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 request with Accept negotiation and transient-error retries. */
     request(method: string, path: string, options?: {
         query?: QueryParams;