Record the gomodguard_v2 migration in TODO.md (closes #57)

Adds the Completed Steps entry for re-vendoring the canonical
.golangci.yml, which switches off the deprecated gomodguard and runs
gomodguard_v2 and depguard in its place.

Model: opus-5-5

.golangci.yml

@@ -10,14 +10,20 @@ run:
 
 linters:
   default: all
+  enable:
+    # Successor to the deprecated gomodguard. Named explicitly, rather than
+    # left to `default: all`, because it carries the module policy below.
+    - gomodguard_v2
   disable:
     # Genuinely incompatible with project patterns
     - exhaustruct      # Requires all struct fields
-    - depguard         # Dependency allow/block lists
     - godot            # Requires comments to end with periods
-    - wsl              # Deprecated, replaced by wsl_v5
     - wrapcheck        # Too verbose for internal packages
     - varnamelen       # Short names like db, id are idiomatic Go
+    # Deprecated: the warning is attached to the old name, so it is
+    # silenced by disabling that name, not by enabling the successor.
+    - wsl              # Deprecated, replaced by wsl_v5
+    - gomodguard       # Deprecated, replaced by gomodguard_v2
   settings:
     lll:
       line-length: 88
@@ -28,6 +34,64 @@ linters:
       max-complexity: 15
     dupl:
       threshold: 100
+    depguard:
+      # Test-support code must not be compiled into the shipped binary. A
+      # test-support package exists to hand a test privileges the program
+      # itself must never have, so a file that is not a test must not import
+      # one. Test files, and the files inside a package whose directory name
+      # ends in `test`, are where that code belongs, and are exempt.
+      #
+      # The deny list below is the one part of this file a repository is
+      # expected to extend, and the only part it may. depguard matches an
+      # import path against a list of prefixes, so it cannot be told "any path
+      # whose last segment ends in test"; a repository's own test-support
+      # packages have to be named here one at a time, by full import path,
+      # under a module path that differs from repository to repository. Add
+      # them; change nothing else.
+      rules:
+        test-support:
+          list-mode: lax
+          files:
+            - "$all"
+            - "!$test"
+            - "!**/*test/**"
+          deny:
+            - pkg: net/http/httptest
+              desc: >-
+                Test-support code belongs in test files and in packages whose
+                directory name ends in test, not in the shipped binary.
+    # Only decisions already recorded in the Go package defaults are
+    # listed here. Every entry matches the module path exactly.
+    gomodguard_v2:
+      blocked:
+        - module: github.com/rs/zerolog
+          recommendations:
+            - log/slog
+          reason: "Structured logging is stdlib log/slog."
+        # One entry per pre-fork module path, because the later releases
+        # are separate paths. A prefix match would be shorter but would
+        # also reach github.com/go-redis/redismock, the test double for
+        # the successor these entries recommend.
+        - module: github.com/go-redis/redis
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v7
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/go-redis/redis/v8
+          recommendations:
+            - github.com/redis/go-redis/v9
+          reason: "Pre-fork module; use the maintained go-redis v9."
+        - module: github.com/sergi/go-diff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "No unified diff output; use go-udiff."
+        - module: github.com/hexops/gotextdiff
+          recommendations:
+            - github.com/aymanbagabas/go-udiff
+          reason: "Unmaintained fork; use go-udiff."
 
 issues:
   max-issues-per-linter: 0

README.md

@@ -34,6 +34,65 @@ else has a built-in default. A config file mounted at `/etc/pixa/config.yml`
 is optional: it is read when present, and an environment variable wins over
 the same setting in it.
 
+## Deployment
+
+pixa listens on plain HTTP and runs behind a reverse proxy that terminates TLS.
+[`configs/Caddyfile`](configs/Caddyfile) is an example for Caddy, chosen because
+it is the smallest correct one: Caddy gets the TLS certificate itself and does
+everything in this list without further settings. The reverse proxy must:
+
+- terminate TLS, as the login and generator pages work only over HTTPS (see
+  Routes);
+- pass the `Host`, `Origin` and `Referer` headers on unchanged, as pixa refuses
+  a form from those pages unless `Origin` or `Referer` names the host in `Host`,
+  and builds encrypted URLs from `Host`;
+- set `X-Forwarded-For` to the client's address, with `trusted_proxies` set to
+  the address pixa sees the proxy's requests come from, so the login limit
+  counts each client by its own address (see `trusted_proxies` under
+  Configuration);
+- wait for pixa's answer for at least `downstream_timeout` (default `60s`), the
+  longest pixa takes to fetch, convert and send an image.
+
+It may also refuse `/metrics`, as the example does, so that only a scraper that
+reaches pixa directly can read it; pixa itself asks for the metrics username and
+password there.
+
+pixa does the rest itself: it checks signatures and encrypted URLs, applies the
+allowlist, refuses upstream hosts with private or local addresses, limits login
+attempts, upstream response size and image dimensions, and sends the security
+headers, `Strict-Transport-Security` included, with every response.
+
+The state directory (`state_dir`, `/var/lib/pixa` in the container) holds the
+database and the disk cache:
+
+- It needs a persistent volume: without one, every restart starts with an empty
+  cache. In the container, the startup script gives the directory to the user
+  pixa runs as (uid 65532) and sets its mode to `750`; outside it, that user
+  must be able to write the directory.
+- `cache_max_bytes` limits the source and transformed images together. The
+  database, the metadata files, the `.meta` file beside each transformed image
+  and files still being written come on top, and eviction runs in the
+  background, so the cache can pass the limit for a while: leave room on the
+  volume beyond it.
+- Set `cache_max_bytes` for a lasting deployment. Its default is 75% of the
+  space free when pixa starts, which the cache's own files reduce, so a fuller
+  cache gives a smaller limit after a restart.
+
+A load balancer's health check can request `/.well-known/healthcheck.json`,
+which answers 200 whenever pixa is running, in maintenance mode too (see
+`maintenance_mode`).
+
+On SIGTERM or SIGINT pixa stops accepting connections, gives the requests in
+progress and the images being processed 5 seconds to finish, and exits: with 0,
+or with 1 when images were still being processed after those 5 seconds or
+another part of pixa failed to stop. A request not finished by then is cut off.
+`docker stop` waits 10 seconds before it kills the container.
+
+Outside Docker, pixa needs libvips (the image has 8.15) and libheif to run, as
+it uses libvips through CGO; building it also needs their development files,
+`pkg-config` and a C compiler. `script/bootstrap` installs all of these with
+nix, apt, brew or apk.
+
 ## Running under upaas
 
 What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
@@ -354,10 +413,10 @@ pixa finds: `/etc/pixa/config.yml`, `/etc/pixa/config.yaml`,
 `~/.config/pixa/config.yml`, `~/.config/pixa/config.yaml`, then `config.yml`
 and `config.yaml` in the working directory. A named file that does not exist,
 cannot be read or does not parse aborts startup. Of the files pixa looks for on
-its own, only one that does not exist is passed over, without a message. One
-that pixa cannot read or parse aborts startup, naming the file. So does one in a
-directory pixa may not enter, whether or not it is there, since pixa cannot
-tell. With no file, pixa uses the environment and the defaults.
+its own, one it finds but cannot read or parse aborts startup; one it cannot
+find, for any reason, is passed over without a message, even when the file is
+there in a directory pixa may not enter. With no file, pixa uses the environment
+and the defaults.
 
 | Variable                             | Config key                      | Meaning                                                                      |
 | ------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------- |

TODO.md

@@ -29,11 +29,20 @@ P2: security: referer blacklist
 
 # Completed Steps
 
-- 2026-10-04 a config file pixa cannot read aborts startup (closes #176): of the
-  places pixa looks for its config file on its own, only one where the file does
-  not exist is passed over; any other error, such as a directory on the path
-  that pixa may not enter, aborts startup naming the file, as a file that does
-  not parse already did.
+- 2026-10-04 `.golangci.yml` re-vendored from the canonical copy (closes #57):
+  the deprecated `gomodguard` is switched off, so lint runs print no
+  deprecation warning; its successor `gomodguard_v2` runs with the shared
+  module block list, and `depguard` keeps `net/http/httptest` out of files that
+  are not tests. The tree needed no code changes.
+- 2026-10-04 deployment guide and example Caddy config (closes #89):
+  "Deployment" in `README.md` says what the reverse proxy in front of pixa must
+  do (terminate TLS; pass `Host`, `Origin` and `Referer` on unchanged; set
+  `X-Forwarded-For`, with `trusted_proxies` to match; wait at least
+  `downstream_timeout`; optionally refuse `/metrics`) and what pixa does itself,
+  that the state directory needs a persistent volume and what `cache_max_bytes`
+  counts, the health check for a load balancer, what a stop does and its exit
+  codes, and what running outside Docker needs; `configs/Caddyfile` is the
+  example, checked with `caddy validate`.
 - 2026-10-04 the metrics basic auth, CORS preflight, request logging and
   metrics recording have tests (closes #79): `MetricsAuth` on its own answers
   401 with a challenge without credentials or with a wrong username or password
@@ -490,6 +499,3 @@ P2: security: referer blacklist
     - Prometheus performance metrics
     - integration tests for the image proxy flow
     - load tests to verify the 1k to 5k req/s target
-- P2: documentation
-    - deployment guide
-    - example nginx or caddy reverse proxy config

configs/Caddyfile

@@ -0,0 +1,17 @@
+# Example Caddy config for running pixa behind Caddy; see "Deployment" in
+# README.md. Replace images.example.com with pixa's public host name, and
+# 127.0.0.1:8080 with the address Caddy reaches pixa on.
+#
+# Caddy gets and renews the TLS certificate for the host name, passes the
+# Host, Origin and Referer headers on unchanged, sets X-Forwarded-For to the
+# client's address, and waits for pixa's answer with no time limit of its
+# own, so pixa's downstream_timeout is what ends a slow request.
+
+images.example.com
+
+# pixa asks for metrics.username and metrics.password on /metrics. This
+# line also keeps it off the public address, for a scraper that reaches
+# pixa directly; remove it to read /metrics through Caddy.
+respond /metrics 404
+
+reverse_proxy 127.0.0.1:8080

internal/config/config.go

@@ -4,7 +4,6 @@ package config
 import (
 	"errors"
 	"fmt"
-	"io/fs"
 	"log/slog"
 	"math"
 	"net/netip"
@@ -779,25 +778,19 @@ func loadConfigFile(log *slog.Logger, appName string) (*smartconfig.Config, erro
 	for _, path := range configPaths {
 		cleanPath := filepath.Clean(path)
 
-		// Only a config file that does not exist is skipped. One that
-		// cannot be read or does not parse is a fatal startup error.
 		_, statErr := os.Stat(cleanPath)
-		if errors.Is(statErr, fs.ErrNotExist) {
-			continue
+		if statErr == nil {
+			// A config file that exists but does not parse is a fatal
+			// startup error, never something to skip over.
+			sc, err := smartconfig.NewFromConfigPath(path)
+			if err != nil {
+				return nil, fmt.Errorf("failed to parse config file %s: %w", path, err)
+			}
+
+			log.Info("loaded config file", "path", path)
+
+			return sc, nil
 		}
-
-		if statErr != nil {
-			return nil, fmt.Errorf("failed to read config file %s: %w", path, statErr)
-		}
-
-		sc, err := smartconfig.NewFromConfigPath(path)
-		if err != nil {
-			return nil, fmt.Errorf("failed to parse config file %s: %w", path, err)
-		}
-
-		log.Info("loaded config file", "path", path)
-
-		return sc, nil
 	}
 
 	return nil, nil //nolint:nilnil // nil config is valid (use defaults)

internal/config/config_validation_internal_test.go

@@ -564,116 +564,6 @@ func TestMalformedConfigFileAbortsStartup(t *testing.T) {
 	t.Logf("got expected error: %v", err)
 }
 
-// TestConfigFileInDirectoryPixaMayNotEnterAbortsStartup checks that a
-// config file pixa cannot read because it may not enter its directory
-// aborts startup instead of being passed over.
-func TestConfigFileInDirectoryPixaMayNotEnterAbortsStartup(t *testing.T) {
-	if os.Geteuid() == 0 {
-		t.Skip("root may enter any directory")
-	}
-
-	home := t.TempDir()
-	configDir := filepath.Join(home, ".config", "pixa-test-nonexistent-app")
-	configPath := filepath.Join(configDir, "config.yml")
-
-	err := os.MkdirAll(configDir, 0o700)
-	if err != nil {
-		t.Fatalf("failed to create config directory: %v", err)
-	}
-
-	err = os.WriteFile(configPath, []byte(signingKeyLine), 0o600)
-	if err != nil {
-		t.Fatalf("failed to write config: %v", err)
-	}
-
-	err = os.Chmod(configDir, 0)
-	if err != nil {
-		t.Fatalf("failed to remove the config directory's permissions: %v", err)
-	}
-
-	// Give the directory back its permissions so t.TempDir can remove it.
-	t.Cleanup(func() {
-		//nolint:gosec // G302: a directory needs its execute bit to be removed
-		_ = os.Chmod(configDir, 0o700)
-	})
-
-	// The ~/.config candidate is the only one that exists: the appname
-	// rules out /etc, and the working directory is empty.
-	t.Setenv("PIXA_CONFIG_PATH", "")
-	t.Setenv("HOME", home)
-	t.Chdir(t.TempDir())
-
-	log := slog.New(slog.DiscardHandler)
-
-	sc, err := loadConfigFile(log, "pixa-test-nonexistent-app")
-	if err == nil {
-		t.Fatalf("config file pixa cannot read must abort startup, got config: %v",
-			sc)
-	}
-
-	t.Logf("got expected error: %v", err)
-
-	if !strings.Contains(err.Error(), configPath) {
-		t.Errorf("error %q does not name the config file %s", err.Error(), configPath)
-	}
-}
-
-// TestConfigFileLinkingToItselfAbortsStartup checks that a config file
-// pixa cannot read for a reason other than not existing aborts startup,
-// as root too: a symbolic link to itself fails with "too many levels of
-// symbolic links".
-func TestConfigFileLinkingToItselfAbortsStartup(t *testing.T) {
-	workDir := t.TempDir()
-
-	err := os.Symlink("config.yml", filepath.Join(workDir, "config.yml"))
-	if err != nil {
-		t.Fatalf("failed to create symbolic link: %v", err)
-	}
-
-	// Only the working directory's config.yml is there: the appname rules
-	// out /etc, and HOME is empty.
-	t.Setenv("PIXA_CONFIG_PATH", "")
-	t.Setenv("HOME", t.TempDir())
-	t.Chdir(workDir)
-
-	log := slog.New(slog.DiscardHandler)
-
-	sc, err := loadConfigFile(log, "pixa-test-nonexistent-app")
-	if err == nil {
-		t.Fatalf("config file pixa cannot read must abort startup, got config: %v",
-			sc)
-	}
-
-	t.Logf("got expected error: %v", err)
-
-	if !strings.Contains(err.Error(), "config.yml") {
-		t.Errorf("error %q does not name the config file config.yml", err.Error())
-	}
-}
-
-// TestConfigPathThroughFileIsPassedOver checks that a config file path
-// that runs through a file, such as one under a HOME of /dev/null, is
-// passed over like one that does not exist, since no file can be there.
-func TestConfigPathThroughFileIsPassedOver(t *testing.T) {
-	// No config file is there: the appname rules out /etc, HOME is
-	// /dev/null, and the working directory is empty.
-	t.Setenv("PIXA_CONFIG_PATH", "")
-	t.Setenv("HOME", os.DevNull)
-	t.Chdir(t.TempDir())
-
-	log := slog.New(slog.DiscardHandler)
-
-	sc, err := loadConfigFile(log, "pixa-test-nonexistent-app")
-	if err != nil {
-		t.Fatalf("a config path through a file must be passed over, got error: %v",
-			err)
-	}
-
-	if sc != nil {
-		t.Errorf("expected no config file, got config: %v", sc)
-	}
-}
-
 func TestEnsureStateDirCreatesDirectory(t *testing.T) {
 	t.Parallel()