The image apps build FROM, with its health check (closes #45)

The Dockerfile's last stage is now the image of "Deployment" in SPEC.md:
Ubuntu 26.04 with ca-certificates, nix-bin and runit from a dated
snapshot whose InRelease files are checked by hash, nixpkgs from its
release file checked by SHA-256, runsvinit built at a fixed commit, and
smallwebwaf as a runit service. smallwebwaf answers
/_smallwebwaf/healthz, and `smallwebwaf healthcheck`, which takes no
further argument, is the image's HEALTHCHECK. script/example-app builds
an app on the image and checks it end to end.

The Nix profile comes last on the PATH: first, busybox from nixpkgs
replaced runit's own runsvdir and sv. SPEC.md is corrected to match
what was built.

Model: opus-5-5

internal/proxy/health_test.go

@@ -0,0 +1,47 @@
+package proxy_test
+
+import (
+	"net/http"
+	"sync/atomic"
+	"testing"
+
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
+)
+
+func TestHealthEndpointIsAnsweredBeforeAnyCheck(t *testing.T) {
+	t.Parallel()
+
+	var calls atomic.Int32
+
+	app := startApp(t, func(http.ResponseWriter, *http.Request) {
+		calls.Add(1)
+	})
+	// With a limit of one request a minute, any request counted before
+	// the last one would have it refused.
+	addr, out := startProxy(t, app.URL, map[string]string{rateLimitPerMinute: "1"})
+
+	const healthChecks = 3
+
+	for range healthChecks {
+		got := get(t, addr, proxy.HealthPath)
+		wantStatus(t, got, http.StatusOK)
+
+		if string(got.body) != "ok\n" {
+			t.Errorf("health endpoint answered %q, want ok", got.body)
+		}
+	}
+
+	wantStatus(t, get(t, addr, "/"), http.StatusOK)
+
+	lines := out.requestLines(t, healthChecks+1)
+	for _, line := range lines[:healthChecks] {
+		wantLine(t, line, http.StatusOK, requestlog.ActionAdmin)
+	}
+
+	wantLine(t, lines[healthChecks], http.StatusOK, requestlog.ActionForward)
+
+	if calls.Load() != 1 {
+		t.Errorf("the app was called %d times, want once", calls.Load())
+	}
+}

internal/proxy/proxy.go

@@ -13,6 +13,7 @@ import (
 	"sneak.berlin/go/smallwebwaf/internal/config"
 	"sneak.berlin/go/smallwebwaf/internal/lookup"
 	"sneak.berlin/go/smallwebwaf/internal/ratelimit"
+	"sneak.berlin/go/smallwebwaf/internal/requestlog"
 )
 
 // The request line and headers a client may send, and how long a
@@ -34,6 +35,10 @@ const (
 	appIdleConnTimeout = 90 * time.Second
 )
 
+// HealthPath is smallwebwaf's health endpoint, which the container's
+// health check asks.
+const HealthPath = "/_smallwebwaf/healthz"
+
 // Params are what New needs.
 type Params struct {
 	Config *config.Config
@@ -111,6 +116,15 @@ func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	rq := h.newRequest(w, r)
 	defer rq.finish()
 
+	// The health endpoint is answered at once, before any check, so that
+	// a health checker is never refused. It does not ask the app.
+	if r.Method == http.MethodGet && r.URL.Path == HealthPath {
+		rq.line.Action = requestlog.ActionAdmin
+		_, _ = io.WriteString(rq.out, "ok\n")
+
+		return
+	}
+
 	refused := rq.check(r.Context())
 	if refused != nil {
 		rq.answer(*refused)

internal/requestlog/requestlog.go

@@ -28,6 +28,9 @@ const (
 	ActionRateLimited = "rate_limited"
 	// ActionCountryDenied is a request refused for its client's country.
 	ActionCountryDenied = "country_denied"
+	// ActionAdmin is a request smallwebwaf answered at one of its own
+	// endpoints, under /_smallwebwaf/.
+	ActionAdmin = "admin"
 )
 
 // timeLayout is RFC 3339 with milliseconds.

internal/smallwebwaf/healthcheck.go

@@ -0,0 +1,100 @@
+package smallwebwaf
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/url"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/config"
+	"sneak.berlin/go/smallwebwaf/internal/proxy"
+)
+
+// healthCheckTimeout bounds the whole health check.
+const healthCheckTimeout = 5 * time.Second
+
+var errHealthEndpoint = errors.New("smallwebwaf's health endpoint answered")
+
+// HealthCheck is the container's health check. It returns 0 while
+// smallwebwaf answers its health endpoint on 127.0.0.1, at the port in
+// SWWAF_LISTEN_ADDR, and the app accepts connections at the address in
+// SWWAF_UPSTREAM_URL. Otherwise it writes why to stderr and returns 1.
+// args are the arguments after `healthcheck`; it takes none, and given
+// one it names it on stderr and returns 1 without checking anything.
+func HealthCheck(
+	ctx context.Context, args []string, lookupEnv func(string) (string, bool),
+	stderr io.Writer,
+) int {
+	if len(args) > 0 {
+		_, _ = fmt.Fprintf(stderr,
+			"smallwebwaf healthcheck: unexpected argument %q\n", args[0])
+
+		return 1
+	}
+
+	err := healthCheck(ctx, lookupEnv)
+	if err != nil {
+		_, _ = fmt.Fprintln(stderr, "unhealthy:", err)
+
+		return 1
+	}
+
+	return 0
+}
+
+func healthCheck(ctx context.Context, lookupEnv func(string) (string, bool)) error {
+	ctx, cancel := context.WithTimeout(ctx, healthCheckTimeout)
+	defer cancel()
+
+	cfg, err := config.FromEnvironment(lookupEnv)
+	if err != nil {
+		return fmt.Errorf("invalid setting: %w", err)
+	}
+
+	// The settings have checked that the address has a port.
+	_, port, _ := net.SplitHostPort(cfg.ListenAddr)
+	health := "http://" + net.JoinHostPort("127.0.0.1", port) + proxy.HealthPath
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, health, http.NoBody)
+	if err != nil {
+		return fmt.Errorf("make the request: %w", err)
+	}
+
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("ask smallwebwaf: %w", err)
+	}
+
+	_ = res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		return fmt.Errorf("%w %s", errHealthEndpoint, res.Status)
+	}
+
+	conn, err := (&net.Dialer{}).DialContext(ctx, "tcp", appAddress(cfg.UpstreamURL))
+	if err != nil {
+		return fmt.Errorf("connect to the app: %w", err)
+	}
+
+	_ = conn.Close()
+
+	return nil
+}
+
+// appAddress is the host and port of the app's URL, the port being the
+// scheme's own when the URL names none.
+func appAddress(app *url.URL) string {
+	port := app.Port()
+	if port == "" {
+		port = "80"
+		if app.Scheme == "https" {
+			port = "443"
+		}
+	}
+
+	return net.JoinHostPort(app.Hostname(), port)
+}

