nish/net/http1-codec

An incremental HTTP/1.1 request parser and a response writer, sans-IO: bytes in, events and bytes out, and no socket anywhere.

import {
  HTTP1_BODY,
  HTTP1_CHUNKED,
  HTTP1_CLOSED,
  HTTP1_END,
  HTTP1_ERROR,
  HTTP1_FIRST_HEAD,
  HTTP1_FIRST_INPUT,
  HTTP1_HEAD,
  HTTP1_MAX_METHOD,
  HTTP1_NEED_MORE,
  HTTP1_NO_BODY,
  HTTP1_NO_ROOM,
  HTTP1_REFUSED,
  HTTP1_UPGRADE,
  Http1Parser,
  http1BytesAre,
  http1Chunk,
  http1ChunkExtValid,
  http1HexValue,
  http1IsFieldText,
  http1IsOws,
  http1IsToken,
  http1IsTokenByte,
  http1IsValueByte,
  http1LastChunk,
  http1PutText,
  http1ResponseHead,
  http1SameWord,
  http1Text,
  http1WriteChunk,
  http1WriteLastChunk,
  http1WriteResponseHead,
} from "nish/net/http1-codec";
import { Http1Parser, HTTP1_NEED_MORE, HTTP1_HEAD, HTTP1_BODY, HTTP1_END, HTTP1_ERROR } from "nish/net/http1-codec";

const p = new Http1Parser(maxTarget, maxHeaderBytes, maxHeaders, maxBody);
p.feed(received, 0, n);
let event: i32 = p.next();
while (event !== HTTP1_NEED_MORE) {
  // HTTP1_HEAD: p.method, p.target, p.header("host"), ...
  // HTTP1_BODY: p.body[p.bodyOff .. p.bodyOff + p.bodyLen)
  // HTTP1_ERROR: answer p.status and close
  event = p.next();
}

The parser is a push-pull machine. A caller feeds whatever slice the socket gave it, of any length and cut anywhere, and then calls next() until it answers HTTP1_NEED_MORE:

The events are HTTP1_HEAD (the request line and header section are in), HTTP1_BODY (some body bytes, de-chunked), HTTP1_END (the message is complete; with keep-alive the next request follows), HTTP1_UPGRADE (the request asked to switch protocols and has ended: the bytes after it are not HTTP), HTTP1_CLOSED (the request said Connection: close, so nothing after it is read) and HTTP1_ERROR (with the status to answer in status). The last three repeat on every later call. Only complete lines are acted on and body bytes are counted, never guessed, so the sequence of heads, the concatenated body and the final event do not depend on where the input was cut — tests/link/net_http1_split feeds a corpus at every split point.

What it refuses, and with what (RFC 9112 unless named):

  • 400: a malformed request line or field line; a bare LF or a stray CR (§2.2); whitespace before the first field or an obs-fold (§2.2, §5.2); whitespace between a field name and its colon (§5.1); a field value with a control character; a 1.1 request without exactly one Host, or a 1.0 request with more than one (§3.2, RFC 9110 §7.2), or a Host that is not uri-host [":" port] (§3.2, by urlIsHostPort); Content-Length that is not one run of digits, or that appears twice (§6.3); Transfer-Encoding together with Content-Length, in a 1.0 request, or whose last coding is not chunked (§6.1, §6.3); a malformed chunk size, chunk extension or chunk terminator (§7.1). These are the request-smuggling shapes, and each one is refused rather than repaired, because two parsers that repair one differently disagree on where the next request starts.
  • 413: a declared or a de-chunked body longer than maxBody.
  • 414: a request target longer than maxTarget.
  • 431: a header (or trailer) section longer than maxHeaderBytes, or with more than maxHeaders fields.
  • 501: a transfer coding other than chunked (§6.1).
  • 505: an HTTP major version other than 1. A 1.x minor version above 1 is read as 1.1, as RFC 9110 §6.2 asks.

An error is final: the parser answers HTTP1_ERROR from then on and ignores further input, and the caller answers status and closes. Every limit is the caller's number. A method is at most HTTP1_MAX_METHOD bytes.

Connection management

