Axle v0.22.0
Package

std/net/http

std/net/http — an HTTP/1.1 client, in Axle.

Entry: an [HttpClient], a URL, and the verb as the method you call.
Exit: an [HttpResponse], or an IOException that says what went wrong.

No Rust HTTP library underneath: what goes on the wire is what these
modules wrote. The work is split across seven of them, and this one is
the surface:

• [std::net::httpcall] — one request, built and sent, and the redirect policy
• [std::net::httpreq] — the head rendered, the response handed back
• [std::net::httpxchg] — one exchange over one connection
• [std::net::httphead] — reading and looking up a head
• [std::net::httpbody] — the three body framings
• [std::net::httpline] — one CRLF-terminated line, and where it left the stream
• [std::net::httpbytes] — the byte primitives and every named bound

Two ways in, and the short one is for a request that configures nothing:

HttpClient::get(url).body()

HttpClient::request(url)
.header("Accept", "application/json")
.query("page", "2")
.postJson(body)

What it does: GET / POST / PUT / DELETE / PATCH / HEAD /
OPTIONS, request and response headers, bodies framed by
Content-Length, by Transfer-Encoding: chunked, or by end of
stream, and bounded redirects.

https:// goes over std::net::tls, which owns its own connection —
the switch lives in the Wire the parser reads through, so the framing
code above is the same on both transports.

What it does not: HTTP/2, and connection reuse. A request opens a
connection and closes it, which is why every request carries
Connection: close.

Free functions

TypeMethod and description
string
blockingGet(url : string) : string The blocking half the two …Async statics hand to a task.

A free function and not a closure: spawn takes a call, and the work has
to be nameable for the task to carry it. The exchange itself is the same
one the synchronous path runs — one connection, opened and closed here.
string
blockingPost(url : string, body : string) : string The blocking half of [HttpClient::postAsync].
string
blockingGetWith(url : string, opts : RequestOptions) : string The blocking half of the record-taking getAsync.

Goes through the request rather than straight to runExchange, because
that is where applying lives — one place decides what a record does, and
the async path gets the same answer as the synchronous one instead of a
second reading of the same two fields.
string
blockingPostWith(url : string, body : string, opts : RequestOptions) : string The blocking half of the record-taking postAsync.

Method detail

#blockingGet

blockingGet(url : string) : string ! IOException

The blocking half the two …Async statics hand to a task.

A free function and not a closure: spawn takes a call, and the work has
to be nameable for the task to carry it. The exchange itself is the same
one the synchronous path runs — one connection, opened and closed here.

#blockingPost

blockingPost(url : string, body : string) : string ! IOException

The blocking half of [HttpClient::postAsync].

#blockingGetWith

blockingGetWith(url : string, opts : RequestOptions) : string ! IOException

The blocking half of the record-taking getAsync.

Goes through the request rather than straight to runExchange, because
that is where applying lives — one place decides what a record does, and
the async path gets the same answer as the synchronous one instead of a
second reading of the same two fields.

#blockingPostWith

blockingPostWith(url : string, body : string, opts : RequestOptions) : string ! IOException

The blocking half of the record-taking postAsync.

C class HttpClient

A blocking HTTP/1.1 client. Stateless: it holds no connection pool,
so an instance is free to create and safe to share.

Constructors

TypeMethod and description
constructor()

Method detail

#constructor

constructor()

Methods

TypeMethod and description
HttpClient
timeoutMillis(mut self, millis : i32) : HttpClient Bound every request from this client. 0 means the OS default.

Answers the client, so configuration chains and a caller writes one
expression rather than three statements over a binding that exists
only to be configured. The receiver is a reference, so what comes
back is this client and not a copy of it — the shape
StringBuilder::append already uses.
HttpClient
header(mut self, name : string, value : string) : HttpClient Set a header every request from this client carries, replacing any
it already set under that name.

Replacing rather than appending: a block is lines, so a second
Accept is a second line, and a server reading the first sees a
value the caller thought they had overwritten.

A \r, \n or NUL in either half is refused here, at the point
the caller supplies it, and not later while the head is rendered. An
appended value carrying \r\n is indistinguishable from a field the
caller meant to add: the block is lines, and the injected bytes are
lines. This is the last moment the difference still exists, and what
it prevents is a caller's data becoming the request's framing,
spelling whatever further fields, and whatever second request, the
bytes happen to spell.

Answers the client, so configuration chains — see timeoutMillis.
HttpRequest
request(mut self, url : string) : HttpRequest A request to url, carrying what this client configures.

The entry point of the chain: a request is named before it is
configured, and the verb closes it.

HttpClient::request(url)
.header("Accept", "application/json")
.query("page", "2")
.timeoutMillis(5000)
.postJson(body)

What is set on the request belongs to that request; what is set on
the client is what several requests share. The one-call verbs below
are the short form for a request that configures nothing.
HttpResponse
get(mut self, url : string) : HttpResponse GET url.
HttpResponse
get(mut self, url : string, opts : RequestOptions) : HttpResponse GET url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.
HttpResponse
head(mut self, url : string) : HttpResponse HEAD url — the head a GET would answer, with no body.
HttpResponse
head(mut self, url : string, opts : RequestOptions) : HttpResponse HEAD url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.
HttpResponse
post(mut self, url : string, body : string) : HttpResponse POST url with body.
HttpResponse
post( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse POST url with body, under opts — see [get].
HttpResponse
put(mut self, url : string, body : string) : HttpResponse PUT url with body.
HttpResponse
put( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse PUT url with body, under opts — see [get].
HttpResponse
patch(mut self, url : string, body : string) : HttpResponse PATCH url with body.
HttpResponse
patch( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse PATCH url with body, under opts — see [get].
HttpResponse
delete(mut self, url : string) : HttpResponse DELETE url.
HttpResponse
delete(mut self, url : string, opts : RequestOptions) : HttpResponse DELETE url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.
HttpResponse
options(mut self, url : string) : HttpResponse OPTIONS url — what the origin says it accepts.
HttpResponse
options(mut self, url : string, opts : RequestOptions) : HttpResponse OPTIONS url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.
Future<string>
getAsync(url : string) : Future<string> GET url run as a task, answering a Future<string> you await.

Static, and that is load-bearing: an instance form would make the
call site synthesise a receiver the shim has no slot for.
async_http_static_dispatch.axle locks the dispatch. The task
carries the body as text rather than the response, because the
response owns a buffer and crossing a thread with it needs an
ownership answer this shortcut does not have.
Future<string>
getAsync(url : string, opts : RequestOptions) : Future<string> GET url run as a task, under what opts sets for this call.

The record reaches the async path too, so a caller does not lose the
ability to bound a request by choosing the asynchronous form — which is
the request most worth bounding.
Future<string>
postAsync(url : string, body : string) : Future<string> POST url with body, run as a task.
Future<string>
postAsync( url : string, body : string, opts : RequestOptions ) : Future<string> POST url with body, run as a task, under opts — see
[getAsync].

Method detail

#timeoutMillis

timeoutMillis(mut self, millis : i32) : HttpClient

Bound every request from this client. 0 means the OS default.

Answers the client, so configuration chains and a caller writes one
expression rather than three statements over a binding that exists
only to be configured. The receiver is a reference, so what comes
back is this client and not a copy of it — the shape
StringBuilder::append already uses.

#header

header(mut self, name : string, value : string) : HttpClient ! IllegalArgumentException

Set a header every request from this client carries, replacing any
it already set under that name.

Replacing rather than appending: a block is lines, so a second
Accept is a second line, and a server reading the first sees a
value the caller thought they had overwritten.

A \r, \n or NUL in either half is refused here, at the point
the caller supplies it, and not later while the head is rendered. An
appended value carrying \r\n is indistinguishable from a field the
caller meant to add: the block is lines, and the injected bytes are
lines. This is the last moment the difference still exists, and what
it prevents is a caller's data becoming the request's framing,
spelling whatever further fields, and whatever second request, the
bytes happen to spell.

Answers the client, so configuration chains — see timeoutMillis.

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

#request

request(mut self, url : string) : HttpRequest

A request to url, carrying what this client configures.

The entry point of the chain: a request is named before it is
configured, and the verb closes it.

HttpClient::request(url)
.header("Accept", "application/json")
.query("page", "2")
.timeoutMillis(5000)
.postJson(body)

What is set on the request belongs to that request; what is set on
the client is what several requests share. The one-call verbs below
are the short form for a request that configures nothing.

#get

get(mut self, url : string) : HttpResponse ! IOException

GET url.

#get

get(mut self, url : string, opts : RequestOptions) : HttpResponse ! IOException

GET url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.

#head

head(mut self, url : string) : HttpResponse ! IOException

HEAD url — the head a GET would answer, with no body.

#head

head(mut self, url : string, opts : RequestOptions) : HttpResponse ! IOException

HEAD url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.

#post

post(mut self, url : string, body : string) : HttpResponse ! IOException

POST url with body.

#post

post( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse ! IOException

POST url with body, under opts — see [get].

#put

put(mut self, url : string, body : string) : HttpResponse ! IOException

PUT url with body.

#put

put( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse ! IOException

PUT url with body, under opts — see [get].

#patch

patch(mut self, url : string, body : string) : HttpResponse ! IOException

PATCH url with body.

#patch

patch( mut self, url : string, body : string, opts : RequestOptions ) : HttpResponse ! IOException

PATCH url with body, under opts — see [get].

#delete

delete(mut self, url : string) : HttpResponse ! IOException

DELETE url.

#delete

delete(mut self, url : string, opts : RequestOptions) : HttpResponse ! IOException

DELETE url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.

#options

options(mut self, url : string) : HttpResponse ! IOException

OPTIONS url — what the origin says it accepts.

#options

options(mut self, url : string, opts : RequestOptions) : HttpResponse ! IOException

OPTIONS url, with what opts sets for this call alone — the one-call
form of the chain, for a request whose options are scalars.

#getAsync

getAsync(url : string) : Future<string> ! IOException

GET url run as a task, answering a Future<string> you await.

Static, and that is load-bearing: an instance form would make the
call site synthesise a receiver the shim has no slot for.
async_http_static_dispatch.axle locks the dispatch. The task
carries the body as text rather than the response, because the
response owns a buffer and crossing a thread with it needs an
ownership answer this shortcut does not have.

#getAsync

getAsync(url : string, opts : RequestOptions) : Future<string> ! IOException

GET url run as a task, under what opts sets for this call.

The record reaches the async path too, so a caller does not lose the
ability to bound a request by choosing the asynchronous form — which is
the request most worth bounding.

#postAsync

postAsync(url : string, body : string) : Future<string> ! IOException

POST url with body, run as a task.

#postAsync

postAsync( url : string, body : string, opts : RequestOptions ) : Future<string> ! IOException

POST url with body, run as a task, under opts — see
[getAsync].