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

doc: improve documentation for raw headers in HTTP/2 APIs · nodejs/node@afaa1cc · GitHub

/ node Public

Commit afaa1cc

Browse files
pimterry
authored and
richardlau
committed
doc: improve documentation for raw headers in HTTP/2 APIs
PR-URL: #59633 Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de> Reviewed-By: Darshan Sen <raisinten@gmail.com>
1 parent 9e2aa23 commit afaa1cc

2 files changed

Lines changed: 46 additions & 20 deletions

File tree

‎doc/api/http2.md‎

Lines changed: 45 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -365,8 +365,7 @@ added: v8.4.0
365365
* `stream` {Http2Stream} A reference to the stream
366366
* `headers` {HTTP/2 Headers Object} An object describing the headers
367367
* `flags` {number} The associated numeric flags
368-
* `rawHeaders` {Array} An array containing the raw header names followed by
369-
their respective values.
368+
* `rawHeaders` {HTTP/2 Raw Headers} An array containing the raw headers
370369

371370
The `'stream'` event is emitted when a new `Http2Stream` is created.
372371

@@ -1082,7 +1081,7 @@ changes:
10821081
description: Allow passing headers in raw array format.
10831082
-->
10841083

1085-
* `headers` {HTTP/2 Headers Object|Array}
1084+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
10861085

10871086
* `options` {Object}
10881087
* `endStream` {boolean} `true` if the `Http2Stream` _writable_ side should
@@ -1683,11 +1682,12 @@ added: v8.4.0
16831682

16841683
* `headers` {HTTP/2 Headers Object}
16851684
* `flags` {number}
1685+
* `rawHeaders` {HTTP/2 Raw Headers}
16861686

16871687
The `'headers'` event is emitted when an additional block of headers is received
16881688
for a stream, such as when a block of `1xx` informational headers is received.
1689-
The listener callback is passed the [HTTP/2 Headers Object][] and flags
1690-
associated with the headers.
1689+
The listener callback is passed the [HTTP/2 Headers Object][], flags associated
1690+
with the headers, and the headers in raw format (see [HTTP/2 Raw Headers][]).
16911691

16921692
```js
16931693
stream.on('headers', (headers, flags) => {
@@ -1722,11 +1722,13 @@ added: v8.4.0
17221722

17231723
* `headers` {HTTP/2 Headers Object}
17241724
* `flags` {number}
1725+
* `rawHeaders` {HTTP/2 Raw Headers}
17251726

17261727
The `'response'` event is emitted when a response `HEADERS` frame has been
17271728
received for this stream from the connected HTTP/2 server. The listener is
1728-
invoked with two arguments: an `Object` containing the received
1729-
[HTTP/2 Headers Object][], and flags associated with the headers.
1729+
invoked with three arguments: an `Object` containing the received
1730+
[HTTP/2 Headers Object][], flags associated with the headers, and the headers
1731+
in raw format (see [HTTP/2 Raw Headers][]).
17301732

17311733
```mjs
17321734
import { connect } from 'node:http2';
@@ -1874,7 +1876,7 @@ changes:
18741876
description: Allow explicitly setting date headers.
18751877
-->
18761878

1877-
* `headers` {HTTP/2 Headers Object|Array}
1879+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
18781880
* `options` {Object}
18791881
* `endStream` {boolean} Set to `true` to indicate that the response will not
18801882
include payload data.
@@ -2358,8 +2360,7 @@ added: v8.4.0
23582360
* `stream` {Http2Stream} A reference to the stream
23592361
* `headers` {HTTP/2 Headers Object} An object describing the headers
23602362
* `flags` {number} The associated numeric flags
2361-
* `rawHeaders` {Array} An array containing the raw header names followed by
2362-
their respective values.
2363+
* `rawHeaders` {HTTP/2 Raw Headers} An array containing the raw headers
23632364

23642365
The `'stream'` event is emitted when a `'stream'` event has been emitted by
23652366
an `Http2Session` associated with the server.
@@ -2612,8 +2613,7 @@ added: v8.4.0
26122613
* `stream` {Http2Stream} A reference to the stream
26132614
* `headers` {HTTP/2 Headers Object} An object describing the headers
26142615
* `flags` {number} The associated numeric flags
2615-
* `rawHeaders` {Array} An array containing the raw header names followed by
2616-
their respective values.
2616+
* `rawHeaders` {HTTP/2 Raw Headers} An array containing the raw headers
26172617

