{ "type": "module", "source": "doc/api/api-h2cclient.md", "modules": [ { "textRaw": "H2CClient", "name": "h2cclient", "introduced_in": "v7.7.0", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

An H2CClient is a Dispatcher that speaks HTTP/2 in cleartext (h2c) over a\nsingle TCP connection to an http: origin, without the protocol upgrade or prior\nknowledge negotiation that a regular Client performs. It is a thin\nspecialization of Client that forces allowH2 and useH2c on and aliases\npipelining to maxConcurrentStreams, so multiple requests are multiplexed as\nHTTP/2 streams rather than pipelined HTTP/1.x requests.

\n

Use an H2CClient when the server is known to accept cleartext HTTP/2 directly,\nfor example a service behind a trusted proxy or in a test environment. Only the\nhttp: protocol is supported; passing any other protocol throws\nInvalidArgumentError.

\n
import { H2CClient } from 'undici'\n\nconst client = new H2CClient('http://localhost:3000')\n\nconst { statusCode, body } = await client.request({ path: '/', method: 'GET' })\nconsole.log(statusCode)\nconsole.log(await body.text())\n
", "classes": [ { "textRaw": "Class: `H2CClient`", "name": "H2CClient", "type": "class", "meta": { "added": [ "v7.7.0" ], "changes": [ { "version": "v7.17.0", "pr-url": "https://github.com/nodejs/undici/pull/4690", "description": "Added support for h2c over Unix domain sockets." } ] }, "desc": "\n

H2CClient inherits the full instance API of Client (and therefore of\nDispatcher). The sections below cover the surface that is meaningful for an\nh2c client; refer to Dispatcher for the complete semantics of each method\nand event.

", "signatures": [ { "textRaw": "`new H2CClient(url[, options])`", "name": "H2CClient", "type": "ctor", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "params": [ { "textRaw": "`url` {URL|string} The origin to connect to. Should include only the protocol, hostname, and port. Only the `http:` protocol is supported.", "name": "url", "type": "URL|string", "desc": "The origin to connect to. Should include only the protocol, hostname, and port. Only the `http:` protocol is supported." }, { "textRaw": "`options` {H2CClientOptions} (optional)", "name": "options", "type": "H2CClientOptions", "desc": "(optional)", "options": [ { "textRaw": "`maxConcurrentStreams` {number} The maximum number of concurrent HTTP/2 streams for the session. It is advertised to the server and may be overridden by a remote `SETTINGS` frame. Must be a positive integer. **Default:** `100`.", "name": "maxConcurrentStreams", "type": "number", "default": "`100`", "desc": "The maximum number of concurrent HTTP/2 streams for the session. It is advertised to the server and may be overridden by a remote `SETTINGS` frame. Must be a positive integer." }, { "textRaw": "`pipelining` {number} The number of concurrent requests multiplexed over the single connection. For an `H2CClient` this is aliased to `maxConcurrentStreams` and may not exceed it. Must be a positive integer. **Default:** `100`.", "name": "pipelining", "type": "number", "default": "`100`", "desc": "The number of concurrent requests multiplexed over the single connection. For an `H2CClient` this is aliased to `maxConcurrentStreams` and may not exceed it. Must be a positive integer." }, { "textRaw": "`maxHeaderSize` {number} The maximum length of request headers in bytes. **Default:** Node.js' `--max-http-header-size` or `16384` (16 KiB).", "name": "maxHeaderSize", "type": "number", "default": "Node.js' `--max-http-header-size` or `16384` (16 KiB)", "desc": "The maximum length of request headers in bytes." }, { "textRaw": "`headersTimeout` {number} The amount of time, in milliseconds, the parser waits to receive the complete HTTP headers. **Default:** `300e3`.", "name": "headersTimeout", "type": "number", "default": "`300e3`", "desc": "The amount of time, in milliseconds, the parser waits to receive the complete HTTP headers." }, { "textRaw": "`connectTimeout` {number} The timeout for establishing a socket connection, in milliseconds. Use `0` to disable it entirely. **Default:** `10e3`.", "name": "connectTimeout", "type": "number", "default": "`10e3`", "desc": "The timeout for establishing a socket connection, in milliseconds. Use `0` to disable it entirely." }, { "textRaw": "`bodyTimeout` {number} The timeout, in milliseconds, after which a request times out. Monitors the time between received body data. Use `0` to disable it entirely. **Default:** `300e3`.", "name": "bodyTimeout", "type": "number", "default": "`300e3`", "desc": "The timeout, in milliseconds, after which a request times out. Monitors the time between received body data. Use `0` to disable it entirely." }, { "textRaw": "`keepAliveTimeout` {number} The timeout, in milliseconds, after which a socket without active requests times out. May be overridden by _keep-alive_ hints from the server. **Default:** `4e3`.", "name": "keepAliveTimeout", "type": "number", "default": "`4e3`", "desc": "The timeout, in milliseconds, after which a socket without active requests times out. May be overridden by _keep-alive_ hints from the server." }, { "textRaw": "`keepAliveMaxTimeout` {number} The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by _keep-alive_ hints from the server. **Default:** `600e3`.", "name": "keepAliveMaxTimeout", "type": "number", "default": "`600e3`", "desc": "The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by _keep-alive_ hints from the server." }, { "textRaw": "`keepAliveTimeoutThreshold` {number} A number of milliseconds subtracted from server _keep-alive_ hints when overriding `keepAliveTimeout`, to account for timing inaccuracies such as transport latency. **Default:** `1e3`.", "name": "keepAliveTimeoutThreshold", "type": "number", "default": "`1e3`", "desc": "A number of milliseconds subtracted from server _keep-alive_ hints when overriding `keepAliveTimeout`, to account for timing inaccuracies such as transport latency." }, { "textRaw": "`socketPath` {string} An IPC endpoint, either a Unix domain socket or a Windows named pipe. **Default:** `null`.", "name": "socketPath", "type": "string", "default": "`null`", "desc": "An IPC endpoint, either a Unix domain socket or a Windows named pipe." }, { "textRaw": "`strictContentLength` {boolean} If `true`, an error is thrown when the request `content-length` header does not match the length of the request body. **Default:** `true`.", "name": "strictContentLength", "type": "boolean", "default": "`true`", "desc": "If `true`, an error is thrown when the request `content-length` header does not match the length of the request body." }, { "textRaw": "`maxCachedSessions` {number} The maximum number of TLS sessions cached by the built-in connector. Use `0` to disable TLS session caching. **Default:** `100`.", "name": "maxCachedSessions", "type": "number", "default": "`100`", "desc": "The maximum number of TLS sessions cached by the built-in connector. Use `0` to disable TLS session caching." }, { "textRaw": "`connect` {Object|Function} Connector options passed to `buildConnector`, or a custom connector function. The `allowH2` option may not be set here. **Default:** `null`.", "name": "connect", "type": "Object|Function", "default": "`null`", "desc": "Connector options passed to `buildConnector`, or a custom connector function. The `allowH2` option may not be set here." }, { "textRaw": "`maxRequestsPerClient` {number} The maximum number of requests to send over a single connection before it is reset. Use `0` to disable this limit. **Default:** `null`.", "name": "maxRequestsPerClient", "type": "number", "default": "`null`", "desc": "The maximum number of requests to send over a single connection before it is reset. Use `0` to disable this limit." }, { "textRaw": "`localAddress` {string} The local IP address the socket should connect from.", "name": "localAddress", "type": "string", "desc": "The local IP address the socket should connect from." }, { "textRaw": "`maxResponseSize` {number} The maximum allowed response body size in bytes. Use `-1` to disable. **Default:** `-1`.", "name": "maxResponseSize", "type": "number", "default": "`-1`", "desc": "The maximum allowed response body size in bytes. Use `-1` to disable." }, { "textRaw": "`autoSelectFamily` {boolean} Enables a family autodetection algorithm that loosely implements section 5 of RFC 8305. Ignored if not supported by the current Node.js version.", "name": "autoSelectFamily", "type": "boolean", "desc": "Enables a family autodetection algorithm that loosely implements section 5 of RFC 8305. Ignored if not supported by the current Node.js version." }, { "textRaw": "`autoSelectFamilyAttemptTimeout` {number} The amount of time, in milliseconds, to wait for a connection attempt to finish before trying the next address when `autoSelectFamily` is enabled.", "name": "autoSelectFamilyAttemptTimeout", "type": "number", "desc": "The amount of time, in milliseconds, to wait for a connection attempt to finish before trying the next address when `autoSelectFamily` is enabled." } ], "optional": true } ], "desc": "

Creates a new H2CClient for the given origin. The client does not connect until\na request is queued; call h2cClient.connect()\nto connect eagerly.

\n
import { H2CClient } from 'undici'\n\nconst client = new H2CClient('http://localhost:3000')\n
" } ], "methods": [ { "textRaw": "`h2cClient.close([callback])`", "name": "close", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`callback` {Function} (optional) Invoked once all queued requests have settled and the client is closed.", "name": "callback", "type": "Function", "desc": "(optional) Invoked once all queued requests have settled and the client is closed.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` that resolves once the client is closed, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` that resolves once the client is closed, when `callback` is not provided." } } ], "desc": "

