Axle v0.22.0
Package

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 to
maxRedirects 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

TypeMethod and description
i32
maxRedirects() : i32 Redirects followed before giving up. RFC 9110 suggests a small bound.
string
jsonMediaType() : string The media type a postJson and its siblings declare.
HttpResponse
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.
string
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 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.
string
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.
string
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 resolved
against.
bool
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.
string
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 caller
set is its own business and travels on.
bool
isCredentialHeader(name : string) : bool Whether name carries a credential scoped to one origin or one hop.

Method detail

#maxRedirects

maxRedirects() : i32

Redirects followed before giving up. RFC 9110 suggests a small bound.

#jsonMediaType

jsonMediaType() : string

The media type a postJson and its siblings declare.

#runExchange

runExchange( verb : string, target : string, payload : string, headerBlock : string, timeoutMillis : i32 ) : HttpResponse ! IOException

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.

Throws
IOException on a connect failure, a malformed response, a bound
exceeded, or a scheme that is neither http nor https.

#resolveLocation

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 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.

#authorityOf

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

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 resolved
against.

Parameters
path the base URL's path component, possibly empty

#sameOrigin

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

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 caller
set is its own business and travels on.

Parameters
headers the request's field block, Name: Value\r\n repeated

#isCredentialHeader

isCredentialHeader(name : string) : bool

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

TypeMethod and description
constructor(url : string, headers : string, timeout : i32) 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.

Method detail

#constructor

constructor(url : string, headers : string, timeout : i32)

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

TypeMethod and description
HttpRequest
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 a
value the caller thought they had overwritten.
HttpRequest
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 &, = 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 +.
HttpRequest
timeoutMillis(mut self, millis : i32) : HttpRequest Bound this request. 0 leaves the OS default.
HttpResponse
get(self) : HttpResponse Send it as GET.
HttpResponse
head(self) : HttpResponse Send it as HEAD — the head a GET would answer, with no body.
HttpResponse
delete(self) : HttpResponse Send it as DELETE.
HttpResponse
options(self) : HttpResponse Send it as OPTIONS — what the origin says it accepts.
HttpResponse
post(self, body : string) : HttpResponse Send it as POST, carrying body.
HttpResponse
put(self, body : string) : HttpResponse Send it as PUT, carrying body.
HttpResponse
patch(self, body : string) : HttpResponse Send it as PATCH, carrying body.
HttpResponse
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 it
is. The three JSON verbs are the three that carry a body.
HttpResponse
putJson(mut self, body : string) : HttpResponse PUT body as JSON — see [postJson].
HttpResponse
patchJson(mut self, body : string) : HttpResponse PATCH body as JSON — see [postJson].
HttpRequest
withJsonType(mut self) : HttpRequest 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.
HttpRequest
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, 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 the
IllegalArgumentException 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 verdict
exchange already gives a URL that would split the request, at the
same moment — nothing has been sent.
string
target(self) : string The URL this request is sent to: what the caller wrote, plus the
query it accumulated.

Method detail

#header

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

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 a
value the caller thought they had overwritten.

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

#query

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 &, = 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

timeoutMillis(mut self, millis : i32) : HttpRequest

Bound this request. 0 leaves the OS default.

#get

get(self) : HttpResponse ! IOException

Send it as GET.

#head

head(self) : HttpResponse ! IOException

Send it as HEAD — the head a GET would answer, with no body.

#delete

delete(self) : HttpResponse ! IOException

Send it as DELETE.

#options

options(self) : HttpResponse ! IOException

Send it as OPTIONS — what the origin says it accepts.

#post

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

Send it as POST, carrying body.

#put

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

Send it as PUT, carrying body.

#patch

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

Send it as PATCH, carrying body.

#postJson

postJson(mut self, body : string) : HttpResponse ! IOException

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 it
is. The three JSON verbs are the three that carry a body.

#putJson

putJson(mut self, body : string) : HttpResponse ! IOException

PUT body as JSON — see [postJson].

#patchJson

patchJson(mut self, body : string) : HttpResponse ! IOException

PATCH body as JSON — see [postJson].

#withJsonType

withJsonType(mut self) : HttpRequest

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

applying(mut self, opts : RequestOptions) : HttpRequest ! IOException

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, 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 the
IllegalArgumentException 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 verdict
exchange already gives a URL that would split the request, at the
same moment — nothing has been sent.

Throws
IOException if contentType carries CR, LF or NUL.

#target

target(self) : string

The URL this request is sent to: what the caller wrote, plus the
query it accumulated.