26182618
The `'stream'` event is emitted when a `'stream'` event has been emitted by
26192619
an `Http2Session` associated with the server.
@@ -3455,6 +3455,32 @@ server.on('stream', (stream, headers) => {
34553455
});
34563456
```
34573457

3458+
#### Raw headers
3459+
3460+
In some APIs, in addition to object format, headers can also be passed or
3461+
accessed as a raw flat array, preserving details of ordering and
3462+
duplicate keys to match the raw transmission format.
3463+
3464+
In this format the keys and values are in the same list. It is _not_ a
3465+
list of tuples. So, the even-numbered offsets are key values, and the
3466+
odd-numbered offsets are the associated values. Duplicate headers are
3467+
not merged and so each key-value pair will appear separately.
3468+
3469+
This can be useful for cases such as proxies, where existing headers
3470+
should be exactly forwarded as received, or as a performance
3471+
optimization when the headers are already available in raw format.
3472+
3473+
```js
3474+
const rawHeaders = [
3475+
':status',
3476+
'404',
3477+
'content-type',
3478+
'text/plain',
3479+
];
3480+
3481+
stream.respond(rawHeaders);
3482+
```
3483+
34583484
#### Sensitive headers
34593485

34603486
HTTP2 headers can be marked as sensitive, which means that the HTTP/2
@@ -3481,6 +3507,10 @@ this flag is set automatically.
34813507
This property is also set for received headers. It will contain the names of
34823508
all headers marked as sensitive, including ones marked that way automatically.
34833509

3510+
For raw headers, this should still be set as a property on the array, like
3511+
`rawHeadersArray[http2.sensitiveHeaders] = ['cookie']`, not as a separate key
3512+
and value pair within the array itself.
3513+
34843514
### Settings object
34853515

34863516
<!-- YAML
@@ -4077,16 +4107,10 @@ The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`.
40774107
added: v8.4.0
40784108
-->
40794109

4080-
* Type: {string\[]}
4110+
* Type: {HTTP/2 Raw Headers}
40814111

40824112
The raw request/response headers list exactly as they were received.
40834113

4084-
The keys and values are in the same list. It is _not_ a
4085-
list of tuples. So, the even-numbered offsets are key values, and the
4086-
odd-numbered offsets are the associated values.
4087-
4088-
Header names are not lowercased, and duplicates are not merged.
4089-
40904114
```js
40914115
// Prints something like:
40924116
//
@@ -4767,7 +4791,7 @@ changes:
47674791

47684792
* `statusCode` {number}
47694793
* `statusMessage` {string}
4770-
* `headers` {Object|Array}
4794+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
47714795
* Returns: {http2.Http2ServerResponse}
47724796

47734797
Sends a response header to the request. The status code is a 3-digit HTTP
@@ -4911,6 +4935,7 @@ you need to implement any fall-back behavior yourself.
49114935
[HTTP/1]: http.md
49124936
[HTTP/2]: https://tools.ietf.org/html/rfc7540
49134937
[HTTP/2 Headers Object]: #headers-object
4938+
[HTTP/2 Raw Headers]: #raw-headers
49144939
[HTTP/2 Settings Object]: #settings-object
49154940
[HTTP/2 Unencrypted]: https://http2.github.io/faq/#does-http2-require-encryption
49164941
[HTTPS]: https.md

‎tools/doc/type-parser.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,7 @@ const customTypesMap = {
165165
'ClientHttp2Session': 'http2.html#class-clienthttp2session',
166166
'ClientHttp2Stream': 'http2.html#class-clienthttp2stream',
167167
'HTTP/2 Headers Object': 'http2.html#headers-object',
168+
'HTTP/2 Raw Headers': 'http2.html#raw-headers',
168169
'HTTP/2 Settings Object': 'http2.html#settings-object',
169170
'http2.Http2ServerRequest': 'http2.html#class-http2http2serverrequest',
170171
'http2.Http2ServerResponse':

0 commit comments

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