Reference

std/http/pool

std/http/src/pool.trb

The client that keeps connections: a Client holds a pool of kept-alive connections per origin, at most maximumConnections of them open to one origin at a time, and follows redirects as its RedirectPolicy allows (docs/design/NETWORK.md section 7, slice 7).

A pooled connection goes back to its pool when the body of its response was read to its end, and is closed when the response is released before that: reading the rest of a body nobody wants only to reuse its connection costs more than a new one. A request waits for a connection where the origin has maximumConnections in use.

type RedirectPolicy

type RedirectPolicy with Show, Equals

What a Client does with a redirect - a 301, 302, 303, 307 or 308 with a Location field. A redirect that is not followed is the response the program gets, as it is from the free functions, which follow none.

Whatever the policy, a redirect from https to http is never followed - the request and everything it carries would cross the network in the clear - and neither is one that would have to send a body again that was a stream: 307 and 308 keep the method and the body, and a body is read once. 301, 302 and 303 turn a POST into a GET without a body, as every browser does; 303 turns every method but HEAD into one.

case Never

case Never

None is followed: the redirect is the response.

case SameHost

case SameHost(limit: Int)

Redirects to the same host - any port and scheme, http to https included - are followed, at most limit of them for one request; one to another host is the response. The default of a Client: a program that named a host gets answers from that host.

case AnyHost

case AnyHost(limit: Int)

Redirects to any host are followed, at most limit of them. Where the host changes, Authorization, Cookie and Proxy-Authorization are not sent on: the credentials a program gave one host are not handed to another.

fn show

fn show(): String

Not documented.

type Client

shared type Client

An HTTP client that keeps its connections alive between requests, one pool per origin, and follows redirects. Its get, post and send are the free functions', so a program that wants the pool changes one line:

const client = Client(maximumConnections: 4, timeout: Some(10.seconds()))
var first = client.get(api.joined("users/1")).await()?
const user = first.body.text().await()?
var second = client.get(api.joined("users/2")).await()?    // the same connection, if the server kept it

A Client is a shared type: its pool is one set of connections that every request of the client draws from, and like every object it stays with the task that made it - the requests of one client run on that task's worker.

field maximumConnections

maximumConnections: Int = 6

How many connections to one origin may be open at once; a request beyond waits for one to come back.

field timeout

timeout: Duration? = None

How long a request may take until its response's head arrived - connecting, sending and waiting, redirects included - or None for no limit of the client's. Reading the body is the program's, which limits it with within.

field redirects

redirects: RedirectPolicy = RedirectPolicy.SameHost 10

Which redirects are followed.

field tls

tls: TlsSettings = TlsSettings()

What an https connection trusts: the platform's roots, and the ones given here.

fn get

fn get(url: Uri, headers: Headers = Headers()): Task<Result<Response, HttpError>>

A GET of url: Client.send with the method.

fn post

fn post(url: Uri, body: Body, headers: Headers = Headers()): Task<Result<Response, HttpError>>

A POST of body to url: Client.send with the method.

fn send

fn send(method: Method, url: Uri, headers: Headers = Headers(), body: Body = Body.empty()): Task<Result<Response, HttpError>>

A request of any method, over a kept-alive connection to the origin of url where one is idle and over a new one where none is, following redirects as Client.redirects allows. A kept-alive connection the server closed while it was idle is noticed when the request finds it closed before any byte of a response arrived, and a request of an idempotent method without a body is then sent once more over a new connection.

Errors