Skip to content

Interface: ClientOptions ​

Defined in: api/rust-fetch.d.ts:241

fetch() options for browsers, Web Workers and other fetch() runtimes (Deno, Bun). Node.js requests don't use them; they're still validated there.

Extends ​

Properties ​

allowAbsoluteUrls? ​

optional allowAbsoluteUrls?: boolean

Defined in: api/rust-fetch.d.ts:312

With a baseUrl, whether an absolute request URL may replace it. An absolute URL also receives the client's headers (e.g. Authorization), so set false when paths come from user input: absolute URLs then reject with an InvalidInputError. Default: true


allowInsecureRedirects? ​

optional allowInsecureRedirects?: boolean

Defined in: api/rust-fetch.d.ts:347

Whether to follow a redirect from https: to http:, which sends the request (and a 307/308 body) unencrypted. With false, such a redirect rejects with a NetworkError (Node.js; browsers apply their own rules). Default: true


allowPrivateNetwork? ​

optional allowPrivateNetwork?: boolean

Defined in: api/rust-fetch.d.ts:369

Node.js: with false, requests whose host resolves to a private or reserved address (loopback, RFC 1918, link-local including cloud metadata at 169.254.169.254, CGNAT, unique-local and link-local IPv6, multicast…) reject with a NetworkError before connecting. The resolved address is checked when connecting, on every redirect, so DNS rebinding can't get past it. For servers that fetch user-supplied URLs (SSRF). Through a proxy, which resolves names itself, IP addresses are checked and host names are refused. Browsers have their own rules. Default: true


auth? ​

optional auth?: AuthOptions

Defined in: api/rust-fetch.d.ts:247

Authentication for requests to the client's origin (baseUrl, plus auth.origins). Needs one of them. A request that sets its own Authorization header keeps it.


baseUrl? ​

optional baseUrl?: string

Defined in: api/rust-fetch.d.ts:266

Base URL that relative request URLs are appended to, e.g. https://api.example.com/v1


cache? ​

optional cache?: "default" | "no-store" | "reload" | "no-cache" | "force-cache" | "only-if-cached"

Defined in: api/rust-fetch.d.ts:74

How the browser's HTTP cache is used

Inherited from ​

BrowserRequestOptions.cache


circuitBreaker? ​

optional circuitBreaker?: CircuitBreakerOptions

Defined in: api/rust-fetch.d.ts:330

Opt-in per-origin circuit breaker. Off by default; counts failed attempts including retries.


connectTimeoutMs? ​

optional connectTimeoutMs?: number

Defined in: api/rust-fetch.d.ts:272

Time until a connection is established, including TLS (Node.js); browsers cannot observe it. 0 disables.


credentials? ​

optional credentials?: "omit" | "same-origin" | "include"

Defined in: api/rust-fetch.d.ts:70

Send cookies and HTTP authentication: same-origin (default), include (also cross-origin) or omit

Inherited from ​

BrowserRequestOptions.credentials


deadlineMs? ​

optional deadlineMs?: number

Defined in: api/rust-fetch.d.ts:278

Total logical-request deadline, including queueing, retries and reading the body. 0 disables.


debug? ​

optional debug?: boolean | ((entry) => void)

Defined in: api/rust-fetch.d.ts:257

Structured, redacted logging; Node also supports DEBUG=rust-fetch.


dedupe? ​

optional dedupe?: boolean

Defined in: api/rust-fetch.d.ts:245

Share one request and response between identical get and head requests in flight at once. Off by default.


headers? ​

optional headers?: HeadersLike

Defined in: api/rust-fetch.d.ts:268

Headers sent with every request; per-request headers with the same name replace them


httpCache? ​

optional httpCache?: boolean | HttpCacheOptions

Defined in: api/rust-fetch.d.ts:243

An opt-in private cache for GET responses, following RFC 9111: fresh responses (Cache-Control: max-age, Expires) come from memory, stale ones with an ETag or Last-Modified are revalidated with If-None-Match / If-Modified-Since, and no-store, no-cache and Vary are honoured. Responses carry cached and revalidated. Not related to the browser's cache option. Off by default.


idempotencyHeader? ​

optional idempotencyHeader?: string

Defined in: api/rust-fetch.d.ts:296

Header carrying the key. Default: Idempotency-Key


idempotencyKey? ​

