XUtils

undici

High performance HTTP client written from scratch with zero dependencies.

Node.js
https://github.com/nodejs/undici

undici

Node CI js-standard-style npm version codecov

An HTTP/1.1 client, written from scratch for Node.js.

Undici means eleven in Italian. 1.1 -> 11 -> Eleven -> Undici. It is also a Stranger Things reference.

Install

npm i undici

Benchmarks

The benchmark is a simple getting data example using a 50 TCP connections with a pipelining depth of 10 running on Node 20.10.0.

Tests Samples Result Tolerance Difference with slowest
undici - fetch 30 3704.43 req/sec ± 2.95 % -
http - no keepalive 20 4275.30 req/sec ± 2.60 % + 15.41 %
node-fetch 10 4759.42 req/sec ± 0.87 % + 28.48 %
request 40 4803.37 req/sec ± 2.77 % + 29.67 %
axios 45 4951.97 req/sec ± 2.88 % + 33.68 %
got 10 5969.67 req/sec ± 2.64 % + 61.15 %
superagent 10 9471.48 req/sec ± 1.50 % + 155.68 %
http - keepalive 25 10327.49 req/sec ± 2.95 % + 178.79 %
undici - pipeline 10 15053.41 req/sec ± 1.63 % + 306.36 %
undici - request 10 19264.24 req/sec ± 1.74 % + 420.03 %
undici - stream 15 20317.29 req/sec ± 2.13 % + 448.46 %
undici - dispatch 10 24883.28 req/sec ± 1.54 % + 571.72 %

The benchmark is a simple sending data example using a 50 TCP connections with a pipelining depth of 10 running on Node 20.10.0.

Tests Samples Result Tolerance Difference with slowest
undici - fetch 20 1968.42 req/sec ± 2.63 % -
http - no keepalive 25 2330.30 req/sec ± 2.99 % + 18.38 %
node-fetch 20 2485.36 req/sec ± 2.70 % + 26.26 %
got 15 2787.68 req/sec ± 2.56 % + 41.62 %
request 30 2805.10 req/sec ± 2.59 % + 42.50 %
axios 10 3040.45 req/sec ± 1.72 % + 54.46 %
superagent 20 3358.29 req/sec ± 2.51 % + 70.61 %
http - keepalive 20 3477.94 req/sec ± 2.51 % + 76.69 %
undici - pipeline 25 3812.61 req/sec ± 2.80 % + 93.69 %
undici - request 10 6067.00 req/sec ± 0.94 % + 208.22 %
undici - stream 10 6391.61 req/sec ± 1.98 % + 224.71 %
undici - dispatch 10 6397.00 req/sec ± 1.48 % + 224.98 %

Quick Start

import { request } from 'undici'

const {
  statusCode,
  headers,
  trailers,
  body
} = await request('http://localhost:3000/foo')

console.log('response received', statusCode)
console.log('headers', headers)

for await (const data of body) { console.log('data', data) }

console.log('trailers', trailers)

Common API Methods

This section documents our most commonly used API methods. Additional APIs are documented in their own files within the docs folder and are accessible via the navigation list on the left side of the docs site.

undici.request([url, options]): Promise

Arguments:

  • url string | URL | UrlObject
  • options RequestOptions
    • dispatcher Dispatcher - Default: getGlobalDispatcher
    • method String - Default: PUT if options.body, otherwise GET
    • maxRedirections Integer - Default: 0

Returns a promise with the result of the Dispatcher.request method.

Calls options.dispatcher.request(options).

See Dispatcher.request for more details, and request examples for examples.

undici.stream([url, options, ]factory): Promise

Arguments:

  • url string | URL | UrlObject
  • options StreamOptions
    • dispatcher Dispatcher - Default: getGlobalDispatcher
    • method String - Default: PUT if options.body, otherwise GET
    • maxRedirections Integer - Default: 0
  • factory Dispatcher.stream.factory

Returns a promise with the result of the Dispatcher.stream method.

Calls options.dispatcher.stream(options, factory).

See Dispatcher.stream for more details.

undici.pipeline([url, options, ]handler): Duplex

