FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

http2: fix documentation errors · nodejs/node@b43caf9 · GitHub

/ node Public

Commit b43caf9

Browse files
jasnell
authored and
addaleax
committed
http2: fix documentation errors
Backport-PR-URL: #14813 Backport-Reviewed-By: Anna Henningsen <anna@addaleax.net> Backport-Reviewed-By: Timothy Gu <timothygu99@gmail.com> PR-URL: #14239 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
1 parent 33b03b2 commit b43caf9

1 file changed

Lines changed: 42 additions & 36 deletions

File tree

‎doc/api/http2.md‎

Lines changed: 42 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1803,10 +1803,10 @@ req.end('Jane');
18031803

18041804
## Compatibility API
18051805

1806-
The Compatibility API has the goal of providing a similar developer experience of
1807-
HTTP/1 when using HTTP/2, making it possible to develop applications
1808-
that supports both [HTTP/1](HTTP/1) and HTTP/2. This API targets only the **public
1809-
API** of the [HTTP/1](HTTP/1), however many modules uses internal
1806+
The Compatibility API has the goal of providing a similar developer experience
1807+
of HTTP/1 when using HTTP/2, making it possible to develop applications
1808+
that supports both [HTTP/1](HTTP/1) and HTTP/2. This API targets only the
1809+
**public API** of the [HTTP/1](HTTP/1), however many modules uses internal
18101810
methods or state, and those _are not supported_ as it is a completely
18111811
different implementation.
18121812

@@ -1823,7 +1823,7 @@ const server = http2.createServer((req, res) => {
18231823
});
18241824
```
18251825

1826-
In order to create a mixed [HTTPs](https) and HTTP/2 server, refer to the
1826+
In order to create a mixed [HTTPS](https) and HTTP/2 server, refer to the
18271827
[ALPN negotiation](alpn-negotiation) section.
18281828
Upgrading from non-tls HTTP/1 servers is not supported.
18291829

@@ -1834,8 +1834,8 @@ the status message for HTTP codes is ignored.
18341834

18351835
### ALPN negotiation
18361836

1837-
ALPN negotiation allows to support both [HTTPs](https) and HTTP/2 over
1838-
the same socket. the `req` and `res` object could be either HTTP/1 or
1837+
ALPN negotiation allows to support both [HTTPS](https) and HTTP/2 over
1838+
the same socket. The `req` and `res` objects can be either HTTP/1 or
18391839
HTTP/2, and an application **must** restrict itself to the public API of
18401840
[HTTP/1](), and detect if it is possible to use the more advanced
18411841
features of HTTP/2.
@@ -1855,7 +1855,7 @@ const server = createSecureServer(
18551855
).listen(4443);
18561856

18571857
function onRequest(req, res) {
1858-
// detects if it is a HTTPs request or HTTP/2
1858+
// detects if it is a HTTPS request or HTTP/2
18591859
const { socket: { alpnProtocol } } = request.httpVersion === '2.0' ?
18601860
request.stream.session : request;
18611861
response.writeHead(200, { 'content-type': 'application/json' });
@@ -1866,7 +1866,7 @@ function onRequest(req, res) {
18661866
}
18671867
```
18681868

1869-
The `'request'` event works identically on both [HTTPs](https) and
1869+
The `'request'` event works identically on both [HTTPS](https) and
18701870
HTTP/2.
18711871

18721872
### Class: http2.Http2ServerRequest
@@ -1875,8 +1875,9 @@ added: REPLACEME
18751875
-->
18761876

18771877
A `Http2ServerRequest` object is created by [`http2.Server`][] or
1878-
[`http2.SecureServer`][] and passed as the first argument to the [`'request'`][] event. It may be used to access a request status,
1879-
headers and data.
1878+
[`http2.SecureServer`][] and passed as the first argument to the
1879+
[`'request'`][] event. It may be used to access a request status, headers and
1880+
data.
18801881

18811882
It implements the [Readable Stream][] interface, as well as the
18821883
following additional events, methods, and properties.
@@ -1907,9 +1908,9 @@ added: REPLACEME
19071908

19081909
* `error` {Error}
19091910

1910-
Calls `destroy()` on the [Http2Stream]() that received the `ServerRequest`. If `error`
1911-
is provided, an `'error'` event is emitted and `error` is passed as an argument
1912-
to any listeners on the event.
1911+
Calls `destroy()` on the [Http2Stream]() that received the `ServerRequest`. If
1912+
`error` is provided, an `'error'` event is emitted and `error` is passed as an
1913+
argument to any listeners on the event.
19131914

19141915
It does nothing if the stream was already destroyed.
19151916

@@ -2201,7 +2202,7 @@ added: REPLACEME
22012202
* `name` {string}
22022203
* Returns: {string}
22032204

2204-
Reads out a header that's already been queued but not sent to the client.
2205+
Reads out a header that has already been queued but not sent to the client.
22052206
Note that the name is case insensitive.
22062207

