feat: expand dynamic config with matchers, env vars, routes, and plugins (#6)

Co-authored-by: Jonathan Gao <[email protected]>

Author: gsmlg

.github/workflows/ci.yml

@@ -121,10 +121,15 @@ jobs:
 
       - name: Restore Dialyzer PLT cache
         uses: actions/cache@v4
+        id: plt-cache
         with:
           path: priv/plts
-          key: ${{ runner.os }}-dialyzer-${{ hashFiles('**/mix.lock') }}
-          restore-keys: ${{ runner.os }}-dialyzer-
+          key: ${{ runner.os }}-plt-otp28-elixir1.18-${{ hashFiles('**/mix.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-plt-otp28-elixir1.18-
+
+      - name: Create PLTs directory
+        run: mkdir -p priv/plts
 
       - name: Run Dialyzer
-        run: mix dialyzer --halt-exit-status
+        run: mix dialyzer

.github/workflows/test.yml

@@ -26,8 +26,17 @@ jobs:
           otp-version: ${{ matrix.otp }}
 
       - name: Download Caddy
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          curl -L "https://github.com/caddyserver/caddy/releases/latest/download/caddy_$(curl -s https://api.github.com/repos/caddyserver/caddy/releases/latest | grep -oP '\"tag_name\": \"v\K[0-9.]+')_linux_amd64.tar.gz" -o caddy.tar.gz
+          # Use GitHub CLI with authentication to avoid rate limits
+          CADDY_VERSION=$(gh release view --repo caddyserver/caddy --json tagName -q '.tagName' | sed 's/^v//')
+          if [ -z "$CADDY_VERSION" ] || [ "$CADDY_VERSION" = "null" ]; then
+            echo "Failed to get latest version, using fallback"
+            CADDY_VERSION="2.9.1"
+          fi
+          echo "Downloading Caddy version: $CADDY_VERSION"
+          curl -fsSL "https://github.com/caddyserver/caddy/releases/download/v${CADDY_VERSION}/caddy_${CADDY_VERSION}_linux_amd64.tar.gz" -o caddy.tar.gz
           tar -xzf caddy.tar.gz
           sudo mv caddy /usr/bin/caddy
           sudo chmod +x /usr/bin/caddy

lib/caddy/config/env_var.ex

@@ -0,0 +1,147 @@
+defmodule Caddy.Config.EnvVar do
+  @moduledoc """
+  Represents a Caddy environment variable placeholder.
+
+  Environment variables in Caddy use `{$VAR}` or `{$VAR:default}` syntax.
+
+  ## Examples
+
+      # Simple environment variable
+      env = EnvVar.new("DATABASE_URL")
+      # Renders as: {$DATABASE_URL}
+
+      # With default value
+      env = EnvVar.new("PORT", "8080")
+      # Renders as: {$PORT:8080}
+
+      # In configuration
+      port_env = EnvVar.new("APP_PORT", "3000")
+      site_address = "localhost:\#{Caddyfile.to_caddyfile(port_env)}"
+      # Results in: localhost:{$APP_PORT:3000}
+
+  ## Usage
+
+  Environment variables are resolved by Caddy at runtime from the process
+  environment. When a default value is provided, Caddy uses that value
+  if the variable is not set.
+
+  """
+
+  @type t :: %__MODULE__{
+          name: String.t(),
+          default: String.t() | nil
+        }
+
+  defstruct [:name, default: nil]
+
+  @doc """
+  Create a new environment variable placeholder.
+
+  ## Parameters
+
+    - `name` - Environment variable name (without `$`)
+    - `default` - Optional default value if variable is unset
+
+  ## Examples
+
+      iex> EnvVar.new("DATABASE_URL")
+      %EnvVar{name: "DATABASE_URL", default: nil}
+
+      iex> EnvVar.new("PORT", "8080")
+      %EnvVar{name: "PORT", default: "8080"}
+
+  """
+  @spec new(String.t(), String.t() | nil) :: t()
+  def new(name, default \\ nil) when is_binary(name) do
+    %__MODULE__{name: name, default: default}
+  end
+
+  @doc """
+  Validate an environment variable.
+
+  ## Examples
+
+      iex> EnvVar.validate(%EnvVar{name: "PORT"})
+      {:ok, %EnvVar{name: "PORT"}}
+
+      iex> EnvVar.validate(%EnvVar{name: ""})
+      {:error, "name cannot be empty"}
+
+      iex> EnvVar.validate(%EnvVar{name: "INVALID-NAME"})
+      {:error, "name must contain only alphanumeric characters and underscores"}
+
+  """
+  @spec validate(t()) :: {:ok, t()} | {:error, String.t()}
+  def validate(%__MODULE__{name: name, default: default} = env_var) do
+    cond do
+      name == "" or name == nil ->
+        {:error, "name cannot be empty"}
+
+      not is_binary(name) ->
+        {:error, "name must be a string"}
+
+      not valid_name?(name) ->
+        {:error, "name must contain only alphanumeric characters and underscores"}
+
+      default != nil and not is_binary(default) ->
+        {:error, "default must be a string or nil"}
+
+      true ->
+        {:ok, env_var}
+    end
+  end
+
+  @doc """
+  Check if a string is a valid environment variable name.
+
+  Valid names contain only alphanumeric characters and underscores,
+  and cannot start with a digit.
+
+  ## Examples
+
+      iex> EnvVar.valid_name?("DATABASE_URL")
+      true
+
+      iex> EnvVar.valid_name?("my-var")
+      false
+
+  """
+  @spec valid_name?(String.t()) :: boolean()
+  def valid_name?(name) when is_binary(name) do
+    Regex.match?(~r/^[A-Za-z_][A-Za-z0-9_]*$/, name)
+  end
+
+  def valid_name?(_), do: false
+end
+
+defimpl Caddy.Caddyfile, for: Caddy.Config.EnvVar do
+  @moduledoc """
+  Caddyfile protocol implementation for EnvVar.
+  """
+
+  def to_caddyfile(%{name: name, default: nil}) do
+    start_time = System.monotonic_time()
+    result = "{$#{name}}"
+    duration = System.monotonic_time() - start_time
+
+    Caddy.Telemetry.emit_config_change(:render, %{duration: duration}, %{
+      module: Caddy.Config.EnvVar,
+      result_size: byte_size(result)
+    })
+
+    result
+  end
+
+  def to_caddyfile(%{name: name, default: default}) do
+    start_time = System.monotonic_time()
+    result = "{$#{name}:#{default}}"
+    duration = System.monotonic_time() - start_time
+
+    Caddy.Telemetry.emit_config_change(:render, %{duration: duration}, %{
+      module: Caddy.Config.EnvVar,
+      result_size: byte_size(result)
+    })
+
+    result
+  end
+end

lib/caddy/config/matcher/client_ip.ex

@@ -0,0 +1,100 @@
+defmodule Caddy.Config.Matcher.ClientIp do
+  @moduledoc """
+  Represents a Caddy client_ip matcher.
+
+  Matches requests by the client IP address, respecting X-Forwarded-For headers
+  when behind trusted proxies.
+
+  ## Examples
+
+      # Match single IP
+      matcher = ClientIp.new(["192.168.1.1"])
+      # Renders as: client_ip 192.168.1.1
+
+      # Match CIDR range
+      matcher = ClientIp.new(["192.168.0.0/16"])
+      # Renders as: client_ip 192.168.0.0/16
+
+      # Match private ranges
+      matcher = ClientIp.new(["private_ranges"])
+      # Renders as: client_ip private_ranges
+
+  ## Shortcuts
+
+  - `private_ranges` - Matches all RFC 1918 private ranges
+  - `forwarded` - Uses the X-Forwarded-For header
+
+  """
+
+  @type t :: %__MODULE__{
+          ranges: [String.t()]
+        }
+
+  defstruct ranges: []
+
+  @doc """
+  Create a new client_ip matcher.
+
+  ## Parameters
+
+    - `ranges` - List of IP addresses, CIDR ranges, or shortcuts
+
+  ## Examples
+
+      iex> ClientIp.new(["192.168.1.1"])
+      %ClientIp{ranges: ["192.168.1.1"]}
+
+      iex> ClientIp.new(["private_ranges"])
+      %ClientIp{ranges: ["private_ranges"]}
+
+  """
+  @spec new([String.t()]) :: t()
+  def new(ranges) when is_list(ranges) do
+    %__MODULE__{ranges: ranges}
+  end
+
+  @doc """
+  Validate a client_ip matcher.
+
+  ## Examples
+
+      iex> ClientIp.validate(%ClientIp{ranges: ["192.168.1.1"]})
+      {:ok, %ClientIp{ranges: ["192.168.1.1"]}}
+
+      iex> ClientIp.validate(%ClientIp{ranges: []})
+      {:error, "ranges cannot be empty"}
+
+  """
+  @spec validate(t()) :: {:ok, t()} | {:error, String.t()}
+  def validate(%__MODULE__{ranges: ranges} = matcher) do
+    cond do
+      ranges == [] ->
+        {:error, "ranges cannot be empty"}
+
+      not Enum.all?(ranges, &is_binary/1) ->
+        {:error, "all ranges must be strings"}
+
+      true ->
+        {:ok, matcher}
+    end
+  end
+end
+
+defimpl Caddy.Caddyfile, for: Caddy.Config.Matcher.ClientIp do
+  @moduledoc """
+  Caddyfile protocol implementation for ClientIp matcher.
+  """
+
+  def to_caddyfile(%{ranges: ranges}) do
+    start_time = System.monotonic_time()
+    result = "client_ip #{Enum.join(ranges, " ")}"
+    duration = System.monotonic_time() - start_time
+
+    Caddy.Telemetry.emit_config_change(:render, %{duration: duration}, %{
+      module: Caddy.Config.Matcher.ClientIp,
+      result_size: byte_size(result)
+    })
+
+    result
+  end
+end

lib/caddy/config/matcher/expression.ex

@@ -0,0 +1,97 @@
+defmodule Caddy.Config.Matcher.Expression do
+  @moduledoc """
+  Represents a Caddy expression matcher.
+
+  Matches requests using CEL (Common Expression Language) expressions.
+
+  ## Examples
+
+      # Match POST/PUT/PATCH methods
+      matcher = Expression.new("{method}.startsWith(\"P\")")
+      # Renders as: expression {method}.startsWith("P")
+
+      # Complex condition
+      matcher = Expression.new("{path}.startsWith(\"/api\") && {method} == \"GET\"")
+      # Renders as: expression {path}.startsWith("/api") && {method} == "GET"
+
+  ## CEL Syntax
+
+  CEL expressions can use Caddy placeholders and support:
+  - String operations: `.startsWith()`, `.endsWith()`, `.contains()`
+  - Comparisons: `==`, `!=`, `<`, `>`, `<=`, `>=`
+  - Logical operators: `&&`, `||`, `!`
+
+  """
+
+  @type t :: %__MODULE__{
+          expression: String.t()
+        }
+
+  defstruct [:expression]
+
+  @doc """
+  Create a new expression matcher.
+
+  ## Parameters
+
+    - `expression` - CEL expression string
+
+  ## Examples
+
+      iex> Expression.new("{method} == \"GET\"")
+      %Expression{expression: "{method} == \"GET\""}
+
+      iex> Expression.new("{path}.startsWith(\"/api\")")
+      %Expression{expression: "{path}.startsWith(\"/api\")"}
+
+  """
+  @spec new(String.t()) :: t()
+  def new(expression) when is_binary(expression) do
+    %__MODULE__{expression: expression}
+  end
+
+  @doc """
+  Validate an expression matcher.
+
+  ## Examples
+
+      iex> Expression.validate(%Expression{expression: "{x} == 1"})
+      {:ok, %Expression{expression: "{x} == 1"}}
+
+      iex> Expression.validate(%Expression{expression: ""})
+      {:error, "expression cannot be empty"}
+
+  """
+  @spec validate(t()) :: {:ok, t()} | {:error, String.t()}
+  def validate(%__MODULE__{expression: expression} = matcher) do
+    cond do
+      expression == "" or expression == nil ->
+        {:error, "expression cannot be empty"}
+
+      not is_binary(expression) ->
+        {:error, "expression must be a string"}
+
+      true ->
+        {:ok, matcher}
+    end
+  end
+end
+
+defimpl Caddy.Caddyfile, for: Caddy.Config.Matcher.Expression do
+  @moduledoc """
+  Caddyfile protocol implementation for Expression matcher.
+  """
+
+  def to_caddyfile(%{expression: expression}) do
+    start_time = System.monotonic_time()
+    result = "expression #{expression}"
+    duration = System.monotonic_time() - start_time
+
+    Caddy.Telemetry.emit_config_change(:render, %{duration: duration}, %{
+      module: Caddy.Config.Matcher.Expression,
+      result_size: byte_size(result)
+    })
+
+    result
+  end
+end