feat: implement h2c client

docs/docs/api/H2CClient.md

@@ -0,0 +1,240 @@
+# Class: H2CClient
+
+Extends: `undici.Dispatcher`
+
+A basic H2C client, mapped on top a single TCP connection. Pipelining is disabled by default.
+
+Requests are not guaranteed to be dispatched in order of invocation.
+
+## `new H2CClient(url[, options])`
+
+Arguments:
+
+- **url** `URL | string` - Should only include the **protocol, hostname, and port**. It only supports `http` protocol.
+- **options** `H2CClientOptions` (optional)
+
+Returns: `H2CClient`
+
+### Parameter: `H2CClientOptions`
+
+- **bodyTimeout** `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.
+- **headersTimeout** `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.
+- **keepAliveMaxTimeout** `number | null` (optional) - Default: `600e3` - The maximum allowed `keepAliveTimeout`, in milliseconds, when overridden by _keep-alive_ hints from the server. Defaults to 10 minutes.
+- **keepAliveTimeout** `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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Keep-Alive#directives) for more details. Defaults to 4 seconds.
+- **keepAliveTimeoutThreshold** `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.
+- **maxHeaderSize** `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.
+- **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
+- **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). 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.
+- **connect** `ConnectOptions | null` (optional) - Default: `null`.
+- **strictContentLength** `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.
+- **autoSelectFamily**: `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](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.
+- **autoSelectFamilyAttemptTimeout**: `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](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details.
+- **maxConcurrentStreams**: `number` - Default: `100`. Dictates the maximum number of concurrent streams for a single H2 session. It can be overridden by a SETTINGS remote frame.
+
+#### Parameter: `H2CConnectOptions`
+
+- **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
+- **timeout** `number | null` (optional) - In milliseconds, Default `10e3`.
+- **servername** `string | null` (optional)
+- **keepAlive** `boolean | null` (optional) - Default: `true` - TCP keep-alive enabled
+- **keepAliveInitialDelay** `number | null` (optional) - Default: `60000` - TCP keep-alive interval for the socket in milliseconds
+
+### Example - Basic Client instantiation
+
+This will instantiate the undici H2CClient, 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`.
+
+```js
+"use strict";
+import { H2CClient } from "undici";
+
+const client = new H2CClient("http://localhost:3000");
+```
+
+## Instance Methods
+
+### `H2CClient.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
+
+### `H2CClient.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+Waits until socket is closed before invoking the callback (or returning a promise if no callback is provided).
+
+### `H2CClient.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
+
+### `H2CClient.dispatch(options, handlers)`
+
+Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
+
+### `H2CClient.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
+
+### `H2CClient.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+
+### `H2CClient.stream(options, factory[, callback])`
+
+See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+
+### `H2CClient.upgrade(options[, callback])`
+
+See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+
+## Instance Properties
+
+### `H2CClient.closed`
+
+- `boolean`
+
+`true` after `H2CClient.close()` has been called.
+
+### `H2CClient.destroyed`
+
+- `boolean`
+
+`true` after `client.destroyed()` has been called or `client.close()` has been called and the client shutdown has completed.
+
+### `H2CClient.pipelining`
+
+- `number`
+
+Property to get and set the pipelining factor.
+
+## Instance Events
+
+### Event: `'connect'`
+
+See [Dispatcher Event: `'connect'`](/docs/docs/api/Dispatcher.md#event-connect).
+
+Parameters:
+
+- **origin** `URL`
+- **targets** `Array<Dispatcher>`
+
+Emitted when a socket has been created and connected. The client will connect once `client.size > 0`.
+
+#### Example - Client connect event
+
+```js
+import { createServer } from "node:http2";
+import { H2CClient } from "undici";
+import { once } from "events";
+
+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}`); // should print before the request body statement
+});
+
+try {
+  const { body } = await client.request({
+    path: "/",
+    method: "GET",
+  });
+  body.setEncoding("utf-8");
+  body.on("data", console.log);
+  client.close();
+  server.close();
+} catch (error) {
+  console.error(error);
+  client.close();
+  server.close();
+}
+```
+
+### Event: `'disconnect'`
+
+See [Dispatcher Event: `'disconnect'`](/docs/docs/api/Dispatcher.md#event-disconnect).
+
+Parameters:
+
+- **origin** `URL`
+- **targets** `Array<Dispatcher>`
+- **error** `Error`
+
+Emitted 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`.
+
+#### Example - Client disconnect event
+
+```js
+import { createServer } from "node:http2";
+import { H2CClient } from "undici";
+import { once } from "events";
+
+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);
+  client.close();
+  server.close();
+}
+```
+
+### Event: `'drain'`
+
+Emitted when pipeline is no longer busy.
+
+See [Dispatcher Event: `'drain'`](/docs/docs/api/Dispatcher.md#event-drain).
+
+#### Example - Client drain event
+
+```js
+import { createServer } from "node:http2";
+import { H2CClient } from "undici";
+import { once } from "events";
+
+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("drain", () => {
+  console.log("drain event");
+  client.close();
+  server.close();
+});
+
+const requests = [
+  client.request({ path: "/", method: "GET" }),
+  client.request({ path: "/", method: "GET" }),
+  client.request({ path: "/", method: "GET" }),
+];
+
+await Promise.all(requests);
+
+console.log("requests completed");
+```
+
+### Event: `'error'`
+
+Invoked for users errors such as throwing in the `onError` handler.

docs/docsify/sidebar.md

@@ -4,6 +4,7 @@
 * API
   * [Dispatcher](/docs/api/Dispatcher.md "Undici API - Dispatcher")
   * [Client](/docs/api/Client.md "Undici API - Client")
+  * [H2CClient](/docs/api/H2CClient.md "Undici H2C API - Client")
   * [Pool](/docs/api/Pool.md "Undici API - Pool")
   * [BalancedPool](/docs/api/BalancedPool.md "Undici API - BalancedPool")
   * [Agent](/docs/api/Agent.md "Undici API - Agent")

index.js

@@ -8,6 +8,7 @@ const Agent = require('./lib/dispatcher/agent')
 const ProxyAgent = require('./lib/dispatcher/proxy-agent')
 const EnvHttpProxyAgent = require('./lib/dispatcher/env-http-proxy-agent')
 const RetryAgent = require('./lib/dispatcher/retry-agent')
+const H2CClient = require('./lib/dispatcher/h2c-client')
 const errors = require('./lib/core/errors')
 const util = require('./lib/core/util')
 const { InvalidArgumentError } = errors
@@ -33,6 +34,7 @@ module.exports.Agent = Agent
 module.exports.ProxyAgent = ProxyAgent
 module.exports.EnvHttpProxyAgent = EnvHttpProxyAgent
 module.exports.RetryAgent = RetryAgent
+module.exports.H2CClient = H2CClient
 module.exports.RetryHandler = RetryHandler
 
 module.exports.DecoratorHandler = DecoratorHandler