H2CClient

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

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

import { H2CClient } from 'undici'

const client = new H2CClient('http://localhost:3000')

const { statusCode, body } = await client.request({ path: '/', method: 'GET' })
console.log(statusCode)
console.log(await body.text())

class H2CClient extends Client

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

new H2CClient(url, options?): void

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

import { H2CClient } from 'undici'

const client = new H2CClient('http://localhost:3000')

h2cClient.close(callback?): Promise | undefined

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

h2cClient.destroy(error?, callback?): Promise | undefined

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

h2cClient.connect(options, callback?): Promise | undefined

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

h2cClient.dispatch(options, handlers): boolean

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

h2cClient.pipeline(options, handler): Duplex

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

h2cClient.request(options, callback?): Promise | undefined

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

h2cClient.stream(options, factory, callback?): Promise | undefined

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

h2cClient.upgrade(options, callback?): Promise | undefined

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

true after h2cClient.close() has been called.

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

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

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

import { createServer } from 'node:http2'
import { once } from 'node:events'
import { H2CClient } from 'undici'

const server = createServer((request, response) => {
  response.end('Hello, World!')
}).listen()

await once(server, 'listening')

const client = new H2CClient(`http://localhost:${server.address().port}`)

client.on('connect', (origin) => {
  console.log(`Connected to ${origin}`)
})

const { body } = await client.request({ path: '/', method: 'GET' })
console.log(await body.text())

client.close()
server.close()

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

import { createServer } from 'node:http2'
import { once } from 'node:events'
import { H2CClient } from 'undici'

const server = createServer((request, response) => {
  response.destroy()
}).listen()

await once(server, 'listening')

const client = new H2CClient(`http://localhost:${server.address().port}`)

client.on('disconnect', (origin) => {
  console.log(`Disconnected from ${origin}`)
})

try {
  await client.request({ path: '/', method: 'GET' })
} catch (error) {
  console.error(error.message)
} finally {
  client.close()
  server.close()
}

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

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

[dispatcher.close([callback])]: Dispatcher.md#dispatcherclosecallback [dispatcher.connect(options[, callback])]: Dispatcher.md#dispatcherconnectoptions-callback [dispatcher.destroy([error[, callback]])]: Dispatcher.md#dispatcherdestroyerror-callback [dispatcher.dispatch(options, handler)]: Dispatcher.md#dispatcherdispatchoptions-handler [dispatcher.pipeline(options, handler)]: Dispatcher.md#dispatcherpipelineoptions-handler [dispatcher.request(options[, callback])]: Dispatcher.md#dispatcherrequestoptions-callback [dispatcher.stream(options, factory[, callback])]: Dispatcher.md#dispatcherstreamoptions-factory-callback [dispatcher.upgrade(options[, callback])]: Dispatcher.md#dispatcherupgradeoptions-callback