Move to the layout REPO_POLICIES.md gives (closes #30)

The Go module moves from backend/ to the root (go.mod, go.sum,
.golangci.yml, cmd/, internal/), the page's source to web/, and nginx's
two files to configs/. backend/ is gone: its LICENSE and .dockerignore
are deleted, and its .gitignore entries, README and scripts are folded
into the root ones. script/build builds the server binary after the
frontend; script/run and script/clean move up from backend/script/;
make test, lint, fmt and fmt-check do what the backend's did. Vite's
root is web/ and it still builds into dist/. go.mod ignores
node_modules/, whose npm packages can ship .go files. script/bootstrap
no longer installs gcc, which only the host Go tests needed.

Model: opus-5-5

internal/config/config.go

@@ -0,0 +1,238 @@
+// Package config loads application configuration from
+// environment variables, .env files, and config files.
+package config
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"math"
+	"net/netip"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	_ "github.com/joho/godotenv/autoload" // loads .env file
+	"github.com/spf13/viper"
+	"go.uber.org/fx"
+)
+
+// defaultTrustedProxies lists the networks whose forwarded
+// headers are honoured by default: IPv4 and IPv6 loopback,
+// for a reverse proxy on the same host, and the RFC1918
+// ranges. The container image does not use it:
+// bin/entrypoint.sh gives the server 127.0.0.1/32, since
+// nginx is its only client there.
+const defaultTrustedProxies = "127.0.0.1/32,::1/128," +
+	"10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+
+// Default limits on stored reports; README.md gives the reasons for
+// these values.
+const (
+	defaultReportsPerMinute = 60
+	defaultDataDirMaxBytes  = 1 << 30 // 1 GiB
+)
+
+var (
+	errNotPositive = errors.New("must be a positive whole number")
+	errNotOrigin   = errors.New(
+		"must be an origin, scheme://host with an optional port",
+	)
+	errNotPort = errors.New("must be a port number, 1 to 65535")
+	errNotBool = errors.New("must be true or false")
+	errNotIP   = errors.New("must be an IP address, or empty")
+
+	errMetricsCredentials = errors.New(
+		"METRICS_USERNAME and METRICS_PASSWORD must be set together, " +
+			"or neither",
+	)
+	errMetricsUsernameColon = errors.New(
+		"METRICS_USERNAME must not contain \":\", " +
+			"which basic auth cannot carry in a user name",
+	)
+)
+
+// Params defines the dependencies for Config.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Config holds the resolved application configuration.
+type Config struct {
+	BindAddress        string
+	CORSAllowedOrigins []string
+	DataDir            string
+	DataDirMaxBytes    int64
+	Debug              bool
+	MetricsPassword    string
+	MetricsUsername    string
+	Port               int
+	ReportsPerMinute   int
+	SentryDSN          string
+	TrustedProxies     []string
+	log                *slog.Logger
+	params             *Params
+}
+
+// New loads configuration from env, .env files, and config
+// files, returning a fully resolved Config. It fails, with an error
+// naming the setting, on a value the server cannot use, and on a
+// config file it finds but cannot read.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Config, error) {
+	log := params.Logger.Get()
+	name := params.Globals.Appname
+
+	viper.SetConfigName(name)
+	viper.SetConfigType("yaml")
+	viper.AddConfigPath("/etc/" + name)
+	viper.AddConfigPath("$HOME/.config/" + name)
+
+	viper.AutomaticEnv()
+
+	// An empty CORS_ALLOWED_ORIGINS allows no other origin.
+	viper.SetDefault("CORS_ALLOWED_ORIGINS", "")
+	viper.SetDefault("DATA_DIR", "./data/reports")
+	viper.SetDefault("DATA_DIR_MAX_BYTES", defaultDataDirMaxBytes)
+	viper.SetDefault("DEBUG", "false")
+	// An empty BIND_ADDRESS listens on every interface.
+	viper.SetDefault("BIND_ADDRESS", "")
+	viper.SetDefault("PORT", "8080")
+	viper.SetDefault("REPORTS_PER_MINUTE", defaultReportsPerMinute)
+	viper.SetDefault("SENTRY_DSN", "")
+	viper.SetDefault("METRICS_USERNAME", "")
+	viper.SetDefault("METRICS_PASSWORD", "")
+	viper.SetDefault("TRUSTED_PROXIES", defaultTrustedProxies)
+
+	err := viper.ReadInConfig()
+	if err != nil {
+		var notFound viper.ConfigFileNotFoundError
+		if !errors.As(err, &notFound) {
+			return nil, fmt.Errorf("config file %s: %w",
+				viper.ConfigFileUsed(), err)
+		}
+	}
+
+	// Read with strconv: viper's GetInt and GetBool would read a value
+	// they cannot parse as 0 or false instead of failing.
+	port, err := strconv.Atoi(viper.GetString("PORT"))
+	if err != nil || port < 1 || port > math.MaxUint16 {
+		return nil, fmt.Errorf("PORT %q: %w",
+			viper.GetString("PORT"), errNotPort)
+	}
+
+	debug, err := strconv.ParseBool(viper.GetString("DEBUG"))
+	if err != nil {
+		return nil, fmt.Errorf("DEBUG %q: %w",
+			viper.GetString("DEBUG"), errNotBool)
+	}
+
+	s := &Config{
+		BindAddress:        viper.GetString("BIND_ADDRESS"),
+		CORSAllowedOrigins: splitList(viper.GetString("CORS_ALLOWED_ORIGINS")),
+		DataDir:            viper.GetString("DATA_DIR"),
+		DataDirMaxBytes:    viper.GetInt64("DATA_DIR_MAX_BYTES"),
+		Debug:              debug,
+		MetricsPassword:    viper.GetString("METRICS_PASSWORD"),
+		MetricsUsername:    viper.GetString("METRICS_USERNAME"),
+		Port:               port,
+		ReportsPerMinute:   viper.GetInt("REPORTS_PER_MINUTE"),
+		SentryDSN:          viper.GetString("SENTRY_DSN"),
+		TrustedProxies:     splitList(viper.GetString("TRUSTED_PROXIES")),
+		log:                log,
+		params:             &params,
+	}
+
+	err = s.check()
+	if err != nil {
+		return nil, err
+	}
+
+	if s.Debug {
+		params.Logger.EnableDebugLogging()
+		s.log = params.Logger.Get()
+	}
+
+	return s, nil
+}
+
+// check fails with an error naming the first setting here whose value
+// the server cannot use. New checks PORT and DEBUG as it reads them,
+// and the middleware checks TRUSTED_PROXIES as it parses it.
+func (s *Config) check() error {
+	// viper reads a value that is not a number as 0, so this also
+	// catches a mistyped setting.
+	if s.ReportsPerMinute <= 0 {
+		return fmt.Errorf("REPORTS_PER_MINUTE %q: %w",
+			viper.GetString("REPORTS_PER_MINUTE"), errNotPositive)
+	}
+
+	if s.DataDirMaxBytes <= 0 {
+		return fmt.Errorf("DATA_DIR_MAX_BYTES %q: %w",
+			viper.GetString("DATA_DIR_MAX_BYTES"), errNotPositive)
+	}
+
+	if s.BindAddress != "" {
+		_, err := netip.ParseAddr(s.BindAddress)
+		if err != nil {
+			return fmt.Errorf("BIND_ADDRESS %q: %w", s.BindAddress, errNotIP)
+		}
+	}
+
+	// The server records and serves metrics only with both set, so
+	// one alone is a mistake that would otherwise go unnoticed.
+	if (s.MetricsUsername == "") != (s.MetricsPassword == "") {
+		return errMetricsCredentials
+	}
+
+	// Basic auth splits the credentials at the first ":", so with one
+	// in the user name every request to /metrics would get 401.
+	if strings.Contains(s.MetricsUsername, ":") {
+		return errMetricsUsernameColon
+	}
+
+	return checkOrigins(s.CORSAllowedOrigins)
+}
+
+// checkOrigins fails on the first CORS_ALLOWED_ORIGINS entry that is
+// not a plain origin, scheme://host with an optional port, as browsers
+// send it; anything more, such as a trailing "/", would match no page.
+// go-chi/cors reads a "*" anywhere in an entry as a wildcard, so no
+// entry may contain one.
+func checkOrigins(origins []string) error {
+	for _, origin := range origins {
+		u, err := url.Parse(origin)
+		if err != nil || u.Scheme == "" || u.Host == "" ||
+			strings.Contains(origin, "*") ||
+			origin != u.Scheme+"://"+u.Host {
+			return fmt.Errorf("CORS_ALLOWED_ORIGINS %q: %w",
+				origin, errNotOrigin)
+		}
+	}
+
+	return nil
+}
+
+// splitList turns a comma-separated setting into a trimmed
+// slice, dropping empty entries.
+func splitList(raw string) []string {
+	parts := strings.Split(raw, ",")
+
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		p = strings.TrimSpace(p)
+		if p != "" {
+			out = append(out, p)
+		}
+	}
+
+	return out
+}

internal/config/config_test.go

@@ -0,0 +1,147 @@
+package config_test
+
+import (
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx"
+)
+
+// requireConfigError builds the config as main does and fails the
+// test unless that fails with an error naming setting. It uses
+// fx.New, because fxtest.New fails the test itself on an error.
+func requireConfigError(t *testing.T, setting string) {
+	t.Helper()
+
+	app := fx.New(
+		fx.NopLogger,
+		fx.Provide(globals.New, logger.New, config.New),
+		fx.Invoke(func(*config.Config) {}),
+	)
+
+	err := app.Err()
+	if err == nil || !strings.Contains(err.Error(), setting) {
+		t.Fatalf("config error = %v, want one naming %s", err, setting)
+	}
+}
+
+// TestSettingsLoadAsGiven: valid values pass the checks and are used
+// as given. bin/entrypoint.sh starts the server with these
+// BIND_ADDRESS and PORT values.
+func TestSettingsLoadAsGiven(t *testing.T) {
+	t.Setenv("BIND_ADDRESS", "127.0.0.1")
+	t.Setenv("PORT", "8081")
+	t.Setenv("DEBUG", "true")
+
+	var cfg *config.Config
+
+	app := fx.New(
+		fx.NopLogger,
+		fx.Provide(globals.New, logger.New, config.New),
+		fx.Populate(&cfg),
+	)
+
+	err := app.Err()
+	if err != nil {
+		t.Fatalf("config error = %v", err)
+	}
+
+	if cfg.BindAddress != "127.0.0.1" || cfg.Port != 8081 || !cfg.Debug {
+		t.Fatalf("BindAddress, Port, Debug = %q, %d, %t; "+
+			"want \"127.0.0.1\", 8081, true",
+			cfg.BindAddress, cfg.Port, cfg.Debug)
+	}
+}
+
+// TestPortMustBeAPortNumber: viper reads a value that is not a number
+// as 0, on which the server would listen on a random port.
+func TestPortMustBeAPortNumber(t *testing.T) {
+	for _, value := range []string{"abc", "0", "65536", "8080.5"} {
+		t.Run(value, func(t *testing.T) {
+			t.Setenv("PORT", value)
+
+			requireConfigError(t, "PORT")
+		})
+	}
+}
+
+// TestDebugMustBeTrueOrFalse: viper reads any other value, such as
+// "yes", as false.
+func TestDebugMustBeTrueOrFalse(t *testing.T) {
+	t.Setenv("DEBUG", "yes")
+
+	requireConfigError(t, "DEBUG")
+}
+
+// TestBindAddressMustBeAnIPAddress: a host name would be looked up
+// only once the server starts listening, and a mistyped one would stop
+// it then with an error that does not name the setting.
+func TestBindAddressMustBeAnIPAddress(t *testing.T) {
+	t.Setenv("BIND_ADDRESS", "localhost")
+
+	requireConfigError(t, "BIND_ADDRESS")
+}
+
+// TestReportsPerMinuteMustBePositive: unchecked, zero would panic
+// when the routes are built, and a negative rate would lift the
+// limit.
+func TestReportsPerMinuteMustBePositive(t *testing.T) {
+	t.Setenv("REPORTS_PER_MINUTE", "0")
+
+	requireConfigError(t, "REPORTS_PER_MINUTE")
+}
+
+// TestDataDirMaxBytesMustBeANumber: viper reads a value that is not
+// a number, such as "1GB", as 0, which would refuse every report.
+func TestDataDirMaxBytesMustBeANumber(t *testing.T) {
+	t.Setenv("DATA_DIR_MAX_BYTES", "1GB")
+
+	requireConfigError(t, "DATA_DIR_MAX_BYTES")
+}
+
+// TestMetricsCredentialsGoTogether: with only one of the two set, the
+// server would quietly serve no metrics, so the start fails, naming
+// both.
+func TestMetricsCredentialsGoTogether(t *testing.T) {
+	for _, set := range []string{"METRICS_USERNAME", "METRICS_PASSWORD"} {
+		t.Run(set, func(t *testing.T) {
+			t.Setenv("METRICS_USERNAME", "")
+			t.Setenv("METRICS_PASSWORD", "")
+			t.Setenv(set, "prometheus")
+
+			requireConfigError(t, "METRICS_USERNAME")
+			requireConfigError(t, "METRICS_PASSWORD")
+		})
+	}
+}
+
+// TestMetricsUsernameMustNotContainColon: basic auth splits the
+// credentials at the first ":", so such a user name would get 401 on
+// every request to /metrics.
+func TestMetricsUsernameMustNotContainColon(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prom:etheus")
+	t.Setenv("METRICS_PASSWORD", "secret")
+
+	requireConfigError(t, "METRICS_USERNAME")
+}
+
+// TestCORSAllowedOriginsMustBeOrigins: "*" would let every origin in,
+// and an entry that is not a plain origin would match no page.
+func TestCORSAllowedOriginsMustBeOrigins(t *testing.T) {
+	for _, entry := range []string{
+		"*",
+		"https://*.netwatch.example",
+		"netwatch.example",
+		"https://netwatch.example/",
+	} {
+		t.Run(entry, func(t *testing.T) {
+			t.Setenv("CORS_ALLOWED_ORIGINS", entry)
+
+			requireConfigError(t, "CORS_ALLOWED_ORIGINS")
+		})
+	}
+}

internal/globals/globals.go

@@ -0,0 +1,27 @@
+// Package globals provides build-time variables injected via
+// ldflags and made available through dependency injection.
+package globals
+
+import "go.uber.org/fx"
+
+//nolint:gochecknoglobals // set from main before fx starts
+var (
+	// Appname is the application name.
+	Appname string
+	// Version is the git version tag.
+	Version string
+)
+
+// Globals holds build-time metadata for the application.
+type Globals struct {
+	Appname string
+	Version string
+}
+
+// New creates a Globals instance from package-level variables.
+func New(_ fx.Lifecycle) (*Globals, error) {
+	return &Globals{
+		Appname: Appname,
+		Version: Version,
+	}, nil
+}

internal/handlers/export_test.go

@@ -0,0 +1,10 @@
+package handlers
+
+import "log/slog"
+
+// NewForTest builds a Handlers around a report sink and logger,
+// bypassing the fx graph so handler behaviour (including the
+// storage failure path) is exercisable in unit tests.
+func NewForTest(buf reportAppender, log *slog.Logger) *Handlers {
+	return &Handlers{buf: buf, log: log}
+}

internal/handlers/handlers.go

@@ -0,0 +1,93 @@
+// Package handlers implements HTTP request handlers for the
+// netwatch-server API.
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+
+	"go.uber.org/fx"
+)
+
+const jsonContentType = "application/json; charset=utf-8"
+
+// reportAppender is the subset of the report buffer the handlers
+// depend on. Defining it here keeps the storage failure path
+// exercisable with a stub in tests.
+type reportAppender interface {
+	Append(v any) error
+}
+
+// Params defines the dependencies for Handlers.
+type Params struct {
+	fx.In
+
+	Buffer      *reportbuf.Buffer
+	Globals     *globals.Globals
+	Healthcheck *healthcheck.Healthcheck
+	Logger      *logger.Logger
+}
+
+// Handlers provides HTTP handler factories for all endpoints.
+type Handlers struct {
+	buf    reportAppender
+	hc     *healthcheck.Healthcheck
+	log    *slog.Logger
+	params *Params
+}
+
+// New creates a Handlers instance.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Handlers, error) {
+	s := new(Handlers)
+	s.buf = params.Buffer
+	s.params = &params
+	s.log = params.Logger.Get()
+	s.hc = params.Healthcheck
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+func (s *Handlers) respondJSON(
+	w http.ResponseWriter,
+	_ *http.Request,
+	data any,
+	status int,
+) {
+	w.Header().Set("Content-Type", jsonContentType)
+	w.WriteHeader(status)
+
+	if data != nil {
+		err := json.NewEncoder(w).Encode(data)
+		if err != nil {
+			s.log.Error("json encode error", "error", err)
+		}
+	}
+}
+
+// decodeJSON decodes the request body into v. The body is
+// expected to already be bounded by the body-size middleware, so
+// a caller can distinguish an over-limit body from malformed
+// JSON by testing the returned error for *http.MaxBytesError.
+func (s *Handlers) decodeJSON(
+	_ http.ResponseWriter,
+	r *http.Request,
+	v any,
+) error {
+	return json.NewDecoder(r.Body).Decode(v)
+}

