ExIncus.Client (ex_incus v1.0.0)

Copy Markdown

Connection to an Incus server.

Build a client once with new/1 and pass it to every API call. The client is a plain struct (no process, no state), so it is safe to share between processes.

Local connection (Unix socket)

The default. Connects to /var/lib/incus/unix.socket:

client = ExIncus.Client.new()
client = ExIncus.Client.new(socket_path: "/run/incus/unix.socket")

Remote connection (HTTPS + client certificate)

Incus authenticates remote clients by TLS client certificate (the cert must be in the server's trust store, see incus config trust):

client =
  ExIncus.Client.new(
    base_url: "https://incus.example.net:8443",
    certfile: "/path/client.crt",
    keyfile: "/path/client.key"
  )

Incus servers normally use a self-signed certificate, so peer verification is disabled unless you pass cacertfile: (or an explicit verify: option).

Options

  • :socket_path - path of the Incus Unix socket (default /var/lib/incus/unix.socket); ignored if :base_url is set
  • :base_url - https://host:8443 style URL for remote connections
  • :certfile / :keyfile - TLS client certificate and key (PEM)
  • :cacertfile - CA certificate to verify the server against; setting it switches on verify: :verify_peer

  • :verify - override TLS verification (:verify_none | :verify_peer)

  • :project - Incus project to scope all requests to (each call may override with its own project: option)
  • :receive_timeout - HTTP receive timeout in ms (default 30_000)
  • :req_options - extra options merged into the underlying Req request (escape hatch; also how tests plug in Req.Test)

Summary

Types

t()

Functions

new(opts \\ [])

Builds a new client. See the module documentation for options.

request(client, method, path, opts \\ [])

Performs a request against the API and normalises the response.

Types

t()

@type t() :: %ExIncus.Client{project: String.t() | nil, req: Req.Request.t()}

Functions

new(opts \\ [])

@spec new(keyword()) :: t()

Builds a new client. See the module documentation for options.

request(client, method, path, opts \\ [])

@spec request(t(), atom(), String.t(), keyword()) ::
  {:ok, term()} | {:error, ExIncus.Error.t()}

Performs a request against the API and normalises the response.

This is the low-level entry point used by all the resource modules; use it directly for any endpoint not yet wrapped.

Returns:

  • {:ok, metadata} for synchronous responses (metadata is the decoded "metadata" field of the response envelope)
  • {:ok, %ExIncus.Operation{}} for asynchronous responses
  • {:ok, binary} for raw responses (raw: true, e.g. file download)
  • {:error, %ExIncus.Error{}} for API errors and transport failures

Options

  • :params - query parameters (keyword or map)
  • :json - request body, encoded as JSON
  • :body - raw request body (file uploads)
  • :headers - additional request headers
  • :raw - do not decode the response body (file downloads)
  • :project - override the client's project for this request
  • :receive_timeout - override the receive timeout for this request