Caddy.Admin.Transport (Caddy v2.3.1)

View Source

Transport abstraction for connecting to Caddy Admin API.

Supports both Unix domain sockets and TCP connections, allowing communication with Caddy instances running in embedded or external mode.

URL Formats

  • unix:///path/to/socket - Unix domain socket
  • http://host:port - TCP connection (default port: 2019)

Examples 

# Parse and connect to Unix socket
{:ok, conn_info} = Transport.parse_url("unix:///var/run/caddy.sock")
{:ok, socket} = Transport.connect(conn_info)

# Parse and connect to TCP
{:ok, conn_info} = Transport.parse_url("http://localhost:2019")
{:ok, socket} = Transport.connect(conn_info)

Summary

Types

conn_info()
tcp_conn()
unix_conn()

Functions

connect(conn_info, opts \\ [])

Connect to Caddy admin API using the provided connection info.

connect_from_config(opts \\ [])

Connect using the current configuration.

get_connection()

Get connection info based on current configuration.

host_header(map)

Get the host header value for HTTP requests.

parse_url(arg1)

Parse an admin URL into connection information.

Types

conn_info()

@type conn_info() :: unix_conn() | tcp_conn()

tcp_conn()

@type tcp_conn() :: %{type: :tcp, host: charlist(), port: non_neg_integer()}

unix_conn()

@type unix_conn() :: %{type: :unix, path: binary()}

Functions

connect(conn_info, opts \\ [])

@spec connect(
  conn_info(),
  keyword()
) :: {:ok, :gen_tcp.socket()} | {:error, term()}

Connect to Caddy admin API using the provided connection info.

Returns a socket that can be used with :gen_tcp functions.

Options

  • :timeout - Connection timeout in milliseconds (default: 5000)
  • :packet - Packet mode (default: :http_bin for HTTP parsing)

connect_from_config(opts \\ [])

@spec connect_from_config(keyword()) :: {:ok, :gen_tcp.socket()} | {:error, term()}

Connect using the current configuration.

Convenience function that combines get_connection/0 and connect/2.

get_connection()

@spec get_connection() :: {:ok, conn_info()} | {:error, term()}

Get connection info based on current configuration.

In embedded mode, uses the configured socket file. In external mode, uses the configured admin_url.

host_header(map)

@spec host_header(conn_info()) :: binary()

Get the host header value for HTTP requests.

For Unix sockets, returns a configured or default host. For TCP connections, returns the actual host:port.

parse_url(arg1)

@spec parse_url(binary()) :: {:ok, conn_info()} | {:error, term()}

Parse an admin URL into connection information.

Examples 

iex> Transport.parse_url("unix:///tmp/caddy.sock")
{:ok, %{type: :unix, path: "/tmp/caddy.sock"}}

iex> Transport.parse_url("http://localhost:2019")
{:ok, %{type: :tcp, host: ~c"localhost", port: 2019}}

iex> Transport.parse_url("http://192.168.1.1")
{:ok, %{type: :tcp, host: ~c"192.168.1.1", port: 2019}}

iex> Transport.parse_url("invalid")
{:error, :invalid_url}