From e8a9945fd87a2d047f2d8a0aa4f2ee8849e61858 Mon Sep 17 00:00:00 2001 From: Fred Cox Date: Fri, 15 Sep 2023 15:29:33 +0100 Subject: [PATCH] improve documentation of timeouts by making the units clear in all places (#2266) --- docs/api/Client.md | 10 +++++----- docs/api/Connector.md | 4 ++-- docs/api/Dispatcher.md | 2 +- types/client.d.ts | 14 +++++++------- types/dispatcher.d.ts | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/api/Client.md b/docs/api/Client.md index 591fb97c44b..c0987713a32 100644 --- a/docs/api/Client.md +++ b/docs/api/Client.md @@ -20,10 +20,10 @@ Returns: `Client` > ⚠️ Warning: The `H2` support is experimental. * **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. -* **headersTimeout** `number | null` (optional) - Default: `300e3` - The amount of time 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` when overridden by *keep-alive* hints from the server. Defaults to 10 minutes. -* **keepAliveTimeout** `number | null` (optional) - Default: `4e3` - The timeout 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: `1e3` - A number subtracted from server *keep-alive* hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 1 second. +* **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: `1e3` - 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 1 second. * **maxHeaderSize** `number | null` (optional) - Default: `16384` - The maximum length of request headers in bytes. Defaults to 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. @@ -42,7 +42,7 @@ Furthermore, the following options can be passed: * **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe. * **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: 100. -* **timeout** `number | null` (optional) - Default `10e3` +* **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 diff --git a/docs/api/Connector.md b/docs/api/Connector.md index 7c966507e5f..56821bd6430 100644 --- a/docs/api/Connector.md +++ b/docs/api/Connector.md @@ -13,8 +13,8 @@ Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_opt Furthermore, the following options can be passed: * **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe. -* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: 100. -* **timeout** `number | null` (optional) - Default `10e3` +* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`. +* **timeout** `number | null` (optional) - In milliseconds. Default `10e3`. * **servername** `string | null` (optional) Once you call `buildConnector`, it will return a connector function, which takes the following parameters. diff --git a/docs/api/Dispatcher.md b/docs/api/Dispatcher.md index a04be8cff1e..fd463bfea16 100644 --- a/docs/api/Dispatcher.md +++ b/docs/api/Dispatcher.md @@ -200,7 +200,7 @@ Returns: `Boolean` - `false` if dispatcher is busy and further dispatch calls wo * **blocking** `boolean` (optional) - Default: `false` - Whether the response is expected to take a long time and would end up blocking the pipeline. When this is set to `true` further pipelining will be avoided on the same connection until headers have been received. * **upgrade** `string | null` (optional) - Default: `null` - Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`. * **bodyTimeout** `number | null` (optional) - 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. -* **headersTimeout** `number | null` (optional) - The amount of time the parser will wait to receive the complete HTTP headers while not sending the request. Defaults to 300 seconds. +* **headersTimeout** `number | null` (optional) - 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. * **throwOnError** `boolean` (optional) - Default: `false` - Whether Undici should throw an error upon receiving a 4xx or 5xx response from the server. * **expectContinue** `boolean` (optional) - Default: `false` - For H2, it appends the expect: 100-continue header, and halts the request body until a 100-continue is received from the remote server diff --git a/types/client.d.ts b/types/client.d.ts index 3d348f9427b..0ed42cd4f1f 100644 --- a/types/client.d.ts +++ b/types/client.d.ts @@ -26,7 +26,7 @@ export declare namespace Client { interceptors?: OptionsInterceptors; /** The maximum length of request headers in bytes. Default: `16384` (16KiB). */ maxHeaderSize?: number; - /** The amount of time the parser will wait to receive the complete HTTP headers (Node 14 and above only). Default: `300e3` milliseconds (300s). */ + /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers (Node 14 and above only). Default: `300e3` milliseconds (300s). */ headersTimeout?: number; /** @deprecated unsupported socketTimeout, use headersTimeout & bodyTimeout instead */ socketTimeout?: never; @@ -40,13 +40,13 @@ export declare namespace Client { idleTimeout?: never; /** @deprecated unsupported keepAlive, use pipelining=0 instead */ keepAlive?: never; - /** the timeout 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. Default: `4e3` milliseconds (4s). */ + /** 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. Default: `4e3` milliseconds (4s). */ keepAliveTimeout?: number; /** @deprecated unsupported maxKeepAliveTimeout, use keepAliveMaxTimeout instead */ maxKeepAliveTimeout?: never; - /** the maximum allowed `idleTimeout` when overridden by *keep-alive* hints from the server. Default: `600e3` milliseconds (10min). */ + /** the maximum allowed `idleTimeout`, in milliseconds, when overridden by *keep-alive* hints from the server. Default: `600e3` milliseconds (10min). */ keepAliveMaxTimeout?: number; - /** A number subtracted from server *keep-alive* hints when overriding `idleTimeout` to account for timing inaccuracies caused by e.g. transport latency. Default: `1e3` milliseconds (1s). */ + /** A number of milliseconds subtracted from server *keep-alive* hints when overriding `idleTimeout` to account for timing inaccuracies caused by e.g. transport latency. Default: `1e3` milliseconds (1s). */ keepAliveTimeoutThreshold?: number; /** TODO */ socketPath?: string; @@ -71,13 +71,13 @@ export declare namespace Client { /** Enables a family autodetection algorithm that loosely implements section 5 of RFC 8305. */ autoSelectFamily?: boolean; /** The amount of time in milliseconds to wait for a connection attempt to finish before trying the next address when using the `autoSelectFamily` option. */ - autoSelectFamilyAttemptTimeout?: number; - /** + autoSelectFamilyAttemptTimeout?: number; + /** * @description Enables support for H2 if the server has assigned bigger priority to it through ALPN negotiation. * @default false */ allowH2?: boolean; - /** + /** * @description Dictates the maximum number of concurrent streams for a single H2 session. It can be overriden by a SETTINGS remote frame. * @default 100 */ diff --git a/types/dispatcher.d.ts b/types/dispatcher.d.ts index 42a78ba0834..816db19d20d 100644 --- a/types/dispatcher.d.ts +++ b/types/dispatcher.d.ts @@ -109,7 +109,7 @@ declare namespace Dispatcher { blocking?: boolean; /** Upgrade the request. Should be used to specify the kind of upgrade i.e. `'Websocket'`. Default: `method === 'CONNECT' || null`. */ upgrade?: boolean | string | null; - /** The amount of time the parser will wait to receive the complete HTTP headers. Defaults to 300 seconds. */ + /** The amount of time, in milliseconds, the parser will wait to receive the complete HTTP headers. Defaults to 300 seconds. */ headersTimeout?: number | null; /** 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. */ bodyTimeout?: number | null;