internal/handlers/healthcheck.go

@@ -0,0 +1,11 @@
+package handlers
+
+import "net/http"
+
+// HandleHealthCheck returns a handler for the health check
+// endpoint.
+func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		s.respondJSON(w, r, s.hc.Healthcheck(), http.StatusOK)
+	}
+}

internal/handlers/healthcheck_test.go

@@ -0,0 +1,120 @@
+package handlers_test
+
+import (
+	"encoding/json"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx/fxtest"
+)
+
+// newStartedHandlers builds Handlers with a real health check for the
+// server named in g, and starts them, which records the time the
+// uptime counts from.
+func newStartedHandlers(t *testing.T, g *globals.Globals) *handlers.Handlers {
+	t.Helper()
+
+	lc := fxtest.NewLifecycle(t)
+
+	log, err := logger.New(lc, logger.Params{Globals: g})
+	if err != nil {
+		t.Fatalf("logger: %v", err)
+	}
+
+	hc, err := healthcheck.New(lc,
+		healthcheck.Params{Globals: g, Logger: log})
+	if err != nil {
+		t.Fatalf("health check: %v", err)
+	}
+
+	h, err := handlers.New(lc,
+		handlers.Params{Globals: g, Healthcheck: hc, Logger: log})
+	if err != nil {
+		t.Fatalf("handlers: %v", err)
+	}
+
+	lc.RequireStart()
+	t.Cleanup(lc.RequireStop)
+
+	return h
+}
+
+// TestHandleHealthCheck checks the health check's answer: 200, a JSON
+// content type, and a JSON object with exactly the fields of
+// healthcheck.HealthcheckResponse, carrying this server's name and
+// version and an uptime counted from its start.
+func TestHandleHealthCheck(t *testing.T) {
+	t.Parallel()
+
+	g := &globals.Globals{Appname: "netwatch-server", Version: "v1.2.3"}
+	h := newStartedHandlers(t, g)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/.well-known/healthcheck", http.NoBody)
+
+	h.HandleHealthCheck().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	contentType := rec.Header().Get("Content-Type")
+	if contentType != "application/json; charset=utf-8" {
+		t.Errorf("Content-Type = %q, want %q",
+			contentType, "application/json; charset=utf-8")
+	}
+
+	var body map[string]any
+
+	err := json.Unmarshal(rec.Body.Bytes(), &body)
+	if err != nil {
+		t.Fatalf("body not a JSON object: %v (%q)", err, rec.Body.String())
+	}
+
+	fields := []string{
+		"appname", "now", "status", "uptime_human", "uptime_seconds", "version",
+	}
+	if got := slices.Sorted(maps.Keys(body)); !slices.Equal(got, fields) {
+		t.Fatalf("fields = %v, want %v", got, fields)
+	}
+
+	for field, want := range map[string]string{
+		"appname": g.Appname, "status": "ok", "version": g.Version,
+	} {
+		if body[field] != want {
+			t.Errorf("%s = %v, want %q", field, body[field], want)
+		}
+	}
+
+	now, _ := body["now"].(string)
+
+	at, err := time.Parse(time.RFC3339Nano, now)
+	if err != nil || time.Since(at).Abs() > time.Minute {
+		t.Errorf("now = %q, want the current time in RFC 3339 (%v)", now, err)
+	}
+
+	// Started just now, so the uptime is well under a minute.
+	human, _ := body["uptime_human"].(string)
+
+	uptime, err := time.ParseDuration(human)
+	if err != nil || uptime > time.Minute {
+		t.Errorf("uptime_human = %q, want a duration under a minute (%v)",
+			human, err)
+	}
+
+	seconds, ok := body["uptime_seconds"].(float64)
+	if !ok || seconds < 0 || seconds > time.Minute.Seconds() {
+		t.Errorf("uptime_seconds = %v, want a number of seconds under a minute",
+			body["uptime_seconds"])
+	}
+}

internal/handlers/report.go

@@ -0,0 +1,121 @@
+package handlers
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+type reportSample struct {
+	T       int64   `json:"t"`
+	Latency *int    `json:"latency"`
+	Error   *string `json:"error"`
+}
+
+type reportHost struct {
+	History []reportSample `json:"history"`
+	Name    string         `json:"name"`
+	Status  string         `json:"status"`
+	URL     string         `json:"url"`
+}
+
+type report struct {
+	ClientID  string          `json:"clientId"`
+	Geo       json.RawMessage `json:"geo"`
+	Hosts     []reportHost    `json:"hosts"`
+	Timestamp string          `json:"timestamp"`
+}
+
+// HandleReport returns a handler that accepts telemetry
+// reports from NetWatch clients.
+func (s *Handlers) HandleReport() http.HandlerFunc {
+	type response struct {
+		Status string `json:"status"`
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		var rpt report
+
+		err := s.decodeJSON(w, r, &rpt)
+		if err != nil {
+			s.respondJSON(w, r,
+				&response{Status: "error"},
+				s.decodeErrorStatus(err),
+			)
+
+			return
+		}
+
+		s.logReportReceived(rpt)
+
+		err = s.buf.Append(rpt)
+		if err != nil {
+			s.respondJSON(w, r,
+				&response{Status: "error"},
+				s.appendErrorStatus(err),
+			)
+
+			return
+		}
+
+		s.respondJSON(w, r, &response{Status: "ok"}, http.StatusOK)
+	}
+}
+
+// decodeErrorStatus logs a report decode failure and returns the
+// status to send: 413 when the body exceeded the size limit,
+// otherwise 400 for malformed JSON.
+func (s *Handlers) decodeErrorStatus(err error) int {
+	var tooLarge *http.MaxBytesError
+	if errors.As(err, &tooLarge) {
+		s.log.Warn("report body too large", "limit_bytes", tooLarge.Limit)
+
+		return http.StatusRequestEntityTooLarge
+	}
+
+	// The decoder's error text can quote request bytes (a whole
+	// oversized number, for example), so it is bounded too.
+	s.log.Error("failed to decode report",
+		"error", logger.BoundedForLog(err.Error()),
+	)
+
+	return http.StatusBadRequest
+}
+
+// appendErrorStatus logs a failure to store a report and returns
+// the status to send: 507 when the reports waiting to be written fill
+// the size cap, otherwise 500.
+func (s *Handlers) appendErrorStatus(err error) int {
+	if errors.Is(err, reportbuf.ErrFull) {
+		s.log.Warn("report refused: " +
+			"reports waiting to be written fill the size cap")
+
+		return http.StatusInsufficientStorage
+	}
+
+	s.log.Error("failed to buffer report", "error", err)
+
+	return http.StatusInternalServerError
+}
+
+// logReportReceived logs an accepted report. Untrusted fields are
+// bounded (client_id, timestamp) or reduced to a length
+// (geo_bytes) so the raw attacker-controlled body never reaches
+// the log.
+func (s *Handlers) logReportReceived(rpt report) {
+	totalSamples := 0
+	for _, h := range rpt.Hosts {
+		totalSamples += len(h.History)
+	}
+
+	s.log.Info("report received",
+		"client_id", logger.BoundedForLog(rpt.ClientID),
+		"timestamp", logger.BoundedForLog(rpt.Timestamp),
+		"host_count", len(rpt.Hosts),
+		"total_samples", totalSamples,
+		"geo_bytes", len(rpt.Geo),
+	)
+}

internal/handlers/report_test.go

@@ -0,0 +1,297 @@
+package handlers_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+var errStorageFailed = errors.New("storage failed")
+
+// stubAppender drives the storage success/failure path without a
+// real buffer or disk.
+type stubAppender struct {
+	err error
+}
+
+func (s stubAppender) Append(any) error { return s.err }
+
+func newTestHandlers(buf stubAppender, out io.Writer) *handlers.Handlers {
+	return handlers.NewForTest(buf, slog.New(slog.NewJSONHandler(out, nil)))
+}
+
+func decodeStatus(t *testing.T, body []byte) string {
+	t.Helper()
+
+	var resp struct {
+		Status string `json:"status"`
+	}
+
+	err := json.Unmarshal(body, &resp)
+	if err != nil {
+		t.Fatalf("response body not JSON: %v (%q)", err, body)
+	}
+
+	return resp.Status
+}
+
+// TestHandleReportAcceptsValidReports checks the answer to a valid
+// report, one with no hosts and one shaped as the frontend sends them:
+// 200 and {"status":"ok"} as JSON.
+func TestHandleReportAcceptsValidReports(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		body string
+	}{
+		{
+			name: "no hosts",
+			body: `{"clientId":"c1","geo":null,"hosts":[],` +
+				`"timestamp":"2026-10-03T12:00:00.000Z"}`,
+		},
+		{
+			name: "a host with a latency and an error sample",
+			body: `{"clientId":"c1","geo":null,"hosts":[{` +
+				`"name":"Example","url":"https://example.com/",` +
+				`"status":"error","history":[` +
+				`{"t":1790000000000,"latency":42,"error":null},` +
+				`{"t":1790000003000,"latency":null,"error":"timeout"}]}],` +
+				`"timestamp":"2026-10-03T12:00:00.000Z"}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			h := newTestHandlers(stubAppender{}, io.Discard)
+
+			rec := httptest.NewRecorder()
+			req := httptest.NewRequestWithContext(t.Context(),
+				http.MethodPost, "/api/v1/reports",
+				strings.NewReader(tt.body),
+			)
+
+			h.HandleReport().ServeHTTP(rec, req)
+
+			if rec.Code != http.StatusOK {
+				t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+			}
+
+			contentType := rec.Header().Get("Content-Type")
+			if contentType != "application/json; charset=utf-8" {
+				t.Errorf("Content-Type = %q, want %q",
+					contentType, "application/json; charset=utf-8")
+			}
+
+			if got := rec.Body.String(); got != "{\"status\":\"ok\"}\n" {
+				t.Errorf("body = %q, want %q", got, "{\"status\":\"ok\"}\n")
+			}
+		})
+	}
+}
+
+func TestHandleReportStorageFailureIsNon2xx(t *testing.T) {
+	t.Parallel()
+
+	h := newTestHandlers(stubAppender{err: errStorageFailed}, io.Discard)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{"clientId":"c1","hosts":[]}`),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	if rec.Code < 500 {
+		t.Fatalf("storage failure status = %d, want a 5xx", rec.Code)
+	}
+
+	if got := decodeStatus(t, rec.Body.Bytes()); got != "error" {
+		t.Fatalf("status field = %q, want %q", got, "error")
+	}
+}
+
+// TestHandleReportFullIs507 checks the answer when the reports waiting
+// to be written fill the size cap: 507 and the usual error body, which
+// tells the client nothing more.
+func TestHandleReportFullIs507(t *testing.T) {
+	t.Parallel()
+
+	h := newTestHandlers(stubAppender{err: reportbuf.ErrFull}, io.Discard)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{"clientId":"c1","hosts":[]}`),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInsufficientStorage {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusInsufficientStorage)
+	}
+
+	if got := rec.Body.String(); got != "{\"status\":\"error\"}\n" {
+		t.Errorf("body = %q, want %q", got, "{\"status\":\"error\"}\n")
+	}
+}
+
+func TestHandleReportMalformedJSONIs400(t *testing.T) {
+	t.Parallel()
+
+	h := newTestHandlers(stubAppender{}, io.Discard)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{not json`),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("malformed status = %d, want %d",
+			rec.Code, http.StatusBadRequest)
+	}
+}
+
+func TestHandleReportOversizeIs413(t *testing.T) {
+	t.Parallel()
+
+	const limit = 32
+
+	h := newTestHandlers(stubAppender{}, io.Discard)
+	handler := (&middleware.Middleware{}).MaxBodyBytes(limit)(
+		h.HandleReport(),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{"clientId":"`+strings.Repeat("x", 200)+`"}`),
+	)
+	// No declared length, so only the middleware's read cap can
+	// stop this body.
+	req.ContentLength = -1
+
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Fatalf("oversize status = %d, want %d",
+			rec.Code, http.StatusRequestEntityTooLarge)
+	}
+}
+
+func TestHandleReportDoesNotLogRawGeo(t *testing.T) {
+	t.Parallel()
+
+	const sentinel = "SENSITIVE-GEO-BLOB"
+
+	var logbuf bytes.Buffer
+
+	h := newTestHandlers(stubAppender{}, &logbuf)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(
+			`{"clientId":"c1","geo":{"raw":"`+sentinel+`"},"hosts":[]}`,
+		),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	if strings.Contains(logbuf.String(), sentinel) {
+		t.Fatal("raw geo bytes were written to the log")
+	}
+
+	if !strings.Contains(logbuf.String(), "geo_bytes") {
+		t.Fatal("expected a bounded geo_bytes field in the log")
+	}
+}
+
+func TestHandleReportLogsClientIDCutToBound(t *testing.T) {
+	t.Parallel()
+
+	long := strings.Repeat("c", 2*logger.MaxLoggedFieldBytes)
+
+	var logbuf bytes.Buffer
+
+	h := newTestHandlers(stubAppender{}, &logbuf)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(
+			`{"clientId":"`+long+`","timestamp":"`+long+`","hosts":[]}`,
+		),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	var logged map[string]any
+
+	err := json.Unmarshal(logbuf.Bytes(), &logged)
+	if err != nil {
+		t.Fatalf("log line not JSON: %v (%q)", err, logbuf.String())
+	}
+
+	want := long[:logger.MaxLoggedFieldBytes]
+
+	if logged["client_id"] != want {
+		t.Fatalf("logged client_id not cut to %d bytes: %q",
+			logger.MaxLoggedFieldBytes, logged["client_id"])
+	}
+
+	if logged["timestamp"] != want {
+		t.Fatalf("logged timestamp not cut to %d bytes: %q",
+			logger.MaxLoggedFieldBytes, logged["timestamp"])
+	}
+}
+
+func TestHandleReportDecodeErrorLogIsBounded(t *testing.T) {
+	t.Parallel()
+
+	// A number too large for its int64 field makes the decoder's
+	// error text quote the whole number.
+	huge := strings.Repeat("9", 2*logger.MaxLoggedFieldBytes)
+
+	var logbuf bytes.Buffer
+
+	h := newTestHandlers(stubAppender{}, &logbuf)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{"hosts":[{"history":[{"t":`+huge+`}]}]}`),
+	)
+
+	h.HandleReport().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+
+	if strings.Contains(logbuf.String(), huge) {
+		t.Fatal("the whole oversized number was written to the log")
+	}
+}

internal/healthcheck/healthcheck.go

