Skip to content

Guide overview ​

Documentation for 2.6.x

This documents rust-fetch 2.6.x. For the latest version, see the current documentation. The changelog lists what 2.7 added.

Every method and the options you'll use most, on one page, with links to the details. New to rust-fetch? Start with Getting started, then read in this order:

  1. Client options and Requests and responses: what a client holds, and what each call takes and returns.
  2. Errors and Timeouts, retries and cancellation: what can fail, and what the client does about it.
  3. Interceptors: auth headers, token refresh and logging in one place.
  4. What your app needs: Streaming and Server-Sent Events, Uploads, WebSockets, TypeScript.
  5. Before production: Security, and the hardened configurations to copy.

Client methods ​

js
import { WasmClient } from 'rust-fetch';

const client = new WasmClient({ baseUrl: 'https://api.example.com/v1' });
MethodReturnsDetails
get, head, delete(url, options?)Promise<HttpResponse>Making requests
post, put, patch(url, { body, ...options })Promise<HttpResponse>Request bodies
fetch(url, { method, body, ...options })Promise<HttpResponse>Making requests
post_json, put_json, patch_json(url, body, options?)Promise<HttpResponse>Always send body as JSON
request(method, url, headers?, body?, options?)Promise<HttpResponse>Fully positional
events(url, options?)EventStreamServer-Sent Events
websocket(url, options?)WebSocketConnectionWebSockets
addRequestInterceptor(fn), addResponseInterceptor(onFulfilled?, onRejected?)an idInterceptors
ejectInterceptor(id), clearInterceptors()Interceptors
retriesRefusednumberRetries the retry budget refused

Common client options ​

Set once, on new WasmClient({ … }). The full list is in Client options.

OptionDefaultWhat it does
baseUrlnoneRelative request URLs resolve under it
headersnoneSent with every request; a request header with the same name wins
timeoutMs30000Per attempt, until the last byte of the body; 0 disables it
retriesno retriesA count, or { maxRetries, initialDelayMs, maxDelayMs, multiplier, retryOn, … }
retryBudgetno budgettrue limits retries across the client, against retry storms
redirect, maxRedirects'follow', 20Or 'manual' / 'error'
maxResponseBytesno limitLargest response body, after decompression
maxPendingRequestsno limitRefuse requests beyond this many unfinished ones
allowAbsoluteUrlstruefalse keeps request URLs under baseUrl
allowPrivateNetworktruefalse blocks loopback, private and metadata addresses (Node.js)
proxynone'env' or a proxy URL (Node.js)

Common request options ​

Passed to each call; most override the client option of the same name. The full list is in Request options.

OptionWhat it does
bodyFor post, put, patch and fetch: objects become JSON; strings, bytes, Blob, FormData and URLSearchParams are sent as they are
headersOverride client headers with the same name
paramsAppended to the query string; arrays repeat the key
timeoutMsOverrides the client timeout
signalAn AbortSignal that cancels the request, its retries and its body
responseType'auto' (by Content-Type), 'json', 'text', 'binary', 'stream' or 'ndjson'
onDownloadProgress, onUploadProgress({ loaded, total }) => void

What a request resolves to ​

A 2xx response (or a redirect, with redirect: 'manual') resolves to { status, statusText, ok, url, headers, body }, with lower-cased header names and body decoded by Content-Type (Responses). Anything else rejects with an Error whose kind is HttpError, TimeoutError, NetworkError, CancelledError, InvalidInputError, ParseError or JsInteropError (Errors).

Released under the MIT or Apache-2.0 license.