Skip to content

rust-fetch 2.5 ​

Documentation for 2.5.x

This is the README as published with 2.5.2, the last 2.5 release; 2.5 had no documentation site. For the latest version, see the current documentation. The changelog lists what 2.6 added; nothing in 2.x breaks code written for 2.5.

A resilient HTTP client for JavaScript and TypeScript: fetch() plus the timeouts, retries, typed errors and interceptors that production code needs, from one Rust core that behaves the same in browsers, Web Workers and Node.js.

  • Errors you can branch on. Every failure rejects with a typed Error: HttpError (with the status and response body), TimeoutError, NetworkError, CancelledError and more, so one catch handles them all.
  • Safe with servers and URLs you don't control. One option each blocks requests to private networks (SSRF, checked on the resolved address), caps response size including decompression bombs, and keeps absolute URLs from taking your credentials away from baseUrl. Header injection is rejected, and credentials never follow a redirect to another origin. Compared with fetch() and axios.
  • Timeouts and retries done right. timeoutMs covers each attempt up to the last byte of the body. Retries back off with jitter, honour Retry-After, and never repeat a POST or PATCH unless you allow it.
  • One core, every runtime. The request policy is written once in Rust and compiled to WebAssembly, so a request is validated, retried and timed out the same way in a browser tab and in a Node.js service.
  • More than fetch() offers. Interceptors, streaming, Server-Sent Events and newline-delimited JSON (for LLM and other streaming APIs), and download and upload progress.
  • One client for HTTP and WebSockets. client.websocket() shares the client's base URL, timeouts and typed errors, and adds reconnection with backoff.
  • Steady under heavy load. This matters at hundreds or thousands of requests per second; at a few requests a minute, fetch() never queues and the server's response time is all you'll see. In an independent benchmark at 15,000 requests per second, the published client's p99 latency was 11.2 ms against 450 ms for Node.js fetch(), with a third of the memory. The native transport, not in the npm package yet, reached up to 1.95× fetch()'s throughput (performance).

Quick start ​

bash
npm install rust-fetch

Node.js (20 or newer): the WebAssembly module loads on import.

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

const client = new WasmClient();
const res = await client.get('https://jsonplaceholder.typicode.com/todos/1');
console.log(res.status, res.body.title);

Browsers and bundlers: call init() once before the first request. It downloads and compiles the .wasm file.

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

await init();
const client = new WasmClient();

init() is safe to call more than once, and calling it in Node.js is harmless, so shared code can always call it. Serve the .wasm file with Content-Type: application/wasm, so the browser compiles it while it downloads, and consider preloading it (see Startup).

A client set up for production, with a base URL, timeouts, retries and error handling:

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

const api = new WasmClient({
  baseUrl: 'https://api.example.com/v1',
  timeoutMs: 10_000, // per attempt, including reading the body
  retries: 3,        // exponential backoff with jitter; honours Retry-After
});

try {
  const { body: user } = await api.get('/users/42');
} catch (error) {
  if (error.kind === 'HttpError' && error.status === 404) {
    // not found: error.body has the response text
  } else if (error.kind === 'TimeoutError') {
    // the last attempt took over 10 s, with no retries left
  } else {
    throw error;
  }
}

Release status

Contents ​

Why rust-fetch? ​

fetch() gives you a request primitive; rust-fetch gives you the policy around it. With fetch(), every caller checks res.ok, wires up an AbortSignal for timeouts, and writes its own retry loop. rust-fetch does that once, correctly, for every request.

Compared with fetch() and axios ​

fetch()axiosrust-fetch
Rejects on HTTP errors (4xx, 5xx)No, check res.okYesYes, with status and the body
TimeoutsWire up AbortSignal.timeout()timeout optiontimeoutMs per attempt, including the body; 30 s by default
Retries with backoffNoWith a plugin (axios-retry)Built in: jitter, Retry-After, no POST or PATCH retries unless enabled
InterceptorsNoYesYes
Server-Sent EventsEventSource: browsers only, GET only, no custom headersNoclient.events(): any method, headers and body, reconnection, browsers and Node.js
Download progressRead the stream yourselfYesYes
Upload progressNoYesYes
Reuses connections in Node.js by defaultYesNo, needs a keep-alive agentYes, up to 256 per origin
Blocks requests to private networks (SSRF)NoNoallowPrivateNetwork: false (Node.js)
Limits response size, including decompressionNomaxContentLengthmaxResponseBytes
Header values with CR/LFRejectedStripped silentlyRejected
Added to a browser bundle (brotli)Nothing, it's built inAbout 21 KBAbout 188 KB: the WebAssembly module (179 KB) and its JS glue

The rust-fetch column describes the JavaScript API; the Rust crate has no interceptors, upload progress or WebSockets (Rust usage).

One client for HTTP and WebSockets ​

Real-time features usually mean a second client with its own URL handling, timeouts and error handling. In rust-fetch, client.websocket() is part of the same client: it resolves against the same baseUrl, uses the same timeout for each connection attempt, and fails with the same typed errors as requests. It also adds what the platform's WebSocket lacks: reconnection with backoff after unexpected drops, a connect timeout, opened/closed promises and JSON messages (WebSockets).

Compared with undici.request() ​

undici.request(), the engine under Node's fetch(), is a lower-level, Node.js-only API. It was faster than both rust-fetch transports for small requests over plain HTTP in our tests, so it's the better choice when raw throughput is all you need and you'll build error handling, timeouts and retries yourself. rust-fetch is the better choice when you want that policy built in and the same client in browsers. Over HTTPS, the native transport matched undici.request() (30,452 against 30,546 requests per second), and on 8 MB bodies it was ahead (322 against 301).

When to choose something else ​

  • Every kilobyte counts in your browser bundle. The WebAssembly module is about 179 KB brotli-compressed.
  • You only need raw throughput in Node.js and will handle failures yourself: use undici.request() (see above).
  • Your latency is the server, not the client. If each request waits seconds on the other side (an AI model, a payment provider, a report) and you send a few a minute, no HTTP client will make it faster. rust-fetch would still give you per-attempt timeouts, retries and typed errors, but if your SDKs already do that, you don't need it.
  • Your calls go through vendor SDKs. Most payment, email and AI SDKs make their own requests. Using rust-fetch there means passing it as a custom fetch where the SDK allows that; it's simplest for calls your own code makes.
  • You need a long track record. rust-fetch 2.x is new: 2.0 to 2.5 shipped within three days in October 2026, and download counts are still small. See the stability policy for how releases work from here.
  • Your Node.js code makes one request at a time and you're considering the native transport for speed: there it's level with the node:http transport and a few percent behind fetch() (it was about 6% slower before 2.4.0).

Features ​

Unless noted, each of these works the same in browsers, Web Workers and Node.js 20+.

Reliability

  • Typed errors. Every rejection is a real Error with a kind (HttpError, TimeoutError, NetworkError, …) and details like status, body and timeoutMs, so error handling branches on data instead of parsing messages. Errors
  • Per-attempt timeouts that cover the response body, not just the headers, so a server that stalls mid-body can't hang a request. The default is 30 s. Timeouts
  • Retries with exponential backoff and jitter, so clients recovering at the same time don't hit a struggling server in lockstep. Retry-After is honoured, and POST/PATCH aren't retried unless you opt in, so a retry can't duplicate an order or a payment. Retries
  • Cancellation with AbortSignal, which also stops pending retry delays and streamed bodies, so an abandoned request releases its resources. Cancellation
  • Interceptors for requests and responses: add auth headers, refresh tokens and report errors in one place. Interceptors