optional idempotencyKey?: string | boolean

Defined in: api/rust-fetch.d.ts:294

true generates a UUID per call; a string supplies a key. The key is reused on retries and enables POST/PATCH retries under the retry policy. Requires server support for deduplication. Default: off. An explicit client string is reused for every call; prefer true or per-request strings.


idleTimeoutMs? ​

optional idleTimeoutMs?: number

Defined in: api/rust-fetch.d.ts:276

Maximum wait for the next body chunk, including streams and SSE. 0 disables.


integrity? ​

optional integrity?: string

Defined in: api/rust-fetch.d.ts:83

Subresource integrity metadata, e.g. sha384-…

Inherited from ​

BrowserRequestOptions.integrity


keepalive? ​

optional keepalive?: boolean

Defined in: api/rust-fetch.d.ts:76

Let the request outlive the page, e.g. for analytics on unload (bodies up to 64 KB)

Inherited from ​

BrowserRequestOptions.keepalive


limitsPerOrigin? ​

optional limitsPerOrigin?: boolean

Defined in: api/rust-fetch.d.ts:336

Apply maxConcurrent/rateLimit independently to each origin. Default: false


maxConcurrent? ​

optional maxConcurrent?: number

Defined in: api/rust-fetch.d.ts:328

Maximum attempts in flight. Streams/SSE hold a slot until their body ends or is cancelled.


maxEventBytes? ​

optional maxEventBytes?: number

Defined in: api/rust-fetch.d.ts:361

events(): reject an event whose data (its data: lines, joined with \n) would be larger than this many bytes, before it's buffered. maxLineBytes limits each line; this limits their total, which an event made of many data: lines could otherwise grow without bound. The events before it are delivered, then the stream errors with a NetworkError whose maxEventBytes is the limit, and isn't reconnected. Default: no limit


maxLineBytes? ​

optional maxLineBytes?: number

Defined in: api/rust-fetch.d.ts:354

Reject a line longer than this many bytes (line break excluded) in responseType: 'ndjson' responses and events() streams, before it's buffered, so a server can't grow one line without bound. The stream errors with a NetworkError whose maxLineBytes is the limit, and the connection is closed; an event stream isn't reconnected. For events, each line (a data: line, a comment…) is checked, not an event's total. Default: no limit


maxPendingRequests? ​

optional maxPendingRequests?: number

Defined in: api/rust-fetch.d.ts:326

Reject a request at once while this client already has this many started and not yet settled, in flight or waiting (retries included), so a caller that can't keep up sheds load instead of queuing requests without bound. A streamed response counts until its headers arrive. Rejects with a NetworkError whose maxPendingRequests is the limit, before anything is sent. Applies on every transport. Default: no limit


maxRedirects? ​

optional maxRedirects?: number

Defined in: api/rust-fetch.d.ts:300

Maximum number of redirects to follow. Browsers apply their own limit (20) instead. Default: 20


maxResponseBytes? ​

optional maxResponseBytes?: number

Defined in: api/rust-fetch.d.ts:319

Reject responses whose body, after decompression, is larger than this many bytes, reading no more than that: checked against Content-Length first, then counted as the body arrives and while it's decompressed, so a decompression bomb never expands in memory. Rejects with a NetworkError whose maxResponseBytes is the limit. Applies to error responses and streamed bodies too. Default: no limit


metrics? ​

optional metrics?: boolean

Defined in: api/rust-fetch.d.ts:253

Collect bounded per-client latency/count samples from construction. Off by default.


mode? ​

optional mode?: "same-origin" | "cors" | "no-cors"

Defined in: api/rust-fetch.d.ts:72

cors (default), same-origin, or no-cors, which resolves with an opaque response (status: 0, no headers, no body)

Inherited from ​

BrowserRequestOptions.mode


onCircuitChange? ​

optional onCircuitChange?: (change) => void

Defined in: api/rust-fetch.d.ts:332

Observes transitions outside the state lock. Thrown exceptions are reported as unhandled rejections.

Parameters ​

change ​

CircuitChange

Returns ​

void


onRequestEnd? ​

optional onRequestEnd?: (entry) => void

Defined in: api/rust-fetch.d.ts:255

Parameters ​

entry ​

RequestLifecycle

Returns ​

void


onRequestStart? ​

optional onRequestStart?: (entry) => void

