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@062b2f7 · GitHub

/ node Public

Commit 062b2f7

Browse files
pimterry
authored and
targos
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 d6d05ba commit 062b2f7

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

@@ -1087,7 +1086,7 @@ changes:
10871086
description: Allow passing headers in raw array format.
10881087
-->
10891088

1090-
* `headers` {HTTP/2 Headers Object|Array}
1089+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
10911090

10921091
* `options` {Object}
10931092
* `endStream` {boolean} `true` if the `Http2Stream` _writable_ side should
@@ -1675,11 +1674,12 @@ added: v8.4.0
16751674

16761675
* `headers` {HTTP/2 Headers Object}
16771676
* `flags` {number}
1677+
* `rawHeaders` {HTTP/2 Raw Headers}
16781678

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

16841684
```js
16851685
stream.on('headers', (headers, flags) => {
@@ -1714,11 +1714,13 @@ added: v8.4.0
17141714

17151715
* `headers` {HTTP/2 Headers Object}
17161716
* `flags` {number}
1717+
* `rawHeaders` {HTTP/2 Raw Headers}
17171718

17181719
The `'response'` event is emitted when a response `HEADERS` frame has been
17191720
received for this stream from the connected HTTP/2 server. The listener is
1720-
invoked with two arguments: an `Object` containing the received
1721-
[HTTP/2 Headers Object][], and flags associated with the headers.
1721+
invoked with three arguments: an `Object` containing the received
1722+
[HTTP/2 Headers Object][], flags associated with the headers, and the headers
1723+
in raw format (see [HTTP/2 Raw Headers][]).
17221724

17231725
```mjs
17241726
import { connect } from 'node:http2';
@@ -1866,7 +1868,7 @@ changes:
18661868
description: Allow explicitly setting date headers.
18671869
-->
18681870

1869-
* `headers` {HTTP/2 Headers Object|Array}
1871+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
18701872
* `options` {Object}
18711873
* `endStream` {boolean} Set to `true` to indicate that the response will not
18721874
include payload data.
@@ -2350,8 +2352,7 @@ added: v8.4.0
23502352
* `stream` {Http2Stream} A reference to the stream
23512353
* `headers` {HTTP/2 Headers Object} An object describing the headers
23522354
* `flags` {number} The associated numeric flags
2353-
* `rawHeaders` {Array} An array containing the raw header names followed by
2354-
their respective values.
2355+
* `rawHeaders` {HTTP/2 Raw Headers} An array containing the raw headers
23552356

23562357
The `'stream'` event is emitted when a `'stream'` event has been emitted by
23572358
an `Http2Session` associated with the server.
@@ -2606,8 +2607,7 @@ added: v8.4.0
26062607
* `stream` {Http2Stream} A reference to the stream
26072608
* `headers` {HTTP/2 Headers Object} An object describing the headers
26082609
* `flags` {number} The associated numeric flags
2609-
* `rawHeaders` {Array} An array containing the raw header names followed by
2610-
their respective values.
2610+
* `rawHeaders` {HTTP/2 Raw Headers} An array containing the raw headers
26112611

26122612
The `'stream'` event is emitted when a `'stream'` event has been emitted by
26132613
an `Http2Session` associated with the server.
@@ -3450,6 +3450,32 @@ server.on('stream', (stream, headers) => {
34503450
});
34513451
```
34523452

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

34553481
HTTP2 headers can be marked as sensitive, which means that the HTTP/2
@@ -3476,6 +3502,10 @@ this flag is set automatically.
34763502
This property is also set for received headers. It will contain the names of
34773503
all headers marked as sensitive, including ones marked that way automatically.
34783504

3505+
For raw headers, this should still be set as a property on the array, like
3506+
`rawHeadersArray[http2.sensitiveHeaders] = ['cookie']`, not as a separate key
3507+
and value pair within the array itself.
3508+
34793509
### Settings object
34803510

34813511
<!-- YAML
@@ -4072,16 +4102,10 @@ The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`.
40724102
added: v8.4.0
40734103
-->
40744104

4075-
* Type: {string\[]}
4105+
* Type: {HTTP/2 Raw Headers}
40764106

40774107
The raw request/response headers list exactly as they were received.
40784108

4079-
The keys and values are in the same list. It is _not_ a
4080-
list of tuples. So, the even-numbered offsets are key values, and the
4081-
odd-numbered offsets are the associated values.
4082-
4083-
Header names are not lowercased, and duplicates are not merged.
4084-
40854109
```js
40864110
// Prints something like:
40874111
//
@@ -4762,7 +4786,7 @@ changes:
47624786

47634787
* `statusCode` {number}
47644788
* `statusMessage` {string}
4765-
* `headers` {Object|Array}
4789+
* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}
47664790
* Returns: {http2.Http2ServerResponse}
47674791

47684792
Sends a response header to the request. The status code is a 3-digit HTTP
@@ -4906,6 +4930,7 @@ you need to implement any fall-back behavior yourself.
49064930
[HTTP/1]: http.md
49074931
[HTTP/2]: https://tools.ietf.org/html/rfc7540
49084932
[HTTP/2 Headers Object]: #headers-object
4933+
[HTTP/2 Raw Headers]: #raw-headers
49094934
[HTTP/2 Settings Object]: #settings-object
49104935
[HTTP/2 Unencrypted]: https://http2.github.io/faq/#does-http2-require-encryption
49114936
[HTTPS]: https.md

‎tools/doc/type-parser.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ const customTypesMap = {
172172
'ClientHttp2Session': 'http2.html#class-clienthttp2session',
173173
'ClientHttp2Stream': 'http2.html#class-clienthttp2stream',
174174
'HTTP/2 Headers Object': 'http2.html#headers-object',
175+
'HTTP/2 Raw Headers': 'http2.html#raw-headers',
175176
'HTTP/2 Settings Object': 'http2.html#settings-object',
176177
'http2.Http2ServerRequest': 'http2.html#class-http2http2serverrequest',
177178
'http2.Http2ServerResponse':

0 commit comments

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