@@ -0,0 +1,85 @@
+// Package healthcheck provides a service that reports
+// application health, uptime, and version information.
+package healthcheck
+
+import (
+	"context"
+	"log/slog"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Healthcheck.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Healthcheck tracks startup time and builds health responses.
+type Healthcheck struct {
+	StartupTime time.Time
+	log         *slog.Logger
+	params      *Params
+}
+
+// HealthcheckResponse is the JSON payload returned by the health
+// check endpoint. Its name and its snake_case keys are the ones
+// GO_HTTP_SERVER_CONVENTIONS.md gives.
+//
+//nolint:revive,tagliatelle // name and keys from the conventions
+type HealthcheckResponse struct {
+	Appname       string `json:"appname"`
+	Now           string `json:"now"`
+	Status        string `json:"status"`
+	UptimeHuman   string `json:"uptime_human"`
+	UptimeSeconds int64  `json:"uptime_seconds"`
+	Version       string `json:"version"`
+}
+
+// New creates a Healthcheck, recording startup time via an
+// fx lifecycle hook.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Healthcheck, error) {
+	s := new(Healthcheck)
+	s.params = &params
+	s.log = params.Logger.Get()
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			s.StartupTime = time.Now().UTC()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+// Healthcheck returns the current health status of the application.
+func (s *Healthcheck) Healthcheck() *HealthcheckResponse {
+	return &HealthcheckResponse{
+		Appname:       s.params.Globals.Appname,
+		Now:           time.Now().UTC().Format(time.RFC3339Nano),
+		Status:        "ok",
+		UptimeHuman:   s.uptime().String(),
+		UptimeSeconds: int64(s.uptime().Seconds()),
+		Version:       s.params.Globals.Version,
+	}
+}
+
+func (s *Healthcheck) uptime() time.Duration {
+	return time.Since(s.StartupTime)
+}

internal/logger/logger.go

@@ -0,0 +1,101 @@
+// Package logger provides a configured slog.Logger with TTY
+// detection for development vs production output.
+package logger
+
+import (
+	"log/slog"
+	"os"
+	"runtime"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+
+	"go.uber.org/fx"
+)
+
+// MaxLoggedFieldBytes bounds untrusted text (request fields,
+// header values, decode error text) before it is logged, so a
+// caller cannot inflate log volume with an oversized value.
+const MaxLoggedFieldBytes = 128
+
+// BoundedForLog truncates an untrusted string to a fixed byte
+// bound so an attacker-controlled field cannot dominate the log.
+func BoundedForLog(s string) string {
+	if len(s) > MaxLoggedFieldBytes {
+		return s[:MaxLoggedFieldBytes]
+	}
+
+	return s
+}
+
+// Params defines the dependencies for Logger.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+}
+
+// Logger wraps slog.Logger with dynamic level control.
+type Logger struct {
+	log    *slog.Logger
+	level  *slog.LevelVar
+	params Params
+}
+
+// New creates a Logger with TTY-aware output formatting.
+func New(_ fx.Lifecycle, params Params) (*Logger, error) {
+	l := new(Logger)
+	l.level = new(slog.LevelVar)
+	l.level.Set(slog.LevelInfo)
+	l.params = params
+
+	tty := false
+
+	if fileInfo, _ := os.Stdout.Stat(); fileInfo != nil {
+		if (fileInfo.Mode() & os.ModeCharDevice) != 0 {
+			tty = true
+		}
+	}
+
+	var handler slog.Handler
+	if tty {
+		handler = slog.NewTextHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	} else {
+		handler = slog.NewJSONHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	}
+
+	l.log = slog.New(handler)
+
+	return l, nil
+}
+
+// EnableDebugLogging sets the log level to debug.
+func (l *Logger) EnableDebugLogging() {
+	l.level.Set(slog.LevelDebug)
+	l.log.Debug("debug logging enabled", "debug", true)
+}
+
+// Get returns the underlying slog.Logger.
+func (l *Logger) Get() *slog.Logger {
+	return l.log
+}
+
+// Identify logs the application's build-time metadata.
+func (l *Logger) Identify() {
+	l.log.Info("starting",
+		"appname", l.params.Globals.Appname,
+		"version", l.params.Globals.Version,
+		"arch", runtime.GOARCH,
+	)
+}

internal/middleware/export_test.go

@@ -0,0 +1,31 @@
+package middleware
+
+import (
+	"log/slog"
+	"net/http"
+	"net/netip"
+)
+
+// Test-only wrappers exposing unexported helpers to the
+// external middleware_test package.
+
+// NewWithLogger builds a Middleware around a logger for tests
+// that exercise the logging paths without the fx graph.
+func NewWithLogger(log *slog.Logger) *Middleware {
+	return &Middleware{log: log}
+}
+
+// NewWithTrustedProxies builds a Middleware that honours forwarded
+// headers from the given networks, for tests of the client address
+// paths without the fx graph.
+func NewWithTrustedProxies(trusted []netip.Prefix) *Middleware {
+	return &Middleware{trustedProxies: trusted}
+}
+
+func ClientIP(
+	remoteAddr string,
+	header http.Header,
+	trusted []netip.Prefix,
+) string {
+	return clientIP(remoteAddr, header, trusted)
+}

internal/middleware/middleware.go

@@ -0,0 +1,393 @@
+// Package middleware provides HTTP middleware for logging,
+// CORS, and other cross-cutting concerns.
+package middleware
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"net"
+	"net/http"
+	"net/netip"
+	"runtime/debug"
+	"strings"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	basicauth "github.com/99designs/basicauth-go"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/cors"
+	"github.com/go-chi/httprate"
+	"github.com/prometheus/client_golang/prometheus"
+	metrics "github.com/slok/go-http-metrics/metrics/prometheus"
+	ghmm "github.com/slok/go-http-metrics/middleware"
+	"github.com/slok/go-http-metrics/middleware/std"
+	"go.uber.org/fx"
+)
+
+const corsMaxAgeSec = 300
+
+// jsonErrorBody is the body written for errors raised inside
+// middleware, matching the {"status":"error"} shape the handlers
+// return so clients see one error contract across the API.
+const (
+	jsonContentType = "application/json; charset=utf-8"
+	jsonErrorBody   = "{\"status\":\"error\"}\n"
+)
+
+// Security header values. The backend is a JSON API with no
+// HTML surface, so the CSP forbids every resource type and
+// framing outright.
+const (
+	hstsValue              = "max-age=31536000; includeSubDomains"
+	cspValue               = "default-src 'none'; frame-ancestors 'none'"
+	permissionsPolicyValue = "camera=(), microphone=(), geolocation=()"
+)
+
+// Params defines the dependencies for Middleware.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Middleware holds shared state for middleware factories.
+type Middleware struct {
+	log            *slog.Logger
+	params         *Params
+	trustedProxies []netip.Prefix
+}
+
+// New creates a Middleware instance.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Middleware, error) {
+	trusted, err := ParseTrustedProxies(params.Config.TrustedProxies)
+	if err != nil {
+		return nil, err
+	}
+
+	s := new(Middleware)
+	s.params = &params
+	s.log = params.Logger.Get()
+	s.trustedProxies = trusted
+
+	return s, nil
+}
+
+// ParseTrustedProxies converts the TRUSTED_PROXIES entries into
+// prefixes, failing fast on any malformed entry. Each entry must be
+// a CIDR; a lone address is refused. "netwatch-server check-cidr"
+// runs it too.
+func ParseTrustedProxies(cidrs []string) ([]netip.Prefix, error) {
+	prefixes := make([]netip.Prefix, 0, len(cidrs))
+
+	for _, cidr := range cidrs {
+		prefix, err := netip.ParsePrefix(cidr)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"TRUSTED_PROXIES %q: %w", cidr, err,
+			)
+		}
+
+		prefixes = append(prefixes, prefix.Masked())
+	}
+
+	return prefixes, nil
+}
+
+type loggingResponseWriter struct {
+	http.ResponseWriter
+
+	statusCode int
+}
+
+func newLoggingResponseWriter(
+	w http.ResponseWriter,
+) *loggingResponseWriter {
+	return &loggingResponseWriter{w, http.StatusOK}
+}
+
+func (lrw *loggingResponseWriter) WriteHeader(code int) {
+	lrw.statusCode = code
+	lrw.ResponseWriter.WriteHeader(code)
+}
+
+func ipFromHostPort(hostPort string) string {
+	host, _, err := net.SplitHostPort(hostPort)
+	if err != nil {
+		return hostPort
+	}
+
+	return host
+}
+
+// clientIP resolves the caller's address. X-Forwarded-For and
+// X-Real-IP are honoured only when the direct peer is a
+// trusted proxy; otherwise the direct peer is returned so a
+// spoofed header cannot forge the logged address.
+func clientIP(
+	remoteAddr string,
+	header http.Header,
+	trusted []netip.Prefix,
+) string {
+	peer := ipFromHostPort(remoteAddr)
+
+	if !addrInAny(peer, trusted) {
+		return peer
+	}
+
+	if xff := firstForwardedFor(header.Get("X-Forwarded-For")); xff != "" {
+		return xff
+	}
+
+	if xr := strings.TrimSpace(header.Get("X-Real-IP")); validIP(xr) {
+		return xr
+	}
+
+	return peer
+}
+
+// firstForwardedFor returns the left-most valid address in an
+// X-Forwarded-For list (the original client), or "" if none.
+func firstForwardedFor(value string) string {
+	for part := range strings.SplitSeq(value, ",") {
+		candidate := strings.TrimSpace(part)
+		if validIP(candidate) {
+			return candidate
+		}
+	}
+
+	return ""
+}
+
+func validIP(s string) bool {
+	_, err := netip.ParseAddr(s)
+
+	return err == nil
+}
+
+// addrInAny reports whether s parses as an address contained
+// in any of the trusted prefixes.
+func addrInAny(s string, trusted []netip.Prefix) bool {
+	addr, err := netip.ParseAddr(s)
+	if err != nil {
+		return false
+	}
+
+	addr = addr.Unmap()
+
+	for _, prefix := range trusted {
+		if prefix.Contains(addr) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// Logging returns middleware that logs each request with
+// timing, status code, and client information. Every string
+// taken from the request is cut to logger.MaxLoggedFieldBytes,
+// including the request ID, which chi takes from the client's
+// X-Request-Id header when one is sent.
+func (s *Middleware) Logging() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				start := time.Now().UTC()
+				lrw := newLoggingResponseWriter(w)
+				ctx := r.Context()
+
+				defer func() {
+					latency := time.Since(start)
+					s.log.InfoContext(ctx, "request",
+						"request_start", start,
+						"method", logger.BoundedForLog(r.Method),
+						"url", logger.BoundedForLog(r.URL.String()),
+						"useragent", logger.BoundedForLog(r.UserAgent()),
+						"request_id",
+						logger.BoundedForLog(middleware.GetReqID(ctx)),
+						"referer", logger.BoundedForLog(r.Referer()),
+						"proto", logger.BoundedForLog(r.Proto),
+						"remote_ip",
+						logger.BoundedForLog(clientIP(
+							r.RemoteAddr,
+							r.Header,
+							s.trustedProxies,
+						)),
+						"status", lrw.statusCode,
+						"latency_ms",
+						latency.Milliseconds(),
+					)
+				}()
+
+				next.ServeHTTP(lrw, r)
+			},
+		)
+	}
+}
+
+// SecurityHeaders returns middleware that sets response
+// security headers. It runs before CORS so the headers are
+// present on preflight responses the CORS handler writes.
+func (s *Middleware) SecurityHeaders() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				h := w.Header()
+				h.Set("Strict-Transport-Security", hstsValue)
+				h.Set("Content-Security-Policy", cspValue)
+				h.Set("X-Frame-Options", "DENY")
+				h.Set("X-Content-Type-Options", "nosniff")
+				h.Set("Referrer-Policy", "no-referrer")
+				h.Set("Permissions-Policy", permissionsPolicyValue)
+
+				next.ServeHTTP(w, r)
+			},
+		)
+	}
+}
+
+// writeJSONError writes the shared JSON error body with the
+// given status. Used where middleware must reject a request
+// before it reaches a handler.
+func writeJSONError(w http.ResponseWriter, status int) {
+	w.Header().Set("Content-Type", jsonContentType)
+	w.WriteHeader(status)
+	_, _ = io.WriteString(w, jsonErrorBody)
+}
+
+// MaxBodyBytes returns middleware that caps the request body at
+// limit bytes. A declared Content-Length over the limit is
+// rejected immediately with 413. Bodies without a declared
+// length (or that understate it) are capped as they are read, so
+// a handler that reads the body sees a *http.MaxBytesError it can
+// map to 413. Mounted again on a route group, it can only lower
+// the limit: a cap applied earlier in the chain still holds.
+func (s *Middleware) MaxBodyBytes(
+	limit int64,
+) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				if r.ContentLength > limit {
+					writeJSONError(
+						w,
+						http.StatusRequestEntityTooLarge,
+					)
+
+					return
+				}
+
+				r.Body = http.MaxBytesReader(w, r.Body, limit)
+
+				next.ServeHTTP(w, r)
+			},
+		)
+	}
+}
+
+// Recoverer returns middleware that recovers from a panic in a
+// downstream handler, logs the panic and stack trace through
+// slog, and responds 500 with no body. http.ErrAbortHandler is
+// re-panicked so the server can abort the response as intended.
+func (s *Middleware) Recoverer() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				defer func() {
+					rec := recover()
+					if rec == nil {
+						return
+					}
+
+					err, ok := rec.(error)
+					if ok && errors.Is(err, http.ErrAbortHandler) {
+						panic(rec)
+					}
+
+					s.log.ErrorContext(r.Context(),
+						"panic recovered",
+						"panic", fmt.Sprintf("%v", rec),
+						"stack", string(debug.Stack()),
+					)
+
+					w.WriteHeader(http.StatusInternalServerError)
+				}()
+
+				next.ServeHTTP(w, r)
+			},
+		)
+	}
+}
+
+// CORS returns middleware that lets pages served from the given
+// origins call the API. With no origins it adds no CORS headers at
+// all, so only same-origin pages can use the API. That case must not
+// reach cors.Handler, which treats an empty origin list as "allow
+// every origin".
+func (s *Middleware) CORS(
+	origins []string,
+) func(http.Handler) http.Handler {
+	if len(origins) == 0 {
+		return func(next http.Handler) http.Handler { return next }
+	}
+
+	return cors.Handler(cors.Options{
+		AllowedOrigins:   origins,
+		AllowedMethods:   []string{http.MethodGet, http.MethodPost},
+		AllowedHeaders:   []string{"Content-Type"},
+		AllowCredentials: false,
+		MaxAge:           corsMaxAgeSec,
+	})
+}
+
+// RateLimit returns middleware that allows each client address
+// perMinute requests a minute and answers the rest with 429, the
+// Retry-After header httprate sets, and the usual error body. The
+// address is the one clientIP resolves, so clients behind the reverse
+// proxy are limited one by one, not together as the proxy.
+func (s *Middleware) RateLimit(
+	perMinute int,
+) func(http.Handler) http.Handler {
+	return httprate.LimitBy(perMinute, time.Minute,
+		func(r *http.Request) (string, error) {
+			return clientIP(r.RemoteAddr, r.Header, s.trustedProxies), nil
+		},
+		httprate.WithLimitHandler(
+			func(w http.ResponseWriter, _ *http.Request) {
+				writeJSONError(w, http.StatusTooManyRequests)
+			},
+		),
+	)
+}
+
+// Metrics returns middleware that records each request's duration and
+// response size, and the requests in progress, in registry. They are
+// labelled by the request path.
+func (s *Middleware) Metrics(
+	registry prometheus.Registerer,
+) func(http.Handler) http.Handler {
+	mdlw := ghmm.New(ghmm.Config{
+		Recorder: metrics.NewRecorder(metrics.Config{Registry: registry}),
+	})
+
+	return std.HandlerProvider("", mdlw)
+}
+
+// MetricsAuth returns middleware that lets a request through only with
+// METRICS_USERNAME and METRICS_PASSWORD as its basic auth credentials,
+// and answers any other with 401.
+func (s *Middleware) MetricsAuth() func(http.Handler) http.Handler {
+	return basicauth.New("metrics", map[string][]string{
+		s.params.Config.MetricsUsername: {s.params.Config.MetricsPassword},
+	})
+}

internal/middleware/middleware_test.go

