Dispatcher is the core abstraction used to dispatch HTTP requests in undici.\nIt extends EventEmitter and defines the low-level dispatch() contract\nalong with the higher-level request(), stream(), pipeline(),\nconnect(), and upgrade() methods that every concrete dispatcher\nprovides.
Dispatcher itself is abstract: its dispatch(), close(), and\ndestroy() methods throw Error: not implemented. Concrete dispatchers such\nas Client, Pool, BalancedPool, and Agent implement the\ncontract and are what application code instantiates. Requests are not guaranteed\nto be dispatched in the order in which they are invoked.
import { Dispatcher, Agent } from 'undici'\n\nconst dispatcher = new Agent()\nconsole.log(dispatcher instanceof Dispatcher) // true\n<EventEmitter>Base dispatcher class. Concrete dispatchers extend it and implement the\ndispatch() method on which the other request helpers are built.
Closes the dispatcher and gracefully waits for enqueued requests to complete\nbefore resolving or invoking callback.
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.end('undici')\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\ntry {\n const { body } = await client.request({ path: '/', method: 'GET' })\n body.setEncoding('utf8')\n body.on('data', console.log)\n} catch (error) {}\n\nawait client.close()\n\nconsole.log('Client closed')\nserver.close()\nStarts two-way communications with the requested resource using the\nHTTP CONNECT method.
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n throw new Error('should never get here')\n}).listen()\n\nserver.on('connect', (req, socket, head) => {\n socket.write('HTTP/1.1 200 Connection established\\r\\n\\r\\n')\n\n let data = head.toString()\n socket.on('data', (buf) => {\n data += buf.toString()\n })\n\n socket.on('end', () => {\n socket.end(data)\n })\n})\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\ntry {\n const { socket } = await client.connect({ path: '/' })\n const wanted = 'Body'\n let data = ''\n socket.on('data', d => { data += d })\n socket.on('end', () => {\n console.log(`Data received: ${data.toString()} | Data wanted: ${wanted}`)\n client.close()\n server.close()\n })\n socket.write(wanted)\n socket.end()\n} catch (error) {}\nDestroys the dispatcher abruptly with the given error. All pending and running\nrequests are asynchronously aborted and rejected. Because the operation is\ndispatched asynchronously, dispatched requests may still make some progress\nbefore being aborted.
Both arguments are optional, so the method can be called in four ways:
\ndispatcher.destroy() // -> Promise\ndispatcher.destroy(new Error()) // -> Promise\ndispatcher.destroy(() => {}) // -> void\ndispatcher.destroy(new Error(), () => {}) // -> void\nimport { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.end()\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\ntry {\n const request = client.request({ path: '/', method: 'GET' })\n client.destroy()\n .then(() => {\n console.log('Client destroyed')\n server.close()\n })\n await request\n} catch (error) {\n console.error(error)\n}\nThis is the low-level API on which all the higher-level methods are built. This\nAPI is expected to evolve through semver-major versions and is less stable than\nthe higher-level methods. It is primarily intended for library developers who\nimplement higher-level APIs on top of it.
\nThe controller passed to each handler is a DispatchController with the\nfollowing shape:
aborted <boolean> Whether the request has been aborted.paused <boolean> Whether the request is paused.reason <Error> | <null> The reason the request was aborted, if any.rawHeaders <Buffer>[] | <string>[] | <Object> | <null> The raw response headers,\npreserving duplicates and casing.rawTrailers <Buffer>[] | <string>[] | <Object> | <null> The raw response trailers.abort(reason) Aborts the request with the given reason.pause() Pauses the response stream.resume() Resumes the response stream.Call controller.pause() and controller.resume() to apply backpressure rather\nthan returning false from a handler.
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.end('Hello, World!')\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\nconst data = []\n\nclient.dispatch({\n path: '/',\n method: 'GET',\n headers: { 'x-foo': 'bar' }\n}, {\n onRequestStart: () => {\n console.log('Connected!')\n },\n onResponseError: (_controller, error) => {\n console.error(error)\n },\n onResponseStart: (_controller, statusCode, headers) => {\n console.log(`statusCode: ${statusCode} | headers: ${JSON.stringify(headers)}`)\n },\n onResponseData: (_controller, chunk) => {\n data.push(chunk)\n },\n onResponseEnd: (_controller, trailers) => {\n console.log(`trailers: ${JSON.stringify(trailers)}`)\n console.log(`Data: ${Buffer.concat(data).toString('utf8')}`)\n client.close()\n server.close()\n }\n})\nFor easy use with stream.pipeline(). The handler should return a\nReadable from which the result is read. Usually it returns the body directly,\nunless a transformation is needed based on, for example, headers or\nstatusCode. The handler should validate the response and save any required\nstate; if there is an error, it should be thrown.
import { Readable, Writable, PassThrough, pipeline } from 'node:stream'\nimport { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n request.pipe(response)\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\nlet res = ''\n\npipeline(\n new Readable({\n read () {\n this.push(Buffer.from('undici'))\n this.push(null)\n }\n }),\n client.pipeline({ path: '/', method: 'GET' }, ({ statusCode, headers, body }) => {\n console.log(`response received ${statusCode}`)\n console.log('headers', headers)\n return pipeline(body, new PassThrough(), () => {})\n }),\n new Writable({\n write (chunk, _, callback) {\n res += chunk.toString()\n callback()\n },\n final (callback) {\n console.log(`Response pipelined to writable: ${res}`)\n callback()\n }\n }),\n error => {\n if (error) {\n console.error(error)\n }\n client.close()\n server.close()\n }\n)\nPerforms an HTTP request. options.method must not be 'CONNECT'.
Non-idempotent requests are not pipelined, to avoid indirect failures. Idempotent\nrequests are automatically retried if they fail due to an indirect failure from\nthe request at the head of the pipeline; this does not apply to idempotent\nrequests with a stream request body. All response bodies must always be fully\nconsumed or destroyed.
\nThe body exposes the following body mixin methods and properties:\n.arrayBuffer(), .blob(), .bytes(), .json(),\n.text(), body, and bodyUsed. A body cannot be consumed twice; for\nexample, calling text() after json() throws a TypeError. The body also\nprovides dump({ limit }), which discards up to limit bytes (default\n131072) without destroying the socket.
The body is always a Readable, even when empty. Deserializing an empty body\nwith json() throws. To guard against this, verify the status code is not 204\nand the content-type header starts with application/json before calling\njson().
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.end('Hello, World!')\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\ntry {\n const { body, headers, statusCode, statusText, trailers } = await client.request({\n path: '/',\n method: 'GET'\n })\n console.log(`response received ${statusCode}`)\n console.log('headers', headers)\n body.setEncoding('utf8')\n body.on('data', console.log)\n body.on('error', console.error)\n body.on('end', () => {\n console.log('trailers', trailers)\n })\n\n client.close()\n server.close()\n} catch (error) {\n console.error(error)\n}\nA request can be aborted with an AbortSignal, with any EventEmitter that\nemits an 'abort' event, or by destroying the response body:
import { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\nconst abortController = new AbortController()\n\ntry {\n client.request({ path: '/', method: 'GET', signal: abortController.signal })\n} catch (error) {\n console.error(error) // RequestAbortedError\n}\n\nabortController.abort()\nWhen the response body is conditionally read, always fully consume it otherwise:
\nconst { body, statusCode } = await client.request({ path: '/', method: 'GET' })\n\nif (statusCode === 200) {\n return await body.arrayBuffer()\n}\n\nawait body.dump()\n\nreturn null\nA faster version of dispatcher.request(). The factory returns a\nWritable to which the response is written, which avoids creating an\nintermediate Readable when the caller intends to pipe the response body\ndirectly to a Writable.
Use options.opaque to avoid creating a closure for the factory method. This\npattern works well with Node.js web frameworks such as Fastify.
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\nimport { Writable } from 'node:stream'\n\nconst server = createServer((request, response) => {\n response.end('Hello, World!')\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\nconst bufs = []\n\ntry {\n await client.stream({\n path: '/',\n method: 'GET',\n opaque: { bufs }\n }, ({ statusCode, headers, opaque: { bufs } }) => {\n console.log(`response received ${statusCode}`)\n console.log('headers', headers)\n return new Writable({\n write (chunk, encoding, callback) {\n bufs.push(chunk)\n callback()\n }\n })\n })\n\n console.log(Buffer.concat(bufs).toString('utf-8'))\n\n client.close()\n server.close()\n} catch (error) {\n console.error(error)\n}\nUpgrades to a different protocol. See\nMDN: Protocol upgrade mechanism for more details.
\nimport { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.statusCode = 101\n response.setHeader('connection', 'upgrade')\n response.setHeader('upgrade', request.headers.upgrade)\n response.end()\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\ntry {\n const { headers, socket } = await client.upgrade({ path: '/' })\n socket.on('end', () => {\n console.log(`upgrade: ${headers.upgrade}`) // upgrade: Websocket\n client.close()\n server.close()\n })\n socket.end()\n} catch (error) {\n console.error(error)\n client.close()\n server.close()\n}\nComposes a new dispatcher from the current dispatcher and the given\ninterceptors. Each interceptor is a function that takes a dispatch method and\nreturns a dispatch-like function with the same signature\n((options, handler)).
The order of the interceptors matters: the last interceptor in the chain is the\nfirst to be called. Forking the chain of interceptors can lead to unexpected\nresults.
\ncompose([interceptor1, interceptor2, interceptor3])\n\nRequest flow:\nRequest -> interceptor3 -> interceptor2 -> interceptor1 -> dispatcher.dispatch\n (called first) (called second) (called last)\nimport { Client, RedirectHandler } from 'undici'\n\nconst redirectInterceptor = dispatch => {\n return (opts, handler) => {\n const { maxRedirections } = opts\n\n if (!maxRedirections) {\n return dispatch(opts, handler)\n }\n\n const redirectHandler = new RedirectHandler(dispatch, maxRedirections, opts, handler)\n opts = { ...opts, maxRedirections: 0 } // Stop the sub-dispatcher from also redirecting.\n return dispatch(opts, redirectHandler)\n }\n}\n\nconst client = new Client('http://localhost:3000').compose(redirectInterceptor)\n\nawait client.request({ path: '/', method: 'GET' })\nInterceptors can be chained by calling compose() repeatedly:
import { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\n .compose(redirectInterceptor)\n .compose(retryInterceptor)\n\nawait client.request({ path: '/', method: 'GET' })\nFor the full list of built-in interceptors provided by undici, see Interceptors.
" } ], "events": [ { "textRaw": "Event: `'connect'`", "name": "connect", "type": "event", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" }, { "textRaw": "`targets` {ArrayEmitted when the dispatcher has connected to the origin.
" }, { "textRaw": "Event: `'disconnect'`", "name": "disconnect", "type": "event", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" }, { "textRaw": "`targets` {ArrayEmitted when the dispatcher has been disconnected from the origin.
\nFor HTTP/2, this event is also emitted when the dispatcher receives a\nGOAWAY frame, with an error whose message is HTTP/2: \"GOAWAY\" frame received\nand whose code is UND_ERR_INFO. Because of the binary-framing nature of the\nprotocol, a request may hang if a frame is received between the HEADER and\nDATA frames. It is recommended to handle this event and close the dispatcher to\ncreate a new HTTP/2 session.
Emitted when the dispatcher fails to connect to the origin.
" }, { "textRaw": "Event: `'drain'`", "name": "drain", "type": "event", "meta": { "added": [ "v4.0.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" } ], "desc": "Emitted when the dispatcher is no longer busy and further dispatch() calls\ncan make progress.
For the full reference of built-in interceptors (dump, retry, redirect,\ndecompress, responseError, dns, cache, deduplicate) and their options,\nsee Interceptors.