Closes the client and gracefully waits for enqueued requests to complete before\nresolving. See [dispatcher.close([callback])][].

" }, { "textRaw": "`h2cClient.destroy([error[, callback]])`", "name": "destroy", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`error` {Error} (optional) The error with which to reject pending requests. **Default:** `null`.", "name": "error", "type": "Error", "default": "`null`", "desc": "(optional) The error with which to reject pending requests.", "optional": true }, { "textRaw": "`callback` {Function} (optional) Invoked once the client is destroyed.", "name": "callback", "type": "Function", "desc": "(optional) Invoked once the client is destroyed.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` that resolves once the client is destroyed, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` that resolves once the client is destroyed, when `callback` is not provided." } } ], "desc": "

Destroys the client abruptly, aborting any pending requests. Waits until the\nsocket is closed before invoking callback (or resolving the returned Promise).\nSee [dispatcher.destroy([error[, callback]])][].

" }, { "textRaw": "`h2cClient.connect(options[, callback])`", "name": "connect", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object}", "name": "options", "type": "Object", "options": [ { "textRaw": "`path` {string}", "name": "path", "type": "string" }, { "textRaw": "`headers` {Object} (optional) **Default:** `null`.", "name": "headers", "type": "Object", "default": "`null`", "desc": "(optional)" }, { "textRaw": "`signal` {AbortSignal|EventEmitter|null} (optional) **Default:** `null`.", "name": "signal", "type": "AbortSignal|EventEmitter|null", "default": "`null`", "desc": "(optional)" }, { "textRaw": "`opaque` {any} (optional) An opaque value passed through to the returned connect data.", "name": "opaque", "type": "any", "desc": "(optional) An opaque value passed through to the returned connect data." }, { "textRaw": "`responseHeaders` {string|null} (optional) Set to `'raw'` to return the response headers as a raw array instead of an object. **Default:** `null`.", "name": "responseHeaders", "type": "string|null", "default": "`null`", "desc": "(optional) Set to `'raw'` to return the response headers as a raw array instead of an object." } ] }, { "textRaw": "`callback` {Function} (optional) Invoked with `(err, data)` once the connection is established. If omitted, a `Promise` is returned instead.", "name": "callback", "type": "Function", "desc": "(optional) Invoked with `(err, data)` once the connection is established. If omitted, a `Promise` is returned instead.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` resolving to the connect data, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` resolving to the connect data, when `callback` is not provided." } } ], "desc": "

