doc: add docs for common/http2.js utility

Backport-PR-URL: #18050 PR-URL: #17942 Reviewed-By: Matteo Collina <[email protected]>
nodejs · Jan 10, 2018 · 46f39b5 · 46f39b5
1 parent f17a5b9
commit 46f39b5
Showing 1 changed file with 138 additions and 0 deletions.
diff --git a/test/common/README.md b/test/common/README.md
@@ -12,6 +12,7 @@ This directory contains modules used to test the Node.js implementation.
 * [Fixtures module](#fixtures-module)
 * [Internet module](#internet-module)
 * [WPT module](#wpt-module)
+* [HTTP2 module](#http2-module)
 
 ## Benchmark Module
 
@@ -565,6 +566,143 @@ Node.js
 implementation with tests from
 [W3C Web Platform Tests](https://github.com/w3c/web-platform-tests).
 
+## HTTP/2 Module
+
+The http2.js module provides a handful of utilities for creating mock HTTP/2
+frames for testing of HTTP/2 endpoints
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+const http2 = require('../common/http2');
+```
+
+### Class: Frame
+
+The `http2.Frame` is a base class that creates a `Buffer` containing a
+serialized HTTP/2 frame header.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+// length is a 24-bit unsigned integer
+// type is an 8-bit unsigned integer identifying the frame type
+// flags is an 8-bit unsigned integer containing the flag bits
+// id is the 32-bit stream identifier, if any.
+const frame = new http2.Frame(length, type, flags, id);
+
+// Write the frame data to a socket
+socket.write(frame.data);
+```
+
+The serialized `Buffer` may be retrieved using the `frame.data` property.
+
+### Class: DataFrame extends Frame
+
+The `http2.DataFrame` is a subclass of `http2.Frame` that serializes a `DATA`
+frame.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+// id is the 32-bit stream identifier
+// payload is a Buffer containing the DATA payload
+// padlen is an 8-bit integer giving the number of padding bytes to include
+// final is a boolean indicating whether the End-of-stream flag should be set,
+// defaults to false.
+const data = new http2.DataFrame(id, payload, padlen, final);
+
+socket.write(frame.data);
+```
+
+### Class: HeadersFrame
+
+The `http2.HeadersFrame` is a subclass of `http2.Frame` that serializes a
+`HEADERS` frame.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+// id is the 32-bit stream identifier
+// payload is a Buffer containing the HEADERS payload (see either
+// http2.kFakeRequestHeaders or http2.kFakeResponseHeaders).
+// padlen is an 8-bit integer giving the number of padding bytes to include
+// final is a boolean indicating whether the End-of-stream flag should be set,
+// defaults to false.
+const data = new http2.HeadersFrame(id, http2.kFakeRequestHeaders,
+                                    padlen, final);
+
+socket.write(frame.data);
+```
+
+### Class: SettingsFrame
+
+The `http2.SettingsFrame` is a subclass of `http2.Frame` that serializes an
+empty `SETTINGS` frame.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+// ack is a boolean indicating whether or not to set the ACK flag.
+const frame = new http2.SettingsFrame(ack);
+
+socket.write(frame.data);
+```
+
+### http2.kFakeRequestHeaders
+
+Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
+request headers to be used as the payload of a `http2.HeadersFrame`.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+const frame = new http2.HeadersFrame(1, http2.kFakeRequestHeaders, 0, true);
+
+socket.write(frame.data);
+```
+
+### http2.kFakeResponseHeaders
+
+Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
+response headers to be used as the payload a `http2.HeadersFrame`.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+const frame = new http2.HeadersFrame(1, http2.kFakeResponseHeaders, 0, true);
+
+socket.write(frame.data);
+```
+
+### http2.kClientMagic
+
+Set to a `Buffer` containing the preamble bytes an HTTP/2 client must send
+upon initial establishment of a connection.
+
+<!-- eslint-disable strict -->
+<!-- eslint-disable required-modules -->
+<!-- eslint-disable no-unused-vars -->
+<!-- eslint-disable no-undef -->
+```js
+socket.write(http2.kClientMagic);
+```
+
+
 [&lt;Array>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
 [&lt;ArrayBufferView&#91;&#93;>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView
 [&lt;Boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type