@@ -0,0 +1,571 @@
+package middleware_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strings"
+	"testing"
+	"testing/synctest"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+
+	chimiddleware "github.com/go-chi/chi/v5/middleware"
+)
+
+const (
+	// loopbackPeer is a remote address inside the trusted-proxy allowlist.
+	loopbackPeer = "127.0.0.1:5000"
+	// forwardedIP is the client address presented via X-Forwarded-For.
+	forwardedIP = "203.0.113.7"
+	// realIP is the client address presented via X-Real-IP.
+	realIP = "203.0.113.9"
+)
+
+func mustPrefixes(t *testing.T, cidrs ...string) []netip.Prefix {
+	t.Helper()
+
+	prefixes, err := middleware.ParseTrustedProxies(cidrs)
+	if err != nil {
+		t.Fatalf("ParseTrustedProxies(%v): %v", cidrs, err)
+	}
+
+	return prefixes
+}
+
+// TestParseTrustedProxiesRejectsMalformed includes entries nginx would
+// read as another address or look up as a hostname, in the CIDR form
+// bin/entrypoint.sh gives "netwatch-server check-cidr".
+func TestParseTrustedProxiesRejectsMalformed(t *testing.T) {
+	t.Parallel()
+
+	for _, cidr := range []string{
+		"not-a-cidr", "10.0.0.1", "1.2.3/32", "172.30/32", "10/32",
+		"cafe/32", "999.1.1.1/32", "10.0.0.0/33", "::1/129",
+		"fe80::1%eth0/128",
+	} {
+		_, err := middleware.ParseTrustedProxies([]string{cidr})
+		if err == nil || !strings.Contains(err.Error(), "TRUSTED_PROXIES") {
+			t.Errorf("%q: error = %v, want one naming TRUSTED_PROXIES",
+				cidr, err)
+		}
+	}
+}
+
+func TestParseTrustedProxiesAcceptsCIDRs(t *testing.T) {
+	t.Parallel()
+
+	mustPrefixes(t, "172.17.0.1/32", "10.0.0.0/8", "2001:db8::1/128",
+		"2001:db8::/32", "::ffff:192.0.2.1/128")
+}
+
+type clientIPCase struct {
+	name       string
+	remoteAddr string
+	xff        string
+	xRealIP    string
+	want       string
+}
+
+func clientIPCases() []clientIPCase {
+	return []clientIPCase{
+		{
+			name:       "trusted proxy uses forwarded-for",
+			remoteAddr: loopbackPeer,
+			xff:        forwardedIP,
+			want:       forwardedIP,
+		},
+		{
+			name:       "trusted proxy uses left-most of chain",
+			remoteAddr: "10.1.2.3:5000",
+			xff:        forwardedIP + ", 10.1.2.3",
+			want:       forwardedIP,
+		},
+		{
+			name:       "trusted proxy falls back to x-real-ip",
+			remoteAddr: loopbackPeer,
+			xRealIP:    realIP,
+			want:       realIP,
+		},
+		{
+			name:       "untrusted peer ignores forwarded-for",
+			remoteAddr: "198.51.100.4:5000",
+			xff:        forwardedIP,
+			want:       "198.51.100.4",
+		},
+		{
+			name:       "untrusted peer ignores x-real-ip",
+			remoteAddr: "198.51.100.4:5000",
+			xRealIP:    realIP,
+			want:       "198.51.100.4",
+		},
+		{
+			name:       "trusted proxy with no headers uses peer",
+			remoteAddr: "10.1.2.3:5000",
+			want:       "10.1.2.3",
+		},
+		{
+			name:       "trusted proxy with garbage header uses peer",
+			remoteAddr: loopbackPeer,
+			xff:        "not-an-ip",
+			want:       "127.0.0.1",
+		},
+	}
+}
+
+func TestClientIP(t *testing.T) {
+	t.Parallel()
+
+	trusted := mustPrefixes(t, "127.0.0.1/32", "::1/128", "10.0.0.0/8")
+
+	for _, tc := range clientIPCases() {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			header := http.Header{}
+			if tc.xff != "" {
+				header.Set("X-Forwarded-For", tc.xff)
+			}
+
+			if tc.xRealIP != "" {
+				header.Set("X-Real-IP", tc.xRealIP)
+			}
+
+			got := middleware.ClientIP(tc.remoteAddr, header, trusted)
+			if got != tc.want {
+				t.Errorf("ClientIP() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestSecurityHeaders(t *testing.T) {
+	t.Parallel()
+
+	handler := (&middleware.Middleware{}).SecurityHeaders()(
+		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", http.NoBody)
+	handler.ServeHTTP(rec, req)
+
+	want := map[string]string{
+		"Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+		"Content-Security-Policy":   "default-src 'none'; frame-ancestors 'none'",
+		"X-Frame-Options":           "DENY",
+		"X-Content-Type-Options":    "nosniff",
+		"Referrer-Policy":           "no-referrer",
+		"Permissions-Policy":        "camera=(), microphone=(), geolocation=()",
+	}
+
+	for name, value := range want {
+		if got := rec.Header().Get(name); got != value {
+			t.Errorf("header %s = %q, want %q", name, got, value)
+		}
+	}
+}
+
+// TestMaxBodyBytesRejectsOversizeOnNonReadingRoute confirms the
+// limit is enforced even for a handler that never reads the body
+// (for example the health check), via the Content-Length check.
+func TestMaxBodyBytesRejectsOversizeOnNonReadingRoute(t *testing.T) {
+	t.Parallel()
+
+	const limit = 16
+
+	called := false
+	handler := (&middleware.Middleware{}).MaxBodyBytes(limit)(
+		http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+			called = true
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/.well-known/healthcheck",
+		strings.NewReader(strings.Repeat("x", limit+1)),
+	)
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusRequestEntityTooLarge)
+	}
+
+	if called {
+		t.Fatal("handler ran despite oversize body")
+	}
+
+	if got := rec.Body.String(); got != "{\"status\":\"error\"}\n" {
+		t.Errorf("body = %q, want %q", got, "{\"status\":\"error\"}\n")
+	}
+
+	got := rec.Header().Get("Content-Type")
+	if got != "application/json; charset=utf-8" {
+		t.Errorf("Content-Type = %q, want a JSON content type", got)
+	}
+}
+
+func TestMaxBodyBytesAllowsWithinLimit(t *testing.T) {
+	t.Parallel()
+
+	const limit = 64
+
+	handler := (&middleware.Middleware{}).MaxBodyBytes(limit)(
+		http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports",
+		strings.NewReader(`{"clientId":"c1"}`),
+	)
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestRecovererReturns500AndLogsThroughSlog(t *testing.T) {
+	t.Parallel()
+
+	var logbuf bytes.Buffer
+
+	mw := middleware.NewWithLogger(
+		slog.New(slog.NewJSONHandler(&logbuf, nil)),
+	)
+
+	handler := mw.Recoverer()(
+		http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+			panic("boom")
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", http.NoBody)
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusInternalServerError)
+	}
+
+	var record map[string]any
+
+	err := json.Unmarshal(logbuf.Bytes(), &record)
+	if err != nil {
+		t.Fatalf("panic log is not one JSON record: %v (%q)", err, logbuf.String())
+	}
+
+	if record["msg"] != "panic recovered" || record["level"] != "ERROR" {
+		t.Errorf("log record = %v, want msg %q at level ERROR",
+			record, "panic recovered")
+	}
+
+	if record["panic"] != "boom" {
+		t.Errorf("panic field = %v, want %q", record["panic"], "boom")
+	}
+
+	stack, _ := record["stack"].(string)
+	if !strings.HasPrefix(stack, "goroutine ") {
+		t.Errorf("stack field = %q, want a stack trace", stack)
+	}
+}
+
+// TestRecovererRepanicsOnAbortHandler checks that a handler aborting
+// with http.ErrAbortHandler is not treated as a crash: Recoverer
+// panics again so the server aborts the response, and logs nothing.
+func TestRecovererRepanicsOnAbortHandler(t *testing.T) {
+	t.Parallel()
+
+	var logbuf bytes.Buffer
+
+	mw := middleware.NewWithLogger(
+		slog.New(slog.NewJSONHandler(&logbuf, nil)),
+	)
+
+	handler := mw.Recoverer()(
+		http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {
+			panic(http.ErrAbortHandler)
+		}),
+	)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", http.NoBody)
+
+	var recovered any
+
+	func() {
+		defer func() { recovered = recover() }()
+
+		handler.ServeHTTP(rec, req)
+	}()
+
+	err, _ := recovered.(error)
+	if !errors.Is(err, http.ErrAbortHandler) {
+		t.Errorf("Recoverer panicked with %v, want http.ErrAbortHandler", recovered)
+	}
+
+	if logbuf.Len() != 0 {
+		t.Errorf("abort was logged: %q", logbuf.String())
+	}
+}
+
+// TestLoggingCutsRequestStringsToBound sends an over-long URL and
+// over-long header values, and checks the request log writes each
+// one cut to logger.MaxLoggedFieldBytes.
+func TestLoggingCutsRequestStringsToBound(t *testing.T) {
+	t.Parallel()
+
+	long := strings.Repeat("a", 2*logger.MaxLoggedFieldBytes)
+
+	var logbuf bytes.Buffer
+
+	mw := middleware.NewWithLogger(
+		slog.New(slog.NewJSONHandler(&logbuf, nil)),
+	)
+
+	handler := chimiddleware.RequestID(mw.Logging()(okHandler()))
+
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/"+long, http.NoBody)
+	req.Header.Set("User-Agent", long)
+	req.Header.Set("Referer", long)
+	req.Header.Set("X-Request-ID", long)
+
+	handler.ServeHTTP(httptest.NewRecorder(), req)
+
+	var logged map[string]any
+
+	err := json.Unmarshal(logbuf.Bytes(), &logged)
+	if err != nil {
+		t.Fatalf("log line not JSON: %v (%q)", err, logbuf.String())
+	}
+
+	want := map[string]string{
+		"url":        ("/" + long)[:logger.MaxLoggedFieldBytes],
+		"useragent":  long[:logger.MaxLoggedFieldBytes],
+		"referer":    long[:logger.MaxLoggedFieldBytes],
+		"request_id": long[:logger.MaxLoggedFieldBytes],
+	}
+
+	for field, value := range want {
+		if logged[field] != value {
+			t.Errorf("logged %s = %q, want it cut to %d bytes",
+				field, logged[field], logger.MaxLoggedFieldBytes)
+		}
+	}
+}
+
+// okHandler stands in for the route a middleware guards.
+func okHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+}
+
+// TestRateLimitRefusesPastAllowanceThenResets checks one client
+// address: it may use its whole allowance at once, the next request
+// is refused with 429, and later it may send again.
+func TestRateLimitRefusesPastAllowanceThenResets(t *testing.T) {
+	t.Parallel()
+
+	// synctest runs this on a fake clock: time.Sleep returns at once,
+	// with the clock moved on.
+	synctest.Test(t, func(t *testing.T) {
+		const perMinute = 2
+
+		handler := (&middleware.Middleware{}).RateLimit(perMinute)(okHandler())
+
+		post := func() *httptest.ResponseRecorder {
+			rec := httptest.NewRecorder()
+			req := httptest.NewRequestWithContext(t.Context(),
+				http.MethodPost, "/api/v1/reports", http.NoBody)
+			handler.ServeHTTP(rec, req)
+
+			return rec
+		}
+
+		for i := range perMinute {
+			if code := post().Code; code != http.StatusOK {
+				t.Fatalf("request %d: status = %d, want %d",
+					i+1, code, http.StatusOK)
+			}
+		}
+
+		rec := post()
+		if rec.Code != http.StatusTooManyRequests {
+			t.Fatalf("request past the allowance: status = %d, want %d",
+				rec.Code, http.StatusTooManyRequests)
+		}
+
+		if got := rec.Body.String(); got != "{\"status\":\"error\"}\n" {
+			t.Errorf("body = %q, want %q", got, "{\"status\":\"error\"}\n")
+		}
+
+		if got := rec.Header().Get("Retry-After"); got != "60" {
+			t.Fatalf("Retry-After = %q, want %q", got, "60")
+		}
+
+		// httprate also counts the previous minute's requests, fading
+		// them out over the current one, so two minutes on the whole
+		// allowance is back.
+		time.Sleep(2 * time.Minute)
+
+		for i := range perMinute {
+			if code := post().Code; code != http.StatusOK {
+				t.Fatalf("two minutes later, request %d: status = %d, want %d",
+					i+1, code, http.StatusOK)
+			}
+		}
+	})
+}
+
+// postForwarded sends handler a report from peer that names client in
+// X-Forwarded-For, and returns the status.
+func postForwarded(
+	t *testing.T,
+	handler http.Handler,
+	peer, client string,
+) int {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodPost, "/api/v1/reports", http.NoBody)
+	req.RemoteAddr = peer
+	req.Header.Set("X-Forwarded-For", client)
+	handler.ServeHTTP(rec, req)
+
+	return rec.Code
+}
+
+// TestRateLimitIsPerForwardedClient checks that clients behind a
+// trusted proxy each get their own allowance: the limit is keyed on
+// the client address clientIP resolves, not on the proxy's.
+func TestRateLimitIsPerForwardedClient(t *testing.T) {
+	t.Parallel()
+
+	const otherClient = "203.0.113.8"
+
+	mw := middleware.NewWithTrustedProxies(mustPrefixes(t, "127.0.0.1/32"))
+	handler := mw.RateLimit(1)(okHandler())
+
+	code := postForwarded(t, handler, loopbackPeer, forwardedIP)
+	if code != http.StatusOK {
+		t.Fatalf("first request: status = %d, want %d", code, http.StatusOK)
+	}
+
+	code = postForwarded(t, handler, loopbackPeer, forwardedIP)
+	if code != http.StatusTooManyRequests {
+		t.Fatalf("same client again: status = %d, want %d",
+			code, http.StatusTooManyRequests)
+	}
+
+	code = postForwarded(t, handler, loopbackPeer, otherClient)
+	if code != http.StatusOK {
+		t.Fatalf("other client behind the same proxy: status = %d, want %d",
+			code, http.StatusOK)
+	}
+}
+
+// TestRateLimitIgnoresForwardedForFromUntrustedPeer checks that a
+// peer that is not a trusted proxy cannot get a fresh allowance by
+// naming a different client in X-Forwarded-For on each request.
+func TestRateLimitIgnoresForwardedForFromUntrustedPeer(t *testing.T) {
+	t.Parallel()
+
+	const untrustedPeer = "198.51.100.4:5000"
+
+	mw := middleware.NewWithTrustedProxies(mustPrefixes(t, "127.0.0.1/32"))
+	handler := mw.RateLimit(1)(okHandler())
+
+	code := postForwarded(t, handler, untrustedPeer, "203.0.113.8")
+	if code != http.StatusOK {
+		t.Fatalf("first request: status = %d, want %d", code, http.StatusOK)
+	}
+
+	code = postForwarded(t, handler, untrustedPeer, "203.0.113.9")
+	if code != http.StatusTooManyRequests {
+		t.Fatalf("same peer naming another client: status = %d, want %d",
+			code, http.StatusTooManyRequests)
+	}
+}
+
+// preflight sends cors the preflight request a browser makes before
+// it POSTs JSON from origin.
+func preflight(
+	t *testing.T,
+	cors func(http.Handler) http.Handler,
+	origin string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodOptions, "/api/v1/reports", http.NoBody)
+	req.Header.Set("Origin", origin)
+	req.Header.Set("Access-Control-Request-Method", http.MethodPost)
+	req.Header.Set("Access-Control-Request-Headers", "content-type")
+	cors(okHandler()).ServeHTTP(rec, req)
+
+	return rec
+}
+
+// TestCORSWithoutOriginsAddsNoHeaders checks the default: with no
+// origins configured, no origin is given any CORS header.
+func TestCORSWithoutOriginsAddsNoHeaders(t *testing.T) {
+	t.Parallel()
+
+	rec := preflight(t,
+		(&middleware.Middleware{}).CORS(nil), "https://elsewhere.example")
+
+	for name := range rec.Header() {
+		if strings.HasPrefix(name, "Access-Control-") {
+			t.Errorf("CORS header %s set with no origins configured", name)
+		}
+	}
+}
+
+func TestCORSAllowsOnlyListedOrigins(t *testing.T) {
+	t.Parallel()
+
+	const listed = "https://netwatch.example"
+
+	cors := (&middleware.Middleware{}).CORS([]string{listed})
+
+	cases := []struct {
+		name   string
+		origin string
+		want   string
+	}{
+		{name: "listed origin allowed", origin: listed, want: listed},
+		{name: "other origin refused", origin: "https://elsewhere.example"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := preflight(t, cors, tc.origin)
+
+			got := rec.Header().Get("Access-Control-Allow-Origin")
+			if got != tc.want {
+				t.Errorf("Access-Control-Allow-Origin = %q, want %q",
+					got, tc.want)
+			}
+		})
+	}
+}

internal/reportbuf/datadir.go

