Extends: undici.Dispatcher
A basic HTTP/1.1 client, mapped on top a single TCP/TLS connection. Pipelining is disabled by default.
\nRequests are not guaranteed to be dispatched in order of invocation.
", "signatures": [ { "textRaw": "`new Client(url[, options])`", "name": "Client", "type": "ctor", "params": [ { "name": "url" }, { "name": "options", "optional": true } ], "desc": "Arguments:
\nURL | string - Should only include the protocol, hostname, and port.ClientOptions (optional)Returns: Client
number | null (optional) - Default: 300e3 - The timeout after which a request will time out, in milliseconds. Monitors time between receiving body data. Use 0 to disable it entirely. Defaults to 300 seconds. Please note the timeout will be reset if you keep writing data to the socket everytime.number | null (optional) - Default: 300e3 - The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds.number | null (optional) - Default: 600e3 - The maximum allowed keepAliveTimeout, in milliseconds, when overridden by keep-alive hints from the server. Defaults to 10 minutes.number | null (optional) - Default: 4e3 - The timeout, in milliseconds, after which a socket without active requests will time out. Monitors time between activity on a connected socket. This value may be overridden by keep-alive hints from the server. See MDN: HTTP - Headers - Keep-Alive directives for more details. Defaults to 4 seconds.number | null (optional) - Default: 2e3 - A number of milliseconds subtracted from server keep-alive hints when overriding keepAliveTimeout to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.number | null (optional) - Default: --max-http-header-size or 16384 - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.number | null (optional) - Default: -1 - The maximum length of response body in bytes. Set to -1 to disable.WebSocketOptions (optional) - WebSocket-specific configuration options.\nnumber (optional) - Default: 131072 - Maximum number of fragments in a message. Set to 0 to disable the limit.number (optional) - Default: 134217728 (128 MB) - Maximum allowed payload size in bytes for WebSocket messages. Applied to uncompressed messages, compressed frame payloads, and decompressed (permessage-deflate) messages. Set to 0 to disable the limit.number | null (optional) - Default: 1 - The amount of concurrent requests to be sent over the single TCP/TLS connection according to RFC7230. Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to 0 to disable keep-alive connections. This option has no effect once HTTP/2 is negotiated — see maxConcurrentStreams for the h2 dispatch ceiling.ConnectOptions | Function | null (optional) - Default: null - Configures how undici establishes TCP/TLS connections. Accepts two forms:\nConnectOptions): Options passed directly to the internal buildConnector(). This is the simplest way to customize TLS or socket behavior (e.g., setting rejectUnauthorized, ca, socketPath). See ConnectOptions for available fields.(options, callback), where options contains { hostname, host, protocol, port, servername, localAddress, httpSocket } and callback follows (error, socket). Useful when you need full control over socket creation, such as adding custom validation or proxy logic. When a function is provided, undici wraps it to automatically inject socketPath and allowH2 into the options argument if those values are set on the client.Boolean (optional) - Default: true - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body. Security Warning: Disabling this option can expose your application to HTTP Request Smuggling attacks, where mismatched content-length headers cause servers and proxies to interpret request boundaries differently. This can lead to cache poisoning, credential hijacking, and bypassing security controls. Only disable this in controlled environments where you fully trust the request source.boolean (optional) - Default: depends on local Node version, on Node 18.13.0 and above is false. Enables a family autodetection algorithm that loosely implements section 5 of RFC 8305. See here for more details. This option is ignored if not supported by the current Node version.number - Default: depends on local Node version, on Node 18.13.0 and above is 250. The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the autoSelectFamily option. See here for more details.boolean - Default: true. Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation.boolean - Default: false. Enforces h2c for non-https connections.number - Default: 100. The maximum number of concurrent HTTP/2 streams per session. When allowH2 negotiates h2, this — not pipelining (which is HTTP/1.1 only, per RFC7230) — is the ceiling the Client uses to dispatch in-flight requests on a shared session. The same value is advertised to the server as peerMaxConcurrentStreams, capping how many streams the server may push back. The initial value is replaced by the server's SETTINGS_MAX_CONCURRENT_STREAMS whenever the server sends one, so a user-supplied value acts as a pre-SETTINGS default rather than a hard cap.number (optional) - Default: 262144 (256KB). Sets the HTTP/2 stream-level flow-control window size (SETTINGS_INITIAL_WINDOW_SIZE). Must be a positive integer greater than 0. This default is higher than Node.js core's default (65535 bytes) to improve throughput, Node's choice is very conservative for current high-bandwith networks. See RFC 7540 Section 6.9.2 for more details.number (optional) - Default 524288 (512KB). Sets the HTTP/2 connection-level flow-control window size using ClientHttp2Session.setLocalWindowSize(). Must be a positive integer greater than 0. This provides better flow control for the entire connection across multiple streams. See Node.js HTTP/2 documentation for more details.number - Default: 60e3. The time interval in milliseconds between PING frames sent to the server. Set to 0 to disable PING frames. This is only applicable for HTTP/2 connections. This will emit a ping event on the client with the duration of the ping in milliseconds.\n", "modules": [ { "textRaw": "Parameter: `ConnectOptions`", "name": "parameter:_`connectoptions`", "type": "module", "desc": "Notes about HTTP/2
\n\n
\n- It only works under TLS connections. h2c is not supported.
\n- The server must support HTTP/2 and choose it as the protocol during the ALPN negotiation.\n
\n\n
\n- The server must not have a bigger priority for HTTP/1.1 than HTTP/2.
\n- Pseudo headers are automatically attached to the request. If you try to set them, they will be overwritten.\n
\n\n
\n- The
\n:pathheader is automatically set to the request path.- The
\n:methodheader is automatically set to the request method.- The
\n:schemeheader is automatically set to the request scheme.- The
\n:authorityheader is automatically set to the requesthost[:port].- \n
PUSHframes are yet not supported.
Every Tls option, see here.\nFurthermore, the following options can be passed:
\nstring | null (optional) - Default: null - An IPC endpoint, either Unix domain socket or Windows named pipe.number | null (optional) - Default: 100 - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: 100.number | null (optional) - In milliseconds, Default 10e3.string | null (optional)boolean | null (optional) - Default: true - TCP keep-alive enablednumber | null (optional) - Default: 60000 - TCP keep-alive interval for the socket in millisecondsThis will instantiate the undici Client, but it will not connect to the origin until something is queued. Consider using client.connect to prematurely connect to the origin, or just call client.request.
'use strict'\nimport { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000')\nPass a ConnectOptions object to customize the TLS connection. The options are forwarded to the internal buildConnector().
'use strict'\nimport { Client } from 'undici'\nimport fs from 'node:fs'\n\nconst client = new Client('https://localhost:3000', {\n connect: {\n rejectUnauthorized: false,\n ca: fs.readFileSync('./ca-cert.pem')\n }\n})\nUse the socketPath option to connect through an IPC endpoint instead of a TCP connection.
'use strict'\nimport { Client } from 'undici'\n\nconst client = new Client('http://localhost:3000', {\n connect: {\n socketPath: '/var/run/docker.sock'\n }\n})\nPass a function for full control over socket creation. This allows you to perform additional checks on the socket, use a proxy, or implement custom connection logic.
\n\n\nNote: When a function is provided, undici wraps it to automatically inject
\nsocketPathandallowH2into the first argument (options) when those values are set on the client.
'use strict'\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 if (/* assertion */) {\n socket.destroy()\n cb(new Error('kaboom'))\n } else {\n cb(null, socket)\n }\n })\n }\n})\nFor more details on building custom connectors, see Connector.
", "displayName": "Example - Custom connector (function form)" } ] } ], "modules": [ { "textRaw": "Instance Methods", "name": "instance_methods", "type": "module", "methods": [ { "textRaw": "`Client.close([callback])`", "name": "close", "type": "method", "signatures": [ { "params": [ { "name": "callback", "optional": true } ] } ], "desc": "Implements Dispatcher.close([callback]).
Implements Dispatcher.destroy([error, callback]).
Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided).
" }, { "textRaw": "`Client.connect(options[, callback])`", "name": "connect", "type": "method", "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "See Dispatcher.connect(options[, callback]).
Implements Dispatcher.dispatch(options, handlers).
See Dispatcher.pipeline(options, handler).
See Dispatcher.request(options [, callback]).
See Dispatcher.stream(options, factory[, callback]).
See Dispatcher.upgrade(options[, callback]).
booleantrue after client.close() has been called.
booleantrue after client.destroyed() has been called or client.close() has been called and the client shutdown has completed.
numberProperty to get and set the pipelining factor.
" } ], "displayName": "Instance Properties" }, { "textRaw": "Instance Events", "name": "instance_events", "type": "module", "events": [ { "textRaw": "Event: `'connect'`", "name": "connect", "type": "event", "params": [], "desc": "See Dispatcher Event: 'connect'.
Parameters:
\nURLArray<Dispatcher>Emitted when a socket has been created and connected. The client will connect once client.size > 0.
import { createServer } from 'http'\nimport { Client } from 'undici'\nimport { once } from '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}`) // should print before the request body statement\n})\n\ntry {\n const { body } = await client.request({\n path: '/',\n method: 'GET'\n })\n body.setEncoding('utf-8')\n body.on('data', console.log)\n client.close()\n server.close()\n} catch (error) {\n console.error(error)\n client.close()\n server.close()\n}\nSee Dispatcher Event: 'disconnect'.
Parameters:
\nURLArray<Dispatcher>ErrorEmitted when socket has disconnected. The error argument of the event is the error which caused the socket to disconnect. The client will reconnect if or once client.size > 0.
import { createServer } from 'http'\nimport { Client } from 'undici'\nimport { once } from '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({\n path: '/',\n method: 'GET'\n })\n} catch (error) {\n console.error(error.message)\n client.close()\n server.close()\n}\nEmitted when pipeline is no longer busy.
\nSee Dispatcher Event: 'drain'.
import { createServer } from 'http'\nimport { Client } from 'undici'\nimport { once } from '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\nconst requests = [\n client.request({ path: '/', method: 'GET' }),\n client.request({ path: '/', method: 'GET' }),\n client.request({ path: '/', method: 'GET' })\n]\n\nawait Promise.all(requests)\n\nconsole.log('requests completed')\nInvoked for user errors such as throwing in the onResponseError handler.