From df10f60cfc65026649af38a891274c9a268c6c32 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:39:46 -0800 Subject: [PATCH 01/17] doc: fix _shutdown_/_shut down_ usage in http2.md _shutdown_ is a noun, but the verb form is _shut down_. "There was a government shutdown during which the government shut down." --- doc/api/http2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 4a071272fa85b7..df4872c00eb6e8 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -166,7 +166,7 @@ When invoked, the handler function will receive three arguments: If the `'frameError'` event is associated with a stream, the stream will be closed and destroyed immediately following the `'frameError'` event. If the -event is not associated with a stream, the `Http2Session` will be shutdown +event is not associated with a stream, the `Http2Session` will be shut down immediately following the `'frameError'` event. #### Event: 'goaway' @@ -183,7 +183,7 @@ the handler function will receive three arguments: * `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 shutdown automatically when the +*Note*: The `Http2Session` instance will be shut down automatically when the `'goaway'` event is emitted. #### Event: 'localSettings' @@ -499,7 +499,7 @@ added: v8.4.0 has been completed. * Returns: {undefined} -Attempts to shutdown this `Http2Session` using HTTP/2 defined procedures. +Attempts to shut down this `Http2Session` using HTTP/2 defined procedures. If specified, the given `callback` function will be invoked once the shutdown process has completed. From cbb7c11629377a20d535bb564db369d27088c04a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:42:05 -0800 Subject: [PATCH 02/17] doc: fix misspelling in http2.md _instance_ was misspelled in the doc. The spelling has been corrected. --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index df4872c00eb6e8..4146d69701d2c8 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -635,7 +635,7 @@ may be passed to clear any previously set alternative service for a given domain. When a string is passed for the `originOrStream` argument, it will be parsed as -a URL and the origin will be derived. For insetance, the origin for the +a URL and the origin will be derived. For instance, the origin for the HTTP URL `'https://example.org/foo/bar'` is the ASCII string `'https://example.org'`. An error will be thrown if either the given string cannot be parsed as a URL or if a valid origin cannot be derived. From 60d28ae2f8d0446c00af41fdcd6101f30f890ade Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:43:49 -0800 Subject: [PATCH 03/17] doc: edit _pseudo-header_ usage in http2.md Use a dash consistently in _pseudo-header_ (which is also consistent with RFC 7540). Remove scare-quotes from the term. --- doc/api/http2.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 4146d69701d2c8..b07e2891b4fef5 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -743,11 +743,11 @@ single object (with a `null` prototype) that the listener may used to specify the trailing header fields to send 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 +pseudo-header fields (e.g. `':method'`, `':path'`, etc). An `'error'` event will be emitted if the `getTrailers` callback attempts to set such header fields. -The `:method` and `:path` pseudoheaders are not specified within `headers`, +The `:method` and `:path` pseudo-headers are not specified within `headers`, they respectively default to: * `:method` = `'GET'` @@ -1215,7 +1215,7 @@ server.on('stream', (stream) => { ``` *Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 -"pseudo-header" fields (e.g. `':status'`, `':path'`, etc). An `'error'` event +pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted if the `getTrailers` callback attempts to set such header fields. @@ -1299,7 +1299,7 @@ server.on('close', () => fs.closeSync(fd)); ``` *Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 -"pseudo-header" fields (e.g. `':status'`, `':path'`, etc). An `'error'` event +pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted if the `getTrailers` callback attempts to set such header fields. @@ -1408,7 +1408,7 @@ server.on('stream', (stream) => { ``` *Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 -"pseudo-header" fields (e.g. `':status'`, `':path'`, etc). An `'error'` event +pseudo-header fields (e.g. `':status'`, `':path'`, etc). An `'error'` event will be emitted if the `getTrailers` callback attempts to set such header fields. From bd47954538405f4877f77500f166c2cf101a797e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:46:32 -0800 Subject: [PATCH 04/17] doc: fix verb conjugation in http2.md Use _is_ rather than _are_ following "each of which". While "each of which are" might seem equally correct in passing, making the phrase slightly more explicit makes it clear that _is_ is the correct choice: "each one of which is". --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index b07e2891b4fef5..4eb11e2e88752f 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -774,7 +774,7 @@ On the client, `Http2Stream` instances are created and returned when either the `'push'` event. *Note*: The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and -[`ClientHttp2Stream`][] classes, each of which are used specifically by either +[`ClientHttp2Stream`][] classes, each of which is used specifically by either the Server or Client side, respectively. All `Http2Stream` instances are [`Duplex`][] streams. The `Writable` side of the From a933b14d992ae0f4d0158976b36569cc5118066e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:49:39 -0800 Subject: [PATCH 05/17] doc: simplify awkward wording in http2.md "have need to" -> "need to" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 4eb11e2e88752f..052ae789fb6c8c 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -798,7 +798,7 @@ On the client side, instances of [`ClientHttp2Stream`][] are created when the `http2session.request()` may not be immediately ready for use if the parent `Http2Session` has not yet been fully established. In such cases, operations called on the `Http2Stream` will be buffered until the `'ready'` event is -emitted. User code should rarely, if ever, have need to handle the `'ready'` +emitted. User code should rarely, if ever, need to handle the `'ready'` event directly. The ready status of an `Http2Stream` can be determined by checking the value of `http2stream.id`. If the value is `undefined`, the stream is not yet ready for use. From e9ad9fe9e9548301cf8054622a6ee8ba0fc1a20a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:50:51 -0800 Subject: [PATCH 06/17] doc: fix verb conjugation in http2.md "a block of...headers are received" -> "a block of...headers is received". The verb is for the block, not the headers. --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 052ae789fb6c8c..1cc046e1a61d93 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1048,7 +1048,7 @@ added: v8.4.0 --> The `'headers'` event is emitted when an additional block of headers is received -for a stream, such as when a block of `1xx` informational headers are received. +for a stream, such as when a block of `1xx` informational headers is received. The listener callback is passed the [Headers Object][] and flags associated with the headers. From 44f47866f64318af9cd3c861b1c5e34845b35b79 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:52:44 -0800 Subject: [PATCH 07/17] doc: fix verb conjugation in http2.md "that the listener may used to specify" -> "that the listener may use to specify" --- doc/api/http2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 1cc046e1a61d93..5c9f5f6304e465 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -739,7 +739,7 @@ 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 used to specify +single object (with a `null` prototype) that the listener may use to specify the trailing header fields to send to the peer. *Note*: The HTTP/1 specification forbids trailers from containing HTTP/2 @@ -1198,7 +1198,7 @@ server.on('stream', (stream) => { 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 used to specify +single object (with a `null` prototype) that the listener may use to specify the trailing header fields to send to the peer. ```js @@ -1272,7 +1272,7 @@ requests. 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 used to specify +single object (with a `null` prototype) that the listener may use to specify the trailing header fields to send to the peer. ```js @@ -1391,7 +1391,7 @@ default behavior is to destroy the stream. 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 used to specify +single object (with a `null` prototype) that the listener may use to specify the trailing header fields to send to the peer. ```js From 216fe10ecd27b05651f9aadca2ae84e85b33c996 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:53:56 -0800 Subject: [PATCH 08/17] doc: fix comma splice in http2.md Fix comma splice. Also clarify if/then construction in previous clause. --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 5c9f5f6304e465..6e28f5e149c06c 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1331,7 +1331,7 @@ of the given file: If an error occurs while attempting to read the file data, the `Http2Stream` will be closed using an `RST_STREAM` frame using the standard `INTERNAL_ERROR` -code. If the `onError` callback is defined it will be called, otherwise +code. If the `onError` callback is defined, then it will be called. Otherwise the stream will be destroyed. Example using a file path: From 6a31d45ce730a20ac625fd231fb3e9ef87badda1 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:54:58 -0800 Subject: [PATCH 09/17] doc: fix a vs. an in http2.md "an ServerHttp2Stream" -> "a ServerHttp2Stream" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 6e28f5e149c06c..402c423dc33978 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1478,7 +1478,7 @@ an `Http2Session` object associated with the `Http2Server`. added: v8.5.0 --> -If an `ServerHttp2Stream` emits an `'error'` event, it will be forwarded here. +If a `ServerHttp2Stream` emits an `'error'` event, it will be forwarded here. The stream will already be destroyed when this event is triggered. #### Event: 'stream' From d1db54646da51973795d966b30fce9e793ae2f47 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:56:55 -0800 Subject: [PATCH 10/17] doc: fix spelling of _maximum_ in http2.md "maxmimum" -> "maximum" --- doc/api/http2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 402c423dc33978..e5aeb2d3f7dfbe 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1655,7 +1655,7 @@ changes: * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a - maxmimum allowed number of padding bytes that is determined by current + maximum allowed number of padding bytes that is determined by current flow control state and settings. If this maximum is less than the calculated amount needed to ensure alignment, the maximum will be used and the total frame length will *not* necessarily be aligned at 8 bytes. @@ -1733,7 +1733,7 @@ changes: * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a - maxmimum allowed number of padding bytes that is determined by current + maximum allowed number of padding bytes that is determined by current flow control state and settings. If this maximum is less than the calculated amount needed to ensure alignment, the maximum will be used and the total frame length will *not* necessarily be aligned at 8 bytes. @@ -1820,7 +1820,7 @@ changes: * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply enough padding to ensure that the total frame length, including the 9-byte header, is a multiple of 8. For each frame, however, there is a - maxmimum allowed number of padding bytes that is determined by current + maximum allowed number of padding bytes that is determined by current flow control state and settings. If this maximum is less than the calculated amount needed to ensure alignment, the maximum will be used and the total frame length will *not* necessarily be aligned at 8 bytes. From 7d19ecf0ece0383c64663267f4a01f8fb5d93b70 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 16:59:41 -0800 Subject: [PATCH 11/17] doc: fix verb conjugation in http2.md "applications that supports" -> "applications that support" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index e5aeb2d3f7dfbe..3e705e1bcb4a46 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2162,7 +2162,7 @@ req.end('Jane'); The Compatibility API has the goal of providing a similar developer experience of HTTP/1 when using HTTP/2, making it possible to develop applications -that supports both [HTTP/1][] and HTTP/2. This API targets only the +that support both [HTTP/1][] and HTTP/2. This API targets only the **public API** of the [HTTP/1][], however many modules uses internal methods or state, and those _are not supported_ as it is a completely different implementation. From ce706b4dfb95a4c16b6a9f0676fa9cb7add98869 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:00:56 -0800 Subject: [PATCH 12/17] doc: fix comma splice and verb conjugation in http2.md Fix comma splice. Also "many modules uses" -> "many modules use". --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 3e705e1bcb4a46..adc36a05e49ff3 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2163,7 +2163,7 @@ req.end('Jane'); The Compatibility API has the goal of providing a similar developer experience of HTTP/1 when using HTTP/2, making it possible to develop applications that support both [HTTP/1][] and HTTP/2. This API targets only the -**public API** of the [HTTP/1][], however many modules uses internal +**public API** of the [HTTP/1][]. However many modules use internal methods or state, and those _are not supported_ as it is a completely different implementation. From 27e6793f77d2b1fadac71b786a2c64d9180ef52c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:03:03 -0800 Subject: [PATCH 13/17] doc: fix verb conjugation/sentence structure in http2.md "allows to support" -> "allows supporting" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index adc36a05e49ff3..d693fa439fe57d 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2191,7 +2191,7 @@ the status message for HTTP codes is ignored. ### ALPN negotiation -ALPN negotiation allows to support both [HTTPS][] and HTTP/2 over +ALPN negotiation allows supporting both [HTTPS][] and HTTP/2 over the same socket. The `req` and `res` objects can be either HTTP/1 or HTTP/2, and an application **must** restrict itself to the public API of [HTTP/1][], and detect if it is possible to use the more advanced From 52f64d2d1f2217d6d787f4682bc153c8fbc341a0 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:03:55 -0800 Subject: [PATCH 14/17] doc: use serial comma in http2.md "request status, headers and data" -> "request status, headers, and data" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index d693fa439fe57d..3f29455d4dd982 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2233,7 +2233,7 @@ added: v8.4.0 A `Http2ServerRequest` object is created by [`http2.Server`][] or [`http2.SecureServer`][] and passed as the first argument to the -[`'request'`][] event. It may be used to access a request status, headers and +[`'request'`][] event. It may be used to access a request status, headers, and data. It implements the [Readable Stream][] interface, as well as the From 50b178be4bbfc89ef46b8c7b65b84959544040f5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:05:01 -0800 Subject: [PATCH 15/17] doc: use _hostname_ rather than _host name_ in http2.md --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 3f29455d4dd982..808ff69c17515a 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2294,7 +2294,7 @@ console.log(request.headers); See [Headers Object][]. -*Note*: In HTTP/2, the request path, host name, protocol, and method are +*Note*: In HTTP/2, the request path, hostname, protocol, and method are represented as special headers prefixed with the `:` character (e.g. `':path'`). These special headers will be included in the `request.headers` object. Care must be taken not to inadvertently modify these special headers or errors may From 7366e69941855151a7a93a95115450844af6d33e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:06:00 -0800 Subject: [PATCH 16/17] doc: use "read-only" rather than "read only" in http2.md --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 808ff69c17515a..2a4ea98a982d72 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2327,7 +2327,7 @@ added: v8.4.0 * {string} -The request method as a string. Read only. Example: +The request method as a string. Read-only. Example: `'GET'`, `'DELETE'`. #### request.rawHeaders From b948a2470d4b26f79635224eb9225a04aa6d1403 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 3 Jan 2018 17:08:11 -0800 Subject: [PATCH 17/17] doc: fix spelling of _acknowledgment_ in http2.md "acknowledgement" -> "acknowledgment" --- doc/api/http2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index 2a4ea98a982d72..d9020237870acb 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2985,7 +2985,7 @@ If `name` is equal to `Http2Session`, the `PerformanceEntry` will contain the following additional properties: * `pingRTT` {number} The number of milliseconds elapsed since the transmission - of a `PING` frame and the reception of its acknowledgement. Only present if + of a `PING` frame and the reception of its acknowledgment. Only present if a `PING` frame has been sent on the `Http2Session`. * `streamCount` {number} The number of `Http2Stream` instances processed by the `Http2Session`.