diff --git a/doc/api/errors.md b/doc/api/errors.md
index 1c5836e553df1a..1ab394580e7b76 100755
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -861,6 +861,19 @@ 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.
+
+### ERR_HTTP2_TRAILERS_ALREADY_SENT
+
+Trailing headers have already been sent on the `Http2Stream`.
+
+
+### ERR_HTTP2_TRAILERS_NOT_READY
+
+The `http2stream.sendTrailers()` method cannot be called until after the
+`'wantTrailers'` event is emitted on an `Http2Stream` object. The
+`'wantTrailers'` event will only be emitted if the `waitForTrailers` option
+is set for the `Http2Stream`.
+
### ERR_HTTP2_UNSUPPORTED_PROTOCOL
diff --git a/doc/api/http2.md b/doc/api/http2.md
index 78a8897c00b55a..300bd44df3ae31 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -176,13 +176,13 @@ immediately following the `'frameError'` event.
added: v8.4.0
-->
-The `'goaway'` event is emitted when a GOAWAY frame is received. When invoked,
+The `'goaway'` event is emitted when a `GOAWAY` frame is received. When invoked,
the handler function will receive three arguments:
-* `errorCode` {number} The HTTP/2 error code specified in the GOAWAY frame.
+* `errorCode` {number} The HTTP/2 error code specified in the `GOAWAY` frame.
* `lastStreamID` {number} The ID of the last stream the remote peer successfully
processed (or `0` if no ID is specified).
-* `opaqueData` {Buffer} If additional opaque data was included in the GOAWAY
+* `opaqueData` {Buffer} If additional opaque data was included in the `GOAWAY`
frame, a `Buffer` instance will be passed containing that data.
*Note*: The `Http2Session` instance will be shut down automatically when the
@@ -193,7 +193,7 @@ the handler function will receive three arguments:
added: v8.4.0
-->
-The `'localSettings'` event is emitted when an acknowledgment SETTINGS frame
+The `'localSettings'` event is emitted when an acknowledgment `SETTINGS` frame
has been received. When invoked, the handler function will receive a copy of
the local settings.
@@ -214,7 +214,7 @@ session.on('localSettings', (settings) => {
added: v8.4.0
-->
-The `'remoteSettings'` event is emitted when a new SETTINGS frame is received
+The `'remoteSettings'` event is emitted when a new `SETTINGS` frame is received
from the connected peer. When invoked, the handler function will receive a copy
of the remote settings.
@@ -385,7 +385,7 @@ added: v8.11.2
* `code` {number} An HTTP/2 error code
* `lastStreamID` {number} The numeric ID of the last processed `Http2Stream`
* `opaqueData` {Buffer|TypedArray|DataView} A `TypedArray` or `DataView`
- instance containing additional data to be carried within the GOAWAY frame.
+ instance containing additional data to be carried within the `GOAWAY` frame.
Transmits a `GOAWAY` frame to the connected peer *without* shutting down the
`Http2Session`.
@@ -419,7 +419,7 @@ added: v8.4.0
* Value: {boolean}
Indicates whether or not the `Http2Session` is currently waiting for an
-acknowledgment for a sent SETTINGS frame. Will be `true` after calling the
+acknowledgment 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.
@@ -554,9 +554,9 @@ Once called, the `http2session.pendingSettingsAck` property will be `true`
while the session is waiting for the remote peer to acknowledge the new
settings.
-*Note*: The new settings will not become effective until the SETTINGS
+*Note*: The new settings will not become effective until the `SETTINGS`
acknowledgment is received and the `'localSettings'` event is emitted. It
-is possible to send multiple SETTINGS frames while acknowledgment is still
+is possible to send multiple `SETTINGS` frames while acknowledgment is still
pending.
#### http2session.type
@@ -699,8 +699,8 @@ added: v8.4.0
* `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).
- * `getTrailers` {Function} Callback function invoked to collect trailer
- headers.
+ * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the
+ `'wantTrailers'` event after the final `DATA` frame has been sent.
* Returns: {ClientHttp2Stream}
@@ -727,15 +727,15 @@ req.on('response', (headers) => {
});
```
-When set, the `options.getTrailers()` function is called immediately after
-queuing the last chunk of payload data to be sent. The callback is passed a
-single object (with a `null` prototype) that the listener may use to specify
-the trailing header fields to send to the peer.
+When the `options.waitForTrailers` option is set, the `'wantTrailers'` event
+is emitted immediately after queuing the last chunk of payload data to be sent.
+The `http2stream.sendTrailers()` method can then be called to send trailing
+headers to the peer.
-*Note*: The HTTP/1 specification forbids trailers from containing HTTP/2
-pseudo-header fields (e.g. `':method'`, `':path'`, etc). An `'error'` event
-will be emitted if the `getTrailers` callback attempts to set such header
-fields.
+It is important to note that when `options.waitForTrailers` is set, the
+`Http2Stream` will *not* automatically close when the final `DATA` frame is
+transmitted. User code *must* call either `http2stream.sendTrailers()` or
+`http2stream.close()` to close the `Http2Stream`.
The `:method` and `:path` pseudo-headers are not specified within `headers`,
they respectively default to:
@@ -881,6 +881,16 @@ stream.on('trailers', (headers, flags) => {
});
```
+#### Event: 'wantTrailers'
+
+
+The `'wantTrailers'` event is emitted when the `Http2Stream` has queued the
+final `DATA` frame to be sent on a frame and the `Http2Stream` is ready to send
+trailing headers. When initiating a request or response, the `waitForTrailers`
+option must be set for this event to be emitted.
+
#### http2stream.aborted
+
+* `headers` {HTTP/2 Headers Object}
+
+Sends a trailing `HEADERS` frame to the connected HTTP/2 peer. This method
+will cause the `Http2Stream` to be immediately closed and must only be
+called after the `'wantTrailers'` event has been emitted. When sending a
+request or sending a response, the `options.waitForTrailers` option must be set
+in order to keep the `Http2Stream` open after the final `DATA` frame so that
+trailers can be sent.
+
+```js
+const http2 = require('http2');
+const server = http2.createServer();
+server.on('stream', (stream) => {
+ stream.respond(undefined, { waitForTrailers: true });
+ stream.on('wantTrailers', () => {
+ stream.sendTrailers({ xyz: 'abc' });
+ });
+ stream.end('Hello World');
+});
+```
+
+The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header
+fields (e.g. `':method'`, `':path'`, etc).
+
### Class: ClientHttp2Stream