keepAlive is true for a 1.1 request unless Connection lists close, and for a 1.0 request only when it lists keep-alive (§9.3). upgrade is the Upgrade field's value when a 1.1 request also lists upgrade in Connection, and empty otherwise (RFC 9110 §7.8 says a 1.0 request's Upgrade is ignored). After such a request's HTTP1_END the parser stops at HTTP1_UPGRADE; upgradeBytes() answers what was fed past the request, for the next protocol, and declineUpgrade() goes back to HTTP for a server that answered without switching.

The writer

The writer is http1ResponseHead, which answers a status line and header section with the framing field the body needs, and http1Chunk and http1LastChunk for a chunked body. It refuses (null) anything that would let a caller's string end a line early — the response-splitting shape. http1WriteResponseHead writes the same head into a caller's buffer with nothing allocated, and adds a Date field from the bytes it is given (httpDateWrite in nish/net/http-fields makes them) to a final response.

Field names are kept in lowercase, the form RFC 9110 §5.1 says they compare in and the form HTTP/2 sends them in. Strings in the language are bytes, so a field value holding obs-text (0x80 to 0xFF) arrives byte for byte.

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 9112 and RFC 9110, not ported from another implementation.

Functions

http1BytesAre

Whether the octets of bytes spell word, which is lowercase, in any ASCII case: a field name compared as RFC 9110 §5.1 says.

const http1BytesAre: (bytes: u8[], word: string) => boolean
bytesu8[]required

the field name as octets, as nish/net/http-fields holds it

wordstringrequired

the lowercase name to compare with

returnsboolean

true when bytes is word with any letters in either case

http1Chunk

data[off .. off + len) as one chunk of a chunked body, in an array of its own; http1WriteChunk writes the same bytes into a buffer the caller owns. An empty window answers an empty array, because a chunk of size zero is the end of the body and only http1LastChunk writes that. A window outside data panics.

const http1Chunk: (data: u8[], off: i32, len: i32) => u8[]
datau8[]required

the body bytes to send

offi32required

where in data the chunk's bytes start

leni32required

how many bytes of data the chunk carries

returnsu8[]

the chunk's bytes, framing included, in a fresh array the caller owns

http1ChunkExtValid

Whether bytes[from .. to), what follows a chunk size on its line, is the chunk-ext of RFC 9112 §7.1.1 and nothing else: *( BWS ";" BWS chunk-ext-name [ BWS "=" BWS chunk-ext-val ] ), the name a token and the value a token or a quoted-string. An empty window holds no extensions and is valid. The extensions are not interpreted, but they are parsed whole: a parser that skips to the line's end and one that reads a quoted-string across it disagree about where the chunk's data starts (the chunk-extension smuggling of Jetty's CVE-2026-2332 and Netty's CVE-2026-33870), so an unclosed quote, an empty name or value, a stray ; or =, and whitespace that leads nowhere are each refused. The server's parser and the client's both read their chunk-size lines through this.

const http1ChunkExtValid: (
  bytes: u8[],
  from: i32,
  to: i32,
) => boolean
bytesu8[]required

the buffer holding the chunk-size line

fromi32required

the index just past the chunk size's last hex digit

toi32required

the index of the line's CR, exclusive

returnsboolean

true when the window is zero or more well-formed chunk extensions

http1HexValue

The value of the hex digit c, or -1.

const http1HexValue: (c: i32) => i32
ci32required

the byte to read, as a number 0 to 255

returnsi32

0 to 15 for a hex digit in either case, or -1 when c is not one

http1IsFieldText

Whether every byte of text may stand in a field value or a reason phrase.

const http1IsFieldText: (text: string) => boolean
textstringrequired

the candidate value or reason phrase

returnsboolean

true when nothing in text could end the line early; an empty string passes

http1IsOws

Whether c is optional whitespace, a space or a tab (OWS, RFC 9110 §5.6.3).

const http1IsOws: (c: i32) => boolean
ci32required

the byte to test, as a number 0 to 255

returnsboolean

true when c is whitespace a field value is trimmed of

http1IsToken

Whether every byte of text is a tchar, and there is at least one.

const http1IsToken: (text: string) => boolean
textstringrequired

the candidate token, such as a field name a caller wants to send

returnsboolean

true when text is a valid token, false for an empty string

http1IsTokenByte

Whether c is a tchar of RFC 9110 §5.6.2, the bytes a token is made of.