@@ -0,0 +1,150 @@
+package reportbuf
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"syscall"
+)
+
+// ErrDataDirOutsideVolume is returned by PrepareDataDir for a DATA_DIR
+// that is not the volume or a path below it, written in full.
+var ErrDataDirOutsideVolume = errors.New(
+	"must be /data or a path below it, with no '.', '..' or extra '/'")
+
+// PrepareDataDir gets dir, the server's DATA_DIR, ready for owner, the
+// user the server runs as, so that a host directory mounted at volume,
+// /data in the image, needs no preparing: it creates dir, gives volume
+// and everything in it to owner, and gives volume and dir the mode the
+// server gives a directory it creates. dir must be volume or a path
+// below it, with no '.', '..', empty part or '/' at the end.
+//
+// bin/entrypoint.sh runs this as root, which would follow a symbolic
+// link anywhere, so every step goes through an os.Root opened on
+// volume: it follows a link only when it is written as a relative
+// path that stays inside volume, and refuses any other. A process on
+// the host can swap a link onto a path in volume at any moment while
+// this runs. Even then, the os.Root checks each link as it reaches
+// it. MkdirAll creates each directory inside a parent it already has
+// open, never following a link at the name it creates, and follows a
+// link on the path only as the os.Root allows, so a relative link
+// inside volume can lead it to create directories elsewhere inside
+// volume. Lchown never changes what a link points to, and the modes
+// are set on directories already opened (see chmodDir), so the most
+// that process can do is make a step fail or wait, or act on
+// something else inside volume.
+func PrepareDataDir(volume, dir string, owner *user.User) error {
+	// rel is dir as a path from volume; IsLocal is false for one that
+	// leads out of it.
+	rel, err := filepath.Rel(volume, dir)
+	if err != nil || dir != filepath.Clean(dir) || !filepath.IsLocal(rel) {
+		return ErrDataDirOutsideVolume
+	}
+
+	uid, err := strconv.Atoi(owner.Uid)
+	if err != nil {
+		return err
+	}
+
+	gid, err := strconv.Atoi(owner.Gid)
+	if err != nil {
+		return err
+	}
+
+	root, err := os.OpenRoot(volume)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = root.Close() }()
+
+	err = root.MkdirAll(rel, dirPerms)
+	if err != nil {
+		return err
+	}
+
+	err = lchownAll(root, ".", uid, gid)
+	if err != nil {
+		return err
+	}
+
+	err = chmodDir(root, ".")
+	if err != nil {
+		return err
+	}
+
+	return chmodDir(root, rel)
+}
+
+// lchownAll gives name, a directory inside root, and everything in it
+// to uid and gid. It reads each directory opened through root, not
+// through root.FS(), which refuses a name that is not valid UTF-8, and
+// calls Lchown on every entry, which gives a symbolic link itself to
+// them, not what it points to. It goes into an entry only when the
+// read found a directory there, so it follows no link it finds; one
+// swapped in for that directory afterwards is followed only as the
+// os.Root allows.
+func lchownAll(root *os.Root, name string, uid, gid int) error {
+	err := root.Lchown(name, uid, gid)
+	if err != nil {
+		return err
+	}
+
+	dir, err := root.Open(name)
+	if err != nil {
+		return err
+	}
+
+	entries, err := dir.ReadDir(-1)
+	_ = dir.Close()
+
+	if err != nil {
+		return err
+	}
+
+	for _, entry := range entries {
+		entryName := filepath.Join(name, entry.Name())
+		if entry.IsDir() {
+			err = lchownAll(root, entryName, uid, gid)
+		} else {
+			err = root.Lchown(entryName, uid, gid)
+		}
+
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// chmodDir gives name, a directory inside root, the mode the server
+// gives a directory it creates. Root.Chmod would not hold: on Linux it
+// checks that name is not a symbolic link, then sets the mode by name,
+// following a link swapped in between. So chmodDir opens name through
+// root and sets the mode on the open directory. It refuses anything
+// but a directory: a directory has no second name (hard link), so the
+// one opened is inside root, where any other file could be a hard link
+// to one outside.
+func chmodDir(root *os.Root, name string) error {
+	dir, err := root.Open(name)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = dir.Close() }()
+
+	info, err := dir.Stat()
+	if err != nil {
+		return err
+	}
+
+	if !info.IsDir() {
+		return &fs.PathError{Op: "chmod", Path: name, Err: syscall.ENOTDIR}
+	}
+
+	return dir.Chmod(dirPerms)
+}

internal/reportbuf/datadir_test.go

@@ -0,0 +1,307 @@
+package reportbuf_test
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"testing"
+
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+// reports is the last part of DATA_DIR in these tests, as in the
+// image's /data/reports.
+const reports = "reports"
+
+// currentUser is the user the test runs as, the only owner a test not
+// run as root can give files to.
+func currentUser() *user.User {
+	return &user.User{
+		Uid: strconv.Itoa(os.Getuid()),
+		Gid: strconv.Itoa(os.Getgid()),
+	}
+}
+
+// tempDirMode700 is a new directory in a t.TempDir with mode 0700, so
+// a test can tell that PrepareDataDir left its mode alone.
+func tempDirMode700(t *testing.T) string {
+	t.Helper()
+
+	dir := filepath.Join(t.TempDir(), "d")
+
+	err := os.Mkdir(dir, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return dir
+}
+
+func requireMode(t *testing.T, path string, want fs.FileMode) {
+	t.Helper()
+
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if info.Mode() != want {
+		t.Errorf("%s: mode %v, want %v", path, info.Mode(), want)
+	}
+}
+
+func requireMissing(t *testing.T, path string) {
+	t.Helper()
+
+	_, err := os.Lstat(path)
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("%s: created, or Lstat failed: %v", path, err)
+	}
+}
+
+func requireOwner(t *testing.T, path string, uid, gid uint32) {
+	t.Helper()
+
+	info, err := os.Lstat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stat, _ := info.Sys().(*syscall.Stat_t)
+	if stat.Uid != uid || stat.Gid != gid {
+		t.Errorf("%s: owner %d:%d, want %d:%d", path, stat.Uid, stat.Gid,
+			uid, gid)
+	}
+}
+
+func TestPrepareDataDirCreatesDataDir(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	dir := filepath.Join(volume, "a", reports)
+
+	err := reportbuf.PrepareDataDir(volume, dir, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, volume, fs.ModeDir|0o750)
+	requireMode(t, dir, fs.ModeDir|0o750)
+}
+
+// TestPrepareDataDirSetsModeOfExistingDataDir: a DATA_DIR already on
+// the host with another mode gets the mode too, not only a new one.
+func TestPrepareDataDirSetsModeOfExistingDataDir(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	dir := filepath.Join(volume, reports)
+
+	err := os.Mkdir(dir, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, dir, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, dir, fs.ModeDir|0o750)
+}
+
+func TestPrepareDataDirTakesTheVolumeItself(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+
+	err := reportbuf.PrepareDataDir(volume, volume, currentUser())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	requireMode(t, volume, fs.ModeDir|0o750)
+}
+
+// TestPrepareDataDirRefusesDataDirOutsideVolume covers a DATA_DIR that
+// is relative, outside the volume, or not written in full.
+func TestPrepareDataDirRefusesDataDirOutsideVolume(t *testing.T) {
+	t.Parallel()
+
+	volume := tempDirMode700(t)
+	for _, dir := range []string{
+		reports, volume + "/../new", volume + "/", volume + "//" + reports,
+		volume + "/./" + reports, volume + "/" + reports + "/..", volume + "x",
+		"/etc",
+	} {
+		err := reportbuf.PrepareDataDir(volume, dir, currentUser())
+		if !errors.Is(err, reportbuf.ErrDataDirOutsideVolume) {
+			t.Errorf("%q: error = %v, want ErrDataDirOutsideVolume", dir, err)
+		}
+	}
+
+	requireMissing(t, filepath.Join(filepath.Dir(volume), "new"))
+	requireMode(t, volume, fs.ModeDir|0o700)
+}
+
+// TestPrepareDataDirRefusesLinkOutOfVolume puts a symbolic link to a
+// directory outside the volume on the path to DATA_DIR, written as a
+// full path and as one that climbs out with '..', and as DATA_DIR
+// itself, where the mode would be set through it.
+func TestPrepareDataDirRefusesLinkOutOfVolume(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name      string
+		climbsOut bool
+		link, dir string
+	}{
+		{"full path", false, "x", "x/reports"},
+		{"climbs out", true, "x", "x/reports"},
+		{"DATA_DIR itself", false, reports, reports},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			outside := tempDirMode700(t)
+			volume := t.TempDir()
+
+			climbOut, err := filepath.Rel(volume, outside)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			target := outside
+			if tc.climbsOut {
+				target = climbOut
+			}
+
+			err = os.Symlink(target, filepath.Join(volume, tc.link))
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = reportbuf.PrepareDataDir(volume,
+				filepath.Join(volume, tc.dir), currentUser())
+			if err == nil {
+				t.Error("no error")
+			}
+
+			requireMissing(t, filepath.Join(outside, reports))
+			requireMode(t, outside, fs.ModeDir|0o700)
+		})
+	}
+}
+
+// TestPrepareDataDirRefusesDanglingLink: DATA_DIR is a symbolic link
+// to a name in the volume that does not exist, which is not created.
+func TestPrepareDataDirRefusesDanglingLink(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+
+	err := os.Symlink("missing", filepath.Join(volume, reports))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		currentUser())
+	if err == nil {
+		t.Error("no error")
+	}
+
+	requireMissing(t, filepath.Join(volume, "missing"))
+}
+
+// TestPrepareDataDirTakesDirectoryNamedInLatin1: a host directory can
+// hold names that are not valid UTF-8, here "café" written in Latin-1.
+// A test not run as root can only check that PrepareDataDir goes into
+// such a directory and gives it, and what it holds, to the current
+// user.
+func TestPrepareDataDirTakesDirectoryNamedInLatin1(t *testing.T) {
+	t.Parallel()
+
+	volume := t.TempDir()
+	latin1 := filepath.Join(volume, "caf\xe9")
+
+	err := os.Mkdir(latin1, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.WriteFile(filepath.Join(latin1, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	owner := currentUser()
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		owner)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	uid, _ := strconv.ParseUint(owner.Uid, 10, 32)
+	gid, _ := strconv.ParseUint(owner.Gid, 10, 32)
+
+	requireOwner(t, latin1, uint32(uid), uint32(gid))
+	requireOwner(t, filepath.Join(latin1, "f"), uint32(uid), uint32(gid))
+}
+
+// TestPrepareDataDirGivesVolumeToOwner gives everything in the volume
+// to a uid and gid that own nothing, which only root can do. A
+// symbolic link in the volume to a directory outside it is given to
+// them itself; what it points to is left as it was.
+func TestPrepareDataDirGivesVolumeToOwner(t *testing.T) {
+	t.Parallel()
+
+	if os.Geteuid() != 0 {
+		t.Skip("only root can give files to another uid")
+	}
+
+	outside := t.TempDir()
+	volume := t.TempDir()
+	old := filepath.Join(volume, "old")
+
+	err := os.WriteFile(filepath.Join(outside, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Mkdir(old, 0o700)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.WriteFile(filepath.Join(old, "f"), nil, 0o600)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = os.Symlink(outside, filepath.Join(old, "link"))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = reportbuf.PrepareDataDir(volume, filepath.Join(volume, reports),
+		&user.User{Uid: "4242", Gid: "4343"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	for _, path := range []string{
+		volume, filepath.Join(volume, reports), old,
+		filepath.Join(old, "f"), filepath.Join(old, "link"),
+	} {
+		requireOwner(t, path, 4242, 4343)
+	}
+
+	requireOwner(t, outside, 0, 0)
+	requireOwner(t, filepath.Join(outside, "f"), 0, 0)
+}

internal/reportbuf/export_test.go

@@ -0,0 +1,29 @@
+package reportbuf
+
+import (
+	"os"
+	"time"
+)
+
+// FlushSizeThreshold exposes the buffer size at which Append starts
+// writing a report file to the external tests.
+const FlushSizeThreshold = flushSizeThreshold
+
+// Flush writes the buffered reports to a file now, as the periodic
+// flush does, so tests need not wait a minute for it.
+func (b *Buffer) Flush() error {
+	return b.flushLocked()
+}
+
+// StopClock makes every report file the buffer writes from now on
+// carry the timestamp at, as if all were written in one millisecond.
+func (b *Buffer) StopClock(at time.Time) {
+	b.now = func() time.Time { return at }
+}
+
+// OnFileCreated makes the buffer call fn with each report file it
+// writes from now on, once the file is created and before anything is
+// written to it.
+func (b *Buffer) OnFileCreated(fn func(f *os.File)) {
+	b.fileCreated = fn
+}

internal/reportbuf/reportbuf.go

@@ -0,0 +1,419 @@
+// Package reportbuf accumulates telemetry reports in memory
+// and periodically flushes them to zstd-compressed JSONL files,
+// deleting the oldest files to keep them under a size cap.
+package reportbuf
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"github.com/klauspost/compress/zstd"
+	"go.uber.org/fx"
+)
+
+const (
+	flushSizeThreshold             = 10 << 20 // 10 MiB
+	flushInterval                  = 1 * time.Minute
+	defaultDataDir                 = "./data/reports"
+	dirPerms           fs.FileMode = 0o750
+	filePerms          fs.FileMode = 0o640
+
+	// Report files are named filePrefix + timestamp + "-" + number +
+	// fileSuffix; see writeFile.
+	filePrefix = "reports-"
+	fileSuffix = ".jsonl.zst"
+)
+
+// ErrFull is returned by Append when the reports waiting to be
+// written leave no room for the report under the configured maximum
+// size, however many report files are deleted.
+var ErrFull = errors.New("reports waiting to be written fill the size cap")
+
+// Params defines the dependencies for Buffer.
+type Params struct {
+	fx.In
+
+	Config *config.Config
+	Logger *logger.Logger
+}
+
+// reportFile is a report file that may be deleted to make room, with
+// the size it counts for in usedBytes.
+type reportFile struct {
+	name string
+	size int64
+}
+
+// Buffer accumulates JSON lines in memory and flushes them
+// to zstd-compressed files on disk.
+type Buffer struct {
+	buf     bytes.Buffer
+	dataDir string
+	done    chan struct{}
+	// fileCreated is called with each report file once it is
+	// created, before anything is written to it: it does nothing,
+	// except in tests that hold the write open or make it fail.
+	fileCreated func(f *os.File)
+	// files are the report files that may be deleted to make room,
+	// in name order, which is oldest first: those in dataDir at
+	// start, and each one this buffer writes, put in at its place by
+	// name once it is complete, even when an older file's write
+	// completes after a newer one's. A file still being written is
+	// not among them. filesBytes is their total size.
+	files      []reportFile
+	filesBytes int64
+	log        *slog.Logger
+	maxBytes   int64
+	mu         sync.Mutex
+	// now is the clock report files are named by: time.Now, except
+	// in tests that need two flushes to share a timestamp.
+	now func() time.Time
+	// seq numbers the report files, so that two named in the same
+	// millisecond still get different names.
+	seq      atomic.Uint64
+	stopOnce sync.Once
+	// usedBytes is what Append checks against maxBytes: the size
+	// of the report files in dataDir, plus the reports waiting to
+	// be written to one at their uncompressed size.
+	usedBytes int64
+}
+
+// New creates a Buffer and registers lifecycle hooks to
+// manage the data directory and flush goroutine.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Buffer, error) {
+	dir := params.Config.DataDir
+	if dir == "" {
+		dir = defaultDataDir
+	}
+
+	b := &Buffer{
+		dataDir:     dir,
+		done:        make(chan struct{}),
+		fileCreated: func(*os.File) {},
+		log:         params.Logger.Get(),
+		maxBytes:    params.Config.DataDirMaxBytes,
+		now:         time.Now,
+	}
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			err := os.MkdirAll(b.dataDir, dirPerms)
+			if err != nil {
+				return fmt.Errorf("create data dir: %w", err)
+			}
+
+			// Report files left by earlier runs count too, and are
+			// the first to be deleted to make room.
+			files, err := reportFiles(b.dataDir)
+			if err != nil {
+				return err
+			}
+
+			b.mu.Lock()
+
+			b.files = files
+			for _, f := range files {
+				b.filesBytes += f.size
+			}
+
+			b.usedBytes = b.filesBytes
+
+			// The files may be past the cap, if it was lowered since
+			// the last run.
+			b.deleteOldestFiles(0)
+
+			b.mu.Unlock()
+
+			go b.flushLoop()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			// stopOnce makes OnStop idempotent: a second
+			// invocation must not close an already-closed channel
+			// (which would panic) or flush again.
+			var err error
+
+			b.stopOnce.Do(func() {
+				close(b.done)
+				err = b.flushLocked()
+			})
+
+			// A failed final flush fails the stop, so the process
+			// exits non-zero.
+			return err
+		},
+	})
+
+	return b, nil
+}
+
+// Append marshals v as a single JSON line and appends it to
+// the buffer. If the line would take usedBytes past maxBytes, the
+// oldest report files are deleted to make room; it stores nothing
+// and returns ErrFull if that cannot make room. If the buffer
+// reaches the size threshold, it is drained and written to disk
+// asynchronously.
+func (b *Buffer) Append(v any) error {
+	line, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Errorf("marshal report: %w", err)
+	}
+
+	lineBytes := int64(len(line)) + 1 // with its newline
+
+	b.mu.Lock()
+
+	b.deleteOldestFiles(lineBytes)
+
+	if b.usedBytes+lineBytes > b.maxBytes {
+		b.mu.Unlock()
+
+		return ErrFull
+	}
+
+	b.usedBytes += lineBytes
+	b.buf.Write(line)
+	b.buf.WriteByte('\n')
+
+	if b.buf.Len() >= flushSizeThreshold {
+		data := b.drainBuf()
+		b.mu.Unlock()
+
+		go func() {
+			writeErr := b.writeFile(data)
+			if writeErr != nil {
+				b.log.Error("flush reports failed", "error", writeErr)
+			}
+		}()
+
+		return nil
+	}
+
+	b.mu.Unlock()
+
+	return nil
+}
+
+// deleteOldestFiles deletes report files, oldest first, until n more
+// bytes fit under maxBytes. It deletes none when the reports waiting
+// to be written leave no room for n even with every file gone, since
+// that would lose the files for nothing. The caller must hold b.mu.
+func (b *Buffer) deleteOldestFiles(n int64) {
+	for b.usedBytes+n > b.maxBytes && len(b.files) > 0 {
+		if b.usedBytes-b.filesBytes+n > b.maxBytes {
+			return
+		}
+
+		f := b.files[0]
+		b.files = b.files[1:]
+		b.filesBytes -= f.size
+
+		// A file already gone, deleted by hand, has freed its room too.
+		err := os.Remove(filepath.Join(b.dataDir, f.name))
+		if err != nil && !errors.Is(err, fs.ErrNotExist) {
+			// The file is still there, so it still counts. It is
+			// not tried again until the next start.
+			b.log.Error("delete report file failed",
+				"file", f.name, "error", err)
+
+			continue
+		}
+
+		b.usedBytes -= f.size
+		b.log.Info("deleted report file to make room",
+			"file", f.name, "bytes", f.size)
+	}
+}
+
+// flushLoop runs a ticker that periodically flushes buffered
+// data to disk until the done channel is closed.
+func (b *Buffer) flushLoop() {
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			err := b.flushLocked()
+			if err != nil {
+				b.log.Error("flush reports failed", "error", err)
+			}
+		case <-b.done:
+			return
+		}
+	}
+}
+
+// flushLocked acquires the lock, drains the buffer, and
+// writes the data to a compressed file.
+func (b *Buffer) flushLocked() error {
+	b.mu.Lock()
+
+	if b.buf.Len() == 0 {
+		b.mu.Unlock()
+
+		return nil
+	}
+
+	data := b.drainBuf()
+	b.mu.Unlock()
+
+	return b.writeFile(data)
+}
+
+// drainBuf copies the buffer contents and resets it.
+// The caller must hold b.mu.
+func (b *Buffer) drainBuf() []byte {
+	data := make([]byte, b.buf.Len())
+	copy(data, b.buf.Bytes())
+	b.buf.Reset()
+
+	return data
+}
+
+// writeFile writes data, reports drained from the buffer, to a new
+// timestamped zstd-compressed JSONL file in the data directory.
+func (b *Buffer) writeFile(data []byte) error {
+	// The timestamp comes first, so the names sort by time; the number
+	// after it tells apart files named in the same millisecond.
+	ts := b.now().UTC().Format("2006-01-02T15-04-05.000Z")
+	name := fmt.Sprintf("%s%s-%d%s", filePrefix, ts, b.seq.Add(1), fileSuffix)
+
+	size, err := b.createFile(filepath.Join(b.dataDir, name), data)
+
+	// The reports no longer wait to be written, so they stop counting
+	// at their uncompressed size. If the write failed they are lost;
+	// otherwise they count as the file, which from here on may be
+	// deleted to make room.
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.usedBytes -= int64(len(data))
+
+	if err != nil {
+		return err
+	}
+
+	b.usedBytes += size
+	b.filesBytes += size
+
+	// At its place by name, not at the end: another write, of a newer
+	// file, may have completed while this one was being written.
+	i, _ := slices.BinarySearchFunc(b.files, name,
+		func(f reportFile, target string) int {
+			return strings.Compare(f.name, target)
+		})
+	b.files = slices.Insert(b.files, i, reportFile{name: name, size: size})
+
+	return nil
+}
+
+// createFile creates the file at path holding data compressed with
+// zstd, and returns its size. If the write fails once the file is
+// created, it removes the file, so that a failed write leaves nothing
+// behind to take room.
+func (b *Buffer) createFile(path string, data []byte) (int64, error) {
+	// path is built from the operator-supplied dataDir plus a
+	// generated timestamp and number, so it carries no external input.
+	f, err := os.OpenFile( //nolint:gosec // see comment above
+		path,
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		filePerms,
+	)
+	if err != nil {
+		return 0, fmt.Errorf("create report file: %w", err)
+	}
+
+	b.fileCreated(f)
+
+	size, err := writeCompressed(f, data)
+	if err != nil {
+		_ = f.Close()
+
+		return 0, errors.Join(err, os.Remove(path))
+	}
+
+	err = f.Close()
+	if err != nil {
+		err = fmt.Errorf("close report file: %w", err)
+
+		return 0, errors.Join(err, os.Remove(path))
+	}
+
+	return size, nil
+}
+
+// writeCompressed writes data to f compressed with zstd, and returns
+// the size of f.
+func writeCompressed(f *os.File, data []byte) (int64, error) {
+	enc, err := zstd.NewWriter(f)
+	if err != nil {
+		return 0, fmt.Errorf("create zstd encoder: %w", err)
+	}
+
+	_, err = enc.Write(data)
+	if err != nil {
+		_ = enc.Close()
+
+		return 0, fmt.Errorf("write compressed data: %w", err)
+	}
+
+	err = enc.Close()
+	if err != nil {
+		return 0, fmt.Errorf("close zstd encoder: %w", err)
+	}
+
+	info, err := f.Stat()
+	if err != nil {
+		return 0, fmt.Errorf("stat report file: %w", err)
+	}
+
+	return info.Size(), nil
+}
+
+// reportFiles returns the report files in dir, oldest first:
+// os.ReadDir sorts them by name, and the names sort by time.
+func reportFiles(dir string) ([]reportFile, error) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil, fmt.Errorf("read data dir: %w", err)
+	}
+
+	files := make([]reportFile, 0, len(entries))
+
+	for _, entry := range entries {
+		name := entry.Name()
+		if !strings.HasPrefix(name, filePrefix) ||
+			!strings.HasSuffix(name, fileSuffix) {
+			continue
+		}
+
+		info, err := entry.Info()
+		if err != nil {
+			return nil, fmt.Errorf("stat report file: %w", err)
+		}
+
+		files = append(files, reportFile{name: name, size: info.Size()})
+	}
+
+	return files, nil
+}

