@spec apply_runtime_config(map()) :: :ok | {:error, term()}

Apply JSON config directly to running Caddy (bypasses in-memory).

Use this for runtime-only changes that don't need to persist.

@spec check_sync_status() :: {:ok, sync_status()}

Check if in-memory and runtime configs are in sync.

Returns :in_sync if configs match, or {:drift_detected, diff} with information about the differences.

Returns a specification to start this module under a supervisor.

See Supervisor.

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

Clear the current configuration, returning to unconfigured state.

@spec configured?() :: boolean()

Check if configuration is set (configured, synced, or degraded state).

@spec get_config(source()) :: {:ok, map()} | {:error, term()}

Get configuration from specified source.

Sources

• :memory - Returns the in-memory config as JSON (adapted from Caddyfile)
• :runtime - Returns the running Caddy's JSON config
• :both - Returns both configs in a map

Examples

{:ok, config} = Caddy.ConfigManager.get_config(:runtime)
{:ok, %{memory: mem_config, runtime: rt_config}} = Caddy.ConfigManager.get_config(:both)

@spec get_internal_state() :: map()

Get current internal state information (for debugging).

@spec get_memory_config(:caddyfile | :json) ::
  {:ok, binary() | map()} | {:error, term()}

Get in-memory config in specified format.

Formats

• :caddyfile - Returns raw Caddyfile text
• :json - Returns JSON map (adapted from Caddyfile)

@spec get_runtime_config() :: {:ok, map()} | {:error, term()}

Get JSON config from running Caddy.

@spec get_runtime_config(String.t()) :: {:ok, map()} | {:error, term()}

Get JSON config from running Caddy at specific path.

@spec get_state() :: application_state()

Get the current application state.

Returns one of: :initializing, :unconfigured, :configured, :synced, :degraded

@spec ready?() :: boolean()

Check if the system is ready to serve (synced state).

@spec report_health_status(:ok | :error) :: :ok

Report a health check result to update state.

Called by Server.External when health checks complete.

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

Rollback to last known good config.

Restores the last successfully synced configuration.

@spec set_caddyfile(
  binary(),
  keyword()
) :: :ok | {:error, term()}

Set Caddyfile in memory with optional sync to Caddy.

Options

• :sync - If true, immediately sync to running Caddy (default: false)
• :validate - If true, validate before setting (default: true)

@spec start_link(keyword()) :: GenServer.on_start()

Start the ConfigManager GenServer

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

Pull running Caddy config to memory.

DEPRECATED: This function stores JSON in the Caddyfile field, which breaks the text-first design principle. It will be removed in v3.0.0.

The Caddy Admin API returns JSON configuration, but there is no reverse conversion from JSON back to Caddyfile format. Use get_runtime_config/0 to inspect the running configuration instead.

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

Push in-memory config to running Caddy.

Adapts the Caddyfile to JSON and loads it into the running Caddy instance.

Options

• :backup - If true, backup current runtime config before sync (default: true)
• :force - If true, skip validation (default: false)

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

Validate config without applying.