Arguments:

  • url string | URL | UrlObject
  • options PipelineOptions
    • dispatcher Dispatcher - Default: getGlobalDispatcher
    • method String - Default: PUT if options.body, otherwise GET
    • maxRedirections Integer - Default: 0
  • handler Dispatcher.pipeline.handler

Returns: stream.Duplex

Calls options.dispatch.pipeline(options, handler).

See Dispatcher.pipeline for more details.

undici.connect([url, options]): Promise

Starts two-way communications with the requested resource using HTTP CONNECT.

Arguments:

  • url string | URL | UrlObject
  • options ConnectOptions
  • callback (err: Error | null, data: ConnectData | null) => void (optional)

Returns a promise with the result of the Dispatcher.connect method.

Calls options.dispatch.connect(options).

See Dispatcher.connect for more details.

request.body

A body can be of the following types:

  • ArrayBuffer
  • ArrayBufferView
  • AsyncIterables
  • Blob
  • Iterables
  • String
  • URLSearchParams
  • FormData

In this implementation of fetch, request.body now accepts Async Iterables. It is not present in the Fetch Standard.

import { fetch } from 'undici'

const data = {
  async *[Symbol.asyncIterator]() {
    yield 'hello'
    yield 'world'
  },
}

await fetch('https://example.com', { body: data, method: 'POST', duplex: 'half' })

FormData besides text data and buffers can also utilize streams via Blob objects:

import { openAsBlob } from 'node:fs'

const file = await openAsBlob('./big.csv')
const body = new FormData()
body.set('file', file, 'big.csv')

await fetch('http://example.com', { method: 'POST', body })

request.duplex

  • half

In this implementation of fetch, request.duplex must be set if request.body is ReadableStream or Async Iterables, however, fetch requests are currently always full duplex. For more detail refer to the Fetch Standard..

response.body

Nodejs has two kinds of streams: web streams, which follow the API of the WHATWG web standard found in browsers, and an older Node-specific streams API. response.body returns a readable web stream. If you would prefer to work with a Node stream you can convert a web stream using .fromWeb().

import { fetch } from 'undici'
import { Readable } from 'node:stream'

const response = await fetch('https://example.com')
const readableWebStream = response.body
const readableNodeStream = Readable.fromWeb(readableWebStream)
Forbidden and Safelisted Header Names

The Fetch Standard requires implementations to exclude certain headers from requests and responses. In browser environments, some headers are forbidden so the user agent remains in full control over them. In Undici, these constraints are removed to give more control to the user.

undici.upgrade([url, options]): Promise

Upgrade to a different protocol. See MDN - HTTP - Protocol upgrade mechanism for more details.

Arguments:

  • url string | URL | UrlObject
  • options UpgradeOptions
  • callback (error: Error | null, data: UpgradeData) => void (optional)

Returns a promise with the result of the Dispatcher.upgrade method.

Calls options.dispatcher.upgrade(options).

See Dispatcher.upgrade for more details.

undici.setGlobalDispatcher(dispatcher)

  • dispatcher Dispatcher

Sets the global dispatcher used by Common API Methods.

undici.getGlobalDispatcher()

Gets the global dispatcher used by Common API Methods.

Returns: Dispatcher

undici.setGlobalOrigin(origin)

  • origin string | URL | undefined

Sets the global origin used in fetch.

If undefined is passed, the global origin will be reset. This will cause Response.redirect, new Request(), and fetch to throw an error when a relative path is passed.

setGlobalOrigin('http://localhost:3000')

const response = await fetch('/api/ping')

console.log(response.url) // http://localhost:3000/api/ping

undici.getGlobalOrigin()

Gets the global origin used in fetch.

Returns: URL

UrlObject

  • port string | number (optional)
  • path string (optional)
  • pathname string (optional)
  • hostname string (optional)
  • origin string (optional)
  • protocol string (optional)
  • search string (optional)

Manual Redirect

Since it is not possible to manually follow an HTTP redirect on the server-side, Undici returns the actual response instead of an opaqueredirect filtered one when invoked with a manual redirect. This aligns fetch() with the other implementations in Deno and Cloudflare Workers.

Refs: https://fetch.spec.whatwg.org/#atomic-http-redirect-handling

Workarounds

Collaborators

Releasers

Articles

  • coming soon...