internal/reportbuf/reportbuf_test.go

@@ -0,0 +1,919 @@
+package reportbuf_test
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+
+	"github.com/klauspost/compress/zstd"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+)
+
+// TestFlushOnShutdown proves the flush-on-shutdown path: a
+// report appended after start but before the periodic flush
+// window must reach disk when the fx lifecycle stops. This is
+// the exact case that silent data loss on restart used to
+// destroy.
+func TestFlushOnShutdown(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	var buf *reportbuf.Buffer
+
+	app := fxtest.New(t,
+		fx.Provide(
+			globals.New,
+			logger.New,
+			config.New,
+			reportbuf.New,
+		),
+		fx.Populate(&buf),
+	)
+
+	app.RequireStart()
+
+	err := buf.Append(map[string]string{"probe": "shutdown"})
+	if err != nil {
+		t.Fatalf("append report: %v", err)
+	}
+
+	// RequireStop runs the reportbuf OnStop hook, which is the
+	// only code path that flushes buffered reports on shutdown.
+	app.RequireStop()
+
+	if !hasReportFile(t, dir) {
+		t.Fatal("no report file on disk after shutdown; " +
+			"the buffered report was lost")
+	}
+}
+
+// TestFailedFinalFlushFailsStop proves a final flush that cannot
+// write its file makes the stop fail, which makes the process
+// exit non-zero instead of dropping the buffered reports silently.
+func TestFailedFinalFlushFailsStop(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	var buf *reportbuf.Buffer
+
+	app := fxtest.New(t,
+		fx.Provide(
+			globals.New,
+			logger.New,
+			config.New,
+			reportbuf.New,
+		),
+		fx.Populate(&buf),
+	)
+
+	app.RequireStart()
+
+	err := buf.Append(map[string]string{"probe": "shutdown"})
+	if err != nil {
+		t.Fatalf("append report: %v", err)
+	}
+
+	// Removing the data directory leaves the final flush nowhere to
+	// write. A read-only directory would not do: tests run as root
+	// in the backend image, and root ignores the read-only bit.
+	err = os.RemoveAll(dir)
+	if err != nil {
+		t.Fatalf("remove data dir: %v", err)
+	}
+
+	err = app.Stop(t.Context())
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("stop error = %v, want the final flush's error", err)
+	}
+}
+
+// startBuffer starts a Buffer through fx, as main does, with the
+// DATA_DIR and DATA_DIR_MAX_BYTES the calling test has set.
+func startBuffer(t *testing.T) *reportbuf.Buffer {
+	t.Helper()
+
+	var buf *reportbuf.Buffer
+
+	app := fxtest.New(t,
+		fx.Provide(
+			globals.New,
+			logger.New,
+			config.New,
+			reportbuf.New,
+		),
+		fx.Populate(&buf),
+	)
+
+	app.RequireStart()
+	t.Cleanup(app.RequireStop)
+
+	return buf
+}
+
+// lineBytes is what one report takes in the buffer: its JSON and a
+// newline.
+func lineBytes(t *testing.T, report any) int {
+	t.Helper()
+
+	line, err := json.Marshal(report)
+	if err != nil {
+		t.Fatalf("marshal report: %v", err)
+	}
+
+	return len(line) + 1
+}
+
+// TestAppendPastCapIsRefused fills the cap with a report not yet
+// written. The next report is refused, and the report file already in
+// DATA_DIR is kept: it is smaller than a report, so deleting it could
+// not make room.
+func TestAppendPastCapIsRefused(t *testing.T) {
+	report := map[string]string{"id": "cap"}
+	dir := t.TempDir()
+	earlier := reportFilePath(dir, 1)
+
+	writeBytes(t, earlier, 1)
+
+	t.Setenv("DATA_DIR", dir)
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(1+lineBytes(t, report)))
+
+	buf := startBuffer(t)
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("report that fills the cap exactly: %v", err)
+	}
+
+	err = buf.Append(report)
+	if !errors.Is(err, reportbuf.ErrFull) {
+		t.Fatalf("report past the cap: error = %v, want ErrFull", err)
+	}
+
+	if !exists(t, earlier) {
+		t.Fatal("report file deleted, though that could not make room")
+	}
+}
+
+// TestOldestReportFileDeletedFirst starts on a data directory holding
+// report files from an earlier run, and a file that is not a report,
+// which neither counts nor is ever deleted. Nothing is deleted while
+// there is room; then only the oldest report file is.
+func TestOldestReportFileDeletedFirst(t *testing.T) {
+	const fileBytes = 100
+
+	report := map[string]string{"id": "oldest"}
+	dir := t.TempDir()
+	oldest := reportFilePath(dir, 1)
+	kept := []string{
+		reportFilePath(dir, 2),
+		reportFilePath(dir, 3),
+		filepath.Join(dir, "notes.txt"),
+	}
+
+	writeBytes(t, oldest, fileBytes)
+
+	for _, path := range kept {
+		writeBytes(t, path, fileBytes)
+	}
+
+	t.Setenv("DATA_DIR", dir)
+	// Room for the three report files and one report.
+	t.Setenv("DATA_DIR_MAX_BYTES",
+		strconv.Itoa(3*fileBytes+lineBytes(t, report)))
+
+	buf := startBuffer(t)
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("report that fills the cap exactly: %v", err)
+	}
+
+	if !exists(t, oldest) {
+		t.Fatal("oldest report file deleted while there was room")
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("report past the cap: %v", err)
+	}
+
+	if exists(t, oldest) {
+		t.Fatal("oldest report file kept when room was needed")
+	}
+
+	for _, path := range kept {
+		if !exists(t, path) {
+			t.Fatalf("%s deleted; only the oldest report file should be", path)
+		}
+	}
+}
+
+// TestStartDeletesFilesPastCap starts on report files past the cap,
+// as after the cap is lowered: the oldest are deleted until the rest
+// fit.
+func TestStartDeletesFilesPastCap(t *testing.T) {
+	const fileBytes = 100
+
+	dir := t.TempDir()
+	oldest := reportFilePath(dir, 1)
+	kept := []string{reportFilePath(dir, 2), reportFilePath(dir, 3)}
+
+	writeBytes(t, oldest, fileBytes)
+
+	for _, path := range kept {
+		writeBytes(t, path, fileBytes)
+	}
+
+	t.Setenv("DATA_DIR", dir)
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(len(kept)*fileBytes))
+
+	startBuffer(t)
+
+	if exists(t, oldest) {
+		t.Fatal("oldest report file kept, though the files were past the cap")
+	}
+
+	for _, path := range kept {
+		if !exists(t, path) {
+			t.Fatalf("%s deleted, though the rest fit without it", path)
+		}
+	}
+}
+
+// TestWrittenReportsCountAtFileSize checks that once reports are
+// written, they count as their compressed file, not their
+// uncompressed size, which frees room under the cap.
+func TestWrittenReportsCountAtFileSize(t *testing.T) {
+	// Repetitive, so its file is far smaller than its JSON.
+	report := map[string]string{"id": strings.Repeat("a", 1000)}
+	size := lineBytes(t, report)
+	dir := t.TempDir()
+
+	t.Setenv("DATA_DIR", dir)
+	// Room for the report twice over only if the first one counts
+	// at its file's size by the time the second arrives.
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*size-1))
+
+	buf := startBuffer(t)
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("first report: %v", err)
+	}
+
+	err = buf.Flush()
+	if err != nil {
+		t.Fatalf("flush: %v", err)
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("second report, after the first was written: %v", err)
+	}
+
+	if !hasReportFile(t, dir) {
+		t.Fatal("first report's file deleted, though the second fit beside it")
+	}
+}
+
+// TestWrittenFilesDeletedToMakeRoom writes one report file after
+// another under a small cap. Every report must be taken; files are
+// deleted only when the report would not fit beside them, and the
+// files kept leave room for it.
+func TestWrittenFilesDeletedToMakeRoom(t *testing.T) {
+	const (
+		maxBytes = 200
+		// One file each, which take far more than maxBytes together.
+		reports = 50
+	)
+
+	report := map[string]string{"id": "written"}
+	size := int64(lineBytes(t, report))
+	dir := t.TempDir()
+
+	t.Setenv("DATA_DIR", dir)
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(maxBytes))
+
+	buf := startBuffer(t)
+
+	for range reports {
+		before := reportFilesBytes(t, dir)
+
+		err := buf.Append(report)
+		if err != nil {
+			t.Fatalf("with %d bytes of report files: %v", before, err)
+		}
+
+		after := reportFilesBytes(t, dir)
+
+		if before+size <= maxBytes && after != before {
+			t.Fatalf("files deleted, though the report fit beside "+
+				"their %d bytes", before)
+		}
+
+		if after+size > maxBytes {
+			t.Fatalf("%d bytes of report files kept, leaving no room "+
+				"for the report", after)
+		}
+
+		err = buf.Flush()
+		if err != nil {
+			t.Fatalf("flush: %v", err)
+		}
+	}
+}
+
+// TestFailedDeletionStillCounts makes deleting the oldest report file
+// fail. It is still there, so it still takes room, and the next oldest
+// is deleted in its place.
+func TestFailedDeletionStillCounts(t *testing.T) {
+	const fileBytes = 100
+
+	report := map[string]string{"id": "stuck"}
+	dir := t.TempDir()
+	stuck := reportFilePath(dir, 1)
+	next := reportFilePath(dir, 2)
+	newest := reportFilePath(dir, 3)
+
+	for _, path := range []string{stuck, next, newest} {
+		writeBytes(t, path, fileBytes)
+	}
+
+	t.Setenv("DATA_DIR", dir)
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(3*fileBytes))
+
+	buf := startBuffer(t)
+
+	// A directory that is not empty cannot be deleted, even by root,
+	// which the tests run as in the backend image.
+	err := os.Remove(stuck)
+	if err != nil {
+		t.Fatalf("remove %s: %v", stuck, err)
+	}
+
+	err = os.Mkdir(stuck, 0o750)
+	if err != nil {
+		t.Fatalf("make directory %s: %v", stuck, err)
+	}
+
+	writeBytes(t, filepath.Join(stuck, "file"), 1)
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("report past the cap: %v", err)
+	}
+
+	if exists(t, next) {
+		t.Fatal("next oldest report file kept: the failed deletion " +
+			"counted as making room")
+	}
+
+	if !exists(t, newest) {
+		t.Fatal("newest report file deleted, though deleting one made room")
+	}
+}
+
+// TestFileDeletedByHandFreesRoom deletes the oldest report file by
+// hand after start. When room is needed, its room counts as freed, so
+// no other file is deleted.
+func TestFileDeletedByHandFreesRoom(t *testing.T) {
+	const fileBytes = 100
+
+	report := map[string]string{"id": "by-hand"}
+	dir := t.TempDir()
+	gone := reportFilePath(dir, 1)
+	kept := reportFilePath(dir, 2)
+
+	writeBytes(t, gone, fileBytes)
+	writeBytes(t, kept, fileBytes)
+
+	t.Setenv("DATA_DIR", dir)
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*fileBytes))
+
+	buf := startBuffer(t)
+
+	err := os.Remove(gone)
+	if err != nil {
+		t.Fatalf("remove %s: %v", gone, err)
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("report past the cap: %v", err)
+	}
+
+	if !exists(t, kept) {
+		t.Fatal("report file deleted, though the one deleted by hand " +
+			"had made room")
+	}
+}
+
+// TestFileBeingWrittenIsNeverDeleted holds the write of one report file
+// open while a second write completes, then sends a report that needs
+// room. Deleting either file would make it, and the one being written is
+// the older, but only the complete one may be deleted. Once the first
+// write is complete, its file is deleted when room is needed.
+func TestFileBeingWrittenIsNeverDeleted(t *testing.T) {
+	report := map[string]string{"id": "writing"}
+
+	t.Setenv("DATA_DIR", t.TempDir())
+	// Room for two reports waiting to be written, but not for two
+	// beside a report file.
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(2*lineBytes(t, report)))
+
+	buf := startBuffer(t)
+
+	created := make(chan string)
+	release := make(chan struct{})
+
+	buf.OnFileCreated(func(f *os.File) {
+		created <- f.Name()
+
+		<-release
+	})
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("first report: %v", err)
+	}
+
+	flushed := make(chan error)
+
+	go func() { flushed <- buf.Flush() }()
+
+	writing := <-created
+
+	// Only the first write is held; the second goes through, and
+	// so do the writes after it, the final one at stop included.
+	var complete string
+
+	buf.OnFileCreated(func(f *os.File) { complete = f.Name() })
+
+	// Errorf, not Fatalf, until the first write is released, so that a
+	// failure here does not leave it held.
+	err = buf.Append(report)
+	if err != nil {
+		t.Errorf("second report: %v", err)
+	}
+
+	err = buf.Flush()
+	if err != nil {
+		t.Errorf("flush of the second report: %v", err)
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Errorf("report that needs room: %v", err)
+	}
+
+	if !exists(t, writing) {
+		t.Error("report file deleted while it was being written")
+	}
+
+	if exists(t, complete) {
+		t.Error("complete report file kept, though room was needed")
+	}
+
+	close(release)
+
+	err = <-flushed
+	if err != nil {
+		t.Fatalf("flush of the first report: %v", err)
+	}
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("report after the first write was complete: %v", err)
+	}
+
+	if exists(t, writing) {
+		t.Fatal("complete report file kept when room was needed")
+	}
+}
+
+// TestFailedWriteStopsCounting makes a write fail once its file is
+// created. Its reports are lost, so they stop counting, and the part of
+// the file written is removed, so it takes no room.
+func TestFailedWriteStopsCounting(t *testing.T) {
+	report := map[string]string{"id": "failed"}
+
+	t.Setenv("DATA_DIR", t.TempDir())
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(lineBytes(t, report)))
+
+	buf := startBuffer(t)
+
+	var failed string
+
+	// Closing the file under the write makes the write fail.
+	buf.OnFileCreated(func(f *os.File) {
+		failed = f.Name()
+
+		_ = f.Close()
+	})
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("report that fills the cap exactly: %v", err)
+	}
+
+	err = buf.Flush()
+	if err == nil {
+		t.Fatal("flush succeeded, though its file was closed under it")
+	}
+
+	if exists(t, failed) {
+		t.Fatal("file of the failed write kept")
+	}
+
+	// Writes from here on, the final one at stop included, succeed.
+	buf.OnFileCreated(func(*os.File) {})
+
+	err = buf.Append(report)
+	if err != nil {
+		t.Fatalf("report after the failed write: %v", err)
+	}
+}
+
+// TestConcurrentAppendsStopAtCap appends from many goroutines at once
+// with room for exactly roomFor reports: exactly that many must be
+// taken, which holds only if Append checks and counts each report
+// under one lock.
+func TestConcurrentAppendsStopAtCap(t *testing.T) {
+	const (
+		roomFor = 5
+		senders = 50
+	)
+
+	// Large, so each Append takes long enough for the senders to
+	// overlap while the cap is reached.
+	report := map[string]string{"id": strings.Repeat("a", 1_000_000)}
+
+	t.Setenv("DATA_DIR", t.TempDir())
+	t.Setenv("DATA_DIR_MAX_BYTES",
+		strconv.Itoa(roomFor*lineBytes(t, report)))
+
+	buf := startBuffer(t)
+
+	var (
+		taken atomic.Int64
+		wg    sync.WaitGroup
+	)
+
+	start := make(chan struct{})
+
+	for range senders {
+		wg.Go(func() {
+			<-start
+
+			err := buf.Append(report)
+			if err == nil {
+				taken.Add(1)
+			} else if !errors.Is(err, reportbuf.ErrFull) {
+				t.Errorf("append: %v", err)
+			}
+		})
+	}
+
+	close(start)
+	wg.Wait()
+
+	if got := taken.Load(); got != roomFor {
+		t.Fatalf("%d reports taken, want %d", got, roomFor)
+	}
+}
+
+// TestTwoFlushesInOneMillisecond flushes twice within one millisecond,
+// as a flush for size and the final flush at shutdown can: each flush
+// must write a file of its own, and the files must hold every report.
+func TestTwoFlushesInOneMillisecond(t *testing.T) {
+	const flushes = 2
+
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	buf := startBuffer(t)
+	buf.StopClock(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))
+
+	for id := 1; id <= flushes; id++ {
+		err := buf.Append(map[string]int{"id": id})
+		if err != nil {
+			t.Fatalf("append report %d: %v", id, err)
+		}
+
+		err = buf.Flush()
+		if err != nil {
+			t.Fatalf("flush %d: %v", id, err)
+		}
+	}
+
+	files, err := readReportFiles(dir)
+	if err != nil {
+		t.Fatalf("read report files: %v", err)
+	}
+
+	if len(files) != flushes {
+		t.Fatalf("%d report files after %d flushes", len(files), flushes)
+	}
+
+	for id := 1; id <= flushes; id++ {
+		want := fmt.Sprintf(`{"id":%d}`+"\n", id)
+		if !slices.Contains(files, want) {
+			t.Fatalf("no report file holds report %d alone", id)
+		}
+	}
+}
+
+// TestReportFileHoldsTheLinesAppended flushes three reports and reads
+// their file back: it must decompress to exactly their JSON lines, in
+// the order they were appended.
+func TestReportFileHoldsTheLinesAppended(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	buf := startBuffer(t)
+
+	for _, id := range []int{1, 2, 3} {
+		err := buf.Append(map[string]int{"id": id})
+		if err != nil {
+			t.Fatalf("append report %d: %v", id, err)
+		}
+	}
+
+	err := buf.Flush()
+	if err != nil {
+		t.Fatalf("flush: %v", err)
+	}
+
+	files, err := readReportFiles(dir)
+	if err != nil {
+		t.Fatalf("read report files: %v", err)
+	}
+
+	want := `{"id":1}` + "\n" + `{"id":2}` + "\n" + `{"id":3}` + "\n"
+	if len(files) != 1 || files[0] != want {
+		t.Fatalf("report files = %q, want one holding %q", files, want)
+	}
+}
+
+// TestFlushAtSizeThreshold appends reports until the buffer holds
+// FlushSizeThreshold bytes. The append that gets it there must write
+// them all to one report file, with no call to Flush and the periodic
+// flush a minute away, and no earlier append may write one.
+func TestFlushAtSizeThreshold(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DATA_DIR", dir)
+
+	buf := startBuffer(t)
+
+	// Large reports, so the threshold takes a few hundred appends.
+	pad := strings.Repeat("a", 64<<10)
+
+	var appended strings.Builder
+
+	for id := 0; appended.Len() < reportbuf.FlushSizeThreshold; id++ {
+		report := map[string]any{"id": id, "pad": pad}
+
+		err := buf.Append(report)
+		if err != nil {
+			t.Fatalf("append report %d: %v", id, err)
+		}
+
+		line, err := json.Marshal(report)
+		if err != nil {
+			t.Fatalf("marshal report %d: %v", id, err)
+		}
+
+		appended.Write(line)
+		appended.WriteByte('\n')
+	}
+
+	// Append writes the file in the background, so wait for it.
+	deadline := time.Now().Add(10 * time.Second)
+
+	for {
+		files, err := readReportFiles(dir)
+		if err == nil && len(files) == 1 && files[0] == appended.String() {
+			return
+		}
+
+		if time.Now().After(deadline) {
+			t.Fatalf("%d report files (error: %v), want one holding the "+
+				"%d bytes appended", len(files), err, appended.Len())
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+// reportFilesBytes returns the total size of the report files in dir.
+func reportFilesBytes(t *testing.T, dir string) int64 {
+	t.Helper()
+
+	paths, err := filepath.Glob(filepath.Join(dir, "reports-*.jsonl.zst"))
+	if err != nil {
+		t.Fatalf("list report files: %v", err)
+	}
+
+	var total int64
+
+	for _, path := range paths {
+		info, statErr := os.Stat(path)
+		if statErr != nil {
+			t.Fatalf("stat %s: %v", path, statErr)
+		}
+
+		total += info.Size()
+	}
+
+	return total
+}
+
+// readReportFiles returns the decompressed contents of each report
+// file in dir. A file still being written does not decompress, so it
+// gives an error.
+func readReportFiles(dir string) ([]string, error) {
+	files := os.DirFS(dir)
+
+	names, err := fs.Glob(files, "reports-*.jsonl.zst")
+	if err != nil {
+		return nil, fmt.Errorf("list report files: %w", err)
+	}
+
+	dec, err := zstd.NewReader(nil)
+	if err != nil {
+		return nil, fmt.Errorf("create zstd decoder: %w", err)
+	}
+	defer dec.Close()
+
+	contents := make([]string, 0, len(names))
+
+	for _, name := range names {
+		compressed, readErr := fs.ReadFile(files, name)
+		if readErr != nil {
+			return nil, fmt.Errorf("read %s: %w", name, readErr)
+		}
+
+		data, decErr := dec.DecodeAll(compressed, nil)
+		if decErr != nil {
+			return nil, fmt.Errorf("decompress %s: %w", name, decErr)
+		}
+
+		contents = append(contents, string(data))
+	}
+
+	return contents, nil
+}
+
+// reportFilePath returns the path in dir of a report file named as
+// written on the given day of January 2026, so that a lower day sorts
+// as older.
+func reportFilePath(dir string, day int) string {
+	return filepath.Join(dir,
+		fmt.Sprintf("reports-2026-01-%02dT00-00-00.000Z-1.jsonl.zst", day))
+}
+
+func writeBytes(t *testing.T, path string, n int) {
+	t.Helper()
+
+	err := os.WriteFile(path, make([]byte, n), 0o600)
+	if err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}
+
+func exists(t *testing.T, path string) bool {
+	t.Helper()
+
+	_, err := os.Stat(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return false
+	}
+
+	if err != nil {
+		t.Fatalf("stat %s: %v", path, err)
+	}
+
+	return true
+}
+
+func hasReportFile(t *testing.T, dir string) bool {
+	t.Helper()
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("read data dir: %v", err)
+	}
+
+	for _, e := range entries {
+		if strings.HasSuffix(e.Name(), ".jsonl.zst") {
+			info, statErr := e.Info()
+			if statErr != nil {
+				t.Fatalf("stat %s: %v", e.Name(), statErr)
+			}
+
+			if info.Size() > 0 {
+				return true
+			}
+		}
+	}
+
+	return false
+}
+
+// TestFilesDeletedOldestFirstWhenWritesOverlap holds the write of an
+// older report file open until a newer one's write completes, then
+// releases it. When room is needed, the older file is deleted first,
+// though its write was the last to complete.
+func TestFilesDeletedOldestFirstWhenWritesOverlap(t *testing.T) {
+	const maxBytes = 1000
+
+	report := map[string]string{"id": "overlap"}
+
+	t.Setenv("DATA_DIR", t.TempDir())
+	t.Setenv("DATA_DIR_MAX_BYTES", strconv.Itoa(maxBytes))
+
+	buf := startBuffer(t)
+
+	created := make(chan string)
+	release := make(chan struct{})
+
+	buf.OnFileCreated(func(f *os.File) {
+		created <- f.Name()
+
+		<-release
+	})
+
+	err := buf.Append(report)
+	if err != nil {
+		t.Fatalf("older report: %v", err)
+	}
+
+	flushed := make(chan error)
+
+	go func() { flushed <- buf.Flush() }()
+
+	older := <-created
+
+	// Only the older write is held; the newer one goes through, and
+	// so do the writes after it, the final one at stop included.
+	var newer string
+
+	buf.OnFileCreated(func(f *os.File) { newer = f.Name() })
+
+	// Errorf, not Fatalf, until the older write is released, so that a
+	// failure here does not leave it held.
+	err = buf.Append(report)
+	if err != nil {
+		t.Errorf("newer report: %v", err)
+	}
+
+	err = buf.Flush()
+	if err != nil {
+		t.Errorf("flush of the newer report: %v", err)
+	}
+
+	close(release)
+
+	err = <-flushed
+	if err != nil {
+		t.Fatalf("flush of the older report: %v", err)
+	}
+
+	info, err := os.Stat(newer)
+	if err != nil {
+		t.Fatalf("stat %s: %v", newer, err)
+	}
+
+	// A report that fits beside the newer file alone, so deleting the
+	// older one makes exactly the room it needs.
+	pad := maxBytes - int(info.Size()) - lineBytes(t, map[string]string{"id": ""})
+
+	err = buf.Append(map[string]string{"id": strings.Repeat("a", pad)})
+	if err != nil {
+		t.Fatalf("report that needs room: %v", err)
+	}
+
+	if exists(t, older) {
+		t.Fatal("older report file kept when room was needed")
+	}
+
+	if !exists(t, newer) {
+		t.Fatal("newer report file deleted before the older one")
+	}
+}

internal/server/export_test.go

@@ -0,0 +1,23 @@
+package server
+
+import "github.com/go-chi/chi/v5"
+
+// Router exposes the router to the external tests, which add routes
+// of their own to it after SetupRoutes.
+func (s *Server) Router() *chi.Mux {
+	return s.router
+}
+
+// MaxRequestBodyBytes exposes the router-wide body limit to the
+// external tests.
+const MaxRequestBodyBytes = maxRequestBodyBytes
+
+// MetricsRequestsPerMinute exposes the /metrics rate limit to the
+// external tests.
+const MetricsRequestsPerMinute = metricsRequestsPerMinute
+
+// ListenAddr exposes the address the server listens on to the
+// external tests.
+func (s *Server) ListenAddr() string {
+	return s.newHTTPServer().Addr
+}

internal/server/http.go

@@ -0,0 +1,71 @@
+package server
+
+import (
+	"errors"
+	"net"
+	"net/http"
+	"runtime"
+	"strconv"
+	"time"
+
+	"go.uber.org/fx"
+)
+
+const (
+	readTimeout       = 10 * time.Second
+	readHeaderTimeout = 5 * time.Second
+	idleTimeout       = 60 * time.Second
+	maxHeaderBytes    = 1 << 20 // 1 MiB
+
+	// requestTimeout (routes.go) is the single per-request
+	// processing budget, enforced by chi's middleware.Timeout.
+	// writeTimeout must exceed that budget so a handler can write
+	// its 503 when the chi timeout fires; if it were shorter the
+	// server would abort the write first and the chi budget would
+	// be unreachable dead configuration.
+	writeTimeout = requestTimeout + 5*time.Second
+)
+
+// newHTTPServer constructs the http.Server. It performs no I/O
+// and does not start listening.
+func (s *Server) newHTTPServer() *http.Server {
+	listenAddr := net.JoinHostPort(
+		s.params.Config.BindAddress,
+		strconv.Itoa(s.params.Config.Port),
+	)
+
+	return &http.Server{
+		Addr:              listenAddr,
+		Handler:           s,
+		MaxHeaderBytes:    maxHeaderBytes,
+		ReadTimeout:       readTimeout,
+		ReadHeaderTimeout: readHeaderTimeout,
+		WriteTimeout:      writeTimeout,
+		IdleTimeout:       idleTimeout,
+	}
+}
+
+// listenAndServe runs the listener until the server is shut
+// down. A genuine listen failure (not the expected
+// ErrServerClosed from a clean shutdown) requests process
+// shutdown through fx with a non-zero exit code, so the failure
+// is visible to any supervisor.
+func (s *Server) listenAndServe() {
+	s.log.Info("http begin listen",
+		"listenaddr", s.httpServer.Addr,
+		"version", s.params.Globals.Version,
+		"arch", runtime.GOARCH,
+	)
+
+	err := s.httpServer.ListenAndServe()
+	if err == nil || errors.Is(err, http.ErrServerClosed) {
+		return
+	}
+
+	s.log.Error("listen error", "error", err)
+
+	shutdownErr := s.shutdowner.Shutdown(fx.ExitCode(1))
+	if shutdownErr != nil {
+		s.log.Error("request shutdown failed", "error", shutdownErr)
+	}
+}

internal/server/http_test.go

@@ -0,0 +1,32 @@
+package server_test
+
+import "testing"
+
+// TestListenAddress checks that the server listens on BIND_ADDRESS
+// and PORT, and on port 8080 on every interface when neither is set.
+// The container image sets both, to keep the backend on loopback
+// behind nginx.
+func TestListenAddress(t *testing.T) {
+	tests := []struct {
+		bindAddress string
+		port        string
+		want        string
+	}{
+		{bindAddress: "", port: "", want: ":8080"},
+		{bindAddress: "127.0.0.1", port: "8081", want: "127.0.0.1:8081"},
+		{bindAddress: "::1", port: "8081", want: "[::1]:8081"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			// t.Setenv rules out t.Parallel.
+			t.Setenv("BIND_ADDRESS", tt.bindAddress)
+			t.Setenv("PORT", tt.port)
+
+			got := newServer(t).ListenAddr()
+			if got != tt.want {
+				t.Errorf("listen address = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

internal/server/routes.go

@@ -0,0 +1,85 @@
+package server
+
+import (
+	"time"
+
+	sentryhttp "github.com/getsentry/sentry-go/http"
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/collectors"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+const (
+	requestTimeout = 60 * time.Second
+
+	// maxRequestBodyBytes caps every request body. A route group
+	// can mount s.mw.MaxBodyBytes with a smaller value to lower
+	// its bound, but cannot raise it: this cap runs first.
+	maxRequestBodyBytes int64 = 1 << 20 // 1 MiB
+
+	// metricsRequestsPerMinute is how many requests to /metrics each
+	// client address may make a minute, whatever their credentials. A
+	// scraper polling every 2 seconds sends half of it, which httprate
+	// never refuses.
+	metricsRequestsPerMinute = 60
+)
+
+// SetupRoutes configures the chi router with middleware and
+// all application routes.
+func (s *Server) SetupRoutes() {
+	s.router = chi.NewRouter()
+
+	s.router.Use(s.mw.Recoverer())
+	s.router.Use(middleware.RequestID)
+	s.router.Use(s.mw.Logging())
+	s.router.Use(s.mw.SecurityHeaders())
+	s.router.Use(s.mw.CORS(s.params.Config.CORSAllowedOrigins))
+	s.router.Use(s.mw.MaxBodyBytes(maxRequestBodyBytes))
+	s.router.Use(middleware.Timeout(requestTimeout))
+
+	// Sentry reports a panic, then panics again, so that s.mw.Recoverer
+	// still answers 500.
+	if s.params.Config.SentryDSN != "" {
+		s.router.Use(sentryhttp.New(sentryhttp.Options{Repanic: true}).Handle)
+	}
+
+	// The metrics go in a registry of this server's own, not in
+	// Prometheus' default one, which takes them only once per process.
+	registry := prometheus.NewRegistry()
+	registry.MustRegister(
+		collectors.NewGoCollector(),
+		collectors.NewProcessCollector(collectors.ProcessCollectorOpts{}),
+	)
+
+	// Requests are measured only once chi has matched them to one of
+	// these routes, by path and method. The metrics are labelled with
+	// both, which any client can make up, so measuring every request
+	// would let clients add labels without bound. A Route here would
+	// be matched by its path prefix alone, so each path is given in
+	// full.
+	s.router.Group(func(r chi.Router) {
+		// config.New refuses one of the two credentials without the
+		// other.
+		if s.params.Config.MetricsUsername != "" {
+			r.Use(s.mw.Metrics(registry))
+		}
+
+		r.Get("/.well-known/healthcheck", s.h.HandleHealthCheck())
+
+		r.With(s.mw.RateLimit(s.params.Config.ReportsPerMinute)).
+			Post("/api/v1/reports", s.h.HandleReport())
+	})
+
+	// The rate limit comes before the basic auth, so a client past it
+	// gets 429 and its password is not checked.
+	if s.params.Config.MetricsUsername != "" {
+		s.router.With(
+			s.mw.RateLimit(metricsRequestsPerMinute),
+			s.mw.MetricsAuth(),
+		).Get("/metrics", promhttp.HandlerFor(
+			registry, promhttp.HandlerOpts{},
+		).ServeHTTP)
+	}
+}

internal/server/routes_test.go

@@ -0,0 +1,342 @@
+package server_test
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+	"sneak.berlin/go/netwatch/internal/server"
+
+	"github.com/getsentry/sentry-go"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+)
+
+// newServer builds a Server from the same constructors as main,
+// configured from the environment. It is never started, so nothing
+// listens.
+func newServer(t *testing.T) *server.Server {
+	t.Helper()
+
+	var srv *server.Server
+
+	app := fxtest.New(t,
+		fx.Provide(
+			config.New,
+			globals.New,
+			handlers.New,
+			healthcheck.New,
+			logger.New,
+			middleware.New,
+			reportbuf.New,
+			server.New,
+		),
+		fx.Populate(&srv),
+	)
+
+	err := app.Err()
+	if err != nil {
+		t.Fatalf("build server: %v", err)
+	}
+
+	return srv
+}
+
+// TestReportsAreRateLimited checks that POST /api/v1/reports is
+// behind the per-address rate limit, set here to two a minute.
+func TestReportsAreRateLimited(t *testing.T) {
+	t.Setenv("REPORTS_PER_MINUTE", "2")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	post := func() int {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequestWithContext(t.Context(),
+			http.MethodPost, "/api/v1/reports",
+			strings.NewReader(`{"clientId":"c1","hosts":[]}`),
+		)
+		srv.ServeHTTP(rec, req)
+
+		return rec.Code
+	}
+
+	for i := range 2 {
+		if code := post(); code != http.StatusOK {
+			t.Fatalf("report %d: status = %d, want %d",
+				i+1, code, http.StatusOK)
+		}
+	}
+
+	if code := post(); code != http.StatusTooManyRequests {
+		t.Fatalf("third report in a minute: status = %d, want %d",
+			code, http.StatusTooManyRequests)
+	}
+}
+
+// TestCORSAllowedOriginsReachTheRouter checks that an origin listed in
+// CORS_ALLOWED_ORIGINS is allowed by the router, not only when handed
+// to the CORS middleware directly.
+func TestCORSAllowedOriginsReachTheRouter(t *testing.T) {
+	const origin = "https://netwatch.example:8443"
+
+	t.Setenv("CORS_ALLOWED_ORIGINS", origin)
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	// The preflight a browser sends before it POSTs JSON from origin.
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodOptions, "/api/v1/reports", http.NoBody)
+	req.Header.Set("Origin", origin)
+	req.Header.Set("Access-Control-Request-Method", http.MethodPost)
+	req.Header.Set("Access-Control-Request-Headers", "content-type")
+	srv.ServeHTTP(rec, req)
+
+	got := rec.Header().Get("Access-Control-Allow-Origin")
+	if got != origin {
+		t.Fatalf("Access-Control-Allow-Origin = %q, want %q", got, origin)
+	}
+}
+
+// TestNoMetricsWithoutCredentials: with neither metrics setting set,
+// there is no /metrics.
+func TestNoMetricsWithoutCredentials(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "")
+	t.Setenv("METRICS_PASSWORD", "")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/metrics", http.NoBody)
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotFound)
+	}
+}
+
+// TestMetricsBehindBasicAuth: with both metrics settings set, /metrics
+// answers only with them as basic auth credentials, and shows a
+// request to a route but not one to a path no route has.
+func TestMetricsBehindBasicAuth(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prometheus")
+	t.Setenv("METRICS_PASSWORD", "right")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	get := func(path, username, password string) *httptest.ResponseRecorder {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequestWithContext(t.Context(),
+			http.MethodGet, path, http.NoBody)
+
+		if username != "" {
+			req.SetBasicAuth(username, password)
+		}
+
+		srv.ServeHTTP(rec, req)
+
+		return rec
+	}
+
+	get("/.well-known/healthcheck", "", "")
+	get("/api/v1/no-such-route", "", "")
+
+	for _, creds := range [][2]string{
+		{"", ""},
+		{"prometheus", "wrong"},
+		{"someone", "right"},
+	} {
+		rec := get("/metrics", creds[0], creds[1])
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("credentials %q: status = %d, want %d",
+				creds, rec.Code, http.StatusUnauthorized)
+		}
+	}
+
+	rec := get("/metrics", "prometheus", "right")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("right credentials: status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+
+	body := rec.Body.String()
+	if !strings.Contains(body, `handler="/.well-known/healthcheck"`) {
+		t.Errorf("metrics show no health check request:\n%s", body)
+	}
+
+	if strings.Contains(body, "no-such-route") {
+		t.Errorf("metrics show a request to a path no route has:\n%s", body)
+	}
+
+	if !strings.Contains(body, "go_goroutines") {
+		t.Errorf("metrics show no Go runtime metrics:\n%s", body)
+	}
+}
+
+// TestMetricsAreRateLimited: a client that has used up its /metrics
+// allowance on wrong passwords gets 429 even with the right one, which
+// is then not checked, while another client behind the same nginx
+// still gets in.
+func TestMetricsAreRateLimited(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prometheus")
+	t.Setenv("METRICS_PASSWORD", "right")
+	// As in the container: nginx connects from loopback and names the
+	// client in X-Forwarded-For.
+	t.Setenv("TRUSTED_PROXIES", "127.0.0.1/32")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	get := func(client, password string) int {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequestWithContext(t.Context(),
+			http.MethodGet, "/metrics", http.NoBody)
+		req.RemoteAddr = "127.0.0.1:40000"
+		req.Header.Set("X-Forwarded-For", client)
+		req.SetBasicAuth("prometheus", password)
+		srv.ServeHTTP(rec, req)
+
+		return rec.Code
+	}
+
+	for i := range server.MetricsRequestsPerMinute {
+		if code := get("203.0.113.7", "wrong"); code != http.StatusUnauthorized {
+			t.Fatalf("guess %d: status = %d, want %d",
+				i+1, code, http.StatusUnauthorized)
+		}
+	}
+
+	if code := get("203.0.113.7", "right"); code != http.StatusTooManyRequests {
+		t.Fatalf("right password past the limit: status = %d, want %d",
+			code, http.StatusTooManyRequests)
+	}
+
+	if code := get("203.0.113.8", "right"); code != http.StatusOK {
+		t.Fatalf("another client: status = %d, want %d",
+			code, http.StatusOK)
+	}
+}
+
+// TestMetricsInTwoServers: two servers in one process can both have
+// metrics on.
+func TestMetricsInTwoServers(t *testing.T) {
+	t.Setenv("METRICS_USERNAME", "prometheus")
+	t.Setenv("METRICS_PASSWORD", "right")
+
+	for range 2 {
+		newServer(t).SetupRoutes()
+	}
+}
+
+// TestSentry: with SENTRY_DSN empty there is no Sentry client. With it
+// pointing at a local server standing in for Sentry, a panic in a
+// handler reaches that server, and the request still gets the 500 from
+// the panic recovery.
+func TestSentry(t *testing.T) {
+	const panicMessage = "handler panic for TestSentry"
+
+	// sentry.Init sets the client for the whole process; take it away
+	// again so that no other test reports to Sentry.
+	t.Cleanup(func() { sentry.CurrentHub().BindClient(nil) })
+
+	t.Setenv("SENTRY_DSN", "")
+	newServer(t)
+
+	if sentry.CurrentHub().Client() != nil {
+		t.Fatal("a Sentry client exists with SENTRY_DSN empty")
+	}
+
+	// The body of the first request the stand-in for Sentry receives.
+	received := make(chan string, 1)
+
+	sentryServer := httptest.NewServer(http.HandlerFunc(
+		func(_ http.ResponseWriter, r *http.Request) {
+			body, _ := io.ReadAll(r.Body)
+
+			select {
+			case received <- string(body):
+			default:
+			}
+		},
+	))
+	defer sentryServer.Close()
+
+	t.Setenv("SENTRY_DSN",
+		"http://key@"+sentryServer.Listener.Addr().String()+"/1")
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+	srv.Router().Get("/panic", func(http.ResponseWriter, *http.Request) {
+		panic(panicMessage)
+	})
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/panic", http.NoBody)
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusInternalServerError)
+	}
+
+	// Sentry sends from a goroutine of its own.
+	select {
+	case body := <-received:
+		if !strings.Contains(body, panicMessage) {
+			t.Fatalf("the Sentry server received no report of the panic:\n%s",
+				body)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("nothing reached the Sentry server")
+	}
+}
+
+// TestHealthCheckRejectsOversizeBody sends the health check, which
+// never reads its body, a body one byte over the limit. Only the
+// router-wide body limit can reject it.
+func TestHealthCheckRejectsOversizeBody(t *testing.T) {
+	t.Parallel()
+
+	srv := newServer(t)
+	srv.SetupRoutes()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/.well-known/healthcheck",
+		strings.NewReader(
+			strings.Repeat("x", int(server.MaxRequestBodyBytes)+1),
+		),
+	)
+
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Fatalf("status = %d, want %d",
+			rec.Code, http.StatusRequestEntityTooLarge)
+	}
+
+	if got := rec.Body.String(); got != "{\"status\":\"error\"}\n" {
+		t.Errorf("body = %q, want %q", got, "{\"status\":\"error\"}\n")
+	}
+
+	got := rec.Header().Get("Content-Type")
+	if got != "application/json; charset=utf-8" {
+		t.Errorf("Content-Type = %q, want a JSON content type", got)
+	}
+}