Starts an HTTP CONNECT request. See [dispatcher.connect(options[, callback])][].

" }, { "textRaw": "`h2cClient.dispatch(options, handlers)`", "name": "dispatch", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} The request options.", "name": "options", "type": "Object", "desc": "The request options." }, { "textRaw": "`handlers` {Object} The dispatch handler callbacks.", "name": "handlers", "type": "Object", "desc": "The dispatch handler callbacks." } ], "return": { "textRaw": "Returns: {boolean} `false` if the dispatcher is busy and the caller should wait for the `'drain'` event before dispatching again.", "name": "return", "type": "boolean", "desc": "`false` if the dispatcher is busy and the caller should wait for the `'drain'` event before dispatching again." } } ], "desc": "

The lowest-level request API. All other request methods are implemented on top of\nit. See [dispatcher.dispatch(options, handler)][].

" }, { "textRaw": "`h2cClient.pipeline(options, handler)`", "name": "pipeline", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} The request options.", "name": "options", "type": "Object", "desc": "The request options." }, { "textRaw": "`handler` {Function} A handler that receives the response data and returns a {Readable} body.", "name": "handler", "type": "Function", "desc": "A handler that receives the response data and returns a {Readable} body." } ], "return": { "textRaw": "Returns: {Duplex} A duplex stream for the request body and response body.", "name": "return", "type": "Duplex", "desc": "A duplex stream for the request body and response body." } } ], "desc": "

Sends a request and returns a duplex stream, suitable for piping. See\n[dispatcher.pipeline(options, handler)][].

" }, { "textRaw": "`h2cClient.request(options[, callback])`", "name": "request", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} The request options.", "name": "options", "type": "Object", "desc": "The request options." }, { "textRaw": "`callback` {Function} (optional) Invoked with `(err, data)` once the response is received. If omitted, a `Promise` is returned instead.", "name": "callback", "type": "Function", "desc": "(optional) Invoked with `(err, data)` once the response is received. If omitted, a `Promise` is returned instead.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` resolving to the response data, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` resolving to the response data, when `callback` is not provided." } } ], "desc": "

