Interface EngineOptions

Base URL of the API. Defaults to https://api.deutsche-digitale-bibliothek.de/2. Checked by validateBaseUrl: not blank, no surrounding whitespace, http(s) only, no query or fragment; anything else makes the constructor throw a DdbValidationError.

Extra headers sent on every request to the configured origin. When a redirect crosses to a different origin, all of them are dropped (only the engine's own Accept and User-Agent go along), so no credential — Authorization, Proxy-Authorization, Cookie, X-API-Key, X-Auth-Token or any other — leaks to an arbitrary host named in Location. Names must be HTTP tokens and values pass the same check as userAgent, or the constructor throws a DdbValidationError.

Number of HTTP redirects (301/302/303/307/308) to follow, 0..20. Defaults to 5. Any other 3xx, one with a missing or malformed Location, and one past this limit surface as a DdbApiError naming the target.

Hard cap on response body size in bytes (defends against memory exhaustion from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit. Enforced by the engine for every transport.

Number of automatic retries for transient (429/503) responses and reset connections, 0..MAX_RETRIES (10). Each waits retryDelayMs * attempt, or longer if the response's Retry-After asks (up to MAX_RETRY_AFTER_MS; a longer one is not retried, and the error names the requested wait).

Called once per retry, right before the backoff sleep, for each retried 429/503 and reset connection; never when there is no retry. A throw is swallowed.

Base backoff between retries in milliseconds (grows linearly); used without a Retry-After. At most MAX_RETRY_AFTER_MS.

Injectable sleep, primarily for deterministic tests.

Per-request timeout in milliseconds (0 disables; at most MAX_TIMEOUT_MS, 2^31 - 1 ms), covering the whole response body. Enforced by the engine for every transport.

Swappable transport. Defaults to the built-in node http/https transport.

Contract: a custom transport must not follow redirects — it honours HttpRequest.redirect ("manual", e.g. fetch(url, { redirect: req.redirect })) and returns the 3xx as is, because one that follows them sends every header (defaultHeaders, the base URL's Authorization) to the redirect target before the engine sees the answer, which the library cannot prevent; it can only reject the response afterwards (a HttpResponse.url on another origin is a DdbNetworkError).

Value of the User-Agent header. Must be non-blank, without control characters (tab allowed) and Latin-1 only (headerValueProblem), or the constructor throws a DdbValidationError.

Optional diagnostic sink for non-fatal warnings (e.g. a followed https:->http: redirect downgrade). Defaults to a no-op so the client stays silent as a library; the CLI wires it to stderr.