nish/net/http-fields

The header model HTTP/2 and HTTP/3 share: what a field name and a field value may hold, the pseudo-header fields and the order and count they come in, the connection-specific fields neither version carries, and the shapes of a request, a response and a trailer section.

import {
  HTTP_DATE_LAST_SECOND,
  HTTP_DATE_SIZE,
  HTTP_FIELDS_AUTHORITY_MISMATCH,
  HTTP_FIELDS_BAD_CONTENT_LENGTH,
  HTTP_FIELDS_BAD_NAME,
  HTTP_FIELDS_BAD_PSEUDO_VALUE,
  HTTP_FIELDS_BAD_VALUE,
  HTTP_FIELDS_CONNECTION_SPECIFIC,
  HTTP_FIELDS_DATE_REPEATED,
  HTTP_FIELDS_NO_LENGTH,
  HTTP_FIELDS_OK,
  HTTP_FIELDS_PSEUDO_AFTER_FIELD,
  HTTP_FIELDS_PSEUDO_FORBIDDEN,
  HTTP_FIELDS_PSEUDO_MISSING,
  HTTP_FIELDS_PSEUDO_REPEATED,
  HTTP_FIELDS_PSEUDO_UNKNOWN,
  HttpFields,
  httpDateWrite,
  httpFieldBytes,
  httpFieldConnectionSpecific,
  httpFieldIs,
  httpFieldNameValid,
  httpFieldSensitive,
  httpFieldValueValid,
  httpFieldsCheckOutgoing,
} from "nish/net/http-fields";
import { HttpFields, HTTP_FIELDS_OK } from "nish/net/http-fields";

const request = new HttpFields();
if (request.readRequest(decoder.names, decoder.values, extendedConnect) === HTTP_FIELDS_OK) {
  // request.method, request.path, request.get("content-type"), ...
}

It is version-neutral on purpose: RFC 9113 §8 and RFC 9114 §4 state the same rules for a field section, and each version answers a section that breaks one in its own words — HTTP/2 with a stream error of type PROTOCOL_ERROR (RFC 9113 §8.1.1), HTTP/3 with H3_MESSAGE_ERROR (RFC 9114 §4.1.2). So every check here answers one of the HTTP_FIELDS_* codes and nothing more, and nothing here knows about frames, streams or a codec.

What it refuses (RFC 9110 §5, RFC 9113 §8.2 and §8.3, RFC 9114 §4.2 and §4.3, RFC 8441 §4):

  • a field name that is empty, holds a character outside RFC 9110's tchar, or holds an uppercase letter — both versions send names in lowercase and call an uppercase one malformed (HTTP_FIELDS_BAD_NAME);
  • a field value with a NUL, CR or LF anywhere, or a space or tab at either end (HTTP_FIELDS_BAD_VALUE) — the first three are what lets a value end a line once the message is turned back into HTTP/1.1;
  • connection, proxy-connection, keep-alive, transfer-encoding, upgrade, and te with any value but trailers (HTTP_FIELDS_CONNECTION_SPECIFIC);
  • a pseudo-header that is not one of the five a request has or the one a response has (HTTP_FIELDS_PSEUDO_UNKNOWN), one that appears twice (_PSEUDO_REPEATED), one after a regular field (_PSEUDO_AFTER_FIELD), one the shape does not allow — :status in a request, :path in a plain CONNECT, any in a trailer section, :protocol where extended CONNECT was not enabled or with a method but CONNECT (_PSEUDO_FORBIDDEN) — and a required one that is absent (_PSEUDO_MISSING);
  • a pseudo-header value of the wrong shape: a :method or :protocol that is not a token, a :scheme that is not RFC 3986's, an empty :path or one that starts with neither / nor is OPTIONS's *, an :authority with userinfo, a :status that is not three digits from 100 to 599 (HTTP_FIELDS_BAD_PSEUDO_VALUE);
  • a host field that names another authority than :authority, letters compared without case (HTTP_FIELDS_AUTHORITY_MISMATCH);
  • a content-length that is not one run of at most eighteen digits, or two that disagree (HTTP_FIELDS_BAD_CONTENT_LENGTH). Matching it against the body is the version's job, since only it sees the body;
  • in a section a program sends, a second date field: Date is a singleton (RFC 9110 §5.3, §6.6.1) whose value holds a comma, so two cannot be combined into one and a reader cannot tell which to believe (HTTP_FIELDS_DATE_REPEATED).
The date

httpDateWrite writes a second since 1970 as an IMF-fixdate (RFC 9110 §5.6.7), Fri, 16 Oct 2026 08:11:54 GMT, the form every version's Date field takes. It reads no clock, so a wasm32 build can import it; the caller supplies the second.

