`http.client`

import http.client

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.client.* needs import http.client.

HttpClient: the connection-pooling, redirect-following, cookie-aware side of the module.

It negotiates HTTP/2 over TLS when the server offers it, falls back to HTTP/1.1 otherwise, and reuses connections between requests. The module-level http.get()/http.post() shortcuts are thin wrappers around a shared instance of this.

Classes

`HttpClient`

class http.HttpClient

An HTTP client.

import http

var client = http.HttpClient()
var response = client.get('https://example.com')

echo response.status
echo response.as_text()

One client is meant to be kept and reused: it holds the connection pool, the cookie jar, and the TLS configuration, all of which are wasted if a fresh client is built per request. Reusing it also means the second request to a host skips the TCP and TLS handshakes entirely.

Redirects are followed, responses are decompressed, and cookies are carried between requests when a jar is attached - all of which can be turned off.

printable — has a @to_string(), so echo and print() show something useful

Fields

Field	Type	Description
`base_url`	`?string`	Prefixed to any request URL that is not already absolute, so a client can be pointed at one service and then…
`headers`	`Headers`	Headers sent with every request, unless a request overrides them.
`user_agent`	`string`	The `User-Agent` sent unless one is set in `headers`.
`follow_redirects`	`bool`	Whether to follow 3xx responses.
`max_redirects`	`number`	The most redirects to follow before giving up.
`connect_timeout`	`number`	How long to wait for a connection to be established, in milliseconds.
`read_timeout`	`number`	How long to wait for data once connected, in milliseconds.
`write_timeout`	`number`	How long a write may block, in milliseconds.
`verify`	`bool`	Whether to verify the server’s certificate chain and hostname.
`max_body_size`	`number`	The largest response body accepted, in bytes.
`decode_content`	`bool`	Whether to decode a compressed response body automatically.
`max_retries`	`number`	How many times to retry a request that failed on a connection error before giving up.
`http2`	`bool`	Whether to negotiate HTTP/2 over TLS.
`proxy`	`?string`	The HTTP proxy every request goes through, as `http://host:port`, with `user:password@` in front of the host…
`trust_env`	`bool`	Whether to take a proxy from the environment when `proxy` is not set: `HTTPS_PROXY` for `https` addresses,…
`cookie_jar`	`?CookieJar`	The cookie jar, or `nil` to not track cookies at all.

Constructor

http.HttpClient(base_url: ?string, options: ?dict)

Parameters

base_url (?string)
options (?dict) — any of the fields above, plus headers

`HttpClient.get()`

http.HttpClient.get(target: string, options: ?dict) -> HttpResponse

Sends a GET request.

Parameters

target (string) — an absolute URL, or a path when base_url is set
options (?dict) — see request()

Returns HttpResponse

`HttpClient.post()`

http.HttpClient.post(target: string, data, options: ?dict) -> HttpResponse

Sends a POST request.

data may be a string, bytes, a dictionary (sent as JSON), or a MultipartBuilder. Use the form option instead to send a dictionary as application/x-www-form-urlencoded.

Parameters

target (string)
data (?any)
options (?dict) — see request()

Returns HttpResponse

`HttpClient.put()`

http.HttpClient.put(target: string, data, options: ?dict) -> HttpResponse

Sends a PUT request.

Parameters

target (string)
data (?any)
options (?dict)

Returns HttpResponse

`HttpClient.patch()`

http.HttpClient.patch(target: string, data, options: ?dict) -> HttpResponse

Sends a PATCH request.

Parameters

target (string)
data (?any)
options (?dict)

Returns HttpResponse

`HttpClient.delete()`

http.HttpClient.delete(target: string, options: ?dict) -> HttpResponse

Sends a DELETE request.

Parameters

target (string)
options (?dict)

Returns HttpResponse

`HttpClient.head()`

http.HttpClient.head(target: string, options: ?dict) -> HttpResponse

Sends a HEAD request. Redirects are not followed by default here, since the point of a HEAD is usually to inspect the very response a redirect would hide.

Parameters

target (string)
options (?dict)

Returns HttpResponse

`HttpClient.options()`

http.HttpClient.options(target: string, options: ?dict) -> HttpResponse

Sends an OPTIONS request.

Parameters

target (string)
options (?dict)

Returns HttpResponse

`HttpClient.trace()`

http.HttpClient.trace(target: string, options: ?dict) -> HttpResponse

Sends a TRACE request.

Parameters

target (string)
options (?dict)

Returns HttpResponse

Note: A TRACE echoes the request back, headers included, which is why servers that sit behind authenticating proxies usually refuse it.

`HttpClient.request()`

http.HttpClient.request(method: string, target: string, options: ?dict) -> HttpResponse

Sends a request and returns the response.

The options dictionary accepts:

Option	Meaning
`headers`	a dictionary or `Headers` merged over the client’s
`body`	a string or bytes, sent as-is
`json`	any value, JSON-encoded, with the matching content type
`form`	a dictionary, form-urlencoded
`multipart`	a `MultipartBuilder`
`query`	a dictionary merged into the URL’s query string
`auth`	`['basic', user, password]` or `['bearer', token]`
`follow_redirects`	overrides the client setting
`timeout`	read timeout for this request, in milliseconds
`stream`	leave the body unread on `response.body_reader`
`decode_content`	overrides the client setting

Parameters

method (string)
target (string)
options (?dict)

Returns HttpResponse

Raises ConnectionError, TimeoutError, ProtocolError, TooManyRedirectsError, UnsupportedProtocolError

`HttpClient.finish()`

http.HttpClient.finish(response)

Releases the connection behind a streamed response, once the caller has finished reading its body.

Anything left unread is drained so the connection can be reused; when there is too much left for that to be worth it, the connection is closed instead. Calling this on an ordinary (non-streamed) response does nothing.

Parameters

response (HttpResponse)

`HttpClient.add_ca()`

http.HttpClient.add_ca(pem: string)

Trusts an additional PEM-encoded certificate authority, on top of the platform’s own roots.

This is the right way to talk to a service with an internal or self-signed certificate; turning verify off instead trusts everyone, including whoever is between you and the server.

Parameters

pem (string)