internal/smallwebwaf/healthcheck_internal_test.go

@@ -0,0 +1,27 @@
+package smallwebwaf
+
+import (
+	"net/url"
+	"testing"
+)
+
+func TestAppAddress(t *testing.T) {
+	t.Parallel()
+
+	for app, want := range map[string]string{
+		"http://127.0.0.1:8081": "127.0.0.1:8081",
+		"http://app":            "app:80",
+		"https://app/":          "app:443",
+		"https://[::1]":         "[::1]:443",
+	} {
+		parsed, err := url.Parse(app)
+		if err != nil {
+			t.Fatalf("parse %q: %v", app, err)
+		}
+
+		got := appAddress(parsed)
+		if got != want {
+			t.Errorf("appAddress(%q) is %q, want %q", app, got, want)
+		}
+	}
+}

internal/smallwebwaf/healthcheck_test.go

@@ -0,0 +1,97 @@
+package smallwebwaf_test
+
+import (
+	"bytes"
+	"context"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/smallwebwaf/internal/smallwebwaf"
+)
+
+func TestHealthCheck(t *testing.T) {
+	t.Parallel()
+
+	app := httptest.NewServer(http.NotFoundHandler())
+	defer app.Close()
+
+	ctx, stop := context.WithCancel(t.Context())
+	defer stop()
+
+	out := &output{}
+	exited := make(chan int, 1)
+
+	go func() {
+		exited <- run(ctx, map[string]string{
+			listenAddr:  localhost + ":0",
+			upstreamURL: app.URL,
+		}, out)
+	}()
+
+	addr, _ := out.line(t, "msg", "starting")["address"].(string)
+	_, port, _ := net.SplitHostPort(addr)
+	// The container's settings: an address to listen on with an empty
+	// host part, which the health check asks at 127.0.0.1.
+	env := map[string]string{listenAddr: ":" + port, upstreamURL: app.URL}
+
+	wantHealthCheck(t, env, 0, "")
+
+	app.Close()
+	wantHealthCheck(t, env, 1, "unhealthy: connect to the app: ")
+
+	stop()
+
+	select {
+	case <-exited:
+	case <-time.After(waitLimit):
+		t.Fatal("still running after being told to stop")
+	}
+
+	wantHealthCheck(t, env, 1, "unhealthy: ask smallwebwaf: ")
+	wantHealthCheck(t, map[string]string{listenAddr: "8080"}, 1,
+		"unhealthy: invalid setting: SWWAF_LISTEN_ADDR: ")
+}
+
+func TestHealthCheckRefusesAnArgument(t *testing.T) {
+	t.Parallel()
+
+	var stderr bytes.Buffer
+
+	noSettings := func(string) (string, bool) {
+		return "", false
+	}
+
+	got := smallwebwaf.HealthCheck(t.Context(), []string{"now"}, noSettings, &stderr)
+
+	want := "smallwebwaf healthcheck: unexpected argument \"now\"\n"
+	if got != 1 || stderr.String() != want {
+		t.Errorf("health check returned %d and wrote %q, want 1 and %q",
+			got, stderr.String(), want)
+	}
+}
+
+// wantHealthCheck runs the health check with the settings in env, and
+// checks its exit status and the start of what it writes to stderr,
+// which is nothing when message is empty.
+func wantHealthCheck(t *testing.T, env map[string]string, status int, message string) {
+	t.Helper()
+
+	var stderr bytes.Buffer
+
+	got := smallwebwaf.HealthCheck(t.Context(), nil, func(name string) (string, bool) {
+		value, ok := env[name]
+
+		return value, ok
+	}, &stderr)
+
+	wrote := stderr.String()
+	if got != status || !strings.HasPrefix(wrote, message) ||
+		(message == "" && wrote != "") {
+		t.Errorf("health check returned %d and wrote %q, want %d and %q",
+			got, wrote, status, message)
+	}
+}