Names and values are octets (u8[]), as HPACK and QPACK answer them. A section that passes keeps references to the caller's arrays, not copies, so it is valid for as long as they are.

Private helpers share the importing program's flat symbol namespace (docs/wp26-stdlib.md §3e), which is why each one carries the module's name.

Written from RFC 9110, RFC 9113, RFC 9114 and RFC 8441, not ported from another implementation.

Functions

httpDateWrite

Writes the IMF-fixdate of seconds since 1970-01-01T00:00:00Z at out[at .. at + HTTP_DATE_SIZE) and answers where it ends; -1, with nothing written, for a second before 1970 or after HTTP_DATE_LAST_SECOND, whose year has no four digits, or for an out without the room. It reads no clock, so it compiles for wasm32 too: HttpDate in nish/net/http1-server is the cache that reads one and calls this at most once a second.

The date follows Howard Hinnant's civil_from_days ("chrono-Compatible Low-Level Date Algorithms"), step for step and with its constants, which its author donated to the public domain: days are counted from 0000-03-01, so a leap day is the last day of its year and a 400-year era is always 146,097 days long. Every step is i64 arithmetic on numbers that are not negative, so --number-mode f64 writes the same bytes.

const httpDateWrite: (
  out: u8[],
  at: i32,
  seconds: i64,
) => i32
outu8[]required

the buffer to write into; its length is not changed

ati32required

the index in out where the date's first letter goes

secondsi64required

the instant to name, in whole seconds since 1970 UTC

returnsi32

the index just past the date's last octet (at + HTTP_DATE_SIZE), or -1 when nothing was written

httpFieldBytes

The octets of text, one a character: what a field name or value is sent as.

const httpFieldBytes: (text: string) => u8[]
textstringrequired

the name or value to turn into octets; each character's code is kept in one octet, so it should be Latin-1

returnsu8[]

a fresh array the caller owns, one octet per character of text

httpFieldConnectionSpecific

Whether a field named name with value is connection-specific, which HTTP/2 and HTTP/3 refuse in a message (RFC 9113 §8.2.2, RFC 9114 §4.2): the fields RFC 9110 §7.6.1 names, keep-alive, proxy-connection, transfer-encoding and upgrade, and te with any value but trailers.

const httpFieldConnectionSpecific: (
  name: u8[],
  value: u8[],
) => boolean
nameu8[]required

the field name's octets, in lowercase

valueu8[]required

the field's value, which matters only for te

returnsboolean

true when the field belongs to one HTTP/1.1 hop and must not be sent or accepted in an HTTP/2 or HTTP/3 message

httpFieldIs

Whether the octets of bytes spell text exactly.

const httpFieldIs: (bytes: u8[], text: string) => boolean
bytesu8[]required

the octets to compare, such as a decoded field name

textstringrequired

the expected spelling, one character an octet; case matters

returnsboolean

true only when both have the same length and every octet matches

httpFieldNameValid

Whether name may be sent as a regular field name in HTTP/2 or HTTP/3: a non-empty token in lowercase (RFC 9110 §5.1, RFC 9113 §8.2.1, RFC 9114 §4.2). A pseudo-header's name starts with a colon and is not one.

const httpFieldNameValid: (name: u8[]) => boolean
nameu8[]required

the field name's octets, as the program would send them

returnsboolean

true when the name may go on the wire as it is; false for an empty name, a non-token character or an uppercase letter

httpFieldSensitive

