Skip to content

Commit d7accdc

Browse files
harjothkharaaduh95
harjothkhara
authored and
aduh95
committed
doc: document http2 header constants
Signed-off-by: harjoth <harjoth.khara@gmail.com> PR-URL: #64548 Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent c57c83b commit d7accdc

1 file changed

Lines changed: 145 additions & 6 deletions

File tree

‎doc/api/http2.md‎

Lines changed: 145 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3354,6 +3354,142 @@ client.close();
33543354
added: v8.4.0
33553355
-->
33563356

3357+
#### Header name constants
3358+
3359+
The `HTTP2_HEADER_*` constants provide names for HTTP/2 pseudo-headers and
3360+
known HTTP header names. Using these string constants is optional. For example,
3361+
`http2.constants.HTTP2_HEADER_CONTENT_TYPE` is equal to `'content-type'`.
3362+
For APIs that accept regular header names,
3363+
`http2.constants.HTTP2_HEADER_CONTENT_TYPE`, `'content-type'`, and
3364+
`'Content-Type'` have the same effect; Node.js serializes the name in
3365+
lower-case.
3366+
3367+
Regular header constants can be used with the compatibility API wherever the
3368+
corresponding literal header name is accepted. In compatibility API request
3369+
handlers, prefer `request.method`, `request.authority`, `request.scheme`, and
3370+
`request.url` for the corresponding pseudo-headers. Other incoming
3371+
pseudo-headers remain available through `request.headers`. Set response status
3372+
through `response.statusCode` or the `statusCode` argument to
3373+
`response.writeHead()`. Passing `HTTP2_HEADER_STATUS` (`':status'`) to
3374+
`response.setHeader()` or in `response.writeHead()`'s headers object throws
3375+
`ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED`. `HTTP2_HEADER_PROTOCOL` is a request
3376+
pseudo-header and cannot be sent in a response.
3377+
3378+
Incoming header object keys are lower-case, so use a constant or a lower-case
3379+
literal when accessing them as object properties. Using a constant does not
3380+
change header validation, and the availability of a constant does not imply
3381+
that the header is valid in every HTTP/2 context. See [HTTP/2 Headers Object][]
3382+
and [Invalid character handling in header names and values][] for details about
3383+
header casing and validation.
3384+
3385+
##### Pseudo-header constants
3386+
3387+
`HTTP2_HEADER_METHOD`, `HTTP2_HEADER_AUTHORITY`, `HTTP2_HEADER_SCHEME`, and
3388+
`HTTP2_HEADER_PATH` identify request pseudo-headers. `HTTP2_HEADER_STATUS`
3389+
identifies the response pseudo-header. `HTTP2_HEADER_PROTOCOL` identifies the
3390+
extended `CONNECT` request pseudo-header. Pseudo-headers are not permitted in
3391+
trailers.
3392+
3393+
| Constant | Value |
3394+
| ---------------------------------------- | -------------- |
3395+
| `http2.constants.HTTP2_HEADER_STATUS` | `':status'` |
3396+
| `http2.constants.HTTP2_HEADER_METHOD` | `':method'` |
3397+
| `http2.constants.HTTP2_HEADER_AUTHORITY` | `':authority'` |
3398+
| `http2.constants.HTTP2_HEADER_SCHEME` | `':scheme'` |
3399+
| `http2.constants.HTTP2_HEADER_PATH` | `':path'` |
3400+
| `http2.constants.HTTP2_HEADER_PROTOCOL` | `':protocol'` |
3401+
3402+
##### Regular header constants
3403+
3404+
The `HTTP2_HEADER_CONNECTION`, `HTTP2_HEADER_UPGRADE`,
3405+
`HTTP2_HEADER_HTTP2_SETTINGS`, `HTTP2_HEADER_KEEP_ALIVE`,
3406+
`HTTP2_HEADER_PROXY_CONNECTION`, and `HTTP2_HEADER_TRANSFER_ENCODING`
3407+
constants identify connection-specific headers that HTTP/2 does not permit.
3408+
`HTTP2_HEADER_TE` is permitted only when its value is `'trailers'`.
3409+
3410+
| Constant | Value |
3411+
| --------------------------------------------------------------- | ------------------------------------ |
3412+
| `http2.constants.HTTP2_HEADER_ACCEPT_ENCODING` | `'accept-encoding'` |
3413+
| `http2.constants.HTTP2_HEADER_ACCEPT_LANGUAGE` | `'accept-language'` |
3414+
| `http2.constants.HTTP2_HEADER_ACCEPT_RANGES` | `'accept-ranges'` |
3415+
| `http2.constants.HTTP2_HEADER_ACCEPT` | `'accept'` |
3416+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_ALLOW_CREDENTIALS` | `'access-control-allow-credentials'` |
3417+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_ALLOW_HEADERS` | `'access-control-allow-headers'` |
3418+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_ALLOW_METHODS` | `'access-control-allow-methods'` |
3419+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN` | `'access-control-allow-origin'` |
3420+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_EXPOSE_HEADERS` | `'access-control-expose-headers'` |
3421+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_REQUEST_HEADERS` | `'access-control-request-headers'` |
3422+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_REQUEST_METHOD` | `'access-control-request-method'` |
3423+
| `http2.constants.HTTP2_HEADER_AGE` | `'age'` |
3424+
| `http2.constants.HTTP2_HEADER_AUTHORIZATION` | `'authorization'` |
3425+
| `http2.constants.HTTP2_HEADER_CACHE_CONTROL` | `'cache-control'` |
3426+
| `http2.constants.HTTP2_HEADER_CONNECTION` | `'connection'` |
3427+
| `http2.constants.HTTP2_HEADER_CONTENT_DISPOSITION` | `'content-disposition'` |
3428+
| `http2.constants.HTTP2_HEADER_CONTENT_ENCODING` | `'content-encoding'` |
3429+
| `http2.constants.HTTP2_HEADER_CONTENT_LENGTH` | `'content-length'` |
3430+
| `http2.constants.HTTP2_HEADER_CONTENT_TYPE` | `'content-type'` |
3431+
| `http2.constants.HTTP2_HEADER_COOKIE` | `'cookie'` |
3432+
| `http2.constants.HTTP2_HEADER_DATE` | `'date'` |
3433+
| `http2.constants.HTTP2_HEADER_ETAG` | `'etag'` |
3434+
| `http2.constants.HTTP2_HEADER_FORWARDED` | `'forwarded'` |
3435+
| `http2.constants.HTTP2_HEADER_HOST` | `'host'` |
3436+
| `http2.constants.HTTP2_HEADER_IF_MODIFIED_SINCE` | `'if-modified-since'` |
3437+
| `http2.constants.HTTP2_HEADER_IF_NONE_MATCH` | `'if-none-match'` |
3438+
| `http2.constants.HTTP2_HEADER_IF_RANGE` | `'if-range'` |
3439+
| `http2.constants.HTTP2_HEADER_LAST_MODIFIED` | `'last-modified'` |
3440+
| `http2.constants.HTTP2_HEADER_LINK` | `'link'` |
3441+
| `http2.constants.HTTP2_HEADER_LOCATION` | `'location'` |
3442+
| `http2.constants.HTTP2_HEADER_RANGE` | `'range'` |
3443+
| `http2.constants.HTTP2_HEADER_REFERER` | `'referer'` |
3444+
| `http2.constants.HTTP2_HEADER_SERVER` | `'server'` |
3445+
| `http2.constants.HTTP2_HEADER_SET_COOKIE` | `'set-cookie'` |
3446+
| `http2.constants.HTTP2_HEADER_STRICT_TRANSPORT_SECURITY` | `'strict-transport-security'` |
3447+
| `http2.constants.HTTP2_HEADER_TRANSFER_ENCODING` | `'transfer-encoding'` |
3448+
| `http2.constants.HTTP2_HEADER_TE` | `'te'` |
3449+
| `http2.constants.HTTP2_HEADER_UPGRADE_INSECURE_REQUESTS` | `'upgrade-insecure-requests'` |
3450+
| `http2.constants.HTTP2_HEADER_UPGRADE` | `'upgrade'` |
3451+
| `http2.constants.HTTP2_HEADER_USER_AGENT` | `'user-agent'` |
3452+
| `http2.constants.HTTP2_HEADER_VARY` | `'vary'` |
3453+
| `http2.constants.HTTP2_HEADER_X_CONTENT_TYPE_OPTIONS` | `'x-content-type-options'` |
3454+
| `http2.constants.HTTP2_HEADER_X_FRAME_OPTIONS` | `'x-frame-options'` |
3455+
| `http2.constants.HTTP2_HEADER_KEEP_ALIVE` | `'keep-alive'` |
3456+
| `http2.constants.HTTP2_HEADER_PROXY_CONNECTION` | `'proxy-connection'` |
3457+
| `http2.constants.HTTP2_HEADER_X_XSS_PROTECTION` | `'x-xss-protection'` |
3458+
| `http2.constants.HTTP2_HEADER_ALT_SVC` | `'alt-svc'` |
3459+
| `http2.constants.HTTP2_HEADER_CONTENT_SECURITY_POLICY` | `'content-security-policy'` |
3460+
| `http2.constants.HTTP2_HEADER_EARLY_DATA` | `'early-data'` |
3461+
| `http2.constants.HTTP2_HEADER_EXPECT_CT` | `'expect-ct'` |
3462+
| `http2.constants.HTTP2_HEADER_ORIGIN` | `'origin'` |
3463+
| `http2.constants.HTTP2_HEADER_PURPOSE` | `'purpose'` |
3464+
| `http2.constants.HTTP2_HEADER_TIMING_ALLOW_ORIGIN` | `'timing-allow-origin'` |
3465+
| `http2.constants.HTTP2_HEADER_X_FORWARDED_FOR` | `'x-forwarded-for'` |
3466+
| `http2.constants.HTTP2_HEADER_PRIORITY` | `'priority'` |
3467+
| `http2.constants.HTTP2_HEADER_ACCEPT_CHARSET` | `'accept-charset'` |
3468+
| `http2.constants.HTTP2_HEADER_ACCESS_CONTROL_MAX_AGE` | `'access-control-max-age'` |
3469+
| `http2.constants.HTTP2_HEADER_ALLOW` | `'allow'` |
3470+
| `http2.constants.HTTP2_HEADER_CONTENT_LANGUAGE` | `'content-language'` |
3471+
| `http2.constants.HTTP2_HEADER_CONTENT_LOCATION` | `'content-location'` |
3472+
| `http2.constants.HTTP2_HEADER_CONTENT_MD5` | `'content-md5'` |
3473+
| `http2.constants.HTTP2_HEADER_CONTENT_RANGE` | `'content-range'` |
3474+
| `http2.constants.HTTP2_HEADER_DNT` | `'dnt'` |
3475+
| `http2.constants.HTTP2_HEADER_EXPECT` | `'expect'` |
3476+
| `http2.constants.HTTP2_HEADER_EXPIRES` | `'expires'` |
3477+
| `http2.constants.HTTP2_HEADER_FROM` | `'from'` |
3478+
| `http2.constants.HTTP2_HEADER_IF_MATCH` | `'if-match'` |
3479+
| `http2.constants.HTTP2_HEADER_IF_UNMODIFIED_SINCE` | `'if-unmodified-since'` |
3480+
| `http2.constants.HTTP2_HEADER_MAX_FORWARDS` | `'max-forwards'` |
3481+
| `http2.constants.HTTP2_HEADER_PREFER` | `'prefer'` |
3482+
| `http2.constants.HTTP2_HEADER_PROXY_AUTHENTICATE` | `'proxy-authenticate'` |
3483+
| `http2.constants.HTTP2_HEADER_PROXY_AUTHORIZATION` | `'proxy-authorization'` |
3484+
| `http2.constants.HTTP2_HEADER_REFRESH` | `'refresh'` |
3485+
| `http2.constants.HTTP2_HEADER_RETRY_AFTER` | `'retry-after'` |
3486+
| `http2.constants.HTTP2_HEADER_TRAILER` | `'trailer'` |
3487+
| `http2.constants.HTTP2_HEADER_TK` | `'tk'` |
3488+
| `http2.constants.HTTP2_HEADER_VIA` | `'via'` |
3489+
| `http2.constants.HTTP2_HEADER_WARNING` | `'warning'` |
3490+
| `http2.constants.HTTP2_HEADER_WWW_AUTHENTICATE` | `'www-authenticate'` |
3491+
| `http2.constants.HTTP2_HEADER_HTTP2_SETTINGS` | `'http2-settings'` |
3492+
33573493
#### Error codes for `RST_STREAM` and `GOAWAY`
33583494

33593495
| Value | Name | Constant |
@@ -3920,19 +4056,21 @@ API:
39204056
```mjs
39214057
import { createServer } from 'node:http2';
39224058
const server = createServer((req, res) => {
3923-
res.setHeader('Content-Type', 'text/html');
3924-
res.setHeader('X-Foo', 'bar');
3925-
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
4059+
res.writeHead(200, {
4060+
'Content-Type': 'text/plain; charset=utf-8',
4061+
'X-Foo': 'bar',
4062+
});
39264063
res.end('ok');
39274064
});
39284065
```
39294066

39304067
```cjs
39314068
const http2 = require('node:http2');
39324069
const server = http2.createServer((req, res) => {
3933-
res.setHeader('Content-Type', 'text/html');
3934-
res.setHeader('X-Foo', 'bar');
3935-
res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
4070+
res.writeHead(200, {
4071+
'Content-Type': 'text/plain; charset=utf-8',
4072+
'X-Foo': 'bar',
4073+
});
39364074
res.end('ok');
39374075
});
39384076
```
@@ -5023,6 +5161,7 @@ you need to implement any fall-back behavior yourself.
50235161
[HTTP/2 Settings Object]: #settings-object
50245162
[HTTP/2 Unencrypted]: https://http2.github.io/faq/#does-http2-require-encryption
50255163
[HTTPS]: https.md
5164+
[Invalid character handling in header names and values]: #invalid-character-handling-in-header-names-and-values
50265165
[Performance Observer]: perf_hooks.md
50275166
[RFC 7838]: https://tools.ietf.org/html/rfc7838
50285167
[RFC 8336]: https://tools.ietf.org/html/rfc8336

0 commit comments

Comments
 (0)