Axle v0.22.0
Package

std/net/httpreq

std/net/httpreq — the request a client builds, the response it hands
back, and the bytes in between.

Entry: a URL and whatever the caller sets on it.
Exit: a head rendered as text, ready for the wire, and an
[HttpResponse] once one has been read.

The two classes sit together because they are two halves of the same
contract: everything a caller writes is validated here, before it can
reach the socket, and everything a caller reads is a copy owned by the
response rather than a view into a parser's buffer.

Free functions

TypeMethod and description
i32
defaultPort(scheme : string) : i32 Default port for a scheme that named none.
string
requestTarget(url : string) : string The request-target of a URL: path plus query, / when the URL named
no path. A request line with an empty target is malformed, and a
server's 400 is a poor way to learn it.
string
hostHeader(url : string) : string The Host value for a URL: authority, with the port appended only
when it is not the scheme's default — which is what RFC 9110 asks
for, and what a virtual-hosted server matches against.
string
renderHeaderLine(name : string, value : string) : string One field line, Name: Value\r\n, refusing what would not be one.

The single place a caller's two halves become a line, so the check that
they can be is here and not at each of the three call sites that set a
header. A CR, an LF or a NUL in either half does not make a malformed
request: it makes a well-formed one the caller did not write, carrying
whatever further fields — and whatever second request — the bytes
happen to spell. This is the last moment the difference still exists.
string
renderHead(method : string, url : string, headers : string, body : string) : string Render the request head.

Host is mandatory in HTTP/1.1. Connection: close is sent because
this client opens one connection per request and a server that kept it
alive would leave the read waiting for a body that never ends.
Accept-Encoding: identity is sent because nothing here decompresses,
and a gzip body would otherwise be handed to the caller as noise.

The URL reaching here has already been through [urlIsFramingSafe] —
std::net::httpxchg's exchange checks it before it opens anything, so
a request that cannot be written costs no connection.
bool
urlIsFramingSafe(url : string) : bool Whether url's request-line halves can be written without changing what
the request is.

A path, a query and an authority are caller data exactly as a header value
is, and a \r\n in one splits the request the same way header refuses
for a field: the bytes after it are read by the server as further fields,
or as a second request the caller never made. A space or a tab is refused
here too, and not for a field: they delimit the request line's three
parts, so one inside a target moves the bytes after it into another part.
header guards the field block, this guards the line above it, and
between the two nothing reaches the wire unread.
i32
parseStatus(statusLine : string) : i32 The status code out of a status line, or -1 when it is malformed.

The HTTP/ prefix is required: without it a body misread as a head, or
the first line of a peer that does not speak HTTP, is accepted as a status
whenever its second word happens to be three digits.

Method detail

#defaultPort

defaultPort(scheme : string) : i32

Default port for a scheme that named none.

#requestTarget

requestTarget(url : string) : string

The request-target of a URL: path plus query, / when the URL named
no path. A request line with an empty target is malformed, and a
server's 400 is a poor way to learn it.

#hostHeader

hostHeader(url : string) : string

The Host value for a URL: authority, with the port appended only
when it is not the scheme's default — which is what RFC 9110 asks
for, and what a virtual-hosted server matches against.

#renderHeaderLine

renderHeaderLine(name : string, value : string) : string ! IllegalArgumentException

One field line, Name: Value\r\n, refusing what would not be one.

The single place a caller's two halves become a line, so the check that
they can be is here and not at each of the three call sites that set a
header. A CR, an LF or a NUL in either half does not make a malformed
request: it makes a well-formed one the caller did not write, carrying
whatever further fields — and whatever second request — the bytes
happen to spell. This is the last moment the difference still exists.

Parameters
name field name
value field value
Throws
IllegalArgumentException if either half carries CR, LF or NUL.

#renderHead

renderHead(method : string, url : string, headers : string, body : string) : string

Render the request head.

Host is mandatory in HTTP/1.1. Connection: close is sent because
this client opens one connection per request and a server that kept it
alive would leave the read waiting for a body that never ends.
Accept-Encoding: identity is sent because nothing here decompresses,
and a gzip body would otherwise be handed to the caller as noise.

