Add support for connecting through Unix socket (#11)

Author: alexandre-daubois

README.md

@@ -43,6 +43,7 @@ Caddy exposes rich metrics through its admin API and Prometheus endpoint, but re
 - Readiness gate: `ember wait` blocks until Caddy is up (`-q` for silent scripting)
 - Deployment validation: `ember diff before.json after.json` compares snapshots
 - Zero-config setup: `ember init` checks Caddy, enables metrics, and warns about missing host matchers
+- Unix socket support for Caddy admin APIs configured with `admin unix//path`
 - TLS and mTLS support for secured Caddy admin APIs
 - Environment variable configuration (`EMBER_ADDR`, `EMBER_EXPOSE`, ...) for container deployments
 - `NO_COLOR` env var support ([no-color.org](https://no-color.org/))

cmd/ember/main_test.go

@@ -30,7 +30,7 @@ func TestRun_InvalidFlag(t *testing.T) {
 func TestRun_InvalidAddr(t *testing.T) {
 	err := app.Run([]string{"--addr", "localhost:2019"}, version)
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "--addr must start with http:// or https://")
+	assert.Contains(t, err.Error(), "--addr must start with http://, https://, or unix//")
 }
 
 func TestRun_InvalidInterval(t *testing.T) {

docs/caddy-configuration.md

@@ -14,6 +14,39 @@ Ember connects to the Caddy admin API (default: `localhost:2019`). Make sure it'
 
 > **Caution:** The admin API is unauthenticated by default. Do not expose it on a public interface. See [Caddy's admin API documentation](https://caddyserver.com/docs/caddyfile/options#admin) for authentication options.
 
+## Unix Socket
+
+For improved security, Caddy can listen on a Unix socket instead of a TCP port. This avoids network exposure entirely and restricts access through filesystem permissions:
+
+```
+{
+    admin unix//run/caddy/admin.sock
+}
+```
+
+You can also set file permissions on the socket:
+
+```
+{
+    admin unix//run/caddy/admin.sock|0660
+}
+```
+
+To connect Ember to a Unix socket:
+
+```bash
+ember --addr unix//run/caddy/admin.sock
+```
+
+Or via environment variable:
+
+```bash
+export EMBER_ADDR=unix//run/caddy/admin.sock
+ember
+```
+
+> **Note:** TLS options (`--ca-cert`, `--client-cert`, `--client-key`, `--insecure`) cannot be used with Unix socket addresses, as the connection is local and does not traverse the network.
+
 ## Metrics Directive
 
 The `metrics` directive enables Prometheus-format metrics on the admin API. Without it, Ember cannot display HTTP traffic data.

docs/cli-reference.md

@@ -10,7 +10,7 @@ ember [flags]
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--addr` | string | `http://localhost:2019` | Caddy admin API address |
+| `--addr` | string | `http://localhost:2019` | Caddy admin API address (`http://`, `https://`, or `unix//path`) |
 | `--interval` | duration | `1s` | Polling interval |
 | `--timeout` | duration | `0` (none) | Global timeout. Applies to all modes and subcommands. 0 means no timeout. |
 | `--slow-threshold` | int | `500` | Slow request threshold in milliseconds. Requests above this are highlighted yellow; above 2x are red. |
@@ -35,7 +35,7 @@ Some flags can be set via environment variables. Explicit flags always take prec
 
 | Variable | Flag | Example |
 |----------|------|---------|
-| `EMBER_ADDR` | `--addr` | `EMBER_ADDR=http://caddy:2019` |
+| `EMBER_ADDR` | `--addr` | `EMBER_ADDR=http://caddy:2019` or `EMBER_ADDR=unix//run/caddy/admin.sock` |
 | `EMBER_INTERVAL` | `--interval` | `EMBER_INTERVAL=5s` |
 | `EMBER_EXPOSE` | `--expose` | `EMBER_EXPOSE=:9191` |
 | `EMBER_METRICS_PREFIX` | `--metrics-prefix` | `EMBER_METRICS_PREFIX=myapp` |
@@ -52,6 +52,9 @@ ember
 # Connect to a remote Caddy instance
 ember --addr http://prod:2019
 
+# Connect via Unix socket
+ember --addr unix//run/caddy/admin.sock
+
 # Pipe-friendly JSON output
 ember --json
 

docs/docker.md

@@ -70,6 +70,40 @@ With this setup, Ember runs in the same network namespace as Caddy and can reach
 
 > **Caution:** The image is built from `scratch`: there is no shell, no `exec`, and no debugging tools inside the container. Use `docker logs` to read Ember's stderr output.
 
+## Unix Socket
+
+If Caddy's admin API is configured to listen on a Unix socket, mount the socket into the Ember container:
+
+```bash
+docker run --rm \
+  -v /run/caddy/admin.sock:/run/caddy/admin.sock \
+  ghcr.io/alexandre-daubois/ember \
+  --daemon --expose :9191 --addr unix//run/caddy/admin.sock
+```
+
+Or with Docker Compose:
+
+```yaml
+services:
+  caddy:
+    image: caddy:latest
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy-admin:/run/caddy
+
+  ember:
+    image: ghcr.io/alexandre-daubois/ember
+    environment:
+      EMBER_ADDR: unix//run/caddy/admin.sock
+    volumes:
+      - caddy-admin:/run/caddy
+    depends_on:
+      - caddy
+
+volumes:
+  caddy-admin:
+```
+
 ## See Also
 
 - [Getting Started](getting-started.md)

internal/app/daemon.go

@@ -50,6 +50,10 @@ func reloadTLS(f fetcher.Fetcher, cfg *config, log *slog.Logger) {
 		log.Warn("TLS reload not supported for this fetcher")
 		return
 	}
+	if hf.IsUnixSocket() {
+		log.Info("TLS reload skipped (Unix socket connection)")
+		return
+	}
 	if err := configureTLS(hf, cfg); err != nil {
 		log.Error("TLS reload failed", "err", err)
 		return

internal/app/run.go

@@ -63,6 +63,7 @@ Keybindings:
   q                  Quit`,
 		Example: `  ember                                  # default: localhost:2019
   ember --addr http://prod:2019           # custom address
+  ember --addr unix//run/caddy/admin.sock # Unix socket
   ember --json                            # pipe-friendly JSON output
   ember --json --once                     # single JSON snapshot and exit
   ember --expose :9191                    # TUI + Prometheus endpoint
@@ -117,7 +118,7 @@ Keybindings:
 	}
 
 	pf := cmd.PersistentFlags()
-	pf.StringVar(&cfg.addr, "addr", "http://localhost:2019", "Caddy admin API address")
+	pf.StringVar(&cfg.addr, "addr", "http://localhost:2019", "Caddy admin API address (http://, https://, or unix//path)")
 	pf.DurationVar(&cfg.interval, "interval", 1*time.Second, "Polling interval")
 	pf.DurationVar(&cfg.timeout, "timeout", 0, "Global timeout (0 = no timeout)")
 	pf.IntVar(&cfg.frankenphpPID, "frankenphp-pid", 0, "FrankenPHP PID (auto-detected if not set)")
@@ -161,6 +162,9 @@ func contextWithTimeout(parent context.Context, timeout time.Duration) (context.
 }
 
 func configureTLS(f *fetcher.HTTPFetcher, cfg *config) error {
+	if f.IsUnixSocket() {
+		return nil
+	}
 	tlsCfg, err := fetcher.BuildTLSConfig(fetcher.TLSOptions{
 		CACert:     cfg.caCert,
 		ClientCert: cfg.clientCert,
@@ -220,8 +224,16 @@ func validate(cfg *config) error {
 	if cfg.interval < minInterval {
 		return fmt.Errorf("--interval must be at least %s", minInterval)
 	}
-	if !strings.HasPrefix(cfg.addr, "http://") && !strings.HasPrefix(cfg.addr, "https://") {
-		return fmt.Errorf("--addr must start with http:// or https://")
+	if !strings.HasPrefix(cfg.addr, "http://") && !strings.HasPrefix(cfg.addr, "https://") && !fetcher.IsUnixAddr(cfg.addr) {
+		return fmt.Errorf("--addr must start with http://, https://, or unix//")
+	}
+	if fetcher.IsUnixAddr(cfg.addr) {
+		if _, ok := fetcher.ParseUnixAddr(cfg.addr); !ok {
+			return fmt.Errorf("--addr must include a non-empty Unix socket path")
+		}
+		if cfg.caCert != "" || cfg.clientCert != "" || cfg.clientKey != "" || cfg.insecure {
+			return fmt.Errorf("TLS options cannot be used with Unix socket addresses")
+		}
 	}
 	if cfg.metricsAuth != "" {
 		if !strings.Contains(cfg.metricsAuth, ":") {

internal/app/run_test.go

@@ -146,7 +146,7 @@ func TestValidate_AddrMissingScheme(t *testing.T) {
 	cfg := &config{interval: 1 * time.Second, addr: "localhost:2019"}
 	err := validate(cfg)
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "--addr must start with http:// or https://")
+	assert.Contains(t, err.Error(), "--addr must start with http://, https://, or unix//")
 }
 
 func TestValidate_AddrHTTPSOK(t *testing.T) {
@@ -159,6 +159,51 @@ func TestValidate_AddrHTTPOK(t *testing.T) {
 	assert.NoError(t, validate(cfg))
 }
 
+func TestValidate_AddrUnixSocket(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix//run/caddy/admin.sock"}
+	assert.NoError(t, validate(cfg))
+}
+
+func TestValidate_AddrUnixSocketTripleSlash(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix:///run/caddy/admin.sock"}
+	assert.NoError(t, validate(cfg))
+}
+
+func TestValidate_AddrUnixSocketEmptyPath(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix//"}
+	err := validate(cfg)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "non-empty Unix socket path")
+}
+
+func TestValidate_AddrUnixSocketEmptyPathTripleSlash(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix:///"}
+	err := validate(cfg)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "non-empty Unix socket path")
+}
+
+func TestValidate_AddrUnixSocketWithTLS(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix//run/caddy/admin.sock", caCert: "ca.pem"}
+	err := validate(cfg)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "TLS options cannot be used with Unix socket addresses")
+}
+
+func TestValidate_AddrUnixSocketWithClientCert(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix//run/caddy/admin.sock", clientCert: "cert.pem", clientKey: "key.pem"}
+	err := validate(cfg)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "TLS options cannot be used with Unix socket addresses")
+}
+
+func TestValidate_AddrUnixSocketWithInsecure(t *testing.T) {
+	cfg := &config{interval: 1 * time.Second, addr: "unix//run/caddy/admin.sock", insecure: true}
+	err := validate(cfg)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "TLS options cannot be used with Unix socket addresses")
+}
+
 func TestValidate_MetricsAuthBadFormat(t *testing.T) {
 	cfg := &config{interval: 1 * time.Second, addr: "http://localhost:2019", expose: ":9191", metricsAuth: "nopassword"}
 	err := validate(cfg)
@@ -192,13 +237,13 @@ func TestRun_IntervalTooLow(t *testing.T) {
 func TestRun_AddrMissingScheme(t *testing.T) {
 	err := Run([]string{"--addr", "localhost:2019"}, "0.0.0")
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "--addr must start with http:// or https://")
+	assert.Contains(t, err.Error(), "--addr must start with http://, https://, or unix//")
 }
 
 func TestRun_SubcommandValidatesAddr(t *testing.T) {
 	err := Run([]string{"wait", "--addr", "localhost:2019"}, "0.0.0")
 	assert.Error(t, err)
-	assert.Contains(t, err.Error(), "--addr must start with http:// or https://")
+	assert.Contains(t, err.Error(), "--addr must start with http://, https://, or unix//")
 }
 
 func TestRun_SubcommandValidatesInterval(t *testing.T) {

internal/fetcher/http.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"net"
 	"net/http"
 	"os"
 	"slices"
@@ -26,6 +27,7 @@ const (
 
 type HTTPFetcher struct {
 	baseURL    string
+	socketPath string
 	httpClient *http.Client
 	procHandle *processHandle
 
@@ -40,21 +42,41 @@ type HTTPFetcher struct {
 
 func NewHTTPFetcher(baseURL string, pid int32) *HTTPFetcher {
 	ph := newProcessHandle(pid)
+
+	var socketPath string
+	transport := &http.Transport{
+		MaxIdleConns:        2,
+		MaxIdleConnsPerHost: 2,
+		IdleConnTimeout:     30 * time.Second,
+	}
+
+	if sp, ok := ParseUnixAddr(baseURL); ok {
+		socketPath = sp
+		baseURL = "http://localhost"
+		transport.DialContext = func(ctx context.Context, _, _ string) (net.Conn, error) {
+			return (&net.Dialer{}).DialContext(ctx, "unix", sp)
+		}
+	}
+
 	return &HTTPFetcher{
-		baseURL: strings.TrimRight(baseURL, "/"),
-		httpClient: &http.Client{
-			Transport: &http.Transport{
-				MaxIdleConns:        2,
-				MaxIdleConnsPerHost: 2,
-				IdleConnTimeout:     30 * time.Second,
-			},
-		},
+		baseURL:    strings.TrimRight(baseURL, "/"),
+		socketPath: socketPath,
+		httpClient: &http.Client{Transport: transport},
 		procHandle: ph,
 	}
 }
 
+// IsUnixSocket reports whether this fetcher communicates over a Unix socket.
+func (f *HTTPFetcher) IsUnixSocket() bool {
+	return f.socketPath != ""
+}
+
 // SetTLSConfig replaces the HTTP transport with one using the given TLS configuration.
+// It is a no-op when the fetcher uses a Unix socket.
 func (f *HTTPFetcher) SetTLSConfig(tlsConfig *tls.Config) {
+	if f.socketPath != "" {
+		return
+	}
 	f.httpClient.Transport = &http.Transport{
 		TLSClientConfig:     tlsConfig,
 		MaxIdleConns:        2,