std/net/httpcall
std/net/httpcall — one request, built and sent.
Entry: [HttpRequest], which a client answers for a URL. Exit: an
[HttpResponse], or an IOException naming what went wrong.
The shape is the whole point. A request is named before it is
configured and the verb closes it, so a call reads in the order it
happens:HttpClient::request(url) .header("Accept", "application/json") .query("page", "2") .timeoutMillis(5000) .postJson(body)
What that buys over setting the same things on the client: they belong
to this request. A header set here does not outlive the call, a
deadline here is not the client's, and a query parameter is encoded
rather than concatenated by the caller. What the client still carries is
what several requests share.
The redirect policy lives here too, because it is a property of the
exchange rather than of the caller: [runExchange] follows up tomaxRedirects hops, drops the body on a 301/302 that was not a GET, and
drops the caller's credentials the moment a hop changes origin.
Free functions
| Type | Method and description |
|---|---|
| maxRedirects() : i32 Redirects followed before giving up. RFC 9110 suggests a small bound. |
| jsonMediaType() : string The media type a postJson and its siblings declare. |
| runExchange(
verb : string,
target : string,
payload : string,
headerBlock : string,
timeoutMillis : i32
) : HttpResponse One exchange, following up to [maxRedirects] redirections.A 301, 302 or 303 answering anything but HEAD is re-issued as a GET with the body dropped: mandatory for a 303, and for the other two what RFC 9110 codifies from what deployed clients already did. A 307 or 308 keeps both. |
| resolveLocation(base : string, location : string) : string Resolve a Location value against the URL it came from.RFC 9110 allows a relative reference, and a client that treated one as absolute would connect to a host named by a path. Three shapes, which is what RFC 3986 §5.2 reduces to once a query and a fragment are out of the picture: an absolute URL, an absolute path, and a relative reference — the last resolved against the base's directory, not against the root. http://h/a/b + c is http://h/a/c; anchoring itat the root would answer http://h/c, which is a different resourceand a silently wrong one. A network-path reference ( //host/path) resolves against the base'sscheme and names a host of its own, which is what RFC 3986 §4.2 says and what separates it from the absolute path directly below. |
| authorityOf(url : string) : string The authority a redirect is resolved against: host, and the port when the base named one that is not its scheme's default. |
| baseDirectory(path : string) : string The directory part of a path — everything through its last /, and"/" when it has none. The prefix a relative reference is resolvedagainst. |
| sameOrigin(a : string, b : string) : bool Whether two URLs name the same origin — scheme, host and port, which is the triple a credential is scoped to. |
| withoutCredentials(headers : string) : string The header block with every credential-bearing field removed.Authorization and Cookie are what a caller grants to one origin;Proxy-Authorization is granted to one hop. Everything else the callerset is its own business and travels on. |
| isCredentialHeader(name : string) : bool Whether name carries a credential scoped to one origin or one hop. |
Method detail
#maxRedirects
Redirects followed before giving up. RFC 9110 suggests a small bound.
#jsonMediaType
The media type a postJson and its siblings declare.
#runExchange
One exchange, following up to [maxRedirects] redirections.
A 301, 302 or 303 answering anything but HEAD is re-issued as a GET with
the body dropped: mandatory for a 303, and for the other two what RFC 9110
codifies from what deployed clients already did. A 307 or 308 keeps both.
IOException on a connect failure, a malformed response, a boundexceeded, or a scheme that is neither
http nor https.#resolveLocation
Resolve a Location value against the URL it came from.
RFC 9110 allows a relative reference, and a client that treated one as
absolute would connect to a host named by a path. Three shapes, which
is what RFC 3986 §5.2 reduces to once a query and a fragment are out of
the picture: an absolute URL, an absolute path, and a relative
reference — the last resolved against the base's directory, not
against the root. http://h/a/b + c is http://h/a/c; anchoring it
at the root would answer http://h/c, which is a different resource
and a silently wrong one.
A network-path reference (//host/path) resolves against the base's
scheme and names a host of its own, which is what RFC 3986 §4.2 says
and what separates it from the absolute path directly below.
#baseDirectory
The directory part of a path — everything through its last /, and"/" when it has none. The prefix a relative reference is resolved
against.
path the base URL's path component, possibly empty#sameOrigin
Whether two URLs name the same origin — scheme, host and port, which is
the triple a credential is scoped to.
#withoutCredentials
The header block with every credential-bearing field removed.Authorization and Cookie are what a caller grants to one origin;Proxy-Authorization is granted to one hop. Everything else the caller
set is its own business and travels on.
headers the request's field block, Name: Value\r\n repeated#isCredentialHeader
Whether name carries a credential scoped to one origin or one hop.
C class HttpRequest
One request under construction: where it goes, what it carries, and how
long it may take.
Every setter answers the request, so configuration chains; every verb
sends it and answers the response. A request is used once — the verb
is the end of its life — so nothing here is reset afterwards.
Constructors
| Type | Method and description |
|---|---|
| constructor(url : string, headers : string, timeout : i32) Built by [HttpClient::request], which seeds it with what theclient carries. Public so a caller holding neither can still write one, but the client is the ordinary way in. |
Method detail
#constructor
Built by [HttpClient::request], which seeds it with what the
client carries. Public so a caller holding neither can still write
one, but the client is the ordinary way in.
Methods
| Type | Method and description |
|---|---|
| header(
mut self,
name : string,
value : string
) : HttpRequest Set a field on this request, replacing any the client set under the same name. Replacing rather than appending, because a block is lines: a second Accept is a second line, and a server reading the first sees avalue the caller thought they had overwritten. |
| query(mut self, name : string, value : string) : HttpRequest Append name=value to the query, encoded.Encoded here rather than by the caller: a value carrying &, = ora space changes which parameters the server reads, and remembering to call an encoder is exactly what a caller forgets. The form encoding is the one a query string uses in practice, so a space is +. |
| timeoutMillis(mut self, millis : i32) : HttpRequest Bound this request. 0 leaves the OS default. |
| get(self) : HttpResponse Send it as GET. |
| head(self) : HttpResponse Send it as HEAD — the head a GET would answer, with no body. |
| delete(self) : HttpResponse Send it as DELETE. |
| options(self) : HttpResponse Send it as OPTIONS — what the origin says it accepts. |
| post(self, body : string) : HttpResponse Send it as POST, carrying body. |
| put(self, body : string) : HttpResponse Send it as PUT, carrying body. |
| patch(self, body : string) : HttpResponse Send it as PATCH, carrying body. |
| postJson(mut self, body : string) : HttpResponse POST body as JSON: the same send, with Content-Type declared.Declared here because a body without one is what a server answers 415 to, and a caller who has written JSON has already said what itis. The three JSON verbs are the three that carry a body. |
| putJson(mut self, body : string) : HttpResponse PUT body as JSON — see [postJson]. |
| patchJson(mut self, body : string) : HttpResponse PATCH body as JSON — see [postJson]. |
| withJsonType(mut self) : HttpRequest This request with Content-Type: application/json, replacing a typethe caller set. The header cannot carry a control byte, so the refusal header declares cannot happen here and is absorbed. |
| applying(mut self, opts : RequestOptions) : HttpRequest This request with opts applied — the one-call form's whole effect,and a chain step in its own right. Public because the two forms are one surface and not two: a caller who has a record in hand and a header to add writes request(url).applying(opts).header(k, v), in either order, ratherthan choosing between the record and the chain. What the record sets is what the equivalent setters set, so the last word wins the same way it does between two header calls.A refusal here is an IOException and not theIllegalArgumentException header raises, and the difference isdeliberate: the record exists so one call needs one catch, and asecond exception type on it would undo that. It is the same verdict exchange already gives a URL that would split the request, at thesame moment — nothing has been sent. |
| target(self) : string The URL this request is sent to: what the caller wrote, plus the query it accumulated. |
Method detail
#header
Set a field on this request, replacing any the client set under the
same name.
Replacing rather than appending, because a block is lines: a secondAccept is a second line, and a server reading the first sees a
value the caller thought they had overwritten.
name field namevalue field valueIllegalArgumentException if either half carries CR, LF or NUL.#query
Append name=value to the query, encoded.
Encoded here rather than by the caller: a value carrying &, = or
a space changes which parameters the server reads, and remembering to
call an encoder is exactly what a caller forgets. The form encoding
is the one a query string uses in practice, so a space is +.
#timeoutMillis
Bound this request. 0 leaves the OS default.
#get
Send it as GET.
#head
Send it as HEAD — the head a GET would answer, with no body.
#delete
Send it as DELETE.
#options
Send it as OPTIONS — what the origin says it accepts.
#post
Send it as POST, carrying body.
#put
Send it as PUT, carrying body.
#patch
Send it as PATCH, carrying body.
#postJson
POST body as JSON: the same send, with Content-Type declared.
Declared here because a body without one is what a server answers415 to, and a caller who has written JSON has already said what it
is. The three JSON verbs are the three that carry a body.
#putJson
PUT body as JSON — see [postJson].
#patchJson
PATCH body as JSON — see [postJson].
#withJsonType
This request with Content-Type: application/json, replacing a type
the caller set. The header cannot carry a control byte, so the
refusal header declares cannot happen here and is absorbed.
#applying
This request with opts applied — the one-call form's whole effect,
and a chain step in its own right.
Public because the two forms are one surface and not two: a caller who
has a record in hand and a header to add writesrequest(url).applying(opts).header(k, v), in either order, rather
than choosing between the record and the chain. What the record sets
is what the equivalent setters set, so the last word wins the same way
it does between two header calls.
A refusal here is an IOException and not theIllegalArgumentException header raises, and the difference is
deliberate: the record exists so one call needs one catch, and a
second exception type on it would undo that. It is the same verdictexchange already gives a URL that would split the request, at the
same moment — nothing has been sent.
IOException if contentType carries CR, LF or NUL.#target
The URL this request is sent to: what the caller wrote, plus the
query it accumulated.