const http1IsTokenByte: (c: i32) => boolean
ci32required

the byte to test, as a number 0 to 255

returnsboolean

true when c may stand in a method, a field name or another token

http1IsValueByte

Whether c may appear in a field value (RFC 9110 §5.5): HTAB, SP, VCHAR or obs-text.

const http1IsValueByte: (c: i32) => boolean
ci32required

the byte to test, as a number 0 to 255

returnsboolean

true when c cannot end the line early or smuggle a control byte into the value

http1LastChunk

The last chunk and the empty trailer section that end a chunked body: 0\r\n\r\n.

const http1LastChunk: () => u8[]
returnsu8[]

those five bytes in a fresh array the caller owns

http1PutText

Writes text at out[at ..), which the caller has made sure holds it, and answers where it ends.

const http1PutText: (
  out: u8[],
  at: i32,
  text: string,
) => i32
outu8[]required

the caller's buffer

ati32required

where in out the text starts

textstringrequired

the text to write, one byte per character

returnsi32

the offset in out just past the text

http1ResponseHead

An HTTP/1.1 status line and header section (RFC 9112 §4, §5), ending in the empty line, with the framing field bodyLength asks for appended: Content-Length: n for n >= 0, Transfer-Encoding: chunked for HTTP1_CHUNKED, and neither for HTTP1_NO_BODY.

Answers null, and writes nothing, for a status outside 100 to 599; a reason phrase or field value holding CR, LF or another control character (which would end the line early and let the rest be read as a field or a second response); a field name that is not a token; names and values of different lengths; a Content-Length or Transfer-Encoding among the caller's fields, since the framing is decided here; two Date fields in any case, since Date is a singleton (RFC 9110 §5.3); a 1xx or 204 response with a body length (RFC 9110 §15.2, §15.3.5); and any other bodyLength below zero.

const http1ResponseHead: (
  status: i32,
  reason: string,
  names: string[],
  values: string[],
  bodyLength: i32,
) => u8[] | null
statusi32required

the status code, 100 to 599

reasonstringrequired

the reason phrase after the code, which may be empty

namesstring[]required

the caller's field names, one per field, beside values

valuesstring[]required

the caller's field values, values[i] for names[i]

bodyLengthi32required

the body's length in bytes, or HTTP1_CHUNKED or HTTP1_NO_BODY

returnsu8[] | null

the head's bytes in a fresh array the caller owns, or null when the head is refused

http1SameWord

Whether text[a .. b) is word, which is lowercase, in any ASCII case.

const http1SameWord: (
  text: string,
  a: i32,
  b: i32,
  word: string,
) => boolean
textstringrequired

the string holding the candidate

ai32required

where the candidate starts in text

bi32required

where the candidate ends in text, exclusive

wordstringrequired

the lowercase word to compare with

returnsboolean

true when the slice is word with any letters in either case

http1Text

buf[from .. to) as a string, each upper-case ASCII letter lowered when lower.

const http1Text: (
  buf: u8[],
  from: i32,
  to: i32,
  lower: boolean,
) => string
bufu8[]required

the bytes to read from

fromi32required

where the text starts in buf

toi32required

where the text ends in buf, exclusive

lowerbooleanrequired

true to lowercase ASCII letters, as a field name wants

returnsstring

a fresh string of those bytes, one character per byte

http1WriteChunk

Writes data[off .. off + len) as one chunk of a chunked body (RFC 9112 §7.1) into out at at — the size in lowercase hex, CRLF, the bytes, CRLF — and answers where it ends, or HTTP1_NO_ROOM when it does not fit, with out untouched. An empty window writes nothing and answers at, because a chunk of size zero ends the body. A window outside data panics.

const http1WriteChunk: (
  out: u8[],
  at: i32,
  data: readonly u8[],
  off: i32,
  len: i32,
) => i32
outu8[]required

the caller's buffer the chunk is written into

ati32required

where in out the chunk starts

datareadonly u8[]required

the body bytes to send

offi32required

where in data the chunk's bytes start

leni32required

how many bytes of data the chunk carries

returnsi32

the offset in out just past the chunk, or HTTP1_NO_ROOM when it does not fit

http1WriteLastChunk

Writes http1LastChunk's five bytes into out at at and answers where they end, or HTTP1_NO_ROOM with out untouched.

