# Undici

> ![Node CI](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) ![neostandard javascript style](https://github.com/neostandard/neostandard) ![npm version](https://badge.fury.io/js/undici) ![codecov](https://codecov.io/gh/nodejs/undici)

## Documentation

- [undici](https://undici-website.vercel.app/): ![Node CI](https://github.com/nodejs/undici/actions/workflows/nodejs.yml) ![neostandard javascript style](https://github.com/neostandard/neostandard) ![npm version](https://badge.fury.io/js/undici) ![codecov](https://codecov.io/gh/nodejs/undici)
- [Getting Started](https://undici-website.vercel.app/getting-started.html): The quickest way to get started is with `fetch`, which follows the Fetch Standard and works the same way as the browser API:
- [Undici Module vs. Node.js Built-in Fetch](https://undici-website.vercel.app/best-practices/undici-vs-builtin-fetch.html): Node.js has shipped a built-in `fetch()` implementation powered by undici since Node.js v18. This guide explains the relationship between the `undici` npm package and the built-in `fetch`, and when you should install one versus relying on the other.
- [Migrating from Undici 7 to 8](https://undici-website.vercel.app/best-practices/migrating-from-v7-to-v8.html): This guide covers the changes you are most likely to hit when upgrading an application or library from Undici v7 to v8.
- [Client certificate](https://undici-website.vercel.app/best-practices/client-certificate.html): Client certificate authentication can be configured with the `Client`, the required options are passed along through the `connect` option.
- [Crawling](https://undici-website.vercel.app/best-practices/crawling.html): RFC 9309 defines crawlers as automated clients.
- [Mocking Request](https://undici-website.vercel.app/best-practices/mocking-request.html): Undici has its own mocking utility. It allow us to intercept undici HTTP requests and return mocked values instead. It can be useful for testing purposes.
- [Connecting through a proxy](https://undici-website.vercel.app/best-practices/proxy.html): Connecting through a proxy is possible by:
- [Writing tests](https://undici-website.vercel.app/best-practices/writing-tests.html): Undici is tuned for a production use case and its default will keep a socket open for a few seconds after an HTTP request is completed to remove the overhead of opening up a new socket. These settings that makes Undici shine in production are not a good fit for using Undici in automated tests, as it will result in longer execution times.
- [Agent](https://undici-website.vercel.app/api/Agent.html): An `Agent` dispatches requests against multiple different origins, creating and reusing a per-origin [`Pool`][] (or [`Client`][]) on demand. It is the default dispatcher used by [`request`][], [`stream`][], and [`fetch`][] when no explicit dispatcher is supplied.
- [BalancedPool](https://undici-website.vercel.app/api/BalancedPool.html): A `BalancedPool` distributes requests across a set of {Pool} instances, each connected to a different upstream. It uses a weighted round-robin algorithm: every upstream starts with the same weight, and the weight is adjusted up on successful connections and down on connection errors, so that healthy upstreams receive a larger share of traffic.
- [CacheStorage](https://undici-website.vercel.app/api/CacheStorage.html): undici provides a spec-compliant implementation of the [W3C Service Worker `CacheStorage`][] and [`Cache`][] interfaces. A `CacheStorage` is a named collection of [`Cache`][] objects, each of which stores `Request`/`Response` pairs.
- [Cache Store](https://undici-website.vercel.app/api/CacheStore.html): A cache store is the storage backend used by the cache interceptor to persist and retrieve cached responses. A store decides which stored response to serve for a request by comparing the request against the response's `Vary` header, and is expected to be compliant with [RFC 9111][].
- [Client](https://undici-website.vercel.app/api/Client.html): A basic HTTP/1.1 client mapped on top of a single TCP/TLS connection. When the server supports HTTP/2 and selects it during ALPN negotiation, the same connection is used for HTTP/2. Pipelining is disabled by default.
- [ClientStats](https://undici-website.vercel.app/api/ClientStats.html): A `ClientStats` is a point-in-time snapshot of the connection and request state of a single [`Client`][]. Instances are not created directly; a fresh snapshot is produced each time the [`client.stats`][] getter is read.
- [Connector](https://undici-website.vercel.app/api/Connector.html): undici opens the underlying socket for every request through a *connector*. By default this is handled internally, so most applications never interact with the connector directly. When a request needs additional control over the socket — for example to inspect a TLS certificate, pin a CA fingerprint, or tunnel the connection — a custom connector can be supplied through the `connect` option of a [`Dispatcher`][].
- [MIME Type Parsing](https://undici-website.vercel.app/api/ContentType.html): undici exposes helpers for parsing and serializing MIME types according to the WHATWG [MIME Sniffing Standard][]. These are the same primitives undici uses internally to interpret `Content-Type` headers and `data:` URLs.
- [Cookies](https://undici-website.vercel.app/api/Cookies.html): A set of helpers for reading and writing HTTP cookies on a [`Headers`][] instance, following the [RFC 6265bis][] cookie parsing and serialization algorithm. They operate on the `Cookie` request header and the `Set-Cookie` response header.
- [Debug](https://undici-website.vercel.app/api/Debug.html): Undici emits human-readable debug logs through Node.js' built-in [`util.debuglog()`][]. The logs are disabled by default and are turned on by listing one or more namespaces in the `NODE_DEBUG` environment variable. Because `util.debuglog()` reads `NODE_DEBUG` once, when the namespace is first used, the variable must be set before the process starts.
- [Diagnostics Channel Support](https://undici-website.vercel.app/api/DiagnosticsChannel.html): Undici is instrumented with Node.js' built-in [`diagnostics_channel`][] module. It is the preferred way to observe undici's internal behaviour without patching the library, and it backs the human-readable [debug logs][Debug].
- [Dispatcher](https://undici-website.vercel.app/api/Dispatcher.html): `Dispatcher` is the core abstraction used to dispatch HTTP requests in undici. It extends [`EventEmitter`][] and defines the low-level [`dispatch()`][] contract along with the higher-level [`request()`][], [`stream()`][], [`pipeline()`][], [`connect()`][], and [`upgrade()`][] methods that every concrete dispatcher provides.
- [EnvHttpProxyAgent](https://undici-website.vercel.app/api/EnvHttpProxyAgent.html): `EnvHttpProxyAgent` is a [`Dispatcher`][] that reads its proxy configuration from the `http_proxy`, `https_proxy`, and `no_proxy` environment variables and routes requests through the appropriate proxy automatically. Import it from `undici`:
- [Errors](https://undici-website.vercel.app/api/Errors.html): undici raises typed error objects so that failures can be distinguished programmatically. Every error class is exposed through the `errors` namespace of the package:
- [EventSource](https://undici-website.vercel.app/api/EventSource.html): `EventSource` is a [WHATWG-conformant][] implementation of the [server-sent events][] interface. It opens a persistent HTTP connection to a server that responds with the `text/event-stream` content type and dispatches the events it receives without closing the connection.
- [Fetch](https://undici-website.vercel.app/api/Fetch.html): undici implements the [WHATWG Fetch Standard][], providing `fetch()` together with the `Request`, `Response`, `Headers`, and `FormData` classes that mirror the browser APIs. The implementation follows the standard, so the [MDN Fetch documentation][] applies as well.
- [Global Installation](https://undici-website.vercel.app/api/GlobalInstallation.html): undici ships its own implementations of several WHATWG web APIs. The `install()` function assigns those implementations onto `globalThis`, so they can be used without importing them from `'undici'` first. This is useful for polyfilling environments, guaranteeing consistent behavior across Node.js versions, and satisfying third-party libraries that expect the relevant classes to be global.
- [H2CClient](https://undici-website.vercel.app/api/H2CClient.html): An `H2CClient` is a [`Dispatcher`][] that speaks HTTP/2 in cleartext (h2c) over a single TCP connection to an `http:` origin, without the protocol upgrade or prior knowledge negotiation that a regular [`Client`][] performs. It is a thin specialization of [`Client`][] that forces `allowH2` and `useH2c` on and aliases `pipelining` to `maxConcurrentStreams`, so multiple requests are multiplexed as HTTP/2 streams rather than pipelined HTTP/1.x requests.
- [Interceptors](https://undici-website.vercel.app/api/Interceptors.html): Undici ships with a set of built-in interceptors that can be composed via `dispatcher.compose()` to add cross-cutting behaviour such as automatic retries, response decompression, redirect following, DNS caching, and more.
- [MockAgent](https://undici-website.vercel.app/api/MockAgent.html): A `MockAgent` is a {Dispatcher} that intercepts HTTP requests made through undici and replies with programmed mock responses instead of contacting the network. It is useful for testing code that performs HTTP requests without relying on a live server.
- [MockCallHistory](https://undici-website.vercel.app/api/MockCallHistory.html): A `MockCallHistory` records the configuration of every request intercepted by a [`MockAgent`][] for which call history is enabled. Each recorded request is stored as a [`MockCallHistoryLog`][], and the `MockCallHistory` exposes helpers to read and filter those logs in tests.
- [MockCallHistoryLog](https://undici-website.vercel.app/api/MockCallHistoryLog.html): A `MockCallHistoryLog` is an immutable snapshot of the configuration of a single request that was intercepted by a [`MockAgent`][]. Each property mirrors a part of the request, with the URL components already parsed by the WHATWG URL parser.
- [MockClient](https://undici-website.vercel.app/api/MockClient.html): A `MockClient` is a [`Client`][] that intercepts requests matching registered routes and replies with mocked responses instead of contacting the network. It is created by a [`MockAgent`][] when the agent is configured with a single connection, and it exposes the same interception API as [`MockPool`][].
- [MockErrors](https://undici-website.vercel.app/api/MockErrors.html): undici raises a dedicated error when a mocked request cannot be matched against any registered interceptor. The mock error classes are exposed through the `mockErrors` namespace of the package:
- [MockPool](https://undici-website.vercel.app/api/MockPool.html): A `MockPool` is a [`Pool`][] that intercepts requests matching registered routes and replies with mocked responses instead of contacting the network. It is created by a [`MockAgent`][] and exposes the same interception API as [`MockClient`][].
- [Pool](https://undici-website.vercel.app/api/Pool.html): A pool of [`Client`][] instances connected to the same upstream origin. A `Pool` spreads requests across several connections to the same host, which allows more than one request to be in flight at a time without enabling pipelining on a single connection.
- [PoolStats](https://undici-website.vercel.app/api/PoolStats.html): `PoolStats` exposes a read-only snapshot of the aggregate connection and request counters for a [`Pool`][] or [`BalancedPool`][]. An instance is created lazily each time the `pool.stats` getter is accessed, so the values reflect the state of the pool at the moment of access.
- [ProxyAgent](https://undici-website.vercel.app/api/ProxyAgent.html): A `ProxyAgent` routes every request through an HTTP, HTTPS, or SOCKS5 proxy server. It implements the [`Agent`][] API, so it can be used wherever a dispatcher is accepted, for example with [`request`][] or [`fetch`][], or installed globally with [`setGlobalDispatcher`][].
- [RedirectHandler](https://undici-website.vercel.app/api/RedirectHandler.html): A dispatch handler that follows HTTP redirects on behalf of another handler. It wraps a downstream `handler` and a `dispatch` function: when a redirectable response is received it transparently re-dispatches the request to the new location, forwarding the lifecycle callbacks to the wrapped `handler` only once a final (non-redirect) response is reached.
- [RetryAgent](https://undici-website.vercel.app/api/RetryAgent.html): A [`Dispatcher`][] that automatically retries failed requests by wrapping another dispatcher with the retry logic of [`RetryHandler`][]. Requests that fail with a retryable status code or transport error are re-dispatched according to the configured retry policy.
- [RetryHandler](https://undici-website.vercel.app/api/RetryHandler.html): A [`Dispatcher`][] handler that automatically retries a request when it fails with a recoverable network error or an eligible HTTP status code. It wraps an inner handler and re-dispatches the request, applying an exponential backoff and honouring the `Retry-After` response header. When a response is partially consumed before the failure, the handler resumes the download with a `Range` request guarded by the original `ETag`.
- [RoundRobinPool](https://undici-website.vercel.app/api/RoundRobinPool.html): A pool of [`Client`][] instances connected to the same upstream target that selects clients in a round-robin fashion.
- [SnapshotAgent](https://undici-website.vercel.app/api/SnapshotAgent.html): `SnapshotAgent` records real HTTP responses and replays them on later requests, allowing tests to run against deterministic, captured data instead of a live network. It extends [`MockAgent`][], so it can be installed with [`setGlobalDispatcher()`][] or passed explicitly through the `dispatcher` option, and it works with every undici API (`fetch`, `request`, `stream`, `pipeline`, and so on).
- [Socks5ProxyAgent](https://undici-website.vercel.app/api/Socks5ProxyAgent.html): A [`Dispatcher`][] implementation that routes requests through a [SOCKS5][] proxy server. It tunnels both HTTP and HTTPS traffic over the proxy, supports optional username/password authentication, and pools connections per origin so that subsequent requests to the same host reuse the established tunnel.
- [Util](https://undici-website.vercel.app/api/Util.html): A small set of utility helpers exposed for third-party implementations of the [`Dispatcher`][] API. They cover the header-handling primitives undici uses internally, so that custom dispatchers and handlers can normalize header names and parse raw header lists exactly the way undici does.
- [WebSocket](https://undici-website.vercel.app/api/WebSocket.html): The `WebSocket` API provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. It follows the [WHATWG WebSocket specification][] and [RFC 6455][], and is intended to be interchangeable with the global `WebSocket` available in browsers.
- [Client Lifecycle](https://undici-website.vercel.app/api/api-lifecycle.html): A {Client} can be understood as a state machine. As requests are dispatched, processed, and drained, the client moves through a well-defined set of states until it is eventually destroyed. This document describes those states and the transitions between them.