Whether a field named name carries a credential an encoder should never put in a compression table, here or at any intermediary: authorization, proxy-authorization, cookie and set-cookie (RFC 7541 §7.1.3, RFC 9204 §7.1.3). A table entry can be probed by a peer that controls part of what is compressed beside it, so a secret sent indexed can leak through the compressed length (CRIME's shape).

const httpFieldSensitive: (name: u8[]) => boolean
nameu8[]required

the field name's octets, in lowercase

returnsboolean

true when the encoder should send this field never-indexed

httpFieldValueValid

Whether value may be sent as a field value: no NUL, CR or LF, and no space or tab as its first or last octet (RFC 9113 §8.2.1, RFC 9114 §4.2). Other octets, obs-text included, pass as they are.

const httpFieldValueValid: (value: u8[]) => boolean
valueu8[]required

the field value's octets, as the program would send them

returnsboolean

true when the value cannot end a line or smuggle whitespace at its edges, so it may be sent as it is

httpFieldsCheckOutgoing

Checks a field section a program is about to send, pseudo-headers left out: every name valid and in lowercase, every value valid, nothing connection-specific, at most one date (a singleton, RFC 9110 §5.3), and as many values as names. Answers HTTP_FIELDS_OK or the first refusal. A version's writer refuses what this refuses, so that a program's string can never reach the wire as a field it was not.

const httpFieldsCheckOutgoing: (
  names: u8[][],
  values: u8[][],
) => i32
namesu8[][]required

the regular field names about to be sent, in order

valuesu8[][]required

the value for each name, at the same index

returnsi32

HTTP_FIELDS_OK when the whole section may be sent, or the HTTP_FIELDS_* code of the first field that may not (HTTP_FIELDS_BAD_VALUE too when the two lists differ in length)

Classes

HttpFields

One field section read into its shape: the pseudo-headers by name, and the regular fields in order. readRequest, readResponse and readTrailers each clear it and fill it from a decoded section, and answer HTTP_FIELDS_OK or the first refusal; after a refusal what it holds is partial and not to be used. Every read empties and refills the same two lists rather than making new ones, so a caller that keeps a section past the next read copies it.

class HttpFields
Member
new HttpFields() Makes an empty section, ready for its first read; no field is set yet.
authority: u8[] :authority, empty when absent.
contentLength: i64 The content-length, or HTTP_FIELDS_NO_LENGTH.
method: u8[] :method, empty in a response or a trailer section.
names: u8[][] The regular fields' names, in order.
path: u8[] :path, empty when absent.
protocol: u8[] :protocol of an extended CONNECT (RFC 8441), empty when absent.
scheme: u8[] :scheme, empty when absent.
status: i32 :status of a response, or 0.
values: u8[][] The regular fields' values, beside their names.
clear(): void Empties every field, so the next read starts from nothing.
get(name: string): u8[] | null The value of the first regular field named name (lowercase), or null.
isConnect(): boolean Whether the method is CONNECT, plain (RFC 9113 §8.5) or extended (RFC 8441).
readRequest(names: u8[][], values: u8[][], extendedConnect: boolean): i32 Reads a request's field section (RFC 9113 §8.3.1, RFC 9114 §4.3.1). Every request has :method. A CONNECT without :protocol has :authority and neither :scheme nor :path (RFC 9113 §8.5). An extended CONNECT — :protocol present, which only extendedConnect allows, the version having sent SETTINGS_ENABLE_CONNECT_PROTOCOL — has all four of the others (RFC 8441 §4). Any other request has :scheme and :path. A :path that does not start with / is OPTIONS's * or refused, and a host field must name :authority when both are there.
readResponse(names: u8[][], values: u8[][]): i32 Reads a response's field section: exactly one :status, and no other pseudo-header (RFC 9113 §8.3.2).
readTrailers(names: u8[][], values: u8[][]): i32 Reads a trailer section: regular fields only (RFC 9113 §8.1).

Constants

253,402,300,799

HTTP_DATE_LAST_SECOND: i64

The last second an IMF-fixdate can name, 9999-12-31T23:59:59Z, in seconds since 1970.

29

HTTP_DATE_SIZE: i32

An IMF-fixdate's length: Sun, 06 Nov 1994 08:49:37 GMT (RFC 9110 §5.6.7).

-10

HTTP_FIELDS_AUTHORITY_MISMATCH: i32

A host field that names another authority than :authority.

-11

HTTP_FIELDS_BAD_CONTENT_LENGTH: i32

A content-length that is not a run of digits, or two that disagree.

-1

HTTP_FIELDS_BAD_NAME: i32

A field name that is empty, not a token, or not in lowercase.

-9

HTTP_FIELDS_BAD_PSEUDO_VALUE: i32

A pseudo-header whose value does not have its field's syntax.

-2

HTTP_FIELDS_BAD_VALUE: i32

A field value with a NUL, CR or LF, or whitespace at either end.

-3

HTTP_FIELDS_CONNECTION_SPECIFIC: i32

A connection-specific field (RFC 9113 §8.2.2, RFC 9114 §4.2).

-12

HTTP_FIELDS_DATE_REPEATED: i32

A date field that a section about to be sent holds more than once (RFC 9110 §5.3).

-1

HTTP_FIELDS_NO_LENGTH: i64

contentLength when the section has no content-length.

0

HTTP_FIELDS_OK: i32

A field section that has the shape asked for.

-6

HTTP_FIELDS_PSEUDO_AFTER_FIELD: i32

A pseudo-header after a regular field.

-8

HTTP_FIELDS_PSEUDO_FORBIDDEN: i32

A pseudo-header the shape does not allow.

-7

HTTP_FIELDS_PSEUDO_MISSING: i32

A pseudo-header the shape requires and the section does not have.

-5

HTTP_FIELDS_PSEUDO_REPEATED: i32

A pseudo-header that appears more than once.

-4

HTTP_FIELDS_PSEUDO_UNKNOWN: i32

A pseudo-header that neither a request nor a response defines.