There are no results.

type pub Client

An HTTP client for sending requests and parsing their responses.

A Client transparently supports both HTTP and HTTPS connections.

Constructing a Client is considered to be somewhat expensive due to the various data structures it needs to set up (e.g. TLS configuration, a connection pool, etc). It's best to do this once and reuse the Client as much as possible.

Requests are built using methods such as Client.get, Client.post or Client.put. These methods return a Request, used for constructing the request (e.g. setting the headers, body, etc). For example, to send a GET request:

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic
let req = client.get(uri)
let resp = req.send.or_panic
let body = ByteArray.new

# Read the entire response and panic upon encountering an error.
let _ = resp.body.read_all(body).or_panic

Refer to the documentation of these methods and the Request type for more details.

TLS configuration

The configuration for TLS clients is stored in the Client.tls field. By default the system certificate store is used. To use a custom certificate, use std.net.tls.ClientConfig.with_certificate to create a custom client configuration object and assign it to the Client.tls field:

import std.net.http.client (Client)
import std.net.tls (ClientConfig)

let client = Client.new

client.tls = ClientConfig
  .with_certificate(...)
  .or_panic_with('the certificate is invalid')

Default User-Agent header

The default value for the User-Agent header is inko/VERSION (https://inko-lang.org) where VERSION is the version of Inko (e.g. inko/1.2.3 (https://inko-lang.org)). It's highly recommended to use a custom value instead. This can be changed by setting the field Client.user_agent to a different value, or by setting the User-Agent header to a custom value on a per-request basis.

Timeouts

A Client uses a timeout when connecting to a server and when sending requests and parsing their responses. These timeouts are controlled by the following fields:

• Client.connect_timeout
• Client.request_timeout

TCP keepalive

Each connection uses a custom set of TCP keepalive settings, controlled by the following fields:

• Client.tcp_keepalive_time
• Client.tcp_keepalive_interval

Both default to 15 seconds in an attempt to prevent idle reusable connections from being terminated prematurely.

Connection reuse

Connections are reused whenever possible, unless a server explicitly signals that keep-alive conections aren't supported. By default the maximum number of connections per host is limited to 5 connections. To disable keeping connections alive, set this value to 0 using Client.connections_per_host=.

Connections can only be reused if the body of a response is consumed as a whole. If any bytes remain available, the connection is terminated when a Response is dropped.

Redirects

Redirects are followed when using Request.send or Request.body to send a request. For more details, refer to the documentation of Request.body.

Basic authentication

If the URI to send a request to includes the user info component (i.e. https://user:pass@host), this component is used to set the Authorization header before sending a request, unless a custom Authorization header is already specified. For example:

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri
  .parse('https://user:pass@httpbun.com/basic-auth/user/pass')
  .or_panic

let resp = client.get(uri).send.or_panic
let body = ByteArray.new
let _ = resp.body.read_all(body).or_panic

body.to_string

The output of this is:

{
  "authenticated": true,
  "user": "user"
}

By default this header is removed when redirecting to a different host. This can be disabled by setting Client.remove_authorization_for_different_host to false.

Websockets

A Client supports establishing a WebSocket connection, using the schemes ws, wss, http and https. To create such a connection, use Client.websocket to create a WebsocketRequest, then call WebsocketRequest.send to send the request and establish the connection:

import std.net.http.client (Client)
import std.uri (Uri)

type async Main {
  fn async main {
    let client = Client.new
    let uri = Uri.parse('https://echo.websocket.org').or_panic
    let (sock, _response) = client.websocket(uri).send.or_panic

    let _ = sock.receive.or_panic
    let _ = sock.text('hello').or_panic

    sock.receive.or_panic # => Message.Text('hello')
  }
}

Fields

let pub @random: Random

let pub @tls: Option[ClientConfig]

let pub @limits: Limits

let pub @user_agent: String

let pub @connect_timeout: Duration

let pub @request_timeout: Duration

let pub @tcp_keepalive_time: Duration

let pub @tcp_keepalive_interval: Duration

let pub @max_redirects: Int

let pub @remove_authorization_for_different_host: Bool

let pub @base_uri: Option[Uri]

Static methods

fn pub static new -> Self {
  Self(
    random: Random.new,
    tls: Option.None,
    dns: dns.Resolver.new,
    connections: Pool.new,
    user_agent: USER_AGENT,
    limits: Limits.new,
    connect_timeout: Duration.from_secs(5),
    request_timeout: Duration.from_secs(15),
    tcp_keepalive_time: Duration.from_secs(15),
    tcp_keepalive_interval: Duration.from_secs(15),
    max_redirects: 5,
    remove_authorization_for_different_host: true,
    base_uri: Option.None,
    buffer: ByteArray.new,
  )
}

fn pub static new -> Client

Instance methods

fn pub mut connections_per_host=(value: Int) {
  @connections.limit = value
}

fn pub mut connections_per_host=(value: Int)

fn pub mut delete(uri: Uri) -> Request {
  request(Method.Delete, uri)
}

fn pub mut delete(uri: Uri) -> Request

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.delete(uri)

fn pub mut get(uri: Uri) -> Request {
  request(Method.Get, uri)
}

fn pub mut get(uri: Uri) -> Request

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.get(uri)

fn pub mut head(uri: Uri) -> Request {
  request(Method.Head, uri)
}

fn pub mut head(uri: Uri) -> Request

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.head(uri)

fn pub mut post(uri: Uri) -> Request {
  request(Method.Post, uri)
}

fn pub mut post(uri: Uri) -> Request

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.post(uri)

fn pub mut put(uri: Uri) -> Request {
  request(Method.Put, uri)
}

fn pub mut put(uri: Uri) -> Request

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.put(uri)

fn pub mut request(method: Method, uri: Uri) -> Request {
  Request.new(self, method, uri)
}

fn pub mut request(method: Method, uri: Uri) -> Request

import std.net.http (Method)
import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.request(Method.Get, uri)

fn pub mut websocket(uri: Uri) -> WebsocketRequest {
  WebsocketRequest.new(get(uri))
}

fn pub mut websocket(uri: Uri) -> WebsocketRequest

import std.net.http.client (Client)
import std.uri (Uri)

let client = Client.new
let uri = Uri.parse('https://example.com').or_panic

client.websocket(uri)