Defined in: api/rust-fetch.d.ts:254

Parameters ​

entry ​

RequestLifecycle

Returns ​

void


priority? ​

optional priority?: "high" | "low" | "auto"

Defined in: api/rust-fetch.d.ts:78

Fetch priority, where the browser supports it

Inherited from ​

BrowserRequestOptions.priority


propagateTrace? ​

optional propagateTrace?: boolean

Defined in: api/rust-fetch.d.ts:261

Automatic W3C propagation is off unless explicitly enabled with an origin allowlist.


proxy? ​

optional proxy?: "env" | string & object

Defined in: api/rust-fetch.d.ts:306

Node.js: send requests through an HTTP(S) proxy, either a URL (http://user:pass@proxy:8080) or 'env' for HTTPS_PROXY / HTTP_PROXY with NO_PROXY. NODE_USE_ENV_PROXY=1 is the same as 'env'. Browsers use the system's proxy settings. Default: none


rateLimit? ​

optional rateLimit?: RateLimitOptions

Defined in: api/rust-fetch.d.ts:334

Client-side token bucket. First burst is immediate; retries re-enter FIFO admission.


redactUrl? ​

optional redactUrl?: (url) => string

Defined in: api/rust-fetch.d.ts:259

Apply a custom redactor to error URLs and already-sanitized hook/log URLs.

Parameters ​

url ​

string

Returns ​

string


redirect? ​

optional redirect?: RedirectMode

Defined in: api/rust-fetch.d.ts:298

What to do when the server redirects. Default: follow


referrer? ​

optional referrer?: string

Defined in: api/rust-fetch.d.ts:80

A same-origin URL, '' for none, or about:client (default)

Inherited from ​

BrowserRequestOptions.referrer


referrerPolicy? ​

optional referrerPolicy?: "" | "origin" | "same-origin" | "no-referrer" | "no-referrer-when-downgrade" | "strict-origin" | "origin-when-cross-origin" | "strict-origin-when-cross-origin" | "unsafe-url"

Defined in: api/rust-fetch.d.ts:81

Inherited from ​

BrowserRequestOptions.referrerPolicy


responseTimeoutMs? ​

optional responseTimeoutMs?: number

Defined in: api/rust-fetch.d.ts:274

Time until final response headers arrive. 0 disables.


retries? ​

optional retries?: number | RetryOptions

Defined in: api/rust-fetch.d.ts:281

Retry failed requests: a maximum retry count, or detailed options. Default: no retries


retryBudget? ​

optional retryBudget?: boolean | RetryBudgetOptions

Defined in: api/rust-fetch.d.ts:288

Limit retries across this client, for all origins: true for the defaults, or options. First attempts are always sent. The budget is checked before waiting to retry and spent when the retry is sent, so cancelling while waiting spends nothing. A refused retry rejects with the attempt's own error, with retryBudgetExhausted: true; client.retriesRefused counts refusals. Default: no budget


sensitiveHeaders? ​

optional sensitiveHeaders?: string[]

Defined in: api/rust-fetch.d.ts:342

Header names that carry credentials (case-insensitive), e.g. ['x-api-key']. On a redirect to another origin, Node.js requests drop them along with Authorization, Cookie and Proxy-Authorization. Browsers follow redirects themselves, so this doesn't apply there. Default: none


timeoutMs? ​

optional timeoutMs?: number

Defined in: api/rust-fetch.d.ts:270

Timeout for each attempt (sending + reading the body), in ms. 0 disables it. Default: 30000


timings? ​

optional timings?: boolean

Defined in: api/rust-fetch.d.ts:251

Collect attempt and logical-request timings. Off by default.


traceContext? ​

optional traceContext?: () => TraceContext | undefined

Defined in: api/rust-fetch.d.ts:263

Returns ​

TraceContext | undefined


traceOrigins? ​

optional traceOrigins?: string[]

Defined in: api/rust-fetch.d.ts:262


transport? ​

optional transport?: (request) => PromiseLike<any>

Defined in: api/rust-fetch.d.ts:249

Answer this client's buffered requests from your own code instead of the network, keeping the retry, timeout and error behaviour. Streamed responses, events() and websocket() do not use it. Build one with createMockTransport() from rust-fetch/testing.

Parameters ​

request ​

any

Returns ​

PromiseLike<any>

Released under the MIT or Apache-2.0 license.