Performs an HTTP request. See [dispatcher.request(options[, callback])][].

" }, { "textRaw": "`h2cClient.stream(options, factory[, callback])`", "name": "stream", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} The request options.", "name": "options", "type": "Object", "desc": "The request options." }, { "textRaw": "`factory` {Function} A factory that returns a {Writable} to which the response body is written.", "name": "factory", "type": "Function", "desc": "A factory that returns a {Writable} to which the response body is written." }, { "textRaw": "`callback` {Function} (optional) Invoked once the request completes. If omitted, a `Promise` is returned instead.", "name": "callback", "type": "Function", "desc": "(optional) Invoked once the request completes. If omitted, a `Promise` is returned instead.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` that resolves once the request completes, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` that resolves once the request completes, when `callback` is not provided." } } ], "desc": "

Sends a request and writes the response body to the stream returned by factory.\nSee [dispatcher.stream(options, factory[, callback])][].

" }, { "textRaw": "`h2cClient.upgrade(options[, callback])`", "name": "upgrade", "type": "method", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {Object} The request options.", "name": "options", "type": "Object", "desc": "The request options." }, { "textRaw": "`callback` {Function} (optional) Invoked with `(err, data)` once the upgrade completes. If omitted, a `Promise` is returned instead.", "name": "callback", "type": "Function", "desc": "(optional) Invoked with `(err, data)` once the upgrade completes. If omitted, a `Promise` is returned instead.", "optional": true } ], "return": { "textRaw": "Returns: {Promise|undefined} A `Promise` resolving to the upgrade data, when `callback` is not provided.", "name": "return", "type": "Promise|undefined", "desc": "A `Promise` resolving to the upgrade data, when `callback` is not provided." } } ], "desc": "

Upgrades a connection to a different protocol. See\n[dispatcher.upgrade(options[, callback])][].

" } ], "properties": [ { "textRaw": "Type: {boolean}", "name": "closed", "type": "boolean", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "desc": "

true after h2cClient.close() has been called.

" }, { "textRaw": "Type: {boolean}", "name": "destroyed", "type": "boolean", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "desc": "

true after h2cClient.destroy() has been\ncalled, or after h2cClient.close() has been called\nand the client shutdown has completed.

" }, { "textRaw": "Type: {number}", "name": "pipelining", "type": "number", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "desc": "

Gets and sets the pipelining factor, i.e. the number of requests multiplexed over\nthe connection.

" } ], "events": [ { "textRaw": "Event: `'connect'`", "name": "connect", "type": "event", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" }, { "textRaw": "`targets` {Array}", "name": "targets", "type": "Array" } ], "desc": "

Emitted when the socket has been created and connected. The client connects once\nclient.size > 0. See Dispatcher Event: 'connect'.

\n
import { createServer } from 'node:http2'\nimport { once } from 'node:events'\nimport { H2CClient } from 'undici'\n\nconst server = createServer((request, response) => {\n  response.end('Hello, World!')\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new H2CClient(`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' })\nconsole.log(await body.text())\n\nclient.close()\nserver.close()\n
" }, { "textRaw": "Event: `'disconnect'`", "name": "disconnect", "type": "event", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" }, { "textRaw": "`targets` {Array}", "name": "targets", "type": "Array" }, { "textRaw": "`error` {Error}", "name": "error", "type": "Error" } ], "desc": "

Emitted when the socket has disconnected. The error argument is the error that\ncaused the socket to disconnect. The client reconnects if (or once)\nclient.size > 0. See Dispatcher Event: 'disconnect'.

\n
import { createServer } from 'node:http2'\nimport { once } from 'node:events'\nimport { H2CClient } from 'undici'\n\nconst server = createServer((request, response) => {\n  response.destroy()\n}).listen()\n\nawait once(server, 'listening')\n\nconst client = new H2CClient(`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}\n
" }, { "textRaw": "Event: `'drain'`", "name": "drain", "type": "event", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "params": [ { "textRaw": "`origin` {URL}", "name": "origin", "type": "URL" } ], "desc": "

Emitted when the client is no longer busy and can accept more requests. See\nDispatcher Event: 'drain'.

" }, { "textRaw": "Event: `'error'`", "name": "error", "type": "event", "meta": { "added": [ "v7.7.0" ], "changes": [] }, "params": [ { "textRaw": "`error` {Error}", "name": "error", "type": "Error" } ], "desc": "

Emitted for user errors, such as an error thrown from an onResponseError\nhandler.

\n

[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback\n[dispatcher.connect(options[, callback])]: 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

" } ] } ] } ] }