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();
}
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.
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.
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.
http1HexValue
The value of the hex digit c, or -1.
http1IsFieldText
Whether every byte of text may stand in a field value or a reason phrase.
http1IsOws
Whether c is optional whitespace, a space or a tab (OWS, RFC 9110 §5.6.3).
http1IsToken
Whether every byte of text is a tchar, and there is at least one.
http1IsTokenByte
Whether c is a tchar of RFC 9110 §5.6.2, the bytes a token is made of.
http1IsValueByte
Whether c may appear in a field value (RFC 9110 §5.5): HTAB, SP, VCHAR or obs-text.
http1LastChunk
The last chunk and the empty trailer section that end a chunked body: 0\r\n\r\n.
http1PutText
Writes text at out[at ..), which the caller has made sure holds it, and answers where it ends.
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.
http1SameWord
Whether text[a .. b) is word, which is lowercase, in any ASCII case.
http1Text
buf[from .. to) as a string, each upper-case ASCII letter lowered when lower.
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.
http1WriteLastChunk
Writes http1LastChunk's five bytes into out at at and answers where they end, or HTTP1_NO_ROOM with out untouched.
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.
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.
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 aHostthat is noturi-host [":" port](§3.2, byurlIsHostPort);Content-Lengththat is not one run of digits, or that appears twice (§6.3);Transfer-Encodingtogether withContent-Length, in a 1.0 request, or whose last coding is notchunked(§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 thanmaxHeadersfields. - 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[]requiredthe field name as octets, as nish/net/http-fields holds it
wordstringrequiredthe lowercase name to compare with
returnsbooleantrue 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[]requiredthe body bytes to send
offi32requiredwhere in data the chunk's bytes start
leni32requiredhow 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[]requiredthe buffer holding the chunk-size line
fromi32requiredthe index just past the chunk size's last hex digit
toi32requiredthe index of the line's CR, exclusive
returnsbooleantrue 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
ci32requiredthe byte to read, as a number 0 to 255
returnsi320 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
textstringrequiredthe candidate value or reason phrase
returnsbooleantrue 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
ci32requiredthe byte to test, as a number 0 to 255
returnsbooleantrue 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
textstringrequiredthe candidate token, such as a field name a caller wants to send
returnsbooleantrue 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
ci32requiredthe byte to test, as a number 0 to 255
returnsbooleantrue 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
ci32requiredthe byte to test, as a number 0 to 255
returnsbooleantrue 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[]requiredthe caller's buffer
ati32requiredwhere in out the text starts
textstringrequiredthe text to write, one byte per character
returnsi32the 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
statusi32requiredthe status code, 100 to 599
reasonstringrequiredthe reason phrase after the code, which may be empty
namesstring[]requiredthe caller's field names, one per field, beside values
valuesstring[]requiredthe caller's field values, values[i] for names[i]
bodyLengthi32requiredthe body's length in bytes, or HTTP1_CHUNKED or HTTP1_NO_BODY
returnsu8[] | nullthe 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
textstringrequiredthe string holding the candidate
ai32requiredwhere the candidate starts in text
bi32requiredwhere the candidate ends in text, exclusive
wordstringrequiredthe lowercase word to compare with
returnsbooleantrue 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[]requiredthe bytes to read from
fromi32requiredwhere the text starts in buf
toi32requiredwhere the text ends in buf, exclusive
lowerbooleanrequiredtrue to lowercase ASCII letters, as a field name wants
returnsstringa 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[]requiredthe caller's buffer the chunk is written into
ati32requiredwhere in out the chunk starts
datareadonly u8[]requiredthe body bytes to send
offi32requiredwhere in data the chunk's bytes start
leni32requiredhow many bytes of data the chunk carries
returnsi32the 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[]requiredthe caller's buffer the last chunk is written into
ati32requiredwhere in out the last chunk starts
returnsi32the 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[]requiredthe caller's buffer the head is written into
ati32requiredwhere in out the head starts
statusi32requiredthe status code, 100 to 599
reasonstringrequiredthe reason phrase after the code, which may be empty
namesu8[][]requiredthe caller's field names as octets, beside values
valuesu8[][]requiredthe caller's field values as octets, values[i] for names[i]
bodyLengthi32requiredthe body's length in bytes, or HTTP1_CHUNKED or HTTP1_NO_BODY
connectionstringrequiredthe Connection field's value to send, such as "close", or empty for none
dateu8[]requiredthe IMF-fixdate bytes to send as Date, or empty for none
returnsi32the 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().