internal/smallwebwaf/smallwebwaf.go

@@ -37,8 +37,13 @@ type Params struct {
 }
 
 // Main runs smallwebwaf until SIGTERM or SIGINT, and returns the
-// process's exit status.
+// process's exit status. Run as `smallwebwaf healthcheck`, it is the
+// container's health check instead.
 func Main(version string) int {
+	if len(os.Args) > 1 && os.Args[1] == "healthcheck" {
+		return HealthCheck(context.Background(), os.Args[2:], os.LookupEnv, os.Stderr)
+	}
+
 	ctx, stop := signal.NotifyContext(context.Background(),
 		syscall.SIGTERM, os.Interrupt)
 	defer stop()

internal/smallwebwaf/smallwebwaf_test.go

@@ -24,8 +24,9 @@ const (
 	// testVersion is the version the tests give smallwebwaf.
 	testVersion = "test"
 	// localhost is where the tests listen.
-	localhost  = "127.0.0.1"
-	listenAddr = "SWWAF_LISTEN_ADDR"
+	localhost   = "127.0.0.1"
+	listenAddr  = "SWWAF_LISTEN_ADDR"
+	upstreamURL = "SWWAF_UPSTREAM_URL"
 )
 
 // output collects what smallwebwaf writes on stdout.
@@ -143,8 +144,8 @@ func TestServesUntilToldToStop(t *testing.T) {
 
 	go func() {
 		exited <- run(ctx, map[string]string{
-			listenAddr:           localhost + ":0",
-			"SWWAF_UPSTREAM_URL": app.URL,
+			listenAddr:  localhost + ":0",
+			upstreamURL: app.URL,
 		}, out)
 	}()
 
@@ -177,7 +178,7 @@ func wantStartingLine(t *testing.T, line map[string]any, appURL string) {
 	settings, _ := line["settings"].(map[string]any)
 	want := map[string]any{
 		listenAddr:                            localhost + ":0",
-		"SWWAF_UPSTREAM_URL":                  appURL,
+		upstreamURL:                           appURL,
 		"SWWAF_TRUSTED_PROXIES":               "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16",
 		"SWWAF_CLIENT_REQUEST_TIMEOUT":        "60s",
 		"SWWAF_CLIENT_RESPONSE_TIMEOUT":       "30m",