Requests and responses

  • Request bodies from strings, bytes, Blob/File, FormData (multipart with files), URLSearchParams or JSON, with the matching Content-Type set for you. Request bodies
  • Response decoding by Content-Type (including application/*+json), or forced to json, text, binary or stream. Responses
  • Streaming responses as a ReadableStream, and download progress callbacks, for large downloads. Streaming
  • Server-Sent Events with client.events(): in browsers and Node.js, with any method, headers and body (as streaming LLM APIs need), JSON data, reconnection with Last-Event-ID, and for await. Newline-delimited JSON with responseType: 'ndjson'. Server-Sent Events
  • Upload progress callbacks, for progress bars on large uploads, which fetch() can't report. Upload progress

Real-time

  • WebSockets on the same client: the same base URL, timeouts and typed errors as your requests, plus reconnection with jittered backoff after unexpected drops. Browsers and Node.js 22+. WebSockets

Node.js

  • A bounded connection pool: up to 256 keep-alive connections per origin, so traffic bursts queue and reuse connections instead of exhausting local ports. Connection pooling
  • A native transport (not in the npm package yet; build it from source) that moves connection work off the event loop for more throughput under concurrency, and steps aside automatically for custom agents and proxies. Architecture

Tooling and quality

  • TypeScript definitions for the whole API, and the same client as a Rust library.
  • Tested with 100% line and function coverage of the Rust core and of the Node.js transport, enforced in CI, and with the JS suites on Node.js 20, 22 and 24. Development

Performance ​

All results are from local servers over loopback, so they compare each client's own overhead, not network performance. Percentages are relative throughput (requests per second), not latency. Two sources:

  • Our measurements of the node:http transport that the npm package uses and of the native transport (not in the npm package yet), next to Node's fetch() and undici.request(). Apple M1 Pro, Node.js 22.13.
  • An independent benchmark of the published rust-fetch 2.1.0 against fetch() and axios. Apple M4 Pro, Node.js 22.15.

These results are about Node.js. In browsers, fetch() is the only way to make requests, so rust-fetch uses it and can't be faster than it; the difference is a fraction of a millisecond per request, which matters little once a request crosses a real network.

The npm package today ​

rust-fetch as published (2.1.x, node:http transport) against Node.js fetch(). The independent column is summarized from the full report below; ours from the all-client tables:

WorkloadIndependent benchmark (2.1.0, M4 Pro)Our measurements (M1 Pro)
Steady 15,000 requests/sp99 11.2 ms against 450 ms; slowest request 64 ms against 1.5 s; 202 MB against 635 MB of memory (one run)Independent harness: kept up (14,981/s against 13,026/s); p50 6.3 ms against 449 ms; p99 565 ms against 920 ms; event-loop delay 9.8 ms against 310 ms. Our harness: 12,955/s against 11,557/s, but a worse p99 (1.6 s against 1.2 s)
50 to 500 requests in flight105% to 116% throughput at every level107% to 114%, with a lower p99 at every level
Overload (offered 40,000 and 50,000 requests/s)Found a port-exhaustion bug in 2.1.0, fixed in 2.1.11.7× and 1.4× the requests delivered
8 MB binary bodies115% (faster in 10 of 10 runs)133%
0.6 MB JSON105% (faster in 10 of 10 runs)95%
Small JSON, one at a time100%102%
Small JSON, 50 at a time91%105% (500 at a time: 112%)
HTTPS small JSON, 50 at a timenot tested92%

The published client matches fetch() one request at a time, is ahead with large binary bodies and many requests in flight, and stays steadier under sustained load in tail latency and memory. It's behind on concurrent HTTPS, and in one of the two 15,000 requests/s harnesses its tail was worse.

The same independent harness later re-tested 2.2.0 (below): ahead of fetch() in all four throughput workloads (102% to 112%), including 50 requests at a time, where 2.1.0 was at 91%, and at an offered 50,000 requests/s it delivered 1.3 times fetch()'s requests with no errors and a third less memory.

Independent benchmark of rust-fetch 2.2.0 ​

aakjp/stress-test re-ran its benchmark on rust-fetch 2.2.0 (node:http transport) against Node's fetch() and axios 1.20, on Apple silicon with Node.js 22.15, against a local HTTP/1.1 server. The report has its method and raw data.

Throughput, requests per second, medians of 10 runs:

Workloadfetch()rust-fetch 2.2.0axios (default)rust-fetch vs fetch()
Small JSON, one at a time10,00210,3897,831104% (faster in 8 of 10 runs)
Small JSON, 50 at a time14,82115,18811,037102% (6 of 10)
Large JSON (0.6 MB)449473436105% (10 of 10)
Binary (8 MB)188210199112% (10 of 10)

Against fetch() in the same runs, 2.1.0 had scored 100%, 91%, 105% and 115%: the clear change is 50 requests at a time, from 91% to 102%. The report also compares 2.2.0's raw numbers with 2.1.0's (+4.5% to +7.3%), but fetch()'s own numbers moved by up to 9% between those runs, so we read the ratios.

Overload: an offered 50,000 requests/s for 60 s:

ClientDeliveredp50p99ErrorsPeak memory
rust-fetch 2.2.021,341/s461 ms505 ms0604 MB
fetch()16,158/s352 ms832 ms2,166913 MB
axios (keep-alive)13,763/s716 ms786 ms0754 MB
axios (default)3,113/s2.6 s10.5 s149,749912 MB

The improvement over 2.1.0 at this load (3,493/s with 172,942 errors) comes from the bounded connection pool released in 2.1.1, after the first report found the port exhaustion; 2.2.0 includes it. The report's verification suite also checked 2.2.0's new features (typed requests, upload progress, WebSockets with reconnection and typed errors): 19 of 19 checks passed, and 2.1.0 code ran unchanged.

Independent benchmark of rust-fetch 2.1.0 ​

aakjp/stress-test compared the published client, rust-fetch 2.1.0 (node:http transport), with Node's built-in fetch() and axios 1.20, on an Apple M4 Pro with Node.js 22.15, against a local HTTP/1.1 server without TLS or compression. The full report has its method and raw data.

Throughput, requests per second, median of 10 runs:

Workloadfetch()rust-fetchaxiosrust-fetch vs fetch()
Small JSON, one at a time9,6499,6807,497100%
Small JSON, 50 at a time15,52914,1919,90291%
Large JSON (0.6 MB)426446407105% (faster in 10 of 10 runs)
Binary (8 MB)174201188115% (faster in 10 of 10 runs)

With each client in its own process and a constant number of requests in flight, rust-fetch was ahead of fetch() at every level (one run per level):

Requests in flight50100200500
fetch()22,80022,39021,18119,019
rust-fetch23,97723,88223,45422,064
axios (default)14,73714,51913,44912,461

A steady 15,000 requests per second for 60 seconds (one run):

ClientDeliveredErrorsp50p99SlowestPeak memory
rust-fetch15,001/s04.7 ms11.2 ms64 ms202 MB
fetch()14,944/s03.1 ms450 ms1,545 ms635 MB
axios (keep-alive agent, 128 sockets)14,578/s0669 ms718 ms731 ms761 MB
axios (default)3,292/s165,4402.4 s13 s14 s843 MB

fetch() had the fastest median, but its slowest requests took up to 1.5 s, and its tail varied tenfold between runs. axios with its default configuration ran out of local ports: Node's default agent keeps connections alive (since Node.js 19) but sets no socket limit, so under overload it kept opening new ones. The keep-alive axios row used an agent capped at 128 sockets, against rust-fetch's 256 per origin, so it compares connection limits as well as clients. The report's 15,000 requests per second was 89% of what its server could handle.

Overload at 50,000 requests per second, two to three times what any client could sustain on the M4 Pro, found a bug: rust-fetch 2.1.0 opened a new connection for every waiting request, ran out of local ports and delivered 3.2k requests per second, while fetch() delivered 14.4k. 2.1.1 fixed it with a pool of up to 256 connections per origin, so extra requests wait instead. In our re-run of that test on an Apple M1 Pro (Node.js 22.13), rust-fetch went from 2.7k requests per second and 43.5k errors to 18.9k and none.

The report tested three clients on one machine. It didn't include undici.request(), got or ky.

The native transport (not in the npm package yet) ​

The native Node.js transport against Node.js fetch(), from our measurements (Apple M1 Pro, Node.js 22.13). The npm package doesn't include it yet; it has to be built from source.

WorkloadNative transport vs fetch()
HTTPS, 50 concurrent small-JSON requests1.95× throughput
500 concurrent small-JSON requests1.89× throughput
50 concurrent small-JSON requests1.71× throughput
8 MB binary transfers1.61× throughput
Offered 40,000 requests/s (overload)2.9× requests delivered
50 to 500 requests in flight, independent harness1.6× to 1.7× throughput, about half the p99 at every level
Event loop at 15,000 requests/s, independent harness1.6 ms p95 delay against 310 ms, leaving the event loop free for your application
Steady 15,000 requests/s, our harnessKept up (14,992/s against 11,557/s), about 13× lower p99 (91 ms against 1.2 s) and about 4× less memory (195 MB against 782 MB)
Steady 15,000 requests/s, independent harnessKept up (14,991/s against 13,026/s); p99 568 ms against 920 ms; 541 MB against 903 MB
Large JSON, 0.6 MB1.02×, even
Sequential small-JSON requests0.94×, about 6% slower (before 2.4.0; see below)

Since 2.4.0 the native transport runs on a single Tokio worker thread, with large compressed bodies decoded on a separate blocking pool. Each request is a short burst of work, so more workers mostly added cross-thread wake-ups. Measured against the previous build in fresh processes over 5 interleaved rounds (npm run bench:compare): sequential small JSON +7.3%, now level with the node:http transport (11,220 against 11,126 requests/s); 8 MB bodies +5.5%; 50 concurrent unchanged; and at an offered 40,000 requests/s, +9% delivered (34,827 against 31,970/s) with a lower p99 (281 against 316 ms). The table above predates this change.

Why concurrency is where it wins. With the node:http transport, connection handling, HTTP parsing and decompression share the JavaScript event loop with your application. The native transport runs them on its own threads, leaving the event loop free to build requests and decode responses. With one request at a time there's little to overlap, and the hand-off between threads costs a little. How much you gain depends on your hardware, payloads and concurrency.

Where it doesn't win: sequential requests were about 6% slower than with fetch() and the node:http transport before 2.4.0, and are now level with the node:http transport; large JSON is effectively even (304 against 299 requests per second), and both parse the JSON in JavaScript; and under heavy overload it used about as much memory as fetch() (796 MB against 781 MB).

Our measurements: every client ​

The tables behind both summaries: Node's fetch(), undici.request() and both rust-fetch transports, measured together on an Apple M1 Pro with Node.js 22.13.

Throughput: all clients ​

All four clients ran in the same rounds, in rotating order, against a server in a separate process (HTTP/1.1, and HTTPS where noted). Requests per second, median of 7 rounds:

Workloadfetch()undici.request()rust-fetch, node:httprust-fetch, nativeNative vs fetch()
Small JSON, sequential10,46815,34610,6919,85794% (6% slower)
Small JSON, 50 concurrent18,01942,26018,91630,874171%
Small JSON, 500 concurrent15,41938,17117,28529,209189%
HTTPS small JSON, 50 concurrent15,63930,54614,44430,452195%
Large JSON, 0.6 MB299325283304102%
Binary, 8 MB201301267322161%

In the three concurrent workloads, the native transport's p99 latency was less than half of fetch()'s (50 concurrent: 2.41 ms against 5.38 ms; 500 concurrent: 23.45 ms against 58.64 ms; HTTPS: 2.44 ms against 6.46 ms). For large JSON it was higher (8.76 ms against 5.39 ms).

Under load: all clients ​

Each client ran in its own process. These rows come from two different harnesses and aren't comparable with each other:

Testfetch()undici.request()rust-fetch, node:httprust-fetch, nativeNative vs fetch()
Offered 40,000 requests/s for 20 s, delivered (our harness)10,081/s37,687/s16,984/s29,502/s2.9×
Offered 50,000 requests/s for 60 s, delivered (aakjp/stress-test harness)12,421/snot tested17,828/s32,678/s2.6×

Concurrency sweep, a constant number of requests in flight for 10 s each (aakjp/stress-test harness), requests per second with p99 latency:

Requests in flightfetch()rust-fetch, node:httprust-fetch, nativeNative vs fetch()
5017,041 (6.8 ms)18,452 (6.1 ms)29,198 (2.4 ms)171%
10017,660 (10.2 ms)18,855 (9.3 ms)28,402 (5.1 ms)161%
20016,365 (24.3 ms)18,624 (14.8 ms)28,454 (11.3 ms)174%
50015,960 (47.3 ms)17,685 (38.7 ms)27,563 (24.6 ms)173%

At 40,000 requests per second, peak memory was 781 MB for fetch(), 244 MB for undici.request(), 567 MB for the node:http transport and 796 MB for the native transport, whose queued requests wait inside the addon.

A steady 15,000 requests per second, sent on a fixed schedule whether or not the client keeps up. No client had errors. Our harness (20 s, one server process):

ClientDeliveredp50p95p99Peak memory
fetch()11,557/s477 ms779 ms1.2 s782 MB
undici.request()14,992/s2.4 ms11 ms31 ms135 MB
rust-fetch, node:http12,955/s404 ms1.1 s1.6 s541 MB
rust-fetch, native14,992/s4.1 ms46 ms91 ms195 MB

The aakjp/stress-test harness (60 s, six server processes):

ClientDeliveredp50p95p99Peak memoryJS heap after the runEvent-loop delay (p95)
fetch()13,026/s449 ms491 ms920 ms903 MB479 MB310 ms
rust-fetch, node:http14,981/s6.3 ms118 ms565 ms548 MB82 MB9.8 ms
rust-fetch, native14,991/s3.5 ms4.8 ms568 ms541 MB23 MB1.6 ms

Event-loop delay is how late the harness's 10 ms scheduler ran: how long your own code would wait behind the HTTP client.

In both harnesses, the native transport sustained approximately the target rate and fetch() didn't. In the independent harness, both rust-fetch transports still show a p99 stall of about 565 ms even though the native transport's p95 was 4.8 ms. Its cause hasn't been verified.

Startup ​

How long until the first response, from a fresh Node.js process or a fresh page (npm run bench:cold; median of 7 samples, local server, Apple M1 Pro, Node.js 22.13). Import is importing the package, or init() in browsers; first request is the first get() of a small JSON response.

RuntimeClientImport / init()First requestTotal
Node.jsfetch()—21.9 ms21.9 ms
Node.jsrust-fetch, node:http transport18.3 ms9.3 ms27.6 ms
Node.jsrust-fetch, native transport20.2 ms5.3 ms25.5 ms
Chromiumrust-fetch, empty cache8.3 ms6.6 ms14.9 ms
Chromiumrust-fetch, cached2.4 ms1.3 ms3.7 ms
Firefoxrust-fetch, empty cache15.0 ms3.0 ms18.0 ms
Firefoxrust-fetch, cached13.0 ms3.0 ms16.0 ms
WebKitrust-fetch, empty cache10.0 ms5.0 ms15.0 ms
WebKitrust-fetch, cached7.0 ms3.0 ms10.0 ms
  • Node.js: about 13 ms of the import is Node.js loading node:http, which fetch() pays too, on its first call (it loads undici lazily). rust-fetch's own share is about 7 ms: compiling the WebAssembly module (about 1 ms, since V8 compiles functions on first use), its JS glue, and loading the native addon. All told, the first response arrives 4 to 6 ms later than with fetch().

  • Browsers: init() streams the module into the compiler as it downloads (WebAssembly.instantiateStreaming, which needs Content-Type: application/wasm). Chromium also caches the compiled code, so a returning visit costs a few milliseconds. The numbers above don't include download time. On a real network, start the download early by preloading the file from your page's <head>:

    html
    <link rel="preload" href="/assets/rust_fetch_bg.wasm" as="fetch" type="application/wasm" crossorigin>

    Use the URL your bundler gives the file. With Vite, for example, import wasmUrl from 'rust-fetch/rust_fetch_bg.wasm?url' returns it, and init({ module_or_path: wasmUrl }) then loads that same URL.

Reading these results ​

  • Throughput, latency and memory are separate questions. A client can deliver more requests per second with a worse tail, or the reverse; memory is the peak resident size of the client process.
  • fetch(), undici.request() and rust-fetch do different amounts of work. Node's fetch() implements the browser fetch() API on top of undici. undici.request() is undici's lower-level API, without WHATWG streams. rust-fetch adds retries, per-attempt timeouts, validation, typed errors and interceptors to every request. So undici.request() isn't an identical workload, and it was fastest on plain HTTP in these tests: 1.4 to 2.2 times the node:http transport's small-JSON throughput and 1.3 to 1.6 times the native transport's, while over HTTPS the native transport matched it.
  • Results vary with hardware, Node.js version, payload size, concurrency and the server setup. The node:http transport delivered 12,955 requests per second at an offered 15,000 in one harness and 14,981 in the other, so measure on your own hardware before relying on a number (how).

Usage and configuration ​

The examples in this section use a client like this one:

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

const client = new WasmClient({ baseUrl: 'https://api.example.com/v1' });

Client options ​

ts
const client = new WasmClient({
  baseUrl: 'https://api.example.com/v1', // relative request URLs are appended to this
  headers: { Authorization: 'Bearer …' }, // sent with every request
  timeoutMs: 10_000,                      // per attempt; 0 disables. Default: 30000
  retries: 3,                             // or a RetryOptions object, see Retries
  redirect: 'follow',                     // or 'manual' / 'error', see Redirects. Default: 'follow'
  maxRedirects: 20,                       // Node.js; browsers apply their own limit. Default: 20
  proxy: 'env',                           // Node.js: HTTPS_PROXY / HTTP_PROXY / NO_PROXY, or a proxy URL; see Proxies
  allowAbsoluteUrls: false,               // reject absolute URLs instead of letting them replace baseUrl; see Security. Default: true
});

Proxies ​

In Node.js, requests can go through an HTTP or HTTPS proxy: HTTPS requests through a CONNECT tunnel, so the proxy never sees their contents, and plain HTTP requests as absolute-URL requests.

js
new WasmClient({ proxy: 'env' });                              // HTTPS_PROXY, HTTP_PROXY and NO_PROXY (or lower case)
new WasmClient({ proxy: 'http://user:pass@proxy.internal:3128' }); // every request; credentials as Proxy-Authorization
  • 'env' reads the variables on each request: HTTPS_PROXY for https: URLs, HTTP_PROXY for http: ones, and skips hosts in NO_PROXY. A NO_PROXY entry is *, a host name (which also covers its subdomains; a leading . or *. is optional) or an IP address (matched exactly), each with an optional :port.
  • NODE_USE_ENV_PROXY=1, which Node.js uses for its own fetch(), turns on 'env' for clients without a proxy option.
  • Proxied requests use the node:http transport, with a pool of connections per proxy. This includes streamed responses ('stream', 'ndjson') and events().
  • Browsers use the system's proxy settings and ignore this option.

Invalid options throw an InvalidInputError right away, from the constructor.

Making requests ​

MethodUse
get(url, options?), head(url, options?), delete(url, options?)Requests without a body
post(url, init?), put(url, init?), patch(url, init?)init.body is the body; any other request option can go next to it
fetch(url, init?)fetch-style, with init.method (default GET)
post_json, put_json, patch_json(url, body, options?)Always send body as JSON
request(method, url, headers?, body?, options?)Fully positional
js
await client.post('/users', { body: { name: 'Zoë' } });
await client.get('/search', { params: { q: 'rust wasm', page: 2, tag: ['a', 'b'] } }); // ?q=rust+wasm&page=2&tag=a&tag=b
await client.fetch('/users/1', { method: 'DELETE', headers: { 'X-Reason': 'cleanup' } });

Relative URLs need a baseUrl. In a browser page without one, they resolve against the page URL. Absolute URLs always win over baseUrl. TRACE and CONNECT are rejected, because browsers' fetch() forbids them.

Request options ​

OptionTypeDescription
headersobject, Headers, Map or [name, value][]Override client headers with the same name. Numbers and booleans are converted to strings.
paramsobject or URLSearchParamsAppended to the query string. Arrays repeat the key; null/undefined are skipped.
timeoutMsnumberOverrides the client timeout; 0 disables it
responseType'auto' | 'json' | 'text' | 'binary' | 'stream' | 'ndjson'See Responses
signalAbortSignalSee Cancellation
onDownloadProgress({ loaded, total }) => voidSee Download progress
onUploadProgress({ loaded, total }) => voidSee Upload progress
redirect'follow' | 'manual' | 'error'Overrides the client's; see Redirects
maxRedirectsnumberOverrides the client's; see Redirects
credentials, mode, cache, keepalive, priority, referrer, referrerPolicy, integrityas in fetch()Browsers; see Browser request options

Browser request options ​

In browsers, Web Workers and other fetch() runtimes (Deno, Bun), the standard fetch() options are passed through: set them on the client for every request, or per request, where each one overrides the client's.

js
const api = new WasmClient({ baseUrl: 'https://api.example.com', credentials: 'include' }); // send cookies cross-origin
await api.get('/feed', { cache: 'no-store' });                     // bypass the HTTP cache
await api.post('/analytics', { body: event, keepalive: true });    // outlives the page
await api.get('https://cdn.example.com/ping', { mode: 'no-cors' }); // opaque: status 0, no headers or body
OptionValues
credentials'same-origin' (default), 'include' (cross-origin too; the server must send Access-Control-Allow-Credentials: true and its exact origin), 'omit'
mode'cors' (default), 'same-origin', 'no-cors' (resolves with an opaque response: status: 0, ok: false, no headers, body: null)
cache'default', 'no-store', 'reload', 'no-cache', 'force-cache', 'only-if-cached'
keepalivetrue lets the request outlive the page (browsers limit these bodies to 64 KB)
priority'high', 'low', 'auto'
referrer, referrerPolicy, integrityAs in fetch()

They apply to every request, streamed responses and client.events(). With upload progress, which uses XMLHttpRequest, credentials: 'include' becomes withCredentials. For the other options, or credentials: 'omit', the request goes through fetch() instead, so upload progress is reported once. Node.js requests don't use these options; invalid values still throw an InvalidInputError there.

Redirects ​

Redirects (301, 302, 303, 307 and 308) are followed the way fetch() follows them: a 303, or a 301 or 302 after POST, becomes a GET without a body, and res.url is the final URL. In Node.js, Authorization, Cookie and Proxy-Authorization headers are dropped when a redirect leaves the origin; browsers apply their own rules.

redirectWhat happens
'follow' (default)Follow up to maxRedirects redirects (default 20); one more rejects with a NetworkError
'manual'Resolve with the redirect response itself, with ok: false and its Location header
'error'Reject with a NetworkError on any redirect (the same as maxRedirects: 0)
js
const res = await client.get('/login', { redirect: 'manual' });
if (!res.ok) console.log(res.status, res.headers.location); // 302 '/sso?…'

In browsers, fetch() hides redirects from scripts: with 'manual' the response has status: 0 and no headers, and the browser's own limit (20) applies instead of maxRedirects. With upload progress in browsers, they send the request with fetch() instead of XMLHttpRequest (which always follows redirects), so upload progress is reported once.

Request bodies ​

The body's type decides how it's sent. A Content-Type header you set yourself is always kept, except for FormData, which needs its own boundary.

BodySent asDefault Content-Type
stringas-istext/plain
Uint8Array, ArrayBuffer, DataView, Bufferbytesapplication/octet-stream
Blob / Filebytesthe blob's type
FormDatamultipart/form-data, including filesmultipart/form-data; boundary=…
URLSearchParamsform-encodedapplication/x-www-form-urlencoded;charset=UTF-8
anything else (objects, arrays, numbers, booleans)JSON.stringifyapplication/json

null and undefined mean no body. The *_json methods are the exception: they always send JSON, so post_json(url, null) sends null. ReadableStream request bodies aren't supported; send a Blob or bytes instead.

Responses ​

Successful (2xx) requests, and redirects with redirect: 'manual', resolve to:

ts
interface HttpResponse<T = any> {
  status: number;          // 200
  statusText: string;      // "OK"
  ok: boolean;             // true; false only for a redirect with redirect: 'manual'. Other non-2xx responses reject with an HttpError
  url: string;             // final URL after redirects
  headers: Record<string, string>; // lower-cased names; repeated headers joined with ", "
  body: T;
}

With the default responseType: 'auto', body is:

  • parsed JSON for application/json and application/*+json (e.g. problem+json), falling back to text if it isn't valid JSON
  • a string for text/*, XML, JavaScript and form-encoded responses
  • a Uint8Array for anything else
  • null when the body is empty (e.g. 204 or HEAD)

Force a type with responseType: 'json' (fails with a ParseError if the body isn't JSON), 'text', 'binary', 'stream' or 'ndjson' (see Streaming). JSON is parsed by the JS engine's JSON.parse, exactly like Response.json().

Errors ​

Every rejection is an Error whose name and kind are one of:

kindWhenExtra fields
HttpErrorNon-2xx responsestatus, statusText, body (full response body as text)
TimeoutErrorAn attempt exceeded timeoutMstimeoutMs
NetworkErrorDNS, connection, TLS or CORS failure, a body cut off mid-transfer, or a WebSocket that fails to connect or drops
CancelledErrorThe signal was aborted
InvalidInputErrorBad URL, method, header, option or body. Rejected before anything is sent.parameter
ParseErrorresponseType: 'json' and the body isn't JSON
JsInteropErrorUnexpected JS ↔ Wasm conversion failure
js
try {
  await client.get('/users/9');
} catch (error) {
  if (error.kind === 'HttpError' && error.status === 404) {
    // not found
  } else if (error.kind === 'TimeoutError') {
    console.warn(`gave up after ${error.timeoutMs} ms`);
  } else {
    throw error;
  }
}

Long error bodies (such as an HTML error page) are truncated to 200 characters in message. error.body always has the full text.

Timeouts ​

timeoutMs limits each attempt, from sending the request to receiving the last byte of the body. When retries are on, each attempt gets the full timeout. For responseType: 'stream', the timeout covers only the wait for the headers; after that, reading the stream is up to you.

Retries ​

Retries are off by default. retries: 3 enables them with these defaults; pass an object to change them:

ts
new WasmClient({
  retries: {
    maxRetries: 3,          // retries after the first attempt
    initialDelayMs: 100,    // first backoff
    maxDelayMs: 10_000,     // cap for any delay, including Retry-After
    multiplier: 2,          // exponential backoff: 100, 200, 400 … ms, each randomized to 50–100%
    retryOn: [408, 429, 500, 502, 503, 504],
    retryOnNetworkError: true,
    retryOnTimeout: true,
    retryNonIdempotent: false, // set to true to also retry POST and PATCH
  },
});
  • A Retry-After header in seconds is honoured, capped at maxDelayMs.
  • POST and PATCH aren't retried by default. The server may already have acted on a failed attempt, so retrying can duplicate work.
  • InvalidInputError, ParseError and unlisted statuses are never retried.
  • When every attempt fails, the request rejects with the last attempt's error.

Cancellation ​

js
const controller = new AbortController();
const request = client.get('/report', { signal: controller.signal });
controller.abort();
try {
  await request;
} catch (error) {
  console.log(error.kind); // 'CancelledError'
}

await client.get('/report', { signal: AbortSignal.timeout(5_000) }); // total deadline, including retries

Aborting cancels the request in flight, any pending retry delay, and a body being streamed.

Interceptors ​

js
const token = 'your-access-token'; // e.g. from your auth flow

// Add a header to every request (may be async)
client.addRequestInterceptor((request) => {
  request.headers.authorization = `Bearer ${token}`;
  // mutate in place, or return a new { method, url, headers, body }
});

// Resolve to the body instead of the whole response
client.addResponseInterceptor((response) => response.body);

// Report failures, then keep rejecting
client.addResponseInterceptor(undefined, (error) => {
  console.error('request failed:', error.kind, error.message);
  throw error;
});

An onRejected handler can also recover by returning a value, for example the result of retrying the request after refreshing a token.

  • Request interceptors run in order before each request. They see { method, url, headers, body }, where headers holds the per-request headers. Client default headers are added afterwards, and a request header with the same name wins.
  • Response interceptors chain like promise.then(onFulfilled, onRejected). Their return values are what the call resolves to. Throw to reject.
  • addRequestInterceptor and addResponseInterceptor return an id for ejectInterceptor(id). clearInterceptors() removes all of them.
  • A request uses the interceptors registered when it started.
  • Interceptors apply to HTTP requests, not to WebSockets.

Streaming ​

responseType: 'stream' resolves as soon as the headers arrive. body is then a ReadableStream<Uint8Array>:

js
const res = await client.get('/export.csv', { responseType: 'stream' });
let received = 0;
for await (const chunk of res.body) {
  received += chunk.byteLength; // each chunk is a Uint8Array
}
console.log(`${received} bytes`);

for await over a stream works in Node.js, Chrome and Firefox. Safari doesn't support it yet, so use res.body.getReader() there. Retries apply until the headers arrive, and error statuses still reject with an HttpError.

Newline-delimited JSON (NDJSON, JSON Lines), as streamed by Ollama, many search and log APIs, and Kubernetes watches: with responseType: 'ndjson', body is a ReadableStream of parsed values, one per line, as each line arrives:

js
const res = await client.post('/api/generate', { body: { model: 'llama3', prompt: 'Why is the sky blue?' }, responseType: 'ndjson' });
for await (const chunk of res.body) {
  console.log(chunk.response);
}

Lines may be split across network chunks, end in \n or \r\n, and the last one doesn't need a newline; empty lines are skipped. A line that isn't JSON errors the stream with a ParseError naming the line number.

Server-Sent Events ​

client.events() reads a Server-Sent Events stream. Unlike the browser's EventSource, it works in Node.js too, sends any method, headers and body, and uses the client's base URL, interceptors, timeouts and typed errors.

js
// A streaming LLM API: POST a JSON body, read JSON events until `data: [DONE]`
const stream = client.events('/v1/chat/completions', {
  method: 'POST',
  body: { model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Hello' }], stream: true },
  headers: { authorization: 'Bearer your-api-key' },
  messageType: 'json',
});
for await (const { data } of stream) {
  console.log(data.choices[0].delta.content ?? '');
}

// A notification feed: callbacks, reconnecting with Last-Event-ID
const feed = client.events('/notifications', {
  onEvent: ({ event, data, id }) => console.log(event, data, id),
  onError: (error) => console.warn(error.kind, error.message),
});
await feed.opened;
feed.close();

Each event is { event, data, id }: event is 'message' unless the server set one, data is the data: lines joined with \n (or parsed JSON with messageType: 'json'), and id is the last event ID. Events go to onEvent when it's set; otherwise they're buffered for for await, and break closes the stream.

OptionDescription
method, body, headers, params, timeoutMsAs for requests. timeoutMs covers each connection attempt until the response headers arrive
reconnectReconnect after the stream ends or a connection fails, sending Last-Event-ID and waiting the server's retry: delay (otherwise backing off like WebSockets). true, a maximum number of attempts in a row, or { maxRetries, initialDelayMs, maxDelayMs, multiplier }. Default: on for GET, off for other methods, which would resend their body
messageType'auto' (default: data is a string) or 'json'
endClose the stream normally when an event's data equals this. Default: '[DONE]' with messageType: 'json'
signalCloses the stream and stops reconnecting when aborted
onOpen, onEvent, onError, onReconnect, onCloseCallbacks; onClose runs once, when the stream is closed for good

The stream also has url, state ('connecting', 'open', 'reconnecting' or 'closed'), lastEventId, and opened and closed promises. Failures are typed: a refused connection or dropped stream is a NetworkError, a response that isn't text/event-stream a ParseError, an error status an HttpError (408, 429 and 5xx are reconnected after, others end the stream), and a 204 No Content ends it normally. With messageType: 'json', a data that isn't JSON goes to onError; when iterating, it ends the stream with the ParseError. Request interceptors run before each connection.

Download progress ​

js
await client.get('/video.mp4', {
  responseType: 'binary',
  onDownloadProgress: ({ loaded, total }) => {
    console.log(total ? `${Math.round((loaded / total) * 100)}%` : `${loaded} bytes`);
  },
});

The callback runs after each chunk of a successful response, including streamed ones. total comes from Content-Length and is null when the server doesn't send it. Exceptions thrown by the callback are ignored.

File uploads ​

Pass a FormData and it's sent as multipart/form-data, files included:

js
const form = new FormData();
form.append('title', 'Quarterly report');
form.append('file', new File(['%PDF-1.7 …'], 'report.pdf', { type: 'application/pdf' })); // or a file from <input type="file">
await client.post('/upload', { body: form });

A single Blob or File body is sent as raw bytes with the blob's type.

Upload progress ​

Report how much of a request body has been sent, for example to drive a progress bar:

js
const form = new FormData();
form.append('video', new Blob([new Uint8Array(50_000_000)]), 'video.mp4');

await client.post('/upload', {
  body: form,
  onUploadProgress: ({ loaded, total }) => {
    console.log(`${Math.round((loaded / total) * 100)}% uploaded`);
  },
});

loaded is the number of body bytes sent so far and total is the body's size. A retried request starts again from 0. Exceptions thrown by the callback are ignored, and requests without a body report nothing. It works with onDownloadProgress on the same request, but not with responseType: 'stream'.

How it's sent:

  • Browsers: fetch() has no upload progress events, so these requests go through XMLHttpRequest, with the same redirects, credentials, timeouts, retries and errors. Like any XMLHttpRequest with an upload listener, a cross-origin request is always preflighted, so the server must answer OPTIONS. Where XMLHttpRequest doesn't exist (service workers), progress is reported once, when the response arrives.
  • Node.js: the node:http transport (never the native one) writes the body in 64 KB chunks and reports each once it has been handed to the operating system.

WebSockets ​

Available in browsers and in Node.js 22 and newer (Node.js 20 needs --experimental-websocket).

js
const socket = client.websocket('/live', {     // wss://api.example.com/v1/live?room=blue
  params: { room: 'blue' },
  messageType: 'json',                         // parse text messages as JSON
  reconnect: true,                             // after failures and unexpected drops, 1 s doubling to 30 s
  onMessage: (message) => console.log('received', message),
  onError: (error) => console.warn(error.kind, error.message),
  onReconnect: ({ attempt, delayMs }) => console.log(`reconnecting in ${delayMs} ms (attempt ${attempt})`),
});

await socket.opened;                           // rejects with a typed error if it never connects
socket.sendJson({ type: 'subscribe', channel: 'prices' });
socket.close();                                // stops reconnecting
const { code, reason, wasClean } = await socket.closed;

In Node.js you can authenticate the handshake with headers, which browsers don't allow:

js
const authed = client.websocket('/live', { headers: { authorization: 'Bearer your-access-token' } }); // Node.js only

websocket() resolves relative URLs against baseUrl, turning http: into ws: and https: into wss:, and returns at once; messages sent before the connection opens (or while it reconnects) are queued. state is 'connecting', 'open', 'reconnecting', 'closing' or 'closed'.

OptionDescription
protocolsSubprotocols to offer; the chosen one is socket.protocol
paramsAppended to the query string
headersHandshake headers, merged over the client's. Node.js only: browsers don't allow WebSocket headers, so passing them there throws an InvalidInputError, and the client's headers aren't sent
dispatcherNode.js only: an undici dispatcher for the connection, e.g. new ProxyAgent('http://proxy:3128') to connect through a proxy (see below). Browsers use the system's proxy settings, so passing one there throws an InvalidInputError
timeoutMsTime allowed for each connection attempt; defaults to the client's timeoutMs, 0 disables it
reconnecttrue, a maximum number of attempts in a row, or { maxRetries, initialDelayMs, maxDelayMs, multiplier } (defaults: unlimited, 1000, 30000, 2). Off by default
messageType'auto' (default: text as strings, binary as Uint8Array) or 'json'
signalCloses the connection and stops reconnecting when aborted
onOpen, onMessage, onError, onReconnect, onCloseCallbacks; onClose runs once, when the connection is closed for good

Failures are typed like request errors: a refused or failed connection is a NetworkError, an attempt that takes too long a TimeoutError, a JSON message that doesn't parse a ParseError, and closing before the first connection opens rejects opened with a CancelledError. With reconnect, a failed attempt or an unexpected drop (close codes 1001, 1006 and 1011–1014) is retried with jittered exponential backoff, and the count resets once a connection opens. A server that closes normally (1000) or with its own code isn't reconnected to. An exception thrown by a callback doesn't affect the connection; it's reported as an unhandled promise rejection. As with an exception in a handler of the platform's own WebSocket, Node.js then ends the process unless you handle it (process.on('unhandledRejection', …)), so catch errors inside your callbacks.

send() takes a string, ArrayBuffer, typed array, DataView or Blob; sendJson() takes any JSON value. close(code, reason) takes 1000 (the default) or 3000–4999.

TypeScript ​

Type definitions ship with the package and need TypeScript 5.2 or newer. Besides WasmClient, it exports the option and result types ClientOptions, RequestOptions, FetchInit, RetryOptions, HttpResponse, RustFetchError, DownloadProgress, UploadProgress and InterceptedRequest, for WebSockets WebSocketConnection, WebSocketOptions, ReconnectOptions, WebSocketCloseInfo, WebSocketReconnectInfo, WebSocketState and WebSocketData, and for Server-Sent Events EventStream, EventStreamOptions, EventStreamState and ServerSentEvent.

Every request method takes the response body's type as a type parameter, defaulting to any:

ts
import { WasmClient, type HttpResponse, type RustFetchError } from 'rust-fetch';

const client = new WasmClient({ baseUrl: 'https://api.example.com/v1' });

interface User { id: number; name: string }

const res = await client.get<User>('/users/42'); // HttpResponse<User>
res.body.name; // string

const created: HttpResponse<User> = await client.post<User>('/users', { body: { name: 'Zoë' } });

try {
  await client.get('/users/9');
} catch (e) {
  const error = e as RustFetchError;
  if (error.kind === 'HttpError') console.log(error.status);
}

The type parameter describes what you expect; rust-fetch doesn't check the JSON against it. Validate untrusted responses with a schema library if you need to.

Legacy functions ​

These standalone functions still work. Each call uses a default client: 30 s timeout, no retries.

FunctionResolves to
fetch_json(url) / fetch_json_promise(url)Parsed JSON, whatever the Content-Type; null for an empty body
fetch_text(url)The body as a string
fetch_with_options(url, method, headers, body?)The full HttpResponse
create_client()new WasmClient()
fetch_wasm_json, fetch_wasm_map, fetch_wasm_api, fetch_wasm_htmlDeprecated aliases of fetch_json / fetch_text

Security ​

What the client does for you, each behaviour covered by tests:

  • Credentials stay with their origin on redirects. When a redirect leaves the origin (another host, port or scheme, including https: to http:), the Node.js transports drop Authorization, Cookie and Proxy-Authorization. This is the class of bug behind CVEs in node-fetch, follow-redirects and undici. Browsers apply their own, equivalent rules.
  • No header injection. A header name or value containing CR or LF rejects with an InvalidInputError before anything is sent.
  • Only http: and https:. Request URLs, baseUrl, and redirect targets with any other scheme (file:, data:, …) are rejected.
  • Paths stay under baseUrl. Relative paths, including tricks like //other.host/x or /\other.host, resolve under the base URL (the class of axios CVE-2024-39338).
  • Proxy credentials go only to the proxy. They're sent as Proxy-Authorization to the proxy, never to the origin.
  • No runtime dependencies. The npm package has none, and every release is published from CI with npm provenance. Rust dependencies are audited in CI (cargo-deny: advisories, licenses, sources).

Security compared with fetch() and axios ​

The same attacks against each client, with the protections it offers turned on (npm run security:compare; Node.js 22.13, axios 1.20). Each rust-fetch row is also a regression test in CI (wasm-module/js/test/security.test.mjs), named after the advisories it covers.

Attackrust-fetchNode's fetch()axios
Credentials on a cross-origin redirect (node-fetch CVE-2022-0235, follow-redirects CVE-2022-0536 and CVE-2024-28849, undici CVE-2023-45143 and CVE-2024-24758)droppeddroppeddropped
CR/LF in a header (undici CVE-2022-31150, CVE-2022-35948)rejected before sendingrejectedstripped silently
Path tricks with a base URL (axios CVE-2024-39338)stay on the base hostno base URLstay on the base host
Absolute URL with a base URL (axios CVE-2025-27152)blocked with allowAbsoluteUrls: falseno base URLblocked with allowAbsoluteUrls: false
Redirect to file:refusedrefusedrefused
256 MB gzip bombrejected with maxResponseBytes, +3 MB of memoryno limit available: accepted, +853 MBrejected with maxContentLength, +2 MB
Request to the cloud metadata endpoint 169.254.169.254 (SSRF)blocked with allowPrivateNetwork: falseno built-in checkno built-in check
Runtime dependenciesnonebuilt in4

Only rust-fetch blocks SSRF before connecting, and rejects header injection instead of altering the header. Like axios, and unlike fetch(), it can bound a response's size. Every protection that isn't on by default (absolute URLs, size, private networks) is one option away.

Absolute URLs and baseUrl ​

By default, as in axios, an absolute URL passed to a client with a baseUrl replaces the base URL, and receives the client's headers, such as Authorization. If any part of a request URL comes from user input, an attacker can send it to their own server along with your credentials (the class of axios CVE-2025-27152). Turn it off:

js
const api = new WasmClient({
  baseUrl: 'https://api.example.com/v1',
  headers: { authorization: `Bearer ${token}` },
  allowAbsoluteUrls: false,
});
await api.get(`/users/${userInput}`);   // stays on api.example.com
await api.get('https://evil.example/'); // rejects with InvalidInputError (parameter: 'url'); nothing is sent
await api.get('https://partner.example/data', { allowAbsoluteUrls: true }); // per request, deliberately

allowAbsoluteUrls applies to requests, client.events() and client.websocket(), and can be set per request. In Rust, it's ClientBuilder::allow_absolute_urls(false).

Response size limits and decompression bombs ​

A server, or anyone who controls a URL you fetch, can send an endless body, or a few kilobytes of gzip that decompress to gigabytes, and exhaust your process's memory. fetch() has no way to limit either. Set maxResponseBytes:

js
const client = new WasmClient({ maxResponseBytes: 10 * 1024 * 1024 });        // 10 MB, for every request
await client.get('/export', { maxResponseBytes: 500 * 1024 * 1024 });         // per request
await client.get('/trusted', { maxResponseBytes: null });                     // no limit for this one
// → NetworkError "Response body larger than maxResponseBytes (10485760 bytes)", error.maxResponseBytes === 10485760

The limit is on the decompressed body, and it's enforced on every transport (node:http, native, browser fetch()), without reading more than needed:

  • A Content-Length over the limit fails before the body is read. For a compressed body, the limit applies to its decompressed size.
  • Without a Content-Length, the body is counted as it arrives, and reading stops at the limit.
  • Decompression is bounded too: zlib, brotli and zstd stop one byte past the limit. A 64 MB gzip bomb with a 1 MB limit fails without expanding in memory (tested for gzip, deflate, brotli and zstd).
  • Error responses and streamed bodies (responseType: 'stream' | 'ndjson') are limited the same way; a stream errors once it passes the limit. In browsers, a request with onUploadProgress and a limit uses fetch() instead of XMLHttpRequest, which can't stop at a limit.

The default is no limit, as before. For servers that fetch URLs they don't control, set one.

Fetching user-supplied URLs (SSRF) ​

A server that fetches URLs its users give it (webhooks, link previews, image proxies, importers) can be pointed at its own network: http://169.254.169.254/ (cloud credentials), http://localhost:6379/, an admin panel on 10.0.0.5. Checking the URL string isn't enough: a public-looking name can resolve to a private address, and a redirect can point anywhere. In Node.js, set allowPrivateNetwork: false:

js
const fetcher = new WasmClient({ allowPrivateNetwork: false, maxResponseBytes: 5 * 1024 * 1024, timeoutMs: 10_000 });
await fetcher.get(userUrl); // NetworkError "Blocked: … resolves to 10.0.0.5, a private or reserved address" for internal targets
  • Every address is checked when connecting: the host's DNS answers (all of them), or the IP address itself. So DNS rebinding can't get past it, and each redirect is checked again.
  • Blocked ranges:
    • IPv4: loopback, RFC 1918 private, link-local (including the 169.254.169.254 metadata endpoint), carrier-grade NAT, "this network", multicast, reserved and documentation ranges
    • IPv6: loopback, unspecified, unique-local, link-local and multicast, plus IPv4-mapped (::ffff:10.0.0.1) and NAT64 (64:ff9b::…) forms of the IPv4 ranges
  • Separate connection pool: checked requests never reuse a connection another client made to a private address.
  • Proxies: through a proxy, only IP-address targets are checked, since the proxy resolves names. Apply the same rule in the proxy's own configuration.
  • Not covered: client.websocket() connections (Node's built-in WebSocket). In browsers this option does nothing; they enforce their own private-network rules.
  • Combine it with limits: use maxResponseBytes, timeoutMs and allowAbsoluteUrls (above) when fetching anything untrusted.

Using it from Rust ​

The same client is a Rust library, for native code (on tokio) and for your own wasm crates:

rust
use rust_fetch::{Client, Multipart, types::RetryConfig};
use std::time::Duration;

let client = Client::builder()
    .base_url("https://api.example.com/v1")
    .timeout(Duration::from_secs(10))
    .retry_config(RetryConfig { max_retries: 3, ..Default::default() })
    .build()?;

let user = client.get("users/42").await?;
println!("{}", user.json().unwrap()["name"]);

let pdf: Vec<u8> = std::fs::read("report.pdf")?;
let form = Multipart::new().text("title", "Report").file("file", "report.pdf", Some("application/pdf".into()), pdf);
client.post("upload").multipart(&form).send().await?;

let mut chunks = client.get_streaming("export.csv").await?.into_stream(); // a futures::Stream of Vec<u8>

Redirects: .redirect(Redirect::Manual) or Redirect::Error, and .max_redirects(n) (default 20), on the ClientBuilder or per request on the RequestBuilder.

Request futures are Send, so you can tokio::spawn them. Progress callbacks (on_download_progress) must be Send + Sync on native targets. Upload progress, WebSockets and interceptors are only in the JavaScript API.

Architecture ​

Everything that decides what happens to a request (URL handling, validation, retries and backoff, per-attempt timeouts, typed errors, interceptors) is Rust compiled to WebAssembly, so it behaves the same in every runtime. Underneath, a transport only moves bytes:

TransportWhereIn the npm package
The platform's fetch()Browsers and Web WorkersYes
XMLHttpRequestBrowsers, for upload progressYes
node:http / node:https with keep-aliveNode.jsYes
The runtime's WebSocket, with the connection policy (URL, timeout, reconnection, errors) in RustWebSockets, everywhereYes
Native addon: HTTP/1.1 on hyper and Tokio threads, loaded through Node-API, with the same redirect, decompression, timeout and connection-limit rules and Node's TLS defaults (Mozilla root certificates, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED)Node.jsNot yet: build it with npm run build:native

Which transport a request uses:

RequestBrowsersNode.js
Most requestsfetch()The native transport where it's built and Node's global agents are untouched; otherwise node:http
With onUploadProgress (with or without onDownloadProgress)XMLHttpRequest, or fetch() where there's nonenode:http
With onDownloadProgress only, responseType: 'stream' or 'ndjson', and client.events()fetch()node:http (since 2.4.0; it was Node's fetch() before)

What the native transport changes. Connection handling, TLS, HTTP parsing and decompression move from the JavaScript event loop to Tokio threads; JavaScript only builds requests and decodes their bodies. That's why it gains most with many requests in flight, and why the hand-off between threads likely contributes to its slower sequential results (measurements).

When it's used. The native transport is used when rust-fetch-native.<platform>-<arch>.node sits next to the package's node.js (npm run build:native puts it there). It steps aside where you have installed your own http.globalAgent / https.globalAgent (for example a proxy agent) or set NODE_USE_ENV_PROXY, and RUST_FETCH_NATIVE=0 turns it off.

Connection pooling ​

Browsers pool connections for fetch(). In Node.js, both transports keep up to 256 keep-alive connections per origin and queue further requests until one is free, so bursts reuse connections instead of exhausting local ports. If you install your own http.globalAgent / https.globalAgent, or set limits on Node's, that agent is used instead.

Compatibility and limitations ​

Supported environments ​

EnvironmentStatus
Browsers, Web Workers and service workersSupported, directly or through bundlers like Vite and webpack; call init() first. Tested in CI in Chromium, Firefox and WebKit (Safari's engine), on pages, in dedicated workers and in module service workers. fetch() options such as credentials and cache are passed through
Node.js 20, 22 and 24Supported and tested in CI; Node.js 20 is the minimum
TypeScriptDefinitions included; TypeScript 5.2 or newer
Upload progress, WebSocketsJavaScript API only, from 2.2.0. WebSockets need a built-in WebSocket: browsers, Node.js 22+, or Node.js 20 with --experimental-websocket. Tested in CI on Node.js 22 and 24
RustThe same client as a Rust library (usage), on tokio or in your own wasm crates
Native Node.js transportIn the repository, not yet in the npm package (no prebuilt binaries); build it with npm run build:native. Tested in CI on Linux with Node.js 20, 22 and 24, and run on macOS (Apple silicon); not tried on Windows

Limitations ​

  • Bundle size: the WebAssembly module adds about 179 KB (brotli) to a browser bundle, plus 9 KB of JS glue.

  • HTTP/2: browsers negotiate it automatically; both Node.js transports use HTTP/1.1 with keep-alive.

  • Proxies: in Node.js, use the proxy option or NODE_USE_ENV_PROXY=1; a proxy agent installed as http.globalAgent / https.globalAgent (for example from https-proxy-agent) works too. In browsers, use the system settings.

  • Native transport: has to be built from source for each platform until it's published. Sequential requests are level with the node:http transport (they were about 6% slower than fetch() before 2.4.0). It isn't used for streamed responses or requests with progress callbacks, and the p99 stall seen in the independent harness is unexplained (see Under load).

  • WebSockets use the runtime's own WebSocket: built into browsers and Node.js 22 and newer, and into Node.js 20 only with --experimental-websocket (without it, websocket() throws a NetworkError). In Node.js it doesn't go through http.globalAgent or the client's proxy option; pass an undici ProxyAgent as dispatcher to connect through a proxy:

    js
    import { ProxyAgent } from 'undici'; // npm install undici
    const socket = client.websocket('wss://stream.example.com/', { dispatcher: new ProxyAgent(process.env.HTTPS_PROXY) });
  • Upload progress in browsers needs XMLHttpRequest, which makes cross-origin requests preflighted (see Upload progress).

Upgrading to 2.0 ​

2.0 fixes long-standing bugs, and some code may have depended on the old behaviour. Check these points:

  • Timeouts are enforced in browsers and Node.js. In 1.x the 30 s default was silently ignored, so slow requests never failed. For long downloads, set timeoutMs higher, or to 0 to disable it.
  • WasmClient JSON bodies are plain objects, not Maps: use body.title, not body.get('title'). JSON with integers above 2^53 no longer fails the request.
  • More responses are decoded: application/*+json (e.g. problem+json) is parsed as JSON instead of returned as bytes, and empty bodies are null.
  • Errors are real Error objects. kind, message, status and the other fields are unchanged, and name equals kind. Like any Error, message isn't enumerable, so JSON.stringify(error) leaves it out.
  • Invalid headers values reject with an InvalidInputError; they used to be dropped silently. Numbers and booleans are converted to strings.
  • Text is decoded as UTF-8, whatever the charset in Content-Type. Invalid bytes become �.
  • The package uses an exports map. Import rust-fetch, rust-fetch/rust_fetch.js or rust-fetch/rust_fetch_bg.wasm.
  • Node.js 20+ is required. In Node.js you no longer need to load the .wasm file yourself; init() is optional there.

These changed too, but are unlikely to break anything:

  • POST and PATCH aren't retried by default (retryNonIdempotent: true re-enables it).
  • Your Content-Type is no longer duplicated.
  • fetch_json parses JSON whatever the Content-Type.
  • Invalid URLs, and TRACE/CONNECT, fail fast with an InvalidInputError.

Rust crate users:

  • RetryConfig has a new field, so add ..Default::default() to struct literals.
  • Method::to_reqwest() returns reqwest 0.13's Method.
  • RequestBuilder::header() replaces a default header with the same name instead of adding a second value.

1.x keeps receiving critical fixes on the v1.x branch (npm install rust-fetch@1).

Stability and releases ​

  • Semantic versioning, staying on 2.x. Nothing in 2.x breaks existing code: new behaviour is opt-in, defaults don't change, and the TypeScript API and the Rust API are checked against the previous release in CI (api/rust-fetch.d.ts, cargo-semver-checks). A breaking change would wait for 3.0, with a migration guide and at least one 2.x release warning about it first.
  • Fewer, larger releases. 2.0 to 2.5 shipped within three days in October 2026, while the project was getting started. From 2.6.0, minor releases come at most every two weeks. Patch releases are only for regressions and security fixes, each with a test that reproduces the problem.
  • What gets fixed. The latest 2.x minor release gets bug and security fixes. Security issues are handled privately, as described in SECURITY.md.
  • How a release is checked. Every release is built and published from CI with npm provenance, after the Rust and JavaScript suites (100% line coverage enforced for the Rust core and the Node.js transport), real-browser tests in Chromium, Firefox and WebKit, the security regression tests, and the size and API checks. Each pull request is also benchmarked against the previous version.
  • What changed and why. CHANGELOG.md lists every change, including performance regressions and their fixes (2.4.1), and ROADMAP.md shows what's next.

Development and benchmarking ​

The npm package is built from wasm-module/ with wasm-pack; the native transport is built from native/. The repository root is a private workspace.

bash
npm run build      # wasm-pack build + package metadata (wasm-module/pkg)
npm run build:native  # build the native Node.js transport (native/) into wasm-module/pkg
npm test           # Rust unit + integration tests, then the JS tests
npm run test:js    # JS end-to-end tests against the built package (requires a build)
npm run test:browsers  # the same package in Chromium, Firefox and WebKit (requires a build and npx playwright install)
npm run bench      # rust-fetch vs native fetch (requires a build)
npm run size       # size budget for the built package
npm run api:check  # public TypeScript API vs the committed snapshot
npm run coverage:js  # Node.js transport coverage (100% lines and functions)

cd wasm-module
wasm-pack test --node    # wasm unit tests for the JS bindings
cargo llvm-cov --ignore-filename-regex 'src/(wasm/|http\.rs)|tests/'   # coverage
SuiteWhereWhat
Rust unit testswasm-module/src/**URL handling, retry policy, decoding, errors, multipart
Rust integration testswasm-module/tests/integration_tests.rsReal HTTP against a local server: retries, timeouts, redirects, chunked/truncated/large bodies, streaming, progress, concurrency
Wasm unit testswasm-module/src/wasm/tests.rsJS conversions, bodies, options, interceptors, timers and abort signals in Node.js
JS end-to-end testswasm-module/js/test/client.test.mjsThe built package against a local server
Node transport testswasm-module/js/test/node-transport.test.mjsRedirects, decompression, default headers, connection pooling and HTTPS. With client.test.mjs, they run once per Node.js transport: native (when built) and node:http (the *-js.test.mjs files)
Browser transport testswasm-module/js/test/browser-transport.test.mjsThe browser entry without the Node.js transport: fetch(), and XMLHttpRequest (simulated over node:http) for upload progress
WebSocket testswasm-module/js/test/websocket.test.mjswebsocket() against a local WebSocket server: URLs, headers, messages, timeouts, reconnection, closing
Real-browser testswasm-module/js/test/browsers.test.mjsThe browser entry in Chromium, Firefox and WebKit (Playwright): requests and typed errors, timeouts, retries, cancellation, streaming, Server-Sent Events and NDJSON, download progress, upload progress with a cross-origin preflight, WebSockets, and the same client in a dedicated worker and a module service worker. npm run test:browsers after npx playwright install
Package testswasm-module/js/test/package.test.mjsInstalls the packed tarball and uses it via import, require, the browser entry and its types

CI runs the Rust suites with a coverage gate that fails if line or function coverage of the Rust core, or of the Node.js transport, drops below 100%. It also runs the wasm and JS suites on Node.js 20, 22 and 24 (against both Node.js transports), and checks formatting, lints of the native transport, dependencies (security advisories and licenses), API compatibility and the size budget. The JS-only bindings in src/wasm/ and src/http.rs need a JS engine, so they're covered by the wasm and JS suites instead.

Benchmarks ​

npm run bench compares rust-fetch with Node's fetch() on a local server, and npm run bench:cold measures startup in Node.js and, when Playwright's browsers are installed, Chromium, Firefox and WebKit. It measures the native transport when it's built (npm run build:native); run it with RUST_FETCH_NATIVE=0 to measure the node:http transport. For sustained load and overload, the aakjp/stress-test harness runs against any installed version of rust-fetch.

Every pull request also compares itself with its base branch in CI: small JSON (sequential and 50 concurrent), an 8 MB body and startup, on both Node.js transports, plus the browser bundle size. Each measurement runs in a fresh process, alternating the two builds over 5 rounds; the table is in the Benchmarks job's summary. A change over 10% worse in the median and in most rounds shows as a warning, never a failure, since shared runners are noisy. To reproduce it locally against main:

sh
git worktree add ../rust-fetch-main main
(cd ../rust-fetch-main && npm ci && npm run build && npm run build:native)
npm run build && npm run build:native
npm run bench:compare -- ../rust-fetch-main/wasm-module/pkg

FAQ ​

How do I add retries and timeouts to fetch()? Use rust-fetch's client instead: new WasmClient({ timeoutMs: 10_000, retries: 3 }) times out each attempt (including the body) and retries network errors, timeouts and 408/429/5xx responses with exponential backoff and jitter, honouring Retry-After. POST and PATCH aren't retried unless you opt in. See Timeouts and Retries.

Is rust-fetch an alternative to axios? Yes, for most uses: it rejects on HTTP errors, has interceptors, timeouts, upload and download progress, and adds built-in retries, typed errors and WebSockets, with the same client in browsers and Node.js. axios is much smaller in a browser bundle (about 21 KB against 188 KB brotli). See Compared with fetch() and axios.

Does it work in browsers and Node.js? Both, with the same API: browsers and Web Workers (through bundlers such as Vite and webpack; call init() first) and Node.js 20, 22 and 24. TypeScript definitions are included. See Supported environments.

Is it faster than fetch()? In Node.js, the published client matches fetch() one request at a time and is ahead with large bodies, many requests in flight and sustained load, but behind on concurrent HTTPS. The native transport, not in the npm package yet, reached up to 1.95× fetch()'s throughput. In browsers it uses fetch() itself. See Performance.

How do I track upload progress? Pass onUploadProgress: ({ loaded, total }) => … to post, put or patch. See Upload progress.

How do I stream a response from an LLM API? For Server-Sent Events APIs (OpenAI-compatible and others), use client.events(url, { method: 'POST', body, messageType: 'json' }) and for await over it; it stops at data: [DONE]. For newline-delimited JSON APIs such as Ollama, use responseType: 'ndjson'. Both work in browsers and Node.js. See Server-Sent Events.

How do I reconnect a WebSocket automatically?client.websocket(url, { reconnect: true }) reconnects after failures and unexpected drops with exponential backoff, and reports failures as typed errors. See WebSockets.

How do I type the response body in TypeScript?client.get<User>('/users/42') resolves to HttpResponse<User>. See TypeScript.

Do I need to know Rust? No. The npm package is used from JavaScript or TypeScript like any other; Rust is only how the core is built. Rust developers can also use the crate directly.

Contributing and license ​

Contributions are welcome. See CONTRIBUTING.md for the development process and pull request checks, and SECURITY.md to report a vulnerability. Releases are published by CI when a version tag is pushed; see CONTRIBUTING.md. Planned work is in the roadmap.

Licensed under either of MIT or Apache-2.0, at your option.

Released under the MIT or Apache-2.0 license.