http2: major update to internals

This update does several significant things:

1. It eliminates the base Nghttp2* classes and folds those
   in to node::http2::Http2Session and node::http2::Http2Stream
2. It makes node::http2::Http2Stream a StreamBase instance and
   sends that out to JS-land to act as the [kHandle] for the
   JavaScript Http2Stream class.
3. It shifts some of the callbacks from C++ off of the JavaScript
   Http2Session class to the Http2Stream class.
4. It refactors the data provider structure for FD and Stream
   based sending to help encapsulate those functions easier
5. It streamlines some of the functions at the C++ layer to
   eliminate now unnecessary redirections
6. It cleans up node_http2.cc for better readability and
   maintainability
7. It refactors some of the debug output
8. Because Http2Stream instances are now StreamBases, they are
   now also trackable using async-hooks
9. The Stream::OnRead algorithm has been simplified with a
   couple bugs fixed.
10. I've eliminated node_http2_core.h and node_http2_core-inl.h
11. Detect invalid handshake a report protocol error to session
12. Refactor out of memory error, improve other errors
13. Add Http2Session.prototype.ping

PR-URL: #17105
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Sebastiaan Deckers <[email protected]>

Author: jasnell

doc/api/errors.md

@@ -873,6 +873,16 @@ created.
 Used when a message payload is specified for an HTTP response code for which
 a payload is forbidden.
 
+<a id="ERR_HTTP2_PING_CANCEL"></a>
+### ERR_HTTP2_PING_CANCEL
+
+An HTTP/2 ping was cancelled.
+
+<a id="ERR_HTTP2_PING_LENGTH"></a>
+### ERR_HTTP2_PING_LENGTH
+
+HTTP/2 ping payloads must be exactly 8 bytes in length.
+
 <a id="ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED"></a>
 ### ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED
 

doc/api/http2.md

@@ -342,6 +342,44 @@ acknowledgement for a sent SETTINGS frame. Will be `true` after calling the
 `http2session.settings()` method. Will be `false` once all sent SETTINGS
 frames have been acknowledged.
 