const http1WriteLastChunk: (out: u8[], at: i32) => i32
outu8[]required

the caller's buffer the last chunk is written into

ati32required

where in out the last chunk starts

returnsi32

the offset in out just past the five bytes, or HTTP1_NO_ROOM when they do not fit

http1WriteResponseHead

http1ResponseHead's status line and header section, written into out at at with nothing allocated: field names and values are octets (as nish/net/http-fields holds them), and connection, when not empty, is sent as a Connection field after the caller's. date, when not empty, is sent as a Date field between the caller's fields and the framing ones (RFC 9110 §6.6.1), on a final status only, and not when the caller's fields already hold a date in any case: the caller's wins, so a response carries one.

Answers where the head ends; HTTP1_REFUSED for everything http1ResponseHead refuses, a Connection among the caller's fields when connection is given, a connection that is not field text, two date fields among the caller's (a singleton, RFC 9110 §5.3), and a date that is not field text on a final status, the only one it is sent on; HTTP1_NO_ROOM when it is well formed but does not fit, the Date line counted when it is sent. Either way out is untouched.

const http1WriteResponseHead: (
  out: u8[],
  at: i32,
  status: i32,
  reason: string,
  names: u8[][],
  values: u8[][],
  bodyLength: i32,
  connection: string,
  date: u8[],
) => i32
outu8[]required

the caller's buffer the head is written into

ati32required

where in out the head starts

statusi32required

the status code, 100 to 599

reasonstringrequired

the reason phrase after the code, which may be empty

namesu8[][]required

the caller's field names as octets, beside values

valuesu8[][]required

the caller's field values as octets, values[i] for names[i]

bodyLengthi32required

the body's length in bytes, or HTTP1_CHUNKED or HTTP1_NO_BODY

connectionstringrequired

the Connection field's value to send, such as "close", or empty for none

dateu8[]required

the IMF-fixdate bytes to send as Date, or empty for none

returnsi32

the offset in out just past the head, HTTP1_REFUSED for a head it will not write, or HTTP1_NO_ROOM

Classes

Http1Parser

One connection's request parser, from the first byte to the close: requests on a kept-alive connection follow one another through the same parser.