The URL reaching here has already been through [urlIsFramingSafe] —
std::net::httpxchg's exchange checks it before it opens anything, so
a request that cannot be written costs no connection.

#urlIsFramingSafe

urlIsFramingSafe(url : string) : bool

Whether url's request-line halves can be written without changing what
the request is.

A path, a query and an authority are caller data exactly as a header value
is, and a \r\n in one splits the request the same way header refuses
for a field: the bytes after it are read by the server as further fields,
or as a second request the caller never made. A space or a tab is refused
here too, and not for a field: they delimit the request line's three
parts, so one inside a target moves the bytes after it into another part.
header guards the field block, this guards the line above it, and
between the two nothing reaches the wire unread.

Parameters
url the absolute URL a request will be sent to

#parseStatus

parseStatus(statusLine : string) : i32

The status code out of a status line, or -1 when it is malformed.

The HTTP/ prefix is required: without it a body misread as a head, or
the first line of a peer that does not speak HTTP, is accepted as a status
whenever its second word happens to be three digits.

C class HttpResponse

A completed HTTP response: status, field block, and body octets.

The body is held as bytes and decoded on demand by [body], so a
response carrying an image or an archive survives — the decode is the
caller's request, made where it knows the media type, rather than
something done to every response on the way in.

Constructors

TypeMethod and description
constructor(status : i32, headerBlock : string, data : i8[], len : i64) Take a copy of data[0..len).

A copy, not the array itself: the buffer arrives owned by the
HttpBody the reader built, and that body dies at the end of the
exchange. Storing the same array in both classes gives two owners
to one allocation — the body's teardown frees it and this field
becomes a dangling pointer, which reads as a segfault the first
time anyone asks for the payload. One copy per response is the
price of each class owning what it holds.

Method detail

#constructor

constructor(status : i32, headerBlock : string, data : i8[], len : i64)

Take a copy of data[0..len).

A copy, not the array itself: the buffer arrives owned by the
HttpBody the reader built, and that body dies at the end of the
exchange. Storing the same array in both classes gives two owners
to one allocation — the body's teardown frees it and this field
becomes a dangling pointer, which reads as a segfault the first
time anyone asks for the payload. One copy per response is the
price of each class owning what it holds.

Methods

TypeMethod and description
string
body(self) : string The body decoded as UTF-8. Lossy for a non-text payload.
i8[]
bytes(self) : i8[] The body as octets — what body would have destroyed on a
payload that is not text. length is the valid count.

A copy, for the reason the constructor above states about the one
it makes: this response owns its buffer and frees it at its own scope
exit, so handing the array itself out would give one allocation two
owners and the caller a dangling pointer the moment the response
dies. One allocation per call is the price of that; a caller writing
a large body to a stream pays it once, at the point it writes.
Json
json(self) : Json The body read as JSON.

Validated here, once, so every accessor on the cursor it answers is
total — see Json. A body that is not JSON is a
failure of the exchange, not of the read that follows it, which is why
this is the call that throws and none of the reads do.
string
header(self, name : string) : string Value of a response header, "" when absent. Case-insensitive.

Method detail

#body

body(self) : string

The body decoded as UTF-8. Lossy for a non-text payload.

#bytes

bytes(self) : i8[]

The body as octets — what body would have destroyed on a
payload that is not text. length is the valid count.

A copy, for the reason the constructor above states about the one
it makes: this response owns its buffer and frees it at its own scope
exit, so handing the array itself out would give one allocation two
owners and the caller a dangling pointer the moment the response
dies. One allocation per call is the price of that; a caller writing
a large body to a stream pays it once, at the point it writes.

#json

json(self) : Json ! ParseException

The body read as JSON.

Validated here, once, so every accessor on the cursor it answers is
total — see Json. A body that is not JSON is a
failure of the exchange, not of the read that follows it, which is why
this is the call that throws and none of the reads do.

Throws
ParseException if the body is not a JSON document.

#header

header(self, name : string) : string

Value of a response header, "" when absent. Case-insensitive.