CrowdControl.Backend.Docker.API (crowd_control v0.2.0)

Copy Markdown View Source

Thin HTTP layer over the Docker Engine API.

Handles transport selection (Unix socket or TCP), JSON encoding, and error normalization. Nothing here knows what CrowdControl uses Docker for — that is CrowdControl.Backend.Docker's job.

Error normalization

Every function returns {:ok, term} or {:error, reason}. Transport failures (%Req.TransportError{}), non-2xx statuses, and timeouts are all flattened into {:error, {:docker, reason}} shapes here, so that by the time a failure reaches CrowdControl.Session it looks like every other backend failure. See CrowdControl.Backend.safe/2 for why that normalization belongs in the backend rather than in the session.

Summary

Types

config()

Docker connection config: :docker_host, :timeout.

Functions

host(config)

The configured Docker host, defaulting to the standard Unix socket.

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

Issue a request, returning the decoded body on 2xx.

stream(config, method, path, opts \\ [])

Like request/4 but returns the raw Req.Response rather than the body.

transport(url)

Build Req options for the configured Docker host.

Types

config()

@type config() :: keyword()

Docker connection config: :docker_host, :timeout.

Functions

host(config)

@spec host(config()) :: String.t()

The configured Docker host, defaulting to the standard Unix socket.

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

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

Issue a request, returning the decoded body on 2xx.

opts are merged into the Req call, so :json, :params, and :into all work as usual.

stream(config, method, path, opts \\ [])

@spec stream(config(), atom(), String.t(), keyword()) ::
  {:ok, Req.Response.t()} | {:error, term()}

Like request/4 but returns the raw Req.Response rather than the body.

Needed for streaming (into: :self), where the caller must keep the response struct in order to call Req.parse_message/2 and Req.cancel_async_response/1.

transport(url)

@spec transport(String.t()) :: {:ok, keyword()} | {:error, term()}

Build Req options for the configured Docker host.

Accepts unix://<path>, http://host:port, and tcp://host:port.

iex> CrowdControl.Backend.Docker.API.transport("unix:///var/run/docker.sock")
{:ok, [base_url: "http://localhost", unix_socket: "/var/run/docker.sock"]}

iex> CrowdControl.Backend.Docker.API.transport("tcp://10.0.0.5:2375")
{:ok, [base_url: "http://10.0.0.5:2375"]}