class Http1Parser
Member
new Http1Parser(maxTarget: i32, maxHeaderBytes: i32, maxHeaders: i32, maxBody: i32) Each limit is clamped into 0 to 2^30, so that the sums the parser makes of them (a request line is the method, the target and ten bytes more) cannot overflow an i32.
body: u8[] The buffer the last HTTP1_BODY's bytes are in, at bodyOff, bodyLen long.
bodyLen: i32 How many bytes the last HTTP1_BODY handed over, from body[bodyOff]; 0 before the first.
bodyOff: i32 Where the bytes the last HTTP1_BODY handed over start in body.
chunked: boolean Whether the request's body is chunked (Transfer-Encoding: chunked), so it has no contentLength.
contentLength: i32 The declared body length, or -1 when the request has none or is chunked.
head: u8[] The request line (method to version, no CRLF) and then the header section's lines with their CRLFs, the closing CRLF last, copied out of buf as each is read, names in lowercase: what the spans below index. A field's line runs from its name's start to its value's end, any OWS around the value, and a CRLF; nothing else is in the head. The bytes from headLength on are slack: the section scan stores a line's first bytes there before the line is whole. Kept from one request to the next, so a slot that has seen its largest head allocates nothing for the next one.
headerCount: i32 How many fields the request's header section kept: the spans of field i are spans[4 * i ..].
headLength: i32 How much of head the request uses: the request line, each kept field line and its CRLF, and the closing CRLF, so headerCount + 1 CRLFs.
keepAlive: boolean Whether the connection stays open after this request: HTTP/1.1 unless it sent Connection: close, HTTP/1.0 only when it sent keep-alive. A server closes after its response when this is false.
keepText: boolean Whether method, target, names, values and upgrade are filled as strings. A server that must allocate nothing per request turns it off and reads the head through head, the spans and the ...Is methods.
maxChunk: i32 The most body bytes one HTTP1_BODY hands over; a caller's number, 2^30 unless set.
method: string The request's method as text when keepText is on, else empty.
methodEnd: i32 Where the method ends in head, one past its last byte.
methodStart: i32 The method is head[methodStart .. methodEnd) and the target head[targetStart .. targetEnd).
minor: i32 The minor version: 0 for HTTP/1.0, 1 for HTTP/1.1 and anything above it.
names: string[] The field names, in lowercase, in the order they arrived; values beside them.
reason: string What was wrong, once next() said HTTP1_ERROR; for a log, not for the response.
spans: i32[] Four entries per field, into head: name start and end, value start and end (OWS trimmed).
status: i32 The status code to answer once next() said HTTP1_ERROR.
target: string The request target (path and query) as text when keepText is on, else empty.
targetEnd: i32 Where the request target ends in head, one past its last byte.
targetStart: i32 Where the request target starts in head.
upgrade: string The Upgrade field when Connection asked for it, else empty.
upgrading: boolean Whether the request asked to switch protocols (upgrade is its value when keepText).
values: string[] The field values, in the order they arrived, each at its name's index in names; filled only when keepText.
buffered(): i32 How many bytes were fed and not consumed yet: what a caller bounds its reads by.
declineUpgrade(): void After HTTP1_UPGRADE: the server answered without switching, so the bytes that follow are the next HTTP request. Anywhere else it does nothing.
feed(data: u8[], off: i32, len: i32): void Appends data[off .. off + len) to the input. A window outside data panics, as the crypto modules' update does. Once the parser has closed or refused, the input is dropped; once it has upgraded, it is kept for upgradeBytes().
header(name: string): string | null The value of the first field named name (any case), or null. A field that may repeat is read through the spans. The answer is a fresh string; headerIndex and headerIs allocate nothing.
headerIndex(name: string): i32 The index of the first field named name (any case), or -1.
headerIs(name: string, value: string): boolean Whether the first field named name (any case) has exactly the value value.
methodIs(text: string): boolean Whether the method is exactly text (methods are case-sensitive, RFC 9110 §9.1).
next(): i32 The next event the input holds; see the module comment.
restart(): void Puts the parser back as the constructor left it, for the next connection, keeping every buffer it has grown: a slot that is reused allocates nothing to start over.
resting(): boolean Whether the parser waits for a request line with nothing fed and unread, so its input and head buffers hold nothing it needs: a caller may lend them out and leave empty arrays in buf, body and head, which the next feed and head make or the caller puts back first.
targetIs(text: string): boolean Whether the request target is exactly text.
upgradeBytes(): u8[] After HTTP1_UPGRADE: every byte fed past the request, as a fresh array.
upgradeIs(protocol: string): boolean Whether the request asked to switch to exactly protocol (any case): one Upgrade field holding that one token, with upgrade in Connection.

Limits

32

HTTP1_MAX_METHOD: i32

The longest method this parser reads; a longer one is a 400.

Constants

2

HTTP1_BODY: i32

next(): bodyLen body bytes are at body[bodyOff ..], valid until the next feed.

-1

HTTP1_CHUNKED: i32

http1ResponseHead's bodyLength for a chunked body.

5

HTTP1_CLOSED: i32

next(), from now on: the request closed the connection; nothing more is read.

3

HTTP1_END: i32

next(): the request's body is complete. Its head (method, target, version, fields, keepAlive) still reads as this request's until the next call to next(), so a response written at HTTP1_END sees the request it answers and never the pipelined one behind it.

6

HTTP1_ERROR: i32

next(), from now on: the input is refused; status and reason say why.

256

HTTP1_FIRST_HEAD: i32

The head buffer a parser makes for its first head.

1,024

HTTP1_FIRST_INPUT: i32

The input buffer a parser makes on its first feed, the smallest it grows from.

1

HTTP1_HEAD: i32

next(): a request line and header section were read.

0

HTTP1_NEED_MORE: i32

next(): the input so far holds no further event; feed more.

-2

HTTP1_NO_BODY: i32

http1ResponseHead's bodyLength for a response that carries no body field (1xx, 204, 304, HEAD).

-1

HTTP1_NO_ROOM: i32

http1WriteResponseHead and http1WriteChunk: the bytes do not fit at at.

-2

HTTP1_REFUSED: i32

http1WriteResponseHead: a head the writer refuses to write.

4

HTTP1_UPGRADE: i32

next(), from now on: the request switched protocols; see upgradeBytes().