internal/server/server.go

@@ -0,0 +1,142 @@
+// Package server provides the HTTP server lifecycle,
+// including startup, routing, and graceful shutdown. The
+// process lifetime is owned by fx: shutdown is requested
+// through fx.Shutdowner so every component's OnStop hook runs
+// in dependency order.
+package server
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+
+	"github.com/getsentry/sentry-go"
+	"github.com/go-chi/chi/v5"
+	"go.uber.org/fx"
+)
+
+// sentryFlushTimeout is how long shutdown waits for Sentry to send
+// what it still holds.
+const sentryFlushTimeout = 2 * time.Second
+
+// Params defines the dependencies for Server.
+type Params struct {
+	fx.In
+
+	Config     *config.Config
+	Globals    *globals.Globals
+	Handlers   *handlers.Handlers
+	Logger     *logger.Logger
+	Middleware *middleware.Middleware
+	Shutdowner fx.Shutdowner
+}
+
+// Server is the top-level HTTP server orchestrator.
+type Server struct {
+	h          *handlers.Handlers
+	httpServer *http.Server
+	log        *slog.Logger
+	mw         *middleware.Middleware
+	params     Params
+	router     *chi.Mux
+	shutdowner fx.Shutdowner
+}
+
+// New creates a Server and registers lifecycle hooks for
+// starting and stopping it.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Server, error) {
+	s := new(Server)
+	s.params = params
+	s.mw = params.Middleware
+	s.h = params.Handlers
+	s.log = params.Logger.Get()
+	s.shutdowner = params.Shutdowner
+
+	err := s.enableSentry()
+	if err != nil {
+		return nil, err
+	}
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			// Build the router and http.Server synchronously
+			// here, before spawning the serving goroutine, so
+			// httpServer is fully constructed by the time OnStop
+			// (or an early signal) can read it. fx guarantees
+			// OnStart returns before OnStop runs, so no
+			// synchronization or nil check is needed at shutdown.
+			s.SetupRoutes()
+			s.httpServer = s.newHTTPServer()
+
+			go s.listenAndServe()
+
+			return nil
+		},
+		OnStop: func(ctx context.Context) error {
+			return s.shutdown(ctx)
+		},
+	})
+
+	return s, nil
+}
+
+// ServeHTTP delegates to the chi router.
+func (s *Server) ServeHTTP(
+	w http.ResponseWriter,
+	r *http.Request,
+) {
+	s.router.ServeHTTP(w, r)
+}
+
+// enableSentry sets Sentry up when SENTRY_DSN is set, so that
+// SetupRoutes can report panics to it. With SENTRY_DSN empty it does
+// nothing. A DSN Sentry refuses stops the start.
+func (s *Server) enableSentry() error {
+	if s.params.Config.SentryDSN == "" {
+		return nil
+	}
+
+	err := sentry.Init(sentry.ClientOptions{
+		Dsn:     s.params.Config.SentryDSN,
+		Release: s.params.Globals.Appname + "-" + s.params.Globals.Version,
+	})
+	if err != nil {
+		return fmt.Errorf("SENTRY_DSN: %w", err)
+	}
+
+	s.log.Info("sentry error reporting activated")
+
+	return nil
+}
+
+// shutdown gracefully stops the HTTP server within the
+// deadline of the context fx provides for OnStop, then gives
+// Sentry, if set up, time to send what it still holds.
+func (s *Server) shutdown(ctx context.Context) error {
+	err := s.httpServer.Shutdown(ctx)
+
+	if s.params.Config.SentryDSN != "" {
+		sentry.Flush(sentryFlushTimeout)
+	}
+
+	if err != nil {
+		s.log.Error("server clean shutdown failed", "error", err)
+
+		return err
+	}
+
+	s.log.Info("server stopped")
+
+	return nil
+}