A basic HTTP/1.1 client mapped on top of a single TCP/TLS connection. When the\nserver supports HTTP/2 and selects it during ALPN negotiation, the same\nconnection is used for HTTP/2. Pipelining is disabled by default.
\nClient extends Dispatcher and is the lowest-level dispatcher in undici:\nit manages exactly one origin over one connection. For pooling across multiple\nconnections use Pool, and for routing across multiple origins use\nAgent. Requests are not guaranteed to be dispatched in the order in which\nthey are invoked.
import { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\nconst { statusCode, body } = await client.request({ path: '/', method: 'GET' })\n<Dispatcher>Instantiating a Client does not open a connection; the connection is\nestablished lazily once a request is queued. Call client.connect() to connect\neagerly.
\n\nNotes about HTTP/2:
\n\n
\n- Pseudo headers (
\n:path,:method,:scheme,:authority) are attached\nautomatically and overwrite any user-provided values.- The server must support HTTP/2 and select it during ALPN negotiation, and\nmust not give HTTP/1.1 a higher priority than HTTP/2.
\n- \n
PUSHframes are not supported.
import { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\nimport { Client } from 'undici'\nimport { readFileSync } from 'node:fs'\n\nconst client = new Client('https://localhost:3000', {\n connect: {\n rejectUnauthorized: false,\n ca: readFileSync('./ca-cert.pem')\n }\n})\nimport { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000', {\n connect: {\n socketPath: '/var/run/docker.sock'\n }\n})\nimport { Client } from 'undici'\nimport dns from 'node:dns'\n\nconst client = new Client('https://example.com', {\n connect: {\n lookup (hostname, options, callback) {\n dns.lookup(hostname, { ...options, family: 4 }, callback)\n }\n }\n})\nimport { Client, buildConnector } from 'undici'\n\nconst connector = buildConnector({ rejectUnauthorized: false })\nconst client = new Client('https://localhost:3000', {\n connect (opts, cb) {\n connector(opts, (err, socket) => {\n if (err) {\n cb(err)\n } else {\n cb(null, socket)\n }\n })\n }\n})\nWhen a connector function is provided, undici wraps it to automatically inject\nsocketPath and allowH2 into the options argument when those values are set\non the client. See Connector for details on building custom connectors.
Implements [dispatcher.close([callback])][]. Closes the client gracefully,\nwaiting for enqueued requests to complete before resolving.
Implements [dispatcher.destroy([error[, callback]])][]. Destroys the client\nabruptly, aborting all pending and running requests, and waits until the socket\nis closed before invoking callback (or resolving the returned promise).
Starts a connection to the client's origin and tunnels a connection through it,\nas defined by [dispatcher.connect()][].
Implements [dispatcher.dispatch(options, handler)][]. This is the lowest-level\nAPI used by all other request methods; prefer client.request() for most use\ncases.
See [dispatcher.pipeline(options, handler)][]. Sends a request and returns a\n<Duplex> stream that the request body is written to and the response body is\nread from.
See [dispatcher.request(options[, callback])][]. Performs an HTTP request and\nreturns its status code, headers, trailers, and a readable body stream.
import { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\nconst { statusCode, headers, body } = await client.request({\n path: '/',\n method: 'GET'\n})\n\nconsole.log(statusCode)\nfor await (const chunk of body) {\n console.log(chunk.toString())\n}\nSee [dispatcher.stream(options, factory[, callback])][]. A faster alternative\nto client.request() when the destination of the response body is known in\nadvance.
See [dispatcher.upgrade(options[, callback])][]. Upgrades a connection to a\ndifferent protocol, such as for WebSocket or HTTP CONNECT.
true after client.close() has been called.
true after client.destroy() has been called, or after client.close() has\nbeen called and the client shutdown has completed.
The pipelining factor. This property can be read and written to adjust the\nnumber of concurrent requests sent over the connection. Only enable pipelining\nwith trusted remote servers.
" }, { "textRaw": "Type: {ClientStats}", "name": "stats", "type": "ClientStats", "meta": { "added": [ "v7.9.0" ], "changes": [] }, "desc": "Aggregate statistics for the client. See ClientStats.
Emitted when a socket has been created and connected. The client connects once\nclient.size > 0. See Dispatcher Event: 'connect'.
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\nclient.on('connect', (origin) => {\n console.log(`Connected to ${origin}`)\n})\n\nconst { body } = await client.request({ path: '/', method: 'GET' })\nbody.setEncoding('utf8')\nbody.on('data', console.log)\n\nclient.close()\nserver.close()\nEmitted when a socket has disconnected. The error argument is the error that\ncaused the disconnection. The client reconnects if or once client.size > 0.\nSee Dispatcher Event: 'disconnect'.
import { createServer } from 'node:http'\nimport { Client } from 'undici'\nimport { once } from 'node:events'\n\nconst server = createServer((request, response) => {\n response.destroy()\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new Client(`http://localhost:${server.address().port}`)\n\nclient.on('disconnect', (origin) => {\n console.log(`Disconnected from ${origin}`)\n})\n\ntry {\n await client.request({ path: '/', method: 'GET' })\n} catch (error) {\n console.error(error.message)\n} finally {\n client.close()\n server.close()\n}\nEmitted when the pipeline is no longer busy. See\nDispatcher Event: 'drain'.
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\nclient.on('drain', () => {\n console.log('drain event')\n client.close()\n server.close()\n})\n\nawait Promise.all([\n client.request({ path: '/', method: 'GET' }),\n client.request({ path: '/', method: 'GET' }),\n client.request({ path: '/', method: 'GET' })\n])\nEmitted for user errors, such as throwing inside an onResponseError handler.
[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback\n[dispatcher.connect()]: Dispatcher.md#dispatcherconnectoptions-callback\n[dispatcher.destroy([error[, callback]])]: Dispatcher.md#dispatcherdestroyerror-callback\n[dispatcher.dispatch(options, handler)]: Dispatcher.md#dispatcherdispatchoptions-handler\n[dispatcher.pipeline(options, handler)]: Dispatcher.md#dispatcherpipelineoptions-handler\n[dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback\n[dispatcher.stream(options, factory[, callback])]: Dispatcher.md#dispatcherstreamoptions-factory-callback\n[dispatcher.upgrade(options[, callback])]: Dispatcher.md#dispatcherupgradeoptions-callback\n[tls.connect()]: https://nodejs.org/api/tls.html#tlsconnectoptions-callback