Guide overview
Documentation for 2.7.x
This documents rust-fetch 2.7.x. For the latest version, see the current documentation. The changelog lists what 2.8 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:
- Client options and Requests and responses: what a client holds, and what each call takes and returns.
- Errors and Timeouts, retries and cancellation: what can fail, and what the client does about it.
- Interceptors: auth headers, token refresh and logging in one place.
- What your app needs: Streaming and Server-Sent Events, Uploads, WebSockets, TypeScript.
- Before production: Security, the hardened configurations to copy, and Observability.
Client methods
import { WasmClient } from 'rust-fetch';
const client = new WasmClient({ baseUrl: 'https://api.example.com/v1' });| Method | Returns | Details |
|---|---|---|
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?) | EventStream | Server-Sent Events |
websocket(url, options?) | WebSocketConnection | WebSockets |
addRequestInterceptor(fn), addResponseInterceptor(onFulfilled?, onRejected?) | an id | Interceptors |
ejectInterceptor(id), clearInterceptors() | Interceptors | |
retriesRefused | number | Retries the retry budget refused |
stats() | ClientStats | Detached request, latency and Node connection-pool snapshots; enables collection for subsequent requests. See Observability |
Common client options
Set once, on new WasmClient({ … }). The full list is in Client options.
| Option | Default | What it does |
|---|---|---|
baseUrl | none | Relative request URLs resolve under it |
headers | none | Sent with every request; a request header with the same name wins |
timeoutMs | 30000 | Per attempt, until the last byte of the body; 0 disables it |
retries | no retries | A count, or { maxRetries, initialDelayMs, maxDelayMs, multiplier, retryOn, … } |
retryBudget | no budget | true limits retries across the client, against retry storms |
redirect, maxRedirects | 'follow', 20 | Or 'manual' / 'error' |
maxResponseBytes | no limit | Largest response body, after decompression |
maxPendingRequests | no limit | Refuse requests beyond this many unfinished ones |
allowAbsoluteUrls | true | false keeps request URLs under baseUrl |
allowPrivateNetwork | true | false blocks loopback, private and metadata addresses (Node.js) |
proxy | none | '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.
| Option | What it does |
|---|---|
body | For post, put, patch and fetch: objects become JSON; strings, bytes, Blob, FormData and URLSearchParams are sent as they are |
headers | Override client headers with the same name |
params | Appended to the query string; arrays repeat the key |
timeoutMs | Overrides the client timeout |
signal | An 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).