Axle v0.22.0
Package

std/net/httphead

std/net/httphead — the head of an HTTP/1.1 message: the start line, the
field block, and the lookups over it.

Entry: a Wire, positioned at the first byte of a message, plus
whatever the previous message's reader read past its own end.
Exit: an [HttpHead], or an IOException naming the bound that was
exceeded.

Bytes throughout, never characters — see
[std::net::httpbytes] for why, and for the bounds every read here is
held to.

Free functions

TypeMethod and description
HttpHead
readHead(inp : Wire, spill : i8[], have : i64) : HttpHead Read until the blank line that ends the head, and parse it.

spill is what a previous message's reader read past its own end — the
first bytes of this head, already off the socket and unreadable a
second time. A connection that serves two messages passes the first
body's spill here; a connection opening on this message passes
noSpill() and 0.

The scan runs before the first read for that reason: a peer that sent
two messages in one segment has already delivered this whole head, and a
reader that asked the socket for more first would block on bytes it is
holding.
i64
countHeaders(headers : string) : i64 Number of field lines in a header block.
string
headerBlockWithout(headers : string, name : string) : string The field block with every line named name removed, case-insensitively.

The one way a header is replaced: a block is lines, so setting a field
that is already there means dropping what was there first. Without it a
second Accept is a second line, and a server reading the first sees a
value the caller thought they had overwritten.
bool
headerValuesAgree(headers : string, name : string) : bool Whether every field line named name carries the same trimmed value.

RFC 9110 lets a repeated Content-Length stand when the copies agree;
copies that disagree are a message nobody framed, and a reader that picked
one would end it where the peer's other reader does not. A field that
appears once, or not at all, agrees with itself — so this one answer covers
"absent", "single" and "repeated and consistent", and a caller needs no
count beside it.
i64
fieldLineEnd(headers : string, from : i64) : i64 Where the field line starting at from ends: the index of its \r\n,
or headers.byteLength for a last line that has none.

The one place that says what a line break is in a field block. Every
walk over the block — a lookup, a count, a filter — steps by this and
resumes at end + 2, so a block whose last line carries no terminator
is read the same way by all of them.
i64
fieldNameEnd(headers : string, from : i64, to : i64) : i64 Where the field name of the line [from, to) ends: the index of its
first :, or to for a line that has none — which is how a caller
tells a malformed line from a field with an empty name.
string
headerValue(headers : string, name : string) : string Value of the field named name, or "" when absent.

The match is case-insensitive because RFC 9110 makes field names so,
and a client that compared them exactly would miss content-length
from a conforming server. Leading and trailing whitespace is stripped
from the value; a duplicated field answers with its first occurrence.

Method detail

#readHead

readHead(inp : Wire, spill : i8[], have : i64) : HttpHead ! IOException

Read until the blank line that ends the head, and parse it.

spill is what a previous message's reader read past its own end — the
first bytes of this head, already off the socket and unreadable a
second time. A connection that serves two messages passes the first
body's spill here; a connection opening on this message passes
noSpill() and 0.

The scan runs before the first read for that reason: a peer that sent
two messages in one segment has already delivered this whole head, and a
reader that asked the socket for more first would block on bytes it is
holding.

Parameters
inp connected stream to read from
spill bytes already read past the previous message
have valid byte count in spill
Throws
IOException if the peer closes before the head is complete,
or if the head exceeds maxHeadBytes / maxStartLine /
maxHeaderCount.

#countHeaders

countHeaders(headers : string) : i64

Number of field lines in a header block.

#headerBlockWithout

headerBlockWithout(headers : string, name : string) : string

The field block with every line named name removed, case-insensitively.

The one way a header is replaced: a block is lines, so setting a field
that is already there means dropping what was there first. Without it a
second Accept is a second line, and a server reading the first sees a
value the caller thought they had overwritten.

Parameters
headers the raw field block, Name: Value\r\n repeated
name field name to drop

#headerValuesAgree

headerValuesAgree(headers : string, name : string) : bool

Whether every field line named name carries the same trimmed value.

RFC 9110 lets a repeated Content-Length stand when the copies agree;
copies that disagree are a message nobody framed, and a reader that picked
one would end it where the peer's other reader does not. A field that
appears once, or not at all, agrees with itself — so this one answer covers
"absent", "single" and "repeated and consistent", and a caller needs no
count beside it.

Parameters
headers the raw field block, Name: Value\r\n repeated
name field name to look up

#fieldLineEnd

fieldLineEnd(headers : string, from : i64) : i64

Where the field line starting at from ends: the index of its \r\n,
or headers.byteLength for a last line that has none.

The one place that says what a line break is in a field block. Every
walk over the block — a lookup, a count, a filter — steps by this and
resumes at end + 2, so a block whose last line carries no terminator
is read the same way by all of them.

Parameters
headers the raw field block, Name: Value\r\n repeated
from index of the line's first byte

#fieldNameEnd

fieldNameEnd(headers : string, from : i64, to : i64) : i64

Where the field name of the line [from, to) ends: the index of its
first :, or to for a line that has none — which is how a caller
tells a malformed line from a field with an empty name.

#headerValue

headerValue(headers : string, name : string) : string

Value of the field named name, or "" when absent.

The match is case-insensitive because RFC 9110 makes field names so,
and a client that compared them exactly would miss content-length
from a conforming server. Leading and trailing whitespace is stripped
from the value; a duplicated field answers with its first occurrence.

Parameters
headers the raw field block, Name: Value\r\n repeated
name field name to look up

C class HttpHead

A message head: the start line, the field block, and whatever body
bytes arrived in the same reads.

spill carries those leftover body bytes. They are not a detail to
discard: a server sends head and body in one segment routinely, so a
reader that dropped what it over-read would block forever waiting for
a body it already holds.

Constructors

Method detail

#constructor

constructor(startLine : string, headers : string, spill : i8[], spillLen : i64)