Skip to content

Commit 46f39b5

Browse files
jasnellMylesBorins
jasnell
authored and
MylesBorins
committed
doc: add docs for common/http2.js utility
Backport-PR-URL: #18050 PR-URL: #17942 Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
1 parent f17a5b9 commit 46f39b5

File tree

1 file changed

+138
-0
lines changed

1 file changed

+138
-0
lines changed

‎test/common/README.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ This directory contains modules used to test the Node.js implementation.
1212
* [Fixtures module](#fixtures-module)
1313
* [Internet module](#internet-module)
1414
* [WPT module](#wpt-module)
15+
* [HTTP2 module](#http2-module)
1516

1617
## Benchmark Module
1718

@@ -565,6 +566,143 @@ Node.js
565566
implementation with tests from
566567
[W3C Web Platform Tests](https://github.com/w3c/web-platform-tests).
567568

569+
## HTTP/2 Module
570+
571+
The http2.js module provides a handful of utilities for creating mock HTTP/2
572+
frames for testing of HTTP/2 endpoints
573+
574+
<!-- eslint-disable strict -->
575+
<!-- eslint-disable required-modules -->
576+
<!-- eslint-disable no-unused-vars -->
577+
<!-- eslint-disable no-undef -->
578+
```js
579+
const http2 = require('../common/http2');
580+
```
581+
582+
### Class: Frame
583+
584+
The `http2.Frame` is a base class that creates a `Buffer` containing a
585+
serialized HTTP/2 frame header.
586+
587+
<!-- eslint-disable strict -->
588+
<!-- eslint-disable required-modules -->
589+
<!-- eslint-disable no-unused-vars -->
590+
<!-- eslint-disable no-undef -->
591+
```js
592+
// length is a 24-bit unsigned integer
593+
// type is an 8-bit unsigned integer identifying the frame type
594+
// flags is an 8-bit unsigned integer containing the flag bits
595+
// id is the 32-bit stream identifier, if any.
596+
const frame = new http2.Frame(length, type, flags, id);
597+
598+
// Write the frame data to a socket
599+
socket.write(frame.data);
600+
```
601+
602+
The serialized `Buffer` may be retrieved using the `frame.data` property.
603+
604+
### Class: DataFrame extends Frame
605+
606+
The `http2.DataFrame` is a subclass of `http2.Frame` that serializes a `DATA`
607+
frame.
608+
609+
<!-- eslint-disable strict -->
610+
<!-- eslint-disable required-modules -->
611+
<!-- eslint-disable no-unused-vars -->
612+
<!-- eslint-disable no-undef -->
613+
```js
614+
// id is the 32-bit stream identifier
615+
// payload is a Buffer containing the DATA payload
616+
// padlen is an 8-bit integer giving the number of padding bytes to include
617+
// final is a boolean indicating whether the End-of-stream flag should be set,
618+
// defaults to false.
619+
const data = new http2.DataFrame(id, payload, padlen, final);
620+
621+
socket.write(frame.data);
622+
```
623+
624+
### Class: HeadersFrame
625+
626+
The `http2.HeadersFrame` is a subclass of `http2.Frame` that serializes a
627+
`HEADERS` frame.
628+
629+
<!-- eslint-disable strict -->
630+
<!-- eslint-disable required-modules -->
631+
<!-- eslint-disable no-unused-vars -->
632+
<!-- eslint-disable no-undef -->
633+
```js
634+
// id is the 32-bit stream identifier
635+
// payload is a Buffer containing the HEADERS payload (see either
636+
// http2.kFakeRequestHeaders or http2.kFakeResponseHeaders).
637+
// padlen is an 8-bit integer giving the number of padding bytes to include
638+
// final is a boolean indicating whether the End-of-stream flag should be set,
639+
// defaults to false.
640+
const data = new http2.HeadersFrame(id, http2.kFakeRequestHeaders,
641+
padlen, final);
642+
643+
socket.write(frame.data);
644+
```
645+
646+
### Class: SettingsFrame
647+
648+
The `http2.SettingsFrame` is a subclass of `http2.Frame` that serializes an
649+
empty `SETTINGS` frame.
650+
651+
<!-- eslint-disable strict -->
652+
<!-- eslint-disable required-modules -->
653+
<!-- eslint-disable no-unused-vars -->
654+
<!-- eslint-disable no-undef -->
655+
```js
656+
// ack is a boolean indicating whether or not to set the ACK flag.
657+
const frame = new http2.SettingsFrame(ack);
658+
659+
socket.write(frame.data);
660+
```
661+
662+
### http2.kFakeRequestHeaders
663+
664+
Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
665+
request headers to be used as the payload of a `http2.HeadersFrame`.
666+
667+
<!-- eslint-disable strict -->
668+
<!-- eslint-disable required-modules -->
669+
<!-- eslint-disable no-unused-vars -->
670+
<!-- eslint-disable no-undef -->
671+
```js
672+
const frame = new http2.HeadersFrame(1, http2.kFakeRequestHeaders, 0, true);
673+
674+
socket.write(frame.data);
675+
```
676+
677+
### http2.kFakeResponseHeaders
678+
679+
Set to a `Buffer` instance that contains a minimal set of serialized HTTP/2
680+
response headers to be used as the payload a `http2.HeadersFrame`.
681+
682+
<!-- eslint-disable strict -->
683+
<!-- eslint-disable required-modules -->
684+
<!-- eslint-disable no-unused-vars -->
685+
<!-- eslint-disable no-undef -->
686+
```js
687+
const frame = new http2.HeadersFrame(1, http2.kFakeResponseHeaders, 0, true);
688+
689+
socket.write(frame.data);
690+
```
691+
692+
### http2.kClientMagic
693+
694+
Set to a `Buffer` containing the preamble bytes an HTTP/2 client must send
695+
upon initial establishment of a connection.
696+
697+
<!-- eslint-disable strict -->
698+
<!-- eslint-disable required-modules -->
699+
<!-- eslint-disable no-unused-vars -->
700+
<!-- eslint-disable no-undef -->
701+
```js
702+
socket.write(http2.kClientMagic);
703+
```
704+
705+
568706
[&lt;Array>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
569707
[&lt;ArrayBufferView&#91;&#93;>]: https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView
570708
[&lt;Boolean>]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type

0 commit comments

Comments
 (0)