22072208
Example:
@@ -2291,7 +2292,7 @@ added: REPLACEME
22912292

22922293
* `name` {string}
22932294

2294-
Removes a header that's queued for implicit sending.
2295+
Removes a header that has been queued for implicit sending.
22952296

22962297
Example:
22972298

@@ -2339,9 +2340,9 @@ response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']);
23392340
Attempting to set a header field name or value that contains invalid characters
23402341
will result in a [`TypeError`][] being thrown.
23412342

2342-
When headers have been set with [`response.setHeader()`][], they will be merged with
2343-
any headers passed to [`response.writeHead()`][], with the headers passed to
2344-
[`response.writeHead()`][] given precedence.
2343+
When headers have been set with [`response.setHeader()`][], they will be merged
2344+
with any headers passed to [`response.writeHead()`][], with the headers passed
2345+
to [`response.writeHead()`][] given precedence.
23452346

23462347
```js
23472348
// returns content-type = text/plain
@@ -2366,9 +2367,9 @@ provided, then it is added as a listener on the `'timeout'` event on
23662367
the response object.
23672368

23682369
If no `'timeout'` listener is added to the request, the response, or
2369-
the server, then [`Http2Stream`]()s are destroyed when they time out. If a handler is
2370-
assigned to the request, the response, or the server's `'timeout'` events,
2371-
timed out sockets must be handled explicitly.
2370+
the server, then [`Http2Stream`]()s are destroyed when they time out. If a
2371+
handler is assigned to the request, the response, or the server's `'timeout'`
2372+
events, timed out sockets must be handled explicitly.
23722373

23732374
Returns `response`.
23742375

@@ -2478,7 +2479,8 @@ buffer. Returns `false` if all or part of the data was queued in user memory.
24782479
added: REPLACEME
24792480
-->
24802481

2481-
Throws an error as the `'continue'` flow is not current implemented. Added for parity with [HTTP/1]().
2482+
Throws an error as the `'continue'` flow is not current implemented. Added for
2483+
parity with [HTTP/1]().
24822484

24832485
### response.writeHead(statusCode[, statusMessage][, headers])
24842486
<!-- YAML
@@ -2491,7 +2493,11 @@ added: REPLACEME
24912493

24922494
Sends a response header to the request. The status code is a 3-digit HTTP
24932495
status code, like `404`. The last argument, `headers`, are the response headers.
2494-
For compatibility with [HTTP/1](), one can give a human-readable `statusMessage` as the second argument, which will be silenty ignored and emit a warning.
2496+
2497+
For compatibility with [HTTP/1](), a human-readable `statusMessage` may be
2498+
passed as the second argument. However, because the `statusMessage` has no
2499+
meaning within HTTP/2, the argument will have no effect and a process warning
2500+
will be emitted.
24952501

24962502
Example:
24972503

@@ -2502,15 +2508,22 @@ response.writeHead(200, {
25022508
'Content-Type': 'text/plain' });
25032509
```
25042510

2505-
This method must only be called once on a message and it must
2506-
be called before [`response.end()`][] is called.
2511+
Note that Content-Length is given in bytes not characters. The
2512+
`Buffer.byteLength()` API may be used to determine the number of bytes in a
2513+
given encoding. On outbound messages, Node.js does not check if Content-Length
2514+
and the length of the body being transmitted are equal or not. However, when
2515+
receiving messages, Node.js will automatically reject messages when the
2516+
Content-Length does not match the actual payload size.
2517+
2518+
This method may be called at most one time on a message before
2519+
[`response.end()`][] is called.
25072520

25082521
If [`response.write()`][] or [`response.end()`][] are called before calling
25092522
this, the implicit/mutable headers will be calculated and call this function.
25102523

2511-
When headers have been set with [`response.setHeader()`][], they will be merged with
2512-
any headers passed to [`response.writeHead()`][], with the headers passed to
2513-
[`response.writeHead()`][] given precedence.
2524+
When headers have been set with [`response.setHeader()`][], they will be merged
2525+
with any headers passed to [`response.writeHead()`][], with the headers passed
2526+
to [`response.writeHead()`][] given precedence.
25142527

25152528
```js
25162529
// returns content-type = text/plain
@@ -2522,13 +2535,6 @@ const server = http2.createServer((req, res) => {
25222535
});
25232536
```
25242537

2525-
Note that Content-Length is given in bytes not characters. The above example
2526-
works because the string `'hello world'` contains only single byte characters.
2527-
If the body contains higher coded characters then `Buffer.byteLength()`
2528-
should be used to determine the number of bytes in a given encoding.
2529-
And Node.js does not check whether Content-Length and the length of the body
2530-
which has been transmitted are equal or not.
2531-
25322538
Attempting to set a header field name or value that contains invalid characters
25332539
will result in a [`TypeError`][] being thrown.
25342540

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL