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 byContent-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 carriesConnection: close.
Free functions
| Type | Method and description |
|---|---|
| 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 hasto 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(url : string, body : string) : string The blocking half of [HttpClient::postAsync]. |
| blockingGetWith(url : string, opts : RequestOptions) : string The blocking half of the record-taking getAsync.Goes through the request rather than straight to runExchange, becausethat is where applying lives — one place decides what a record does, andthe async path gets the same answer as the synchronous one instead of a second reading of the same two fields. |
| blockingPostWith(url : string, body : string, opts : RequestOptions) : string The blocking half of the record-taking postAsync. |
Method detail
#blockingGet
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
The blocking half of [HttpClient::postAsync].
#blockingGetWith
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
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
| Type | Method and description |
|---|---|
| constructor() |
Method detail
#constructor
Methods
| Type | Method and description |
|---|---|
| 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(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 avalue the caller thought they had overwritten. A \r, \n or NUL in either half is refused here, at the pointthe caller supplies it, and not later while the head is rendered. An appended value carrying \r\n is indistinguishable from a field thecaller 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. |
| 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(mut self, url : string) : HttpResponse GET url. |
| get(mut self, url : string, opts : RequestOptions) : HttpResponse GET url, with what opts sets for this call alone — the one-callform of the chain, for a request whose options are scalars. |
| head(mut self, url : string) : HttpResponse HEAD url — the head a GET would answer, with no body. |
| head(mut self, url : string, opts : RequestOptions) : HttpResponse HEAD url, with what opts sets for this call alone — the one-callform of the chain, for a request whose options are scalars. |
| post(mut self, url : string, body : string) : HttpResponse POST url with body. |
| post(
mut self,
url : string,
body : string,
opts : RequestOptions
) : HttpResponse POST url with body, under opts — see [get]. |
| put(mut self, url : string, body : string) : HttpResponse PUT url with body. |
| put(
mut self,
url : string,
body : string,
opts : RequestOptions
) : HttpResponse PUT url with body, under opts — see [get]. |
| patch(mut self, url : string, body : string) : HttpResponse PATCH url with body. |
| patch(
mut self,
url : string,
body : string,
opts : RequestOptions
) : HttpResponse PATCH url with body, under opts — see [get]. |
| delete(mut self, url : string) : HttpResponse DELETE url. |
| delete(mut self, url : string, opts : RequestOptions) : HttpResponse DELETE url, with what opts sets for this call alone — the one-callform of the chain, for a request whose options are scalars. |
| options(mut self, url : string) : HttpResponse OPTIONS url — what the origin says it accepts. |
| options(mut self, url : string, opts : RequestOptions) : HttpResponse OPTIONS url, with what opts sets for this call alone — the one-callform of the chain, for a request whose options are scalars. |
| 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 taskcarries 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(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. |
| postAsync(url : string, body : string) : Future<string> POST url with body, run as a task. |
| postAsync(
url : string,
body : string,
opts : RequestOptions
) : Future<string> POST url with body, run as a task, under opts — see[ getAsync]. |
Method detail
#timeoutMillis
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 shapeStringBuilder::append already uses.
#header
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 secondAccept 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.
name field namevalue field valueIllegalArgumentException if either half carries CR, LF or NUL.#request
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 url.
#get
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 url — the head a GET would answer, with no body.
#head
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 url with body.
#post
POST url with body, under opts — see [get].
#put
PUT url with body.
#put
PUT url with body, under opts — see [get].
#patch
PATCH url with body.
#patch
PATCH url with body, under opts — see [get].
#delete
DELETE url.
#delete
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 url — what the origin says it accepts.
#options
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
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
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
POST url with body, run as a task.
#postAsync
POST url with body, run as a task, under opts — see
[getAsync].