http2: customSettings add documentation

Add an explanation to the documentation for Http2Settings to explain the usage of customSettings and its limitations. Co-authored-by: James M Snell <[email protected]>
nodejs · Nov 27, 2023 · 2860c65 · 2860c65
1 parent 6bedd4c
commit 2860c65
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 0 deletions.
diff --git a/doc/api/errors.md b/doc/api/errors.md
@@ -1710,6 +1710,12 @@ When setting the priority for an HTTP/2 stream, the stream may be marked as
 a dependency for a parent stream. This error code is used when an attempt is
 made to mark a stream and dependent of itself.
 
+<a id="ERR_HTTP2_TOO_MANY_CUSTOM_SETTINGS"></a>
+
+### `ERR_HTTP2_TOO_MANY_CUSTOM_SETTINGS`
+
+The number of supported custom settings (10) has been exceeded.
+
 <a id="ERR_HTTP2_TOO_MANY_INVALID_FRAMES"></a>
 
 ### `ERR_HTTP2_TOO_MANY_INVALID_FRAMES`

diff --git a/doc/api/http2.md b/doc/api/http2.md
@@ -3010,6 +3010,19 @@ properties.
   meaningful if sent by the server. Once the `enableConnectProtocol` setting
   has been enabled for a given `Http2Session`, it cannot be disabled.
   **Default:** `false`.
+* `customSettings` {Object} Specifies additional settings, yet not implemented
+  in node and the underlying libraries. The key of the object defines the
+  numeric value of the settings type (as defined in the "HTTP/2 SETTINGS"
+  registry established by \[RFC 7540]) and the values the actual numeric value
+  of the settings.
+  The settings type has to be an integer in the range from 1 to 2^16-1.
+  It should not be a settings type already handled by node, i.e. currently
+  it should be greater than 6, although it is not an error.
+  The values need to be unsigned integers in the range from 0 to 2^32-1.
+  Currently, a maximum of up 10 custom settings is supported.
+  It is only supported for sending SETTINGS.
+  Custom settings are not supported for the functions retrieving remote and
+  local settings as nghttp2 does not pass unknown HTTP/2 settings to Node.js.
 
 All additional properties on the settings object are ignored.