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

@@ -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

370369371370

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

-->

108910881090-

* `headers` {HTTP/2 Headers Object|Array}

1089+

* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}

1091109010921091

* `options` {Object}

10931092

* `endStream` {boolean} `true` if the `Http2Stream` _writable_ side should

@@ -1675,11 +1674,12 @@ added: v8.4.0

1675167416761675

* `headers` {HTTP/2 Headers Object}

16771676

* `flags` {number}

1677+

* `rawHeaders` {HTTP/2 Raw Headers}

1678167816791679

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][]).

1683168316841684

```js

16851685

stream.on('headers', (headers, flags) => {

@@ -1714,11 +1714,13 @@ added: v8.4.0

1714171417151715

* `headers` {HTTP/2 Headers Object}

17161716

* `flags` {number}

1717+

* `rawHeaders` {HTTP/2 Raw Headers}

1717171817181719

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][]).

1722172417231725

```mjs

17241726

import { connect } from 'node:http2';

@@ -1866,7 +1868,7 @@ changes:

18661868

description: Allow explicitly setting date headers.

18671869

-->

186818701869-

* `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

2355235623562357

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

2611261126122612

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

```

345234523453+

#### 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

3454348034553481

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.

347835043505+

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

3480351034813511

<!-- YAML

@@ -4072,16 +4102,10 @@ The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`.

40724102

added: v8.4.0

40734103

-->

407441044075-

* Type: {string\[]}

4105+

* Type: {HTTP/2 Raw Headers}

4076410640774107

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

407841084079-

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:

4762478647634787

* `statusCode` {number}

47644788

* `statusMessage` {string}

4765-

* `headers` {Object|Array}

4789+

* `headers` {HTTP/2 Headers Object|HTTP/2 Raw Headers}

47664790

* Returns: {http2.Http2ServerResponse}

4767479147684792

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