Axle v0.22.0
Package

std/net/httpbody

std/net/httpbody — the three framings a message body can arrive under,
and the bytes each one leaves behind.

Entry: a Wire positioned at the first body byte the head's read did
not already pull in, plus that leftover.
Exit: an [HttpBody] holding the octets and whatever was read past
them, or an IOException naming the bound that was exceeded.

A body is arbitrary octets and never becomes a string here — that
conversion is the caller's choice, at the point where it knows the media
type. Every count a peer sends is checked against a named bound in
[std::net::httpbytes] before it is believed.

Free functions

TypeMethod and description
HttpBody
readSizedBody(inp : Wire, spill : i8[], have : i64, length : i64) : HttpBody Read a body framed by Content-Length.

spill may run past the declared length — the read that found the head
does not stop at a message boundary — and the excess is the next message,
handed back on the result rather than dropped.
HttpBody
readEofBody(inp : Wire, spill : i8[], have : i64) : HttpBody Read a body that runs to end of stream — the framing a
Connection: close response with no Content-Length uses.

Nothing can follow such a body, so its spill is empty by construction
rather than by omission.
LineRead
drainTrailer(inp : Wire, spill : i8[], have : i64) : LineRead Consume the trailer section that may follow the terminating 0 chunk:
field lines up to and including the empty line that ends them.

Leaving it on the stream is invisible to a client that closes after every
exchange and a framing error to anything that does not — connection reuse,
or the server this parser is shared with, would begin the next message in
the middle of a trailer field.

Tolerant of a close, not of an unbounded peer. A server that writes the
terminating chunk and hangs up has delivered a complete body, and refusing
that would fail a conforming exchange; a peer that writes trailer fields
without end is refused by the same maxHeaderCount that bounds a head.
HttpBody
readChunkedBody(inp : Wire, spill : i8[], have : i64) : HttpBody Read a body framed by Transfer-Encoding: chunked.

Every chunk size is validated before it is believed: a size that is not
hexadecimal, or that exceeds maxChunkBytes, ends the read with an
IOException rather than an allocation. The running total is checked
against maxBodyBytes too, so a peer cannot stay under the per-chunk
bound and exhaust memory a chunk at a time.

The terminating 0 chunk is followed by an optional trailer section, and
[drainTrailer] reads it to its end, so the stream is left positioned at
the next message rather than in the middle of one.

rest tracks the reader's position and is seeded with the caller's
spill, which it does not own. The first readLine below always replaces
it with a LineRead's own array before any path returns, so what leaves
on the result is never the caller's allocation under a second owner.

Method detail

#readSizedBody

readSizedBody(inp : Wire, spill : i8[], have : i64, length : i64) : HttpBody ! IOException

Read a body framed by Content-Length.

spill may run past the declared length — the read that found the head
does not stop at a message boundary — and the excess is the next message,
handed back on the result rather than dropped.

Parameters
inp stream positioned at the first body byte not in spill
spill body bytes already read while locating the head
have valid byte count in spill
length declared length; refused above maxBodyBytes
Throws
IOException if the declared length is out of bounds or the
peer closes before delivering it.

#readEofBody

readEofBody(inp : Wire, spill : i8[], have : i64) : HttpBody ! IOException

Read a body that runs to end of stream — the framing a
Connection: close response with no Content-Length uses.

Nothing can follow such a body, so its spill is empty by construction
rather than by omission.

Parameters
inp stream positioned at the first body byte not in spill
spill body bytes already read while locating the head
have valid byte count in spill
Throws
IOException if the body grows past maxBodyBytes.

#drainTrailer

drainTrailer(inp : Wire, spill : i8[], have : i64) : LineRead ! IOException

Consume the trailer section that may follow the terminating 0 chunk:
field lines up to and including the empty line that ends them.

Leaving it on the stream is invisible to a client that closes after every
exchange and a framing error to anything that does not — connection reuse,
or the server this parser is shared with, would begin the next message in
the middle of a trailer field.

Tolerant of a close, not of an unbounded peer. A server that writes the
terminating chunk and hangs up has delivered a complete body, and refusing
that would fail a conforming exchange; a peer that writes trailer fields
without end is refused by the same maxHeaderCount that bounds a head.

Parameters
inp stream positioned just past the 0 chunk's line
spill bytes already read past it
have valid byte count in spill
Returns the [LineRead] the drain ended on, whose spill is what
was read past the trailer — the next message's first bytes.
Throws
IOException on a trailer longer than maxHeaderCount field lines.

#readChunkedBody

readChunkedBody(inp : Wire, spill : i8[], have : i64) : HttpBody ! IOException

Read a body framed by Transfer-Encoding: chunked.

Every chunk size is validated before it is believed: a size that is not
hexadecimal, or that exceeds maxChunkBytes, ends the read with an
IOException rather than an allocation. The running total is checked
against maxBodyBytes too, so a peer cannot stay under the per-chunk
bound and exhaust memory a chunk at a time.

The terminating 0 chunk is followed by an optional trailer section, and
[drainTrailer] reads it to its end, so the stream is left positioned at
the next message rather than in the middle of one.

rest tracks the reader's position and is seeded with the caller's
spill, which it does not own. The first readLine below always replaces
it with a LineRead's own array before any path returns, so what leaves
on the result is never the caller's allocation under a second owner.

Parameters
inp stream positioned at the first chunk-size line
spill body bytes already read while locating the head
have valid byte count in spill
Throws
IOException on a malformed size, a bound, or a close inside
a message (before a chunk size, before a chunk's bytes, or
before the CRLF that closes a chunk).

C class HttpBody

A message body: the octets, and how many of them are valid.

Kept as bytes. Which media type they carry is the caller's knowledge,
and a UTF-8 decode applied here would destroy every image, archive and
protobuf that crosses this path.

Constructors

Method detail

#constructor

constructor(data : i8[], len : i64, spill : i8[], spillLen : i64)