+#### http2session.ping([payload, ]callback)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `payload` {Buffer|TypedArray|DataView} Optional ping payload.
+* `callback` {Function}
+* Returns: {boolean}
+
+Sends a `PING` frame to the connected HTTP/2 peer. A `callback` function must
+be provided. The method will return `true` if the `PING` was sent, `false`
+otherwise.
+
+The maximum number of outstanding (unacknowledged) pings is determined by the
+`maxOutstandingPings` configuration option. The default maximum is 10.
+
+If provided, the `payload` must be a `Buffer`, `TypedArray`, or `DataView`
+containing 8 bytes of data that will be transmitted with the `PING` and
+returned with the ping acknowledgement.
+
+The callback will be invoked with three arguments: an error argument that will
+be `null` if the `PING` was successfully acknowledged, a `duration` argument
+that reports the number of milliseconds elapsed since the ping was sent and the
+acknowledgement was received, and a `Buffer` containing the 8-byte `PING`
+payload.
+
+```js
+session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => {
+  if (!err) {
+    console.log(`Ping acknowledged in ${duration} milliseconds`);
+    console.log(`With payload '${payload.toString()}`);
+  }
+});
+```
+
+If the `payload` argument is not specified, the default payload will be the
+64-bit timestamp (little endian) marking the start of the `PING` duration.
+
 #### http2session.remoteSettings
 <!-- YAML
 added: v8.4.0
@@ -409,19 +447,6 @@ the trailing header fields to send to the peer.
 will be emitted if the `getTrailers` callback attempts to set such header
 fields.
 
-#### http2session.rstStream(stream, code)
-<!-- YAML
-added: v8.4.0
--->
-
-* stream {Http2Stream}
-* code {number} Unsigned 32-bit integer identifying the error code. **Default:**
-  `http2.constant.NGHTTP2_NO_ERROR` (`0x00`)
-* Returns: {undefined}
-
-Sends an `RST_STREAM` frame to the connected HTTP/2 peer, causing the given
-`Http2Stream` to be closed on both sides using [error code][] `code`.
-
 #### http2session.setTimeout(msecs, callback)
 <!-- YAML
 added: v8.4.0
@@ -513,28 +538,6 @@ added: v8.4.0
 
 An object describing the current status of this `Http2Session`.
 
-#### http2session.priority(stream, options)
-<!-- YAML
-added: v8.4.0
--->
-
-* `stream` {Http2Stream}
-* `options` {Object}
-  * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream,
-    the given stream is made the sole direct dependency of the parent, with
-    all other existing dependents made a dependent of the given stream. **Default:**
-    `false`
-  * `parent` {number} Specifies the numeric identifier of a stream the given
-    stream is dependent on.
-  * `weight` {number} Specifies the relative dependency of a stream in relation
-    to other streams with the same `parent`. The value is a number between `1`
-    and `256` (inclusive).
-  * `silent` {boolean} When `true`, changes the priority locally without
-    sending a `PRIORITY` frame to the connected peer.
-* Returns: {undefined}
-
-Updates the priority for the given `Http2Stream` instance.
-
 #### http2session.settings(settings)
 <!-- YAML
 added: v8.4.0
@@ -622,8 +625,7 @@ is not yet ready for use.
 All [`Http2Stream`][] instances are destroyed either when:
 
 * An `RST_STREAM` frame for the stream is received by the connected peer.
-* The `http2stream.rstStream()` or `http2session.rstStream()` methods are
-  called.
+* The `http2stream.rstStream()` methods is called.
 * The `http2stream.destroy()` or `http2session.destroy()` methods are called.
 
 When an `Http2Stream` instance is destroyed, an attempt will be made to send an
@@ -1471,6 +1473,10 @@ not be emitted.
 <!-- YAML
 added: v8.4.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/17105
+    description: Added the `maxOutstandingPings` option with a default limit of
+                 10.
   - version: v9.1.0
     pr-url: https://github.com/nodejs/node/pull/16676
     description: Added the `maxHeaderListPairs` option with a default limit of
@@ -1482,6 +1488,8 @@ changes:
     for deflating header fields. **Default:** `4Kib`
   * `maxHeaderListPairs` {number} Sets the maximum number of header entries.
     **Default:** `128`. The minimum value is `4`.
+  * `maxOutstandingPings` {number} Sets the maximum number of outstanding,
+    unacknowledged pings. The default is `10`.
   * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a
     serialized, compressed block of headers. Attempts to send headers that
     exceed this limit will result in a `'frameError'` event being emitted
@@ -1533,6 +1541,10 @@ server.listen(80);
 <!-- YAML
 added: v8.4.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/17105
+    description: Added the `maxOutstandingPings` option with a default limit of
+                 10.
   - version: v9.1.0
     pr-url: https://github.com/nodejs/node/pull/16676
     description: Added the `maxHeaderListPairs` option with a default limit of
@@ -1547,6 +1559,8 @@ changes:
     for deflating header fields. **Default:** `4Kib`
   * `maxHeaderListPairs` {number} Sets the maximum number of header entries.
     **Default:** `128`. The minimum value is `4`.
+  * `maxOutstandingPings` {number} Sets the maximum number of outstanding,
+    unacknowledged pings. The default is `10`.
   * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a
     serialized, compressed block of headers. Attempts to send headers that
     exceed this limit will result in a `'frameError'` event being emitted
@@ -1605,6 +1619,10 @@ server.listen(80);
 <!-- YAML
 added: v8.4.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/17105
+    description: Added the `maxOutstandingPings` option with a default limit of
+                 10.
   - version: v9.1.0
     pr-url: https://github.com/nodejs/node/pull/16676
     description: Added the `maxHeaderListPairs` option with a default limit of
@@ -1617,6 +1635,8 @@ changes:
     for deflating header fields. **Default:** `4Kib`
   * `maxHeaderListPairs` {number} Sets the maximum number of header entries.
     **Default:** `128`. The minimum value is `1`.
+  * `maxOutstandingPings` {number} Sets the maximum number of outstanding,
+    unacknowledged pings. The default is `10`.
   * `maxReservedRemoteStreams` {number} Sets the maximum number of reserved push
     streams the client will accept at any given time. Once the current number of
     currently reserved push streams exceeds reaches this limit, new push streams

lib/internal/errors.js

@@ -221,6 +221,8 @@ E('ERR_HTTP2_OUT_OF_STREAMS',
   'No stream ID is available because maximum stream ID has been reached');
 E('ERR_HTTP2_PAYLOAD_FORBIDDEN',
   (code) => `Responses with ${code} status must not have a payload`);
+E('ERR_HTTP2_PING_CANCEL', 'HTTP2 ping cancelled');
+E('ERR_HTTP2_PING_LENGTH', 'HTTP2 ping payload must be 8 bytes');
 E('ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED', 'Cannot set HTTP/2 pseudo-headers');
 E('ERR_HTTP2_PUSH_DISABLED', 'HTTP/2 client has disabled push streams');
 E('ERR_HTTP2_SEND_FILE', 'Only regular files can be sent');