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?
optionalallowAbsoluteUrls?: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?
optionalallowInsecureRedirects?: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?
optionalallowPrivateNetwork?: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?
optionalauth?: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?
optionalbaseUrl?: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?
optionalcache?:"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
circuitBreaker?
optionalcircuitBreaker?:CircuitBreakerOptions
Defined in: api/rust-fetch.d.ts:330
Opt-in per-origin circuit breaker. Off by default; counts failed attempts including retries.
connectTimeoutMs?
optionalconnectTimeoutMs?: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?
optionalcredentials?:"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?
optionaldeadlineMs?:number
Defined in: api/rust-fetch.d.ts:278
Total logical-request deadline, including queueing, retries and reading the body. 0 disables.
debug?
optionaldebug?:boolean| ((entry) =>void)
Defined in: api/rust-fetch.d.ts:257
Structured, redacted logging; Node also supports DEBUG=rust-fetch.
dedupe?
optionaldedupe?: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?
optionalheaders?:HeadersLike
Defined in: api/rust-fetch.d.ts:268
Headers sent with every request; per-request headers with the same name replace them
httpCache?
optionalhttpCache?: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?
optionalidempotencyHeader?:string
Defined in: api/rust-fetch.d.ts:296
Header carrying the key. Default: Idempotency-Key
idempotencyKey?
optionalidempotencyKey?: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?
optionalidleTimeoutMs?:number
Defined in: api/rust-fetch.d.ts:276
Maximum wait for the next body chunk, including streams and SSE. 0 disables.
integrity?
optionalintegrity?:string
Defined in: api/rust-fetch.d.ts:83
Subresource integrity metadata, e.g. sha384-…
Inherited from
BrowserRequestOptions.integrity
keepalive?
optionalkeepalive?: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?
optionallimitsPerOrigin?:boolean
Defined in: api/rust-fetch.d.ts:336
Apply maxConcurrent/rateLimit independently to each origin. Default: false
maxConcurrent?
optionalmaxConcurrent?: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?
optionalmaxEventBytes?: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?
optionalmaxLineBytes?: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?
optionalmaxPendingRequests?: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?
optionalmaxRedirects?: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?
optionalmaxResponseBytes?: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?
optionalmetrics?:boolean
Defined in: api/rust-fetch.d.ts:253
Collect bounded per-client latency/count samples from construction. Off by default.
mode?
optionalmode?:"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
onCircuitChange?
optionalonCircuitChange?: (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
Returns
void
onRequestEnd?
optionalonRequestEnd?: (entry) =>void
Defined in: api/rust-fetch.d.ts:255
Parameters
entry
Returns
void
onRequestStart?
optionalonRequestStart?: (entry) =>void
Defined in: api/rust-fetch.d.ts:254
Parameters
entry
Returns
void
priority?
optionalpriority?:"high"|"low"|"auto"
Defined in: api/rust-fetch.d.ts:78
Fetch priority, where the browser supports it
Inherited from
BrowserRequestOptions.priority
propagateTrace?
optionalpropagateTrace?:boolean
Defined in: api/rust-fetch.d.ts:261
Automatic W3C propagation is off unless explicitly enabled with an origin allowlist.
proxy?
optionalproxy?:"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?
optionalrateLimit?:RateLimitOptions
Defined in: api/rust-fetch.d.ts:334
Client-side token bucket. First burst is immediate; retries re-enter FIFO admission.
redactUrl?
optionalredactUrl?: (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?
optionalredirect?:RedirectMode
Defined in: api/rust-fetch.d.ts:298
What to do when the server redirects. Default: follow
referrer?
optionalreferrer?:string
Defined in: api/rust-fetch.d.ts:80
A same-origin URL, '' for none, or about:client (default)
Inherited from
BrowserRequestOptions.referrer
referrerPolicy?
optionalreferrerPolicy?:""|"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?
optionalresponseTimeoutMs?:number
Defined in: api/rust-fetch.d.ts:274
Time until final response headers arrive. 0 disables.
retries?
optionalretries?:number|RetryOptions
Defined in: api/rust-fetch.d.ts:281
Retry failed requests: a maximum retry count, or detailed options. Default: no retries
retryBudget?
optionalretryBudget?: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?
optionalsensitiveHeaders?: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?
optionaltimeoutMs?: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?
optionaltimings?:boolean
Defined in: api/rust-fetch.d.ts:251
Collect attempt and logical-request timings. Off by default.
traceContext?
optionaltraceContext?: () =>TraceContext|undefined
Defined in: api/rust-fetch.d.ts:263
Returns
TraceContext | undefined
traceOrigins?
optionaltraceOrigins?:string[]
Defined in: api/rust-fetch.d.ts:262
transport?
optionaltransport?: (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>