Stop waiting for count writes after a request's deadline (closes #224)

TestService_Get_ReturnsByItsDeadline failed on a busy host because its
request, past its deadline, still waited for its miss count to be
written, a database write with no deadline; in pixad that write waits
for the one database connection every request shares. The hit, miss,
upstream fetch and transform counts are now each written in a goroutine
of their own, which the request waits for only until its deadline; a
count not written by then is written after it returns. Shutdown waits
for those writes within ShutdownTimeout and reports any left unfinished.
The test phase also runs go test with -parallel 4: on a busy host, as
many tests at once as there are CPUs wait so long to be scheduled that
a timed request can fail.

Model: opus-5-5

.dockerignore

@@ -1,12 +1,73 @@
-# .git is sent without its config. Without a VERSION build argument the
-# stage that compiles runs `git describe --tags --always` on .git, which
-# does not need .git/config; that file can hold a credential, such as a
+# .dockerignore does NOT use .gitignore semantics. Docker matches with
+# moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
+# `/` and an unprefixed pattern is anchored at the context root. Every
+# depth-independent pattern therefore needs `**/`, or `config/.env` and
+# `certs/server.key` still ship while this file reads as solved. Only
+# genuinely root-anchored entries go unprefixed. Never transplant these
+# into .gitignore, where `**/` is wrong.
+#
+# Matching is case-sensitive, so secrets use character ranges rather
+# than an ALL-CAPS twin, which would still miss `Server.Key`.
+#
+# Extend with this repo's own host-built artifacts, written anchored:
+# `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
+# deletes the package directory from the context.
+
+# Unlike the standard file, which leaves out all of .git, pixa sends
+# .git without its config. Without a VERSION build argument the stage
+# that compiles runs `git describe --tags --always` on .git, which does
+# not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
 .git/config
-.gitignore
-.DS_Store
-.env*
+
+# Agent scratch: one full checkout of the repo per in-flight agent.
+# Anchored because it occurs once where agents run at the repo root.
+# KNOWN GAP: a repo running agents in subdirectories still ships
+# `services/api/.claude/` and must add its own anchored entry.
 .claude
-node_modules
-bin/
-data/
+
+# Environment files. `*.env` covers bare `.env` and the `prod.env`
+# convention. Re-include a committed template with a negation if the
+# build needs one: `!docs/example.env`.
+**/*.[eE][nN][vV]
+**/.[eE][nN][vV].*
+**/.[eE][nN][vV][rR][cC]
+
+# Private keys and the bundles carrying them. Public certificates
+# (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
+**/*.[pP][eE][mM]
+**/*.[kK][eE][yY]
+**/*.[pP]12
+**/*.[pP][fF][xX]
+**/[iI][dD]_[rR][sS][aA]
+**/[iI][dD]_[dD][sS][aA]
+**/[iI][dD]_[eE][cC][dD][sS][aA]
+**/[iI][dD]_[eE][dD]25519
+
+# Dependencies: restored inside the image, never copied in.
+**/node_modules
+
+# OS metadata.
+**/.DS_Store
+**/Thumbs.db
+
+# Editor state: never a build input, and it churns COPY.
+**/*.swp
+**/*.swo
+**/*~
+**/*.bak
+**/.idea
+**/.vscode
+**/*.sublime-*
+
+# pixa's own entries. Nothing in the build reads .gitignore. On the
+# host, `make build` writes bin/pixad, and the example config keeps its
+# state directory in data/.
+.gitignore
+/bin
+/data
+
+# Local config files, kept out of git because they can hold the signing key.
+**/[cC][oO][nN][fF][iI][gG].[yY][mM][lL]
+**/[cC][oO][nN][fF][iI][gG].[yY][aA][mM][lL]
+**/[cC][oO][nN][fF][iI][gG].[dD][eE][vV].[yY][mM][lL]

.gitattributes

@@ -0,0 +1,4 @@
+# Every PR adds an entry at the top of TODO.md's Completed Steps; union keeps
+# both sides instead of conflicting. Git never reports a conflict here: read
+# the merged entries after every merge or rebase.
+TODO.md merge=union

.gitea/workflows/check.yml

@@ -6,5 +6,10 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+              # The default clone is shallow and has no tags, so the
+              # version the build takes from `git describe` would be a
+              # bare commit; this fetches the whole history with its tags.
+              with:
+                  fetch-depth: 0
             - run: script/cibuild
             - run: script/docker-smoke

.gitignore

@@ -11,6 +11,12 @@ Thumbs.db
 .vscode/
 *.sublime-*
 
+# Agent scratch (worktrees of this repo, created and destroyed by
+# in-flight tooling). Unanchored: .gitignore patterns already match at
+# every depth, so no prefix is wanted here. This is not a .dockerignore
+# entry and must not be given a `**/` prefix on the way into one.
+.claude/
+
 # Environment / secrets
 .env
 .env.*
@@ -31,5 +37,6 @@ node_modules/
 *.sqlite3
 
 # Local dev configs
+config.yml
 config.yaml
 config.dev.yml

.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

.prettierignore

@@ -0,0 +1,7 @@
+node_modules/
+yarn.lock
+
+# A byte-for-byte copy of the one in sneak/prompts.
+REPO_POLICIES.md
+
+vendor/

.prettierrc

@@ -0,0 +1,4 @@
+{
+    "tabWidth": 4,
+    "proseWrap": "always"
+}

CLAUDE.md

@@ -4,73 +4,68 @@ Last Updated 2026-01-08
 
 These rules MUST be followed at all times, it is very important.
 
-* Never use `git add -A` - add specific changes to a deliberate commit. A
-  commit should contain one change. After each change, make a commit with a
-  good one-line summary.
+- Never use `git add -A` - add specific changes to a deliberate commit. A commit
+  should contain one change. After each change, make a commit with a good
+  one-line summary.
 
-* NEVER modify the linter config without asking first.
+- NEVER modify the linter config without asking first.
 
-* NEVER modify tests to exclude special cases or otherwise get them to pass
-  without asking first. In almost all cases, the code should be changed,
-  NOT the tests. If you think the test needs to be changed, make your case
-  for that and ask for permission to proceed, then stop. You need explicit
-  user approval to modify existing tests. (You do not need user approval
-  for writing NEW tests.)
+- NEVER modify tests to exclude special cases or otherwise get them to pass
+  without asking first. In almost all cases, the code should be changed, NOT the
+  tests. If you think the test needs to be changed, make your case for that and
+  ask for permission to proceed, then stop. You need explicit user approval to
+  modify existing tests. (You do not need user approval for writing NEW tests.)
 
-* When linting, assume the linter config is CORRECT, and that each item
-  output by the linter is something that legitimately needs fixing in the
-  code.
+- When linting, assume the linter config is CORRECT, and that each item output
+  by the linter is something that legitimately needs fixing in the code.
 
-* When running tests, use `make test`.
+- When running tests, use `make test`.
 
-* Before commits, run `make check`. This runs `make lint` and `make test`
-  and `make check-fmt`. Any issues discovered MUST be resolved before
-  committing unless explicitly told otherwise.
+- Before commits, run `make check`. This runs `make lint` and `make test` and
+  `make check-fmt`. Any issues discovered MUST be resolved before committing
+  unless explicitly told otherwise.
 
-* When fixing a bug, write a failing test for the bug FIRST. Add
-  appropriate logging to the test to ensure it is written correctly. Commit
-  that. Then go about fixing the bug until the test passes (without
-  modifying the test further). Then commit that.
+- When fixing a bug, write a failing test for the bug FIRST. Add appropriate
+  logging to the test to ensure it is written correctly. Commit that. Then go
+  about fixing the bug until the test passes (without modifying the test
+  further). Then commit that.
 
-* When adding a new feature, do the same - implement a test first (TDD). It
-  doesn't have to be super complex. Commit the test, then commit the
-  feature.
+- When adding a new feature, do the same - implement a test first (TDD). It
+  doesn't have to be super complex. Commit the test, then commit the feature.
 
-* When adding a new feature, use a feature branch. When the feature is
-  completely finished and the code is up to standards (passes `make check`)
-  then and only then can the feature branch be merged into `main` and the
-  branch deleted.
+- When adding a new feature, use a feature branch. When the feature is
+  completely finished and the code is up to standards (passes `make check`) then
+  and only then can the feature branch be merged into `main` and the branch
+  deleted.
 
-* Write godoc documentation comments for all exported types and functions as
-  you go along.
+- Write godoc documentation comments for all exported types and functions as you
+  go along.
 
-* ALWAYS be consistent in naming. If you name something one thing in one
-  place, name it the EXACT SAME THING in another place.
+- ALWAYS be consistent in naming. If you name something one thing in one place,
+  name it the EXACT SAME THING in another place.
 
-* Be descriptive and specific in naming. `wl` is bad;
-  `SourceHostWhitelist` is good. `ConnsPerHost` is bad;
-  `MaxConnectionsPerHost` is good.
+- Be descriptive and specific in naming. `wl` is bad; `SourceHostWhitelist` is
+  good. `ConnsPerHost` is bad; `MaxConnectionsPerHost` is good.
 
-* This is not prototype or teaching code - this is designed for production.
-  Any security issues (such as denial of service) or other web
-  vulnerabilities are P1 bugs and must be added to TODO.md at the top.
+- This is not prototype or teaching code - this is designed for production. Any
+  security issues (such as denial of service) or other web vulnerabilities are
+  P1 bugs and must be added to TODO.md at the top.
 
-* As this is production code, no stubbing of implementations unless
-  specifically instructed. We need working implementations.
+- As this is production code, no stubbing of implementations unless specifically
+  instructed. We need working implementations.
 
-* NEVER silently fall back to a different setting when a user's parameter
-  explicitly specifies a value. If a user requests format=webp and WebP
-  encoding is not supported, return an error - do NOT silently output PNG
-  instead. If a user specifies fit=invalid and that fit mode doesn't exist,
-  return an error - do NOT silently default to "cover". Silent fallbacks
-  violate the principle of least surprise and mask bugs. The only acceptable
-  defaults are for OMITTED parameters, never for INVALID explicit values.
+- NEVER silently fall back to a different setting when a user's parameter
+  explicitly specifies a value. If a user requests format=webp and WebP encoding
+  is not supported, return an error - do NOT silently output PNG instead. If a
+  user specifies fit=invalid and that fit mode doesn't exist, return an error -
+  do NOT silently default to "cover". Silent fallbacks violate the principle of
+  least surprise and mask bugs. The only acceptable defaults are for OMITTED
+  parameters, never for INVALID explicit values.
 
-* Avoid vendoring deps unless specifically instructed to.  NEVER commit
-  the vendor directory, NEVER commit compiled binaries.  If these
-  directories or files exist, add them to .gitignore (and commit the
-  .gitignore) if they are not already in there.  Keep the entire git
-  repository (with history) small - under 20MiB, unless you specifically
-  must commit larger files (e.g. test fixture example media files).  Only
-  OUR source code and immediately supporting files (such as test examples)
-  goes into the repo/history.
+- Avoid vendoring deps unless specifically instructed to. NEVER commit the
+  vendor directory, NEVER commit compiled binaries. If these directories or
+  files exist, add them to .gitignore (and commit the .gitignore) if they are
+  not already in there. Keep the entire git repository (with history) small -
+  under 20MiB, unless you specifically must commit larger files (e.g. test
+  fixture example media files). Only OUR source code and immediately supporting
+  files (such as test examples) goes into the repo/history.

Dockerfile

@@ -1,55 +1,66 @@
-# Lint stage
-# Same image as Dockerfile.lint: change both pins together.
-# golangci/golangci-lint:v2.12.2-alpine, 2026-08-07
-FROM golangci/golangci-lint:v2.12.2-alpine@sha256:91b27804074a0bacea298707f016911e60cf0cdbc6c7bf5ccacb5f0606d18d60 AS lint
+# Lint phase. script/lint builds it alone. The linter is run directly:
+# `make lint` and script/lint are themselves a docker build.
+# golangci/golangci-lint:v2.12.2, 2026-10-04
+FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
+
+# The linter compiles every package, and govips needs the libvips
+# headers for that. REPO_POLICIES.md has the lint phase install them
+# itself; this image is Debian, so with apt-get rather than apk.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libvips-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN golangci-lint run --config .golangci.yml ./...
+
+# Test phase. script/test builds it alone.
+# golang:1.25.4-alpine3.22, 2026-02-25; the runtime stage uses Alpine 3.22 too
+FROM golang:1.25.4-alpine3.22@sha256:d3f0cf7723f3429e3f9ed846243970b20a2de7bae6a5b66fc5914e228d831bbb AS test
 
 WORKDIR /src
 
-# script/bootstrap installs the build dependencies and downloads the Go
-# modules. Only script/, go.mod and go.sum are copied first, so this
-# layer is reused until one of them changes.
+# script/bootstrap --cgo installs the build dependencies (a C compiler,
+# the libvips and libheif headers, and libvips' JPEG XL support, which
+# the tests need) and downloads the Go modules.
 COPY script/ ./script/
 COPY go.mod go.sum ./
-RUN script/bootstrap
+RUN script/bootstrap --cgo
 
-# Copy source code
 COPY . .
 
-# Tells script/lint it is inside a container, so it runs the linter.
-ENV container=docker
+# Without -v first; on a failure, again with -v for the details, and
+# the step fails even if the second run passes. -parallel 4: by default
+# a package runs as many of its tests at once as the host has CPUs, and
+# on a busy host they then wait so long to be scheduled that a test
+# that times a request can see it return a second late.
+RUN go test -count=1 -timeout 90s -race -parallel 4 -cover ./... || \
+    { echo "--- Rerunning with -v for details ---"; \
+      go test -count=1 -timeout 90s -race -parallel 4 -v ./...; exit 1; }
 
-# Run formatting check and linter. script/cibuild and script/docker pass
-# a new CHECK_EPOCH on every run, and each check step names it in its
-# command, so a new value reruns the step instead of reusing a cached
-# success that checked nothing. A plain `docker build .` leaves it empty
-# and reuses the check steps only for an identical build context.
-ARG CHECK_EPOCH
-RUN echo "check epoch: ${CHECK_EPOCH}" && make fmt-check
-RUN echo "check epoch: ${CHECK_EPOCH}" && make lint
+# Build stage. Nothing is wanted from the two phases above: these copies
+# make BuildKit build them first, so this stage runs only when lint and
+# test passed.
+# golang:1.25.4-alpine3.22, 2026-02-25; the runtime stage uses Alpine 3.22 too
+FROM golang:1.25.4-alpine3.22@sha256:d3f0cf7723f3429e3f9ed846243970b20a2de7bae6a5b66fc5914e228d831bbb AS builder
 
-# Build stage
-# golang:1.25.4-alpine, 2026-02-25
-FROM golang:1.25.4-alpine@sha256:d3f0cf7723f3429e3f9ed846243970b20a2de7bae6a5b66fc5914e228d831bbb AS builder
-
-# Depend on lint stage passing
 COPY --from=lint /src/go.sum /dev/null
+COPY --from=test /src/go.sum /dev/null
 
 WORKDIR /src
 
-# Build dependencies and Go modules, as in the lint stage
+# Build dependencies and Go modules, as in the test phase
 COPY script/ ./script/
 COPY go.mod go.sum ./
-RUN script/bootstrap
+RUN script/bootstrap --cgo
 
 # Copy source code
 COPY . .
 
-# Run tests; a new CHECK_EPOCH reruns them, as in the lint stage.
-ARG CHECK_EPOCH
-RUN echo "check epoch: ${CHECK_EPOCH}" && make test
-
 # VERSION is declared here, not earlier: a new value reruns only the
-# build, not script/bootstrap or the tests. Given none, the version is
+# build, not script/bootstrap. Given none, the version is
 # `git describe --tags --always` of the .git in the build context (git
 # comes from script/bootstrap): the tag on a tagged commit, tag-N-gHASH
 # after one, the short commit when no tag is reachable. A context that
@@ -68,13 +79,18 @@ RUN version="${VERSION:-$(git describe --tags --always)}"; \
         -ldflags "-s -w -X main.Version=${version}" \
         -o /pixad ./cmd/pixad
 
-# Runtime stage
-# alpine:3.21, 2026-02-25
-FROM alpine:3.21@sha256:c3f8e73fdb79deaebaa2037150150191b9dcbfba68b4a46d70103204c53f4709
+# Runtime stage, and the last one: a plain `docker build .` builds this
+# stage and what it depends on, and nothing else. It must use the Alpine
+# release the golang image above is based on, so that pixad runs against
+# the libvips and musl it was built with.
+# alpine:3.22, 2026-10-08
+FROM alpine:3.22@sha256:5291449c3df73caf6ed85e649dec1b9e818b39a5d8c871e97afc13e9cd5e8fa8
 
-# Install runtime dependencies only
+# Install runtime dependencies only. vips-jxl is libvips' JPEG XL
+# support, without which pixad does not start.
 RUN apk add --no-cache \
     vips \
+    vips-jxl \
     libheif \
     ca-certificates \
     tzdata \

Dockerfile.lint

@@ -1,34 +0,0 @@
-# Dockerfile.lint: the container script/lint builds to run golangci-lint,
-# which is never installed on the host. Pinned to the same image as the
-# Dockerfile lint stage: change both pins together, or the two run
-# different linter versions.
-#
-# golangci/golangci-lint:v2.12.2-alpine, 2026-08-07
-FROM golangci/golangci-lint:v2.12.2-alpine@sha256:91b27804074a0bacea298707f016911e60cf0cdbc6c7bf5ccacb5f0606d18d60
-
-WORKDIR /src
-
-# pixa is CGO/libvips: the type-aware linters compile every package, so
-# this image needs the same C libraries the build does. script/bootstrap
-# installs them and downloads the Go modules. Only script/, go.mod and
-# go.sum are copied first; they settle this layer's result, so it may
-# safely be reused between runs.
-COPY script/ ./script/
-COPY go.mod go.sum ./
-RUN script/bootstrap
-
-COPY . .
-
-# Tells script/lint it is inside a container, so it runs the linter.
-ENV container=docker
-
-# script/lint passes a different CACHEBUST on every run, and BuildKit
-# keys every RUN after this ARG on its value, so the lint step always
-# runs instead of returning a cached success that linted nothing.
-#
-# Go's and golangci-lint's caches (/root/.cache, hundreds of MB) go on a
-# tmpfs that is discarded after the step. Written into the layer, they
-# would pile up as build cache on every run, since no later run, with
-# its new CACHEBUST, can reuse that layer.
-ARG CACHEBUST
-RUN --mount=type=tmpfs,target=/root/.cache script/lint

Makefile

@@ -1,10 +1,10 @@
-.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-smoke docker-versioned docker-test devserver devserver-stop hooks
+.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-smoke docker-versioned docker-test devserver devserver-stop hooks loadtest
 
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS := -X main.Version=$(VERSION)
 
 # Use nix-shell to provide CGO dependencies unless they are already available
-# (e.g. inside a Docker build or an existing nix-shell).
+# (e.g. inside an existing nix-shell).
 HAS_PKGCONFIG := $(shell command -v pkg-config 2>/dev/null)
 ifdef HAS_PKGCONFIG
   NIX_RUN_PREFIX =
@@ -32,11 +32,11 @@ fmt-check:
 fmt:
 	@script/fmt
 
-# Run linter
+# Run linter (the lint phase of the Dockerfile)
 lint:
 	@script/lint
 
-# Run tests (30-second timeout)
+# Run tests (the test phase of the Dockerfile)
 test:
 	@script/test
 
@@ -59,20 +59,25 @@ docker:
 docker-smoke:
 	@script/docker-smoke
 
-# Build Docker image tagged pixad:$(VERSION) and pixad:latest
-docker-versioned:
-	docker build --build-arg VERSION=$(VERSION) -t pixad:$(VERSION) -t pixad:latest .
+# Measure throughput, latency and peak memory with the default duration and
+# number of clients (needs Docker and Go; a benchmark, not part of check)
+loadtest:
+	@script/loadtest
 
-# Run tests in Docker (needed for CGO/libvips)
+# Build Docker image as `make docker` does, and also tag it pixa:$(VERSION)
+docker-versioned:
+	@script/docker
+	docker tag pixa pixa:$(VERSION)
+
+# Run tests in Docker, as `make test` does
 docker-test:
-	docker build --target builder --build-arg VERSION=$(VERSION) -t pixad-builder .
-	docker run --rm pixad-builder sh -c "CGO_ENABLED=1 GOTOOLCHAIN=auto go test -v ./..."
+	@script/test
 
 # Run local dev server in Docker
 devserver: docker-versioned devserver-stop
 	docker run -d --name pixad-dev -p 8080:8080 \
 		-v $(CURDIR)/config.dev.yml:/etc/pixa/config.yml:ro \
-		pixad:latest
+		pixa:latest
 	@echo "pixad running at http://localhost:8080"
 
 # Stop dev server

README.md

@@ -1,10 +1,9 @@
 # pixa
 
-pixa is a GPL-3.0-licensed Go web server by
-[@sneak](https://sneak.berlin) that proxies images from upstream
-sources, optionally resizing or transforming them, and serves the
-results. Both source and transformed images are cached to disk so that
-subsequent requests are served without origin fetches or additional
+pixa is a GPL-3.0-licensed Go web server by [@sneak](https://sneak.berlin) that
+proxies images from upstream sources, optionally resizing or transforming them,
+and serves the results. Both source and transformed images are cached to disk so
+that subsequent requests are served without origin fetches or additional
 processing.
 
 ## Getting Started
@@ -18,7 +17,7 @@ make build
 # run with a config file: copy the example and set a real signing key
 # (the example placeholder is refused at startup), e.g. with
 # openssl rand -base64 32
-cp config.example.yml config.yml
+cp configs/config.example.yml config.yml
 $EDITOR config.yml   # replace the signing_key placeholder
 ./bin/pixad --config config.yml
 
@@ -27,111 +26,330 @@ make docker
 docker run -p 8080:8080 -e PIXA_SIGNING_KEY="$(openssl rand -base64 32)" pixa:latest
 ```
 
-A container takes its settings from environment variables (see
-Configuration below for the list). Only `PIXA_SIGNING_KEY` is required; if
-it is unset the container exits at startup naming the variable. Everything
-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.
+A container takes its settings from environment variables (see Configuration
+below for the list). Only `PIXA_SIGNING_KEY` is required; if it is unset the
+container exits at startup naming the variable. Everything 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`,
+  builds encrypted URLs from `Host`, and checks `Referer` against
+  `referer_blocklist`;
+- 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, worked out each
+  time pixa starts, is 75% of the sum of the space free on the volume and the
+  space the cached images already take, so a restart keeps the limit the cache
+  had, but anything else that fills or frees space on the volume moves it.
+
+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, the images being processed and the counts of cache hits, misses,
+fetches and conversions being written to the database 5 seconds to finish, and
+exits: with 0, or with 1 when images were still being processed or counts still
+being written 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.16) and libheif to run, as
+it uses libvips through CGO. pixad does not start unless libvips has its JPEG XL
+support, which on Alpine is the `vips-jxl` package and which the nix and brew
+packages of libvips include, as do the apt ones from Debian 12 and Ubuntu 24.04
+on. Building pixa also needs the development files of libvips and libheif,
+`pkg-config` and a C compiler. `script/bootstrap --cgo` installs all of these,
+as the `Dockerfile` does where it compiles pixa. Plain `script/bootstrap`, which
+`script/setup` and `script/cibuild` run, installs git, make and Go, and Node,
+Yarn and the prettier pinned in `yarn.lock` for formatting the markdown, but
+none of the C libraries: the checks compile pixa in Docker. Docker itself must
+already be installed.
 
 ## Running under upaas
 
 What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
 
 - **Port:** pixa listens on container port `8080`.
-- **Volume:** container path `/var/lib/pixa`, where pixa keeps its
-  database and cache. Creating the host directory when it is missing is
-  upaas's job, tracked in https://git.eeqj.de/sneak/upaas/issues/235.
+- **Volume:** container path `/var/lib/pixa`, where pixa keeps its database and
+  cache. Creating the host directory when it is missing is upaas's job, tracked
+  in https://git.eeqj.de/sneak/upaas/issues/235.
 - **Environment variables:**
-    - `PIXA_SIGNING_KEY` (required): secret for signed and encrypted URLs
-      and login, 32+ characters, for example from
-      `openssl rand -base64 32`
+    - `PIXA_SIGNING_KEY` (required): secret for signed and encrypted URLs and
+      login, 32+ characters, for example from `openssl rand -base64 32`
     - `PIXA_ALLOWLIST_HOSTS`: upstream hosts served without a signature,
       comma-separated
     - `PIXA_CACHE_MAX_BYTES`: disk cache limit in bytes; `0` disables it;
-      default 75% of free space
+      default 75% of (free space + what the cache holds)
     - the rest are in the table under Configuration below
 - **Health check:** the image's `HEALTHCHECK` requests
-  `/.well-known/healthcheck.json`. upaas reads the container's health 60
-  seconds after a deploy and marks the deploy failed unless it is
-  `healthy`. The probe uses the port from `PORT` (default `8080`), so a
-  port changed only in a mounted config file is not seen by it: change
-  the port with `PORT`.
+  `/.well-known/healthcheck.json`. upaas reads the container's health 60 seconds
+  after a deploy and marks the deploy failed unless it is `healthy`. The probe
+  uses the port from `PORT` (default `8080`), so a port changed only in a
+  mounted config file is not seen by it: change the port with `PORT`.
 
 ## Rationale
 
-Image-heavy web applications need a fast, caching reverse proxy that
-can resize and transcode images on the fly. pixa fills that role as a
-single, self-contained binary with no external runtime dependencies
-beyond libvips. It supports HMAC-SHA256 signed URLs with expiration to
-prevent abuse, and allowlisted source hosts for open access.
+Image-heavy web applications need a fast, caching reverse proxy that can resize
+and transcode images on the fly. pixa fills that role as a single,
+self-contained binary with no external runtime dependencies beyond libvips. It
+supports HMAC-SHA256 signed URLs with expiration to prevent abuse, and
+allowlisted source hosts for open access.
 
 ## Design
 
 ### Storage
 
 - **Source content**:
-  `<statedir>/cache/src-content/<ab>/<cd>/<sha256 of source content>`
+  `<state_dir>/cache/sources/<ab>/<cd>/<sha256 of source content>`
 - **Source metadata**:
-  `<statedir>/cache/src-metadata/<hostname>/<sha256 of path>.json`
-  (fetch time, original headers, request, content hash)
-- **Database**: `<statedir>/state.sqlite3` (SQLite)
-- **Output documents**:
-  `<statedir>/cache/dst-content/<ab>/<cd>/<sha256 of output content>`
+  `<state_dir>/cache/metadata/<hostname>/<sha256 of path and query>.json` (host,
+  path and query, content hash, upstream status and headers, fetch time)
+- **Database**: `<state_dir>/state.sqlite3` (SQLite)
+- **Transformed images**:
+  `<state_dir>/cache/variants/<ab>/<cd>/<sha256 of host, path, query, size, format, quality and fit>`,
+  each with a `.meta` file beside it holding its content type
 
-Multiple source paths may reference the same content blob; the
-database tracks references rather than using filesystem refcounting.
-Toward a target of 1-5k r/s, pixa keeps in memory the content types of
-the 10,000 transformed images most recently cached or served, so a
-cache hit on one of them reads only the image file from disk and not
-the metadata file stored beside it.
+`<ab>` and `<cd>` are the first and second pairs of characters of the file's
+name.
+
+Multiple source paths may reference the same content blob; the database tracks
+references rather than using filesystem refcounting.
+
+pixa's target is 1-5k r/s, which has not been measured at that rate (see Load
+Test). Toward it, pixa keeps in memory the content types of the 10,000
+transformed images most recently cached or served, so a cache hit on one of them
+reads only the image file from disk and not the metadata file stored beside it.
 
 ### Routes
 
+pixa answers these routes; any other path answers 404. A path in this list asked
+with a method the list does not give answers 405, except `/static/<file>`, which
+answers any method as it answers `GET`. A browser's CORS preflight request
+(`OPTIONS` with `Origin` and `Access-Control-Request-Method` headers) to any
+path under `/v1/` answers 200, in maintenance mode too.
+
+- `GET /` — the login page, or the URL generator page with a login session (see
+  Encrypted URLs). Needs: nothing. Answers: 200.
+- `POST /` — log in with the signing key typed into the login page. Needs: the
+  login page's form (below). Answers: 303 to `/` with a login session cookie
+  that lasts 30 days for the right key; 200 with the login page and an error for
+  a wrong key; 429 over the login limit (below).
+- `POST /generate` — make an encrypted URL from the generator page's form.
+  Needs: a login session and the generator page's form (below); without a login
+  session it answers 303 to `/`. Answers: 200 with the page showing the URL; 400
+  with the page naming a field that is not valid; 500 when the URL cannot be
+  made.
+- `GET /logout` — end the login session. Needs: nothing. Answers: 303 to `/`.
+- `GET` or `HEAD` `/v1/image/<host>/<path>/<size>.<format>`, or
+  `/v1/image/<host>/<path>/<size>` with no format — an image, fetched, resized
+  and converted (below). Needs: a signature, unless the host is allowlisted (see
+  Source Hosts). Answers: 200; 304 when `If-None-Match` matches the image's
+  `ETag`; 400 for a URL or parameter that is not valid, or for the format `auto`
+  an `Accept` header that is not valid; 406 for the format `auto` when `Accept`
+  allows none of the formats it chooses from; 401 for a missing or wrong
+  signature, a missing `exp` or an `exp` in the past; 403 when the request's
+  `Referer` names a host in `referer_blocklist`, checked before the signature,
+  the cache and the upstream fetch; 403 when the upstream host, or a host it
+  redirects to, is `localhost`, ends in `.localhost` or `.local`, or has an
+  address in a blocked network (see `blocked_networks`); 502 when the upstream
+  answered with an error status, and for 5 minutes after that for the same
+  source URL; 503 when pixa is busy or in maintenance mode; 500 for any other
+  failure.
+- `GET` or `HEAD` `/v1/e/<token>/<name>` — an image through an encrypted URL
+  (see Encrypted URLs). Needs: nothing but the URL. Answers: 200; 304 when
+  `If-None-Match` matches the image's `ETag`; 400 for a token that does not
+  decrypt, or that asks for a size or fit that is not valid; 410 once it has
+  expired; 504 when the upstream has not sent its response headers within
+  `upstream_fetch_timeout`, but 500 when that time runs out while the image
+  itself is still arriving; 400 for an `Accept` header that is not valid, and
+  406, 403, 502, 503 and 500, as for `/v1/image/`.
+- `GET /robots.txt` — asks every crawler to stay away (`Disallow: /`). Needs:
+  nothing. Answers: 200.
+- `GET /.well-known/healthcheck.json` — JSON with `status` (`ok`), `now`,
+  `uptime_seconds`, `uptime_human`, `version`, `appname` and `maintenance_mode`.
+  Needs: nothing. Answers: 200, always.
+- `GET /static/<file>` — the stylesheet and script the login and generator pages
+  load. Needs: nothing. Answers: 200, or 404 for a file that does not exist.
+- `GET /metrics` — Prometheus metrics (see Architecture). Needs: HTTP basic
+  authentication with `metrics.username` and `metrics.password`. Answers: 200;
+  401 without them; 404 when they are not set, as the route then does not exist.
+
+Every response carries an `X-Request-ID` header holding the request's ID, which
+a client can quote when reporting a problem: the request's own `X-Request-ID`,
+as a reverse proxy in front of pixa may send, when it is at most 64 letters,
+digits, `-`, `_` or `.`; otherwise a random one pixa makes for the request,
+which tells nothing about the machine or the other requests. pixa's log line for
+the request carries the same ID as `request_id`, and so do the lines it logs
+when it fetches, converts and serves an image; the fetch sends it to the
+upstream host as `X-Request-ID`.
+
+Both `POST` routes accept only a form that pixa's own page served: the page puts
+a token in the form and sets a cookie to match, and a request without both is
+refused with 403, so another site cannot submit the form from a visitor's
+browser. The login and generator pages are meant to be opened over HTTPS: while
+`debug` is off, a form sent from a page opened over plain HTTP is refused with
+403, and while it is on, so is one sent from a page opened over HTTPS. Plain
+HTTP is for development on the browser's own machine: the login session cookie
+is always marked `Secure`, and over plain HTTP a browser keeps such a cookie
+only for its own machine (`localhost`), if at all. A form is also refused with
+403 when the page's host is not the `Host` header pixa receives, so a reverse
+proxy in front of pixa must pass that header on unchanged. A form body over 1
+MiB is refused with 413. The image routes answer the errors listed for them with
+JSON holding `error`, `status` and `timestamp`.
+
+An image URL has one of these forms, the second with no format:
+
 ```
-/v1/image/<host>/<path>/<size>.<format>?sig=<signature>&exp=<expiration>
+/v1/image/<host>/<path>/<size>.<format>?sig=<signature>&exp=<expiration>&q=<quality>&fit=<fit>
+/v1/image/<host>/<path>/<size>?sig=<signature>&exp=<expiration>&q=<quality>&fit=<fit>
 ```
 
-Images are only fetched from origins using TLS with valid certificates.
+Images are only fetched from origins using TLS with valid certificates, unless
+`allow_http` is set: then pixa fetches every image over plain HTTP, which is for
+testing only.
 
-A request whose query string cannot be decoded, or gives any parameter more
-than once, is refused with 400.
+A request whose query string cannot be decoded, or gives any parameter more than
+once, is refused with 400.
 
-- `<format>`: one of `orig`, `png`, `jpeg`, `webp`
+- `<format>`: one of `orig` (or `original`), `jpeg` (or `jpg`), `png`, `webp`,
+  `avif`, `jxl` (JPEG XL), `gif`, or `auto` (below). A URL with no format (the
+  second form, with no dot after the size) is served as JPEG XL, the default, as
+  with `jxl`
 - `<size>`: `orig` or `<width>x<height>` (e.g. `800x600`)
+- `sig` and `exp`: the signature and its expiry, needed unless the host is
+  allowlisted (see Signature Specification)
+- `q` and `fit`: the output quality and how the image is fitted to `<size>`,
+  both optional (values under Signature Specification). Both are part of what is
+  cached, so each value of either is a separate cached image.
+
+The source image may be JPEG, PNG, GIF, WebP, AVIF, JPEG XL or SVG. The
+upstream's `Content-Type` must name its format, and the image's first bytes must
+match it.
+
+With the format `auto`, pixa chooses the format for each request from its
+`Accept` header, in this order:
+
+1. JPEG XL, when the header names `image/jxl`;
+2. AVIF, when it names `image/avif`;
+3. WebP, when it names `image/webp`;
+4. JPEG, when the first of `image/jpeg`, `image/*` and `*/*` that it names
+   allows it, or when there is no `Accept` header or it is empty.
+
+An entry with `q=0` refuses its format; other `q` values do not change the
+order. JPEG XL, AVIF and WebP must be named, as clients that cannot show them
+also send `image/*` and `*/*`. pixa never sends a format the client refused:
+when the header allows none of the four, the answer is 406, and a header that
+does not parse, or has a `q` that is not a number from 0 to 1, is refused
+with 400. The signature, or the token of an encrypted URL, covers `auto` itself,
+so one URL serves every client. Each format chosen is cached as a separate
+image, and every answer that depends on `Accept` (the image, a 304, and the 400
+and 406 above) carries `Vary: Accept`, so a shared cache keeps the formats apart
+too.
 
 An image is served with `Cache-Control: public, max-age=<seconds>, immutable`.
-When the URL has an expiry (an `exp`, or the TTL of an encrypted URL),
-`max-age` is the whole seconds left until then, at most one year, so no browser
-or proxy cache keeps the image after pixa would refuse the URL. A URL with no
-expiry gets one year. `immutable` only stops a client revalidating while its
-copy is fresh.
+When the URL has an expiry (an `exp`, or the TTL of an encrypted URL), `max-age`
+is the whole seconds left until then, at most one year, so no browser or proxy
+cache keeps the image after pixa would refuse the URL. A URL with no expiry gets
+one year. `immutable` only stops a client revalidating while its copy is fresh.
 
-When several requests for the same image, size, format, quality and fit miss
-the cache at once, they share one upstream fetch (or one read of the cached
-source) and one transcode: the first request does the work, and the others wait
-for its image or its error, holding no upstream connection or processing slot
-of their own. A waiting request stops waiting when its own client goes away.
-The work goes on for the others even if the first request's client goes away,
-until that request's `downstream_timeout` ends.
+When several requests for the same image, size, format, quality and fit miss the
+cache at once, they share one upstream fetch (or one read of the cached source)
+and one transcode: the first request does the work, and the others wait for its
+image or its error, holding no upstream connection or processing slot of their
+own. A waiting request stops waiting when its own client goes away. The work
+goes on for the others even if the first request's client goes away, until that
+request's `downstream_timeout` ends. The shared fetch sends the first request's
+ID upstream, and the lines logged for the fetch and the transcode carry that ID.
 
 The login form (`POST /`) is limited to 5 attempts per minute per client
 address, counting an IPv6 client by its /64; an attempt over the limit is
 refused with 429 and a `Retry-After` header. Behind a reverse proxy the client
 address comes from `X-Forwarded-For` only when the address pixa sees for
 requests that come through the proxy is in `trusted_proxies`; otherwise all
-users behind the proxy are counted as one client. That address is not always
-the proxy's own: a proxy on the Docker host that connects to pixa over
-`127.0.0.1` is seen as the gateway of the container's Docker network, such as
-`172.17.0.1` on the default bridge, and one that connects through another of the
-host's addresses is seen with that address. To be sure, read it as `remoteIP` in
-pixa's request log while it is not in `trusted_proxies` (see `trusted_proxies`
-under Configuration). With the default `trusted_proxies` (the RFC 1918 ranges),
-a client with a private address can choose the address it is counted by through
+users behind the proxy are counted as one client. That address is not always the
+proxy's own: a proxy on the Docker host that connects to pixa over `127.0.0.1`
+is seen as the gateway of the container's Docker network, such as `172.17.0.1`
+on the default bridge, and one that connects through another of the host's
+addresses is seen with that address. To be sure, read it as `remoteIP` in pixa's
+request log while it is not in `trusted_proxies` (see `trusted_proxies` under
+Configuration). With the default `trusted_proxies` (the RFC 1918 ranges), a
+client with a private address can choose the address it is counted by through
 its own `X-Forwarded-For`, whether it connects directly or through the proxy,
 because its own address is trusted too. Setting `trusted_proxies` to only the
 address pixa sees for requests that come through the proxy closes this.
 
+### Encrypted URLs
+
+An encrypted URL is an image URL made on pixa's own web page by someone who
+knows the signing key. It works for any upstream host, allowlisted or not,
+without a signature, and whoever gets it can neither read the source URL from it
+nor change what it asks for.
+
+1. Open `/` in a browser over HTTPS (or over plain HTTP while `debug` is on, see
+   Routes) and log in with the signing key (`signing_key`). The login session
+   lasts 30 days, or until `/logout`.
+2. On the generator page, give the source image's URL, the width and height, the
+   format, quality and fit, and how long the URL lasts, then submit the form
+   (`POST /generate`). The format is JPEG XL unless another is chosen; a form
+   sent with an empty format, or none, also makes a JPEG XL URL. Width and
+   height both empty or `0` keep the original size; if only one of them is empty
+   or `0`, that side is scaled to keep the image's proportions.
+3. The page shows the URL, `https://<host>/v1/e/<token>/img.<format>`, and when
+   it expires. `<host>` is the host the page was opened on, and the URL starts
+   with `http` instead while `debug` is on. The name after the token is ignored
+   and only gives the URL a file extension, `jpg` for `orig` and `auto`, and
+   `jxl` for a form with no format.
+
+The token holds the source's host, path and query and the size, format, quality,
+fit and expiry, encrypted with a key derived from `signing_key`. The source
+URL's scheme is not kept: the image is fetched like any other (see Routes), and
+the blocked networks still apply.
+
+How long the URL lasts is chosen on the page, from 1 minute to 1 year, or never.
+The expiry is fixed in the token when the URL is made and cannot be changed or
+revoked afterwards. Until then the image is served with a `max-age` that ends at
+the expiry (see Routes); after it the URL answers 410 `URL has expired`. A URL
+made to last forever stops working only when `signing_key` changes: changing it
+makes every encrypted URL already handed out answer 400, and ends every login
+session.
+
 ### Image Metadata
 
 pixa decodes and re-encodes every image it serves, and removes all metadata from
@@ -146,19 +364,22 @@ turned off.
 - An image with an ICC profile is converted to sRGB first, since clients show an
   image with no profile as sRGB. Colours outside sRGB, such as the most
   saturated ones in a Display P3 photo, are clipped.
+- The one exception is JPEG XL with libvips 8.16 and later: libvips then writes
+  an EXIF block of its own into the image, as govips cannot ask libvips to leave
+  it out. It holds the image's size and otherwise fixed values, such as an
+  orientation of 1 and a resolution of 72 dpi, and nothing from the source.
 
 ### Source Hosts
 
-Source hosts may be allowlisted in the configuration. Non-allowlisted
-hosts require an HMAC-SHA256 signature.
+Source hosts may be allowlisted in the configuration. Non-allowlisted hosts
+require an HMAC-SHA256 signature.
 
 #### Signature Specification
 
-Signatures use HMAC-SHA256 and include an expiration timestamp to
-prevent replay attacks. Signatures are **exact match only**: every
-component (host, path, query, dimensions, format, expiration, quality,
-fit) must match exactly what was signed. No suffix matching, wildcard
-matching, or partial matching is supported.
+Signatures use HMAC-SHA256 and include an expiration timestamp to prevent replay
+attacks. Signatures are **exact match only**: every component (host, path,
+query, dimensions, format, expiration, quality, fit) must match exactly what was
+signed. No suffix matching, wildcard matching, or partial matching is supported.
 
 **Signed data format** (colon-separated):
 
@@ -173,25 +394,28 @@ Where:
 - `query` — source query string, empty string if none
 - `width` — requested width in pixels, `0` for original
 - `height` — requested height in pixels, `0` for original
-- `format` — output format (jpeg, png, webp, avif, gif, orig)
-- `expiration` — the URL's `exp` query parameter, the Unix timestamp when
-  the signature expires; a request whose `exp` is not a whole number, an
-  empty `exp=` included, is refused with 400
-- `quality` — the URL's `q` query parameter, a whole number from 1 to 100,
-  or `85` when the URL has no `q`; a request whose `q` is anything else is
-  refused with 400
+- `format` — output format, one of those listed under Routes, with `original`
+  signed as `orig`, `jpg` as `jpeg`, and no format as `jxl`, so a URL with no
+  format has the signature of the same URL ending in `.jxl`; `auto` is signed as
+  `auto`, not as the format chosen for the request
+- `expiration` — the URL's `exp` query parameter, the Unix timestamp when the
+  signature expires; a request whose `exp` is not a whole number, an empty
+  `exp=` included, is refused with 400
+- `quality` — the URL's `q` query parameter, a whole number from 1 to 100, or
+  `85` when the URL has no `q`; a request whose `q` is anything else is refused
+  with 400
 - `fit` — the URL's `fit` query parameter (cover, contain, fill, inside,
   outside), or `cover` when the URL has no `fit`; a request whose `fit` is
   anything else, an empty `fit=` included, is refused with 400
 
-The URL's `sig` is the HMAC-SHA256 result in base64url (the URL-safe alphabet
-of RFC 4648) with the trailing `=` padding kept, 44 characters in all. pixa
+The URL's `sig` is the HMAC-SHA256 result in base64url (the URL-safe alphabet of
+RFC 4648) with the trailing `=` padding kept, 44 characters in all. pixa
 compares it exactly, so a signature encoded without padding, as Node's
 `base64url` and Go's `base64.RawURLEncoding` do, is refused with 401.
 
 **Example:** with the signing key `example-signing-key-for-documentation`,
-resize `https://cdn.example.com/photos/cat.jpg` to 800x600 WebP with
-expiration 1704067200, default quality and fit:
+resize `https://cdn.example.com/photos/cat.jpg` to 800x600 WebP with expiration
+1704067200, default quality and fit:
 
 1. Build input:
    `cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200:85:cover`
@@ -212,22 +436,38 @@ and the URL is
 - **Suffix match**: `.example.com` — matches `cdn.example.com`,
   `images.example.com`, and `example.com`
 
+An IP address is matched exactly; write an IPv6 address without brackets. An
+entry that is neither a host name (letters, digits, hyphens, underscores and
+dots, with at most one leading dot) nor an IP address, such as one with a port
+or a `*.` wildcard, aborts startup.
+
 ### Configuration
 
-Every setting can be given as an environment variable, in a YAML config
-file (`--config`), or both. A variable present in the environment wins over
-the file, even when it is empty, and the file wins over the built-in
-default. The one exception is a variable named in the file's `env:` section:
-it is set while the file loads, so it overrides both the environment the
-process was started with and the file's own key. A variable's value is
-parsed as the same text in the file would be. The three lists take
-comma-separated entries, with the spaces around each trimmed; an empty
-variable is an empty list. A value that does not parse or is invalid aborts
-startup, naming the variable. A variable whose name starts with `PIXA_` but
-is not in the table below, such as a misspelled one or `PIXA_PORT`, aborts
-startup naming it, as an unknown config key does. The one other accepted
-name is `PIXA_CONFIG_PATH`, the config file's path (like `--config`). The
-variables set by the file's `env:` section are checked the same way.
+Every setting can be given as an environment variable, in a YAML config file
+(`--config`), or both. A variable present in the environment wins over the file,
+even when it is empty, and the file wins over the built-in default. The one
+exception is a variable named in the file's `env:` section: it is set while the
+file loads, so it overrides both the environment the process was started with
+and the file's own key. A variable's value is parsed as the same text in the
+file would be. The three lists take comma-separated entries, with the spaces
+around each trimmed; an empty variable is an empty list. A value that does not
+parse or is invalid aborts startup, naming the variable. A variable whose name
+starts with `PIXA_` but is not in the table below, such as a misspelled one or
+`PIXA_PORT`, aborts startup naming it, as an unknown config key does. The one
+other accepted name is `PIXA_CONFIG_PATH`, the config file's path (like
+`--config`). The variables set by the file's `env:` section are checked the same
+way.
+
+pixa reads at most one config file: the one given with `--config` (or `-c`),
+otherwise the one `PIXA_CONFIG_PATH` names, otherwise the first of these that
+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.
 
 | Variable                             | Config key                      | Meaning                                                                      |
 | ------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------- |
@@ -235,8 +475,9 @@ variables set by the file's `env:` section are checked the same way.
 | `PORT`                               | `port`                          | Port to listen on; default `8080`                                            |
 | `PIXA_STATE_DIR`                     | `state_dir`                     | Directory for the database and the disk cache; default `/var/lib/pixa`       |
 | `PIXA_DB_URL`                        | `db_url`                        | SQLite database URL; default `state.sqlite3` in the state directory          |
-| `PIXA_CACHE_MAX_BYTES`               | `cache_max_bytes`               | Disk cache limit in bytes; `0` disables it; default 75% of free space        |
+| `PIXA_CACHE_MAX_BYTES`               | `cache_max_bytes`               | Disk cache limit in bytes; `0` disables it; default 75% of (free + cached)   |
 | `PIXA_ALLOWLIST_HOSTS`               | `allowlist_hosts`               | Upstream hosts served without a signature                                    |
+| `PIXA_REFERER_BLOCKLIST`             | `referer_blocklist`             | Hosts whose pages the image routes refuse with 403, by `Referer`             |
 | `PIXA_BLOCKED_NETWORKS`              | `blocked_networks`              | CIDR ranges never fetched from, on top of the built-in ones                  |
 | `PIXA_TRUSTED_PROXIES`               | `trusted_proxies`               | CIDR ranges of proxies whose `X-Forwarded-For` is believed; default RFC 1918 |
 | `PIXA_ALLOW_HTTP`                    | `allow_http`                    | Allow plain-HTTP upstreams, for testing only; default `false`                |
@@ -259,49 +500,67 @@ Key settings in more detail:
   of the image routes, `/v1/image/` and `/v1/e/`, sent as the CORS
   `Access-Control-Allow-Origin` header; no other route sends it. `*`, the
   default, is any site; otherwise one `http` or `https` origin such as
-  `https://example.com`, whose host is a lowercase host name (letters,
-  digits, hyphens and dots, with a letter in its last part) or an IP address
-  (IPv6 in brackets, in its shortest form), with an optional port 1-65535
-  that has no leading zero and is not the scheme's default. Any other value,
-  including another scheme such as a browser extension's, aborts startup
+  `https://example.com`, whose host is a lowercase host name (letters, digits,
+  hyphens and dots, with a letter in its last part) or an IP address (IPv6 in
+  brackets, in its shortest form), with an optional port 1-65535 that has no
+  leading zero and is not the scheme's default. Any other value, including
+  another scheme such as a browser extension's, aborts startup
 - `allowlist_hosts` — list of allowed upstream hosts
-- `blocked_networks` — list of CIDR ranges to refuse for SSRF protection,
-  added to the always-enforced built-in ranges (loopback, private,
-  link-local, CGNAT, benchmark, NAT64, and the like); an invalid CIDR
-  aborts startup
-- `trusted_proxies` — list of CIDR ranges of the reverse proxies in front
-  of pixa. `X-Forwarded-For` is believed only when the direct peer falls
-  inside one of these ranges; the logged and login-recorded client
-  address is then the rightmost forwarded entry that is not itself a
-  trusted proxy. Otherwise the direct peer address is used and the header
-  is ignored, so a client connecting directly from an address outside
-  these ranges cannot spoof its address.
-  An omitted key defaults to the RFC 1918 private ranges (`10.0.0.0/8`,
-  `172.16.0.0/12`, `192.168.0.0/16`), since pixa is deployed behind a
-  proxy on a private network; an explicitly empty list (`[]`) trusts no
-  one, and an explicit list replaces the default. An invalid CIDR aborts
-  startup. Set this to the address pixa sees for requests that come through
-  your proxy, such as `172.17.0.1/32`, when the defaults do not cover it, or
-  to trust nothing else (see the login limit under Routes). For a proxy on
-  the Docker host that connects to pixa over `127.0.0.1`, that address is the
-  gateway of the container's Docker network (`172.17.0.1` on the default
-  bridge), not the proxy's own address; a proxy that connects through another of
-  the host's addresses is seen with that address. To be sure which address it
-  is, set this to `[]` (or `PIXA_TRUSTED_PROXIES` to empty), send a request
-  through the proxy, and read `remoteIP` in pixa's request log line for it
-- `upstream_fetch_timeout` — time allowed for one fetch from an upstream
-  host, as a duration such as `30s` (the default) or `2m`
-- `upstream_max_response_size` — largest upstream response accepted, in
-  bytes; default `52428800` (50 MiB). It also limits the image data pixa
-  decodes
+- `referer_blocklist` — list of hosts whose pages may not show pixa's images, to
+  stop other sites hotlinking them. Entries are written and matched as for
+  `allowlist_hosts` (see Allowlist patterns), and an entry that is neither a
+  host name nor an IP address aborts startup. A request to `/v1/image/` or
+  `/v1/e/` whose `Referer` header names a listed host is refused with 403 before
+  its signature or token is checked and before the cache or the upstream host is
+  used, so it fetches nothing, and it is refused even when the image is cached.
+  A request with no `Referer`, or one that does not parse as a URL with a host,
+  is served, as many clients send none. So this is easily got around: a site
+  whose pages send no `Referer` (for example with
+  `Referrer-Policy: no-referrer`) is not stopped. It does not apply to the login
+  and generator pages. Default: empty
+- `blocked_networks` — list of CIDR ranges to refuse for SSRF protection, added
+  to the always-enforced built-in ranges (loopback, private, link-local, CGNAT,
+  benchmark, NAT64, and the like); an invalid CIDR aborts startup
+- `trusted_proxies` — list of CIDR ranges of the reverse proxies in front of
+  pixa. `X-Forwarded-For` is believed only when the direct peer falls inside one
+  of these ranges; the logged and login-recorded client address is then the
+  rightmost forwarded entry that is not itself a trusted proxy. Otherwise the
+  direct peer address is used and the header is ignored, so a client connecting
+  directly from an address outside these ranges cannot spoof its address. An
+  omitted key defaults to the RFC 1918 private ranges (`10.0.0.0/8`,
+  `172.16.0.0/12`, `192.168.0.0/16`), since pixa is deployed behind a proxy on a
+  private network; an explicitly empty list (`[]`) trusts no one, and an
+  explicit list replaces the default. An invalid CIDR aborts startup. Set this
+  to the address pixa sees for requests that come through your proxy, such as
+  `172.17.0.1/32`, when the defaults do not cover it, or to trust nothing else
+  (see the login limit under Routes). For a proxy on the Docker host that
+  connects to pixa over `127.0.0.1`, that address is the gateway of the
+  container's Docker network (`172.17.0.1` on the default bridge), not the
+  proxy's own address; a proxy that connects through another of the host's
+  addresses is seen with that address. To be sure which address it is, set this
+  to `[]` (or `PIXA_TRUSTED_PROXIES` to empty), send a request through the
+  proxy, and read `remoteIP` in pixa's request log line for it
+- `upstream_fetch_timeout` — time allowed for one fetch from an upstream host,
+  as a duration such as `30s` (the default) or `2m`
+- `upstream_max_response_size` — largest upstream response accepted, in bytes;
+  default `52428800` (50 MiB). It also limits the image data pixa decodes
 - `downstream_timeout` — time allowed for answering one client request, as a
   duration; default `60s`. The upstream fetch counts toward it, and so do the
   waits for an upstream connection and for a processing slot (up to 10 seconds
   each), so keep it longer than `upstream_fetch_timeout` plus 20 seconds
 - `signing_key` — HMAC secret for URL signatures
-- `cache_max_bytes` — disk cache size limit in bytes; `0` disables the
-  disk cache entirely; omitted defaults to 75% of the free space on
-  the filesystem containing `<state_dir>/cache/` (minimum 500 MiB)
+- `db_url` — the SQLite database to open; omitted, it is
+  `file:<state_dir>/state.sqlite3?_pragma=journal_mode(WAL)`, which keeps the
+  database in WAL mode. pixa opens one connection to it, so its own reads and
+  writes run one at a time. pixa adds `_pragma=busy_timeout(5000)` to any
+  `db_url`, so a write that finds another program writing to the file waits up
+  to five seconds for it instead of failing. WAL mode comes only from the URL:
+  keep `_pragma=journal_mode(WAL)` in one you set
+- `cache_max_bytes` — disk cache size limit in bytes; `0` disables the disk
+  cache entirely; omitted defaults to 75% of the sum of the free space on the
+  filesystem containing `<state_dir>/cache/` and the bytes of source and
+  transformed images the cache already holds, worked out at startup (minimum 500
+  MiB)
 - `upstream_connections` — the most connections to upstream hosts at once, all
   hosts together, on top of `upstream_connections_per_host`; default `64`. A
   fetch holds its connection until its image has been processed. A fetch that
@@ -314,14 +573,14 @@ Key settings in more detail:
   seconds for one to free up; if none does, and `downstream_timeout` has not
   ended first, it is answered 503 the same way
 - `maintenance_mode` — while `true`, the image routes (`/v1/image/` and
-  `/v1/e/`) answer every request with 503, a `Retry-After` header and a JSON
-  error body. The health check (`/.well-known/healthcheck.json`) still answers
-  200 and reports `"maintenance_mode": true`. It stays 200 because the image's
-  Docker `HEALTHCHECK` requests it: a 503 there would make the container
-  unhealthy, and upaas marks a deploy failed when its container is unhealthy.
-  The login and URL generator pages and `/metrics` keep working
+  `/v1/e/`) answer every request for an image with 503, a `Retry-After` header
+  and a JSON error body. The health check (`/.well-known/healthcheck.json`)
+  still answers 200 and reports `"maintenance_mode": true`. It stays 200 because
+  the image's Docker `HEALTHCHECK` requests it: a 503 there would make the
+  container unhealthy, and upaas marks a deploy failed when its container is
+  unhealthy. The login and URL generator pages and `/metrics` keep working
 
-See `config.example.yml` for all options with defaults.
+See `configs/config.example.yml` for all options with defaults.
 
 ### Architecture
 
@@ -330,7 +589,10 @@ See `config.example.yml` for all options with defaults.
 - **Image processing**: govips (CGO wrapper for libvips)
 - **Database**: SQLite via modernc.org/sqlite
 - **Static assets**: embedded via `//go:embed`
-- **Metrics**: Prometheus
+- **Metrics**: Prometheus, at `/metrics`: generic HTTP request metrics
+  (duration, response size, requests in flight) and the Go runtime and process
+  metrics; requests are measured and `/metrics` is served only when
+  `metrics.username` and `metrics.password` are set
 - **Logging**: stdlib slog
 
 ## Entrypoints
@@ -338,28 +600,98 @@ See `config.example.yml` for all options with defaults.
 This repository adheres to the
 [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
 standard: normalized scripts in `script/` are the entrypoints for the
-development workflow, and the Makefile targets are thin shims that call
-them. We provide:
+development workflow, and the Makefile targets are thin shims that call them. We
+provide:
 
-- `script/bootstrap` — install all dependencies (idempotent)
-- `script/setup` — make a fresh clone ready for development
-  (bootstrap, then install-precommit)
+- `script/bootstrap` — install git, make, Go, Node, Yarn and prettier and
+  download the Go modules (idempotent); with `--cgo`, the C compiler and the
+  libvips (with its JPEG XL support) and libheif libraries that compiling and
+  testing pixa need instead of Node, Yarn and prettier
+- `script/setup` — make a fresh clone ready for development (bootstrap, then
+  install-precommit)
 - `script/projectname` — output the project name ("pixa")
-- `script/test` — run the test suite
-- `script/lint` — run golangci-lint, always in a container (builds
-  `Dockerfile.lint` when run outside one)
-- `script/fmt` — format all code (writes)
-- `script/fmt-check` — check formatting (read-only)
+- `script/test` — run the test suite: build the `test` phase of the
+  `Dockerfile`, tagged `pixa-test`
+- `script/lint` — run golangci-lint: build the `lint` phase of the `Dockerfile`,
+  tagged `pixa-lint`; the linter never runs on the host
+- `script/fmt` — format the Go code with gofmt and the markdown with prettier
+  (writes)
+- `script/fmt-check` — check the same formatting (read-only), on the host
 - `script/check` — run test, lint, and fmt-check
-- `script/docker` — build the Docker image tagged via `script/projectname`
+- `script/docker` — build the Docker image tagged via `script/projectname`, with
+  the version from `git describe`; the image's build stage depends on the `lint`
+  and `test` phases, so this runs them too
 - `script/docker-smoke` — build the image, start it, wait for it to be healthy
-- `script/cibuild` — CI entrypoint: `docker build .` with a new
-  `CHECK_EPOCH` on every run, so the Dockerfile's checks run instead of
-  coming from the build cache, and a green run implies a green repo
+- `script/loadtest` — measure pixad's throughput, latency and peak memory; a
+  benchmark, not part of `script/check` (see Load Test)
+- `script/cibuild` — CI entrypoint: run `script/bootstrap` (without `--cgo`),
+  then `script/check`, then build the image as `script/docker` does
 - `script/precommit` — pre-commit checks (`go mod tidy` guard, then
   `script/check`)
-- `script/install-precommit` — install the git pre-commit hook that
-  runs `script/precommit`
+- `script/install-precommit` — install the git pre-commit hook that runs
+  `script/precommit`
+
+Every `docker build` in these scripts passes `--no-cache`, so the lint and test
+phases run on every build instead of coming from the build cache.
+`script/check`, `script/cibuild`, `script/docker`, `script/lint`, `script/test`,
+`script/setup` and `script/install-precommit` are the standard copies from
+`sneak/prompts`, kept identical to them. `script/fmt` and `script/fmt-check` are
+the standard copies with pixa's `gofmt` step kept before prettier. prettier
+formats the markdown only: not the HTML templates, as it cannot parse a Go
+template action inside a tag, and not `REPO_POLICIES.md` (see
+`.prettierignore`), a copy of the one in `sneak/prompts`.
+
+## Load Test
+
+`script/loadtest` (or `make loadtest`) measures how fast pixad answers and how
+much memory it uses. It is a benchmark, not a check: `script/check` does not run
+it. It needs Docker and Go.
+
+```bash
+script/loadtest           # 10 seconds per scenario, 4 clients
+script/loadtest 30s 32    # 30 seconds per scenario, 32 clients
+```
+
+It builds the image with `script/docker` and the load tool,
+[vegeta](https://github.com/tsenart/vegeta), from a pinned commit. Each scenario
+starts a new pixad container and a new origin container, `cmd/loadtest-origin`:
+an upstream host that answers every path with the same generated 1600x1200 JPEG.
+vegeta then sends requests from the given number of clients, each sending its
+next request as soon as its last one is answered, all for an image resized to
+400x300 WebP:
+
+- `hit`: the same image every time, put in the cache first;
+- `miss`: a new source image every time, so pixad fetches and converts each one;
+- `herd`: each new source image once per client in a row, so that all clients
+  ask for it at the same time and share one fetch and one conversion (see
+  Routes).
+
+pixad refuses upstream hosts with private or local addresses, so the containers
+share a Docker network in `203.0.113.0/24`, a range set aside for documentation.
+A second run on the same Docker host while one is going fails, as it cannot
+create that network.
+
+For each scenario the script prints vegeta's report and two lines of its own:
+
+- `Requests [total, rate, throughput]`: the requests sent, how many were sent
+  per second, and how many were answered successfully per second; the last is
+  the number to compare with the target under Storage;
+- `Latencies [min, mean, 50, 90, 95, 99, max]`: the time from sending a request
+  to the end of its answer; `50`, `95` and `99` are the 50th, 95th and 99th
+  percentiles;
+- `Status Codes` and `Error Set`: anything other than `200` means the other
+  numbers are not for the scenario described, such as `503` when pixad was busy;
+- `Bytes In`: `0`, as vegeta is told not to keep the images it receives;
+- `pixad peak memory (VmHWM)`: the peak resident memory of pixad's process since
+  its container started, in kB; for `hit` it includes the request that put the
+  image in the cache;
+- `requests to the origin`: the fetches pixad made: one for `hit`, one per
+  request for `miss`, and one per image for `herd`, that is the requests sent
+  divided by the number of clients.
+
+The numbers depend on the machine and on whatever else runs on it. The first
+measurement, made on a shared machine with few clients, is in `TODO.md`; it says
+nothing about the target.
 
 ## TODO
 

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-07-06
+last_modified: 2026-09-08
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,17 +60,28 @@ style conventions are in separate documents:
   prerequisite since nvm requires bash. yarn is then pinned via
   `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
   always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
-  scripts are our own extensions to the standard: `script/check` runs
-  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
-  what the git pre-commit hook runs, and it calls `script/check`;
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
-  target shims to it); and `script/projectname` (literally that filename) simply
-  outputs the project's name. Scripts that need the name call
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
-  so those scripts stay byte-identical across all repos. Repo-type-specific
-  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
-  `script/precommit`, not in the hook itself. Model scripts are at
+  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
+  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  `script/bootstrap` first**, because the workflow checks out the repo and runs
+  nothing else, while `script/fmt-check` runs the formatter on the host: on a
+  pristine checkout with nothing installed the run dies there, after the
+  containerised gates have passed. **The bootstrap alone is not enough**:
+  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  source nvm for the pinned node version before invoking it, exactly as
+  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  docker and git then gets through `script/check`. Four further scripts are our
+  own extensions to the standard: `script/check` runs `script/test`,
+  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
+  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
+  installs the git pre-commit hook (the `make hooks` target shims to it); and
+  `script/projectname` (literally that filename) simply outputs the project's
+  name. Scripts that need the name call `script/projectname` — e.g.
+  `script/docker` assembles its image tag from it — so those scripts stay
+  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
+  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
+  the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
   must document the provided scripts in an **Entrypoints** section (see the
   README requirements below).
@@ -89,87 +100,140 @@ style conventions are in separate documents:
   contributor should be able to understand the entire development workflow by
   reading the Makefile.
 
-- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  as a build step so the build fails if the branch is not green. For non-server
-  repos, the Dockerfile should bring up a development environment and run
-  `make check`. For server repos, `make check` should run as an early build
-  stage before the final image is assembled. Dockerfiles install development
-  prerequisites by running `script/bootstrap` rather than duplicating installs
-  inline; COPY `script/` and the dependency manifests (`package.json` +
-  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
-  layer stays cached until dependencies change.
+- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
+  `lint` phase and a `test` phase, with the final stage depending on both so the
+  image cannot be built unless they pass. For non-server repos the final stage
+  brings up a development environment; for server repos it is the runtime image.
+  Dockerfiles install development prerequisites by running `script/bootstrap`
+  rather than duplicating installs inline; COPY `script/` and the dependency
+  manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
+  running it.
 
-- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
-  repos use a multistage build where linting runs in an independent stage based
-  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
-  `make fmt-check` and `make lint` before the full build begins. The build stage
-  then declares an explicit dependency on the lint stage via
-  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
-  linting before proceeding to compilation and tests. This ensures lint failures
-  surface in seconds rather than minutes, without blocking on dependency
-  download or compilation in the build stage.
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
+  no separate lint file. `script/lint` and `script/test` each build one phase
+  and nothing else:
 
-    The standard pattern for a Go repo Dockerfile is:
+    ```sh
+    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
+    docker build --no-cache --target test -t "$(script/projectname)-test" .
+    ```
+
+    **A stage that is not the last one in the file is built only when the final
+    stage's chain depends on it, or when `--target` names it.** That is why the
+    two gates are always invoked by name here, and why the final stage carries a
+    `COPY --from=` of a harmless file from each of them: without that edge a
+    plain `docker build .` builds the last stage alone and exits 0 having linted
+    and tested nothing.
+
+    **Every `docker build` in `script/` is tagged**, here and in
+    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
+    image behind on every invocation, on every developer host and every CI
+    runner; a tagged one replaces the previous image.
+
+    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
+    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
+    themselves a `docker build` and would recurse into a daemon that does not
+    exist in a build step. Formatting is the exception and stays on the host:
+    `script/fmt` writes the working tree, and `script/fmt-check` is its
+    read-only twin.
+
+    **No lint verdict may come from a host invocation of the linter.** On a
+    shared host golangci-lint reads a result cache keyed on file content rather
+    than location, so a second checkout of the same content is served the first
+    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
+    exit non-zero with `parallel golangci-lint is running` — a status a caller
+    cannot tell from real findings. Both have produced wrong verdicts in this
+    org, in both directions. A container has its own cache, its own `TMPDIR` and
+    a digest-pinned binary, so neither is reachable.
+
+- **Any build that runs checks is built with `--no-cache`.** Docker invalidates
+  a `COPY` layer only when the copied content changes, so on an unchanged tree
+  the check `RUN` is served from cache, nothing executes, and the build still
+  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
+  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
+  four, and there is no fifth — `script/check` runs the two gate phases and
+  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
+  not evidence that anything ran: a sub-second build reporting success is a
+  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
+  and friends destroy a build cache shared with every other build on the host.
+
+- **The gate phases are separate stages, and the build stage depends on both.**
+  The lint phase is based on the `golangci/golangci-lint` image (pinned by
+  hash), so lint failures surface in seconds rather than after a full compile,
+  and the test phase is based on the Go image. The canonical Go repo
+  `Dockerfile`:
 
     ```dockerfile
-    # Lint stage — fast feedback on formatting and lint issues
+    # Lint phase
     # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
     FROM golangci/golangci-lint@sha256:... AS lint
     WORKDIR /src
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make fmt-check
-    RUN make lint
+    RUN golangci-lint run --config .golangci.yml ./...
 
-    # Build stage
+    # Test phase
     # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS test
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN go test -timeout 90s -race -cover ./... || \
+        { echo "--- Rerunning with -v for details ---"; \
+          go test -timeout 90s -race -v ./...; exit 1; }
+
+    # Build stage. Nothing is wanted from either phase above; the copies
+    # are what make BuildKit build them first, so this stage cannot run
+    # unless lint and test passed.
+    # golang:1.x-alpine, YYYY-MM-DD
     FROM golang@sha256:... AS builder
+    COPY --from=lint /src/go.sum /dev/null
+    COPY --from=test /src/go.sum /dev/null
     WORKDIR /src
-
-    # Force BuildKit to run the lint stage before proceeding
-    COPY --from=lint /src/go.sum /dev/null
-
     COPY go.mod go.sum ./
     RUN go mod download
     COPY . .
-    RUN make test
 
     ARG VERSION=dev
     RUN CGO_ENABLED=0 go build -trimpath \
         -ldflags="-s -w -X main.Version=${VERSION}" \
         -o /app ./cmd/app/
 
-    # Runtime stage
+    # Runtime stage, and the last one
     FROM alpine@sha256:...
     COPY --from=builder /app /usr/local/bin/app
     ENTRYPOINT ["app"]
     ```
 
     Key points:
-    - The lint stage uses the `golangci/golangci-lint` image directly (it
-      includes both Go and the linter), so there is no need to install the
-      linter separately.
-    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
-      a stage dependency. BuildKit runs stages in parallel by default; without
-      this line, the build stage would not wait for lint to finish and a lint
-      failure might not fail the overall build.
+    - The lint phase uses the `golangci/golangci-lint` image directly (it has
+      both Go and the linter), so nothing needs installing.
+    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
+      and a stage nothing depends on is not built at all, so without these two
+      lines a red gate would not fail the build.
+    - Keep the runtime stage last, and if you add a stage after it, give it the
+      same two copies. A plain `docker build .` builds the last stage's chain
+      and nothing else.
     - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      (e.g. a web frontend compiled in a separate stage), the lint phase must
       create placeholder files so the embed directives resolve. Example:
       `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
-      The lint stage should not depend on the actual build output — it exists to
-      fail fast.
     - If the project requires CGO or system libraries for linting (e.g.
-      `vips-dev`), install them in the lint stage with `apk add`.
-    - The build stage runs `make test` after compilation setup. Tests run in the
-      build stage, not the lint stage, because they may require compiled
-      artifacts or heavier dependencies.
+      `vips-dev`), install them in the lint phase with `apk add`.
+    - `ARG VERSION=dev` is declared in the stage that compiles and supplied by
+      `script/docker` and `script/cibuild`; no stage may call `git describe`.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` (which runs `docker build .`) on push. Since the
-  Dockerfile already runs `make check`, a successful build implies all checks
-  pass.
+  runs `script/cibuild` on push, and checks out the repo as its only other step.
+  That script bootstraps, runs the gate phases, and then builds the image, so a
+  successful run means every check passed; a bare `docker build .` does not
+  carry the same guarantee, because its gate phases may come from the cache. The
+  image build is uncached and so runs the gate phases a second time. That is the
+  price of the rule above, and it is worth paying: the image that ships is built
+  from a run of its own gates rather than from a cache entry.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -189,14 +253,21 @@ style conventions are in separate documents:
   module under test to verify it compiles/parses. There is no excuse for
   `make test` to be a no-op.
 
-- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
-  Makefile.
+- `make test` must complete in under 60 seconds. That is the hard cap, and a
+  suite that exceeds it fails. Under 20 seconds is the target. A suite between
+  20 and 60 seconds is still green, but the overage must be filed as an
+  improvement bug against that repo. Add a 90-second timeout to the test
+  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
+  hard cap so that it catches a genuinely hung test rather than a merely slow
+  one.
 
-- **`make test` should use the conditional verbose rerun pattern.** Run tests
-  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
-  show full output. This keeps CI logs and `docker build` output clean on
-  success (just package/suite summaries) while providing full diagnostic detail
-  on failure (every test case, every assertion). The general shell pattern:
+- **The test command should use the conditional verbose rerun pattern.** Run
+  tests without `-v` (verbose) first. If tests fail, automatically rerun with
+  `-v` to show full output. This keeps CI logs and `docker build` output clean
+  on success (just package/suite summaries) while providing full diagnostic
+  detail on failure (every test case, every assertion). The command lives in the
+  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
+  Makefile form below is the same pattern for any repo-local invocation:
 
     ```makefile
     test:
@@ -209,11 +280,24 @@ style conventions are in separate documents:
 
     ```makefile
     test:
-    	@go test -timeout 30s -race -cover ./... || \
+    	@go test -count=1 -timeout 90s -race -cover ./... || \
     		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -timeout 30s -race -v ./...; exit 1; }
+    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
     ```
 
+    `-count=1` is required on both invocations: it defeats Go's test _result_
+    cache, so the target cannot report a pass it did not earn, and the rerun
+    reproduces a failure instead of replaying it. It leaves the build cache
+    alone, so it costs the runtime of the suite and no recompilation.
+
+    Note that this is a second, independent cache, stacked below the Docker
+    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
+    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
+    it does not guarantee `go test` inside that step does any work, because the
+    `GOCACHE` baked into earlier image layers survives into the re-executed
+    step. They are two separate defects requiring two separate fixes, and a fix
+    for one must not be recorded as covering the other.
+
     Python example:
 
     ```makefile
@@ -239,10 +323,83 @@ style conventions are in separate documents:
   must be in `.gitignore`. No exceptions.
 
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  Fetch the standard `.gitignore` from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
-  a new repo.
+  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
+  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  setting up a new repo. These patterns are written to `.gitignore`'s own
+  semantics, in which an unanchored pattern already matches at every depth; they
+  are not a `.dockerignore` and must not be transplanted into one unmodified.
+
+- **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
+  across unmodified leaves secrets in the build context.** Docker matches with
+  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
+  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
+  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
+  therefore excludes only the copies at the repository root, while `config/.env`
+  and `certs/server.key` still reach the context and can land in an image layer
+  — which is more dangerous than a short file with no secret patterns at all,
+  because it reads as solved and stops anyone looking. Give every
+  depth-independent pattern the `**/` prefix and leave only genuinely
+  root-anchored entries unprefixed: `.git`, and the repo's own host-built
+  binary, written `/myapp` and never `**/myapp`, which would also match
+  `cmd/myapp/` and delete the package directory from the context. Matching is
+  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
+  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
+  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
+  also catches something the build needs, re-include it with a negation
+  (`!docs/example.env`); deleting the pattern reopens the exposure for every
+  other file it covers. Fetch the standard `.dockerignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
+  it with the repo's own artifacts.
+
+- **In-repo agent scratch belongs in both files, written to each file's own
+  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
+  additional checkout of the repo — so under `COPY . .` the build context
+  inflates by a multiple of the repo and another session's unreviewed work can
+  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
+  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
+  prefix, because the prefixed form would also delete any nested directory of
+  that name from the build. Anchoring carries a known gap that the canonical
+  `.dockerignore` states in its own comment, since consuming repos receive the
+  file and not the tracker: the directory is created in the agent's working
+  directory, so a repo running agents in subdirectories still ships
+  `services/api/.claude/` and must add its own anchored entry there.
+
+- **Excluding `.git` means `git describe` cannot run inside any build stage, and
+  it fails quietly there.** In a build stage there is no repository, so
+  `git describe` writes nothing to stdout, `-X main.Version=` comes out empty,
+  the binary reports no version at all, and the build still exits 0. Compute the
+  version on the host and thread it in as a build arg. `script/docker` and
+  `script/cibuild` do this, byte-identically across repos:
+
+    ```sh
+    # Own line: a failing command substitution inside an argument does not
+    # trip `set -e`, so the inline form degrades to an empty constant.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$(script/projectname)" .
+    ```
+
+    `--always` makes an untagged repo yield an abbreviated commit hash rather
+    than failing, and the `[ -n "$version" ]` line is the single place the
+    fallback is applied — a live check that fires on a build from an export with
+    no `.git` and on a repository with no commits yet. Do not fold it into the
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
+    Dockerfile's side is `ARG VERSION=dev` in the stage that compiles, declared
+    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
+    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
+    the scripts stay byte-identical. One consequence for CI: the standard
+    checkout action clones shallow and fetches no tags, so a repo that embeds a
+    tag-derived version must set `fetch-depth: 0` on its checkout step.
+
+- **Verify `.dockerignore` by enumerating the image, not by reading the
+  patterns.** Plant files at the root _and_ at least two directories deep, build
+  a probe image that does `COPY . .`, and list what actually landed
+  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
+  size is not a substitute: a nested secret is a few bytes, and BuildKit
+  transfers only the delta from the previous build.
 
 - **No build artifacts in version control.** Code-derived data (compiled
   bundles, minified output, generated assets) must never be committed to the
@@ -258,9 +415,45 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
-  manually by the user. Fetch from
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
+- `.golangci.yml` is standardized. The vendored copy in a consuming repo must
+  _NEVER_ be modified by an agent: fetch it from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and keep it
+  byte-identical, so that no repo can quietly loosen its own linting. Linter
+  configuration changes are made to the canonical copy in the `prompts` repo and
+  reach consuming repos by re-vendoring; an agent may open a PR against
+  canonical, which only the user merges. One list is exempt from byte-identity,
+  because it cannot be written once for every repo: the `deny` list of the
+  `test-support` depguard rule, where a repo names its own test-support packages
+  by full import path. A repo adds entries there and changes nothing else, and a
+  re-vendor carries its entries forward. The canonical golangci-lint version is
+  v2.12.2 (released 2026-05-06), pinned as the digest of the lint phase's base
+  image
+  (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
+  which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the
+  only pin, since no repo installs golangci-lint on the host: bumping the
+  version means changing it and nothing else.
+
+- **`script/bootstrap` installs a pinned tool by comparing versions, never by
+  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
+  `PATH` only, so on an already-provisioned machine the pin is inert and a
+  version bump is a silent no-op — while the Dockerfile, installing into a clean
+  image, gets the pinned version, so a local `make check` and `make docker` can
+  disagree about what the tool even is. The canonical form:
+    - compares the installed version against the pin over the **whole** version
+      token; a parser that stops at the first `-` reports `2.12.2` for a host
+      running `2.12.2-rc1` and skips the install;
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
+      mismatch, so the failure direction is a redundant install and never a
+      skipped one;
+    - after installing, re-resolves the binary the way callers do — `hash -r`,
+      then through `PATH`, not through the directory the installer wrote to —
+      and fails naming the resolved path, since an install that a shadowing
+      binary hides succeeds while changing nothing any caller sees;
+    - is actually called, and prints the version on both success paths: a
+      function defined and never invoked has the same exit status and the same
+      empty output as one that worked.
+
+    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
 
 - When pinning images or packages by hash, add a comment above the reference
   with the version and date (YYYY-MM-DD).
@@ -379,7 +572,9 @@ style conventions are in separate documents:
   language-specific config). Everything else goes in a subdirectory. Canonical
   subdirectory names:
     - `bin/` — executable scripts and tools
-    - `cmd/` — Go command entrypoints
+    - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose
+      body is a single call into `internal/` or `pkg/`, no project logic in
+      `cmd/`
     - `configs/` — configuration templates and examples
     - `deploy/` — deployment manifests (k8s, compose, terraform)
     - `docs/` — documentation and markdown (README.md stays in root)

TODO.md

@@ -1,34 +1,422 @@
 # Workflow
 
-* branch per issue from `next`
-* do the work in Next Step
-* move Next Step to the top of Completed Steps
-* move the top item of Future Steps into Next Step
-* commit (`TODO.md` changes in the same commit as the work)
-* open a PR based on `next`
-* an independent reviewer who did not write the change gates it
-* the manager squash-merges the PR into `next` once review passes
-* `next` stays green and mergeable to `main` at any time; only the owner
-  merges `next` into `main`, via the single milestone PR
-* push
+- branch per issue from `next`
+- do the work in Next Step
+- move Next Step to the top of Completed Steps
+- `TODO.md` merges with git's union merge (`.gitattributes`), which never
+  reports a conflict: read the merged entries after every merge or rebase
+- move the top item of Future Steps into Next Step
+- commit (`TODO.md` changes in the same commit as the work)
+- open a PR based on `next`
+- an independent reviewer who did not write the change gates it
+- the manager squash-merges the PR into `next` once review passes
+- `next` stays green and mergeable to `main` at any time; only the owner merges
+  `next` into `main`, via the single milestone PR
+- push
 
 # Status
 
-pre-1.0. No git tags exist. The `1.0.0` milestone is in progress; work
-lands on `next`, and `main` receives only the milestone PR that the
-owner merges. `next` is at the canonical `golangci-lint` v2.12.2 config
-and is green. Recent work extracted the internal/magic,
-internal/allowlist, internal/httpfetcher, and internal/signature
-packages. The gosec findings from the 2026-07-06 survey are resolved.
-The disk cache is now size-bounded with LRU eviction
+pre-1.0. No git tags exist. The `1.0.0` milestone is in progress; work lands on
+`next`, and `main` receives only the milestone PR that the owner merges. `next`
+is at the canonical `golangci-lint` v2.12.2 config and is green. Recent work
+extracted the internal/magic, internal/allowlist, internal/httpfetcher, and
+internal/signature packages. The gosec findings from the 2026-07-06 survey are
+resolved. The disk cache is now size-bounded with LRU eviction
 (`cache_max_bytes`), closing the unbounded disk growth DoS vector.
 
 # Next Step
 
-P2: security: referer blacklist
+P2: security: per-IP rate limiting on the image routes
 
 # Completed Steps
 
+- 2026-10-08 a request past its deadline no longer waits for a database write
+  (closes #224). On a busy host, `TestService_Get_ReturnsByItsDeadline` failed
+  because its request returned over a second after its deadline: it was still
+  waiting for its miss count to be written to the database, a write with no
+  deadline, which in pixad waits for the one database connection that every
+  request shares. The hit, miss, upstream fetch and transform counts are now
+  each written in a goroutine of their own, which the request waits for only
+  until its deadline; a count not written by then is written after the request
+  returns. On shutdown pixad waits for those writes within the same 5 seconds as
+  for the images being processed, and exits with 1 when some are unfinished. The
+  test phase of the `Dockerfile` also runs at most 4 tests of a package at once
+  (`go test -parallel 4`), where it ran as many as the host has CPUs: on a busy
+  host they then wait so long to be scheduled that a test that times a request
+  can fail. `-p`, how many packages are tested at once, is unchanged, as capping
+  it also slows compiling.
+- 2026-10-08 every output format is saved with settings pixa sets on purpose
+  (closes #232): each format has its own govips export, as JPEG XL does, in
+  place of govips' generic `Export`, which sent libvips a zero for some settings
+  it was not given. PNG gets libvips' default compression, 6, where it had none,
+  and WebP libvips' default effort, 4, where it had 0. GIF was already at
+  libvips' default effort, 7, and JPEG output is unchanged. AVIF is saved at
+  effort 1, the lowest govips can set, where it had libvips' default, 4. With
+  one libvips thread, an 8192x8192 image of random pixels, the worst case, takes
+  about 51 seconds as AVIF at effort 1 and 43 as WebP at effort 4, against the
+  default `downstream_timeout` of 60 seconds. On an image of milder noise, which
+  AVIF at effort 1 saves in about 12 seconds, effort 4 takes minutes. AVIF is
+  also saved with 8 bits per sample from a 16-bit source, which libvips would
+  save with 12: a 16-bit 8192x8192 image of milder noise takes about 54 seconds
+  at effort 1 with 12 bits, nearly all of the default `downstream_timeout`, and
+  about 12 with 8.
+- 2026-10-08 JPEG XL is the default output (closes #222): a `/v1/image/` URL
+  whose last segment is a size with no format, such as `800x600` or `orig`, is
+  served as JPEG XL and signed as `jxl`, so it has the signature of the same URL
+  ending in `.jxl`. An encrypted URL whose token holds no format is served as
+  JPEG XL (`encurl.DefaultFormat`). The generator page selects JPEG XL until
+  another format is chosen, and a form with an empty format, or none, makes a
+  JPEG XL URL whose name ends in `.jxl`. The image processor no longer takes an
+  empty format as `orig`: both routes give every request a format, and it
+  refuses a request with none. `auto` still ends with JPEG.
+- 2026-10-08 JPEG XL as an input and output format (part of #222): a source
+  whose bytes start with either JPEG XL signature, the bare codestream's `FF 0A`
+  or the container's, is detected as `image/jxl`, which the upstream fetch
+  accepts; `orig` of such a source is JPEG XL. The format `jxl` works in plain
+  and encrypted URLs and on the generator page, served as `image/jxl` and cached
+  like the other formats. `auto` chooses JPEG XL first when `Accept` names
+  `image/jxl`. govips sends libvips a JPEG XL distance with every save, so
+  libvips ignores the quality: pixa turns `q` into a distance with libvips' own
+  formula, keeping 100 lossy, and removes the metadata from the image before
+  saving, as govips cannot have libvips strip it from JPEG XL. libvips 8.16 and
+  later still write an EXIF block of their own into JPEG XL, from the image's
+  size, orientation and resolution, and fixed values; the image is upright and
+  is given 72 dpi before the save, so the block holds nothing from the source.
+  An image with an ICC profile is converted to sRGB before the JPEG XL save too,
+  and a CMYK image with none is converted to sRGB, as libvips cannot save CMYK
+  as JPEG XL. libvips' default effort, 7, is kept. JPEG XL is not yet the
+  default output.
+- 2026-10-08 pixad runs on the Alpine release it is built on (closes #229): the
+  runtime stage of the `Dockerfile` uses `alpine:3.22`, the release of the
+  `golang:1.25.4-alpine3.22` image that the test phase and the build stage use,
+  so all three have libvips 8.16, where the runtime image had 8.15.
+- 2026-10-08 requests no longer wait behind eviction queries that read a whole
+  table (closes #227): the new `cache_usage` table holds the total cache usage,
+  kept up to date by triggers on `source_content` and `variant_content` in the
+  statement that adds, removes or resizes a row, and `UsageBytes` reads it. The
+  reconciliation pass reads the content tables 1000 rows per query, sums them
+  and corrects the total when it differs, unless a row changed while it summed.
+  Source rows get `last_accessed_at` when added, so choosing source images to
+  evict reads that column's index instead of sorting the whole table.
+- 2026-10-08 libvips' JPEG XL support is installed and required (part of #222):
+  `script/bootstrap --cgo` installs `vips-jxl` when its package manager is apk,
+  as Alpine's `vips` package lacks the support, and the runtime stage of the
+  `Dockerfile` installs it too. `imgcache.NewService` fails, naming the fix,
+  when `imageprocessor.CheckJPEGXLSupport` finds that libvips cannot load and
+  save JPEG XL, so pixad does not start without it. A test saves an image as
+  JPEG XL with govips and loads it back. JPEG XL is not yet a format pixa
+  serves.
+- 2026-10-08 SQLite writes no longer fail with "database is locked" under load
+  (closes #223): `internal/database` opens the database with one connection, so
+  pixa's own reads and writes run on it one at a time instead of competing for
+  SQLite's lock, where a write that kept losing could wait past the five-second
+  busy timeout and be lost. The busy timeout stays, for another program writing
+  to the same file. No code in pixa keeps rows or a transaction open while it
+  runs another query, which with one connection would wait forever.
+- 2026-10-05 the format `auto` (closes #88): a format in the `/v1/image/` path,
+  an encrypted URL's token and the generator page's format choice, chosen for
+  each request from `Accept` once the signature or token is checked: AVIF when
+  the header names `image/avif`, else WebP when it names `image/webp`, else JPEG
+  when the first of `image/jpeg`, `image/*` and `*/*` that it names allows it,
+  or when it names nothing; `q=0` refuses a format. AVIF and WebP must be named,
+  as clients that cannot show them send the wildcards too. A header that allows
+  none of the three answers 406, one that does not parse 400. The signature and
+  the token cover `auto` itself; the cache key and `ETag` use the format chosen.
+  Answers from the point the format is chosen carry `Vary: Accept`, next to the
+  CORS `Vary: Origin`; fixed-format answers do not.
+- 2026-10-05 the markdown is formatted with prettier (closes #100): `script/fmt`
+  and `script/fmt-check` run prettier 3.8.1, pinned in `package.json` and
+  `yarn.lock`, on `**/*.md` after `gofmt`, with four-space tabs and
+  `proseWrap: always` as `.prettierrc` says; `.prettierignore` keeps it off
+  `REPO_POLICIES.md`, the copy from `sneak/prompts`, and `vendor/`. Plain
+  `script/bootstrap` installs Node and Yarn as the one in `sneak/prompts` does
+  and then prettier; `script/bootstrap --cgo` does not, as the `Dockerfile`
+  stages that run it format nothing. The HTML templates stay unformatted:
+  prettier cannot parse a Go template action inside a tag. The markdown was
+  reflowed in a commit of its own.
+- 2026-10-05 lint and tests run as the `lint` and `test` phases of the
+  `Dockerfile`, built with `--no-cache` (closes #202): `script/check`,
+  `script/cibuild`, `script/docker`, `script/lint`, `script/test`,
+  `script/setup` and `script/install-precommit` are now the copies from
+  `sneak/prompts` `main`, unchanged. The `lint` phase runs golangci-lint from
+  the image `REPO_POLICIES.md` names, with `libvips-dev` from `apt-get`; the
+  `test` phase runs the tests with a 90-second timeout; the build stage depends
+  on both. `Dockerfile.lint` and the `CHECK_EPOCH` build argument are gone, the
+  formatting check runs on the host, and `make docker-versioned` and
+  `make docker-test` call the scripts. `script/bootstrap`, `script/fmt`,
+  `script/fmt-check`, `script/precommit` and `script/projectname` stay pixa's
+  own. `script/bootstrap` installs git, make and Go, refreshing apt's package
+  lists before its first apt install; with `--cgo`, which only the `test` phase
+  and the build stage pass, it also installs the C compiler and the libvips and
+  libheif libraries. The stage that compiles still takes the version from
+  `git describe` when no `VERSION` is given, per
+  https://git.eeqj.de/sneak/pixa/issues/166, so the copied scripts' comment that
+  `.dockerignore` leaves out `.git` does not hold for pixa.
+- 2026-10-04 load test (closes #81): `script/loadtest [duration [clients]]`
+  (`make loadtest`, defaults `10s` and `4`), a benchmark that `script/check`
+  does not run, measures three scenarios, each against a new pixad container and
+  a new upstream host, `cmd/loadtest-origin`: `hit` (one cached image), `miss`
+  (a new source image every request) and `herd` (each new source image asked for
+  by all clients at once). For each it prints vegeta's report (requests per
+  second, latency percentiles, status codes), pixad's peak resident memory and
+  the requests that reached the origin. `README.md` says how to run it and read
+  it, and keeps 1-5k r/s as a target not yet measured. First measurement, with
+  the defaults on a shared 48-CPU machine with other work running: a baseline
+  for later changes, not a test of the target. `hit` 1413 r/s, p50 0.7 ms, p95
+  8.7 ms, p99 44 ms, peak 53 MiB (4 clients that each wait for their answer, so
+  not pixad's limit); `miss` 70 r/s, p50 52 ms, p95 91 ms, p99 122 ms, peak 100
+  MiB, one fetch per request; `herd` 74 r/s, p50 52 ms, p95 69 ms, p99 111 ms,
+  peak 60 MiB, 188 fetches for 749 requests.
+- 2026-10-04 the CI checkout fetches the tags (closes #208): the checkout step
+  in `.gitea/workflows/check.yml` sets `fetch-depth: 0`, as `REPO_POLICIES.md`
+  asks of a repo that takes its version from the tags, so a CI build of a tagged
+  commit stamps the tag from `git describe` instead of a bare commit.
+- 2026-10-04 `config.yml` stays out of git and the Docker build context (closes
+  #212): `.gitignore` now ignores `config.yml`, the config file Getting Started
+  creates with the signing key, and `.dockerignore` leaves it out in every
+  directory and in any letter case, as it already did `config.yaml` and
+  `config.dev.yml`.
+- 2026-10-04 local config files stay out of the Docker build context (closes
+  #211): `.dockerignore` now leaves out `config.yaml` and `config.dev.yml` in
+  every directory and in any letter case, the local config files `.gitignore`
+  keeps out of git because they can hold the signing key.
+  `configs/config.example.yml` is still sent. `config.yml`, which Getting
+  Started creates, is in neither file:
+  https://git.eeqj.de/sneak/pixa/issues/212.
+- 2026-10-04 `cmd/pixad/main.go` is one call into `internal/` (closes #206):
+  what it did (the command line and its `--config` flag, setting
+  `PIXA_CONFIG_PATH`, ignoring `SIGPIPE`, starting the fx app) is now `Run` in
+  `internal/app`, unchanged, and `main` calls it with `Version`, which the build
+  still sets through `-X main.Version`. That code had no tests to move.
+- 2026-10-04 `.gitignore` ignores `.claude/` (closes #204): the entry and its
+  comment are copied from the canonical `.gitignore` in `sneak/prompts`,
+  unanchored so it matches at every depth. `.dockerignore` already has
+  `.claude`.
+- 2026-10-04 `.dockerignore` keeps secrets out at every depth (closes #205): the
+  file is now the standard one from `sneak/prompts`, whose patterns match in
+  every directory and, for environment files and private keys, in any letter
+  case, so a nested `.env` or `server.key` no longer reaches the build context.
+  pixa still sends `.git` without `.git/config` in place of the standard file's
+  `.git` line, and still leaves out `.gitignore`, `/bin` and `/data`.
+- 2026-10-04 `REPO_POLICIES.md` matches the canonical copy again (closes #196):
+  it is replaced, unchanged, by `prompts/REPO_POLICIES.md` from `sneak/prompts`
+  `main`. The rules it adds that pixa's tree breaks are filed:
+  https://git.eeqj.de/sneak/pixa/issues/202 (lint and tests as `Dockerfile`
+  phases built with `--no-cache`), https://git.eeqj.de/sneak/pixa/issues/203
+  (the workflow's `script/docker-smoke` step),
+  https://git.eeqj.de/sneak/pixa/issues/204 (`.claude/` in `.gitignore`),
+  https://git.eeqj.de/sneak/pixa/issues/205 (`.dockerignore` patterns at every
+  depth), https://git.eeqj.de/sneak/pixa/issues/206 (a thin `cmd/pixad/main.go`)
+  and https://git.eeqj.de/sneak/pixa/issues/208 (`fetch-depth: 0` on the CI
+  checkout, so the build sees the tags). Its rule that no build stage runs
+  `git describe` is not followed: pixa takes the version from the `.git` in the
+  build context, per https://git.eeqj.de/sneak/pixa/issues/166, as the copy on
+  `sneak/prompts` `next` already says.
+- 2026-10-04 an integration test of the image proxy flow (closes #80):
+  `TestImageProxyFlow` in `internal/server` starts the database, handlers and
+  middleware from the constructors `pixad` uses, with a fresh state directory,
+  and replaces only the upstream origin with a local test server. For a resize
+  with a change to JPEG and for `orig`, the first request goes through the
+  router, the real fetcher, libvips, the disk cache and SQLite and answers 200
+  with the right content type and size and `X-Pixa-Cache: MISS`; the second
+  answers `HIT` with the same image and the upstream has had one request; the
+  source and the converted image are then in `cache/sources` and
+  `cache/variants`, with their rows in `source_content`, `source_metadata` and
+  `variant_content`. Two optional fields make this possible, which `pixad` does
+  not set and the config file and environment cannot:
+  `httpfetcher.Config.DialContext` connects in place of the dialer that refuses
+  internal addresses, the URL and redirect checks still running, and
+  `handlers.Params.Fetcher` replaces the fetcher the handlers build.
+- 2026-10-04 a URL made on the generator page with a `ttl` is tested to expire
+  (closes #199): a new test in `internal/handlers` makes a URL on the generator
+  page with a `ttl` of one second, checks that `/v1/e/` serves it at once, waits
+  two seconds and checks that it then answers 410. The test waits for real, as
+  pixa reads the clock directly when it makes and checks a URL; it waits two
+  seconds because the time a URL expires is kept in whole seconds. Test only.
+- 2026-10-04 referer blocklist (closes #90): `referer_blocklist`
+  (`PIXA_REFERER_BLOCKLIST`) lists hosts, written and matched as for
+  `allowlist_hosts` with the same matcher; an entry of either list that is
+  neither a host name (letters, digits, hyphens, underscores and dots, with at
+  most one leading dot) nor an IP address, such as one with a port or a `*.`
+  wildcard, aborts startup naming the setting and the entry. Both image routes
+  refuse a request whose `Referer` names a listed host with 403 and a JSON error
+  before the signature, the cache and the upstream fetch, so it fetches nothing
+  and is refused whether or not the image is cached. A request with no
+  `Referer`, or one that does not parse as a URL with a host, is served, so the
+  list is easily got around; `README.md` and `configs/config.example.yml` say
+  so. It does not apply to the login and generator pages.
+- 2026-10-04 fewer files in the repository root (closes #97):
+  `config.example.yml` moved unchanged to `configs/config.example.yml`, and
+  `README.md`, the comments in `internal/config/config.go` and the startup error
+  for the placeholder signing key name the new path; `scripts/manual-test.sh`
+  and its directory are deleted, as the handler tests in `internal/handlers`
+  cover every check it made except two: fetching a real image from the internet,
+  and a URL made on the generator page with a `ttl` answering 410 once the `ttl`
+  has passed (https://git.eeqj.de/sneak/pixa/issues/199); `CONVENTIONS.md` is
+  deleted, as `REPO_POLICIES.md` links the canonical Go HTTP server conventions.
+- 2026-10-04 SQLite writes no longer fail with "database is locked" (closes
+  #198): pixa adds `_pragma=busy_timeout(5000)` to every `db_url`, so a write
+  that finds another in progress on another connection waits up to five seconds
+  for it, and the default `db_url` turns on WAL mode with
+  `_pragma=journal_mode(WAL)`. The old default's `_journal_mode=WAL` is not a
+  parameter the driver reads, so the database was never in WAL mode.
+- 2026-10-04 `TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup` only
+  passes through a periodic pass (closes #189): it slept for three eviction
+  intervals before writing its file, and a startup pass still running then could
+  adopt the file itself. It now holds the test database's only connection until
+  the startup pass waits for it after walking the empty variant directory,
+  writes the file and lets the connection go, as
+  `TestEvictionRunsOnPeriodicSchedule` does, so only a periodic reconciliation
+  pass can adopt the file. Test only.
+- 2026-10-04 logging in, logging out, the URL generator and `/v1/e/` have
+  handler tests (closes #77): new tests in `internal/handlers`, with no network,
+  check that `GET /` without a login session shows the login form; a wrong key
+  shows it again with an error and sets no session cookie; the right key answers
+  303 to `/` with a session cookie marked `Secure`, `HttpOnly` and
+  `SameSite=Strict`, with which `GET /` shows the generator page; `GET /logout`
+  answers 303 to `/` with an empty session cookie sent with `Max-Age=0`;
+  `POST /generate` without a login session answers 303 to `/`; `/v1/e/` serves
+  the image for a valid token, answers 410 for an expired one and 400 for one
+  with a character changed, cut short or made with another signing key; and a
+  URL made on the generator page is served by `/v1/e/`. No code changes.
+- 2026-10-04 `TODO.md` merges with git's union merge (closes #190): a root
+  `.gitattributes`, copied from `sneak/prompts`, marks it `merge=union`, so two
+  branches that each add an entry at the top of Completed Steps merge without a
+  conflict and keep both entries. Git now never reports a conflict in `TODO.md`:
+  a real one keeps both versions of the lines, and two entries that share an
+  identical line can end up one inside the other, which a rebase can do to an
+  entry already on `next`. The Workflow above says to read the merged entries
+  after every merge or rebase.
+- 2026-10-04 the default `cache_max_bytes` no longer shrinks as the cache fills
+  (closes #184): for an omitted key, the cache works out the limit when it
+  opens, after the database is open, as 75% of the sum of the free space on the
+  filesystem containing `<state_dir>/cache/` and what the cache already holds by
+  its own size accounting, at least 500 MiB, so a cache filled to its limit
+  keeps that limit across a restart. The computation and its tests moved from
+  `internal/config` to `internal/imgcache`; the config only records whether the
+  key was set.
+- 2026-10-04 `TestEvictionRunsOnPeriodicSchedule` no longer races the evictor
+  (closes #183): it wrote each variant file and then inserted its accounting row
+  by hand, and a reconciliation pass between the two adopted the file first, so
+  the insert failed. It now writes the files only, while holding the test
+  database's only connection so the evictor's startup pass waits after walking
+  the empty variant directory; a periodic reconciliation pass then adopts the
+  files and the eviction pass after it evicts them. No other test in
+  `internal/imgcache` inserts a row by hand after starting the evictor. Test
+  only.
+- 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 the Content-Security-Policy allows no inline script or style
+  (closes #125): `script-src` and `style-src` are `'self'` only. The generator
+  page's two inline `onclick` handlers moved into
+  `internal/static/generator.js`, attached with `addEventListener`; the bundled
+  Tailwind script, which built styles in the browser, is replaced by a small
+  hand-written `internal/static/style.css` with only the rules the login and
+  generator pages use, the templates carrying a few plain class names in place
+  of Tailwind's. No build step. The pages keep their layout, not every pixel of
+  it.
+- 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 and lets
+  the configured ones through; a preflight request gets `*` for any origin when
+  `access_control_allow_origin` is `*` and no `Access-Control-Allow-Origin` from
+  another origin than the configured one; a `POST /` carrying the signing key
+  leaves no trace of it in the request log line, and the login handler's own log
+  lines leave out the submitted key; the metrics middleware on its own records a
+  request it served, and the router records nothing while no metrics username is
+  set. Not tested: that the router puts the basic auth in front of `/metrics`
+  and records requests when a metrics username is set. Only one test per package
+  can set up `/metrics`, and in `internal/server` that is
+  `TestMaintenanceModeKeepsOtherRoutes`, which needs the owner's approval to
+  change; #180 holds it. Tests only; the basic auth library already compares the
+  password in constant time.
+- 2026-10-04 the image route's signature check and error answers are tested
+  (closes #76): new tests in `internal/handlers`, with no network, check the
+  status and JSON error body for a missing, wrong, unpadded, upper-case or
+  expired signature on a host not on the allowlist, or a valid one sent for its
+  parent domain, a sibling host, a subdomain or the host with another domain
+  appended (401), an unparseable path (400), `localhost` as the upstream host
+  (403) and an upstream error (502); that an allowlisted host is served without
+  a signature, another host only with a valid one; and the answers of
+  `/robots.txt` and the health check. No code changes.
+- 2026-10-04 request IDs returned and passed on, and `/v1/e/` revalidates
+  (closes #84): pixa's own `RequestID` middleware, in place of chi's, gives each
+  request an ID, its own `X-Request-ID` when that is at most 64 letters, digits,
+  `-`, `_` or `.` and a random one otherwise, stores it where chi's did and
+  sends it back as `X-Request-ID` on every response; the upstream fetch sends
+  that ID, and the "upstream fetched", "image converted" and "image served" log
+  lines carry it as `request_id`, a fetch shared by several requests carrying
+  the first request's; `/v1/e/` sets `ETag`, answers a matching `If-None-Match`
+  with 304 and is routed for `HEAD`, the `ETag` and 304 code being
+  `notModified`, which `/v1/image/` calls too; its token checks moved unchanged
+  into `parseImageEncRequest` to keep `HandleImageEnc` within the line limit; no
+  `Vary` is added, as no response depends on a request header except the image
+  routes' CORS headers, for which `go-chi/cors` already sends `Vary: Origin`;
+  `Vary: Accept` is left to #88.
+- 2026-10-04 routes, encrypted URLs and config file documented (closes #75):
+  "Routes" in `README.md` lists every route with its method, purpose, what it
+  needs and the status codes it answers with, and says `q` and `fit` are part of
+  what is cached; "Encrypted URLs" covers logging in, making one on the
+  generator page, how long it lasts and the 410 once it has expired;
+  "Configuration" gives the order in which pixa looks for its config file;
+  `config.example.yml` lists `db_url` and `env` and gives every key's default;
+  `scripts/manual-test.sh` is left to #97.
+- 2026-10-04 shutdown stops cache eviction in progress (closes #102):
+  `StartEviction` runs the eviction goroutine with its own context, which
+  `StopEviction` cancels, so a pass in progress stops at its next database call,
+  file, row or eviction candidate instead of running to completion, and no pass
+  starts after it, so a stop logs at most one warning; `StopEviction` takes a
+  context and, when that context ends before the goroutine exits, stops waiting
+  and returns its error; the handlers' stop hook passes fx's stop context, so an
+  eviction still running when fx's stop deadline ends fails the stop and makes
+  the exit code 1.
+- 2026-10-04 dead code in `internal/imgcache` is gone (closes #73): `Purge`,
+  which only returned an error and which nothing called, is no longer part of
+  the `ImageCache` interface or `Service`; the `SignatureValidator`, `Allowlist`
+  and `Storage` interfaces, which nothing implemented or used, are deleted.
+  Nothing else changes.
+- 2026-10-04 upstream host semaphores and variant `.meta` files no longer
+  outlive their use (closes #87): the fetcher counts the fetches holding or
+  waiting for a slot of each upstream host's semaphore and removes the host's
+  semaphore once none is left, so fetches from many hosts no longer leave one
+  semaphore each until restart; `VariantStorage.Delete` removes the variant's
+  `.meta` file along with it, a missing `.meta` file not being an error, and
+  `DeleteWithMeta`, which eviction called for that, is gone.
+- 2026-10-04 `README.md` matches the code (closes #74): "Storage" names the
+  cache directories pixa uses (`cache/sources`, `cache/metadata`,
+  `cache/variants`) and how files are named in each, and the comments in
+  `001_schema.sql` name the same paths; the routes and the signature section
+  list the same output formats, `jpg` and `original` included; the TLS sentence
+  names `allow_http` as its exception; "Metrics" says only generic HTTP and Go
+  runtime metrics exist, measured and served only when the metrics username and
+  password are set.
+- 2026-10-03 shutdown sets the exit code and waits for image processing (closes
+  #86): fx alone handles SIGINT and SIGTERM, and the server's own signal handler
+  is gone; fx's `Run` in `cmd/pixad` exits with the shutdown's code: 0 for a
+  signal, 1 when the HTTP server cannot listen or the app fails to start or to
+  stop; the server's stop hook, which fx waits for, stops the HTTP server, waits
+  for the images still being processed, both within 5 seconds, then flushes
+  Sentry; images still being processed after that are logged with their count
+  and make the exit code 1; a Sentry DSN that cannot be used fails startup, so
+  the stop hooks of what had already started run, instead of exiting the process
+  from a goroutine; the eviction loop is left to #102.
 - 2026-10-03 every `script/cibuild` and `script/docker` run executes the checks
   (closes #101): the `Dockerfile` declares `CHECK_EPOCH` above `make fmt-check`
   and `make lint` in the lint stage and above `make test` in the build stage,
@@ -43,11 +431,11 @@ P2: security: referer blacklist
   upstream fetch or cached source read and one transcode through
   `golang.org/x/sync/singleflight`; the first request's processing ignores its
   cancellation but keeps its deadline, and the others wait for its image or
-  error holding no upstream connection or processing slot, and stop waiting
-  when their own context ends; the request doing the processing waits for it
-  even then, up to its deadline; a request whose context has already ended
-  starts nothing; each request counts one miss, and the processing counts its
-  fetch and transcode once; a panic while processing is reported to Sentry when
+  error holding no upstream connection or processing slot, and stop waiting when
+  their own context ends; the request doing the processing waits for it even
+  then, up to its deadline; a request whose context has already ended starts
+  nothing; each request counts one miss, and the processing counts its fetch and
+  transcode once; a panic while processing is reported to Sentry when
   `sentry_dsn` is set and becomes an error for every waiting request instead of
   stopping pixad; documented in `README.md`.
 - 2026-09-29 only the image routes send CORS headers (closes #98): the CORS
@@ -56,20 +444,20 @@ P2: security: referer blacklist
   still answers a preflight `OPTIONS` request; the login and URL generator
   pages, `/metrics` and the other routes send no `Access-Control-Allow-Origin`;
   documented in `README.md` and `config.example.yml`.
-- 2026-10-02 a plain `docker build .` stamps the tag or short commit, not
-  `dev` (closes #166): `.dockerignore` lets `.git` into the build context,
-  without `.git/config`; with no `VERSION` build argument the `Dockerfile`
-  takes the version from `git describe --tags --always`, and fails the build if
-  the context carries `.git` and no version comes out; `ARG VERSION` has no
-  default; pixad logs its version, with its name and architecture, as its first
-  log line at startup.
-- 2026-09-29 the container makes `/var/lib/pixa` usable by itself (closes
-  #159): `deploy/docker-entrypoint.sh` creates the directory if it is missing,
-  gives the directory and everything in it to `pixad` when the directory or one
-  of its top-level entries belongs to another user or group, sets its mode to
-  `750`, then runs the server as `pixad`; data left by an earlier run under
-  another uid is taken over this way; "Running under upaas" in `README.md` no
-  longer tells the operator to create or chown the host directory.
+- 2026-10-02 a plain `docker build .` stamps the tag or short commit, not `dev`
+  (closes #166): `.dockerignore` lets `.git` into the build context, without
+  `.git/config`; with no `VERSION` build argument the `Dockerfile` takes the
+  version from `git describe --tags --always`, and fails the build if the
+  context carries `.git` and no version comes out; `ARG VERSION` has no default;
+  pixad logs its version, with its name and architecture, as its first log line
+  at startup.
+- 2026-09-29 the container makes `/var/lib/pixa` usable by itself (closes #159):
+  `deploy/docker-entrypoint.sh` creates the directory if it is missing, gives
+  the directory and everything in it to `pixad` when the directory or one of its
+  top-level entries belongs to another user or group, sets its mode to `750`,
+  then runs the server as `pixad`; data left by an earlier run under another uid
+  is taken over this way; "Running under upaas" in `README.md` no longer tells
+  the operator to create or chown the host directory.
 - 2026-09-29 variant content types kept in memory (closes #70):
   `Cache.metaCache` holds the content types of up to 10,000 variants in an LRU
   (`github.com/hashicorp/golang-lru/v2`), filled by `StoreVariant` and by
@@ -108,8 +496,8 @@ P2: security: referer blacklist
   `ARG VERSION` sits just above the build, so a new version reruns neither
   `script/bootstrap` nor the tests.
 - 2026-09-29 migrations at the path `REPO_POLICIES.md` sets (closes #96): the
-  migration files moved, contents unchanged, from `internal/database/schema/`
-  to `internal/db/migrations/` as `000_migration.sql` and `001_schema.sql`; the
+  migration files moved, contents unchanged, from `internal/database/schema/` to
+  `internal/db/migrations/` as `000_migration.sql` and `001_schema.sql`; the
   `internal/db/migrations` package embeds them and `internal/database` reads
   them through its `FS()`; the `internal/database` package itself stays; the
   version still comes from the filename prefix, so a database that has recorded
@@ -124,8 +512,8 @@ P2: security: referer blacklist
   `=` padding kept, and gives the example's `sig` for a stated signing key.
 - 2026-09-29 fixed uid and gid for `pixad` (closes #151): the image creates the
   `pixad` group with gid 65532 and the `pixad` user with uid 65532, instead of
-  the first free uid 1000, so a bind-mounted `/var/lib/pixa` given to `pixad`
-  is not owned on the host by a person's login account; the first-run step of
+  the first free uid 1000, so a bind-mounted `/var/lib/pixa` given to `pixad` is
+  not owned on the host by a person's login account; the first-run step of
   "Running under upaas" in `README.md` names the uid and gid.
 - 2026-09-29 `max-age` never outlives an expiring URL (closes #63): both image
   routes build `Cache-Control` from the request's `Expires`, which an encrypted
@@ -134,29 +522,27 @@ P2: security: referer blacklist
   that is sooner, never negative; an allowlisted host's URL that has an `exp`
   follows it too; `immutable` stays, as freshness now ends at the expiry;
   documented in `README.md`.
-- 2026-09-28 add the four settings `README.md` documented but pixa did not
-  have, which aborted startup as unknown keys (closes #61):
+- 2026-09-28 add the four settings `README.md` documented but pixa did not have,
+  which aborted startup as unknown keys (closes #61):
   `access_control_allow_origin` (default `*`, the CORS origin),
   `upstream_fetch_timeout` (default `30s`), `upstream_max_response_size`
-  (default 50 MiB) and `downstream_timeout` (default `60s`, both the
-  server's write timeout and the per-request timeout); each has a
-  `PIXA_` variable; durations are positive Go duration strings, the size a
-  whole number of bytes up to 1 GiB, the origin `*` or one `http` or
-  `https` origin as `README.md` describes it; an invalid value
-  aborts startup naming the key and the value; documented in
-  `config.example.yml` and `README.md`.
-- 2026-09-28 cache stats report real numbers (closes #56): `Cache.Stats`
-  counts the cached source images and processed variants (`source_content`
-  plus `variant_content`) and takes their size from `Cache.UsageBytes`,
-  instead of reading `request_cache` and `output_content`, which nothing
-  writes; those two tables are left in the schema; a disabled disk cache
-  reports no items and no size. A hit is counted even when the request
-  context has ended. A miss is counted after it is served or fails, also
-  when the request context has ended by then, with the bytes it read from
-  upstream, so `upstream_fetch_count` and `upstream_fetch_bytes` move,
-  including for an upstream body that fails partway or a fetched source
-  that then fails the magic byte check; `transform_count` counts each image
-  the image processor transcodes.
+  (default 50 MiB) and `downstream_timeout` (default `60s`, both the server's
+  write timeout and the per-request timeout); each has a `PIXA_` variable;
+  durations are positive Go duration strings, the size a whole number of bytes
+  up to 1 GiB, the origin `*` or one `http` or `https` origin as `README.md`
+  describes it; an invalid value aborts startup naming the key and the value;
+  documented in `config.example.yml` and `README.md`.
+- 2026-09-28 cache stats report real numbers (closes #56): `Cache.Stats` counts
+  the cached source images and processed variants (`source_content` plus
+  `variant_content`) and takes their size from `Cache.UsageBytes`, instead of
+  reading `request_cache` and `output_content`, which nothing writes; those two
+  tables are left in the schema; a disabled disk cache reports no items and no
+  size. A hit is counted even when the request context has ended. A miss is
+  counted after it is served or fails, also when the request context has ended
+  by then, with the bytes it read from upstream, so `upstream_fetch_count` and
+  `upstream_fetch_bytes` move, including for an upstream body that fails partway
+  or a fetched source that then fails the magic byte check; `transform_count`
+  counts each image the image processor transcodes.
 - 2026-09-28 strip metadata from processed images (closes #82): every output is
   exported with govips' `StripMetadata`, so it carries no EXIF, XMP, IPTC or ICC
   profile; the image is first turned upright with `AutoRotate` (before sizes are
@@ -167,241 +553,213 @@ P2: security: referer blacklist
   attempts per minute per client address, and an attempt over the limit is
   refused with 429 and a `Retry-After` header; the address is the one
   `internal/clientip` resolves through `trusted_proxies`, an IPv6 client is
-  counted by its /64, and an IPv4-mapped address as the IPv4 address it
-  carries; the limit is a `RateLimit` middleware in `internal/middleware` on
+  counted by its /64, and an IPv4-mapped address as the IPv4 address it carries;
+  the limit is a `RateLimit` middleware in `internal/middleware` on
   `github.com/go-chi/httprate`, which the image routes can reuse; the library
   keeps counts for the current and the previous minute only; documented in
   `README.md`.
-- 2026-09-28 refuse an unparseable `exp` on `/v1/image/` and log swallowed
-  cache errors (closes #72): an `exp` in the URL that is not a whole
-  number, an empty `exp=` included, is a 400 naming `exp` and the value,
-  instead of being ignored and answered with 401 as if the URL had no
-  `exp`; only an `exp` missing from the URL is unchanged; `README.md` says
-  so where it documents `exp`. A failed variant `.meta` write, source
-  metadata JSON write, `Stats` count query, stats counter update, negative
-  cache write or expired negative cache delete is now logged at `warn`
-  with the path or key and the error, and stays non-fatal.
-- 2026-09-28 refuse an empty `fit` on `/v1/image/` (closes #139): a
-  `fit` in the URL with an empty value (`fit=`) is a 400 naming `fit`,
-  instead of being served as `cover` and verified against a signature
-  made for `cover`; only a `fit` missing from the URL is still `cover`;
-  any other value still goes through the existing fit-mode check;
-  `README.md` says so where it documents `fit`.
-- 2026-09-28 refuse an invalid `q` on `/v1/image/` (closes #134): a `q`
-  that is not a whole number from 1 to 100, an empty `q` included, is a
-  400 naming `q` and the value, instead of being served at the default
-  85; the route reads `q` with the generator's quality check
-  (`parseFormInt` with `minQuality` and `maxQuality`); only a `q` missing
-  from the URL is still 85; a query string that cannot be decoded, such
-  as `q=80%`, is a 400 showing it; any query parameter given more than
-  once (`q`, `fit`, `sig`, `exp` alike) is a 400 naming it, so none is
-  read from its first value only; `README.md` states the range and both
-  query-string rules.
-- 2026-09-28 unknown `PIXA_` environment variables abort startup (closes
-  #133): a variable whose name starts with `PIXA_` but is neither a
-  setting's variable nor `PIXA_CONFIG_PATH` aborts startup naming it, as
-  an unknown config key does, and `PIXA_PORT` is named with a pointer to
-  `PORT`; the check runs after the config file loads, so the variables
-  the file's `env:` section sets are checked too; documented in
-  `README.md`.
-- 2026-09-28 start on a fresh upaas volume (closes #129): the image
-  starts as root only to give `/var/lib/pixa` to `pixad` when `pixad`
-  does not own it (`deploy/docker-entrypoint.sh`), then runs the server
-  as `pixad` through `su-exec`, so a root-owned host directory
-  bind-mounted there no longer stops the container at startup;
-  `README.md` gains a "Running under upaas" section.
-- 2026-09-28 run all linting in Docker via `Dockerfile.lint` +
-  `script/lint` (closes #104): `make lint` calls `script/lint`, the only
-  way the linter is run; inside a container (both Dockerfiles set
-  `container=docker`) it runs `golangci-lint`, anywhere else it builds the
-  hash-pinned `Dockerfile.lint`, whose last step runs `script/lint` again;
-  the `Dockerfile` lint stage runs `make lint`; no host or nix-shell
-  `golangci-lint` path remains (`script/bootstrap` installs no linter);
-  a per-run `CACHEBUST` build-arg keeps the lint step from being served
-  from cache, and a tmpfs mount on that step keeps Go's and
-  golangci-lint's caches out of its layer, so a run leaves no large build
-  cache behind; `golangci-lint config verify` stays out, as it fetches its
-  schema over an unpinned live HTTPS call
-- 2026-09-28 every setting as an environment variable (closes #128, also
-  covers #99): each config key can be set by `PIXA_` plus the key in upper
-  case (`.` written as `_`), and the port by `PORT`; a variable present in
-  the environment, even empty, wins over the config file, which wins over
-  the default; the typed getters read the variable first, so every existing
-  check applies to it and a bad value aborts startup naming the variable;
-  lists are comma-separated, and an empty variable (or `""` in the file) is
-  an empty list; the Docker image no longer bakes in `config.docker.yml` or
-  passes `--config`, and its `HEALTHCHECK` probes `PORT` (default `8080`);
-  the config file is looked for under `/etc/pixa` and `~/.config/pixa`
-  instead of the daemon name `pixad`; documented in `README.md` and
-  `config.example.yml`.
-- 2026-09-28 quality and fit in the URL signature (closes #60): the signed
-  data is now `host:path:query:width:height:format:expiration:quality:fit`,
-  using `85` and `cover` when the URL has no `q` or `fit`, so one signed
-  URL can no longer be replayed across other quality and fit values to
-  create unauthorized cache entries and transcodes; the known-answer
-  vectors in `internal/signature/golden_test.go` and the README signature
-  specification describe the new format.
-- 2026-09-28 Docker image healthcheck (closes #111): a `HEALTHCHECK` in
-  the runtime stage probing `/.well-known/healthcheck.json` with busybox
-  `wget`; `script/docker-smoke` (`make docker-smoke`) builds the image,
-  starts it with a throwaway `PIXA_SIGNING_KEY`, and passes only once
-  Docker reports it healthy within 30 seconds, removing the container on
-  exit; the Gitea workflow runs it after `script/cibuild`.
+- 2026-09-28 refuse an unparseable `exp` on `/v1/image/` and log swallowed cache
+  errors (closes #72): an `exp` in the URL that is not a whole number, an empty
+  `exp=` included, is a 400 naming `exp` and the value, instead of being ignored
+  and answered with 401 as if the URL had no `exp`; only an `exp` missing from
+  the URL is unchanged; `README.md` says so where it documents `exp`. A failed
+  variant `.meta` write, source metadata JSON write, `Stats` count query, stats
+  counter update, negative cache write or expired negative cache delete is now
+  logged at `warn` with the path or key and the error, and stays non-fatal.
+- 2026-09-28 refuse an empty `fit` on `/v1/image/` (closes #139): a `fit` in the
+  URL with an empty value (`fit=`) is a 400 naming `fit`, instead of being
+  served as `cover` and verified against a signature made for `cover`; only a
+  `fit` missing from the URL is still `cover`; any other value still goes
+  through the existing fit-mode check; `README.md` says so where it documents
+  `fit`.
+- 2026-09-28 refuse an invalid `q` on `/v1/image/` (closes #134): a `q` that is
+  not a whole number from 1 to 100, an empty `q` included, is a 400 naming `q`
+  and the value, instead of being served at the default 85; the route reads `q`
+  with the generator's quality check (`parseFormInt` with `minQuality` and
+  `maxQuality`); only a `q` missing from the URL is still 85; a query string
+  that cannot be decoded, such as `q=80%`, is a 400 showing it; any query
+  parameter given more than once (`q`, `fit`, `sig`, `exp` alike) is a 400
+  naming it, so none is read from its first value only; `README.md` states the
+  range and both query-string rules.
+- 2026-09-28 unknown `PIXA_` environment variables abort startup (closes #133):
+  a variable whose name starts with `PIXA_` but is neither a setting's variable
+  nor `PIXA_CONFIG_PATH` aborts startup naming it, as an unknown config key
+  does, and `PIXA_PORT` is named with a pointer to `PORT`; the check runs after
+  the config file loads, so the variables the file's `env:` section sets are
+  checked too; documented in `README.md`.
+- 2026-09-28 start on a fresh upaas volume (closes #129): the image starts as
+  root only to give `/var/lib/pixa` to `pixad` when `pixad` does not own it
+  (`deploy/docker-entrypoint.sh`), then runs the server as `pixad` through
+  `su-exec`, so a root-owned host directory bind-mounted there no longer stops
+  the container at startup; `README.md` gains a "Running under upaas" section.
+- 2026-09-28 run all linting in Docker via `Dockerfile.lint` + `script/lint`
+  (closes #104): `make lint` calls `script/lint`, the only way the linter is
+  run; inside a container (both Dockerfiles set `container=docker`) it runs
+  `golangci-lint`, anywhere else it builds the hash-pinned `Dockerfile.lint`,
+  whose last step runs `script/lint` again; the `Dockerfile` lint stage runs
+  `make lint`; no host or nix-shell `golangci-lint` path remains
+  (`script/bootstrap` installs no linter); a per-run `CACHEBUST` build-arg keeps
+  the lint step from being served from cache, and a tmpfs mount on that step
+  keeps Go's and golangci-lint's caches out of its layer, so a run leaves no
+  large build cache behind; `golangci-lint config verify` stays out, as it
+  fetches its schema over an unpinned live HTTPS call
+- 2026-09-28 every setting as an environment variable (closes #128, also covers
+  #99): each config key can be set by `PIXA_` plus the key in upper case (`.`
+  written as `_`), and the port by `PORT`; a variable present in the
+  environment, even empty, wins over the config file, which wins over the
+  default; the typed getters read the variable first, so every existing check
+  applies to it and a bad value aborts startup naming the variable; lists are
+  comma-separated, and an empty variable (or `""` in the file) is an empty list;
+  the Docker image no longer bakes in `config.docker.yml` or passes `--config`,
+  and its `HEALTHCHECK` probes `PORT` (default `8080`); the config file is
+  looked for under `/etc/pixa` and `~/.config/pixa` instead of the daemon name
+  `pixad`; documented in `README.md` and `config.example.yml`.
+- 2026-09-28 quality and fit in the URL signature (closes #60): the signed data
+  is now `host:path:query:width:height:format:expiration:quality:fit`, using
+  `85` and `cover` when the URL has no `q` or `fit`, so one signed URL can no
+  longer be replayed across other quality and fit values to create unauthorized
+  cache entries and transcodes; the known-answer vectors in
+  `internal/signature/golden_test.go` and the README signature specification
+  describe the new format.
+- 2026-09-28 Docker image healthcheck (closes #111): a `HEALTHCHECK` in the
+  runtime stage probing `/.well-known/healthcheck.json` with busybox `wget`;
+  `script/docker-smoke` (`make docker-smoke`) builds the image, starts it with a
+  throwaway `PIXA_SIGNING_KEY`, and passes only once Docker reports it healthy
+  within 30 seconds, removing the container on exit; the Gitea workflow runs it
+  after `script/cibuild`.
 - 2026-09-21 trusted-proxy client IP resolution (closes #94): a
   `trusted_proxies` config key taking a list of CIDRs, parsed by the same
-  `net/netip` list parser as `blocked_networks` (an invalid entry aborts
-  startup naming the key and value; an omitted key defaults to the RFC 1918
-  private ranges, an explicitly empty list trusts no one, and an explicit
-  list replaces the default); a new
-  `internal/clientip` package resolves the client address by honoring
-  `X-Forwarded-For` only when the direct peer is a trusted proxy, walking
-  the chain right-to-left to the rightmost non-proxy entry, so a client
-  connecting directly cannot spoof its address; the resolved address is
-  stored in the request context by a new middleware and used by the
-  request-logging middleware and the login-attempt logs in place of the
-  raw peer address; documented in `README.md` and `config.example.yml`.
+  `net/netip` list parser as `blocked_networks` (an invalid entry aborts startup
+  naming the key and value; an omitted key defaults to the RFC 1918 private
+  ranges, an explicitly empty list trusts no one, and an explicit list replaces
+  the default); a new `internal/clientip` package resolves the client address by
+  honoring `X-Forwarded-For` only when the direct peer is a trusted proxy,
+  walking the chain right-to-left to the rightmost non-proxy entry, so a client
+  connecting directly cannot spoof its address; the resolved address is stored
+  in the request context by a new middleware and used by the request-logging
+  middleware and the login-attempt logs in place of the raw peer address;
+  documented in `README.md` and `config.example.yml`.
 - 2026-09-21 blocked networks configuration extending SSRF protection: a
-  `blocked_networks` config key taking a list of CIDRs (parsed with
-  `net/netip`, an invalid entry aborts startup naming the key and value),
-  added to the built-in blocklist rather than replacing it; the built-in
-  ranges extended to CGNAT `100.64.0.0/10`, IETF protocol assignments
-  `192.0.0.0/24`, benchmark `198.18.0.0/15`, and NAT64 `64:ff9b::/96`
-  (IPv4-mapped forms covered); enforcement stays in the dial-time
-  re-resolution so the DNS-rebinding window remains closed; documented in
-  `README.md` and `config.example.yml`.
-- 2026-09-21 validate dimensions and fit mode on the encrypted-URL
-  route and the token generator (closes #62): `imgcache.ValidateDimension`
-  alone holds the `MaxDimension` bound and is used by the path parser, by
-  the new `ValidateImageRequest` (which also applies `ValidateFitMode`)
-  and by the generator; both the `/v1/image/` and `/v1/e/` routes call
-  `ValidateImageRequest`, so an over-limit size or an unknown fit mode is a
-  400 rather than an out-of-memory or a 500 from the processor; the URL
-  generator answers 400 naming the field for a `width` or `height` that is
-  not a number or fails the shared check, a `quality` that is not a number
-  from 1 to 100, a `ttl` that is not a number from 0 to the largest number
-  of seconds the expiry calculation can hold, or an unknown `fit`; an empty
-  `quality` is 85 and
-  an empty `ttl` never expires; the form's width and height inputs stop at
-  8192
-- 2026-09-21 http.Server hardening (closes #92): added
-  `HTTPReadHeaderTimeout` (10s, bounds the slowloris header dribble) and
-  `HTTPIdleTimeout` (120s, bounds keep-alive reuse) alongside the
-  existing timeouts and wired them onto the server; added a `LimitBody`
-  middleware capping the two form POST bodies (`POST /`, `POST /generate`)
-  at `MaxFormBytes` (1 MiB) and returning 413, applied ahead of the CSRF
-  middleware so an oversized body is refused as 413 rather than being read
-  as a missing CSRF token (403); left `WriteTimeout` at 60s unchanged
-- 2026-08-07 update golangci-lint to v2.12.2 with the canonical
-  `.golangci.yml` (v2 schema, `default: all` minus six disabled
-  linters, `lll` 88, tests included): bumped the pinned
-  `golangci/golangci-lint:v2.12.2-alpine` image in `Dockerfile` and the
-  release-archive sha256 pins in `script/bootstrap`; fixed the findings
-  the stricter config surfaced (notably `paralleltest`, `wsl_v5`,
+  `blocked_networks` config key taking a list of CIDRs (parsed with `net/netip`,
+  an invalid entry aborts startup naming the key and value), added to the
+  built-in blocklist rather than replacing it; the built-in ranges extended to
+  CGNAT `100.64.0.0/10`, IETF protocol assignments `192.0.0.0/24`, benchmark
+  `198.18.0.0/15`, and NAT64 `64:ff9b::/96` (IPv4-mapped forms covered);
+  enforcement stays in the dial-time re-resolution so the DNS-rebinding window
+  remains closed; documented in `README.md` and `config.example.yml`.
+- 2026-09-21 validate dimensions and fit mode on the encrypted-URL route and the
+  token generator (closes #62): `imgcache.ValidateDimension` alone holds the
+  `MaxDimension` bound and is used by the path parser, by the new
+  `ValidateImageRequest` (which also applies `ValidateFitMode`) and by the
+  generator; both the `/v1/image/` and `/v1/e/` routes call
+  `ValidateImageRequest`, so an over-limit size or an unknown fit mode is a 400
+  rather than an out-of-memory or a 500 from the processor; the URL generator
+  answers 400 naming the field for a `width` or `height` that is not a number or
+  fails the shared check, a `quality` that is not a number from 1 to 100, a
+  `ttl` that is not a number from 0 to the largest number of seconds the expiry
+  calculation can hold, or an unknown `fit`; an empty `quality` is 85 and an
+  empty `ttl` never expires; the form's width and height inputs stop at 8192
+- 2026-09-21 http.Server hardening (closes #92): added `HTTPReadHeaderTimeout`
+  (10s, bounds the slowloris header dribble) and `HTTPIdleTimeout` (120s, bounds
+  keep-alive reuse) alongside the existing timeouts and wired them onto the
+  server; added a `LimitBody` middleware capping the two form POST bodies
+  (`POST /`, `POST /generate`) at `MaxFormBytes` (1 MiB) and returning 413,
+  applied ahead of the CSRF middleware so an oversized body is refused as 413
+  rather than being read as a missing CSRF token (403); left `WriteTimeout` at
+  60s unchanged
+- 2026-08-07 update golangci-lint to v2.12.2 with the canonical `.golangci.yml`
+  (v2 schema, `default: all` minus six disabled linters, `lll` 88, tests
+  included): bumped the pinned `golangci/golangci-lint:v2.12.2-alpine` image in
+  `Dockerfile` and the release-archive sha256 pins in `script/bootstrap`; fixed
+  the findings the stricter config surfaced (notably `paralleltest`, `wsl_v5`,
   `goconst`, `lll`, `noinlineerr`, `err113`, `errcheck`, `testpackage` —
-  white-box test files renamed to `*_internal_test.go`), including #55's
-  code absorbed after it merged, iterating the pinned linter to
-  `0 issues.`; no single finding total is substantiable, since
-  golangci-lint's `uniq-by-line` reveals new findings on a line as
-  others there are fixed — the documented re-measurements were 81 after
-  the #53 merge and 149 after the #55 merge; three behavior changes, so
-  not a pure no-op: `Cache.StoreVariant` now takes a `context.Context`
-  (`noctx`), so a cancelled request skips its best-effort accounting
-  row; `MetadataStorage.Store`'s cleanup defer was dead on `main` and
-  leaked `.tmp-*.json` on failure, now fixed with explicit removals; and
-  the `signing_key` validation error text gained `value too short: `;
-  the eviction loop's uncancellable context is deferred to #102 under a
-  `//nolint:contextcheck`; three `//nolint:tagliatelle` directives keep
-  the snake_case JSON wire/disk formats unchanged; `make check` green
-- 2026-08-07 implement cache size management and eviction (closes
-  #51): new `cache_max_bytes` config key validated by the startup
-  framework (explicit values used exactly with no floor, `0` disables
-  the disk cache entirely, omitted defaults to max(75% of free space
-  on the filesystem containing `<state_dir>/cache/`, 500 MiB), logged
-  at startup); processed variants are now tracked in the database (a
-  new `variant_content` table and an LRU timestamp on `source_content`)
-  so total usage is two SUMs, never a directory scan on the hot path; a
-  background goroutine evicts globally least-recently-used entries
-  (variants and source blobs merged) to the limit, woken by a periodic
-  ticker and by write-pressure notifications from stores; a source
-  blob and ALL of its `source_metadata` references are deleted in one
-  transaction before the file is unlinked, so multi-referenced blobs
-  are never removed while referenced and rows never point at deleted
-  files; a startup and periodic reconciliation pass adopts untracked
-  variant files, drops rows for missing files, removes unreachable
-  source blobs, and sweeps stale temp files
-- 2026-08-07 validate configuration on startup, fail fast on bad
-  config (closes #52): a config value that is set but unparseable or
-  invalid aborts startup naming the key and value (defaults apply only
-  to omitted keys), unknown config keys abort startup, a malformed
-  config file aborts instead of being skipped, and `state_dir` is
-  verified creatable and writable before the listener binds
-- 2026-08-07 manual test pass of the auth and encrypted URL flows
-  against a locally built and running `pixad` (built from `main` at
-  `6573b9d`, port 18099, local throwaway config); all six checks
-  passed, plus all nine tests in `scripts/manual-test.sh` (closes #49):
-    - [x] visit `/` and see the login form: HTTP 200, `Pixa - Login`
-      page with `name="key"` password form
-    - [x] wrong key shows an error: POST `/` with `key=wrong-key`
-      returned HTTP 200 login page containing "Invalid signing key"
-    - [x] correct signing key shows the generator form: POST `/`
-      returned HTTP 303 to `/` with
-      `Set-Cookie: pixa_session=...; HttpOnly; Secure; SameSite=Strict`;
-      GET `/` with that cookie rendered `Pixa - URL Generator` with the
-      `/generate` form and logout link
+  white-box test files renamed to `*_internal_test.go`), including #55's code
+  absorbed after it merged, iterating the pinned linter to `0 issues.`; no
+  single finding total is substantiable, since golangci-lint's `uniq-by-line`
+  reveals new findings on a line as others there are fixed — the documented
+  re-measurements were 81 after the #53 merge and 149 after the #55 merge; three
+  behavior changes, so not a pure no-op: `Cache.StoreVariant` now takes a
+  `context.Context` (`noctx`), so a cancelled request skips its best-effort
+  accounting row; `MetadataStorage.Store`'s cleanup defer was dead on `main` and
+  leaked `.tmp-*.json` on failure, now fixed with explicit removals; and the
+  `signing_key` validation error text gained `value too short: `; the eviction
+  loop's uncancellable context is deferred to #102 under a
+  `//nolint:contextcheck`; three `//nolint:tagliatelle` directives keep the
+  snake_case JSON wire/disk formats unchanged; `make check` green
+- 2026-08-07 implement cache size management and eviction (closes #51): new
+  `cache_max_bytes` config key validated by the startup framework (explicit
+  values used exactly with no floor, `0` disables the disk cache entirely,
+  omitted defaults to max(75% of free space on the filesystem containing
+  `<state_dir>/cache/`, 500 MiB), logged at startup); processed variants are now
+  tracked in the database (a new `variant_content` table and an LRU timestamp on
+  `source_content`) so total usage is two SUMs, never a directory scan on the
+  hot path; a background goroutine evicts globally least-recently-used entries
+  (variants and source blobs merged) to the limit, woken by a periodic ticker
+  and by write-pressure notifications from stores; a source blob and ALL of its
+  `source_metadata` references are deleted in one transaction before the file is
+  unlinked, so multi-referenced blobs are never removed while referenced and
+  rows never point at deleted files; a startup and periodic reconciliation pass
+  adopts untracked variant files, drops rows for missing files, removes
+  unreachable source blobs, and sweeps stale temp files
+- 2026-08-07 validate configuration on startup, fail fast on bad config (closes
+  #52): a config value that is set but unparseable or invalid aborts startup
+  naming the key and value (defaults apply only to omitted keys), unknown config
+  keys abort startup, a malformed config file aborts instead of being skipped,
+  and `state_dir` is verified creatable and writable before the listener binds
+- 2026-08-07 manual test pass of the auth and encrypted URL flows against a
+  locally built and running `pixad` (built from `main` at `6573b9d`, port 18099,
+  local throwaway config); all six checks passed, plus all nine tests in
+  `scripts/manual-test.sh` (closes #49):
+    - [x] visit `/` and see the login form: HTTP 200, `Pixa - Login` page with
+          `name="key"` password form
+    - [x] wrong key shows an error: POST `/` with `key=wrong-key` returned HTTP
+          200 login page containing "Invalid signing key"
+    - [x] correct signing key shows the generator form: POST `/` returned HTTP
+          303 to `/` with
+          `Set-Cookie: pixa_session=...; HttpOnly; Secure; SameSite=Strict`; GET
+          `/` with that cookie rendered `Pixa - URL Generator` with the
+          `/generate` form and logout link
     - [x] a generated encrypted URL serves the image: POST `/generate`
-      (ttl=3600) produced a `/v1/e/<token>/img.jpeg` URL that returned
-      HTTP 200, `Content-Type: image/jpeg`, an 800x600 baseline JPEG of
-      61706 bytes
-    - [x] an expired URL (short TTL) returns 410: a ttl=1 URL fetched
-      after 3 s returned HTTP 410 Gone with
-      `{"error":"URL has expired","status":410,...}`
-    - [x] logout redirects back to login: GET `/logout` returned HTTP
-      303 to `/` with `Set-Cookie: pixa_session=; Max-Age=0`;
-      subsequent GET `/` rendered the login form again
-- 2026-08-07 fix the two remaining gosec findings (G124 in
-  internal/session): session cookies now always carry
-  Secure/HttpOnly/SameSite=Strict on both the set and clear paths;
-  `make check` green (closes #47)
-- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
-  Makefile shims, README Entrypoints section
+          (ttl=3600) produced a `/v1/e/<token>/img.jpeg` URL that returned HTTP
+          200, `Content-Type: image/jpeg`, an 800x600 baseline JPEG of 61706
+          bytes
+    - [x] an expired URL (short TTL) returns 410: a ttl=1 URL fetched after 3 s
+          returned HTTP 410 Gone with
+          `{"error":"URL has expired","status":410,...}`
+    - [x] logout redirects back to login: GET `/logout` returned HTTP 303 to `/`
+          with `Set-Cookie: pixa_session=; Max-Age=0`; subsequent GET `/`
+          rendered the login form again
+- 2026-08-07 fix the two remaining gosec findings (G124 in internal/session):
+  session cookies now always carry Secure/HttpOnly/SameSite=Strict on both the
+  set and clear paths; `make check` green (closes #47)
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
+  shims, README Entrypoints section
 - 2026-04-07 extract magic byte detection into internal/magic (#42)
 - 2026-03-25 extract allowlist package from internal/imgcache (#41)
 - 2026-03-25 move schema_migrations table creation into 000.sql (#36)
-- 2026-03-20 enforce and document exact-match-only signature
-  verification (#40)
-- 2026-03-20 bound imageprocessor.Process input read to prevent
-  unbounded memory use (#37); consolidate appname into an
-  internal/globals constant (#34)
+- 2026-03-20 enforce and document exact-match-only signature verification (#40)
+- 2026-03-20 bound imageprocessor.Process input read to prevent unbounded memory
+  use (#37); consolidate appname into an internal/globals constant (#34)
 - 2026-03-18 parse version prefix from migration filenames (#33)
 - 2026-03-15 QA audit fixes for 1.0/MVP readiness (#25)
-- 2026-03-02 split Dockerfile with pre-built golangci-lint stage for
-  faster CI (#23)
+- 2026-03-02 split Dockerfile with pre-built golangci-lint stage for faster CI
+  (#23)
 - 2026-02-25 repo policy compliance: CI workflow, hash-pinned images,
-  golangci-lint and gosec fixes of that date (#14); arm64 Docker build
-  fix (#16)
-- 2026-01-08 WebP and AVIF encoding support via govips (both former P0
-  image processing items, now done)
+  golangci-lint and gosec fixes of that date (#14); arm64 Docker build fix (#16)
+- 2026-01-08 WebP and AVIF encoding support via govips (both former P0 image
+  processing items, now done)
 
 # Future Steps
 
 - P2: security
-    - per-IP rate limiting on the image routes
     - per-origin rate limiting
 - P2: HTTP response handling
     - Last-Modified headers
-    - Vary header for content negotiation
-    - X-Request-ID propagation
-- P2: auto format selection (format=auto based on Accept header)
 - P2: configuration
     - YAML config file support
 - P2: operational
     - optional Sentry error reporting
     - comprehensive request logging
     - Prometheus performance metrics
-    - integration tests for the image proxy flow
-    - load tests to verify the 1k to 5k req/s target
-- P2: documentation
-    - configuration options
-    - API endpoints
-    - deployment guide
-    - example nginx or caddy reverse proxy config
+    - measure the 1k to 5k req/s target with `script/loadtest` on a machine not
+      shared with other work

cmd/loadtest-origin/main.go

@@ -0,0 +1,9 @@
+// Command loadtest-origin is the upstream host script/loadtest points pixad
+// at; internal/loadtestorigin says what it does.
+package main
+
+import "sneak.berlin/go/pixa/internal/loadtestorigin"
+
+func main() {
+	loadtestorigin.Run()
+}

cmd/pixad/main.go

@@ -1,64 +1,10 @@
 // Package main is the entry point for the pixad image proxy server.
 package main
 
-import (
-	"fmt"
-	"os"
-
-	"github.com/spf13/cobra"
-	"go.uber.org/fx"
-	"sneak.berlin/go/pixa/internal/config"
-	"sneak.berlin/go/pixa/internal/database"
-	"sneak.berlin/go/pixa/internal/globals"
-	"sneak.berlin/go/pixa/internal/handlers"
-	"sneak.berlin/go/pixa/internal/healthcheck"
-	"sneak.berlin/go/pixa/internal/logger"
-	"sneak.berlin/go/pixa/internal/middleware"
-	"sneak.berlin/go/pixa/internal/server"
-)
+import "sneak.berlin/go/pixa/internal/app"
 
 var Version string //nolint:gochecknoglobals // set by ldflags
 
-var configPath string //nolint:gochecknoglobals // cobra flag
-
 func main() {
-	rootCmd := &cobra.Command{
-		Use:   "pixad",
-		Short: "Pixa image caching proxy server",
-		Run:   run,
-	}
-
-	rootCmd.Flags().StringVarP(&configPath, "config", "c", "", "path to config file")
-
-	err := rootCmd.Execute()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-}
-
-func run(_ *cobra.Command, _ []string) {
-	globals.Version = Version
-
-	// Set config path in environment if specified via flag
-	if configPath != "" {
-		_ = os.Setenv("PIXA_CONFIG_PATH", configPath)
-	}
-
-	fx.New(
-		fx.Provide(
-			config.New,
-			database.New,
-			globals.New,
-			handlers.New,
-			logger.New,
-			server.New,
-			middleware.New,
-			healthcheck.New,
-		),
-		fx.Invoke(
-			func(log *logger.Logger) { log.Identify() },
-			func(*server.Server) {},
-		),
-	).Run()
+	app.Run(Version)
 }

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

configs/config.example.yml

@@ -12,28 +12,42 @@
 # Durations are Go duration strings such as 30s or 2m and must be
 # positive; a bare number has no unit and aborts startup. Sizes are a
 # whole number of bytes.
+#
+# A key left out takes the default its comment gives.
 
-# Server settings
+# Port to listen on (default: 8080)
 port: 8080
+
+# Debug logging and plain-HTTP local development (default: false)
 debug: false
 
 # While true, the image routes (/v1/image/ and /v1/e/) answer every request
-# with 503 and a Retry-After header. The health check keeps answering 200 and
-# reports maintenance_mode as true. It stays 200 because the image's Docker
-# HEALTHCHECK requests it: a 503 there would make the container unhealthy, and
-# upaas marks a deploy failed when its container is unhealthy.
+# for an image with 503 and a Retry-After header. The health check keeps
+# answering 200 and reports maintenance_mode as true. It stays 200 because
+# the image's Docker HEALTHCHECK requests it: a 503 there would make the
+# container unhealthy, and upaas marks a deploy failed when its container is
+# unhealthy. (default: false)
 maintenance_mode: false
 
 # Data directory for SQLite database and cache files
+# (default: /var/lib/pixa)
 state_dir: ./data
 
+# SQLite database URL (default:
+# file:<state_dir>/state.sqlite3?_pragma=journal_mode(WAL)). pixa adds
+# _pragma=busy_timeout(5000) to it. An empty value aborts startup; leave the
+# key out to use the default.
+# db_url: "file:./data/state.sqlite3?_pragma=journal_mode(WAL)"
+
 # Image proxy settings
 # HMAC signing key for URL signatures (required, at least 32 characters)
 # Generate with: openssl rand -base64 32
 signing_key: "CHANGE_ME_generate_with_openssl_rand_base64_32"
 
-# Hosts that don't require signatures
+# Hosts that don't require signatures (default: none)
 # Use "." prefix for wildcard subdomain matching (e.g., ".example.com" matches "cdn.example.com")
+# An entry that is neither a host name nor an IP address (IPv6 without
+# brackets), such as one with a port or a "*." wildcard, aborts startup.
 allowlist_hosts:
   - s3.sneak.cloud
   - static.sneak.cloud
@@ -41,11 +55,21 @@ allowlist_hosts:
   - github.com
   - user-images.githubusercontent.com
 
+# Hosts whose pages may not show pixa's images, written as for
+# allowlist_hosts. A request to /v1/image/ or /v1/e/ whose Referer header
+# names one of them is answered 403 before anything is fetched, even when
+# the image is cached. A request with no Referer, or one that does not
+# parse, is served, so a site whose pages send no Referer is not stopped.
+# The login and generator pages are not covered. (default: none)
+# referer_blocklist:
+#   - leech.example
+#   - .hotlinker.example
+
 # Additional CIDR ranges to refuse when fetching upstream, extending the
 # SSRF protection. These are added to the always-enforced built-in ranges
 # (loopback, RFC 1918 private, link-local, CGNAT, benchmark, NAT64, and
 # similar), never replacing them. Each entry must be a valid CIDR in IPv4
-# or IPv6 form; an invalid entry aborts startup.
+# or IPv6 form; an invalid entry aborts startup. (default: none)
 # blocked_networks:
 #   - 100.64.0.0/10
 #   - 2001:db8::/32
@@ -72,6 +96,7 @@ allowlist_hosts:
 #   - 2001:db8::/32
 
 # Allow HTTP upstream (only for testing, always use HTTPS in production)
+# (default: false)
 allow_http: false
 
 # Maximum concurrent connections per upstream host (default: 20)
@@ -116,15 +141,22 @@ access_control_allow_origin: "*"
 
 # Maximum disk cache size in bytes. Explicit values are used exactly as
 # given; 0 disables the disk cache entirely (every request fetches and
-# processes uncached). When omitted, the default is 75% of the free
-# space on the filesystem containing <state_dir>/cache/ at startup,
+# processes uncached). When omitted, the default is 75% of the sum of
+# the free space on the filesystem containing <state_dir>/cache/ and
+# the bytes of images the cache already holds, worked out at startup,
 # with a minimum of 500 MiB.
 # cache_max_bytes: 10737418240
 
-# Sentry error reporting (optional)
+# Sentry DSN for error reporting (default: empty, which turns it off)
 sentry_dsn: ""
 
-# Metrics endpoint authentication (optional)
+# Username and password for /metrics, set together (default: unset). Metrics
+# are measured and /metrics is served only when both are set.
 # metrics:
 #   username: "admin"
 #   password: "secret"
+
+# Environment variables set while this file loads, as described at the top
+# (default: none)
+# env:
+#   PIXA_DEBUG: "true"

internal/app/app.go

@@ -0,0 +1,70 @@
+// Package app reads the pixad command line and runs the server.
+package app
+
+import (
+	"fmt"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/spf13/cobra"
+	"go.uber.org/fx"
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/handlers"
+	"sneak.berlin/go/pixa/internal/healthcheck"
+	"sneak.berlin/go/pixa/internal/logger"
+	"sneak.berlin/go/pixa/internal/middleware"
+	"sneak.berlin/go/pixa/internal/server"
+)
+
+var configPath string //nolint:gochecknoglobals // cobra flag
+
+// Run reads the command line and runs the server until it stops, with
+// version as the version pixad logs and reports. It exits the process
+// with status 1 when the command line is not valid.
+func Run(version string) {
+	globals.Version = version
+
+	rootCmd := &cobra.Command{
+		Use:   "pixad",
+		Short: "Pixa image caching proxy server",
+		Run:   run,
+	}
+
+	rootCmd.Flags().StringVarP(&configPath, "config", "c", "", "path to config file")
+
+	err := rootCmd.Execute()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(_ *cobra.Command, _ []string) {
+	// Set config path in environment if specified via flag
+	if configPath != "" {
+		_ = os.Setenv("PIXA_CONFIG_PATH", configPath)
+	}
+
+	// A write to a closed stdout or stderr must not end the process.
+	signal.Ignore(syscall.SIGPIPE)
+
+	fx.New(
+		fx.Provide(
+			config.New,
+			database.New,
+			globals.New,
+			handlers.New,
+			logger.New,
+			server.New,
+			middleware.New,
+			healthcheck.New,
+		),
+		fx.Invoke(
+			func(log *logger.Logger) { log.Identify() },
+			func(*server.Server) {},
+		),
+	).Run()
+}

internal/config/cache_max_bytes_internal_test.go

@@ -1,26 +1,10 @@
 package config
 
 import (
-	"errors"
-	"log/slog"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 )
 
-// Static errors returned by the stub free-space probes below.
-var (
-	errTestStatfsFailed     = errors.New("statfs failed")
-	errTestProbeNotExpected = errors.New("probe must not be called")
-)
-
-// discardLogger returns a logger that swallows all output, for tests
-// that exercise code paths which log.
-func discardLogger() *slog.Logger {
-	return slog.New(slog.DiscardHandler)
-}
-
 // TestCacheMaxBytesExplicitValueUsedWithoutFloor verifies that an
 // explicitly configured cache_max_bytes value is used exactly as
 // given: the 500 MiB floor applies only to the computed default, never
@@ -151,155 +135,30 @@ func TestCacheMaxBytesInvalidValuesAbortStartup(t *testing.T) {
 	}
 }
 
-// TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace verifies the
-// computed default is 75% of the probed free space when that exceeds
-// the floor.
-func TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace(t *testing.T) {
+// TestCacheMaxBytesExplicitIsRecorded verifies that an omitted
+// cache_max_bytes is recorded as not explicit, so the cache works out
+// the default when it opens, and that an explicit zero is recorded as
+// explicit, so it disables the disk cache instead.
+func TestCacheMaxBytesExplicitIsRecorded(t *testing.T) {
 	t.Parallel()
 
-	// 4 GiB free -> 3 GiB default.
-	probe := func(string) (uint64, error) { return 4294967296, nil }
+	signingKeyLine := "signing_key: " + validTestSigningKey + "\n"
 
-	got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
-	if err != nil {
-		t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
-	}
-
-	if got != 3221225472 {
-		t.Errorf("ComputeDefaultCacheMaxBytes = %d, want 3221225472 (75%% of 4 GiB)",
-			got)
-	}
-}
-
-// TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault
-// verifies that when 75% of free space is below 500 MiB, the computed
-// default is floored at DefaultCacheMaxBytesFloor.
-func TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault(t *testing.T) {
-	t.Parallel()
-
-	cases := []struct {
-		name      string
-		freeBytes uint64
-	}{
-		{name: "100 MiB free", freeBytes: 104857600},
-		{name: "zero free", freeBytes: 0},
-		{name: "just below floor threshold", freeBytes: 699050665},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			t.Parallel()
-
-			probe := func(string) (uint64, error) { return tc.freeBytes, nil }
-
-			got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
-			if err != nil {
-				t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
-			}
-
-			if got != DefaultCacheMaxBytesFloor {
-				t.Errorf("ComputeDefaultCacheMaxBytes = %d, want floor %d",
-					got, DefaultCacheMaxBytesFloor)
-			}
-		})
-	}
-}
-
-// TestComputeDefaultCacheMaxBytesPropagatesProbeError verifies that a
-// failing free-space probe produces an error naming the config key,
-// instead of a silently wrong default.
-func TestComputeDefaultCacheMaxBytesPropagatesProbeError(t *testing.T) {
-	t.Parallel()
-
-	probe := func(string) (uint64, error) { return 0, errTestStatfsFailed }
-
-	_, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
-	if err == nil {
-		t.Fatal("probe failure must produce an error, got nil")
-	}
-
-	t.Logf("got expected error: %v", err)
-
-	if !strings.Contains(err.Error(), keyCacheMaxBytes) {
-		t.Errorf("error %q does not name the config key cache_max_bytes", err.Error())
-	}
-}
-
-// TestResolveCacheMaxBytesComputesDefaultWhenOmitted verifies that an
-// omitted cache_max_bytes key resolves to the computed default, that
-// the probe is pointed at <state_dir>/cache/ (which must be created
-// first so statfs measures the right filesystem), and that the result
-// lands on the Config.
-func TestResolveCacheMaxBytesComputesDefaultWhenOmitted(t *testing.T) {
-	t.Parallel()
-
-	c, err := configFromYAML(t, "signing_key: "+validTestSigningKey+"\n")
+	omitted, err := configFromYAML(t, signingKeyLine)
 	if err != nil {
 		t.Fatalf("minimal config should be valid, got error: %v", err)
 	}
 
-	c.StateDir = t.TempDir()
-	wantCacheDir := filepath.Join(c.StateDir, "cache")
-
-	var probedPath string
-
-	// 4 GiB free -> 3 GiB default.
-	probe := func(path string) (uint64, error) {
-		probedPath = path
-
-		return 4294967296, nil
+	if omitted.CacheMaxBytesExplicit {
+		t.Error("omitted cache_max_bytes recorded as explicit")
 	}
 
-	err = c.resolveCacheMaxBytes(discardLogger(), probe)
+	zero, err := configFromYAML(t, signingKeyLine+"cache_max_bytes: 0\n")
 	if err != nil {
-		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
+		t.Fatalf("cache_max_bytes: 0 must be accepted, got error: %v", err)
 	}
 
-	if c.CacheMaxBytes != 3221225472 {
-		t.Errorf("CacheMaxBytes = %d, want computed default 3221225472",
-			c.CacheMaxBytes)
-	}
-
-	if probedPath != wantCacheDir {
-		t.Errorf("free space probed at %q, want cache directory %q",
-			probedPath, wantCacheDir)
-	}
-
-	info, err := os.Stat(wantCacheDir)
-	if err != nil || !info.IsDir() {
-		t.Errorf("cache directory %q was not created before probing: info=%v err=%v",
-			wantCacheDir, info, err)
-	}
-}
-
-// TestResolveCacheMaxBytesDoesNotOverrideExplicitValue verifies that
-// an explicitly configured value survives resolution untouched and
-// that the free-space probe is never consulted for it.
-func TestResolveCacheMaxBytesDoesNotOverrideExplicitValue(t *testing.T) {
-	t.Parallel()
-
-	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 1024\n"
-
-	c, err := configFromYAML(t, yamlContent)
-	if err != nil {
-		t.Fatalf("explicit cache_max_bytes must be accepted, got error: %v", err)
-	}
-
-	c.StateDir = t.TempDir()
-
-	probe := func(string) (uint64, error) {
-		t.Error("free-space probe must not be consulted for explicit values")
-
-		return 0, errTestProbeNotExpected
-	}
-
-	err = c.resolveCacheMaxBytes(discardLogger(), probe)
-	if err != nil {
-		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
-	}
-
-	if c.CacheMaxBytes != 1024 {
-		t.Errorf("CacheMaxBytes = %d, want explicit 1024 (no floor, no recompute)",
-			c.CacheMaxBytes)
+	if !zero.CacheMaxBytesExplicit {
+		t.Error("cache_max_bytes: 0 not recorded as explicit")
 	}
 }

internal/config/cachesize.go

@@ -1,116 +0,0 @@
-package config
-
-import (
-	"fmt"
-	"log/slog"
-	"math"
-	"os"
-	"path/filepath"
-	"syscall"
-)
-
-// DefaultCacheMaxBytesFloor is the minimum computed default for the
-// cache_max_bytes setting: 500 MiB. The floor applies only to the
-// computed default (when the key is omitted from the configuration),
-// never to explicitly configured values.
-const DefaultCacheMaxBytesFloor int64 = 524288000
-
-// cacheDirPerms is the permission mode for the cache directory created
-// before probing free space, matching the state directory permissions.
-const cacheDirPerms = 0o750
-
-// freeSpaceFractionNumerator and freeSpaceFractionDenominator express
-// the 75% share of free space used for the computed default limit as
-// integer arithmetic (dividing before multiplying avoids overflow).
-const (
-	freeSpaceFractionNumerator   uint64 = 3
-	freeSpaceFractionDenominator uint64 = 4
-)
-
-// FreeSpaceProbeFunc reports the number of free bytes available on the
-// filesystem containing path. It is a function type so tests can
-// inject a fake probe instead of depending on the host disk.
-type FreeSpaceProbeFunc func(path string) (uint64, error)
-
-// defaultFreeSpaceProbe reports free filesystem bytes via statfs on
-// the given path, as available to unprivileged processes.
-func defaultFreeSpaceProbe(path string) (uint64, error) {
-	var stat syscall.Statfs_t
-
-	err := syscall.Statfs(path, &stat)
-	if err != nil {
-		return 0, err
-	}
-
-	if stat.Bsize < 0 {
-		return 0, fmt.Errorf("%w %d for %q", errNegativeBlockSize, stat.Bsize, path)
-	}
-
-	blockSize := uint64(stat.Bsize)
-
-	return stat.Bavail * blockSize, nil
-}
-
-// ComputeDefaultCacheMaxBytes returns the default cache size limit for
-// the filesystem containing cacheDir: 75% of the free bytes reported
-// by probe, with a floor of DefaultCacheMaxBytesFloor.
-func ComputeDefaultCacheMaxBytes(
-	cacheDir string, probe FreeSpaceProbeFunc,
-) (int64, error) {
-	freeBytes, err := probe(cacheDir)
-	if err != nil {
-		return 0, fmt.Errorf("config key %q: cannot determine free space for %q: %w",
-			"cache_max_bytes", cacheDir, err)
-	}
-
-	computed := freeBytes / freeSpaceFractionDenominator * freeSpaceFractionNumerator
-	computed = min(computed, math.MaxInt64)
-
-	// gosec cannot see that min() above bounds computed, so it reads
-	// this conversion as potentially overflowing. It cannot: computed is
-	// at most math.MaxInt64 on every path here.
-	//nolint:gosec // G115: clamped to MaxInt64 by min above
-	limit := int64(computed)
-	limit = max(limit, DefaultCacheMaxBytesFloor)
-
-	return limit, nil
-}
-
-// resolveCacheMaxBytes finalizes CacheMaxBytes after state_dir
-// validation: an explicitly configured value is kept as-is (no floor
-// applies), while an omitted key receives the computed default based
-// on free space in <state_dir>/cache/. The cache directory is created
-// first so statfs measures the filesystem that will actually hold the
-// cache. The effective limit is logged either way.
-func (c *Config) resolveCacheMaxBytes(
-	log *slog.Logger, probe FreeSpaceProbeFunc,
-) error {
-	if !c.cacheMaxBytesExplicit {
-		cacheDir := filepath.Join(c.StateDir, "cache")
-
-		err := os.MkdirAll(cacheDir, cacheDirPerms)
-		if err != nil {
-			return fmt.Errorf("config key %q: cannot create cache directory %q: %w",
-				keyCacheMaxBytes, cacheDir, err)
-		}
-
-		limit, err := ComputeDefaultCacheMaxBytes(cacheDir, probe)
-		if err != nil {
-			return err
-		}
-
-		c.CacheMaxBytes = limit
-
-		log.Info("computed default cache size limit from free space",
-			"cache_max_bytes", limit,
-			"cache_dir", cacheDir,
-		)
-	}
-
-	log.Info("effective cache size limit",
-		"cache_max_bytes", c.CacheMaxBytes,
-		"cache_disabled", c.CacheMaxBytes == 0,
-	)
-
-	return nil
-}

internal/config/config.go

@@ -4,16 +4,19 @@ package config
 import (
 	"errors"
 	"fmt"
+	"io/fs"
 	"log/slog"
 	"math"
 	"net/netip"
 	"net/url"
 	"os"
 	"path/filepath"
+	"regexp"
 	"runtime"
 	"sort"
 	"strconv"
 	"strings"
+	"syscall"
 	"time"
 
 	"git.eeqj.de/sneak/smartconfig"
@@ -46,6 +49,7 @@ const (
 	keyMetricsPassword            = "metrics.password"
 	keySigningKey                 = "signing_key"
 	keyAllowlistHosts             = "allowlist_hosts"
+	keyRefererBlocklist           = "referer_blocklist"
 	keyAllowHTTP                  = "allow_http"
 	keyUpstreamConnectionsPerHost = "upstream_connections_per_host"
 	keyUpstreamConnections        = "upstream_connections"
@@ -60,7 +64,7 @@ const (
 )
 
 // placeholderSigningKey is the dummy signing_key shipped in
-// config.example.yml. It is 45 characters, so it passes the length
+// configs/config.example.yml. It is 45 characters, so it passes the length
 // check, but it is public in this repository and must be rejected at
 // startup so no deployment ever signs URLs with it.
 const placeholderSigningKey = "CHANGE_ME_generate_with_openssl_rand_base64_32"
@@ -86,23 +90,20 @@ var (
 	errMustBeAtLeastOne  = errors.New("must be at least 1")
 	errValueTooShort     = errors.New("value too short")
 	errPlaceholderKey    = errors.New(
-		"is the placeholder from config.example.yml; " +
+		"is the placeholder from configs/config.example.yml; " +
 			"generate a real key with: openssl rand -base64 32")
 	errMustBeSetTogether = errors.New("must be set together")
 	errMustNotBeNegative = errors.New("must not be negative")
 	errOverflowsInt64    = errors.New("overflows a 64-bit integer")
-	errNegativeBlockSize = errors.New(
-		"statfs reported negative block size")
-	errValueNull = errors.New(
+	errValueNull         = errors.New(
 		"value is null; omit the key entirely to use the default")
 	errValuesNull = errors.New(
 		"value is null; omit a key entirely to use its default")
-	errNotBareHostname = errors.New(
-		"must be a bare hostname without scheme, path, or whitespace")
-	errNoHostnameLabels = errors.New("contains no hostname labels")
-	errNotADuration     = errors.New("not a duration such as 30s or 2m")
-	errMustBePositive   = errors.New("must be positive")
-	errNotAnOrigin      = errors.New(
+	errNotAHost = errors.New("must be a host name such as " +
+		"cdn.example.com or .example.com, or an IP address")
+	errNotADuration   = errors.New("not a duration such as 30s or 2m")
+	errMustBePositive = errors.New("must be positive")
+	errNotAnOrigin    = errors.New(
 		`not "*" or an origin such as https://example.com`)
 )
 
@@ -130,6 +131,10 @@ type Config struct {
 	AllowHTTP                  bool     // Allow non-TLS upstream (testing only)
 	UpstreamConnectionsPerHost int      // Max concurrent connections per upstream host
 
+	// RefererBlocklist holds host patterns, matched as AllowlistHosts is: the
+	// image routes refuse a request whose Referer names a matching host.
+	RefererBlocklist []string
+
 	// UpstreamConnections is the most concurrent connections to all
 	// upstream hosts together, on top of the per-host limit.
 	// MaxConcurrentProcessing is the most images processed at once.
@@ -169,18 +174,19 @@ type Config struct {
 	// address, and an explicit list replaces the default.
 	TrustedProxies []netip.Prefix
 
-	// CacheMaxBytes is the disk cache size limit in bytes. Zero
-	// disables the disk cache entirely. When cache_max_bytes is
-	// omitted from the configuration, this holds the computed default
-	// (75% of free space on the filesystem containing
-	// <state_dir>/cache/, floored at DefaultCacheMaxBytesFloor).
+	// CacheMaxBytes is the disk cache size limit in bytes. Only an
+	// explicit zero (CacheMaxBytesExplicit true) disables the disk
+	// cache. Zero with CacheMaxBytesExplicit false means
+	// cache_max_bytes was omitted, and the cache works out the default
+	// limit when it opens.
 	CacheMaxBytes int64
 
-	// cacheMaxBytesExplicit records whether cache_max_bytes was
+	// CacheMaxBytesExplicit records whether cache_max_bytes was
 	// explicitly set, in the environment or the configuration file.
-	// Explicit values are used exactly as given; only an omitted key
-	// gets the computed default (and its floor) in resolveCacheMaxBytes.
-	cacheMaxBytesExplicit bool
+	// Explicit values are used exactly as given; for an omitted key the
+	// cache works out the default limit when it opens (see
+	// imgcache.CacheConfig.UseDefaultMaxBytes).
+	CacheMaxBytesExplicit bool
 }
 
 // New creates a new Config instance from the environment and the
@@ -217,9 +223,13 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
 		return nil, err
 	}
 
-	err = c.resolveCacheMaxBytes(log, defaultFreeSpaceProbe)
-	if err != nil {
-		return nil, err
+	// An omitted cache_max_bytes is worked out and logged when the
+	// cache opens.
+	if c.CacheMaxBytesExplicit {
+		log.Info("effective cache size limit",
+			"cache_max_bytes", c.CacheMaxBytes,
+			"cache_disabled", c.CacheMaxBytes == 0,
+		)
 	}
 
 	if c.Debug {
@@ -265,7 +275,6 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 	}
 
 	loader := &strictLoader{sc: sc}
-
 	c := &Config{
 		Debug:           loader.boolVal(keyDebug, false),
 		MaintenanceMode: loader.boolVal(keyMaintenanceMode, false),
@@ -293,16 +302,17 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 			keyAccessControlAllowOrigin, DefaultAccessControlAllowOrigin),
 		DownstreamTimeout: loader.durationVal(
 			keyDownstreamTimeout, DefaultDownstreamTimeout),
-		CacheMaxBytes:   loader.int64Val(keyCacheMaxBytes, 0),
-		BlockedNetworks: blockedNetworks,
-		TrustedProxies:  trustedProxies,
+		CacheMaxBytes:    loader.int64Val(keyCacheMaxBytes, 0),
+		BlockedNetworks:  blockedNetworks,
+		TrustedProxies:   trustedProxies,
+		RefererBlocklist: loader.hostListVal(keyRefererBlocklist),
 	}
 
-	// The computed default for cache_max_bytes needs a validated
-	// state_dir, so it is resolved later (resolveCacheMaxBytes); here
-	// we only record whether the operator set the key explicitly.
+	// The default for an omitted cache_max_bytes is worked out when
+	// the cache opens; here we only record whether the operator set
+	// the key explicitly.
 	if _, present := lookupValue(sc, keyCacheMaxBytes); present {
-		c.cacheMaxBytesExplicit = true
+		c.CacheMaxBytesExplicit = true
 	}
 
 	// Build DBURL from StateDir if not explicitly set. The derived URL
@@ -315,7 +325,8 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 				settingName(keyDBURL), errValueEmpty)
 		}
 
-		c.DBURL = fmt.Sprintf("file:%s/state.sqlite3?_journal_mode=WAL", c.StateDir)
+		// The driver sets the journal mode only through a _pragma parameter.
+		c.DBURL = fmt.Sprintf("file:%s/state.sqlite3?_pragma=journal_mode(WAL)", c.StateDir)
 	}
 
 	if loader.err != nil {
@@ -414,7 +425,8 @@ func isKnownConfigKey(key string) bool {
 		keyUpstreamConnectionsPerHost, keyUpstreamConnections,
 		keyMaxConcurrentProcessing, keyCacheMaxBytes, keyBlockedNetworks,
 		keyTrustedProxies, keyAccessControlAllowOrigin, keyUpstreamFetchTimeout,
-		keyUpstreamMaxResponseSize, keyDownstreamTimeout, "env":
+		keyUpstreamMaxResponseSize, keyDownstreamTimeout, keyRefererBlocklist,
+		"env":
 		return true
 	}
 
@@ -437,6 +449,7 @@ func envVarNames() map[string]string {
 		keyMetricsPassword:            "PIXA_METRICS_PASSWORD",
 		keySigningKey:                 "PIXA_SIGNING_KEY",
 		keyAllowlistHosts:             "PIXA_ALLOWLIST_HOSTS",
+		keyRefererBlocklist:           "PIXA_REFERER_BLOCKLIST",
 		keyAllowHTTP:                  "PIXA_ALLOW_HTTP",
 		keyUpstreamConnectionsPerHost: "PIXA_UPSTREAM_CONNECTIONS_PER_HOST",
 		keyUpstreamConnections:        "PIXA_UPSTREAM_CONNECTIONS",
@@ -548,8 +561,8 @@ func (c *Config) ensureStateDirWritable() error {
 }
 
 // validateSigningKey checks that the signing key is present, long
-// enough, and not the public placeholder from config.example.yml. The
-// key value itself is never echoed in error messages.
+// enough, and not the public placeholder from configs/config.example.yml.
+// The key value itself is never echoed in error messages.
 func (c *Config) validateSigningKey() error {
 	if c.SigningKey == "" {
 		return fmt.Errorf("%s: %w", settingName(keySigningKey), errValueRequired)
@@ -606,7 +619,7 @@ func (c *Config) validate() error {
 	}
 
 	for _, host := range c.AllowlistHosts {
-		err := validateAllowlistHost(host)
+		err := validateHostPattern(keyAllowlistHosts, host)
 		if err != nil {
 			return err
 		}
@@ -729,25 +742,24 @@ func (c *Config) validateConcurrencyLimits() error {
 	return nil
 }
 
-// validateAllowlistHost checks that an allowlist_hosts entry is a bare
-// hostname, optionally with a leading dot for suffix matching. URLs,
-// paths, and whitespace indicate a misconfigured entry. An entry with
-// no hostname labels (such as ".") is rejected: the allowlist matcher
-// treats a leading dot as a suffix pattern, so a bare "." would match
-// any upstream host written in FQDN trailing-dot form and effectively
-// disable URL signing.
-func validateAllowlistHost(host string) error {
-	if strings.Contains(host, "://") || strings.ContainsAny(host, "/ \t") {
-		return fmt.Errorf("%s: entry %q %w",
-			settingName(keyAllowlistHosts), host, errNotBareHostname)
+// hostNamePattern matches a host name: letters, digits, hyphens, underscores
+// and dots, optionally after one leading dot.
+var hostNamePattern = regexp.MustCompile(`^\.?[A-Za-z0-9_-][A-Za-z0-9_.-]*$`)
+
+// validateHostPattern checks that an entry of the named key, allowlist_hosts
+// or referer_blocklist, is an IP address or a host name, the host name
+// optionally with one leading dot for suffix matching. Anything else, such as
+// a URL, a port or a "*." wildcard, can never match a host name that resolves,
+// so it is refused.
+// So is "." alone: the allowlist matcher would match it against any host
+// written with a trailing dot, which in allowlist_hosts disables URL signing.
+func validateHostPattern(key, host string) error {
+	_, err := netip.ParseAddr(host)
+	if err == nil || hostNamePattern.MatchString(host) {
+		return nil
 	}
 
-	if strings.Trim(host, ".") == "" {
-		return fmt.Errorf("%s: entry %q %w",
-			settingName(keyAllowlistHosts), host, errNoHostnameLabels)
-	}
-
-	return nil
+	return fmt.Errorf("%s: entry %q %w", settingName(key), host, errNotAHost)
 }
 
 // loadConfigFile loads configuration from the PIXA_CONFIG_PATH env var
@@ -778,19 +790,27 @@ 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, including
+		// one whose path runs through a file, such as under a HOME of
+		// /dev/null. One that cannot be read or does not parse is a
+		// fatal startup error.
 		_, statErr := os.Stat(cleanPath)
-		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 errors.Is(statErr, fs.ErrNotExist) || errors.Is(statErr, syscall.ENOTDIR) {
+			continue
 		}
+
+		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)
@@ -869,6 +889,19 @@ func (l *strictLoader) boolVal(key string, defaultVal bool) bool {
 	return val
 }
 
+func (l *strictLoader) hostListVal(key string) []string {
+	if l.err != nil {
+		return nil
+	}
+
+	val, err := parseHostList(l.sc, key)
+	if err != nil {
+		l.err = err
+	}
+
+	return val
+}
+
 // getString returns the string value for key, or defaultVal if the key
 // is omitted. A present value that is not a string, or is explicitly
 // null, is an error.
@@ -1166,7 +1199,7 @@ func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
 		return nil, errNullConfigValue(key)
 	}
 
-	entries, err := cidrListEntries(raw, key)
+	entries, err := listEntries(raw, key)
 	if err != nil {
 		return nil, err
 	}
@@ -1186,11 +1219,41 @@ func parseCIDRList(sc *smartconfig.Config, key string) ([]netip.Prefix, error) {
 	return prefixes, nil
 }
 
-// cidrListEntries extracts the raw entries of the named CIDR-list key as
-// trimmed, non-empty strings, from either a YAML list of strings or a
-// comma-separated string; an empty string is an empty list, as for
-// allowlist_hosts. Any other shape is a configuration error.
-func cidrListEntries(raw any, key string) ([]string, error) {
+// parseHostList parses the value of the named config key into host patterns,
+// or returns nil if the key is omitted. It accepts a YAML list of strings or a
+// comma-separated string. An explicitly null value, a wrong type, an empty
+// entry, a non-string entry, or an entry validateHostPattern rejects aborts
+// startup naming the key and the offending value.
+func parseHostList(sc *smartconfig.Config, key string) ([]string, error) {
+	raw, ok := lookupValue(sc, key)
+	if !ok {
+		return nil, nil
+	}
+
+	if raw == nil {
+		return nil, errNullConfigValue(key)
+	}
+
+	entries, err := listEntries(raw, key)
+	if err != nil {
+		return nil, err
+	}
+
+	for _, entry := range entries {
+		err := validateHostPattern(key, entry)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return entries, nil
+}
+
+// listEntries extracts the raw entries of the named list key as trimmed,
+// non-empty strings, from either a YAML list of strings or a comma-separated
+// string; an empty string is an empty list, as for allowlist_hosts. Any other
+// shape is a configuration error.
+func listEntries(raw any, key string) ([]string, error) {
 	switch val := raw.(type) {
 	case []any:
 		entries := make([]string, 0, len(val))

internal/config/config_validation_internal_test.go

@@ -1,14 +1,18 @@
 package config
 
 import (
+	"database/sql"
 	"log/slog"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"testing"
 	"time"
 
 	"git.eeqj.de/sneak/smartconfig"
+
+	_ "modernc.org/sqlite" // SQLite driver registration
 )
 
 // validTestSigningKey is a 32-character signing key that satisfies the
@@ -94,12 +98,43 @@ func TestOmittedValuesUseDefaults(t *testing.T) {
 		t.Errorf("AllowlistHosts = %v, want empty", c.AllowlistHosts)
 	}
 
-	wantDBURL := "file:" + DefaultStateDir + "/state.sqlite3?_journal_mode=WAL"
+	wantDBURL := "file:" + DefaultStateDir +
+		"/state.sqlite3?_pragma=journal_mode(WAL)"
 	if c.DBURL != wantDBURL {
 		t.Errorf("DBURL = %q, want derived default %q", c.DBURL, wantDBURL)
 	}
 }
 
+// TestDefaultDBURLOpensTheDatabaseInWALMode opens the db_url derived from
+// state_dir with the SQLite driver pixad uses and checks that the database
+// is in WAL mode: the driver ignores any parameter it does not know.
+func TestDefaultDBURLOpensTheDatabaseInWALMode(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+"state_dir: "+t.TempDir()+"\n")
+	if err != nil {
+		t.Fatalf("config with only state_dir set should be valid, got: %v", err)
+	}
+
+	db, err := sql.Open("sqlite", c.DBURL)
+	if err != nil {
+		t.Fatalf("failed to open %q: %v", c.DBURL, err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	var journalMode string
+
+	err = db.QueryRowContext(t.Context(), "PRAGMA journal_mode").Scan(&journalMode)
+	if err != nil {
+		t.Fatalf("failed to read the journal mode of %q: %v", c.DBURL, err)
+	}
+
+	if journalMode != "wal" {
+		t.Errorf("journal mode of %q = %q, want wal", c.DBURL, journalMode)
+	}
+}
+
 func TestExplicitValidValuesAreUsed(t *testing.T) {
 	t.Parallel()
 
@@ -182,6 +217,25 @@ func TestCommaSeparatedAllowlistStillSupported(t *testing.T) {
 	}
 }
 
+// TestAllowlistHostsAcceptsUnderscore checks that an upstream host name with
+// an underscore, which pixa can fetch from, is accepted as an entry.
+func TestAllowlistHostsAcceptsUnderscore(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+`allowlist_hosts:
+  - my_bucket.example.com
+  - .my_bucket.example.org
+`)
+	if err != nil {
+		t.Fatalf("host names with an underscore should load, got error: %v", err)
+	}
+
+	want := []string{"my_bucket.example.com", ".my_bucket.example.org"}
+	if !slices.Equal(c.AllowlistHosts, want) {
+		t.Errorf("AllowlistHosts = %v, want %v", c.AllowlistHosts, want)
+	}
+}
+
 // runAbortCases asserts that each case's config aborts startup with an
 // error message mentioning every expected substring.
 func runAbortCases(t *testing.T, cases []abortCase) {
@@ -284,6 +338,20 @@ func invalidHostAndCredentialCases() []abortCase {
 				keyAllowlistHosts, "example.com/images",
 			},
 		},
+		{
+			name: "allowlist host with wildcard",
+			yaml: signingKeyLine + "allowlist_hosts:\n  - \"*.example.com\"\n",
+			wantErrSubstrings: []string{
+				keyAllowlistHosts, "*.example.com",
+			},
+		},
+		{
+			name: "allowlist host with port",
+			yaml: signingKeyLine + "allowlist_hosts:\n  - example.com:8443\n",
+			wantErrSubstrings: []string{
+				keyAllowlistHosts, "example.com:8443",
+			},
+		},
 		{
 			name:              "allowlist host with whitespace",
 			yaml:              signingKeyLine + "allowlist_hosts:\n  - \"exa mple.com\"\n",
@@ -564,6 +632,116 @@ 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()
 

internal/config/env_internal_test.go

@@ -65,6 +65,7 @@ func TestEnvironmentSetsEveryKey(t *testing.T) {
 	t.Setenv("PIXA_METRICS_PASSWORD", "metricspass")
 	t.Setenv("PIXA_SIGNING_KEY", validTestSigningKey)
 	t.Setenv("PIXA_ALLOWLIST_HOSTS", "s3.sneak.cloud,.example.com")
+	t.Setenv("PIXA_REFERER_BLOCKLIST", "hotlinker.example,.leech.example")
 	t.Setenv("PIXA_ALLOW_HTTP", "true")
 	t.Setenv("PIXA_UPSTREAM_CONNECTIONS_PER_HOST", "5")
 	t.Setenv("PIXA_UPSTREAM_CONNECTIONS", "10")
@@ -93,12 +94,13 @@ func TestEnvironmentSetsEveryKey(t *testing.T) {
 		MetricsPassword:            "metricspass",
 		SigningKey:                 validTestSigningKey,
 		AllowlistHosts:             []string{testHostS3, ".example.com"},
+		RefererBlocklist:           []string{"hotlinker.example", ".leech.example"},
 		AllowHTTP:                  true,
 		UpstreamConnectionsPerHost: 5,
 		UpstreamConnections:        10,
 		MaxConcurrentProcessing:    3,
 		CacheMaxBytes:              1024,
-		cacheMaxBytesExplicit:      true,
+		CacheMaxBytesExplicit:      true,
 		BlockedNetworks:            []netip.Prefix{netip.MustParsePrefix("203.0.113.0/24")},
 		TrustedProxies:             []netip.Prefix{netip.MustParsePrefix("192.0.2.0/24")},
 		AccessControlAllowOrigin:   "https://app.example.com",

internal/config/referer_blocklist_internal_test.go

@@ -0,0 +1,166 @@
+package config
+
+import (
+	"slices"
+	"testing"
+)
+
+// TestRefererBlocklistParsed loads a referer_blocklist with a host and a
+// pattern starting with "." and checks both are kept in order.
+func TestRefererBlocklistParsed(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+`referer_blocklist:
+  - leech.example
+  - .hotlinker.example
+`)
+	if err != nil {
+		t.Fatalf("valid referer_blocklist should load, got error: %v", err)
+	}
+
+	want := []string{"leech.example", ".hotlinker.example"}
+	if !slices.Equal(c.RefererBlocklist, want) {
+		t.Errorf("RefererBlocklist = %v, want %v", c.RefererBlocklist, want)
+	}
+}
+
+// TestRefererBlocklistAcceptsIPAddresses checks that IPv4 and IPv6 addresses,
+// the IPv6 one written without brackets, are accepted as entries.
+func TestRefererBlocklistAcceptsIPAddresses(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+`referer_blocklist:
+  - 192.0.2.7
+  - "2001:db8::7"
+`)
+	if err != nil {
+		t.Fatalf("IP address entries should load, got error: %v", err)
+	}
+
+	want := []string{"192.0.2.7", "2001:db8::7"}
+	if !slices.Equal(c.RefererBlocklist, want) {
+		t.Errorf("RefererBlocklist = %v, want %v", c.RefererBlocklist, want)
+	}
+}
+
+// TestRefererBlocklistAcceptsUnderscore checks that a host name with an
+// underscore, which a page can be served from, is accepted as an entry.
+func TestRefererBlocklistAcceptsUnderscore(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+`referer_blocklist:
+  - my_site.leech.example
+  - .my_site.hotlinker.example
+`)
+	if err != nil {
+		t.Fatalf("host names with an underscore should load, got error: %v", err)
+	}
+
+	want := []string{"my_site.leech.example", ".my_site.hotlinker.example"}
+	if !slices.Equal(c.RefererBlocklist, want) {
+		t.Errorf("RefererBlocklist = %v, want %v", c.RefererBlocklist, want)
+	}
+}
+
+// TestRefererBlocklistOmittedIsEmpty checks that an omitted key blocks no
+// referer.
+func TestRefererBlocklistOmittedIsEmpty(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine)
+	if err != nil {
+		t.Fatalf("minimal config should be valid, got error: %v", err)
+	}
+
+	if len(c.RefererBlocklist) != 0 {
+		t.Errorf("RefererBlocklist = %v, want empty", c.RefererBlocklist)
+	}
+}
+
+// TestRefererBlocklistInvalidAbortsStartup checks that an entry that is not a
+// host, or a value that is not a list of them, aborts startup with an error
+// naming the key and the entry.
+func TestRefererBlocklistInvalidAbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	runAbortCases(t, []abortCase{
+		{
+			name: "entry with a scheme",
+			yaml: signingKeyLine + "referer_blocklist:\n  - https://leech.example\n",
+			wantErrSubstrings: []string{
+				keyRefererBlocklist, "https://leech.example",
+			},
+		},
+		{
+			name: "entry with a path",
+			yaml: signingKeyLine + "referer_blocklist:\n  - leech.example/page\n",
+			wantErrSubstrings: []string{
+				keyRefererBlocklist, "leech.example/page",
+			},
+		},
+		{
+			name: "wildcard entry",
+			yaml: signingKeyLine + "referer_blocklist:\n  - \"*.leech.example\"\n",
+			wantErrSubstrings: []string{
+				keyRefererBlocklist, "*.leech.example",
+			},
+		},
+		{
+			name: "entry with a port",
+			yaml: signingKeyLine + "referer_blocklist:\n  - leech.example:8080\n",
+			wantErrSubstrings: []string{
+				keyRefererBlocklist, "leech.example:8080",
+			},
+		},
+		{
+			name: "two leading dots",
+			yaml: signingKeyLine + "referer_blocklist:\n  - ..leech.example\n",
+			wantErrSubstrings: []string{
+				keyRefererBlocklist, "..leech.example",
+			},
+		},
+		{
+			name:              "dot only",
+			yaml:              signingKeyLine + "referer_blocklist:\n  - \".\"\n",
+			wantErrSubstrings: []string{keyRefererBlocklist, `"."`},
+		},
+		{
+			name:              "empty entry",
+			yaml:              signingKeyLine + "referer_blocklist:\n  - \"\"\n",
+			wantErrSubstrings: []string{keyRefererBlocklist},
+		},
+		{
+			name:              "entry not a string",
+			yaml:              signingKeyLine + "referer_blocklist:\n  - 42\n",
+			wantErrSubstrings: []string{keyRefererBlocklist, "42"},
+		},
+		{
+			name:              "null value",
+			yaml:              signingKeyLine + "referer_blocklist:\n",
+			wantErrSubstrings: []string{keyRefererBlocklist, nullValueText},
+		},
+	})
+}
+
+// TestRefererBlocklistFromEnvironment checks that PIXA_REFERER_BLOCKLIST
+// takes comma-separated entries, and that an entry in it that is not a host
+// aborts startup naming the variable and the entry.
+func TestRefererBlocklistFromEnvironment(t *testing.T) {
+	t.Setenv("PIXA_SIGNING_KEY", validTestSigningKey)
+	t.Setenv("PIXA_REFERER_BLOCKLIST", " leech.example , .hotlinker.example ")
+
+	c, err := newFromSmartConfig(nil)
+	if err != nil {
+		t.Fatalf("valid PIXA_REFERER_BLOCKLIST should load, got error: %v", err)
+	}
+
+	want := []string{"leech.example", ".hotlinker.example"}
+	if !slices.Equal(c.RefererBlocklist, want) {
+		t.Errorf("RefererBlocklist = %v, want %v", c.RefererBlocklist, want)
+	}
+
+	t.Setenv("PIXA_REFERER_BLOCKLIST", "leech.example,https://hotlinker.example")
+
+	_, err = newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_REFERER_BLOCKLIST", "https://hotlinker.example")
+}

internal/database/concurrent_writes_internal_test.go

@@ -0,0 +1,152 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/config"
+)
+
+// TestConcurrentWritesAllSucceed opens a database the way pixad does and
+// writes to it from several goroutines at once, as one request's writes and
+// the background eviction pass do. Every write must succeed, none failing
+// with "database is locked", whether or not db_url already has parameters,
+// and the parameters it has must still apply.
+func TestConcurrentWritesAllSucceed(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name            string
+		query           string
+		wantJournalMode string
+	}{
+		{
+			name:            "db_url without parameters",
+			query:           "",
+			wantJournalMode: "delete",
+		},
+		{
+			name:            "db_url with the WAL parameter",
+			query:           "?_pragma=journal_mode(WAL)",
+			wantJournalMode: "wal",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			dbURL := "file:" + filepath.Join(t.TempDir(), "state.sqlite3") + tt.query
+
+			d := &Database{
+				log:    slog.New(slog.DiscardHandler),
+				config: &config.Config{DBURL: dbURL},
+			}
+
+			err := d.connect(t.Context())
+			if err != nil {
+				t.Fatalf("failed to connect to %q: %v", dbURL, err)
+			}
+
+			t.Cleanup(func() { _ = d.db.Close() })
+
+			writeConcurrently(t, d.db)
+
+			var journalMode string
+
+			err = d.db.QueryRowContext(t.Context(), "PRAGMA journal_mode").
+				Scan(&journalMode)
+			if err != nil {
+				t.Fatalf("failed to read the journal mode: %v", err)
+			}
+
+			if journalMode != tt.wantJournalMode {
+				t.Errorf("journal mode = %q, want %q", journalMode, tt.wantJournalMode)
+			}
+		})
+	}
+}
+
+// writeConcurrently runs writeLikeOneRequest from several goroutines at once
+// and checks that every write was made.
+func writeConcurrently(t *testing.T, db *sql.DB) {
+	t.Helper()
+
+	const (
+		writers       = 4
+		requestsEach  = 20
+		totalRequests = writers * requestsEach
+	)
+
+	ctx := t.Context()
+
+	var wg sync.WaitGroup
+
+	for writer := range writers {
+		wg.Go(func() {
+			for request := range requestsEach {
+				key := fmt.Sprintf("%d-%d", writer, request)
+
+				err := writeLikeOneRequest(ctx, db, key)
+				if err != nil {
+					t.Errorf("writer %d: %v", writer, err)
+
+					return
+				}
+			}
+		})
+	}
+
+	wg.Wait()
+
+	var hits, sources int
+
+	err := db.QueryRowContext(ctx, `
+		SELECT hit_count, (SELECT COUNT(*) FROM source_content)
+		FROM cache_stats WHERE id = 1
+	`).Scan(&hits, &sources)
+	if err != nil {
+		t.Fatalf("failed to count the writes: %v", err)
+	}
+
+	if hits != totalRequests || sources != totalRequests {
+		t.Errorf("hit_count = %d and %d source_content rows, want %d of each",
+			hits, sources, totalRequests)
+	}
+}
+
+// writeLikeOneRequest makes the writes one request and the eviction pass
+// make: it counts a cache hit, stores a source, records a transformed image
+// and deletes that record again.
+func writeLikeOneRequest(ctx context.Context, db *sql.DB, key string) error {
+	_, err := db.ExecContext(ctx,
+		`UPDATE cache_stats SET hit_count = hit_count + 1 WHERE id = 1`)
+	if err != nil {
+		return fmt.Errorf("counting a cache hit: %w", err)
+	}
+
+	_, err = db.ExecContext(ctx, `INSERT INTO source_content
+		(content_hash, content_type, size_bytes) VALUES (?, 'image/png', 1)`, key)
+	if err != nil {
+		return fmt.Errorf("storing a source: %w", err)
+	}
+
+	_, err = db.ExecContext(ctx, `INSERT INTO variant_content
+		(cache_key, size_bytes, content_type) VALUES (?, 1, 'image/png')`, key)
+	if err != nil {
+		return fmt.Errorf("recording a transformed image: %w", err)
+	}
+
+	_, err = db.ExecContext(ctx,
+		`DELETE FROM variant_content WHERE cache_key = ?`, key)
+	if err != nil {
+		return fmt.Errorf("evicting a transformed image: %w", err)
+	}
+
+	return nil
+}

internal/database/database.go

@@ -237,13 +237,24 @@ func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
 	return nil
 }
 
-// DB returns the underlying sql.DB.
+// DB returns the underlying sql.DB. It has one connection, so close any
+// rows and end any transaction before running another query on it; a
+// query run while they are open waits forever.
 func (s *Database) DB() *sql.DB {
 	return s.db
 }
 
 func (s *Database) connect(ctx context.Context) error {
-	dbURL := s.config.DBURL
+	// With a busy timeout, a write that finds another program writing to
+	// the same database file waits up to five seconds for it instead of
+	// failing at once with "database is locked". The driver runs each
+	// _pragma parameter on every connection it opens.
+	separator := "?"
+	if strings.Contains(s.config.DBURL, "?") {
+		separator = "&"
+	}
+
+	dbURL := s.config.DBURL + separator + "_pragma=busy_timeout(5000)"
 
 	s.log.Info("connecting to database", "url", dbURL)
 
@@ -254,6 +265,11 @@ func (s *Database) connect(ctx context.Context) error {
 		return err
 	}
 
+	// One connection: pixa's own reads and writes run on it one at a
+	// time instead of competing for SQLite's lock, where a write that
+	// keeps losing can wait past the busy timeout and be lost.
+	db.SetMaxOpenConns(1)
+
 	err = db.PingContext(ctx)
 	if err != nil {
 		s.log.Error("failed to ping database", "error", err)

internal/db/migrations/001_schema.sql

@@ -2,21 +2,19 @@
 -- Creates all tables for the pixa caching image proxy
 
 -- Source content blobs
--- Files stored at: cache/src-content/<ab>/<cd>/<sha256>
--- last_accessed_at is NULL until the first LRU touch; eviction falls
--- back to fetched_at for rows that have never been touched.
+-- Files stored at: cache/sources/<ab>/<cd>/<sha256>
 CREATE TABLE IF NOT EXISTS source_content (
     content_hash TEXT PRIMARY KEY,
     content_type TEXT NOT NULL,
     size_bytes INTEGER NOT NULL,
     fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    last_accessed_at DATETIME
+    last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 CREATE INDEX IF NOT EXISTS idx_source_content_last_accessed
     ON source_content(last_accessed_at);
 
 -- Source URL metadata - maps URLs to content hashes
--- JSON stored at: cache/src-metadata/<hostname>/<path_hash>.json
+-- JSON stored at: cache/metadata/<hostname>/<path_hash>.json
 CREATE TABLE IF NOT EXISTS source_metadata (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     source_host TEXT NOT NULL,
@@ -42,9 +40,8 @@ CREATE INDEX IF NOT EXISTS idx_source_meta_content_hash ON source_metadata(conte
 -- Processed variant blobs
 -- Files stored at: cache/variants/<ab>/<cd>/<cache_key> (plus a .meta
 -- sidecar with the content type). Tracked here (like source content
--- blobs above) so total cache usage can be computed with a SUM query,
--- never a directory scan, and so LRU eviction has a timestamp to order
--- on.
+-- blobs above) so total cache usage is known without a directory scan,
+-- and so LRU eviction has a timestamp to order on.
 CREATE TABLE IF NOT EXISTS variant_content (
     cache_key TEXT PRIMARY KEY,
     size_bytes INTEGER NOT NULL,
@@ -55,8 +52,77 @@ CREATE TABLE IF NOT EXISTS variant_content (
 CREATE INDEX IF NOT EXISTS idx_variant_content_last_accessed
     ON variant_content(last_accessed_at);
 
+-- Total cache usage: the sum of size_bytes over source_content and
+-- variant_content, kept by the triggers below in the same statement
+-- that adds, removes or resizes a row, so eviction reads this one row
+-- instead of summing both tables. Each trigger also adds one to
+-- change_count; the reconciliation pass, which sums both tables a page
+-- at a time, corrects total_size_bytes only if change_count did not
+-- move while it summed.
+CREATE TABLE IF NOT EXISTS cache_usage (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    total_size_bytes INTEGER NOT NULL DEFAULT 0,
+    change_count INTEGER NOT NULL DEFAULT 0
+);
+INSERT OR IGNORE INTO cache_usage (id) VALUES (1);
+
+CREATE TRIGGER IF NOT EXISTS source_content_usage_insert
+AFTER INSERT ON source_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes + NEW.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
+CREATE TRIGGER IF NOT EXISTS source_content_usage_delete
+AFTER DELETE ON source_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes - OLD.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
+CREATE TRIGGER IF NOT EXISTS source_content_usage_update
+AFTER UPDATE OF size_bytes ON source_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes - OLD.size_bytes + NEW.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
+CREATE TRIGGER IF NOT EXISTS variant_content_usage_insert
+AFTER INSERT ON variant_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes + NEW.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
+CREATE TRIGGER IF NOT EXISTS variant_content_usage_delete
+AFTER DELETE ON variant_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes - OLD.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
+CREATE TRIGGER IF NOT EXISTS variant_content_usage_update
+AFTER UPDATE OF size_bytes ON variant_content
+BEGIN
+    UPDATE cache_usage
+    SET total_size_bytes = total_size_bytes - OLD.size_bytes + NEW.size_bytes,
+        change_count = change_count + 1
+    WHERE id = 1;
+END;
+
 -- Output/transformed content blobs
--- Files stored at: cache/dst-content/<ab>/<cd>/<sha256>
+-- Not written: transformed images are stored in cache/variants and
+-- tracked in variant_content above.
 CREATE TABLE IF NOT EXISTS output_content (
     content_hash TEXT PRIMARY KEY,
     content_type TEXT NOT NULL,

internal/encurl/encurl.go

@@ -14,7 +14,7 @@ import (
 // Default values for optional fields.
 const (
 	DefaultQuality = 85
-	DefaultFormat  = imgcache.FormatOriginal
+	DefaultFormat  = imgcache.FormatJXL
 	DefaultFitMode = imgcache.FitCover
 
 	// HKDF salt for URL encryption key derivation
@@ -37,7 +37,7 @@ type Payload struct {
 	SourceQuery string               `cbor:"q,omitempty"`  // optional
 	Width       int                  `cbor:"w,omitempty"`  // 0 = original
 	Height      int                  `cbor:"ht,omitempty"` // 0 = original
-	Format      imgcache.ImageFormat `cbor:"f,omitempty"`  // default: orig
+	Format      imgcache.ImageFormat `cbor:"f,omitempty"`  // default: jxl
 	Quality     int                  `cbor:"ql,omitempty"` // default: 85
 	FitMode     imgcache.FitMode     `cbor:"fm,omitempty"` // default: cover
 	ExpiresAt   int64                `cbor:"e,omitempty"`  // 0 = never expires

internal/globals/globals.go

@@ -7,8 +7,8 @@ import (
 
 const appname = "pixad"
 
-// Version is populated from main() via ldflags.
-var Version string //nolint:gochecknoglobals // set from main
+// Version is set by app.Run to the version main was built with.
+var Version string //nolint:gochecknoglobals // set by app.Run
 
 // Globals holds application-wide constants.
 type Globals struct {

internal/handlers/auth.go

@@ -369,10 +369,15 @@ func (s *Handlers) buildGeneratedURL(r *http.Request, token, format string) stri
 		scheme = "http"
 	}
 
-	// Determine file extension for the trailing filename
+	// Determine file extension for the trailing filename. A form with no
+	// format makes a token with none, which is served as encurl.DefaultFormat.
 	ext := format
-	if ext == "" || ext == "orig" {
-		ext = "jpg" // Default extension
+
+	switch format {
+	case "":
+		ext = string(encurl.DefaultFormat)
+	case "orig", "auto":
+		ext = "jpg"
 	}
 
 	return scheme + "://" + r.Host + "/v1/e/" + url.PathEscape(token) + "/img." + ext

internal/handlers/auth_login_log_internal_test.go

@@ -0,0 +1,59 @@
+package handlers
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/session"
+)
+
+// TestLoginLogLeavesOutSubmittedKey verifies that the log lines for a
+// failed and for a successful login do not contain the submitted key.
+func TestLoginLogLeavesOutSubmittedKey(t *testing.T) {
+	t.Parallel()
+
+	const wrongKey = "wrong-signing-key-fedcba9876543210"
+
+	var buf bytes.Buffer
+
+	sessMgr, err := session.NewManager(testSigningKey)
+	if err != nil {
+		t.Fatalf("session.NewManager() error = %v", err)
+	}
+
+	h := &Handlers{
+		log:     slog.New(slog.NewJSONHandler(&buf, nil)),
+		config:  &config.Config{SigningKey: testSigningKey},
+		sessMgr: sessMgr,
+	}
+
+	submittedKeys := []string{wrongKey, testSigningKey}
+
+	for _, key := range submittedKeys {
+		form := url.Values{loginKeyField: {key}}
+		req := httptest.NewRequestWithContext(
+			t.Context(), http.MethodPost, "/",
+			strings.NewReader(form.Encode()))
+		req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+		h.handleLoginPost(httptest.NewRecorder(), req)
+	}
+
+	for _, msg := range []string{"failed login attempt", "successful login"} {
+		if !strings.Contains(buf.String(), msg) {
+			t.Fatalf("log missing %q; got %q", msg, buf.String())
+		}
+	}
+
+	for _, key := range submittedKeys {
+		if strings.Contains(buf.String(), key) {
+			t.Errorf("log contains submitted key %q; got %q", key, buf.String())
+		}
+	}
+}

internal/handlers/auth_session_internal_test.go

@@ -0,0 +1,292 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/session"
+)
+
+// formatField is the generator form's format field name.
+const formatField = "format"
+
+// Markers telling the login page from the generator page.
+const (
+	loginForm     = `action="/"`
+	loginKeyInput = `name="key"`
+	generatorForm = `action="/generate"`
+)
+
+// generatedURLPattern extracts the path of the URL the generator page shows.
+// The test router runs with debug on, so the URL starts with http, and its
+// host is httptest's default request host.
+var generatedURLPattern = regexp.MustCompile(
+	`value="http://example\.com(/v1/e/[^"]+)"`)
+
+// findSessionCookie returns the session cookie rec sets, or nil if it sets
+// none.
+func findSessionCookie(rec *httptest.ResponseRecorder) *http.Cookie {
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == session.CookieName {
+			return c
+		}
+	}
+
+	return nil
+}
+
+// TestHandleRoot_NoSession_ShowsLoginForm verifies that GET / without a
+// login session shows the login form.
+func TestHandleRoot_NoSession_ShowsLoginForm(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/", nil))
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	body := rec.Body.String()
+	if !strings.Contains(body, loginForm) || !strings.Contains(body, loginKeyInput) {
+		t.Errorf("page is not the login form: %s", body)
+	}
+}
+
+// TestLoginPost_WrongKey_ShowsErrorWithoutSession verifies that a wrong key
+// shows the login form again with an error, and sets no session cookie.
+func TestLoginPost_WrongKey_ShowsErrorWithoutSession(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	cookies, token := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/", cookies, url.Values{
+		loginKeyField:  {"wrong-signing-key-fedcba9876543210"},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	body := rec.Body.String()
+	if !strings.Contains(body, loginForm) || !strings.Contains(body, loginKeyInput) {
+		t.Errorf("page is not the login form: %s", body)
+	}
+
+	if !strings.Contains(body, "Invalid signing key") {
+		t.Error("login form does not show the error")
+	}
+
+	if c := findSessionCookie(rec); c != nil {
+		t.Errorf("wrong key set a session cookie: %s", c)
+	}
+}
+
+// TestLoginPost_RightKey_SetsSessionCookie verifies that the right key answers
+// 303 to / with a session cookie marked Secure, HttpOnly and SameSite=Strict,
+// and that GET / with that cookie shows the generator page.
+func TestLoginPost_RightKey_SetsSessionCookie(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	cookies, token := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/", cookies, url.Values{
+		loginKeyField:  {testSigningKey},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusSeeOther || rec.Header().Get("Location") != "/" {
+		t.Fatalf("status = %d, Location = %q, want %d to /",
+			rec.Code, rec.Header().Get("Location"), http.StatusSeeOther)
+	}
+
+	sessionCookie := findSessionCookie(rec)
+	if sessionCookie == nil {
+		t.Fatal("right key set no session cookie")
+	}
+
+	t.Logf("Set-Cookie: %s", sessionCookie)
+
+	if !sessionCookie.Secure {
+		t.Error("session cookie is not Secure")
+	}
+
+	if !sessionCookie.HttpOnly {
+		t.Error("session cookie is not HttpOnly")
+	}
+
+	if sessionCookie.SameSite != http.SameSiteStrictMode {
+		t.Errorf("session cookie SameSite = %v, want Strict", sessionCookie.SameSite)
+	}
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", nil)
+	req.AddCookie(sessionCookie)
+
+	rec = httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK ||
+		!strings.Contains(rec.Body.String(), generatorForm) {
+		t.Errorf("GET / with the session cookie: status = %d, "+
+			"want %d and the generator page", rec.Code, http.StatusOK)
+	}
+}
+
+// TestHandleLogout_ClearsSessionCookie verifies that GET /logout answers 303
+// to / and replaces the session cookie with an empty one sent with
+// Max-Age=0, which makes the browser delete it.
+func TestHandleLogout_ClearsSessionCookie(t *testing.T) {
+	t.Parallel()
+
+	h, _ := newCSRFTestRouter(t)
+
+	req := httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/logout", nil)
+	req.AddCookie(newSessionCookie(t, h))
+
+	rec := httptest.NewRecorder()
+	h.HandleLogout().ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusSeeOther || rec.Header().Get("Location") != "/" {
+		t.Fatalf("status = %d, Location = %q, want %d to /",
+			rec.Code, rec.Header().Get("Location"), http.StatusSeeOther)
+	}
+
+	t.Logf("Set-Cookie: %s", rec.Header().Get("Set-Cookie"))
+
+	sessionCookie := findSessionCookie(rec)
+	if sessionCookie == nil {
+		t.Fatal("logout did not set the session cookie")
+	}
+
+	if sessionCookie.Value != "" {
+		t.Errorf("session cookie value = %q, want empty", sessionCookie.Value)
+	}
+
+	// net/http reads a Max-Age=0 attribute back as MaxAge -1.
+	if sessionCookie.MaxAge != -1 {
+		t.Errorf("session cookie MaxAge = %d, want -1 (Max-Age=0)",
+			sessionCookie.MaxAge)
+	}
+}
+
+// TestGeneratePost_NoSession_RedirectsToLogin verifies that POST /generate
+// with a valid CSRF token but no login session answers 303 to / and makes no
+// URL.
+func TestGeneratePost_NoSession_RedirectsToLogin(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	cookies, token := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/generate", cookies, url.Values{
+		sourceURLField: {testSourceURL},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusSeeOther || rec.Header().Get("Location") != "/" {
+		t.Fatalf("status = %d, Location = %q, want %d to /",
+			rec.Code, rec.Header().Get("Location"), http.StatusSeeOther)
+	}
+
+	if strings.Contains(rec.Body.String(), "/v1/e/") {
+		t.Error("a URL was made without a login session")
+	}
+}
+
+// TestGeneratePost_URLServesImage verifies that the URL the generator page
+// makes is served by /v1/e/. The image route runs on handlers of its own,
+// made with the same signing key.
+func TestGeneratePost_URLServesImage(t *testing.T) {
+	t.Parallel()
+
+	_, imageSrv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	rec := generatePost(t, url.Values{
+		sourceURLField: {"https://" + signedHost + photoPath},
+		widthField:     {"50"},
+		heightField:    {"50"},
+		formatField:    {string(imgcache.FormatJPEG)},
+	})
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST /generate status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	match := generatedURLPattern.FindStringSubmatch(rec.Body.String())
+	if match == nil {
+		t.Fatalf("generator page shows no URL: %s", rec.Body.String())
+	}
+
+	t.Logf("generated URL path: %s", match[1])
+
+	imageRec := httptest.NewRecorder()
+	imageSrv.ServeHTTP(imageRec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, match[1], nil))
+
+	requireServedPhoto(t, imageRec)
+}
+
+// TestGeneratePost_URLWithTTLExpires verifies that a URL the generator page
+// makes with a ttl of one second is served by /v1/e/ at once and answers 410
+// once the ttl has passed.
+func TestGeneratePost_URLWithTTLExpires(t *testing.T) {
+	t.Parallel()
+
+	_, imageSrv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	rec := generatePost(t, url.Values{
+		sourceURLField: {"https://" + signedHost + photoPath},
+		widthField:     {"50"},
+		heightField:    {"50"},
+		formatField:    {string(imgcache.FormatJPEG)},
+		ttlField:       {"1"},
+	})
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST /generate status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	match := generatedURLPattern.FindStringSubmatch(rec.Body.String())
+	if match == nil {
+		t.Fatalf("generator page shows no URL: %s", rec.Body.String())
+	}
+
+	imageRec := httptest.NewRecorder()
+	imageSrv.ServeHTTP(imageRec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, match[1], nil))
+
+	requireServedPhoto(t, imageRec)
+
+	// The URL keeps the time it expires in whole seconds and is served
+	// through the whole of that second, so a ttl of one second has passed
+	// for certain two seconds after the URL was made.
+	time.Sleep(2 * time.Second)
+
+	imageRec = httptest.NewRecorder()
+	imageSrv.ServeHTTP(imageRec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, match[1], nil))
+
+	t.Logf("GET %s after the ttl: %d %q", match[1], imageRec.Code, imageRec.Body)
+
+	if imageRec.Code != http.StatusGone {
+		t.Errorf("status after the ttl = %d, want %d",
+			imageRec.Code, http.StatusGone)
+	}
+}

internal/handlers/cache_max_bytes_internal_test.go

@@ -0,0 +1,147 @@
+package handlers
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"go.uber.org/fx/fxtest"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/logger"
+)
+
+// TestNewCacheConfigFromCacheMaxBytes checks the cache configuration
+// built from cache_max_bytes: omitted, the cache works out the default
+// limit; 0 turns the disk cache off; a positive value is the limit,
+// unchanged.
+func TestNewCacheConfigFromCacheMaxBytes(t *testing.T) {
+	t.Parallel()
+
+	const oneGiB = 1 << 30
+
+	cases := []struct {
+		name                   string
+		cacheMaxBytes          int64
+		cacheMaxBytesExplicit  bool
+		wantMaxBytes           int64
+		wantUseDefaultMaxBytes bool
+		wantDisableDiskCache   bool
+	}{
+		{
+			name:                   "cache_max_bytes omitted",
+			cacheMaxBytes:          0,
+			cacheMaxBytesExplicit:  false,
+			wantMaxBytes:           0,
+			wantUseDefaultMaxBytes: true,
+			wantDisableDiskCache:   false,
+		},
+		{
+			name:                   "cache_max_bytes: 0",
+			cacheMaxBytes:          0,
+			cacheMaxBytesExplicit:  true,
+			wantMaxBytes:           0,
+			wantUseDefaultMaxBytes: false,
+			wantDisableDiskCache:   true,
+		},
+		{
+			name:                   "cache_max_bytes: 1 GiB",
+			cacheMaxBytes:          oneGiB,
+			cacheMaxBytesExplicit:  true,
+			wantMaxBytes:           oneGiB,
+			wantUseDefaultMaxBytes: false,
+			wantDisableDiskCache:   false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			cfg := &config.Config{
+				CacheMaxBytes:         tc.cacheMaxBytes,
+				CacheMaxBytesExplicit: tc.cacheMaxBytesExplicit,
+			}
+
+			got := newCacheConfig(cfg, nil)
+			t.Logf("MaxBytes = %d, UseDefaultMaxBytes = %v, DisableDiskCache = %v",
+				got.MaxBytes, got.UseDefaultMaxBytes, got.DisableDiskCache)
+
+			if got.MaxBytes != tc.wantMaxBytes {
+				t.Errorf("MaxBytes = %d, want %d", got.MaxBytes, tc.wantMaxBytes)
+			}
+
+			if got.UseDefaultMaxBytes != tc.wantUseDefaultMaxBytes {
+				t.Errorf("UseDefaultMaxBytes = %v, want %v",
+					got.UseDefaultMaxBytes, tc.wantUseDefaultMaxBytes)
+			}
+
+			if got.DisableDiskCache != tc.wantDisableDiskCache {
+				t.Errorf("DisableDiskCache = %v, want %v",
+					got.DisableDiskCache, tc.wantDisableDiskCache)
+			}
+		})
+	}
+}
+
+// TestDiskCacheOffOnlyForExplicitZeroCacheMaxBytes starts the handlers
+// once with cache_max_bytes omitted and once with cache_max_bytes: 0,
+// and checks by whether the cache directories were created that the
+// disk cache is on in the first case and off in the second.
+func TestDiskCacheOffOnlyForExplicitZeroCacheMaxBytes(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name                  string
+		cacheMaxBytesExplicit bool
+		wantDiskCache         bool
+	}{
+		{name: "cache_max_bytes omitted", cacheMaxBytesExplicit: false, wantDiskCache: true},
+		{name: "cache_max_bytes: 0", cacheMaxBytesExplicit: true, wantDiskCache: false},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			stateDir := t.TempDir()
+			cfg := &config.Config{
+				SigningKey:            testSigningKey,
+				StateDir:              stateDir,
+				DBURL:                 "file:" + filepath.Join(stateDir, "state.sqlite3"),
+				CacheMaxBytes:         0,
+				CacheMaxBytesExplicit: tc.cacheMaxBytesExplicit,
+			}
+
+			lc := fxtest.NewLifecycle(t)
+
+			log, err := logger.New(lc, logger.Params{Globals: &globals.Globals{}})
+			if err != nil {
+				t.Fatalf("logger.New() error = %v", err)
+			}
+
+			db, err := database.New(lc, database.Params{Logger: log, Config: cfg})
+			if err != nil {
+				t.Fatalf("database.New() error = %v", err)
+			}
+
+			_, err = New(lc, Params{Logger: log, Database: db, Config: cfg})
+			if err != nil {
+				t.Fatalf("New() error = %v", err)
+			}
+
+			lc.RequireStart()
+			t.Cleanup(lc.RequireStop)
+
+			_, err = os.Stat(filepath.Join(stateDir, "cache", "variants"))
+			gotDiskCache := err == nil
+
+			if gotDiskCache != tc.wantDiskCache {
+				t.Errorf("cache directories created = %v, want %v",
+					gotDiskCache, tc.wantDiskCache)
+			}
+		})
+	}
+}

internal/handlers/fetcher_internal_test.go

@@ -0,0 +1,61 @@
+package handlers
+
+import (
+	"net/http"
+	"net/netip"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/healthcheck"
+	"sneak.berlin/go/pixa/internal/logger"
+)
+
+// TestHandlersBuildTheirOwnFetcherWhenNoneIsProvided builds the handlers as
+// pixad does, in an fx app that provides no fetcher, and requests an image
+// from 192.0.2.10, which is on the allowlist and in blocked_networks. The URL
+// check accepts that address; only the dialer that refuses internal
+// addresses checks blocked_networks, so the answer is 403 only if the
+// fetcher the handlers build from the config connects with that dialer. Any
+// other dialer would try to connect until the upstream fetch timeout, which
+// is short so that the test then fails quickly.
+func TestHandlersBuildTheirOwnFetcherWhenNoneIsProvided(t *testing.T) {
+	t.Parallel()
+
+	const host = "192.0.2.10"
+
+	stateDir := t.TempDir()
+	cfg := &config.Config{
+		SigningKey:           testSigningKey,
+		StateDir:             stateDir,
+		DBURL:                "file:" + filepath.Join(stateDir, "state.sqlite3"),
+		AllowlistHosts:       []string{host},
+		BlockedNetworks:      []netip.Prefix{netip.MustParsePrefix("192.0.2.0/24")},
+		UpstreamFetchTimeout: 2 * time.Second,
+		// With no connection slots, the fetch would fail before dialing.
+		UpstreamConnections: config.DefaultUpstreamConnections,
+	}
+
+	var h *Handlers
+
+	app := fxtest.New(t,
+		fx.Supply(cfg),
+		fx.Provide(globals.New, logger.New, database.New, healthcheck.New, New),
+		fx.Populate(&h),
+	)
+	app.RequireStart()
+	t.Cleanup(app.RequireStop)
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", h.HandleImage())
+
+	rec := sendGet(t, r, photoURL(host))
+	checkErrorBody(t, rec, http.StatusForbidden, "forbidden")
+}

internal/handlers/format_auto.go

@@ -0,0 +1,135 @@
+package handlers
+
+import (
+	"errors"
+	"fmt"
+	"mime"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// Errors for an Accept header that an auto URL cannot be served for.
+var (
+	errInvalidAccept = errors.New("invalid Accept header")
+	errNotAcceptable = errors.New("not acceptable: auto serves " +
+		"image/jxl, image/avif, image/webp or image/jpeg")
+)
+
+// chooseAutoFormat replaces the format auto in req with the format
+// formatForAccept chooses from r's Accept header, and adds Vary: Accept to the
+// response, which then depends on that header. It answers 400 for an Accept
+// header that is not valid and 406 for one that allows none of the formats,
+// and reports whether req can be served. Any other format is left as it is.
+func (s *Handlers) chooseAutoFormat(
+	w http.ResponseWriter, r *http.Request, req *imgcache.ImageRequest,
+) bool {
+	if req.Format != imgcache.FormatAuto {
+		return true
+	}
+
+	w.Header().Add("Vary", "Accept")
+
+	format, err := formatForAccept(strings.Join(r.Header.Values("Accept"), ","))
+	if errors.Is(err, errNotAcceptable) {
+		s.respondError(w, err.Error(), http.StatusNotAcceptable)
+
+		return false
+	}
+
+	if err != nil {
+		s.respondError(w, err.Error(), http.StatusBadRequest)
+
+		return false
+	}
+
+	req.Format = format
+
+	return true
+}
+
+// formatForAccept returns the format an auto URL is served in for the Accept
+// header accept: JPEG XL when it names image/jxl, else AVIF when it names
+// image/avif, else WebP when it names image/webp, else JPEG when its most
+// specific entry of image/jpeg, image/* and */* allows it, or when it names
+// nothing. A q of 0 refuses a format. JPEG XL, AVIF and WebP must be named, as
+// clients that cannot show them send image/* and */* too.
+func formatForAccept(accept string) (imgcache.ImageFormat, error) {
+	qualities, err := parseAccept(accept)
+	if err != nil {
+		return "", err
+	}
+
+	if len(qualities) == 0 {
+		return imgcache.FormatJPEG, nil
+	}
+
+	if qualities["image/jxl"] > 0 {
+		return imgcache.FormatJXL, nil
+	}
+
+	if qualities["image/avif"] > 0 {
+		return imgcache.FormatAVIF, nil
+	}
+
+	if qualities["image/webp"] > 0 {
+		return imgcache.FormatWebP, nil
+	}
+
+	// For JPEG, the most specific entry the header has decides
+	quality, named := qualities["image/jpeg"]
+	if !named {
+		quality, named = qualities["image/*"]
+	}
+
+	if !named {
+		quality = qualities["*/*"]
+	}
+
+	if quality > 0 {
+		return imgcache.FormatJPEG, nil
+	}
+
+	return "", errNotAcceptable
+}
+
+// parseAccept returns the q of each media range the Accept header accept
+// names, 1 where it gives none. A media range named more than once keeps its
+// lowest q, so a refusal is never overridden. A media range that does not
+// parse, or a q that is not a number from 0 to 1, is an error.
+func parseAccept(accept string) (map[string]float64, error) {
+	qualities := make(map[string]float64)
+
+	for entry := range strings.SplitSeq(accept, ",") {
+		// A header field list may hold empty entries
+		if strings.TrimSpace(entry) == "" {
+			continue
+		}
+
+		mediaRange, params, err := mime.ParseMediaType(entry)
+		if err != nil {
+			return nil, fmt.Errorf("%w: %q: %w", errInvalidAccept, entry, err)
+		}
+
+		quality := 1.0
+
+		if qParam, given := params["q"]; given {
+			quality, err = strconv.ParseFloat(qParam, 64)
+			inRange := quality >= 0 && quality <= 1
+
+			if err != nil || !inRange {
+				return nil, fmt.Errorf("%w: %q: q is not a number from 0 to 1",
+					errInvalidAccept, entry)
+			}
+		}
+
+		previous, named := qualities[mediaRange]
+		if !named || quality < previous {
+			qualities[mediaRange] = quality
+		}
+	}
+
+	return qualities, nil
+}

internal/handlers/format_auto_internal_test.go

@@ -0,0 +1,310 @@
+package handlers
+
+import (
+	"errors"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// The content types the tests below expect.
+const (
+	avifType = "image/avif"
+	webpType = "image/webp"
+	jpegType = "image/jpeg"
+	jsonType = "application/json"
+)
+
+// TestFormatForAccept verifies the format chosen for the format auto from each
+// Accept header below, and the error for one that allows none of AVIF, WebP
+// and JPEG or is not valid.
+func TestFormatForAccept(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		accept  string
+		want    imgcache.ImageFormat
+		wantErr error
+	}{
+		{"AVIF-capable browser",
+			"image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
+			imgcache.FormatAVIF, nil},
+		{"WebP-capable browser",
+			"image/webp,image/png,image/svg+xml,image/*;q=0.8,*/*;q=0.5",
+			imgcache.FormatWebP, nil},
+		{"WebP only", webpType, imgcache.FormatWebP, nil},
+		{"neither", "image/png,image/*;q=0.8,*/*;q=0.5", imgcache.FormatJPEG, nil},
+		{"wildcard only", "*/*", imgcache.FormatJPEG, nil},
+		{"image wildcard only", "image/*", imgcache.FormatJPEG, nil},
+		{"absent", "", imgcache.FormatJPEG, nil},
+		{"q=0 on AVIF", "image/avif;q=0,image/webp,*/*", imgcache.FormatWebP, nil},
+		{"AVIF named twice, once with q=0", "image/avif,image/avif;q=0.0,*/*",
+			imgcache.FormatJPEG, nil},
+		{"upper case and spaces", " Image/AVIF ; Q=0.5 ", imgcache.FormatAVIF, nil},
+		{"q=0 on JPEG", "image/jpeg;q=0,image/*", "", errNotAcceptable},
+		{"q=0 on everything", "*/*;q=0", "", errNotAcceptable},
+		{"PNG only", "image/png", "", errNotAcceptable},
+		{"malformed media range", "image/", "", errInvalidAccept},
+		{"q not a number", "image/avif;q=high", "", errInvalidAccept},
+		{"q above 1", "image/avif;q=2", "", errInvalidAccept},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := formatForAccept(tt.accept)
+			t.Logf("Accept %q: %q, %v", tt.accept, got, err)
+
+			if got != tt.want || !errors.Is(err, tt.wantErr) {
+				t.Errorf("formatForAccept(%q) = %q, %v, want %q, %v",
+					tt.accept, got, err, tt.want, tt.wantErr)
+			}
+		})
+	}
+}
+
+// autoPhotoURLs returns a signed /v1/image/ URL and an encrypted /v1/e/ URL,
+// both valid for a minute, for the JPEG at photoPath on signedHost at 50x50 in
+// the format auto, made with h's image service and generator.
+func autoPhotoURLs(t *testing.T, h *Handlers) (string, string) {
+	t.Helper()
+
+	signedURL, err := h.imgSvc.GenerateSignedURL("", &imgcache.ImageRequest{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Size:       imgcache.Size{Width: 50, Height: 50},
+		Format:     imgcache.FormatAuto,
+	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
+
+	token, err := h.encGen.Generate(&encurl.Payload{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+		Format:     imgcache.FormatAuto,
+		ExpiresAt:  time.Now().Add(time.Minute).Unix(),
+	})
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	return signedURL, "/v1/e/" + token + "/img.jpg"
+}
+
+// requestImage sends method for target to srv with an Accept header line for
+// each of accept, and returns the response.
+func requestImage(
+	t *testing.T, srv http.Handler, method, target string, accept ...string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), method, target, nil)
+
+	for _, value := range accept {
+		req.Header.Add("Accept", value)
+	}
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	t.Logf("%s %s with Accept %q: %d, Content-Type %s, Vary %v, X-Pixa-Cache %s",
+		method, target, accept, rec.Code, rec.Header().Get("Content-Type"),
+		rec.Header().Values("Vary"), rec.Header().Get("X-Pixa-Cache"))
+
+	return rec
+}
+
+// TestFormatAuto_ChosenFromAccept requests an auto URL on each image route
+// with each Accept below, and checks the answer and that it carries
+// Vary: Accept. The signed URL is signed for auto, so it is valid whatever
+// Accept chooses.
+func TestFormatAuto_ChosenFromAccept(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	signedURL, encryptedURL := autoPhotoURLs(t, h)
+
+	tests := []struct {
+		name       string
+		accept     []string
+		wantStatus int
+		wantType   string
+	}{
+		{"AVIF accepted", []string{"image/avif,image/webp,*/*;q=0.8"},
+			http.StatusOK, avifType},
+		{"WebP accepted", []string{"image/webp,*/*;q=0.8"}, http.StatusOK, webpType},
+		{"no Accept", nil, http.StatusOK, jpegType},
+		{"two Accept lines", []string{"image/png", webpType}, http.StatusOK, webpType},
+		{"none of the three", []string{"image/gif"},
+			http.StatusNotAcceptable, jsonType},
+		{"not valid", []string{"image/avif;q=high"}, http.StatusBadRequest, jsonType},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			for _, target := range []string{signedURL, encryptedURL} {
+				rec := requestImage(t, srv, http.MethodGet, target, tt.accept...)
+				gotType := rec.Header().Get("Content-Type")
+
+				if rec.Code != tt.wantStatus || gotType != tt.wantType {
+					t.Errorf("%s: %d %s, want %d %s; body %s", target,
+						rec.Code, gotType, tt.wantStatus, tt.wantType, rec.Body)
+				}
+
+				if !slices.Contains(rec.Header().Values("Vary"), "Accept") {
+					t.Errorf("%s: Vary = %v, want Accept in it",
+						target, rec.Header().Values("Vary"))
+				}
+			}
+		})
+	}
+}
+
+// TestFormatAuto_SignatureCoversAuto verifies that a /v1/image/ URL with the
+// format auto is checked against a signature for auto, not for the format
+// chosen: a URL signed for avif, with auto put in its path, is refused for a
+// client whose Accept chooses AVIF.
+func TestFormatAuto_SignatureCoversAuto(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	signedForAVIF, err := h.imgSvc.GenerateSignedURL("", &imgcache.ImageRequest{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Size:       imgcache.Size{Width: 50, Height: 50},
+		Format:     imgcache.FormatAVIF,
+	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
+
+	target := strings.Replace(signedForAVIF, "/50x50.avif?", "/50x50.auto?", 1)
+	if target == signedForAVIF {
+		t.Fatalf("no /50x50.avif? in %s", signedForAVIF)
+	}
+
+	rec := requestImage(t, srv, http.MethodGet, target, avifType)
+	if rec.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want %d", rec.Code, http.StatusUnauthorized)
+	}
+}
+
+// TestFormatAuto_CachesEachFormatApart requests an auto URL for AVIF, then
+// JPEG, then both again. Each format is processed once and then served from
+// the cache, with an ETag of its own, so a client never gets the other format
+// from the cache.
+func TestFormatAuto_CachesEachFormatApart(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	signedURL, _ := autoPhotoURLs(t, h)
+
+	steps := []struct {
+		wantType  string
+		wantCache string
+	}{
+		{avifType, "MISS"},
+		{jpegType, "MISS"},
+		{avifType, "HIT"},
+		{jpegType, "HIT"},
+	}
+
+	etags := make(map[string]string)
+
+	for _, step := range steps {
+		rec := requestImage(t, srv, http.MethodGet, signedURL, step.wantType)
+		gotType := rec.Header().Get("Content-Type")
+		gotCache := rec.Header().Get("X-Pixa-Cache")
+
+		if rec.Code != http.StatusOK || gotType != step.wantType ||
+			gotCache != step.wantCache {
+			t.Fatalf("Accept %s: %d %s %s, want 200 %s %s", step.wantType,
+				rec.Code, gotType, gotCache, step.wantType, step.wantCache)
+		}
+
+		etag := rec.Header().Get("ETag")
+		if previous, seen := etags[gotType]; seen && previous != etag {
+			t.Errorf("%s ETag changed from %s to %s", gotType, previous, etag)
+		}
+
+		etags[gotType] = etag
+	}
+
+	if etags[avifType] == etags[jpegType] {
+		t.Errorf("AVIF and JPEG have the same ETag %s", etags[avifType])
+	}
+}
+
+// TestFormatAuto_Vary verifies that on each image route a HEAD answer and a
+// 304 for an auto URL carry Vary: Accept, and that the answer for a URL with
+// a fixed format does not.
+func TestFormatAuto_Vary(t *testing.T) {
+	t.Parallel()
+
+	h, _ := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	srv := chi.NewRouter()
+	srv.Get("/v1/image/*", h.HandleImage())
+	srv.Head("/v1/image/*", h.HandleImage())
+	srv.Get("/v1/e/{token}/*", h.HandleImageEnc())
+	srv.Head("/v1/e/{token}/*", h.HandleImageEnc())
+
+	signedURL, encryptedURL := autoPhotoURLs(t, h)
+
+	for _, urls := range [][2]string{
+		{signedURL, signedPhotoURL(t, h)},
+		{encryptedURL, encPhotoURL(t, h)},
+	} {
+		autoURL, fixedURL := urls[0], urls[1]
+
+		head := requestImage(t, srv, http.MethodHead, autoURL, webpType)
+		checkVaryAccept(t, head, http.StatusOK, true)
+
+		req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+			autoURL, nil)
+		req.Header.Set("Accept", webpType)
+		req.Header.Set("If-None-Match", head.Header().Get("ETag"))
+
+		notModified := httptest.NewRecorder()
+		srv.ServeHTTP(notModified, req)
+		checkVaryAccept(t, notModified, http.StatusNotModified, true)
+
+		fixed := requestImage(t, srv, http.MethodGet, fixedURL)
+		checkVaryAccept(t, fixed, http.StatusOK, false)
+	}
+}
+
+// checkVaryAccept fails the test unless rec answered wantStatus and, as
+// wantVary says, has or has not Accept in its Vary header.
+func checkVaryAccept(
+	t *testing.T, rec *httptest.ResponseRecorder, wantStatus int, wantVary bool,
+) {
+	t.Helper()
+
+	vary := rec.Header().Values("Vary")
+	t.Logf("status %d, Vary %v", rec.Code, vary)
+
+	if rec.Code != wantStatus {
+		t.Errorf("status = %d, want %d", rec.Code, wantStatus)
+	}
+
+	if slices.Contains(vary, "Accept") != wantVary {
+		t.Errorf("Vary = %v, want Accept in it: %v", vary, wantVary)
+	}
+}

internal/handlers/handlers.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"go.uber.org/fx"
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/config"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/encurl"
@@ -27,6 +28,11 @@ type Params struct {
 	Healthcheck *healthcheck.Healthcheck
 	Database    *database.Database
 	Config      *config.Config
+
+	// Fetcher, when provided, fetches upstream images in place of the
+	// fetcher the handlers build from the config. Only tests provide one;
+	// pixad does not.
+	Fetcher httpfetcher.Fetcher `optional:"true"`
 }
 
 // Handlers provides HTTP request handlers.
@@ -35,11 +41,16 @@ type Handlers struct {
 	hc          *healthcheck.Healthcheck
 	db          *database.Database
 	config      *config.Config
+	fetcher     httpfetcher.Fetcher
 	imgSvc      *imgcache.Service
 	imgCache    *imgcache.Cache
 	sessMgr     *session.Manager
 	encGen      *encurl.Generator
 	csrfProtect func(http.Handler) http.Handler
+
+	// refererBlocklist matches the hosts of referer_blocklist; its IsAllowed
+	// reports whether a URL's host is on that list.
+	refererBlocklist *allowlist.HostAllowList
 }
 
 // New creates a new Handlers instance.
@@ -50,49 +61,64 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 	}
 
 	s := &Handlers{
-		log:         params.Logger.Get(),
-		hc:          params.Healthcheck,
-		db:          params.Database,
-		config:      params.Config,
-		csrfProtect: csrfProtect,
+		log:              params.Logger.Get(),
+		hc:               params.Healthcheck,
+		db:               params.Database,
+		config:           params.Config,
+		fetcher:          params.Fetcher,
+		csrfProtect:      csrfProtect,
+		refererBlocklist: allowlist.New(params.Config.RefererBlocklist),
 	}
 
 	lc.Append(fx.Hook{
-		// The eviction goroutine must outlive OnStart, so it cannot
-		// inherit this hook's context. It makes its own instead, which
-		// leaves it uncancellable: an in-flight pass runs to completion
-		// during OnStop regardless of the shutdown deadline. Making the
-		// loop cancellable changes shutdown semantics and is tracked
-		// separately in issue #102, rather than being folded into the
-		// lint-conformance change that surfaced it.
-		//nolint:contextcheck // see issue #102
+		//nolint:contextcheck // the eviction loop outlives OnStart; OnStop cancels it
 		OnStart: func(_ context.Context) error {
 			return s.initImageService()
 		},
-		OnStop: func(_ context.Context) error {
-			if s.imgCache != nil {
-				s.imgCache.StopEviction()
+		OnStop: func(ctx context.Context) error {
+			if s.imgCache == nil {
+				return nil
 			}
 
-			return nil
+			return s.imgCache.StopEviction(ctx)
 		},
 	})
 
 	return s, nil
 }
 
+// WaitForProcessing waits until no image is being processed, or until ctx
+// ends, and returns how many images were still being processed then.
+func (s *Handlers) WaitForProcessing(ctx context.Context) int {
+	return s.imgSvc.WaitForProcessing(ctx)
+}
+
+// WaitForCountWrites waits until every count a request has started writing
+// to the database is written, or until ctx ends, and reports whether they
+// all were.
+func (s *Handlers) WaitForCountWrites(ctx context.Context) bool {
+	return s.imgSvc.WaitForCountWrites(ctx)
+}
+
+// newCacheConfig builds the image cache's configuration from cfg.
+// cache_max_bytes: 0 disables the disk cache entirely; any other value
+// is the eviction limit in bytes; when it is omitted, the cache works
+// out the default limit itself.
+func newCacheConfig(cfg *config.Config, log *slog.Logger) imgcache.CacheConfig {
+	return imgcache.CacheConfig{
+		StateDir:           cfg.StateDir,
+		CacheTTL:           imgcache.DefaultCacheTTL,
+		NegativeTTL:        imgcache.DefaultNegativeTTL,
+		MaxBytes:           cfg.CacheMaxBytes,
+		UseDefaultMaxBytes: !cfg.CacheMaxBytesExplicit,
+		DisableDiskCache:   cfg.CacheMaxBytesExplicit && cfg.CacheMaxBytes == 0,
+		Logger:             log,
+	}
+}
+
 // initImageService initializes the image cache and service.
 func (s *Handlers) initImageService() error {
-	// Create the cache. cache_max_bytes: 0 disables the disk cache
-	// entirely; any other value is the eviction limit in bytes.
-	cache, err := imgcache.NewCache(s.db.DB(), imgcache.CacheConfig{
-		StateDir:         s.config.StateDir,
-		CacheTTL:         imgcache.DefaultCacheTTL,
-		NegativeTTL:      imgcache.DefaultNegativeTTL,
-		MaxBytes:         s.config.CacheMaxBytes,
-		DisableDiskCache: s.config.CacheMaxBytes == 0,
-		Logger:           s.log,
-	})
+	cache, err := imgcache.NewCache(s.db.DB(), newCacheConfig(s.config, s.log))
 	if err != nil {
 		return err
 	}
@@ -116,10 +142,12 @@ func (s *Handlers) initImageService() error {
 	fetcherCfg.MaxConnections = s.config.UpstreamConnections
 	fetcherCfg.BlockedNetworks = s.config.BlockedNetworks
 
-	// Create the service
+	// Create the service. With no fetcher provided, it builds its own from
+	// fetcherCfg.
 	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
 		Cache:                   cache,
 		FetcherConfig:           fetcherCfg,
+		Fetcher:                 s.fetcher,
 		SigningKey:              s.config.SigningKey,
 		Allowlist:               s.config.AllowlistHosts,
 		MaxConcurrentProcessing: s.config.MaxConcurrentProcessing,

internal/handlers/image.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
@@ -17,9 +18,14 @@ import (
 )
 
 // HandleImage handles the main image proxy route:
-// /v1/image/<host>/<path>/<width>x<height>.<format>
+// /v1/image/<host>/<path>/<width>x<height>.<format>, or with no format
+// /v1/image/<host>/<path>/<width>x<height>
 func (s *Handlers) HandleImage() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
+		if s.refuseBlockedReferer(w, r) {
+			return
+		}
+
 		req, ok := s.parseImageRequest(w, r)
 		if !ok {
 			return
@@ -38,6 +44,11 @@ func (s *Handlers) HandleImage() http.HandlerFunc {
 			return
 		}
 
+		// The signature covers the format auto, not the format chosen
+		if !s.chooseAutoFormat(w, r, req) {
+			return
+		}
+
 		// Get cache key for logging
 		cacheKey := imgcache.CacheKey(req)
 
@@ -247,6 +258,42 @@ func cacheControl(expires time.Time) string {
 	return fmt.Sprintf("public, max-age=%d, immutable", int64(maxAge/time.Second))
 }
 
+// refuseBlockedReferer answers 403 with a JSON error when the request's Referer
+// names a host on referer_blocklist, and reports whether it answered. A request
+// with no Referer, or one that does not parse as a URL with a host, is not
+// refused.
+func (s *Handlers) refuseBlockedReferer(
+	w http.ResponseWriter, r *http.Request,
+) bool {
+	referer, err := url.Parse(r.Referer())
+	if err != nil || !s.refererBlocklist.IsAllowed(referer) {
+		return false
+	}
+
+	s.respondError(w, "referer blocked", http.StatusForbidden)
+
+	return true
+}
+
+// notModified sets the ETag header to etag and, when the request's
+// If-None-Match is that ETag, answers 304 Not Modified. It reports whether it
+// answered. An empty etag sets no header and never answers.
+func notModified(w http.ResponseWriter, r *http.Request, etag string) bool {
+	if etag == "" {
+		return false
+	}
+
+	w.Header().Set("ETag", etag)
+
+	if r.Header.Get("If-None-Match") != etag {
+		return false
+	}
+
+	w.WriteHeader(http.StatusNotModified)
+
+	return true
+}
+
 // writeImageResponse writes headers and streams the image content,
 // handling conditional and HEAD requests.
 func (s *Handlers) writeImageResponse(
@@ -265,17 +312,8 @@ func (s *Handlers) writeImageResponse(
 	w.Header().Set("Cache-Control", cacheControl(req.Expires))
 	w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
-	if resp.ETag != "" {
-		w.Header().Set("ETag", resp.ETag)
-
-		// Check for conditional request (If-None-Match)
-		if ifNoneMatch := r.Header.Get("If-None-Match"); ifNoneMatch != "" {
-			if ifNoneMatch == resp.ETag {
-				w.WriteHeader(http.StatusNotModified)
-
-				return
-			}
-		}
+	if notModified(w, r, resp.ETag) {
+		return
 	}
 
 	// Handle HEAD request - return headers only
@@ -298,6 +336,7 @@ func (s *Handlers) writeImageResponse(
 	// Log cache status and timing after serving
 	duration := time.Since(startTime)
 	s.log.Info("image served",
+		"request_id", middleware.GetReqID(r.Context()),
 		"cache_key", cacheKey,
 		"cache_status", resp.CacheStatus,
 		"duration_ms", duration.Milliseconds(),

internal/handlers/image_cache_control_internal_test.go

@@ -23,8 +23,10 @@ const photoPath = "/images/photo.jpg"
 // newSignedHostServer returns a router for both image routes, and the Handlers
 // behind it, whose fetcher serves a JPEG at photoPath on signedHost. signedHost
 // is not on the allowlist, so a /v1/image/ URL for it is served only with a
-// valid signature.
-func newSignedHostServer(t *testing.T) (*Handlers, http.Handler) {
+// valid signature. The handlers and the image service log to log.
+func newSignedHostServer(
+	t *testing.T, log *slog.Logger,
+) (*Handlers, http.Handler) {
 	t.Helper()
 
 	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
@@ -44,6 +46,7 @@ func newSignedHostServer(t *testing.T) (*Handlers, http.Handler) {
 			signedHost + photoPath: &fstest.MapFile{Data: jpegData},
 		}),
 		SigningKey: testSigningKey,
+		Logger:     log,
 	})
 	if err != nil {
 		t.Fatalf("imgcache.NewService() error = %v", err)
@@ -55,7 +58,7 @@ func newSignedHostServer(t *testing.T) (*Handlers, http.Handler) {
 	}
 
 	h := &Handlers{
-		log:    slog.New(slog.DiscardHandler),
+		log:    log,
 		imgSvc: svc,
 		encGen: encGen,
 	}
@@ -103,7 +106,7 @@ func getMaxAge(t *testing.T, srv http.Handler, target string) int {
 func TestHandleImage_SignedURL_MaxAgeEndsAtExp(t *testing.T) {
 	t.Parallel()
 
-	h, srv := newSignedHostServer(t)
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
 
 	signedURL, err := h.imgSvc.GenerateSignedURL("", &imgcache.ImageRequest{
 		SourceHost: signedHost,
@@ -179,7 +182,7 @@ func TestHandleImageEnc_MaxAge(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			h, srv := newSignedHostServer(t)
+			h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
 
 			token, err := h.encGen.Generate(&encurl.Payload{
 				SourceHost: signedHost,

internal/handlers/image_errors_internal_test.go

@@ -0,0 +1,267 @@
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"image/color"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
+)
+
+// allowlistedHost is the only host on the allowlist of the image route
+// newImageRoute builds.
+const allowlistedHost = "allowed.example.com"
+
+// newImageRoute returns the image route of a Handlers whose service fetches
+// with fetcher and checks signatures with testSigningKey.
+func newImageRoute(t *testing.T, fetcher httpfetcher.Fetcher) http.Handler {
+	t.Helper()
+
+	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
+		StateDir:    t.TempDir(),
+		CacheTTL:    time.Hour,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("failed to create cache: %v", err)
+	}
+
+	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
+		Cache:      cache,
+		Fetcher:    fetcher,
+		SigningKey: testSigningKey,
+		Allowlist:  []string{allowlistedHost},
+	})
+	if err != nil {
+		t.Fatalf("failed to create service: %v", err)
+	}
+
+	h := &Handlers{imgSvc: svc, log: slog.New(slog.DiscardHandler)}
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", h.HandleImage())
+
+	return r
+}
+
+// newPhotoFetcher returns a mock fetcher that serves a JPEG at photoPath on
+// each of hosts, and answers any other URL with an upstream error.
+func newPhotoFetcher(t *testing.T, hosts ...string) *httpfetcher.MockFetcher {
+	t.Helper()
+
+	photo := &fstest.MapFile{
+		Data: generateTestJPEG(t, 100, 100, color.RGBA{255, 0, 0, 255}),
+	}
+
+	files := fstest.MapFS{}
+	for _, host := range hosts {
+		files[host+photoPath] = photo
+	}
+
+	return httpfetcher.NewMock(files)
+}
+
+// photoURL returns the image route URL of photoPath on host, as a 50x50 JPEG.
+func photoURL(host string) string {
+	return "/v1/image/" + host + photoPath + "/50x50.jpeg"
+}
+
+// photoURLWithSig returns photoURL(host) with sig and expires as its sig and
+// exp.
+func photoURLWithSig(host, sig string, expires time.Time) string {
+	return fmt.Sprintf("%s?sig=%s&exp=%d", photoURL(host), sig, expires.Unix())
+}
+
+// photoSignature returns the signature of photoURL(host) at the default
+// quality and fit, made with key and expiring at expires.
+func photoSignature(key, host string, expires time.Time) string {
+	return signature.New(key).Sign(&signature.Request{
+		SourceHost: host,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+		Format:     string(imgcache.FormatJPEG),
+		Quality:    85,
+		FitMode:    string(imgcache.FitCover),
+		Expires:    expires,
+	})
+}
+
+// sendGet sends a GET for target to route and returns the response.
+func sendGet(
+	t *testing.T, route http.Handler, target string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, target, nil)
+	rec := httptest.NewRecorder()
+
+	route.ServeHTTP(rec, req)
+	t.Logf("GET %s: %d", target, rec.Code)
+
+	return rec
+}
+
+// checkErrorBody checks that rec has status wantStatus and the JSON error body
+// the image route sends: wantError, wantStatus and the time in RFC 3339.
+func checkErrorBody(
+	t *testing.T, rec *httptest.ResponseRecorder, wantStatus int, wantError string,
+) {
+	t.Helper()
+
+	if rec.Code != wantStatus {
+		t.Errorf("status = %d, want %d", rec.Code, wantStatus)
+	}
+
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+
+	var body struct {
+		Error     string `json:"error"`
+		Status    int    `json:"status"`
+		Timestamp string `json:"timestamp"`
+	}
+
+	err := json.NewDecoder(rec.Body).Decode(&body)
+	if err != nil {
+		t.Fatalf("decoding response body: %v", err)
+	}
+
+	if body.Error != wantError || body.Status != wantStatus {
+		t.Errorf("body error and status = %q %d, want %q %d",
+			body.Error, body.Status, wantError, wantStatus)
+	}
+
+	_, err = time.Parse(time.RFC3339, body.Timestamp)
+	if err != nil {
+		t.Errorf("body timestamp: %v", err)
+	}
+}
+
+// TestHandleImage_ErrorAnswers checks the status and the JSON error body the
+// image route answers each request below with. The JPEG at photoPath exists on
+// signedHost and on each host below that differs from it, so a request refused
+// with 401 would otherwise be served.
+func TestHandleImage_ErrorAnswers(t *testing.T) {
+	t.Parallel()
+
+	// A signature for signedHost must not verify for any of these.
+	parentHost := "example.com"
+	siblingHost := "other.example.com"
+	subdomainHost := "img." + signedHost
+	appendedHost := signedHost + ".example.net"
+
+	photos := newPhotoFetcher(t,
+		signedHost, parentHost, siblingHost, subdomainHost, appendedHost)
+	// The real fetcher refuses localhost before any lookup or connection.
+	realFetcher := httpfetcher.New(httpfetcher.DefaultConfig())
+
+	exp := time.Now().Add(time.Hour)
+	expired := time.Now().Add(-time.Hour)
+	sig := photoSignature(testSigningKey, signedHost, exp)
+	otherKeySig := photoSignature("another-signing-key", signedHost, exp)
+	expiredSig := photoSignature(testSigningKey, signedHost, expired)
+	localhostSig := photoSignature(testSigningKey, "localhost", exp)
+
+	// The error every request refused for its signature gets.
+	const unauthorized = "unauthorized"
+
+	tests := []struct {
+		name       string
+		fetcher    httpfetcher.Fetcher
+		target     string
+		wantStatus int
+		wantError  string
+	}{
+		{"no sig or exp", photos, photoURL(signedHost),
+			http.StatusUnauthorized, unauthorized},
+		{"exp but no sig", photos,
+			fmt.Sprintf("%s?exp=%d", photoURL(signedHost), exp.Unix()),
+			http.StatusUnauthorized, unauthorized},
+		{"sig made with another key", photos,
+			photoURLWithSig(signedHost, otherKeySig, exp),
+			http.StatusUnauthorized, unauthorized},
+		{"sig without its = padding", photos,
+			photoURLWithSig(signedHost, strings.TrimRight(sig, "="), exp),
+			http.StatusUnauthorized, unauthorized},
+		{"sig in upper case", photos,
+			photoURLWithSig(signedHost, strings.ToUpper(sig), exp),
+			http.StatusUnauthorized, unauthorized},
+		{"expired sig", photos, photoURLWithSig(signedHost, expiredSig, expired),
+			http.StatusUnauthorized, unauthorized},
+		{"sig sent for the parent domain", photos,
+			photoURLWithSig(parentHost, sig, exp),
+			http.StatusUnauthorized, unauthorized},
+		{"sig sent for a sibling host", photos,
+			photoURLWithSig(siblingHost, sig, exp),
+			http.StatusUnauthorized, unauthorized},
+		{"sig sent for a subdomain", photos,
+			photoURLWithSig(subdomainHost, sig, exp),
+			http.StatusUnauthorized, unauthorized},
+		{"sig sent with another domain appended", photos,
+			photoURLWithSig(appendedHost, sig, exp),
+			http.StatusUnauthorized, unauthorized},
+		{"unparseable path", photos,
+			"/v1/image/" + allowlistedHost + photoPath + "/big.jpeg",
+			http.StatusBadRequest, "invalid image URL: invalid size format"},
+		{"blocked upstream address", realFetcher,
+			photoURLWithSig("localhost", localhostSig, exp),
+			http.StatusForbidden, "forbidden"},
+		{"upstream error", photos,
+			"/v1/image/" + allowlistedHost + "/images/missing.jpg/50x50.jpeg",
+			http.StatusBadGateway, "upstream error"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := sendGet(t, newImageRoute(t, tt.fetcher), tt.target)
+			checkErrorBody(t, rec, tt.wantStatus, tt.wantError)
+		})
+	}
+}
+
+// TestHandleImage_AllowlistOrSignature checks that the image route serves an
+// image without a signature for a host on the allowlist only, and for another
+// host only with a valid signature.
+func TestHandleImage_AllowlistOrSignature(t *testing.T) {
+	t.Parallel()
+
+	photos := newPhotoFetcher(t, allowlistedHost, signedHost)
+	exp := time.Now().Add(time.Hour)
+	sig := photoSignature(testSigningKey, signedHost, exp)
+
+	tests := []struct {
+		name       string
+		target     string
+		wantStatus int
+	}{
+		{"allowlisted host, no sig", photoURL(allowlistedHost), http.StatusOK},
+		{"other host, no sig", photoURL(signedHost), http.StatusUnauthorized},
+		{"other host, valid sig", photoURLWithSig(signedHost, sig, exp),
+			http.StatusOK},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := sendGet(t, newImageRoute(t, photos), tt.target)
+			if rec.Code != tt.wantStatus {
+				t.Errorf("status = %d, want %d", rec.Code, tt.wantStatus)
+			}
+		})
+	}
+}

internal/handlers/imageenc.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
 
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
@@ -21,46 +22,15 @@ import (
 // browsers identify the content type.
 func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
+		if s.refuseBlockedReferer(w, r) {
+			return
+		}
+
 		ctx := r.Context()
 		start := time.Now()
 
-		// Extract token from URL
-		token := chi.URLParam(r, "token")
-		if token == "" {
-			s.respondError(w, "missing token", http.StatusBadRequest)
-
-			return
-		}
-
-		// Decrypt and validate the payload
-		payload, err := s.encGen.Parse(token)
-		if err != nil {
-			if errors.Is(err, encurl.ErrExpired) {
-				s.log.Debug("encrypted URL expired", "error", err)
-				s.respondError(w, "URL has expired", http.StatusGone)
-
-				return
-			}
-
-			s.log.Debug("failed to decrypt URL", "error", err)
-			s.respondError(w, "invalid encrypted URL", http.StatusBadRequest)
-
-			return
-		}
-
-		// Convert payload to ImageRequest
-		req := payload.ToImageRequest()
-
-		// Apply the same dimension and fit-mode bounds as the plain image
-		// route: a sealed payload is trusted for its origin, not for staying
-		// within limits, so an over-limit size or unknown fit mode is a 400
-		// here rather than an out-of-memory or a 500 from the processor.
-		err = imgcache.ValidateImageRequest(req)
-		if err != nil {
-			s.log.Debug("encrypted URL failed validation", "error", err)
-			s.respondError(w, "invalid encrypted URL: "+err.Error(),
-				http.StatusBadRequest)
-
+		req, ok := s.parseImageEncRequest(w, r)
+		if !ok || !s.chooseAutoFormat(w, r, req) {
 			return
 		}
 
@@ -94,6 +64,17 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		w.Header().Set("Cache-Control", cacheControl(req.Expires))
 		w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
+		if notModified(w, r, resp.ETag) {
+			return
+		}
+
+		// A HEAD request gets the headers only
+		if r.Method == http.MethodHead {
+			w.WriteHeader(http.StatusOK)
+
+			return
+		}
+
 		// Stream the response
 		written, err := io.Copy(w, resp.Content)
 		if err != nil {
@@ -105,6 +86,7 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		// Log completion
 		duration := time.Since(start)
 		s.log.Info("image served",
+			"request_id", middleware.GetReqID(ctx),
 			"cache_key", imgcache.CacheKey(req),
 			"host", req.SourceHost,
 			"path", req.SourcePath,
@@ -116,6 +98,56 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 	}
 }
 
+// parseImageEncRequest decrypts the token of an encrypted image URL into an
+// ImageRequest and checks it. On a token that is missing, does not decrypt,
+// has expired or asks for something not valid, it writes an error response
+// and returns false.
+func (s *Handlers) parseImageEncRequest(
+	w http.ResponseWriter, r *http.Request,
+) (*imgcache.ImageRequest, bool) {
+	// Extract token from URL
+	token := chi.URLParam(r, "token")
+	if token == "" {
+		s.respondError(w, "missing token", http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Decrypt and validate the payload
+	payload, err := s.encGen.Parse(token)
+	if err != nil {
+		if errors.Is(err, encurl.ErrExpired) {
+			s.log.Debug("encrypted URL expired", "error", err)
+			s.respondError(w, "URL has expired", http.StatusGone)
+
+			return nil, false
+		}
+
+		s.log.Debug("failed to decrypt URL", "error", err)
+		s.respondError(w, "invalid encrypted URL", http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Convert payload to ImageRequest
+	req := payload.ToImageRequest()
+
+	// Apply the same dimension and fit-mode bounds as the plain image
+	// route: a sealed payload is trusted for its origin, not for staying
+	// within limits, so an over-limit size or unknown fit mode is a 400
+	// here rather than an out-of-memory or a 500 from the processor.
+	err = imgcache.ValidateImageRequest(req)
+	if err != nil {
+		s.log.Debug("encrypted URL failed validation", "error", err)
+		s.respondError(w, "invalid encrypted URL: "+err.Error(),
+			http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	return req, true
+}
+
 // handleImageError converts image service errors to HTTP responses.
 func (s *Handlers) handleImageError(w http.ResponseWriter, err error) {
 	switch {

internal/handlers/imageenc_internal_test.go

@@ -96,3 +96,70 @@ func TestHandleImageEnc_InvalidFitMode_Returns400(t *testing.T) {
 		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
 	}
 }
+
+// TestHandleImageEnc_IfNoneMatch_Returns304 verifies that an image served
+// through an encrypted URL carries an ETag, and that a request whose
+// If-None-Match is that ETag is answered 304 Not Modified with no body.
+func TestHandleImageEnc_IfNoneMatch_Returns304(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	target := encPhotoURL(t, h)
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, target, nil))
+
+	etag := rec.Header().Get("ETag")
+	t.Logf("GET: %d, ETag %q", rec.Code, etag)
+
+	if rec.Code != http.StatusOK || etag == "" {
+		t.Fatalf("GET: status = %d, ETag = %q, want %d and an ETag",
+			rec.Code, etag, http.StatusOK)
+	}
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, target, nil)
+	req.Header.Set("If-None-Match", etag)
+
+	rec = httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+	t.Logf("GET with If-None-Match: %d, %d body bytes", rec.Code, rec.Body.Len())
+
+	if rec.Code != http.StatusNotModified || rec.Body.Len() != 0 {
+		t.Errorf("status = %d with %d body bytes, want %d with none",
+			rec.Code, rec.Body.Len(), http.StatusNotModified)
+	}
+}
+
+// TestHandleImageEnc_HEAD_ReturnsHeadersOnly verifies that HEAD on an
+// encrypted URL is answered 200 with the headers GET sends and no body.
+func TestHandleImageEnc_HEAD_ReturnsHeadersOnly(t *testing.T) {
+	t.Parallel()
+
+	h, _ := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	r := chi.NewRouter()
+	r.Head("/v1/e/{token}/*", h.HandleImageEnc())
+
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodHead, encPhotoURL(t, h), nil))
+	t.Logf("HEAD: %d, headers %v, %d body bytes",
+		rec.Code, rec.Header(), rec.Body.Len())
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	for _, name := range []string{
+		"Content-Type", "Content-Length", "Cache-Control", "ETag",
+	} {
+		if rec.Header().Get(name) == "" {
+			t.Errorf("HEAD response has no %s", name)
+		}
+	}
+
+	if rec.Body.Len() != 0 {
+		t.Errorf("HEAD response body has %d bytes, want none", rec.Body.Len())
+	}
+}

internal/handlers/imageenc_token_internal_test.go

@@ -0,0 +1,126 @@
+package handlers
+
+import (
+	"image/jpeg"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+)
+
+// requireServedPhoto requires that rec answers 200 with the JPEG at photoPath
+// on signedHost at the 50x50 that encPhotoURL and the generator tests ask for.
+func requireServedPhoto(t *testing.T, rec *httptest.ResponseRecorder) {
+	t.Helper()
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d; body %q",
+			rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	contentType := rec.Header().Get("Content-Type")
+	if contentType != "image/jpeg" {
+		t.Errorf("Content-Type = %q, want image/jpeg", contentType)
+	}
+
+	img, err := jpeg.DecodeConfig(rec.Body)
+	if err != nil {
+		t.Fatalf("body is not a JPEG: %v", err)
+	}
+
+	if img.Width != 50 || img.Height != 50 {
+		t.Errorf("image is %dx%d, want 50x50", img.Width, img.Height)
+	}
+}
+
+// TestHandleImageEnc_ValidToken_ServesImage verifies that a token made with
+// the signing key serves the image it asks for.
+func TestHandleImageEnc_ValidToken_ServesImage(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, encPhotoURL(t, h), nil))
+
+	requireServedPhoto(t, rec)
+}
+
+// TestHandleImageEnc_RejectedToken verifies that a token that has expired
+// answers 410, and that a token with one character changed, a token cut
+// short, and a token made with another signing key answer 400. The server
+// would serve the photo for a token it accepted.
+func TestHandleImageEnc_RejectedToken(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	photo := encurl.Payload{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+	}
+
+	valid, err := h.encGen.Generate(&photo)
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	expiredPhoto := photo
+	expiredPhoto.ExpiresAt = time.Now().Add(-time.Minute).Unix()
+
+	expired, err := h.encGen.Generate(&expiredPhoto)
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	otherGen, err := encurl.NewGenerator("another-signing-key-fedcba9876543210")
+	if err != nil {
+		t.Fatalf("encurl.NewGenerator() error = %v", err)
+	}
+
+	otherKey, err := otherGen.Generate(&photo)
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	// Changing a character in the middle always changes the decoded bytes;
+	// the last character of unpadded base64 can carry unused bits.
+	middle := len(valid) / 2
+
+	replacement := "A"
+	if valid[middle] == 'A' {
+		replacement = "B"
+	}
+
+	changed := valid[:middle] + replacement + valid[middle+1:]
+
+	tests := []struct {
+		name       string
+		token      string
+		wantStatus int
+	}{
+		{"expired", expired, http.StatusGone},
+		{"one character changed", changed, http.StatusBadRequest},
+		{"cut short", valid[:middle], http.StatusBadRequest},
+		{"another signing key", otherKey, http.StatusBadRequest},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := getEncToken(srv, tt.token)
+			t.Logf("GET /v1/e/%s/img.jpg: %d %s", tt.token, rec.Code, rec.Body)
+
+			if rec.Code != tt.wantStatus {
+				t.Errorf("status = %d, want %d", rec.Code, tt.wantStatus)
+			}
+		})
+	}
+}

internal/handlers/jpegxl_default_internal_test.go

@@ -0,0 +1,162 @@
+package handlers
+
+import (
+	"fmt"
+	"log/slog"
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/davidbyttow/govips/v2/vips"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
+)
+
+// requireJPEGXL requires that rec answers 200 with a JPEG XL image.
+func requireJPEGXL(t *testing.T, rec *httptest.ResponseRecorder) {
+	t.Helper()
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d; body %q",
+			rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	if got := rec.Header().Get("Content-Type"); got != jxlType {
+		t.Errorf("Content-Type = %q, want %s", got, jxlType)
+	}
+
+	if got := vips.DetermineImageType(rec.Body.Bytes()); got != vips.ImageTypeJXL {
+		t.Errorf("body is %s, want jxl", vips.ImageTypes[got])
+	}
+}
+
+// TestImageWithoutFormat_ServesJPEGXL verifies that a /v1/image/ URL whose
+// last segment is a size with no format, 50x50 or orig, answers JPEG XL.
+func TestImageWithoutFormat_ServesJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	route := newImageRoute(t, newPhotoFetcher(t, allowlistedHost))
+
+	for _, size := range []string{"50x50", "orig"} {
+		target := "/v1/image/" + allowlistedHost + photoPath + "/" + size
+		requireJPEGXL(t, sendGet(t, route, target))
+	}
+}
+
+// TestImageWithoutFormat_SignedAsJXL verifies that a /v1/image/ URL with no
+// format is signed as jxl: the signature made for the URL ending in .jxl is
+// accepted for the same URL without .jxl.
+func TestImageWithoutFormat_SignedAsJXL(t *testing.T) {
+	t.Parallel()
+
+	route := newImageRoute(t, newPhotoFetcher(t, signedHost))
+	expires := time.Now().Add(time.Hour)
+
+	sig := signature.New(testSigningKey).Sign(&signature.Request{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+		Format:     string(imgcache.FormatJXL),
+		Quality:    encurl.DefaultQuality,
+		FitMode:    string(imgcache.FitCover),
+		Expires:    expires,
+	})
+	query := fmt.Sprintf("?sig=%s&exp=%d", sig, expires.Unix())
+
+	for _, size := range []string{"50x50.jxl", "50x50"} {
+		target := "/v1/image/" + signedHost + photoPath + "/" + size + query
+		requireJPEGXL(t, sendGet(t, route, target))
+	}
+}
+
+// TestImageEncWithoutFormat_ServesJPEGXL verifies that an encrypted URL whose
+// token holds no format answers JPEG XL.
+func TestImageEncWithoutFormat_ServesJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	token, err := h.encGen.Generate(&encurl.Payload{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+	})
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	requireJPEGXL(t, getEncToken(srv, token))
+}
+
+// TestGeneratorPage_SelectsJPEGXL verifies that the generator page's format
+// choice is JPEG XL until another is chosen.
+func TestGeneratorPage_SelectsJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newCSRFTestRouter(t)
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", nil)
+	req.AddCookie(newSessionCookie(t, h))
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	if !strings.Contains(rec.Body.String(), `<option value="jxl" selected>`) {
+		t.Errorf("generator page does not select JPEG XL: %s", rec.Body.String())
+	}
+}
+
+// TestGeneratePost_NoFormat_MakesJPEGXLURL verifies that the generator form
+// sent with an empty format field, or with none, makes a URL whose name ends
+// in .jxl and which answers JPEG XL.
+func TestGeneratePost_NoFormat_MakesJPEGXLURL(t *testing.T) {
+	t.Parallel()
+
+	photo := url.Values{
+		sourceURLField: {"https://" + signedHost + photoPath},
+		widthField:     {"50"},
+		heightField:    {"50"},
+	}
+
+	emptyFormat := maps.Clone(photo)
+	emptyFormat.Set(formatField, "")
+
+	for name, form := range map[string]url.Values{
+		"empty format field": emptyFormat,
+		"no format field":    photo,
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			_, imageSrv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+			rec := generatePost(t, form)
+
+			match := generatedURLPattern.FindStringSubmatch(rec.Body.String())
+			if match == nil {
+				t.Fatalf("generator page shows no URL: %d %s",
+					rec.Code, rec.Body.String())
+			}
+
+			t.Logf("generated URL path: %s", match[1])
+
+			if !strings.HasSuffix(match[1], "/img.jxl") {
+				t.Errorf("generated URL %s does not end in /img.jxl", match[1])
+			}
+
+			imageRec := httptest.NewRecorder()
+			imageSrv.ServeHTTP(imageRec, httptest.NewRequestWithContext(
+				t.Context(), http.MethodGet, match[1], nil))
+
+			requireJPEGXL(t, imageRec)
+		})
+	}
+}

internal/handlers/jpegxl_internal_test.go

@@ -0,0 +1,73 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+	"testing"
+
+	"github.com/davidbyttow/govips/v2/vips"
+
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// jxlType is the content type of JPEG XL.
+const jxlType = "image/jxl"
+
+// TestFormatForAccept_JPEGXL verifies that the format auto chooses JPEG XL
+// when Accept names image/jxl, ahead of AVIF whatever their q, and AVIF when
+// Accept refuses JPEG XL with q=0.
+func TestFormatForAccept_JPEGXL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name   string
+		accept string
+		want   imgcache.ImageFormat
+	}{
+		{"JPEG XL-capable browser",
+			"image/jxl,image/avif,image/webp,image/*,*/*;q=0.8", imgcache.FormatJXL},
+		{"JPEG XL only", jxlType, imgcache.FormatJXL},
+		{"JPEG XL with a lower q than AVIF", "image/avif,image/jxl;q=0.5",
+			imgcache.FormatJXL},
+		{"q=0 on JPEG XL", "image/jxl;q=0,image/avif,*/*", imgcache.FormatAVIF},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := formatForAccept(tt.accept)
+			if got != tt.want || err != nil {
+				t.Errorf("formatForAccept(%q) = %q, %v, want %q",
+					tt.accept, got, err, tt.want)
+			}
+		})
+	}
+}
+
+// TestFormatAuto_JPEGXL requests an auto URL on each image route with an
+// Accept header that names image/jxl, and checks that the answer is a JPEG XL
+// image.
+func TestFormatAuto_JPEGXL(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	signedURL, encryptedURL := autoPhotoURLs(t, h)
+
+	for _, target := range []string{signedURL, encryptedURL} {
+		rec := requestImage(t, srv, http.MethodGet, target,
+			"image/jxl,image/avif,image/webp,*/*;q=0.8")
+		gotType := rec.Header().Get("Content-Type")
+
+		if rec.Code != http.StatusOK || gotType != jxlType {
+			t.Errorf("%s: %d %s, want 200 %s; body %s",
+				target, rec.Code, gotType, jxlType, rec.Body)
+
+			continue
+		}
+
+		if got := vips.DetermineImageType(rec.Body.Bytes()); got != vips.ImageTypeJXL {
+			t.Errorf("%s: body is %s, want jxl", target, vips.ImageTypes[got])
+		}
+	}
+}

internal/handlers/referer_blocklist_internal_test.go

@@ -0,0 +1,185 @@
+package handlers
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"sneak.berlin/go/pixa/internal/allowlist"
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// blockedReferer is a page on leech.example, which newRefererRoutes puts on
+// referer_blocklist.
+const blockedReferer = "https://leech.example/page.html"
+
+// countingFetcher passes each fetch on to the fetcher it holds and counts it.
+type countingFetcher struct {
+	httpfetcher.Fetcher
+
+	fetches atomic.Int32
+}
+
+// Fetch counts the fetch and passes it on.
+func (f *countingFetcher) Fetch(
+	ctx context.Context, url string,
+) (*httpfetcher.FetchResult, error) {
+	f.fetches.Add(1)
+
+	return f.Fetcher.Fetch(ctx, url)
+}
+
+// newRefererRoutes returns both image routes of a Handlers whose
+// referer_blocklist is "leech.example" and ".hotlinker.example", the
+// Handlers, and the fetcher the routes fetch through. The JPEG at photoPath
+// exists on allowlistedHost and on signedHost.
+func newRefererRoutes(t *testing.T) (http.Handler, *Handlers, *countingFetcher) {
+	t.Helper()
+
+	fetcher := &countingFetcher{
+		Fetcher: newPhotoFetcher(t, allowlistedHost, signedHost),
+	}
+
+	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
+		StateDir:    t.TempDir(),
+		CacheTTL:    time.Hour,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("imgcache.NewCache() error = %v", err)
+	}
+
+	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
+		Cache:      cache,
+		Fetcher:    fetcher,
+		SigningKey: testSigningKey,
+		Allowlist:  []string{allowlistedHost},
+	})
+	if err != nil {
+		t.Fatalf("imgcache.NewService() error = %v", err)
+	}
+
+	encGen, err := encurl.NewGenerator(testSigningKey)
+	if err != nil {
+		t.Fatalf("encurl.NewGenerator() error = %v", err)
+	}
+
+	h := &Handlers{
+		log:    slog.New(slog.DiscardHandler),
+		imgSvc: svc,
+		encGen: encGen,
+		refererBlocklist: allowlist.New(
+			[]string{"leech.example", ".hotlinker.example"}),
+	}
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", h.HandleImage())
+	r.Get("/v1/e/{token}/*", h.HandleImageEnc())
+
+	return r, h, fetcher
+}
+
+// getWithReferer sends a GET for target to routes with referer as its
+// Referer header, or with none when referer is empty, and returns the
+// response.
+func getWithReferer(
+	t *testing.T, routes http.Handler, target, referer string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, target, nil)
+	if referer != "" {
+		req.Header.Set("Referer", referer)
+	}
+
+	rec := httptest.NewRecorder()
+
+	routes.ServeHTTP(rec, req)
+	t.Logf("GET %s with Referer %q: %d", target, referer, rec.Code)
+
+	return rec
+}
+
+// TestRefererBlocklist verifies that both image routes refuse a request whose
+// Referer names a host on referer_blocklist with 403 and the JSON error,
+// without fetching from the upstream host, and serve a request with no
+// Referer, one that does not parse, or one naming any other host. Hosts are
+// matched as allowlist_hosts matches them.
+func TestRefererBlocklist(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name    string
+		referer string
+		want    int
+	}{
+		{"no referer", "", http.StatusOK},
+		{"unlisted host", "https://unlisted.example/page.html", http.StatusOK},
+		{"unparseable", "%zz", http.StatusOK},
+		{"listed host", blockedReferer, http.StatusForbidden},
+		{"subdomain of listed host", "https://www.leech.example/", http.StatusOK},
+		{"subdomain of dot pattern", "https://www.hotlinker.example/a.html",
+			http.StatusForbidden},
+		{"dot pattern without its dot", "https://hotlinker.example/",
+			http.StatusForbidden},
+		{"host continuing past dot pattern",
+			"https://hotlinker.example.evil.example/", http.StatusOK},
+	}
+
+	// The photo's URL on each image route.
+	photoURLs := map[string]func(t *testing.T, h *Handlers) string{
+		"plain URL": func(t *testing.T, _ *Handlers) string {
+			t.Helper()
+
+			return photoURL(allowlistedHost)
+		},
+		"encrypted URL": encPhotoURL,
+	}
+
+	for urlName, photoURLFor := range photoURLs {
+		for _, tc := range cases {
+			t.Run(urlName+", "+tc.name, func(t *testing.T) {
+				t.Parallel()
+
+				routes, h, fetcher := newRefererRoutes(t)
+
+				rec := getWithReferer(t, routes, photoURLFor(t, h), tc.referer)
+
+				if tc.want == http.StatusOK {
+					requireServedPhoto(t, rec)
+
+					return
+				}
+
+				checkErrorBody(t, rec, http.StatusForbidden, "referer blocked")
+
+				if n := fetcher.fetches.Load(); n != 0 {
+					t.Errorf("upstream fetched %d times, want 0", n)
+				}
+			})
+		}
+	}
+}
+
+// TestBlockedRefererRefusedWhenImageIsCached verifies that a request whose
+// Referer is on referer_blocklist is refused even when the image it asks for
+// is already cached, so the answer does not depend on the cache.
+func TestBlockedRefererRefusedWhenImageIsCached(t *testing.T) {
+	t.Parallel()
+
+	routes, h, _ := newRefererRoutes(t)
+
+	for _, target := range []string{photoURL(allowlistedHost), encPhotoURL(t, h)} {
+		requireServedPhoto(t, getWithReferer(t, routes, target, ""))
+
+		rec := getWithReferer(t, routes, target, blockedReferer)
+		checkErrorBody(t, rec, http.StatusForbidden, "referer blocked")
+	}
+}

internal/handlers/request_id_internal_test.go

@@ -0,0 +1,131 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5/middleware"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// signedPhotoURL returns a signed /v1/image/ URL, valid for a minute, for the
+// JPEG at photoPath on signedHost at 50x50, made with h's image service.
+func signedPhotoURL(t *testing.T, h *Handlers) string {
+	t.Helper()
+
+	signedURL, err := h.imgSvc.GenerateSignedURL("", &imgcache.ImageRequest{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Size:       imgcache.Size{Width: 50, Height: 50},
+		Format:     imgcache.FormatJPEG,
+	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
+
+	return signedURL
+}
+
+// encPhotoURL returns an encrypted /v1/e/ URL, which never expires, for the
+// JPEG at photoPath on signedHost at 50x50, made with h's generator.
+func encPhotoURL(t *testing.T, h *Handlers) string {
+	t.Helper()
+
+	token, err := h.encGen.Generate(&encurl.Payload{
+		SourceHost: signedHost,
+		SourcePath: photoPath,
+		Width:      50,
+		Height:     50,
+		Format:     imgcache.FormatJPEG,
+	})
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	return "/v1/e/" + token + "/img.jpg"
+}
+
+// requestIDByMessage reads the JSON log lines in logs and returns the
+// request_id of each line, by its message.
+func requestIDByMessage(t *testing.T, logs io.Reader) map[string]string {
+	t.Helper()
+
+	logged := make(map[string]string)
+
+	dec := json.NewDecoder(logs)
+	for dec.More() {
+		var line map[string]any
+
+		err := dec.Decode(&line)
+		if err != nil {
+			t.Fatalf("decoding log line: %v", err)
+		}
+
+		msg, _ := line["msg"].(string)
+		requestID, _ := line["request_id"].(string)
+		logged[msg] = requestID
+	}
+
+	return logged
+}
+
+// TestImageLogLinesCarryRequestID verifies that the lines logged when an image
+// is fetched, converted and served through either image route carry the
+// request's ID as request_id, as the request log line does, so they can be
+// found from it.
+func TestImageLogLinesCarryRequestID(t *testing.T) {
+	t.Parallel()
+
+	const requestID = "test-request-id"
+
+	imageURLs := map[string]func(*testing.T, *Handlers) string{
+		"/v1/image/": signedPhotoURL,
+		"/v1/e/":     encPhotoURL,
+	}
+
+	for route, imageURL := range imageURLs {
+		t.Run(route, func(t *testing.T) {
+			t.Parallel()
+
+			var logs bytes.Buffer
+
+			h, srv := newSignedHostServer(t,
+				slog.New(slog.NewJSONHandler(&logs, nil)))
+
+			ctx := context.WithValue(t.Context(),
+				middleware.RequestIDKey, requestID)
+			rec := httptest.NewRecorder()
+			srv.ServeHTTP(rec, httptest.NewRequestWithContext(
+				ctx, http.MethodGet, imageURL(t, h), nil))
+
+			if rec.Code != http.StatusOK {
+				t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+			}
+
+			t.Logf("logged:\n%s", logs.String())
+
+			logged := requestIDByMessage(t, &logs)
+
+			for _, msg := range []string{
+				"upstream fetched", "image converted", "image served",
+			} {
+				got, ok := logged[msg]
+				if !ok {
+					t.Errorf("no %q line logged", msg)
+				} else if got != requestID {
+					t.Errorf("%q line has request_id %q, want %q",
+						msg, got, requestID)
+				}
+			}
+		})
+	}
+}

internal/handlers/robots_healthcheck_internal_test.go

@@ -0,0 +1,90 @@
+package handlers
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"testing"
+
+	"go.uber.org/fx/fxtest"
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/healthcheck"
+	"sneak.berlin/go/pixa/internal/logger"
+)
+
+// TestHandleRobotsTxt checks that /robots.txt asks every crawler to stay off
+// the whole site.
+func TestHandleRobotsTxt(t *testing.T) {
+	t.Parallel()
+
+	h := &Handlers{log: slog.New(slog.DiscardHandler)}
+	rec := sendGet(t, h.HandleRobotsTxt(), "/robots.txt")
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	if ct := rec.Header().Get("Content-Type"); ct != "text/plain" {
+		t.Errorf("Content-Type = %q, want text/plain", ct)
+	}
+
+	want := "User-agent: *\nDisallow: /\n"
+	if rec.Body.String() != want {
+		t.Errorf("body = %q, want %q", rec.Body.String(), want)
+	}
+}
+
+// TestHandleHealthCheck checks that the health check answers 200 with status
+// ok, the app's name and version, now, uptime_seconds, uptime_human and
+// maintenance_mode, which is true here: the health check stays 200 while
+// maintenance mode is on.
+func TestHandleHealthCheck(t *testing.T) {
+	t.Parallel()
+
+	lc := fxtest.NewLifecycle(t)
+
+	log, err := logger.New(lc, logger.Params{Globals: &globals.Globals{}})
+	if err != nil {
+		t.Fatalf("logger.New() error = %v", err)
+	}
+
+	hc, err := healthcheck.New(lc, healthcheck.Params{
+		Globals: &globals.Globals{Appname: "pixad", Version: "v1.2.3"},
+		Config:  &config.Config{MaintenanceMode: true},
+		Logger:  log,
+	})
+	if err != nil {
+		t.Fatalf("healthcheck.New() error = %v", err)
+	}
+
+	h := &Handlers{hc: hc, log: slog.New(slog.DiscardHandler)}
+	rec := sendGet(t, h.HandleHealthCheck(), "/.well-known/healthcheck.json")
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	if ct := rec.Header().Get("Content-Type"); ct != "application/json" {
+		t.Errorf("Content-Type = %q, want application/json", ct)
+	}
+
+	var body map[string]any
+
+	err = json.NewDecoder(rec.Body).Decode(&body)
+	if err != nil {
+		t.Fatalf("decoding response body: %v", err)
+	}
+
+	if body["status"] != "ok" || body["appname"] != "pixad" ||
+		body["version"] != "v1.2.3" || body["maintenance_mode"] != true {
+		t.Errorf("body = %v, want status ok, appname pixad, version v1.2.3 "+
+			"and maintenance_mode true", body)
+	}
+
+	for _, key := range []string{"now", "uptime_seconds", "uptime_human"} {
+		if _, ok := body[key]; !ok {
+			t.Errorf("body = %v, has no %s", body, key)
+		}
+	}
+}

internal/httpfetcher/dial_context_internal_test.go

@@ -0,0 +1,66 @@
+package httpfetcher
+
+import (
+	"errors"
+	"net"
+	"testing"
+)
+
+// TestNewUsesCheckedDialerWithoutDialContext checks that a fetcher built
+// without DialContext, as pixa builds it, refuses to connect to a local
+// server.
+func TestNewUsesCheckedDialerWithoutDialContext(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	transport := transportOf(t, New(DefaultConfig()))
+
+	addr := srv.Listener.Addr().String()
+
+	_, err := transport.DialContext(testContext(t), "tcp", addr)
+	if !errors.Is(err, ErrSSRFBlocked) {
+		t.Fatalf("DialContext(%s) error = %v, want ErrSSRFBlocked", addr, err)
+	}
+}
+
+// TestDialContextReplacesOnlyTheDialer checks that a fetcher built with
+// DialContext connects through it, while the URL check still refuses a
+// loopback URL and the redirect check a redirect to a link-local address.
+func TestDialContextReplacesOnlyTheDialer(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	dialer := &recordingDialer{target: srv.Listener.Addr().String()}
+
+	cfg := DefaultConfig()
+	cfg.AllowHTTP = true
+	cfg.DialContext = dialer.dialContext
+	f := New(cfg)
+
+	if body := fetchBody(t, f, "/image"); body != imagePayload {
+		t.Errorf("body = %q, want %q", body, imagePayload)
+	}
+
+	_, err := f.Fetch(testContext(t), "http://127.0.0.1/image")
+	if !errors.Is(err, ErrSSRFBlocked) {
+		t.Errorf("Fetch(loopback URL) error = %v, want ErrSSRFBlocked", err)
+	}
+
+	_, err = f.Fetch(testContext(t), upstreamURL("/redirect/private"))
+	if !errors.Is(err, ErrSSRFBlocked) {
+		t.Errorf("Fetch(/redirect/private) error = %v, want ErrSSRFBlocked", err)
+	}
+
+	// The upstream server is reached through DialContext, and nothing else
+	// is asked of it.
+	dialed := dialer.dialedAddrs()
+	if len(dialed) == 0 {
+		t.Error("DialContext was never called")
+	}
+
+	for _, addr := range dialed {
+		if addr != net.JoinHostPort(testPublicHost, "80") {
+			t.Errorf("DialContext was asked to connect to %s", addr)
+		}
+	}
+}

internal/httpfetcher/fetch_internal_test.go

@@ -191,7 +191,23 @@ func fetchBody(t *testing.T, f *HTTPFetcher, path string) string {
 
 // semLen reports how many per-host semaphore slots are currently held.
 func semLen(f *HTTPFetcher, host string) int {
-	return len(f.getHostSemaphore(host))
+	f.hostSemMu.Lock()
+	defer f.hostSemMu.Unlock()
+
+	sem, ok := f.hostSems[host]
+	if !ok {
+		return 0
+	}
+
+	return len(sem.slots)
+}
+
+// hostSemCount reports how many hosts have a semaphore in hostSems.
+func hostSemCount(f *HTTPFetcher) int {
+	f.hostSemMu.Lock()
+	defer f.hostSemMu.Unlock()
+
+	return len(f.hostSems)
 }
 
 func TestFetchRedirectToPrivateIPBlocked(t *testing.T) {

internal/httpfetcher/httpfetcher.go

@@ -18,6 +18,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/go-chi/chi/v5/middleware"
 )
 
 // Fetcher configuration constants.
@@ -43,6 +45,7 @@ const (
 	contentTypeGIF         = "image/gif"
 	contentTypeWebP        = "image/webp"
 	contentTypeAVIF        = "image/avif"
+	contentTypeJXL         = "image/jxl"
 	contentTypeSVG         = "image/svg+xml"
 	contentTypeOctetStream = "application/octet-stream"
 )
@@ -135,6 +138,11 @@ type Config struct {
 	// BlockedNetworks are operator-supplied CIDR ranges refused by the
 	// dialer, in addition to the always-enforced built-in ranges.
 	BlockedNetworks []netip.Prefix
+	// DialContext, when set, makes the fetcher's connections in place of
+	// the dialer that refuses internal addresses; the URL and redirect
+	// checks still run. Only tests set it, to reach a local server; the
+	// config file and the environment cannot.
+	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
 }
 
 // DefaultConfig returns a Config with sensible defaults.
@@ -149,6 +157,7 @@ func DefaultConfig() *Config {
 			contentTypeGIF,
 			contentTypeWebP,
 			contentTypeAVIF,
+			contentTypeJXL,
 			contentTypeSVG,
 		},
 		AllowHTTP:             false,
@@ -160,10 +169,13 @@ func DefaultConfig() *Config {
 // HTTPFetcher implements Fetcher with SSRF protection and connection limits
 // per host and for all hosts together.
 type HTTPFetcher struct {
-	client    *http.Client
-	config    *Config
-	hostSems  map[string]chan struct{} // per-host semaphores
-	hostSemMu sync.Mutex               // protects hostSems map
+	client *http.Client
+	config *Config
+	// hostSems holds the semaphore of each host with a fetch holding or
+	// waiting for one of its slots; the entry is removed when the host's
+	// last such fetch gives its slot back or stops waiting.
+	hostSems  map[string]*hostSemaphore
+	hostSemMu sync.Mutex // protects hostSems and each entry's count
 	// allHostsSemaphore has one slot per connection allowed to all hosts
 	// together (config.MaxConnections).
 	allHostsSemaphore chan struct{}
@@ -171,19 +183,33 @@ type HTTPFetcher struct {
 	connectionWaitTimeout time.Duration
 }
 
+// hostSemaphore is one host's connection slots
+// (config.MaxConnectionsPerHost) and the number of fetches holding or
+// waiting for one of them.
+type hostSemaphore struct {
+	slots chan struct{}
+	count int
+}
+
 // New creates a new HTTPFetcher with SSRF protection.
 func New(config *Config) *HTTPFetcher {
 	if config == nil {
 		config = DefaultConfig()
 	}
 
-	// Create transport with SSRF-safe dialer. The dialer re-resolves and
-	// re-checks at connect time (closing the DNS-rebinding window) against
-	// both the built-in ranges and the operator-supplied blocklist.
-	transport := &http.Transport{
-		DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
+	// Unless config.DialContext replaces it, the transport connects with
+	// the SSRF-safe dialer, which re-resolves and re-checks at connect time
+	// (closing the DNS-rebinding window) against both the built-in ranges
+	// and the operator-supplied blocklist.
+	dialContext := config.DialContext
+	if dialContext == nil {
+		dialContext = func(ctx context.Context, network, addr string) (net.Conn, error) {
 			return dialSSRFSafe(ctx, network, addr, config.BlockedNetworks)
-		},
+		}
+	}
+
+	transport := &http.Transport{
+		DialContext:         dialContext,
 		TLSHandshakeTimeout: DefaultTLSTimeout,
 		MaxIdleConns:        DefaultMaxIdleConns,
 		IdleConnTimeout:     DefaultIdleConnTimeout,
@@ -211,7 +237,7 @@ func New(config *Config) *HTTPFetcher {
 	return &HTTPFetcher{
 		client:                client,
 		config:                config,
-		hostSems:              make(map[string]chan struct{}),
+		hostSems:              make(map[string]*hostSemaphore),
 		allHostsSemaphore:     make(chan struct{}, config.MaxConnections),
 		connectionWaitTimeout: ConnectionWaitTimeout,
 	}
@@ -256,6 +282,13 @@ func (f *HTTPFetcher) Fetch(ctx context.Context, url string) (*FetchResult, erro
 	req.Header.Set("User-Agent", f.config.UserAgent)
 	req.Header.Set("Accept", strings.Join(f.config.AllowedContentTypes, ", "))
 
+	// The ID of the request this fetch serves, so the fetch can be found in
+	// the upstream host's logs
+	requestID := middleware.GetReqID(ctx)
+	if requestID != "" {
+		req.Header.Set(middleware.RequestIDHeader, requestID)
+	}
+
 	// Use httptrace to capture connection details
 	var remoteAddr string
 
@@ -307,6 +340,8 @@ func (f *HTTPFetcher) acquireConnection(
 	select {
 	case hostSem <- struct{}{}:
 	case <-ctx.Done():
+		f.putHostSemaphore(host)
+
 		return nil, ctx.Err()
 	}
 
@@ -314,32 +349,55 @@ func (f *HTTPFetcher) acquireConnection(
 	case f.allHostsSemaphore <- struct{}{}:
 	case <-time.After(f.connectionWaitTimeout):
 		<-hostSem
+		f.putHostSemaphore(host)
 
 		return nil, ErrTooManyConnections
 	case <-ctx.Done():
 		<-hostSem
+		f.putHostSemaphore(host)
 
 		return nil, ctx.Err()
 	}
 
 	return func() {
 		<-hostSem
+		f.putHostSemaphore(host)
 		<-f.allHostsSemaphore
 	}, nil
 }
 
-// getHostSemaphore returns the semaphore for a host, creating it if necessary.
+// getHostSemaphore returns the semaphore for a host, creating it if
+// necessary, and counts the caller among the fetches using it. The caller
+// calls putHostSemaphore once it holds no slot and waits for none.
 func (f *HTTPFetcher) getHostSemaphore(host string) chan struct{} {
 	f.hostSemMu.Lock()
 	defer f.hostSemMu.Unlock()
 
 	sem, ok := f.hostSems[host]
 	if !ok {
-		sem = make(chan struct{}, f.config.MaxConnectionsPerHost)
+		sem = &hostSemaphore{
+			slots: make(chan struct{}, f.config.MaxConnectionsPerHost),
+		}
 		f.hostSems[host] = sem
 	}
 
-	return sem
+	sem.count++
+
+	return sem.slots
+}
+
+// putHostSemaphore stops counting the caller among the fetches using the
+// host's semaphore, and removes the semaphore when no fetch uses it.
+func (f *HTTPFetcher) putHostSemaphore(host string) {
+	f.hostSemMu.Lock()
+	defer f.hostSemMu.Unlock()
+
+	sem := f.hostSems[host]
+
+	sem.count--
+	if sem.count == 0 {
+		delete(f.hostSems, host)
+	}
 }
 
 // buildResult validates the upstream response and assembles a FetchResult

internal/httpfetcher/jpegxl_internal_test.go

@@ -0,0 +1,20 @@
+package httpfetcher
+
+import "testing"
+
+// TestJPEGXLContentType verifies that the fetcher accepts an upstream answer
+// of type image/jxl by default, and that the mock fetcher serves a .jxl file
+// as image/jxl.
+func TestJPEGXLContentType(t *testing.T) {
+	t.Parallel()
+
+	const jxlType = "image/jxl"
+
+	if !New(DefaultConfig()).isAllowedContentType(jxlType) {
+		t.Errorf("isAllowedContentType(%q) = false, want true", jxlType)
+	}
+
+	if got := detectContentTypeFromPath("images/photo.jxl"); got != jxlType {
+		t.Errorf("detectContentTypeFromPath(photo.jxl) = %q, want %q", got, jxlType)
+	}
+}

internal/httpfetcher/max_connections_internal_test.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"net"
 	"strconv"
+	"sync"
 	"testing"
 	"time"
 )
@@ -119,6 +120,98 @@ func TestFetchFreesHostSlotWhenContextEndsWaitingForConnection(t *testing.T) {
 	}
 }
 
+// TestFetchRemovesIdleHostSemaphores checks that a host's semaphore is
+// removed once no fetch holds or waits for one of its slots: after 100
+// concurrent fetches from 50 hosts have all finished, no semaphore is left.
+func TestFetchRemovesIdleHostSemaphores(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, _ := newServerFetcher(t, srv, nil)
+	ctx := testContext(t)
+
+	var wg sync.WaitGroup
+
+	for i := range 100 {
+		wg.Go(func() {
+			res, err := f.Fetch(ctx, imageURLOnPort(1+i%50))
+			if err != nil {
+				t.Errorf("Fetch() error = %v", err)
+
+				return
+			}
+
+			_ = res.Content.Close()
+		})
+	}
+
+	wg.Wait()
+
+	if n := hostSemCount(f); n != 0 {
+		t.Errorf("%d host semaphores left after every fetch finished, want 0", n)
+	}
+}
+
+// TestFetchRemovesHostSemaphoreWhenNoConnection checks that a fetch that
+// ends without a connection leaves no semaphore behind: when it is refused
+// after waiting for a connection shared by all hosts, when its context ends
+// while it waits for its host's slot, and when its context ends while it
+// waits for a connection shared by all hosts, long before the 10 second
+// wait timeout.
+func TestFetchRemovesHostSemaphoreWhenNoConnection(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxConnections = 1
+	cfg.MaxConnectionsPerHost = 1
+
+	f, _ := newServerFetcher(t, srv, cfg)
+	f.connectionWaitTimeout = 100 * time.Millisecond
+
+	open, err := f.Fetch(testContext(t), imageURLOnPort(81))
+	if err != nil {
+		t.Fatalf("first Fetch() error = %v", err)
+	}
+
+	_, err = f.Fetch(testContext(t), imageURLOnPort(82))
+	if !errors.Is(err, ErrTooManyConnections) {
+		t.Fatalf("Fetch() from another host: error = %v, "+
+			"want ErrTooManyConnections", err)
+	}
+
+	ctx, cancel := context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancel()
+
+	_, err = f.Fetch(ctx, imageURLOnPort(81))
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Fetch() from the busy host: error = %v, "+
+			"want context.DeadlineExceeded", err)
+	}
+
+	// Back to the 10 second wait, so the next fetch's context ends first.
+	f.connectionWaitTimeout = ConnectionWaitTimeout
+
+	ctx, cancel = context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancel()
+
+	_, err = f.Fetch(ctx, imageURLOnPort(83))
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Fetch() from a host with nothing open: error = %v, "+
+			"want context.DeadlineExceeded", err)
+	}
+
+	err = open.Content.Close()
+	if err != nil {
+		t.Fatalf("close first body: %v", err)
+	}
+
+	if n := hostSemCount(f); n != 0 {
+		t.Errorf("%d host semaphores left after every fetch finished, want 0", n)
+	}
+}
+
 // TestFetchReleasesConnectionOnError checks that a fetch that fails after
 // taking its connection gives it back: with MaxConnections at 1, the slot
 // must be free after the failure and the next fetch must succeed.

internal/httpfetcher/mock.go

@@ -109,6 +109,8 @@ func detectContentTypeFromPath(path string) string {
 		return contentTypeWebP
 	case strings.HasSuffix(path, ".avif"):
 		return contentTypeAVIF
+	case strings.HasSuffix(path, ".jxl"):
+		return contentTypeJXL
 	case strings.HasSuffix(path, ".svg"):
 		return contentTypeSVG
 	default:

internal/httpfetcher/request_id_internal_test.go

@@ -0,0 +1,50 @@
+package httpfetcher
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+// TestFetchSendsRequestID verifies that a fetch sends the ID of the request
+// it serves, which the RequestID middleware stores in the request context,
+// to the upstream host as X-Request-Id, so the fetch can be found in that
+// host's logs.
+func TestFetchSendsRequestID(t *testing.T) {
+	t.Parallel()
+
+	const requestID = "test-request-id"
+
+	received := make(chan string, 1)
+
+	srv := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			received <- r.Header.Get("X-Request-Id")
+
+			w.Header().Set("Content-Type", contentTypeJPEG)
+			_, _ = io.WriteString(w, imagePayload)
+		}))
+	t.Cleanup(srv.Close)
+
+	f, _ := newServerFetcher(t, srv, nil)
+
+	ctx := context.WithValue(testContext(t), middleware.RequestIDKey, requestID)
+
+	res, err := f.Fetch(ctx, upstreamURL("/image"))
+	if err != nil {
+		t.Fatalf("Fetch() error = %v", err)
+	}
+
+	_ = res.Content.Close()
+
+	got := <-received
+	t.Logf("upstream received X-Request-Id %q", got)
+
+	if got != requestID {
+		t.Errorf("upstream X-Request-Id = %q, want %q", got, requestID)
+	}
+}

internal/imageprocessor/empty_format_internal_test.go

@@ -0,0 +1,21 @@
+package imageprocessor
+
+import (
+	"bytes"
+	"errors"
+	"testing"
+)
+
+// TestImageProcessor_EmptyFormatRefused verifies that a request with no format
+// is refused, as both image routes give every request a format before it is
+// processed.
+func TestImageProcessor_EmptyFormatRefused(t *testing.T) {
+	t.Parallel()
+
+	_, err := New(Params{}).Process(
+		t.Context(), bytes.NewReader(createTestJPEG(t, 20, 20)), &Request{},
+	)
+	if !errors.Is(err, ErrUnsupportedOutputFormat) {
+		t.Errorf("Process() error = %v, want %v", err, ErrUnsupportedOutputFormat)
+	}
+}

internal/imageprocessor/encoder_settings_internal_test.go

@@ -0,0 +1,145 @@
+package imageprocessor
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/png"
+	"testing"
+
+	"github.com/davidbyttow/govips/v2/vips"
+)
+
+// processedSize runs input through Process and returns the output's size in
+// bytes.
+func processedSize(t *testing.T, input []byte, req *Request) int64 {
+	t.Helper()
+
+	result, err := New(Params{}).Process(t.Context(), bytes.NewReader(input), req)
+	if err != nil {
+		t.Fatalf("Process() error = %v", err)
+	}
+
+	_ = result.Content.Close()
+
+	return result.ContentLength
+}
+
+// encodePNG encodes img as PNG with Go's encoder.
+func encodePNG(t *testing.T, img image.Image) []byte {
+	t.Helper()
+
+	var buf bytes.Buffer
+
+	err := png.Encode(&buf, img)
+	if err != nil {
+		t.Fatalf("failed to encode test PNG: %v", err)
+	}
+
+	return buf.Bytes()
+}
+
+// decode decodes input with vips, as Process does.
+func decode(t *testing.T, input []byte) *vips.ImageRef {
+	t.Helper()
+
+	img, err := vips.NewImageFromBuffer(input)
+	if err != nil {
+		t.Fatalf("failed to decode input: %v", err)
+	}
+
+	t.Cleanup(img.Close)
+
+	return img
+}
+
+// TestImageProcessor_PNGIsCompressed verifies that a PNG output is
+// compressed: a flat 200x150 image, 90,000 bytes of raw pixels, comes out at
+// a small fraction of that.
+func TestImageProcessor_PNGIsCompressed(t *testing.T) {
+	t.Parallel()
+
+	const width, height = 200, 150
+
+	flat := image.NewRGBA(image.Rect(0, 0, width, height))
+	for y := range height {
+		for x := range width {
+			flat.Set(x, y, color.RGBA{R: 40, G: 120, B: 200, A: 255})
+		}
+	}
+
+	size := processedSize(t, encodePNG(t, flat), &Request{Format: FormatPNG})
+
+	const rawBytes = width * height * 3
+	if size > rawBytes/10 {
+		t.Errorf("PNG output is %d bytes, want under a tenth of its %d raw",
+			size, rawBytes)
+	}
+}
+
+// TestImageProcessor_WebPAtDefaultEffort verifies that WebP is saved at
+// libvips' default effort, 4: the output is the size of the same image saved
+// at that effort.
+func TestImageProcessor_WebPAtDefaultEffort(t *testing.T) {
+	t.Parallel()
+
+	input := createTestJPEG(t, 200, 150)
+
+	size := processedSize(t, input, &Request{Format: FormatWebP, Quality: 85})
+
+	want, _, err := decode(t, input).ExportWebp(&vips.WebpExportParams{
+		StripMetadata:   true,
+		Quality:         85,
+		ReductionEffort: 4,
+	})
+	if err != nil {
+		t.Fatalf("ExportWebp() error = %v", err)
+	}
+
+	if size != int64(len(want)) {
+		t.Errorf("WebP output is %d bytes, want %d, the size at effort 4",
+			size, len(want))
+	}
+}
+
+// TestImageProcessor_AVIFAtEffort1 verifies that AVIF is saved at effort 1
+// with 8 bits per sample: the output is the size of the same image saved
+// with those settings. The source is 16-bit, which libvips saves with 12
+// bits when it is not given a bit depth, and 640x480: on a small image,
+// such as 64x48, efforts 1 and 2 give the same output.
+func TestImageProcessor_AVIFAtEffort1(t *testing.T) {
+	t.Parallel()
+
+	const width, height = 640, 480
+
+	source := image.NewRGBA64(image.Rect(0, 0, width, height))
+	for y := range height {
+		for x := range width {
+			source.Set(x, y, color.RGBA64{
+				R: uint16((x * 65535 / width) & 0xffff),
+				G: uint16((y * 65535 / height) & 0xffff),
+				B: 32768,
+				A: 65535,
+			})
+		}
+	}
+
+	input := encodePNG(t, source)
+
+	size := processedSize(t, input, &Request{Format: FormatAVIF, Quality: 85})
+
+	want, _, err := decode(t, input).ExportAvif(&vips.AvifExportParams{
+		StripMetadata: true,
+		Quality:       85,
+		Effort:        1,
+		Bitdepth:      8,
+	})
+	if err != nil {
+		t.Fatalf("ExportAvif() error = %v", err)
+	}
+
+	if size != int64(len(want)) {
+		t.Errorf("AVIF output is %d bytes, want %d, the size at effort 1 "+
+			"and 8 bits", size, len(want))
+	}
+}

internal/imageprocessor/imageprocessor.go

@@ -37,6 +37,24 @@ func initVips() {
 	})
 }
 
+// errNoJPEGXL is returned by CheckJPEGXLSupport.
+var errNoJPEGXL = errors.New("libvips lacks JPEG XL support: install " +
+	"vips-jxl on Alpine, or use a libvips built with libjxl")
+
+// CheckJPEGXLSupport returns an error, naming the fix, when libvips
+// cannot load and save JPEG XL.
+func CheckJPEGXLSupport() error {
+	initVips()
+
+	// govips counts a format as supported when libvips has its loader;
+	// libvips builds the JPEG XL loader and saver together.
+	if !vips.IsTypeSupported(vips.ImageTypeJXL) {
+		return errNoJPEGXL
+	}
+
+	return nil
+}
+
 // Format represents supported output image formats.
 type Format string
 
@@ -47,6 +65,7 @@ const (
 	FormatPNG      Format = "png"
 	FormatWebP     Format = "webp"
 	FormatAVIF     Format = "avif"
+	FormatJXL      Format = "jxl"
 	FormatGIF      Format = "gif"
 )
 
@@ -237,9 +256,9 @@ func (p *ImageProcessor) Process(
 		}
 	}
 
-	// Determine output format
+	// orig is the source's own format; encode refuses an empty format
 	outputFormat := req.Format
-	if outputFormat == FormatOriginal || outputFormat == "" {
+	if outputFormat == FormatOriginal {
 		outputFormat = p.formatFromString(inputFormat)
 	}
 
@@ -287,6 +306,7 @@ const (
 	mimeGIF  = "image/gif"
 	mimeWebP = "image/webp"
 	mimeAVIF = "image/avif"
+	mimeJXL  = "image/jxl"
 )
 
 // SupportedInputFormats returns MIME types this processor can read.
@@ -297,6 +317,7 @@ func (p *ImageProcessor) SupportedInputFormats() []string {
 		mimeGIF,
 		mimeWebP,
 		mimeAVIF,
+		mimeJXL,
 	}
 }
 
@@ -308,6 +329,7 @@ func (p *ImageProcessor) SupportedOutputFormats() []Format {
 		FormatGIF,
 		FormatWebP,
 		FormatAVIF,
+		FormatJXL,
 	}
 }
 
@@ -324,6 +346,8 @@ func FormatToMIME(format Format) string {
 		return mimeGIF
 	case FormatAVIF:
 		return mimeAVIF
+	case FormatJXL:
+		return mimeJXL
 	case FormatOriginal:
 		return "application/octet-stream"
 	default:
@@ -331,6 +355,31 @@ func FormatToMIME(format Format) string {
 	}
 }
 
+// WaitForProcessing waits until no image is being processed, or until ctx
+// ends, and returns how many images were still being processed then. It
+// waits by taking each slot in processingSemaphore as it frees up until it
+// holds them all, or until ctx ends, then gives back the slots it took.
+func (p *ImageProcessor) WaitForProcessing(ctx context.Context) int {
+	taken := 0
+
+	defer func() {
+		for range taken {
+			<-p.processingSemaphore
+		}
+	}()
+
+	for taken < cap(p.processingSemaphore) {
+		select {
+		case p.processingSemaphore <- struct{}{}:
+			taken++
+		case <-ctx.Done():
+			return len(p.processingSemaphore) - taken
+		}
+	}
+
+	return 0
+}
+
 // acquireSlot takes a slot in processingSemaphore, waiting at most
 // processingWaitTimeout for one to free up, and returns the func that gives
 // it back. A free slot is taken even when ctx has ended; only the wait for
@@ -368,9 +417,11 @@ func (p *ImageProcessor) detectFormat(img *vips.ImageRef) string {
 		return "webp"
 	case vips.ImageTypeAVIF, vips.ImageTypeHEIF:
 		return string(FormatAVIF)
+	case vips.ImageTypeJXL:
+		return string(FormatJXL)
 	case vips.ImageTypeUnknown, vips.ImageTypeMagick, vips.ImageTypePDF,
 		vips.ImageTypeSVG, vips.ImageTypeTIFF, vips.ImageTypeBMP,
-		vips.ImageTypeJP2K, vips.ImageTypeJXL:
+		vips.ImageTypeJP2K:
 		return "unknown"
 	default:
 		return "unknown"
@@ -442,44 +493,6 @@ func (p *ImageProcessor) encode(
 		quality = defaultQuality
 	}
 
-	var params vips.ExportParams
-
-	switch format {
-	case FormatJPEG:
-		params = vips.ExportParams{
-			Format:  vips.ImageTypeJPEG,
-			Quality: quality,
-		}
-
-	case FormatPNG:
-		params = vips.ExportParams{
-			Format: vips.ImageTypePNG,
-		}
-
-	case FormatGIF:
-		params = vips.ExportParams{
-			Format: vips.ImageTypeGIF,
-		}
-
-	case FormatWebP:
-		params = vips.ExportParams{
-			Format:  vips.ImageTypeWEBP,
-			Quality: quality,
-		}
-
-	case FormatAVIF:
-		params = vips.ExportParams{
-			Format:  vips.ImageTypeAVIF,
-			Quality: quality,
-		}
-
-	case FormatOriginal:
-		return nil, fmt.Errorf("%w: %s", ErrUnsupportedOutputFormat, format)
-
-	default:
-		return nil, fmt.Errorf("%w: %s", ErrUnsupportedOutputFormat, format)
-	}
-
 	// Stripping drops the ICC profile as well, and clients show an image
 	// with no profile as sRGB, so convert to sRGB first. "srgb" names
 	// libvips' built-in profile; govips' own sRGB path variable is set on
@@ -491,11 +504,166 @@ func (p *ImageProcessor) encode(
 		}
 	}
 
-	// Drop EXIF, XMP, IPTC and the ICC profile. govips ignores this for
-	// GIF, which carries none of them.
-	params.StripMetadata = true
+	switch format {
+	case FormatJPEG:
+		return exportJPEG(img, quality)
 
-	output, _, err := img.Export(&params)
+	case FormatPNG:
+		return exportPNG(img)
+
+	case FormatGIF:
+		return exportGIF(img)
+
+	case FormatWebP:
+		return exportWebP(img, quality)
+
+	case FormatAVIF:
+		return exportAVIF(img, quality)
+
+	case FormatJXL:
+		return exportJXL(img, quality)
+
+	case FormatOriginal:
+		return nil, fmt.Errorf("%w: %s", ErrUnsupportedOutputFormat, format)
+
+	default:
+		return nil, fmt.Errorf("%w: %s", ErrUnsupportedOutputFormat, format)
+	}
+}
+
+// govips sends libvips Go's zero value for some settings an export leaves
+// out, such as no compression at all for PNG, so each export below sets
+// every setting whose zero value is not what pixa wants. Stripping metadata
+// drops EXIF, XMP, IPTC and the ICC profile.
+
+// exportJPEG encodes img as JPEG at quality, without metadata. The settings
+// it leaves out are at libvips' defaults.
+func exportJPEG(img *vips.ImageRef, quality int) ([]byte, error) {
+	output, _, err := img.ExportJpeg(&vips.JpegExportParams{
+		StripMetadata: true,
+		Quality:       quality,
+	})
+
+	return output, err
+}
+
+// pngCompression is libvips' default PNG compression, from 0 (none) to 9.
+const pngCompression = 6
+
+// exportPNG encodes img as PNG at libvips' default compression and row
+// filter, without metadata.
+func exportPNG(img *vips.ImageRef) ([]byte, error) {
+	output, _, err := img.ExportPng(&vips.PngExportParams{
+		StripMetadata: true,
+		Compression:   pngCompression,
+		Filter:        vips.PngFilterNone,
+	})
+
+	return output, err
+}
+
+// gifEffort is libvips' default GIF effort, from 1 to 10.
+const gifEffort = 7
+
+// exportGIF encodes img as GIF at libvips' default effort. govips cannot
+// have libvips strip metadata from GIF, which carries none.
+func exportGIF(img *vips.ImageRef) ([]byte, error) {
+	output, _, err := img.ExportGIF(&vips.GifExportParams{Effort: gifEffort})
+
+	return output, err
+}
+
+// webpEffort is libvips' default WebP effort, from 0 (fastest) to 6.
+const webpEffort = 4
+
+// exportWebP encodes img as lossy WebP at quality and libvips' default
+// effort, without metadata.
+func exportWebP(img *vips.ImageRef, quality int) ([]byte, error) {
+	output, _, err := img.ExportWebp(&vips.WebpExportParams{
+		StripMetadata:   true,
+		Quality:         quality,
+		ReductionEffort: webpEffort,
+	})
+
+	return output, err
+}
+
+// avifEffort is the AVIF effort, from 0 (fastest) to 9; 1 is the lowest
+// govips can set. With one thread, as pixad runs libvips, 1 takes about 51
+// seconds to save an 8192x8192 image of random pixels, the worst case,
+// against the default downstream_timeout of 60 seconds. On an image of
+// milder noise, which 1 saves in about 12 seconds, 2 takes nearly a minute
+// and libvips' default, 4, takes minutes.
+const avifEffort = 1
+
+// avifBitdepth is the AVIF bit depth, 8 bits per sample for every image.
+// libvips would save a 16-bit image with 12, but at avifEffort that takes
+// about 54 seconds for a 16-bit 8192x8192 image of milder noise, nearly all
+// of the default downstream_timeout, and about 12 seconds with 8.
+const avifBitdepth = 8
+
+// exportAVIF encodes img as lossy AVIF at quality, avifEffort and
+// avifBitdepth, without metadata.
+func exportAVIF(img *vips.ImageRef, quality int) ([]byte, error) {
+	output, _, err := img.ExportAvif(&vips.AvifExportParams{
+		StripMetadata: true,
+		Quality:       quality,
+		Effort:        avifEffort,
+		Bitdepth:      avifBitdepth,
+	})
+
+	return output, err
+}
+
+// jxlResolution is the resolution every JPEG XL image is saved with, in
+// pixels per millimetre as libvips counts it: 72 dpi, what libvips gives a
+// JPEG that names none.
+const jxlResolution = 72 / 25.4
+
+// exportJXL encodes img as JPEG XL at quality, with libvips' default effort
+// and without metadata. govips sends libvips a distance, the JPEG XL
+// encoder's own measure of quality, along with the quality, and libvips then
+// uses the distance alone, so the quality is also given as a distance.
+func exportJXL(img *vips.ImageRef, quality int) ([]byte, error) {
+	// libvips converts a CMYK image to sRGB before it saves WebP, AVIF or
+	// PNG, but cannot save one as JPEG XL. encode has already converted
+	// any image with an ICC profile to sRGB, so this is CMYK with none.
+	if img.Interpretation() == vips.InterpretationCMYK {
+		err := img.ToColorSpace(vips.InterpretationSRGB)
+		if err != nil {
+			return nil, fmt.Errorf("failed to convert CMYK to sRGB: %w", err)
+		}
+	}
+
+	// govips cannot make libvips strip metadata from JPEG XL, so it is
+	// removed from the image itself. RemoveMetadata removes EXIF, XMP and
+	// IPTC but keeps the ICC profile.
+	err := img.RemoveMetadata()
+	if err != nil {
+		return nil, err
+	}
+
+	err = img.RemoveICCProfile()
+	if err != nil {
+		return nil, err
+	}
+
+	// libvips 8.16 and later still write an EXIF block of their own, from
+	// the image's size, orientation and resolution, and fixed values. The
+	// image is upright, so its orientation is 1, but its resolution is still
+	// the source's.
+	toSave, err := img.CopyChangingResolution(jxlResolution, jxlResolution)
+	if err != nil {
+		return nil, err
+	}
+
+	defer toSave.Close()
+
+	params := vips.NewJxlExportParams()
+	params.Quality = quality
+	params.Distance = jxlDistance(quality)
+
+	output, _, err := toSave.ExportJxl(params)
 	if err != nil {
 		return nil, err
 	}
@@ -503,6 +671,22 @@ func (p *ImageProcessor) encode(
 	return output, nil
 }
 
+// jxlDistance turns a quality from 1 to 100 into the JPEG XL encoder's
+// distance, with the formula libvips and libjxl use for their own quality
+// setting, except that 100 stays lossy (distance 0.1) where libjxl makes it
+// lossless.
+//
+//nolint:mnd // the constants of that formula
+func jxlDistance(quality int) float64 {
+	q := float64(quality)
+
+	if quality >= 30 {
+		return 0.1 + (100-q)*0.09
+	}
+
+	return 53.0/3000.0*q*q - 23.0/20.0*q + 25.0
+}
+
 // formatFromString converts a format string to Format.
 func (p *ImageProcessor) formatFromString(format string) Format {
 	switch format {
@@ -516,6 +700,8 @@ func (p *ImageProcessor) formatFromString(format string) Format {
 		return FormatWebP
 	case string(FormatAVIF):
 		return FormatAVIF
+	case string(FormatJXL):
+		return FormatJXL
 	default:
 		return FormatJPEG
 	}

internal/imageprocessor/jpegxl_internal_test.go

@@ -0,0 +1,52 @@
+package imageprocessor
+
+import (
+	"testing"
+
+	"github.com/davidbyttow/govips/v2/vips"
+)
+
+// TestCheckJPEGXLSupport fails when libvips lacks JPEG XL support, as on
+// Alpine without the vips-jxl package.
+func TestCheckJPEGXLSupport(t *testing.T) {
+	t.Parallel()
+
+	err := CheckJPEGXLSupport()
+	if err != nil {
+		t.Fatalf("CheckJPEGXLSupport() error = %v", err)
+	}
+}
+
+// TestLibvipsSavesAndLoadsJPEGXL saves an image as JPEG XL with govips and
+// loads it back. It fails when libvips lacks JPEG XL support, as on Alpine
+// without the vips-jxl package.
+func TestLibvipsSavesAndLoadsJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	img, err := vips.NewImageFromBuffer(createTestJPEG(t, 64, 48))
+	if err != nil {
+		t.Fatalf("failed to load test JPEG: %v", err)
+	}
+
+	defer img.Close()
+
+	jxl, _, err := img.ExportJxl(vips.NewJxlExportParams())
+	if err != nil {
+		t.Fatalf("ExportJxl() error = %v", err)
+	}
+
+	loaded, err := vips.NewImageFromBuffer(jxl)
+	if err != nil {
+		t.Fatalf("failed to load the JPEG XL image: %v", err)
+	}
+
+	defer loaded.Close()
+
+	if loaded.Format() != vips.ImageTypeJXL {
+		t.Errorf("loaded format = %s, want jxl", vips.ImageTypes[loaded.Format()])
+	}
+
+	if loaded.Width() != 64 || loaded.Height() != 48 {
+		t.Errorf("loaded size = %dx%d, want 64x48", loaded.Width(), loaded.Height())
+	}
+}

internal/imageprocessor/jpegxl_output_internal_test.go

@@ -0,0 +1,244 @@
+package imageprocessor
+
+import (
+	"bytes"
+	"io"
+	"math"
+	"os"
+	"testing"
+
+	"github.com/davidbyttow/govips/v2/vips"
+)
+
+// TestImageProcessor_EncodeJPEGXL converts a JPEG to a smaller JPEG XL and
+// checks the content type, and the format and size the output loads as.
+func TestImageProcessor_EncodeJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	req := &Request{Size: Size{Width: 100, Height: 75}, Format: FormatJXL}
+
+	result, err := New(Params{}).Process(
+		t.Context(), bytes.NewReader(createTestJPEG(t, 200, 150)), req,
+	)
+	if err != nil {
+		t.Fatalf("Process() error = %v", err)
+	}
+
+	defer func() { _ = result.Content.Close() }()
+
+	if result.ContentType != "image/jxl" {
+		t.Errorf("ContentType = %q, want image/jxl", result.ContentType)
+	}
+
+	data, err := io.ReadAll(result.Content)
+	if err != nil {
+		t.Fatalf("failed to read result: %v", err)
+	}
+
+	output, err := vips.NewImageFromBuffer(data)
+	if err != nil {
+		t.Fatalf("failed to load the output: %v", err)
+	}
+
+	defer output.Close()
+
+	if output.Format() != vips.ImageTypeJXL {
+		t.Errorf("output format = %s, want jxl", vips.ImageTypes[output.Format()])
+	}
+
+	if output.Width() != 100 || output.Height() != 75 {
+		t.Errorf("output size = %dx%d, want 100x75", output.Width(), output.Height())
+	}
+}
+
+// TestImageProcessor_JPEGXLQuality verifies that the quality reaches the JPEG
+// XL encoder: the same image comes out smaller at quality 30 than at 90.
+func TestImageProcessor_JPEGXLQuality(t *testing.T) {
+	t.Parallel()
+
+	input := createTestJPEG(t, 400, 300)
+	outputBytes := make(map[int]int64)
+
+	for _, quality := range []int{30, 90} {
+		result, err := New(Params{}).Process(t.Context(),
+			bytes.NewReader(input), &Request{Format: FormatJXL, Quality: quality})
+		if err != nil {
+			t.Fatalf("Process() at quality %d error = %v", quality, err)
+		}
+
+		_ = result.Content.Close()
+		outputBytes[quality] = result.ContentLength
+	}
+
+	if outputBytes[30] >= outputBytes[90] {
+		t.Errorf("%d bytes at quality 30, %d at 90, want fewer at 30",
+			outputBytes[30], outputBytes[90])
+	}
+}
+
+// TestImageProcessor_JPEGXLDropsSourceEXIF verifies that none of the source's
+// EXIF reaches a JPEG XL output. libvips 8.16 and later write an EXIF block of
+// their own into JPEG XL (orientation, resolution, size, colour space and
+// fixed defaults), and govips cannot ask them to leave it out, so the test
+// looks for the source's fields rather than for no EXIF at all.
+func TestImageProcessor_JPEGXLDropsSourceEXIF(t *testing.T) {
+	t.Parallel()
+
+	input, err := os.ReadFile("testdata/gps-exif.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	exif := processAndDecode(t, input, &Request{Format: FormatJXL}).GetExif()
+
+	for _, field := range []string{
+		"exif-ifd0-Make", "exif-ifd0-Model", "exif-ifd2-BodySerialNumber",
+		"exif-ifd2-DateTimeOriginal", "exif-ifd3-GPSLatitude",
+		"exif-ifd3-GPSLongitude",
+	} {
+		if value, found := exif[field]; found {
+			t.Errorf("output has %s: %s", field, value)
+		}
+	}
+}
+
+// TestImageProcessor_JPEGXLDropsSourceResolution verifies that the source's
+// resolution does not reach the EXIF block libvips 8.16 and later write into
+// JPEG XL. A JPEG XL image holds its resolution in that block alone, so the
+// resolution the output loads with is the block's.
+func TestImageProcessor_JPEGXLDropsSourceResolution(t *testing.T) {
+	t.Parallel()
+
+	// dpi-300.jpg is a flat 8x8 grey image with a resolution of 300 dpi.
+	input, err := os.ReadFile("testdata/dpi-300.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	output := processAndDecode(t, input, &Request{Format: FormatJXL})
+
+	// libvips gives the resolution in pixels per millimetre.
+	xDPI := math.Round(output.ResX() * 25.4)
+	yDPI := math.Round(output.ResY() * 25.4)
+
+	if xDPI == 300 || yDPI == 300 {
+		t.Errorf("output resolution = %vx%v dpi, the source's", xDPI, yDPI)
+	}
+}
+
+// TestImageProcessor_JPEGXLAppliesEXIFOrientation verifies that a JPEG XL
+// output is turned upright, as TestImageProcessor_AppliesEXIFOrientation does
+// for PNG.
+func TestImageProcessor_JPEGXLAppliesEXIFOrientation(t *testing.T) {
+	t.Parallel()
+
+	// orientation-6.jpg is stored 16x8, red on the left and blue on the
+	// right, with EXIF orientation 6 (turn 90 degrees clockwise to view).
+	// Upright it is 8x16, red on top and blue below.
+	input, err := os.ReadFile("testdata/orientation-6.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	output := processAndDecode(t, input, &Request{Format: FormatJXL})
+
+	if output.Width() != 8 || output.Height() != 16 {
+		t.Fatalf("output is %dx%d, want 8x16", output.Width(), output.Height())
+	}
+
+	top, err := output.GetPoint(4, 0)
+	if err != nil {
+		t.Fatalf("GetPoint() error = %v", err)
+	}
+
+	bottom, err := output.GetPoint(4, 15)
+	if err != nil {
+		t.Fatalf("GetPoint() error = %v", err)
+	}
+
+	if top[0] <= top[2] || bottom[2] <= bottom[0] {
+		t.Errorf("top pixel = %v, bottom pixel = %v, want red above blue",
+			top, bottom)
+	}
+}
+
+// TestImageProcessor_JPEGXLConvertsWideGamutToSRGB verifies that a JPEG XL
+// output is converted to sRGB, as TestImageProcessor_ConvertsWideGamutToSRGB
+// does for PNG. It does not check for an ICC profile, as libvips reports one
+// for every JPEG XL image it loads.
+func TestImageProcessor_JPEGXLConvertsWideGamutToSRGB(t *testing.T) {
+	t.Parallel()
+
+	// display-p3.jpg is a flat 8x8 image with the Display P3 profile
+	// embedded, filled with Display P3 (234, 51, 35), which is sRGB red.
+	input, err := os.ReadFile("testdata/display-p3.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	output := processAndDecode(t, input, &Request{Format: FormatJXL})
+
+	pixel, err := output.GetPoint(4, 4)
+	if err != nil {
+		t.Fatalf("GetPoint() error = %v", err)
+	}
+
+	want := []float64{255, 0, 0}
+	for i := range want {
+		if math.Abs(pixel[i]-want[i]) > 5 {
+			t.Fatalf("pixel = %v, want within 5 of %v", pixel, want)
+		}
+	}
+}
+
+// TestImageProcessor_JPEGXLFromCMYK verifies that a CMYK JPEG with no ICC
+// profile can be served as JPEG XL, in sRGB.
+func TestImageProcessor_JPEGXLFromCMYK(t *testing.T) {
+	t.Parallel()
+
+	// cmyk.jpg is a flat 8x8 CMYK image with no ICC profile, filled with
+	// full cyan and no magenta, yellow or black.
+	input, err := os.ReadFile("testdata/cmyk.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	output := processAndDecode(t, input, &Request{Format: FormatJXL})
+
+	if output.Bands() != 3 {
+		t.Fatalf("output has %d bands, want 3", output.Bands())
+	}
+
+	pixel, err := output.GetPoint(4, 4)
+	if err != nil {
+		t.Fatalf("GetPoint() error = %v", err)
+	}
+
+	// Cyan in sRGB: little red, much green and blue.
+	if pixel[0] > 50 || pixel[1] < 100 || pixel[2] < 200 {
+		t.Errorf("pixel = %v, want cyan", pixel)
+	}
+}
+
+// TestJXLDistance verifies the JPEG XL distance for a few qualities: 90 is
+// distance 1, the encoder's own default, and 100 stays lossy.
+func TestJXLDistance(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		quality int
+		want    float64
+	}{
+		{quality: 100, want: 0.1},
+		{quality: 90, want: 1},
+		{quality: 30, want: 6.4},
+		{quality: 20, want: 9.0667},
+	}
+
+	for _, tt := range tests {
+		got := jxlDistance(tt.quality)
+		if math.Abs(got-tt.want) > 0.0001 {
+			t.Errorf("jxlDistance(%d) = %v, want %v", tt.quality, got, tt.want)
+		}
+	}
+}

internal/imageprocessor/max_concurrent_processing_internal_test.go

@@ -300,3 +300,69 @@ func TestProcessReleasesSlotOnError(t *testing.T) {
 		})
 	}
 }
+
+// TestWaitForProcessing holds a processing slot with a Process call that
+// cannot finish reading its input. WaitForProcessing must report that image
+// when its context ends first, wait for it otherwise, return 0 once it has
+// finished, and give back the slots it took while waiting.
+func TestWaitForProcessing(t *testing.T) {
+	t.Parallel()
+
+	proc := New(Params{MaxConcurrentProcessing: 2})
+
+	gate := make(chan struct{})
+	entered := make(chan struct{}, 1)
+	results := make(chan error, 1)
+
+	openGate := sync.OnceFunc(func() { close(gate) })
+	t.Cleanup(openGate)
+
+	processInBackground(proc, &gatedReader{
+		data: bytes.NewReader(createTestJPEG(t, 10, 10)), gate: gate,
+		entered: entered, counter: &readingCounter{},
+	}, results)
+	waitForEntries(t, entered, 1)
+
+	ctx, cancel := context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancel()
+
+	stillProcessing := proc.WaitForProcessing(ctx)
+	t.Logf("WaitForProcessing() after its context ended: %d", stillProcessing)
+
+	if stillProcessing != 1 {
+		t.Errorf("WaitForProcessing() after its context ended = %d, want 1",
+			stillProcessing)
+	}
+
+	waited := make(chan int, 1)
+
+	go func() { waited <- proc.WaitForProcessing(t.Context()) }()
+
+	select {
+	case got := <-waited:
+		t.Fatalf("WaitForProcessing() = %d while an image was being processed",
+			got)
+	case <-time.After(100 * time.Millisecond):
+	}
+
+	openGate()
+
+	err := <-results
+	if err != nil {
+		t.Errorf("Process() error = %v, want nil", err)
+	}
+
+	select {
+	case got := <-waited:
+		if got != 0 {
+			t.Errorf("WaitForProcessing() once processing finished = %d, want 0",
+				got)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("WaitForProcessing() did not return once processing finished")
+	}
+
+	if held := len(proc.processingSemaphore); held != 0 {
+		t.Errorf("%d slots still held after WaitForProcessing() returned", held)
+	}
+}

internal/imgcache/cache.go

@@ -11,7 +11,6 @@ import (
 	"io"
 	"log/slog"
 	"path/filepath"
-	"sync"
 	"time"
 
 	lru "github.com/hashicorp/golang-lru/v2"
@@ -38,11 +37,16 @@ type CacheConfig struct {
 	NegativeTTL time.Duration
 
 	// MaxBytes is the disk cache size limit in bytes that eviction
-	// enforces. Zero means no limit is enforced (no eviction). The
-	// config layer supplies the computed default when the operator
-	// omits cache_max_bytes.
+	// enforces. Zero means no limit is enforced (no eviction).
 	MaxBytes int64
 
+	// UseDefaultMaxBytes makes NewCache replace MaxBytes with the
+	// default limit: 75% of the sum of the space free on the filesystem
+	// holding the cache and the bytes the cache already holds, at least
+	// DefaultCacheMaxBytesFloor. The config layer sets this when the
+	// operator omits cache_max_bytes.
+	UseDefaultMaxBytes bool
+
 	// DisableDiskCache turns the disk cache off entirely: no cache
 	// directories are created, lookups always miss, stores are
 	// no-ops, and no eviction machinery runs. The config layer sets
@@ -69,11 +73,11 @@ type Cache struct {
 
 	// Eviction machinery. The channels are created in NewCache so
 	// stores can signal write pressure without racing StartEviction.
+	// evictionCancel, set by StartEviction, cancels the eviction
+	// goroutine's context.
 	evictionPressure chan struct{}
-	evictionStop     chan struct{}
 	evictionDone     chan struct{}
-	evictionStarted  bool
-	evictionStopOnce sync.Once
+	evictionCancel   context.CancelFunc
 
 	// metaCache holds the content types of the variants most recently
 	// stored or served, so a hit does not read the variant's .meta file.
@@ -92,10 +96,29 @@ type Cache struct {
 	// deterministically pause inside that window to exercise
 	// concurrent stores against it; production code leaves it nil.
 	evictSourceBlobTestHook func(ContentHash)
+
+	// reconciliationPageSize is the most rows one read of a content table
+	// returns in the reconciliation pass and in Stats. newCache sets it to
+	// defaultReconciliationPageSize; tests set it smaller.
+	reconciliationPageSize int
+
+	// reconciliationReadTestHook, when set, is called after each of those
+	// reads with the number of rows the read covered, so tests can check
+	// that no read covers more than one page; production code leaves it
+	// nil.
+	reconciliationReadTestHook func(rows int)
 }
 
 // NewCache creates a new cache instance.
 func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
+	return newCache(db, config, defaultFreeSpaceProbe)
+}
+
+// newCache is NewCache with the free-space probe passed in, so tests
+// can fake the free space the default limit is worked out from.
+func newCache(
+	db *sql.DB, config CacheConfig, probe FreeSpaceProbeFunc,
+) (*Cache, error) {
 	log := config.Logger
 	if log == nil {
 		log = slog.Default()
@@ -112,10 +135,11 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 		log:              log,
 		disabled:         config.DisableDiskCache,
 		evictionPressure: make(chan struct{}, 1),
-		evictionStop:     make(chan struct{}),
 		evictionDone:     make(chan struct{}),
 		metaCache:        metaCache,
 		contentLocks:     newContentLock(),
+
+		reconciliationPageSize: defaultReconciliationPageSize,
 	}
 
 	if c.disabled {
@@ -147,6 +171,20 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 	c.variants = variants
 	c.srcMetadata = srcMetadata
 
+	if config.UseDefaultMaxBytes {
+		limit, err := c.computeDefaultMaxBytes(context.Background(), probe)
+		if err != nil {
+			return nil, err
+		}
+
+		c.config.MaxBytes = limit
+
+		log.Info("computed default cache size limit from free space and cache contents",
+			"cache_max_bytes", limit,
+			"cache_dir", filepath.Join(config.StateDir, "cache"),
+		)
+	}
+
 	return c, nil
 }
 
@@ -446,8 +484,9 @@ func (c *Cache) Stats(ctx context.Context) (*CacheStats, error) {
 		return nil, fmt.Errorf("failed to get cache stats: %w", err)
 	}
 
-	// Count and size the cached source images and processed variants. A
-	// disabled cache holds none, whatever rows an earlier run left.
+	// Count and size the cached source images and processed variants from
+	// their tables. A disabled cache holds none, whatever rows an earlier
+	// run left.
 	if !c.disabled {
 		err = c.db.QueryRowContext(ctx, `
 			SELECT (SELECT COUNT(*) FROM source_content)
@@ -457,7 +496,7 @@ func (c *Cache) Stats(ctx context.Context) (*CacheStats, error) {
 			c.log.Warn("failed to count cache items for stats", "error", err)
 		}
 
-		stats.TotalSizeBytes, err = c.UsageBytes(ctx)
+		stats.TotalSizeBytes, err = c.sumContentSizeBytes(ctx)
 		if err != nil {
 			c.log.Warn("failed to sum cache size for stats", "error", err)
 		}

internal/imgcache/cache_usage_internal_test.go

@@ -0,0 +1,265 @@
+package imgcache
+
+import (
+	"bytes"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// TestEvictionReadsTheUsageTotal adds, stores again, resizes and evicts
+// cache content, then drops both content tables. UsageBytes must still
+// report what the tables held, and an eviction pass under the limit must
+// still succeed: neither may sum the tables.
+func TestEvictionReadsTheUsageTotal(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+	ctx := t.Context()
+
+	kept := storeEvictionTestSource(t, cache, "total.example.com", "/kept.jpg",
+		bytes.Repeat([]byte{0x71}, 1000))
+	evicted := storeEvictionTestSource(t, cache, "total.example.com", "/evicted.jpg",
+		bytes.Repeat([]byte{0x72}, 700))
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne,
+		bytes.Repeat([]byte{0x73}, 500))
+	storeEvictionTestVariant(t, cache, testVariantKeyOne,
+		bytes.Repeat([]byte{0x74}, 300))
+	storeEvictionTestVariant(t, cache, testVariantKeyTwo,
+		bytes.Repeat([]byte{0x75}, 200))
+
+	// pixa never changes a source's size, but a statement that does must
+	// change the total too.
+	_, err := cache.db.ExecContext(ctx,
+		`UPDATE source_content SET size_bytes = 900 WHERE content_hash = ?`,
+		string(kept))
+	if err != nil {
+		t.Fatalf("failed to change the source's size: %v", err)
+	}
+
+	err = cache.evictSourceBlob(ctx, evicted)
+	if err != nil {
+		t.Fatalf("evictSourceBlob failed: %v", err)
+	}
+
+	err = cache.evictVariant(ctx, testVariantKeyTwo)
+	if err != nil {
+		t.Fatalf("evictVariant failed: %v", err)
+	}
+
+	_, err = cache.db.ExecContext(ctx,
+		`DROP TABLE source_content; DROP TABLE variant_content`)
+	if err != nil {
+		t.Fatalf("failed to drop the content tables: %v", err)
+	}
+
+	usage, err := cache.UsageBytes(ctx)
+	t.Logf("UsageBytes() = %d, error = %v", usage, err)
+
+	if err != nil {
+		t.Fatalf("UsageBytes() error = %v, want nil: it read a content table", err)
+	}
+
+	if usage != 1200 {
+		t.Errorf("UsageBytes() = %d, want 1200 (900 + 300)", usage)
+	}
+
+	err = cache.EvictToLimit(ctx)
+	if err != nil {
+		t.Errorf("EvictToLimit() error = %v, want nil: it read a content table", err)
+	}
+}
+
+// TestReconciliationCorrectsTheUsageTotal sets the total cache usage to a
+// wrong value and checks that a reconciliation pass, which sums both
+// content tables, puts it right.
+func TestReconciliationCorrectsTheUsageTotal(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+	ctx := t.Context()
+
+	storeEvictionTestSource(t, cache, "total.example.com", "/a.jpg",
+		bytes.Repeat([]byte{0x76}, 1000))
+	storeEvictionTestVariant(t, cache, testVariantKeyOne,
+		bytes.Repeat([]byte{0x77}, 500))
+
+	_, err := cache.db.ExecContext(ctx,
+		`UPDATE cache_usage SET total_size_bytes = 1 WHERE id = 1`)
+	if err != nil {
+		t.Fatalf("failed to set a wrong total: %v", err)
+	}
+
+	err = cache.reconcileAccounting(ctx)
+	if err != nil {
+		t.Fatalf("reconcileAccounting failed: %v", err)
+	}
+
+	usage, err := cache.UsageBytes(ctx)
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
+	if usage != 1500 {
+		t.Errorf("UsageBytes() after reconciliation = %d, want 1500 (1000 + 500)",
+			usage)
+	}
+}
+
+// TestUsageTotalNotCorrectedFromAnOlderSum stores a variant after the
+// change count was read, then offers a sum taken before the store as the
+// correction: the total must keep the stored variant, as that sum may
+// have missed it.
+func TestUsageTotalNotCorrectedFromAnOlderSum(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+	ctx := t.Context()
+
+	var changeCount int64
+
+	err := cache.db.QueryRowContext(ctx,
+		`SELECT change_count FROM cache_usage WHERE id = 1`,
+	).Scan(&changeCount)
+	if err != nil {
+		t.Fatalf("failed to read the change count: %v", err)
+	}
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne,
+		bytes.Repeat([]byte{0x78}, 500))
+
+	corrected, err := cache.correctUsageTotal(ctx, 0, changeCount)
+	if err != nil {
+		t.Fatalf("correctUsageTotal failed: %v", err)
+	}
+
+	if corrected {
+		t.Error("correctUsageTotal() = true, want false: content changed since the sum")
+	}
+
+	usage, err := cache.UsageBytes(ctx)
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
+	if usage != 500 {
+		t.Errorf("UsageBytes() = %d, want 500", usage)
+	}
+}
+
+// TestReconciliationReadsAPageAtATime stores five source images and five
+// variants, sets the page size to two rows and runs a reconciliation
+// pass. No read the pass makes of a content table, to check its rows or
+// to sum them, may cover more than two rows, so a request's query waits
+// for one page at most. Between them the reads must still cover every
+// row of both tables twice, once to check it and once to sum it, and the
+// sum must put a wrong total right.
+func TestReconciliationReadsAPageAtATime(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+	ctx := t.Context()
+
+	const pageSize = 2
+
+	cache.reconciliationPageSize = pageSize
+
+	// Sources of 100 bytes and variants of 10, five of each.
+	for i := range 5 {
+		content := []byte(strconv.Itoa(i))
+
+		storeEvictionTestSource(t, cache, "pages.example.com",
+			"/"+strconv.Itoa(i)+".jpg", bytes.Repeat(content, 100))
+		storeEvictionTestVariant(t, cache, VariantKey("aabbccdd000"+strconv.Itoa(i)),
+			bytes.Repeat(content, 10))
+	}
+
+	_, err := cache.db.ExecContext(ctx,
+		`UPDATE cache_usage SET total_size_bytes = 1 WHERE id = 1`)
+	if err != nil {
+		t.Fatalf("failed to set a wrong total: %v", err)
+	}
+
+	var rowsPerRead []int
+
+	cache.reconciliationReadTestHook = func(rows int) {
+		rowsPerRead = append(rowsPerRead, rows)
+	}
+
+	err = cache.reconcileAccounting(ctx)
+	if err != nil {
+		t.Fatalf("reconcileAccounting failed: %v", err)
+	}
+
+	t.Logf("rows covered by each read, in order: %v", rowsPerRead)
+
+	coveredRows := 0
+
+	for _, rows := range rowsPerRead {
+		if rows > pageSize {
+			t.Errorf("a read covered %d rows, want at most %d", rows, pageSize)
+		}
+
+		coveredRows += rows
+	}
+
+	// Ten rows, each read once to check it and once to sum it.
+	if coveredRows != 20 {
+		t.Errorf("the reads covered %d rows in all, want 20", coveredRows)
+	}
+
+	usage, err := cache.UsageBytes(ctx)
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
+	if usage != 550 {
+		t.Errorf("UsageBytes() after reconciliation = %d, want 550 (5*100 + 5*10)",
+			usage)
+	}
+}
+
+// TestSourceEvictionCandidatesComeFromTheIndex checks that the query
+// choosing source images to evict reads source_content in last access
+// order from its index, instead of reading and sorting the whole table.
+func TestSourceEvictionCandidatesComeFromTheIndex(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	rows, err := cache.db.QueryContext(t.Context(),
+		`EXPLAIN QUERY PLAN `+sourceCandidatesQuery, evictionBatchSize)
+	if err != nil {
+		t.Fatalf("EXPLAIN QUERY PLAN failed: %v", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var plan []string
+
+	for rows.Next() {
+		var id, parent, unused int
+
+		var detail string
+
+		err := rows.Scan(&id, &parent, &unused, &detail)
+		if err != nil {
+			t.Fatalf("failed to scan the query plan: %v", err)
+		}
+
+		plan = append(plan, detail)
+	}
+
+	err = rows.Err()
+	if err != nil {
+		t.Fatalf("query plan iteration failed: %v", err)
+	}
+
+	t.Logf("query plan: %q", plan)
+
+	if !strings.Contains(strings.Join(plan, "\n"), "idx_source_content_last_accessed") {
+		t.Errorf("the source candidate query does not use "+
+			"idx_source_content_last_accessed; plan: %q", plan)
+	}
+}

internal/imgcache/cachesize.go

@@ -0,0 +1,89 @@
+package imgcache
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math"
+	"path/filepath"
+	"syscall"
+)
+
+// DefaultCacheMaxBytesFloor is the minimum computed default for the
+// cache_max_bytes setting: 500 MiB. The floor applies only to the
+// computed default (when the key is omitted from the configuration),
+// never to explicitly configured values.
+const DefaultCacheMaxBytesFloor int64 = 524288000
+
+// freeSpaceFractionNumerator and freeSpaceFractionDenominator express
+// the 75% share used for the computed default limit as integer
+// arithmetic (dividing before multiplying avoids overflow).
+const (
+	freeSpaceFractionNumerator   uint64 = 3
+	freeSpaceFractionDenominator uint64 = 4
+)
+
+var errNegativeBlockSize = errors.New("statfs reported negative block size")
+
+// FreeSpaceProbeFunc reports the number of free bytes available on the
+// filesystem containing path. It is a function type so tests can
+// inject a fake probe instead of depending on the host disk.
+type FreeSpaceProbeFunc func(path string) (uint64, error)
+
+// defaultFreeSpaceProbe reports free filesystem bytes via statfs on
+// the given path, as available to unprivileged processes.
+func defaultFreeSpaceProbe(path string) (uint64, error) {
+	var stat syscall.Statfs_t
+
+	err := syscall.Statfs(path, &stat)
+	if err != nil {
+		return 0, err
+	}
+
+	if stat.Bsize < 0 {
+		return 0, fmt.Errorf("%w %d for %q", errNegativeBlockSize, stat.Bsize, path)
+	}
+
+	blockSize := uint64(stat.Bsize)
+
+	return stat.Bavail * blockSize, nil
+}
+
+// computeDefaultMaxBytes returns the default cache size limit: 75% of
+// the sum of the free bytes probe reports for <state_dir>/cache/ and
+// the bytes the cache already holds, with a floor of
+// DefaultCacheMaxBytesFloor. Counting what the cache holds keeps the
+// limit from shrinking as the cache fills.
+func (c *Cache) computeDefaultMaxBytes(
+	ctx context.Context, probe FreeSpaceProbeFunc,
+) (int64, error) {
+	cacheDir := filepath.Join(c.config.StateDir, "cache")
+
+	freeBytes, err := probe(cacheDir)
+	if err != nil {
+		return 0, fmt.Errorf(
+			"default cache_max_bytes: cannot determine free space for %q: %w",
+			cacheDir, err)
+	}
+
+	usedBytes, err := c.UsageBytes(ctx)
+	if err != nil {
+		return 0, err
+	}
+
+	// Both terms are at most math.MaxInt64, so the sum cannot overflow.
+	//nolint:gosec // G115: UsageBytes returns the total cache usage, never negative
+	spaceBytes := min(freeBytes, math.MaxInt64) + uint64(usedBytes)
+
+	computed := spaceBytes / freeSpaceFractionDenominator * freeSpaceFractionNumerator
+	computed = min(computed, math.MaxInt64)
+
+	// gosec cannot see that min() above bounds computed, so it reads
+	// this conversion as potentially overflowing. It cannot: computed is
+	// at most math.MaxInt64 on every path here.
+	//nolint:gosec // G115: clamped to MaxInt64 by min above
+	limit := int64(computed)
+	limit = max(limit, DefaultCacheMaxBytesFloor)
+
+	return limit, nil
+}

internal/imgcache/cachesize_internal_test.go

@@ -0,0 +1,188 @@
+package imgcache
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Static errors returned by the stub free-space probes below.
+var (
+	errTestStatfsFailed     = errors.New("statfs failed")
+	errTestProbeNotExpected = errors.New("probe must not be called")
+)
+
+// TestComputeDefaultMaxBytesCountsWhatTheCacheHolds verifies that the
+// default limit is 75% of the free space plus what the cache already
+// holds, so a cache filled to its limit keeps that limit across a
+// restart instead of shrinking to 75% of the space left free.
+func TestComputeDefaultMaxBytesCountsWhatTheCacheHolds(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	// Empty cache, 4 GiB free -> 3 GiB default.
+	got, err := cache.computeDefaultMaxBytes(t.Context(),
+		func(string) (uint64, error) { return 4294967296, nil })
+	if err != nil {
+		t.Fatalf("computeDefaultMaxBytes returned error: %v", err)
+	}
+
+	t.Logf("default for an empty cache with 4 GiB free: %d", got)
+
+	if got != 3221225472 {
+		t.Errorf("default for an empty cache = %d, want 3221225472 (75%% of 4 GiB)",
+			got)
+	}
+
+	// The cache now holds those 3 GiB, which leaves 1 GiB free.
+	_, err = cache.db.ExecContext(t.Context(),
+		`INSERT INTO variant_content (cache_key, size_bytes, content_type)
+		 VALUES (?, ?, ?)`,
+		string(testVariantKeyOne), 3221225472, testContentTypeWebP,
+	)
+	if err != nil {
+		t.Fatalf("failed to insert variant accounting row: %v", err)
+	}
+
+	got, err = cache.computeDefaultMaxBytes(t.Context(),
+		func(string) (uint64, error) { return 1073741824, nil })
+	if err != nil {
+		t.Fatalf("computeDefaultMaxBytes returned error: %v", err)
+	}
+
+	t.Logf("default for a cache holding 3 GiB with 1 GiB free: %d", got)
+
+	if got != 3221225472 {
+		t.Errorf("default for a cache holding 3 GiB with 1 GiB free = %d, "+
+			"want 3221225472 (75%% of 1 GiB + 3 GiB)", got)
+	}
+}
+
+// TestComputeDefaultMaxBytesAppliesFloor verifies that when 75% of the
+// free space plus what the cache holds is below 500 MiB, the default
+// is floored at DefaultCacheMaxBytesFloor.
+func TestComputeDefaultMaxBytesAppliesFloor(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name      string
+		freeBytes uint64
+	}{
+		{name: "100 MiB free", freeBytes: 104857600},
+		{name: "zero free", freeBytes: 0},
+		{name: "just below floor threshold", freeBytes: 699050665},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			cache, _ := newEvictionTestCache(t, 1<<30)
+
+			got, err := cache.computeDefaultMaxBytes(t.Context(),
+				func(string) (uint64, error) { return tc.freeBytes, nil })
+			if err != nil {
+				t.Fatalf("computeDefaultMaxBytes returned error: %v", err)
+			}
+
+			if got != DefaultCacheMaxBytesFloor {
+				t.Errorf("computeDefaultMaxBytes = %d, want floor %d",
+					got, DefaultCacheMaxBytesFloor)
+			}
+		})
+	}
+}
+
+// TestComputeDefaultMaxBytesPropagatesProbeError verifies that a
+// failing free-space probe produces an error naming cache_max_bytes,
+// instead of a silently wrong default.
+func TestComputeDefaultMaxBytesPropagatesProbeError(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	_, err := cache.computeDefaultMaxBytes(t.Context(),
+		func(string) (uint64, error) { return 0, errTestStatfsFailed })
+	if err == nil {
+		t.Fatal("probe failure must produce an error, got nil")
+	}
+
+	t.Logf("got expected error: %v", err)
+
+	if !strings.Contains(err.Error(), "cache_max_bytes") {
+		t.Errorf("error %q does not name cache_max_bytes", err.Error())
+	}
+}
+
+// TestNewCacheComputesDefaultMaxBytesWhenAsked verifies that with
+// UseDefaultMaxBytes set, the cache's limit becomes the computed
+// default, and that the probe is pointed at <state_dir>/cache/, which
+// must be created first so statfs measures the right filesystem.
+func TestNewCacheComputesDefaultMaxBytesWhenAsked(t *testing.T) {
+	t.Parallel()
+
+	stateDir := t.TempDir()
+	wantCacheDir := filepath.Join(stateDir, "cache")
+
+	var probedPath string
+
+	// 4 GiB free -> 3 GiB default.
+	probe := func(path string) (uint64, error) {
+		probedPath = path
+
+		info, err := os.Stat(path)
+		if err != nil || !info.IsDir() {
+			t.Errorf("cache directory %q was not created before probing: info=%v err=%v",
+				path, info, err)
+		}
+
+		return 4294967296, nil
+	}
+
+	cache, err := newCache(evictionTestDB(t), CacheConfig{
+		StateDir:           stateDir,
+		UseDefaultMaxBytes: true,
+	}, probe)
+	if err != nil {
+		t.Fatalf("newCache returned error: %v", err)
+	}
+
+	if cache.config.MaxBytes != 3221225472 {
+		t.Errorf("MaxBytes = %d, want computed default 3221225472",
+			cache.config.MaxBytes)
+	}
+
+	if probedPath != wantCacheDir {
+		t.Errorf("free space probed at %q, want cache directory %q",
+			probedPath, wantCacheDir)
+	}
+}
+
+// TestNewCacheKeepsExplicitMaxBytes verifies that without
+// UseDefaultMaxBytes the cache keeps MaxBytes exactly as given and
+// never consults the free-space probe.
+func TestNewCacheKeepsExplicitMaxBytes(t *testing.T) {
+	t.Parallel()
+
+	probe := func(string) (uint64, error) {
+		t.Error("free-space probe must not be consulted for explicit values")
+
+		return 0, errTestProbeNotExpected
+	}
+
+	cache, err := newCache(evictionTestDB(t), CacheConfig{
+		StateDir: t.TempDir(),
+		MaxBytes: 1024,
+	}, probe)
+	if err != nil {
+		t.Fatalf("newCache returned error: %v", err)
+	}
+
+	if cache.config.MaxBytes != 1024 {
+		t.Errorf("MaxBytes = %d, want explicit 1024 (no floor, no recompute)",
+			cache.config.MaxBytes)
+	}
+}

internal/imgcache/count_writes_internal_test.go

@@ -0,0 +1,116 @@
+package imgcache
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+// holdDatabase takes the one connection of the test service's database, so
+// that every other query waits for it, and returns the func that frees it.
+func holdDatabase(t *testing.T, svc *Service) func() {
+	t.Helper()
+
+	conn, err := svc.cache.db.Conn(t.Context())
+	if err != nil {
+		t.Fatalf("failed to take the database connection: %v", err)
+	}
+
+	release := func() { _ = conn.Close() }
+	t.Cleanup(release)
+
+	return release
+}
+
+// TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy holds the
+// database's one connection while a request whose fetch is held reaches its
+// deadline. The request must still return by its deadline with the
+// deadline's error, and its miss must be counted once the connection is free.
+func TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	const timeout = 200 * time.Millisecond
+
+	ctx, cancel := context.WithTimeout(t.Context(), timeout)
+	defer cancel()
+
+	results := startGet(ctx, svc, photoVariant(fixtures, 85, FitCover))
+
+	// The request has made its database reads by the time it fetches.
+	<-fetcher.started
+
+	releaseDatabase := holdDatabase(t, svc)
+
+	select {
+	case got := <-results:
+		deadline, _ := ctx.Deadline()
+		t.Logf("Get() returned %v after its deadline, error = %v",
+			time.Since(deadline), got.err)
+
+		if !errors.Is(got.err, context.DeadlineExceeded) {
+			t.Errorf("Get() error = %v, want %v", got.err, context.DeadlineExceeded)
+		}
+	case <-time.After(timeout + time.Second):
+		t.Fatal("request did not return by its deadline while the database was busy")
+	}
+
+	releaseDatabase()
+
+	waitCtx, cancelWait := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancelWait()
+
+	if !svc.WaitForCountWrites(waitCtx) {
+		t.Fatal("the miss was not counted once the database was free")
+	}
+
+	want := cacheStatsCounters{missCount: 1}
+	if got := readCacheStatsCounters(t, svc.cache); got != want {
+		t.Errorf("counters = %+v, want %+v", got, want)
+	}
+}
+
+// TestService_WaitForCountWrites holds the database's one connection while a
+// request past its deadline counts a miss. WaitForCountWrites must report the
+// count unwritten when its context ends, and written once the connection is
+// free.
+func TestService_WaitForCountWrites(t *testing.T) {
+	t.Parallel()
+
+	svc, _, _ := setupHeldFetchService(t)
+
+	releaseDatabase := holdDatabase(t, svc)
+
+	ended, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	svc.writeCount(ended, func(ctx context.Context) {
+		svc.cache.IncrementStats(ctx, false, 0)
+	})
+
+	shortCtx, cancelShort := context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancelShort()
+
+	written := svc.WaitForCountWrites(shortCtx)
+	t.Logf("WaitForCountWrites() while the database was busy = %t", written)
+
+	if written {
+		t.Fatal("WaitForCountWrites() = true while the database was busy")
+	}
+
+	releaseDatabase()
+
+	waitCtx, cancelWait := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancelWait()
+
+	if !svc.WaitForCountWrites(waitCtx) {
+		t.Fatal("WaitForCountWrites() = false once the database was free")
+	}
+
+	want := cacheStatsCounters{missCount: 1}
+	if got := readCacheStatsCounters(t, svc.cache); got != want {
+		t.Errorf("counters = %+v, want %+v", got, want)
+	}
+}

internal/imgcache/eviction.go

@@ -21,6 +21,12 @@ const DefaultEvictionInterval = 5 * time.Minute
 // and source blobs) one eviction pass fetches from the database.
 const evictionBatchSize = 100
 
+// defaultReconciliationPageSize is the most rows one read of the
+// reconciliation pass returns, unless a test sets
+// Cache.reconciliationPageSize smaller. Each read is a query of its own,
+// so a request waits for one page at most, however large the cache is.
+const defaultReconciliationPageSize = 1000
+
 // staleTempFileAge is how old an orphaned temp file (left behind by a
 // crashed write) must be before reconciliation removes it. Fresh temp
 // files may still belong to an in-flight store.
@@ -45,7 +51,9 @@ const fallbackContentType = "application/octet-stream"
 
 // UsageBytes returns the total number of bytes of cache content
 // tracked in the database (source content blobs plus processed
-// variants). It never scans the cache directories.
+// variants). It reads the total the database keeps up to date as rows
+// are added and removed, so it neither scans the cache directories nor
+// sums the tables.
 func (c *Cache) UsageBytes(ctx context.Context) (int64, error) {
 	if c.disabled {
 		return 0, nil
@@ -53,12 +61,11 @@ func (c *Cache) UsageBytes(ctx context.Context) (int64, error) {
 
 	var total int64
 
-	err := c.db.QueryRowContext(ctx, `
-		SELECT (SELECT COALESCE(SUM(size_bytes), 0) FROM source_content)
-		     + (SELECT COALESCE(SUM(size_bytes), 0) FROM variant_content)
-	`).Scan(&total)
+	err := c.db.QueryRowContext(ctx,
+		`SELECT total_size_bytes FROM cache_usage WHERE id = 1`,
+	).Scan(&total)
 	if err != nil {
-		return 0, fmt.Errorf("failed to compute cache usage: %w", err)
+		return 0, fmt.Errorf("failed to read cache usage: %w", err)
 	}
 
 	return total, nil
@@ -117,7 +124,10 @@ func (c *Cache) EvictToLimit(ctx context.Context) error {
 
 // evictBatch fetches one batch of LRU candidates across variants and
 // source blobs and evicts them oldest-first until excessBytes are
-// freed or the batch is exhausted. It returns the bytes freed.
+// freed or the batch is exhausted. It returns the bytes freed. A
+// candidate that fails once ctx is cancelled (every one started after
+// that fails at its first database call) ends the batch with ctx's
+// error, without a warning.
 func (c *Cache) evictBatch(ctx context.Context, excessBytes int64) (int64, error) {
 	candidates, err := c.evictionCandidates(ctx)
 	if err != nil {
@@ -133,6 +143,10 @@ func (c *Cache) evictBatch(ctx context.Context, excessBytes int64) (int64, error
 
 		err := c.evictCandidate(ctx, candidate)
 		if err != nil {
+			if ctx.Err() != nil {
+				return freed, ctx.Err()
+			}
+
 			c.log.Warn("failed to evict cache entry",
 				"cache_key", candidate.cacheKey,
 				"content_hash", candidate.contentHash,
@@ -229,16 +243,19 @@ func (c *Cache) variantCandidates(ctx context.Context) ([]evictionCandidate, err
 	return candidates, nil
 }
 
-// sourceCandidates returns the least recently used source blobs. Rows
-// written before the LRU column existed fall back to fetched_at.
+// sourceCandidatesQuery selects the least recently used source blobs. It
+// orders by the last_accessed_at column itself, not by an expression, so
+// SQLite reads the rows in order from that column's index instead of
+// sorting the whole table.
+const sourceCandidatesQuery = `
+	SELECT content_hash, size_bytes, last_accessed_at
+	FROM source_content
+	ORDER BY last_accessed_at ASC, content_hash ASC
+	LIMIT ?`
+
+// sourceCandidates returns the least recently used source blobs.
 func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, error) {
-	rows, err := c.db.QueryContext(ctx, `
-		SELECT content_hash, size_bytes,
-		       COALESCE(last_accessed_at, fetched_at, '1970-01-01 00:00:00') AS lru
-		FROM source_content
-		ORDER BY lru ASC, content_hash ASC
-		LIMIT ?
-	`, evictionBatchSize)
+	rows, err := c.db.QueryContext(ctx, sourceCandidatesQuery, evictionBatchSize)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query source eviction candidates: %w", err)
 	}
@@ -283,7 +300,7 @@ func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 
 	c.metaCache.Remove(cacheKey)
 
-	err = c.variants.DeleteWithMeta(cacheKey)
+	err = c.variants.Delete(cacheKey)
 	if err != nil {
 		return err
 	}
@@ -424,37 +441,44 @@ func (c *Cache) notifyWritePressure() {
 // startup and again on every periodic tick thereafter, and evicts to
 // the configured limit on the given periodic interval and on
 // write-pressure notifications. It is a no-op on a disabled cache or
-// when already started.
+// when already started. The goroutine outlives the caller, so it runs
+// with its own context, which StopEviction cancels.
 func (c *Cache) StartEviction(interval time.Duration) {
-	if c.disabled || c.evictionStarted {
+	if c.disabled || c.evictionCancel != nil {
 		return
 	}
 
-	c.evictionStarted = true
+	ctx, cancel := context.WithCancel(context.Background())
+	c.evictionCancel = cancel
 
-	go c.evictionLoop(interval)
+	go c.evictionLoop(ctx, interval)
 }
 
-// StopEviction stops the background eviction goroutine and waits for
-// it to exit. It is safe to call when eviction was never started, and
-// safe to call more than once.
-func (c *Cache) StopEviction() {
-	if !c.evictionStarted {
-		return
+// StopEviction cancels the background eviction goroutine, which
+// interrupts a pass in progress, and waits for it to exit or for ctx to
+// end, whichever comes first. In the second case it returns an error
+// wrapping ctx's error. It is safe to call when eviction was never
+// started, and safe to call more than once.
+func (c *Cache) StopEviction(ctx context.Context) error {
+	if c.evictionCancel == nil {
+		return nil
 	}
 
-	c.evictionStopOnce.Do(func() {
-		close(c.evictionStop)
-		<-c.evictionDone
-	})
+	c.evictionCancel()
+
+	select {
+	case <-c.evictionDone:
+		return nil
+	case <-ctx.Done():
+		return fmt.Errorf("cache eviction still running: %w", ctx.Err())
+	}
 }
 
-// evictionLoop is the body of the background eviction goroutine.
-func (c *Cache) evictionLoop(interval time.Duration) {
+// evictionLoop is the body of the background eviction goroutine. It
+// returns when ctx is cancelled, and starts no pass after that.
+func (c *Cache) evictionLoop(ctx context.Context, interval time.Duration) {
 	defer close(c.evictionDone)
 
-	ctx := context.Background()
-
 	c.runReconciliationPass(ctx)
 	c.runEvictionPass(ctx)
 
@@ -463,7 +487,7 @@ func (c *Cache) evictionLoop(interval time.Duration) {
 
 	for {
 		select {
-		case <-c.evictionStop:
+		case <-ctx.Done():
 			return
 		case <-ticker.C:
 			// Reconciliation walks the cache directories, so it only
@@ -484,8 +508,13 @@ func (c *Cache) evictionLoop(interval time.Duration) {
 }
 
 // runEvictionPass runs one eviction pass, logging failures instead of
-// propagating them (the loop must keep running).
+// propagating them (the loop must keep running). It does nothing once
+// ctx is cancelled.
 func (c *Cache) runEvictionPass(ctx context.Context) {
+	if ctx.Err() != nil {
+		return
+	}
+
 	err := c.EvictToLimit(ctx)
 	if err != nil {
 		c.log.Warn("cache eviction pass failed", "error", err)
@@ -493,8 +522,13 @@ func (c *Cache) runEvictionPass(ctx context.Context) {
 }
 
 // runReconciliationPass runs one reconciliation pass, logging failures
-// instead of propagating them (the loop must keep running).
+// instead of propagating them (the loop must keep running). It does
+// nothing once ctx is cancelled.
 func (c *Cache) runReconciliationPass(ctx context.Context) {
+	if ctx.Err() != nil {
+		return
+	}
+
 	err := c.reconcileAccounting(ctx)
 	if err != nil {
 		c.log.Warn("cache accounting reconciliation failed", "error", err)
@@ -508,10 +542,13 @@ func (c *Cache) runReconciliationPass(ctx context.Context) {
 // (or whose accounting insert failed, e.g. StoreVariant's best-effort
 // insert under transient DB contention), drops accounting rows whose
 // files are missing, removes source blob files the database does not
-// know (and rows whose files are gone), and sweeps stale temp files
-// left behind by crashed writes. Running it periodically, not just
-// once, bounds how long such drift can accumulate unaccounted for on a
-// long-running process to one eviction interval.
+// know (and rows whose files are gone), sweeps stale temp files left
+// behind by crashed writes, and last checks the total cache usage
+// against the tables. It reads the tables a page at a time. Running it
+// periodically, not just once, bounds how long such drift can
+// accumulate unaccounted for on a long-running process to one eviction
+// interval. Once ctx is cancelled, it stops at the next file or row and
+// returns ctx's error.
 func (c *Cache) reconcileAccounting(ctx context.Context) error {
 	if c.disabled {
 		return nil
@@ -537,7 +574,7 @@ func (c *Cache) reconcileAccounting(ctx context.Context) error {
 		return err
 	}
 
-	return nil
+	return c.reconcileUsageTotal(ctx)
 }
 
 // reconcileVariantFiles walks the variant storage directory, adopting
@@ -546,6 +583,10 @@ func (c *Cache) reconcileVariantFiles(ctx context.Context) error {
 	return filepath.WalkDir(
 		c.variants.baseDir,
 		func(path string, entry fs.DirEntry, err error) error {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
 			if err != nil || entry.IsDir() {
 				return err
 			}
@@ -628,42 +669,63 @@ func (c *Cache) variantContentTypeFromSidecar(variantPath string) string {
 // reconcileVariantRows drops accounting rows whose variant files are
 // missing, so the database never references deleted content.
 func (c *Cache) reconcileVariantRows(ctx context.Context) error {
-	keys, err := c.allVariantKeys(ctx)
-	if err != nil {
-		return err
-	}
+	var after VariantKey
 
-	for _, key := range keys {
-		if c.variants.Exists(key) {
-			continue
-		}
-
-		_, err := c.db.ExecContext(ctx,
-			`DELETE FROM variant_content WHERE cache_key = ?`, string(key))
+	for {
+		keys, err := c.variantKeysAfter(ctx, after)
 		if err != nil {
-			return fmt.Errorf("failed to drop stale variant accounting row: %w", err)
+			return err
 		}
 
-		c.log.Info("dropped accounting row for missing variant file", "cache_key", key)
+		if c.reconciliationReadTestHook != nil {
+			c.reconciliationReadTestHook(len(keys))
+		}
+
+		if len(keys) == 0 {
+			return nil
+		}
+
+		for _, key := range keys {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
+			if c.variants.Exists(key) {
+				continue
+			}
+
+			_, err := c.db.ExecContext(ctx,
+				`DELETE FROM variant_content WHERE cache_key = ?`, string(key))
+			if err != nil {
+				return fmt.Errorf("failed to drop stale variant accounting row: %w", err)
+			}
+
+			c.log.Info("dropped accounting row for missing variant file", "cache_key", key)
+		}
+
+		after = keys[len(keys)-1]
 	}
-
-	return nil
 }
 
-// allVariantKeys returns every tracked variant cache key.
-func (c *Cache) allVariantKeys(ctx context.Context) ([]VariantKey, error) {
-	return queryStringColumn[VariantKey](ctx, c.db,
-		`SELECT cache_key FROM variant_content`, "variant keys", "variant key")
+// variantKeysAfter returns, in order, up to c.reconciliationPageSize
+// tracked variant cache keys that sort after the given one.
+func (c *Cache) variantKeysAfter(
+	ctx context.Context, after VariantKey,
+) ([]VariantKey, error) {
+	return queryStringColumn[VariantKey](ctx, c.db, `
+		SELECT cache_key FROM variant_content
+		WHERE cache_key > ? ORDER BY cache_key LIMIT ?
+	`, "variant keys", "variant key", string(after), c.reconciliationPageSize)
 }
 
-// queryStringColumn runs a single-column query and returns the column
-// values as T. plural names the set for the query and scan failure
-// messages; singular names one row for the scan and iteration failure
-// messages.
+// queryStringColumn runs a single-column query with args and returns the
+// column values as T. plural names the set for the query and scan
+// failure messages; singular names one row for the scan and iteration
+// failure messages.
 func queryStringColumn[T ~string](
-	ctx context.Context, db *sql.DB, query, plural, singular string,
+	ctx context.Context, db *sql.DB, query, plural, singular string, args ...any,
 ) ([]T, error) {
-	rows, err := db.QueryContext(ctx, query)
+	rows, err := db.QueryContext(ctx, query, args...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query %s: %w", plural, err)
 	}
@@ -699,6 +761,10 @@ func (c *Cache) reconcileSourceFiles(ctx context.Context) error {
 	return filepath.WalkDir(
 		c.srcContent.baseDir,
 		func(path string, entry fs.DirEntry, err error) error {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
 			if err != nil || entry.IsDir() {
 				return err
 			}
@@ -754,34 +820,183 @@ func (c *Cache) removeUntrackedSourceFile(
 // reconcileSourceRows removes source_content rows (and their metadata
 // references and sidecars) whose blob files are missing on disk.
 func (c *Cache) reconcileSourceRows(ctx context.Context) error {
-	hashes, err := c.allSourceContentHashes(ctx)
-	if err != nil {
-		return err
-	}
+	var after ContentHash
 
-	for _, hash := range hashes {
-		if c.srcContent.Exists(hash) {
-			continue
-		}
-
-		// The blob file is already gone; evictSourceBlob removes the
-		// rows and sidecars and tolerates the missing file.
-		err := c.evictSourceBlob(ctx, hash)
+	for {
+		hashes, err := c.sourceContentHashesAfter(ctx, after)
 		if err != nil {
 			return err
 		}
 
-		c.log.Info("dropped rows for missing source content file", "content_hash", hash)
+		if c.reconciliationReadTestHook != nil {
+			c.reconciliationReadTestHook(len(hashes))
+		}
+
+		if len(hashes) == 0 {
+			return nil
+		}
+
+		for _, hash := range hashes {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
+			if c.srcContent.Exists(hash) {
+				continue
+			}
+
+			// The blob file is already gone; evictSourceBlob removes the
+			// rows and sidecars and tolerates the missing file.
+			err := c.evictSourceBlob(ctx, hash)
+			if err != nil {
+				return err
+			}
+
+			c.log.Info("dropped rows for missing source content file", "content_hash", hash)
+		}
+
+		after = hashes[len(hashes)-1]
 	}
+}
+
+// sourceContentHashesAfter returns, in order, up to
+// c.reconciliationPageSize tracked source content hashes that sort after
+// the given one.
+func (c *Cache) sourceContentHashesAfter(
+	ctx context.Context, after ContentHash,
+) ([]ContentHash, error) {
+	return queryStringColumn[ContentHash](ctx, c.db, `
+		SELECT content_hash FROM source_content
+		WHERE content_hash > ? ORDER BY content_hash LIMIT ?
+	`, "source content hashes", "content hash", string(after),
+		c.reconciliationPageSize)
+}
+
+// Each of these queries sums size_bytes over the next page of rows of
+// one content table, the rows that sort after a key, and returns the
+// page's last key, the sum and the number of rows in the page. Past the
+// last row the page has no rows and the key is NULL.
+const (
+	sourceSizePageQuery = `
+		SELECT MAX(content_hash), COALESCE(SUM(size_bytes), 0), COUNT(*)
+		FROM (
+			SELECT content_hash, size_bytes FROM source_content
+			WHERE content_hash > ? ORDER BY content_hash LIMIT ?
+		)`
+	variantSizePageQuery = `
+		SELECT MAX(cache_key), COALESCE(SUM(size_bytes), 0), COUNT(*)
+		FROM (
+			SELECT cache_key, size_bytes FROM variant_content
+			WHERE cache_key > ? ORDER BY cache_key LIMIT ?
+		)`
+)
+
+// sumContentSizeBytes sums size_bytes over both content tables, a page
+// of rows per query.
+func (c *Cache) sumContentSizeBytes(ctx context.Context) (int64, error) {
+	sourceBytes, err := c.sumSizeBytesInPages(ctx, sourceSizePageQuery)
+	if err != nil {
+		return 0, err
+	}
+
+	variantBytes, err := c.sumSizeBytesInPages(ctx, variantSizePageQuery)
+	if err != nil {
+		return 0, err
+	}
+
+	return sourceBytes + variantBytes, nil
+}
+
+// sumSizeBytesInPages runs pageQuery, one of the size page queries
+// above, from the first page to the last and adds up the page sums.
+func (c *Cache) sumSizeBytesInPages(
+	ctx context.Context, pageQuery string,
+) (int64, error) {
+	var total int64
+
+	after := ""
+
+	for {
+		var lastKey sql.NullString
+
+		var pageBytes int64
+
+		var pageRows int
+
+		err := c.db.QueryRowContext(ctx, pageQuery, after, c.reconciliationPageSize).
+			Scan(&lastKey, &pageBytes, &pageRows)
+		if err != nil {
+			return 0, fmt.Errorf("failed to sum cache content sizes: %w", err)
+		}
+
+		if c.reconciliationReadTestHook != nil {
+			c.reconciliationReadTestHook(pageRows)
+		}
+
+		if pageRows == 0 {
+			return total, nil
+		}
+
+		total += pageBytes
+		after = lastKey.String
+	}
+}
+
+// reconcileUsageTotal checks the total cache usage the database keeps
+// against size_bytes summed over both content tables, and corrects the
+// total when they differ.
+func (c *Cache) reconcileUsageTotal(ctx context.Context) error {
+	var totalBytes, changeCount int64
+
+	err := c.db.QueryRowContext(ctx,
+		`SELECT total_size_bytes, change_count FROM cache_usage WHERE id = 1`,
+	).Scan(&totalBytes, &changeCount)
+	if err != nil {
+		return fmt.Errorf("failed to read cache usage: %w", err)
+	}
+
+	sumBytes, err := c.sumContentSizeBytes(ctx)
+	if err != nil {
+		return err
+	}
+
+	if sumBytes == totalBytes {
+		return nil
+	}
+
+	corrected, err := c.correctUsageTotal(ctx, sumBytes, changeCount)
+	if err != nil || !corrected {
+		return err
+	}
+
+	c.log.Warn("corrected total cache usage to the sum of the content tables",
+		"previous_usage_bytes", totalBytes, "usage_bytes", sumBytes)
 
 	return nil
 }
 
-// allSourceContentHashes returns every tracked source content hash.
-func (c *Cache) allSourceContentHashes(ctx context.Context) ([]ContentHash, error) {
-	return queryStringColumn[ContentHash](ctx, c.db,
-		`SELECT content_hash FROM source_content`,
-		"source content hashes", "content hash")
+// correctUsageTotal sets the total cache usage to sumBytes, a sum of the
+// content tables taken when the change count was changeCount, and
+// reports whether it did. If a row was added, removed or resized since,
+// the count has moved and the total is left alone: the sum may have
+// missed that change, and the next pass checks again.
+func (c *Cache) correctUsageTotal(
+	ctx context.Context, sumBytes, changeCount int64,
+) (bool, error) {
+	result, err := c.db.ExecContext(ctx, `
+		UPDATE cache_usage SET total_size_bytes = ?
+		WHERE id = 1 AND change_count = ?
+	`, sumBytes, changeCount)
+	if err != nil {
+		return false, fmt.Errorf("failed to correct cache usage: %w", err)
+	}
+
+	affected, err := result.RowsAffected()
+	if err != nil {
+		return false, fmt.Errorf("failed to read cache usage correction: %w", err)
+	}
+
+	return affected > 0, nil
 }
 
 // sweepStaleTempFile removes a temp file left behind by a crashed

internal/imgcache/eviction_internal_test.go

@@ -4,9 +4,12 @@ import (
 	"bytes"
 	"context"
 	"database/sql"
+	"errors"
 	"io/fs"
+	"log/slog"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -657,7 +660,7 @@ func TestEvictionRunsUnderWritePressure(t *testing.T) {
 	// An interval far longer than the test ensures only write
 	// pressure can trigger eviction here.
 	cache.StartEviction(time.Hour)
-	defer cache.StopEviction()
+	defer func() { _ = cache.StopEviction(t.Context()) }()
 
 	keys := []VariantKey{
 		testVariantKeyOne, testVariantKeyTwo, testVariantKeyThree,
@@ -678,6 +681,11 @@ func TestEvictionRunsUnderWritePressure(t *testing.T) {
 	assertNoDanglingReferences(t, cache)
 }
 
+// TestEvictionRunsOnPeriodicSchedule writes three variant files straight
+// to disk, bypassing StoreVariant, so they have no accounting rows and no
+// write-pressure notification fires. Only a periodic reconciliation pass
+// can then adopt them, and only the eviction pass that follows it can
+// evict them.
 func TestEvictionRunsOnPeriodicSchedule(t *testing.T) {
 	t.Parallel()
 
@@ -685,12 +693,28 @@ func TestEvictionRunsOnPeriodicSchedule(t *testing.T) {
 
 	cache, _ := newEvictionTestCache(t, limit)
 
-	// Start the evictor while the cache is empty, then create tracked
-	// over-limit state WITHOUT going through the store methods, so no
-	// write-pressure notification fires and only the periodic ticker
-	// can trigger eviction.
+	// Hold the test database's only connection, so the startup pass
+	// waits for it after walking the still empty variant directory: the
+	// files written while it waits are first seen by a periodic pass.
+	conn, err := cache.db.Conn(t.Context())
+	if err != nil {
+		t.Fatalf("failed to take the database connection: %v", err)
+	}
+
+	defer func() { _ = conn.Close() }()
+
 	cache.StartEviction(100 * time.Millisecond)
-	defer cache.StopEviction()
+	defer func() { _ = cache.StopEviction(t.Context()) }()
+
+	deadline := time.Now().Add(5 * time.Second)
+
+	for cache.db.Stats().WaitCount == 0 {
+		if time.Now().After(deadline) {
+			t.Fatal("the startup pass never waited for the database")
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
 
 	keys := []VariantKey{
 		testVariantKeyOne, testVariantKeyTwo, testVariantKeyThree,
@@ -700,25 +724,43 @@ func TestEvictionRunsOnPeriodicSchedule(t *testing.T) {
 	for i, key := range keys {
 		content := bytes.Repeat([]byte{fills[i]}, 1000)
 
-		_, err := cache.variants.Store(key, bytes.NewReader(content), "image/webp")
+		_, err = cache.variants.Store(key, bytes.NewReader(content), "image/webp")
 		if err != nil {
 			t.Fatalf("failed to store variant file: %v", err)
 		}
+	}
 
-		_, err = cache.db.ExecContext(t.Context(),
-			`INSERT INTO variant_content (cache_key, size_bytes, content_type)
-			 VALUES (?, ?, ?)`,
-			string(key), len(content), "image/webp",
-		)
-		if err != nil {
-			t.Fatalf("failed to insert variant accounting row: %v", err)
+	_ = conn.Close()
+
+	// Only one of the 1000-byte files fits under the limit: wait until
+	// the evictor has removed the other two.
+	stored := len(keys)
+	deadline = time.Now().Add(5 * time.Second)
+
+	for stored > 1 && time.Now().Before(deadline) {
+		time.Sleep(25 * time.Millisecond)
+
+		stored = 0
+
+		for _, key := range keys {
+			if cache.variants.Exists(key) {
+				stored++
+			}
 		}
 	}
 
-	usage := waitForUsageAtOrBelow(t, cache, limit, 5*time.Second)
+	if stored > 1 {
+		t.Fatalf("periodic schedule did not trigger eviction: %d of %d "+
+			"variant files still on disk, want at most 1", stored, len(keys))
+	}
+
+	usage, err := cache.UsageBytes(t.Context())
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
 	if usage > limit {
-		t.Errorf("periodic schedule did not trigger eviction: usage = %d, want <= %d",
-			usage, limit)
+		t.Errorf("usage after eviction = %d, want <= %d", usage, limit)
 	}
 
 	assertNoDanglingReferences(t, cache)
@@ -751,7 +793,7 @@ func TestStartEvictionReconcilesAccountingWithDisk(t *testing.T) {
 	}
 
 	cache.StartEviction(time.Hour)
-	defer cache.StopEviction()
+	defer func() { _ = cache.StopEviction(t.Context()) }()
 
 	deadline := time.Now().Add(5 * time.Second)
 
@@ -805,15 +847,28 @@ func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 
 	cache, _ := newEvictionTestCache(t, 1<<30)
 
-	const interval = 100 * time.Millisecond
+	// Hold the test database's only connection, so the startup pass
+	// waits for it after walking the still empty variant directory: the
+	// file written while it waits is first seen by a periodic pass.
+	conn, err := cache.db.Conn(t.Context())
+	if err != nil {
+		t.Fatalf("failed to take the database connection: %v", err)
+	}
 
-	cache.StartEviction(interval)
-	defer cache.StopEviction()
+	defer func() { _ = conn.Close() }()
 
-	// Let startup reconciliation run and settle on an empty cache
-	// before introducing the untracked file, so the adoption we assert
-	// below can only be the work of a later, periodic pass.
-	time.Sleep(3 * interval)
+	cache.StartEviction(100 * time.Millisecond)
+	defer func() { _ = cache.StopEviction(t.Context()) }()
+
+	deadline := time.Now().Add(5 * time.Second)
+
+	for cache.db.Stats().WaitCount == 0 {
+		if time.Now().After(deadline) {
+			t.Fatal("the startup pass never waited for the database")
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
 
 	// Simulate a variant whose accounting insert failed after the
 	// process was already running and serving requests: the content
@@ -822,14 +877,16 @@ func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 	// insert had failed and only the file write had succeeded.
 	untracked := bytes.Repeat([]byte{0x41}, 900)
 
-	_, err := cache.variants.Store(
+	_, err = cache.variants.Store(
 		"aabbccdd0099", bytes.NewReader(untracked), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to store untracked variant file: %v", err)
 	}
 
-	deadline := time.Now().Add(5 * time.Second)
+	_ = conn.Close()
+
+	deadline = time.Now().Add(5 * time.Second)
 
 	var usage int64
 
@@ -862,6 +919,242 @@ func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 	}
 }
 
+// TestStopEvictionInterruptsPassInProgress holds the test database's
+// only connection, so the startup reconciliation pass waits for it, and
+// checks that StopEviction stops that pass instead of waiting for the
+// connection to come free, and that the stop logs one warning: the
+// interrupted reconciliation's, with no eviction pass started after it.
+func TestStopEvictionInterruptsPassInProgress(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	var logBuf bytes.Buffer
+
+	cache.log = slog.New(slog.NewJSONHandler(&logBuf, nil))
+
+	conn, err := cache.db.Conn(t.Context())
+	if err != nil {
+		t.Fatalf("failed to take the database connection: %v", err)
+	}
+
+	defer func() { _ = conn.Close() }()
+
+	cache.StartEviction(time.Hour)
+
+	// The pass is in progress once it waits for the connection.
+	deadline := time.Now().Add(5 * time.Second)
+
+	for cache.db.Stats().WaitCount == 0 {
+		if time.Now().After(deadline) {
+			t.Fatal("the reconciliation pass never waited for the database")
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	ctx, cancel := context.WithTimeout(t.Context(), 5*time.Second)
+	defer cancel()
+
+	err = cache.StopEviction(ctx)
+	t.Logf("StopEviction() error = %v", err)
+
+	if err != nil {
+		t.Fatalf("StopEviction() error = %v, want nil: the pass waiting for "+
+			"the database did not stop", err)
+	}
+
+	t.Logf("log output: %s", logBuf.String())
+
+	warnings := strings.Count(logBuf.String(), `"level":"WARN"`)
+	if warnings != 1 {
+		t.Errorf("the stop logged %d warnings, want 1", warnings)
+	}
+}
+
+// TestEvictToLimitStopsAtNextCandidateOnceCancelled cancels the context
+// while the oldest of three source blobs is being evicted, and checks that
+// EvictToLimit then returns context.Canceled without evicting the other
+// two or logging a warning for either of them.
+func TestEvictToLimitStopsAtNextCandidateOnceCancelled(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1)
+
+	var logBuf bytes.Buffer
+
+	cache.log = slog.New(slog.NewJSONHandler(&logBuf, nil))
+
+	hashes := []ContentHash{
+		storeEvictionTestSource(t, cache, "cancel.example.com", "/a.jpg",
+			bytes.Repeat([]byte{0x61}, 1000)),
+		storeEvictionTestSource(t, cache, "cancel.example.com", "/b.jpg",
+			bytes.Repeat([]byte{0x62}, 1000)),
+		storeEvictionTestSource(t, cache, "cancel.example.com", "/c.jpg",
+			bytes.Repeat([]byte{0x63}, 1000)),
+	}
+
+	base := time.Now().Add(-time.Hour)
+
+	for i, hash := range hashes {
+		setSourceLastAccessed(t, cache, hash, base.Add(time.Duration(i)*time.Minute))
+	}
+
+	ctx, cancel := context.WithCancel(t.Context())
+	defer cancel()
+
+	cache.evictSourceBlobTestHook = func(ContentHash) { cancel() }
+
+	err := cache.EvictToLimit(ctx)
+	t.Logf("EvictToLimit() error = %v", err)
+	t.Logf("log output: %s", logBuf.String())
+
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("EvictToLimit() error = %v, want context.Canceled", err)
+	}
+
+	if cache.srcContent.Exists(hashes[0]) {
+		t.Errorf("source blob %s, evicted when the context was cancelled, "+
+			"is still on disk", hashes[0])
+	}
+
+	for _, hash := range hashes[1:] {
+		if !cache.srcContent.Exists(hash) {
+			t.Errorf("source blob %s was evicted after the context was cancelled", hash)
+		}
+	}
+
+	if strings.Contains(logBuf.String(), `"level":"WARN"`) {
+		t.Errorf("EvictToLimit logged a warning after the context was cancelled")
+	}
+
+	assertNoDanglingReferences(t, cache)
+}
+
+// TestStopEvictionReturnsWhenItsContextEnds pauses an eviction pass where
+// cancellation cannot reach it, after a source blob's rows are deleted and
+// before its file is removed, and checks that StopEviction returns its
+// context's error when that context ends instead of waiting for the pass.
+// Once the pass goes on, the goroutine exits and no row points at a
+// missing file.
+func TestStopEvictionReturnsWhenItsContextEnds(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1)
+
+	paused := make(chan struct{})
+	resume := make(chan struct{})
+
+	cache.evictSourceBlobTestHook = func(ContentHash) {
+		close(paused)
+		<-resume
+	}
+
+	hash := storeEvictionTestSource(t, cache, "stop.example.com", "/a.jpg",
+		bytes.Repeat([]byte{0x61}, 1000))
+
+	cache.StartEviction(time.Hour)
+
+	select {
+	case <-paused:
+	case <-time.After(5 * time.Second):
+		t.Fatal("the eviction pass never reached the source blob")
+	}
+
+	ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
+	defer cancel()
+
+	err := cache.StopEviction(ctx)
+	t.Logf("StopEviction() error = %v", err)
+
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Errorf("StopEviction() error = %v, want context.DeadlineExceeded", err)
+	}
+
+	close(resume)
+
+	err = cache.StopEviction(t.Context())
+	if err != nil {
+		t.Fatalf("second StopEviction() error = %v, want nil", err)
+	}
+
+	assertNoDanglingReferences(t, cache)
+
+	if cache.srcContent.Exists(hash) {
+		t.Errorf("source blob %s is still on disk after its rows were deleted", hash)
+	}
+}
+
+// TestReconciliationWalksStopOnceCancelled checks that both directory
+// walks of a reconciliation pass return the context's error once it is
+// cancelled, leaving in place a stale temp file they would otherwise
+// remove.
+func TestReconciliationWalksStopOnceCancelled(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	staleTime := time.Now().Add(-2 * staleTempFileAge)
+
+	walks := map[string]func(context.Context) error{
+		cache.variants.baseDir:   cache.reconcileVariantFiles,
+		cache.srcContent.baseDir: cache.reconcileSourceFiles,
+	}
+
+	for dir, walk := range walks {
+		tempFile := filepath.Join(dir, tempFilePrefix+"stale")
+
+		err := os.WriteFile(tempFile, []byte("partial"), 0o600)
+		if err != nil {
+			t.Fatalf("failed to write temp file: %v", err)
+		}
+
+		err = os.Chtimes(tempFile, staleTime, staleTime)
+		if err != nil {
+			t.Fatalf("failed to backdate temp file: %v", err)
+		}
+
+		err = walk(ctx)
+		t.Logf("walk of %s: error = %v", dir, err)
+
+		if !errors.Is(err, context.Canceled) {
+			t.Errorf("walk of %s: error = %v, want context.Canceled", dir, err)
+		}
+
+		_, err = os.Stat(tempFile)
+		if err != nil {
+			t.Errorf("walk of %s went on after cancellation: %v", dir, err)
+		}
+	}
+}
+
+// TestReconciliationPassLogsNoWarningOnceCancelled checks that a
+// reconciliation pass run with an already cancelled context logs no
+// warning, so a periodic tick the loop takes after a stop adds no
+// warning to the one from the pass the stop interrupted.
+func TestReconciliationPassLogsNoWarningOnceCancelled(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	var logBuf bytes.Buffer
+
+	cache.log = slog.New(slog.NewJSONHandler(&logBuf, nil))
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	cache.runReconciliationPass(ctx)
+	t.Logf("log output: %s", logBuf.String())
+
+	if strings.Contains(logBuf.String(), `"level":"WARN"`) {
+		t.Errorf("runReconciliationPass logged a warning with a cancelled context")
+	}
+}
+
 // TestEvictSourceBlobExcludesConcurrentStoreOfIdenticalContent exercises
 // the exact TOCTOU window between evictSourceBlob's row-deletion
 // transaction commit and its content file unlink: a concurrent

internal/imgcache/imgcache.go

@@ -5,7 +5,6 @@ import (
 	"context"
 	"errors"
 	"io"
-	"net/url"
 	"time"
 )
 
@@ -22,7 +21,13 @@ const (
 	FormatPNG      ImageFormat = "png"
 	FormatWebP     ImageFormat = "webp"
 	FormatAVIF     ImageFormat = "avif"
+	FormatJXL      ImageFormat = "jxl"
 	FormatGIF      ImageFormat = "gif"
+
+	// FormatAuto stands for JPEG XL, AVIF, WebP or JPEG, chosen for each
+	// request from its Accept header once the URL's signature or token has
+	// been checked; it is never processed or cached as itself.
+	FormatAuto ImageFormat = "auto"
 )
 
 // Size represents requested image dimensions
@@ -154,9 +159,6 @@ type ImageCache interface {
 	// Warm pre-fetches and caches an image without returning it
 	Warm(ctx context.Context, req *ImageRequest) error
 
-	// Purge removes a cached image
-	Purge(ctx context.Context, req *ImageRequest) error
-
 	// Stats returns cache statistics
 	Stats(ctx context.Context) (*CacheStats, error)
 }
@@ -176,29 +178,3 @@ type CacheStats struct {
 	// HitRate is HitCount / (HitCount + MissCount)
 	HitRate float64
 }
-
-// SignatureValidator validates request signatures
-type SignatureValidator interface {
-	// Validate checks if the signature is valid for the request
-	Validate(req *ImageRequest) error
-	// Generate creates a signature for a request
-	Generate(req *ImageRequest) string
-}
-
-// Allowlist checks if a URL is allowlisted (no signature required)
-type Allowlist interface {
-	// IsAllowlisted returns true if the URL doesn't require a signature
-	IsAllowlisted(u *url.URL) bool
-}
-
-// Storage handles persistent storage of cached content
-type Storage interface {
-	// Store saves content and returns its hash
-	Store(ctx context.Context, content io.Reader) (hash string, err error)
-	// Load retrieves content by hash
-	Load(ctx context.Context, hash string) (io.ReadCloser, error)
-	// Delete removes content by hash
-	Delete(ctx context.Context, hash string) error
-	// Exists checks if content exists
-	Exists(ctx context.Context, hash string) (bool, error)
-}

internal/imgcache/service.go

@@ -9,10 +9,12 @@ import (
 	"log/slog"
 	"net/url"
 	"runtime/debug"
+	"sync"
 	"time"
 
 	"github.com/dustin/go-humanize"
 	"github.com/getsentry/sentry-go"
+	"github.com/go-chi/chi/v5/middleware"
 	"golang.org/x/sync/singleflight"
 	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
@@ -35,13 +37,17 @@ type Service struct {
 	// variantsInProgress lets the requests that miss the same variant at the
 	// same time share one fetch and one transcode.
 	variantsInProgress singleflight.Group
+	// countWrites holds the count writes writeCount has started, for
+	// WaitForCountWrites.
+	countWrites sync.WaitGroup
 }
 
 // ServiceConfig holds configuration for the image service.
 type ServiceConfig struct {
 	// Cache is the cache instance
 	Cache *Cache
-	// FetcherConfig configures the upstream fetcher (ignored if Fetcher is set)
+	// FetcherConfig configures the upstream fetcher built when Fetcher is
+	// not set. Its AllowHTTP and MaxResponseSize are used either way.
 	FetcherConfig *httpfetcher.Config
 	// Fetcher is an optional custom fetcher (for testing)
 	Fetcher httpfetcher.Fetcher
@@ -56,11 +62,10 @@ type ServiceConfig struct {
 	Logger *slog.Logger
 }
 
-// Static errors for service construction and unimplemented operations.
+// Static errors for service construction.
 var (
-	errCacheRequired       = errors.New("cache is required")
-	errSigningKeyRequired  = errors.New("signing key is required")
-	errPurgeNotImplemented = errors.New("purge not implemented")
+	errCacheRequired      = errors.New("cache is required")
+	errSigningKeyRequired = errors.New("signing key is required")
 )
 
 // NewService creates a new image service.
@@ -99,6 +104,13 @@ func NewService(cfg *ServiceConfig) (*Service, error) {
 		allowHTTP = cfg.FetcherConfig.AllowHTTP
 	}
 
+	// JPEG XL is the default output format, so pixad does not start
+	// without it.
+	err := imageprocessor.CheckJPEGXLSupport()
+	if err != nil {
+		return nil, err
+	}
+
 	maxResponseSize := fetcherCfg.MaxResponseSize
 	processor := imageprocessor.New(imageprocessor.Params{
 		MaxInputBytes:           maxResponseSize,
@@ -153,8 +165,9 @@ func (s *Service) Get(ctx context.Context, req *ImageRequest) (*ImageResponse, e
 			s.log.Error("failed to get cached variant", "key", result.CacheKey, "error", err)
 			// Fall through to re-process
 		} else {
-			// Counted also when the request context has ended meanwhile
-			s.cache.IncrementStats(context.WithoutCancel(ctx), true, 0)
+			s.writeCount(ctx, func(ctx context.Context) {
+				s.cache.IncrementStats(ctx, true, 0)
+			})
 
 			return &ImageResponse{
 				Content:       reader,
@@ -171,7 +184,9 @@ func (s *Service) Get(ctx context.Context, req *ImageRequest) (*ImageResponse, e
 	// failed or the request context has ended meanwhile
 	response, err := s.processOrWait(ctx, req)
 
-	s.cache.IncrementStats(context.WithoutCancel(ctx), false, 0)
+	s.writeCount(ctx, func(ctx context.Context) {
+		s.cache.IncrementStats(ctx, false, 0)
+	})
 
 	if err != nil {
 		return nil, err
@@ -189,16 +204,36 @@ func (s *Service) Warm(ctx context.Context, req *ImageRequest) error {
 	return err
 }
 
-// Purge removes a cached image. Purging is not implemented yet.
-func (s *Service) Purge(_ context.Context, _ *ImageRequest) error {
-	return errPurgeNotImplemented
-}
-
 // Stats returns cache statistics.
 func (s *Service) Stats(ctx context.Context) (*CacheStats, error) {
 	return s.cache.Stats(ctx)
 }
 
+// WaitForProcessing waits until no image is being processed, or until ctx
+// ends, and returns how many images were still being processed then.
+func (s *Service) WaitForProcessing(ctx context.Context) int {
+	return s.processor.WaitForProcessing(ctx)
+}
+
+// WaitForCountWrites waits until every count a request has started writing
+// to the database is written, or until ctx ends, and reports whether they
+// all were.
+func (s *Service) WaitForCountWrites(ctx context.Context) bool {
+	written := make(chan struct{})
+
+	go func() {
+		s.countWrites.Wait()
+		close(written)
+	}()
+
+	select {
+	case <-written:
+		return true
+	case <-ctx.Done():
+		return false
+	}
+}
+
 // ValidateRequest validates the request signature if required.
 func (s *Service) ValidateRequest(req *ImageRequest) error {
 	// Check if host is allowed (no signature required)
@@ -245,6 +280,38 @@ func (s *Service) GenerateSignedURL(
 		baseURL, path, sig, exp, req.Quality, req.FitMode), nil
 }
 
+// writeCount runs write, which adds to a count in the database, in a
+// goroutine of its own. The write gets ctx without its cancellation or
+// deadline, so an ended request is still counted. writeCount waits for it
+// until ctx's deadline, even if ctx is cancelled first, so a request
+// returns with its count written unless its deadline has passed; past
+// that, it does not wait for the database connection, which every request
+// shares.
+func (s *Service) writeCount(ctx context.Context, write func(context.Context)) {
+	written := make(chan struct{})
+
+	s.countWrites.Go(func() {
+		defer close(written)
+
+		write(context.WithoutCancel(ctx))
+	})
+
+	deadline, hasDeadline := ctx.Deadline()
+	if !hasDeadline {
+		<-written
+
+		return
+	}
+
+	deadlineTimer := time.NewTimer(time.Until(deadline))
+	defer deadlineTimer.Stop()
+
+	select {
+	case <-written:
+	case <-deadlineTimer.C:
+	}
+}
+
 // errPanicked is returned when processing a variant panicked.
 var errPanicked = errors.New("panic while processing image")
 
@@ -443,8 +510,9 @@ func (s *Service) fetchAndProcess(
 	sourceData, err := io.ReadAll(fetchResult.Content)
 	fetchBytes := int64(len(sourceData))
 
-	// Counted also when the request context has ended meanwhile
-	s.cache.IncrementUpstreamFetch(context.WithoutCancel(ctx), fetchBytes)
+	s.writeCount(ctx, func(ctx context.Context) {
+		s.cache.IncrementUpstreamFetch(ctx, fetchBytes)
+	})
 
 	if err != nil {
 		return nil, fmt.Errorf("failed to read upstream response: %w", err)
@@ -461,6 +529,7 @@ func (s *Service) fetchAndProcess(
 
 	// Log upstream fetch details
 	s.log.Info("upstream fetched",
+		"request_id", middleware.GetReqID(ctx),
 		"host", req.SourceHost,
 		"path", req.SourcePath,
 		"bytes", fetchBytes,
@@ -524,8 +593,7 @@ func (s *Service) processAndStore(
 
 	processDuration := time.Since(processStart)
 
-	// Counted also when the request context has ended meanwhile
-	s.cache.IncrementTransformCount(context.WithoutCancel(ctx))
+	s.writeCount(ctx, s.cache.IncrementTransformCount)
 
 	// Read processed content
 	processedData, err := io.ReadAll(processResult.Content)
@@ -545,6 +613,7 @@ func (s *Service) processAndStore(
 	}
 
 	s.log.Info("image converted",
+		"request_id", middleware.GetReqID(ctx),
 		"host", req.SourceHost,
 		"path", req.SourcePath,
 		"src_format", processResult.InputFormat,

internal/imgcache/storage.go

@@ -564,7 +564,8 @@ func (s *VariantStorage) Exists(key VariantKey) bool {
 	return err == nil
 }
 
-// Delete removes content at the given key.
+// Delete removes the content at the given key together with its .meta
+// sidecar file. A missing file is not an error.
 func (s *VariantStorage) Delete(key VariantKey) error {
 	path := s.keyToPath(key)
 
@@ -573,18 +574,7 @@ func (s *VariantStorage) Delete(key VariantKey) error {
 		return fmt.Errorf("failed to delete content: %w", err)
 	}
 
-	return nil
-}
-
-// DeleteWithMeta removes the content at the given key together with
-// its .meta sidecar file. A missing file is not an error.
-func (s *VariantStorage) DeleteWithMeta(key VariantKey) error {
-	err := s.Delete(key)
-	if err != nil {
-		return err
-	}
-
-	metaPath := s.keyToPath(key) + ".meta"
+	metaPath := path + ".meta"
 
 	err = os.Remove(metaPath)
 	if err != nil && !os.IsNotExist(err) {

internal/imgcache/storage_internal_test.go

@@ -438,3 +438,73 @@ func TestVariantStorage_StoreLogsFailedMetaWrite(t *testing.T) {
 		t.Errorf("log missing %s; got %q", want, logBuf.String())
 	}
 }
+
+// storeTestVariant stores one variant, with its .meta file, in a new
+// VariantStorage and returns the storage and the variant's key.
+func storeTestVariant(t *testing.T) (*VariantStorage, VariantKey) {
+	t.Helper()
+
+	storage, err := NewVariantStorage(t.TempDir(), slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatalf("NewVariantStorage() error = %v", err)
+	}
+
+	key := CacheKey(&ImageRequest{SourceHost: testHostCDN, SourcePath: testPathCat})
+
+	_, err = storage.Store(key, bytes.NewReader([]byte("variant data")), "image/webp")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	return storage, key
+}
+
+// TestVariantStorage_DeleteRemovesMeta verifies that Delete removes the
+// variant's .meta file along with the variant file.
+func TestVariantStorage_DeleteRemovesMeta(t *testing.T) {
+	t.Parallel()
+
+	storage, key := storeTestVariant(t)
+	metaPath := storage.keyToPath(key) + ".meta"
+
+	_, err := os.Stat(metaPath)
+	if err != nil {
+		t.Fatalf("Store() wrote no .meta file: %v", err)
+	}
+
+	err = storage.Delete(key)
+	if err != nil {
+		t.Fatalf("Delete() error = %v", err)
+	}
+
+	if storage.Exists(key) {
+		t.Error("Exists() = true after delete, want false")
+	}
+
+	_, err = os.Stat(metaPath)
+	if !os.IsNotExist(err) {
+		t.Errorf(".meta file left after Delete() (stat err=%v)", err)
+	}
+}
+
+// TestVariantStorage_DeleteWithoutMeta verifies that Delete succeeds for a
+// variant whose .meta file is missing.
+func TestVariantStorage_DeleteWithoutMeta(t *testing.T) {
+	t.Parallel()
+
+	storage, key := storeTestVariant(t)
+
+	err := os.Remove(storage.keyToPath(key) + ".meta")
+	if err != nil {
+		t.Fatalf("removing .meta file: %v", err)
+	}
+
+	err = storage.Delete(key)
+	if err != nil {
+		t.Fatalf("Delete() error = %v, want nil", err)
+	}
+
+	if storage.Exists(key) {
+		t.Error("Exists() = true after delete, want false")
+	}
+}

internal/imgcache/urlparser.go

@@ -38,8 +38,10 @@ func ValidateDimension(name string, value int) error {
 	return nil
 }
 
-// sizeFormatRegex matches patterns like "800x600.webp", "0x0.jpeg", "orig.png"
-var sizeFormatRegex = regexp.MustCompile(`^(\d+)x(\d+)\.(\w+)$|^(orig)\.(\w+)$`)
+// sizeFormatRegex matches patterns like "800x600.webp", "0x0.jpeg", "orig.png",
+// and a size with no format, such as "800x600" or "orig"
+var sizeFormatRegex = regexp.MustCompile(
+	`^(\d+)x(\d+)(?:\.(\w+))?$|^(orig)(?:\.(\w+))?$`)
 
 // ParsedURL contains the parsed components of an image proxy URL.
 type ParsedURL struct {
@@ -56,12 +58,13 @@ type ParsedURL struct {
 }
 
 // ParseImagePath parses the path captured by chi's wildcard:
-// <host>/<path>/<size>.<format>
+// <host>/<path>/<size>.<format>, or <host>/<path>/<size> for JPEG XL
 // This is the primary entry point when using chi routing.
 // Examples:
 //   - cdn.example.com/photos/cat.jpg/800x600.webp
 //   - cdn.example.com/photos/cat.jpg/0x0.jpeg
 //   - cdn.example.com/photos/cat.jpg/orig.png
+//   - cdn.example.com/photos/cat.jpg/800x600
 func ParseImagePath(path string) (*ParsedURL, error) {
 	// Strip leading slash if present (chi may include it)
 	path = strings.TrimPrefix(path, "/")
@@ -72,7 +75,8 @@ func ParseImagePath(path string) (*ParsedURL, error) {
 	return parseImageComponents(path)
 }
 
-// ParseImageURL parses a full URL path like /v1/image/<host>/<path>/<size>.<format>
+// ParseImageURL parses a full URL path like /v1/image/<host>/<path>/<size>.<format>,
+// or /v1/image/<host>/<path>/<size> for JPEG XL
 // Use ParseImagePath instead when working with chi's wildcard capture.
 func ParseImageURL(urlPath string) (*ParsedURL, error) {
 	// Remove the /v1/image/ prefix
@@ -89,7 +93,8 @@ func ParseImageURL(urlPath string) (*ParsedURL, error) {
 	return parseImageComponents(remainder)
 }
 
-// parseImageComponents parses <host>/<path>/<size>.<format> structure.
+// parseImageComponents parses <host>/<path>/<size>.<format>, or
+// <host>/<path>/<size> for JPEG XL.
 func parseImageComponents(remainder string) (*ParsedURL, error) {
 	// Check for path traversal before any other processing
 	err := checkPathTraversal(remainder)
@@ -97,7 +102,7 @@ func parseImageComponents(remainder string) (*ParsedURL, error) {
 		return nil, err
 	}
 
-	// Find the last path segment which contains size.format
+	// Find the last path segment, which holds "size" or "size.format"
 	lastSlash := strings.LastIndex(remainder, "/")
 	if lastSlash == -1 {
 		return nil, ErrMissingSize
@@ -212,7 +217,7 @@ func checkPathTraversal(path string) error {
 	return nil
 }
 
-// parseSizeFormat parses strings like "800x600.webp" or "orig.png"
+// parseSizeFormat parses strings like "800x600.webp", "orig.png" or "800x600"
 func parseSizeFormat(s string) (Size, ImageFormat, error) {
 	matches := sizeFormatRegex.FindStringSubmatch(s)
 	if matches == nil {
@@ -225,11 +230,11 @@ func parseSizeFormat(s string) (Size, ImageFormat, error) {
 	)
 
 	if matches[4] == "orig" {
-		// "orig.format" pattern
+		// "orig" or "orig.format" pattern
 		size = Size{Width: 0, Height: 0}
 		formatStr = matches[5]
 	} else {
-		// "WxH.format" pattern
+		// "WxH" or "WxH.format" pattern
 		width, err := strconv.Atoi(matches[1])
 		if err != nil {
 			return Size{}, "", ErrInvalidSize
@@ -254,6 +259,11 @@ func parseSizeFormat(s string) (Size, ImageFormat, error) {
 		return Size{}, "", err
 	}
 
+	// A URL that names no format is served, and signed, as JPEG XL
+	if formatStr == "" {
+		return size, FormatJXL, nil
+	}
+
 	format, err := parseFormat(formatStr)
 	if err != nil {
 		return Size{}, "", err
@@ -275,8 +285,12 @@ func parseFormat(s string) (ImageFormat, error) {
 		return FormatWebP, nil
 	case "avif":
 		return FormatAVIF, nil
+	case "jxl":
+		return FormatJXL, nil
 	case "gif":
 		return FormatGIF, nil
+	case "auto":
+		return FormatAuto, nil
 	default:
 		return "", fmt.Errorf("%w: %s", ErrInvalidFormat, s)
 	}

internal/imgcache/urlparser_internal_test.go

@@ -111,6 +111,21 @@ func TestParseImageURL(t *testing.T) {
 	}
 }
 
+// TestParseImageURL_AutoFormat verifies that the format auto in an image URL
+// parses as FormatAuto.
+func TestParseImageURL_AutoFormat(t *testing.T) {
+	t.Parallel()
+
+	got, err := ParseImageURL("/v1/image/example.com/photo.jpg/200x200.auto")
+	if err != nil {
+		t.Fatalf("ParseImageURL() error = %v", err)
+	}
+
+	if got.Format != FormatAuto {
+		t.Errorf("Format = %q, want %q", got.Format, FormatAuto)
+	}
+}
+
 func TestParseImageURL_Errors(t *testing.T) {
 	t.Parallel()
 

internal/loadtestorigin/loadtestorigin.go

@@ -0,0 +1,87 @@
+// Package loadtestorigin is the upstream host script/loadtest points pixad
+// at, run by cmd/loadtest-origin. It answers every request, whatever its path,
+// with the same generated JPEG, so each new path is a new source image for
+// pixad to fetch, and it logs one line per request, so its log counts pixad's
+// fetches.
+package loadtestorigin
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"log/slog"
+	"math"
+	"net/http"
+	"os"
+	"time"
+)
+
+const (
+	listenAddress     = ":80"
+	readHeaderTimeout = 10 * time.Second
+	imageWidth        = 1600
+	imageHeight       = 1200
+	jpegQuality       = 85
+)
+
+// Run makes the image and serves it on port 80 until the server fails, then
+// exits the process with status 1.
+func Run() {
+	photo, err := makeJPEG()
+	if err != nil {
+		slog.Error("cannot make the image", "error", err)
+		os.Exit(1)
+	}
+
+	server := &http.Server{
+		Addr:              listenAddress,
+		Handler:           newHandler(photo),
+		ReadHeaderTimeout: readHeaderTimeout,
+	}
+
+	err = server.ListenAndServe()
+	slog.Error("server stopped", "error", err)
+	os.Exit(1)
+}
+
+// newHandler answers every request with photo and logs the request's path.
+func newHandler(photo []byte) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		slog.Info("request", "path", r.URL.Path)
+		w.Header().Set("Content-Type", "image/jpeg")
+		_, _ = w.Write(photo)
+	})
+}
+
+// makeJPEG draws colour gradients crossed with a fine pattern, so the image
+// has detail to decode and does not compress to almost nothing.
+func makeJPEG() ([]byte, error) {
+	img := image.NewRGBA(image.Rect(0, 0, imageWidth, imageHeight))
+
+	// red and green count up from 0 to 255 and wrap around, along each row
+	// and down the image.
+	var green uint8
+
+	for y := range imageHeight {
+		var red uint8
+
+		for x := range imageWidth {
+			img.SetRGBA(x, y, color.RGBA{
+				R: red, G: green, B: red ^ green, A: math.MaxUint8,
+			})
+			red++
+		}
+
+		green++
+	}
+
+	var buf bytes.Buffer
+
+	err := jpeg.Encode(&buf, img, &jpeg.Options{Quality: jpegQuality})
+	if err != nil {
+		return nil, err
+	}
+
+	return buf.Bytes(), nil
+}

internal/loadtestorigin/loadtestorigin_internal_test.go

@@ -0,0 +1,51 @@
+package loadtestorigin
+
+import (
+	"bytes"
+	"image/jpeg"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestEveryPathServesTheSameJPEG checks that the origin answers any path with
+// 200 and the same JPEG, so every new path script/loadtest asks pixad for is
+// a valid source image.
+func TestEveryPathServesTheSameJPEG(t *testing.T) {
+	t.Parallel()
+
+	photo, err := makeJPEG()
+	if err != nil {
+		t.Fatalf("makeJPEG: %v", err)
+	}
+
+	size, err := jpeg.DecodeConfig(bytes.NewReader(photo))
+	if err != nil {
+		t.Fatalf("the image does not decode as a JPEG: %v", err)
+	}
+
+	if size.Width != imageWidth || size.Height != imageHeight {
+		t.Errorf("the image is %dx%d, want %dx%d",
+			size.Width, size.Height, imageWidth, imageHeight)
+	}
+
+	handler := newHandler(photo)
+
+	for _, path := range []string{"/", "/miss/1.jpg", "/herd/2.jpg"} {
+		rec := httptest.NewRecorder()
+		handler.ServeHTTP(rec, httptest.NewRequestWithContext(
+			t.Context(), http.MethodGet, path, nil))
+
+		if rec.Code != http.StatusOK {
+			t.Errorf("%s: status = %d, want %d", path, rec.Code, http.StatusOK)
+		}
+
+		if ct := rec.Header().Get("Content-Type"); ct != "image/jpeg" {
+			t.Errorf("%s: Content-Type = %q, want image/jpeg", path, ct)
+		}
+
+		if !bytes.Equal(rec.Body.Bytes(), photo) {
+			t.Errorf("%s: the body is not the image", path)
+		}
+	}
+}

internal/magic/jpegxl_internal_test.go

@@ -0,0 +1,58 @@
+package magic
+
+import "testing"
+
+// testMIMEJXL is the MIME type of JPEG XL.
+const testMIMEJXL = "image/jxl"
+
+// TestDetectFormatJPEGXL verifies that both JPEG XL signatures, that of a
+// bare codestream and that of the container, are detected as image/jxl.
+func TestDetectFormatJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		data []byte
+	}{
+		{"codestream", pad(0xFF, 0x0A)},
+		{"container", pad(
+			0x00, 0x00, 0x00, 0x0C, 0x4A, 0x58, 0x4C, 0x20, 0x0D, 0x0A, 0x87, 0x0A,
+		)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := DetectFormat(tt.data)
+			if err != nil || got != MIMETypeJXL {
+				t.Errorf("DetectFormat() = %q, %v, want %q", got, err, testMIMEJXL)
+			}
+
+			err = ValidateMagicBytes(tt.data, testMIMEJXL)
+			if err != nil {
+				t.Errorf("ValidateMagicBytes(%q) error = %v", testMIMEJXL, err)
+			}
+		})
+	}
+}
+
+// TestJPEGXLMIMEType verifies that image/jxl is a supported input type and
+// maps to and from the format jxl.
+func TestJPEGXLMIMEType(t *testing.T) {
+	t.Parallel()
+
+	if !IsSupportedMIMEType(testMIMEJXL) {
+		t.Errorf("IsSupportedMIMEType(%q) = false", testMIMEJXL)
+	}
+
+	format, ok := MIMEToImageFormat(testMIMEJXL)
+	if format != FormatJXL || !ok {
+		t.Errorf("MIMEToImageFormat(%q) = %q, %v, want %q, true",
+			testMIMEJXL, format, ok, FormatJXL)
+	}
+
+	if got := ImageFormatToMIME(FormatJXL); got != testMIMEJXL {
+		t.Errorf("ImageFormatToMIME(%q) = %q, want %q", FormatJXL, got, testMIMEJXL)
+	}
+}

internal/magic/magic.go

@@ -26,6 +26,7 @@ const (
 	MIMETypeWebP = MIMEType("image/webp")
 	MIMETypeGIF  = MIMEType("image/gif")
 	MIMETypeAVIF = MIMEType("image/avif")
+	MIMETypeJXL  = MIMEType("image/jxl")
 	MIMETypeSVG  = MIMEType("image/svg+xml")
 )
 
@@ -40,6 +41,7 @@ const (
 	FormatPNG      ImageFormat = "png"
 	FormatWebP     ImageFormat = "webp"
 	FormatAVIF     ImageFormat = "avif"
+	FormatJXL      ImageFormat = "jxl"
 	FormatGIF      ImageFormat = "gif"
 )
 
@@ -62,6 +64,11 @@ var (
 	// AVIF uses the ftyp box with brand "avif" or "avis"
 	// Format: size(4 bytes) + "ftyp" + brand(4 bytes)
 	magicFtyp = []byte{0x66, 0x74, 0x79, 0x70} // "ftyp"
+	// JPEG XL is a bare codestream or a codestream in a container
+	magicJXLCodestream = []byte{0xFF, 0x0A}
+	magicJXLContainer  = []byte{
+		0x00, 0x00, 0x00, 0x0C, 0x4A, 0x58, 0x4C, 0x20, 0x0D, 0x0A, 0x87, 0x0A,
+	}
 )
 
 // WebP identifier appears at offset 8 after RIFF header.
@@ -115,6 +122,12 @@ func DetectFormat(data []byte) (MIMEType, error) {
 		}
 	}
 
+	// Check JPEG XL (FF0A, or the 12-byte container signature)
+	if bytes.HasPrefix(data, magicJXLCodestream) ||
+		bytes.HasPrefix(data, magicJXLContainer) {
+		return MIMETypeJXL, nil
+	}
+
 	// Check SVG - look for XML declaration or SVG tag
 	if detectSVG(data) {
 		return MIMETypeSVG, nil
@@ -181,7 +194,8 @@ func normalizeMIMEType(mimeType string) string {
 func IsSupportedMIMEType(mimeType string) bool {
 	normalized := normalizeMIMEType(mimeType)
 	switch MIMEType(normalized) {
-	case MIMETypeJPEG, MIMETypePNG, MIMETypeWebP, MIMETypeGIF, MIMETypeAVIF, MIMETypeSVG:
+	case MIMETypeJPEG, MIMETypePNG, MIMETypeWebP, MIMETypeGIF, MIMETypeAVIF,
+		MIMETypeJXL, MIMETypeSVG:
 		return true
 	default:
 		return false
@@ -226,6 +240,8 @@ func MIMEToImageFormat(mimeType string) (ImageFormat, bool) {
 		return FormatGIF, true
 	case MIMETypeAVIF:
 		return FormatAVIF, true
+	case MIMETypeJXL:
+		return FormatJXL, true
 	case MIMETypeSVG:
 		// SVG has no corresponding output format.
 		return "", false
@@ -247,6 +263,8 @@ func ImageFormatToMIME(format ImageFormat) string {
 		return string(MIMETypeGIF)
 	case FormatAVIF:
 		return string(MIMETypeAVIF)
+	case FormatJXL:
+		return string(MIMETypeJXL)
 	case FormatOriginal:
 		// Original format passes content through unchanged.
 		return mimeOctetStream

internal/middleware/middleware.go

@@ -2,9 +2,12 @@
 package middleware
 
 import (
+	"context"
+	"crypto/rand"
 	"log/slog"
 	"net/http"
 	"net/netip"
+	"regexp"
 	"time"
 
 	basicauth "github.com/99designs/basicauth-go"
@@ -32,13 +35,10 @@ const HSTSValue = "max-age=31536000; includeSubDomains"
 
 // ContentSecurityPolicyValue is the Content-Security-Policy header value.
 // default-src 'self' is the baseline and frame-ancestors 'none' is the primary
-// clickjacking control. 'unsafe-inline' is required in script-src and style-src
-// because the served templates carry inline onclick handlers (generator page)
-// and the bundled Tailwind asset injects a runtime <style> element; dropping it
-// needs template changes outside this issue's scope.
+// clickjacking control.
 const ContentSecurityPolicyValue = "default-src 'self'; " +
-	"script-src 'self' 'unsafe-inline'; " +
-	"style-src 'self' 'unsafe-inline'; " +
+	"script-src 'self'; " +
+	"style-src 'self'; " +
 	"object-src 'none'; " +
 	"base-uri 'self'; " +
 	"form-action 'self'; " +
@@ -115,6 +115,32 @@ func (s *Middleware) RateLimit(
 		})
 }
 
+// requestIDPattern is what a request's own X-Request-Id must look like to be
+// kept as its ID: 1 to 64 letters, digits, '-', '_' or '.'.
+var requestIDPattern = regexp.MustCompile(`^[A-Za-z0-9._-]{1,64}$`)
+
+// RequestID returns a middleware that gives each request an ID and sends it as
+// the X-Request-Id response header, so a client can quote it when reporting a
+// problem. The ID is the request's own X-Request-Id when that matches
+// requestIDPattern, and otherwise a random one, which tells nothing about the
+// machine or the traffic. It is stored in the request context under chi's
+// RequestIDKey, where the logging middleware, the handlers and the upstream
+// fetch read it.
+func (s *Middleware) RequestID() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			id := r.Header.Get(middleware.RequestIDHeader)
+			if !requestIDPattern.MatchString(id) {
+				id = rand.Text()
+			}
+
+			w.Header().Set(middleware.RequestIDHeader, id)
+			ctx := context.WithValue(r.Context(), middleware.RequestIDKey, id)
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
+	}
+}
+
 type loggingResponseWriter struct {
 	http.ResponseWriter
 

internal/middleware/middleware_internal_test.go

@@ -1,11 +1,16 @@
 package middleware
 
 import (
+	"bytes"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
+	"strings"
 	"testing"
 
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+
 	"sneak.berlin/go/pixa/internal/config"
 )
 
@@ -56,6 +61,203 @@ func TestCORSAnswersWithConfiguredOrigin(t *testing.T) {
 	}
 }
 
+// TestCORSAnswersPreflightWithConfiguredOrigin checks that the CORS
+// middleware answers a preflight request, which the CORS library handles
+// apart from other requests, the same way: "*" lets any origin read
+// responses and a single origin lets only that origin read them.
+func TestCORSAnswersPreflightWithConfiguredOrigin(t *testing.T) {
+	t.Parallel()
+
+	const appOrigin = "https://app.example.com"
+
+	cases := []struct {
+		configured    string
+		requestOrigin string
+		want          string
+	}{
+		{"*", "https://any.example.com", "*"},
+		{appOrigin, appOrigin, appOrigin},
+		{appOrigin, "https://other.example.com", ""},
+	}
+
+	testHandler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	for _, tc := range cases {
+		mw := &Middleware{
+			log:    slog.Default(),
+			config: &config.Config{AccessControlAllowOrigin: tc.configured},
+		}
+
+		handler := mw.CORS()(testHandler)
+
+		// An OPTIONS request naming the method it asks about is the
+		// preflight a browser sends before some cross-origin requests.
+		req := httptest.NewRequestWithContext(
+			t.Context(), http.MethodOptions, "/v1/image/example.com/a.jpg/1x1.png", nil)
+		req.Header.Set("Origin", tc.requestOrigin)
+		req.Header.Set("Access-Control-Request-Method", http.MethodGet)
+
+		rec := httptest.NewRecorder()
+
+		handler.ServeHTTP(rec, req)
+
+		got := rec.Header().Get("Access-Control-Allow-Origin")
+		if got != tc.want {
+			t.Errorf("configured %q, preflight from %q: "+
+				"Access-Control-Allow-Origin = %q, want %q",
+				tc.configured, tc.requestOrigin, got, tc.want)
+		}
+	}
+}
+
+// TestMetricsAuthRequiresConfiguredCredentials checks that MetricsAuth on
+// its own answers 401 with a challenge to a request without credentials or
+// with a wrong username or password, and lets a request with the configured
+// username and password through. That the router puts it in front of
+// /metrics is not tested.
+func TestMetricsAuthRequiresConfiguredCredentials(t *testing.T) {
+	t.Parallel()
+
+	const (
+		username  = "metricsuser"
+		password  = "metricspass"
+		challenge = `Basic realm="metrics"`
+	)
+
+	// An empty username stands for a request sent without credentials.
+	cases := []struct {
+		name        string
+		username    string
+		password    string
+		wantReached bool
+	}{
+		{"no credentials", "", "", false},
+		{"wrong username", "someone", password, false},
+		{"wrong password", username, "wrongpass", false},
+		{"configured credentials", username, password, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			mw := &Middleware{
+				log: slog.Default(),
+				config: &config.Config{
+					MetricsUsername: username,
+					MetricsPassword: password,
+				},
+			}
+
+			reached := false
+			handler := mw.MetricsAuth()(http.HandlerFunc(
+				func(http.ResponseWriter, *http.Request) {
+					reached = true
+				}))
+
+			req := httptest.NewRequestWithContext(
+				t.Context(), http.MethodGet, "/metrics", nil)
+
+			if tc.username != "" {
+				req.SetBasicAuth(tc.username, tc.password)
+			}
+
+			rec := httptest.NewRecorder()
+
+			handler.ServeHTTP(rec, req)
+
+			if reached != tc.wantReached {
+				t.Fatalf("request reached /metrics = %v, want %v",
+					reached, tc.wantReached)
+			}
+
+			if tc.wantReached {
+				return
+			}
+
+			if rec.Code != http.StatusUnauthorized {
+				t.Errorf("status = %d, want %d",
+					rec.Code, http.StatusUnauthorized)
+			}
+
+			if got := rec.Header().Get("WWW-Authenticate"); got != challenge {
+				t.Errorf("WWW-Authenticate = %q, want %q", got, challenge)
+			}
+		})
+	}
+}
+
+// TestMetricsRecordsServedRequest checks that the metrics middleware
+// records a request it served, so /metrics reports it. It is the only test
+// in this package that sets up the metrics middleware, which registers with
+// the process-wide Prometheus registry and can do so only once.
+func TestMetricsRecordsServedRequest(t *testing.T) {
+	t.Parallel()
+
+	// The line /metrics shows once one GET /test has been served.
+	const want = `http_request_duration_seconds_count{` +
+		`code="200",handler="/test",method="GET",service=""} 1`
+
+	mw := &Middleware{log: slog.Default(), config: &config.Config{}}
+
+	handler := mw.Metrics()(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		}))
+
+	handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/test", nil))
+
+	rec := httptest.NewRecorder()
+	promhttp.Handler().ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/metrics", nil))
+
+	if !strings.Contains(rec.Body.String(), want) {
+		t.Errorf("/metrics does not report the GET /test served; "+
+			"want the line %q in:\n%s", want, rec.Body.String())
+	}
+}
+
+// TestLoggingLeavesOutSubmittedSigningKey checks that a login, a POST /
+// whose form carries the signing key, leaves no trace of the key in the
+// request's log line.
+func TestLoggingLeavesOutSubmittedSigningKey(t *testing.T) {
+	t.Parallel()
+
+	const signingKey = "test-signing-key-0123456789abcdef"
+
+	var buf bytes.Buffer
+
+	mw := newTestMiddleware(t, &buf)
+
+	// The handler reads the key from the form, as the login handler does.
+	handler := mw.Logging()(http.HandlerFunc(
+		func(w http.ResponseWriter, r *http.Request) {
+			if got := r.FormValue("key"); got != signingKey {
+				t.Errorf("key in form = %q, want %q", got, signingKey)
+			}
+
+			w.WriteHeader(http.StatusSeeOther)
+		}))
+
+	form := url.Values{"key": {signingKey}}
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodPost, "/",
+		strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	handler.ServeHTTP(httptest.NewRecorder(), req)
+
+	if !strings.Contains(buf.String(), `"method":"POST"`) {
+		t.Fatalf("no log line for the request; got %q", buf.String())
+	}
+
+	if strings.Contains(buf.String(), signingKey) {
+		t.Errorf("log output contains the signing key; got %q", buf.String())
+	}
+}
+
 func TestSecurityHeaders(t *testing.T) {
 	t.Parallel()
 
@@ -123,6 +325,13 @@ func TestSecurityHeaders_PolicyHeaders(t *testing.T) {
 
 	handler.ServeHTTP(rec, req)
 
+	// The login and generator pages load their script and stylesheet from
+	// /static, so the policy allows no inline script or style.
+	csp := rec.Header().Get("Content-Security-Policy")
+	if strings.Contains(csp, "unsafe-inline") {
+		t.Errorf("Content-Security-Policy allows unsafe-inline: %q", csp)
+	}
+
 	tests := []struct {
 		header string
 		want   string
@@ -131,8 +340,8 @@ func TestSecurityHeaders_PolicyHeaders(t *testing.T) {
 		{
 			"Content-Security-Policy",
 			"default-src 'self'; " +
-				"script-src 'self' 'unsafe-inline'; " +
-				"style-src 'self' 'unsafe-inline'; " +
+				"script-src 'self'; " +
+				"style-src 'self'; " +
 				"object-src 'none'; " +
 				"base-uri 'self'; " +
 				"form-action 'self'; " +

internal/middleware/request_id_internal_test.go

@@ -0,0 +1,118 @@
+package middleware
+
+import (
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5/middleware"
+
+	"sneak.berlin/go/pixa/internal/config"
+)
+
+// sendRequestID sends a request through the RequestID middleware, carrying
+// incoming as its X-Request-Id unless that is empty. It returns the ID the
+// next handler found in the request context, which the upstream fetch sends
+// and the log lines carry, and the X-Request-Id of the response.
+func sendRequestID(t *testing.T, incoming string) (string, string) {
+	t.Helper()
+
+	mw := &Middleware{log: slog.Default(), config: &config.Config{}}
+
+	var inContext string
+
+	handler := mw.RequestID()(http.HandlerFunc(
+		func(_ http.ResponseWriter, r *http.Request) {
+			inContext = middleware.GetReqID(r.Context())
+		}))
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", nil)
+	if incoming != "" {
+		req.Header.Set("X-Request-Id", incoming)
+	}
+
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	return inContext, rec.Header().Get("X-Request-Id")
+}
+
+// TestRequestIDKeepsShortPlainID verifies that a request's own X-Request-Id of
+// at most 64 letters, digits, '-', '_' or '.' is kept as its ID.
+func TestRequestIDKeepsShortPlainID(t *testing.T) {
+	t.Parallel()
+
+	for _, incoming := range []string{
+		"client-request-id",
+		"A1_b2.c3-d4",
+		strings.Repeat("a", 64),
+	} {
+		inContext, inResponse := sendRequestID(t, incoming)
+
+		if inContext != incoming || inResponse != incoming {
+			t.Errorf("incoming %q: context has %q, response %q, want both %q",
+				incoming, inContext, inResponse, incoming)
+		}
+	}
+}
+
+// TestRequestIDReplacesLongOrUnusualID verifies that a request's own
+// X-Request-Id that is over 64 characters or holds anything but letters,
+// digits, '-', '_' or '.' is neither sent back nor sent upstream: the request
+// gets a fresh ID instead.
+func TestRequestIDReplacesLongOrUnusualID(t *testing.T) {
+	t.Parallel()
+
+	for _, incoming := range []string{
+		strings.Repeat("a", 65),
+		strings.Repeat("a", 9000),
+		"has space",
+		"a/b",
+		"a,b",
+		"<script>",
+		"ünicode",
+	} {
+		inContext, inResponse := sendRequestID(t, incoming)
+		t.Logf("incoming %.20q: made up %q", incoming, inResponse)
+
+		if inResponse == "" || inResponse == incoming {
+			t.Errorf("incoming %.20q: response has %q, want a fresh ID",
+				incoming, inResponse)
+		}
+
+		if inContext != inResponse {
+			t.Errorf("incoming %.20q: context has %q, want the response's %q",
+				incoming, inContext, inResponse)
+		}
+	}
+}
+
+// TestRequestIDMadeUpTellsNothing verifies that the ID made up for a request
+// that sent none differs for every request and does not hold the host name.
+func TestRequestIDMadeUpTellsNothing(t *testing.T) {
+	t.Parallel()
+
+	hostname, err := os.Hostname()
+	if err != nil {
+		t.Fatalf("os.Hostname() error = %v", err)
+	}
+
+	firstInContext, first := sendRequestID(t, "")
+	_, second := sendRequestID(t, "")
+	t.Logf("host %q, made up %q and %q", hostname, first, second)
+
+	if first == "" || first == second {
+		t.Errorf("made up %q and %q, want two different IDs", first, second)
+	}
+
+	if firstInContext != first {
+		t.Errorf("context has %q, want the response's %q", firstInContext, first)
+	}
+
+	if strings.Contains(first, hostname) {
+		t.Errorf("made-up ID %q holds the host name %q", first, hostname)
+	}
+}

internal/server/format_auto_internal_test.go

@@ -0,0 +1,46 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"testing"
+)
+
+// TestFormatAutoVaryNextToOrigin requests an image URL with the format auto
+// through the server's routes and verifies that the answer carries
+// Vary: Accept next to the Vary: Origin the CORS middleware sends.
+func TestFormatAutoVaryNextToOrigin(t *testing.T) {
+	t.Parallel()
+
+	source := encodeTestPNG(t, 64, 48)
+
+	upstream := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.Header().Set("Content-Type", "image/png")
+			_, _ = w.Write(source)
+		}))
+	t.Cleanup(upstream.Close)
+
+	s, _, _ := startImageProxy(t, upstream)
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+		"/v1/image/"+upstreamHost+"/photo.png/32x24.auto", nil)
+	req.Header.Set("Origin", "https://app.example.com")
+	req.Header.Set("Accept", "image/webp")
+
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, req)
+
+	vary := rec.Header().Values("Vary")
+	t.Logf("status %d, Content-Type %s, Vary %v",
+		rec.Code, rec.Header().Get("Content-Type"), vary)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	if want := []string{"Origin", "Accept"}; !slices.Equal(vary, want) {
+		t.Errorf("Vary = %v, want %v", vary, want)
+	}
+}

internal/server/http.go

@@ -5,6 +5,8 @@ import (
 	"fmt"
 	"net/http"
 	"time"
+
+	"go.uber.org/fx"
 )
 
 // HTTP server configuration constants.
@@ -36,19 +38,19 @@ func (s *Server) newHTTPServer() *http.Server {
 	}
 }
 
+// serveUntilShutdown serves on s.httpServer until it is shut down. When it
+// stops for any other reason, such as its port being in use, it asks fx to
+// shut down with exit code 1.
 func (s *Server) serveUntilShutdown() {
-	s.httpServer = s.newHTTPServer()
-
-	s.SetupRoutes()
-
 	s.log.Info("http begin listen", "listenaddr", s.httpServer.Addr)
 
 	err := s.httpServer.ListenAndServe()
 	if err != nil && !errors.Is(err, http.ErrServerClosed) {
 		s.log.Error("listen error", "error", err)
 
-		if s.cancelFunc != nil {
-			s.cancelFunc()
+		err = s.shutdowner.Shutdown(fx.ExitCode(1))
+		if err != nil {
+			s.log.Error("shutdown request failed", "error", err)
 		}
 	}
 }

internal/server/image_proxy_internal_test.go

@@ -0,0 +1,302 @@
+package server
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/handlers"
+	"sneak.berlin/go/pixa/internal/healthcheck"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/logger"
+	"sneak.berlin/go/pixa/internal/middleware"
+)
+
+// upstreamHost is the upstream host of the image URLs below. It is a
+// documentation address (RFC 5737), which the fetcher's URL check accepts as
+// public; the fetcher's dial function connects it to the test upstream server.
+const upstreamHost = "192.0.2.10"
+
+// TestImageProxyFlow requests images through pixa's router, handlers,
+// upstream fetcher, image processor, disk cache and database, with only the
+// upstream origin replaced by a local test server. The first request for a URL
+// is fetched and converted; the second is served from the cache without
+// another upstream request. The source and the converted image are then on
+// disk, with their rows in the database.
+func TestImageProxyFlow(t *testing.T) {
+	t.Parallel()
+
+	source := encodeTestPNG(t, 64, 48)
+
+	tests := []struct {
+		name          string
+		sizeFormat    string // the <size>.<format> part of the image URL
+		contentType   string
+		decodeConfig  func(io.Reader) (image.Config, error)
+		width, height int
+	}{
+		{"resize and convert to JPEG", "32x24.jpeg", "image/jpeg",
+			jpeg.DecodeConfig, 32, 24},
+		{"orig", "orig.orig", "image/png", png.DecodeConfig, 64, 48},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var upstreamRequests atomic.Int32
+
+			upstream := httptest.NewServer(http.HandlerFunc(
+				func(w http.ResponseWriter, _ *http.Request) {
+					upstreamRequests.Add(1)
+					w.Header().Set("Content-Type", "image/png")
+					_, _ = w.Write(source)
+				}))
+			t.Cleanup(upstream.Close)
+
+			s, db, stateDir := startImageProxy(t, upstream)
+			target := "/v1/image/" + upstreamHost + "/photo.png/" + tt.sizeFormat
+
+			first := getImage(t, s, target)
+
+			if got := first.Header().Get("X-Pixa-Cache"); got != "MISS" {
+				t.Errorf("first X-Pixa-Cache = %q, want MISS", got)
+			}
+
+			if got := first.Header().Get("Content-Type"); got != tt.contentType {
+				t.Errorf("Content-Type = %q, want %q", got, tt.contentType)
+			}
+
+			decoded, err := tt.decodeConfig(bytes.NewReader(first.Body.Bytes()))
+			if err != nil {
+				t.Fatalf("decoding the image: %v", err)
+			}
+
+			if decoded.Width != tt.width || decoded.Height != tt.height {
+				t.Errorf("image is %dx%d, want %dx%d",
+					decoded.Width, decoded.Height, tt.width, tt.height)
+			}
+
+			second := getImage(t, s, target)
+
+			if got := second.Header().Get("X-Pixa-Cache"); got != "HIT" {
+				t.Errorf("second X-Pixa-Cache = %q, want HIT", got)
+			}
+
+			if !bytes.Equal(second.Body.Bytes(), first.Body.Bytes()) {
+				t.Error("the second response is not the image the first served")
+			}
+
+			if got := upstreamRequests.Load(); got != 1 {
+				t.Errorf("upstream received %d requests, want 1", got)
+			}
+
+			checkSourceCached(t, db, stateDir, source)
+			checkVariantCached(t, db, stateDir, first.Body.Bytes(), tt.contentType)
+		})
+	}
+}
+
+// startImageProxy starts the components pixad's fx app builds, from a config
+// with a fresh state directory and upstreamHost on the allowlist, and with an
+// upstream fetcher that connects every upstream address to upstream. It
+// returns the server with its routes, the database and the state directory.
+func startImageProxy(
+	t *testing.T, upstream *httptest.Server,
+) (*Server, *sql.DB, string) {
+	t.Helper()
+
+	stateDir := t.TempDir()
+	cfg := &config.Config{
+		SigningKey:     testSigningKey,
+		StateDir:       stateDir,
+		DBURL:          "file:" + filepath.Join(stateDir, "state.sqlite3"),
+		AllowlistHosts: []string{upstreamHost},
+		// The test upstream server has no TLS.
+		AllowHTTP: true,
+		// A limit of its own, so the cache does not size itself from the
+		// host's free disk space.
+		CacheMaxBytes:           64 << 20,
+		CacheMaxBytesExplicit:   true,
+		UpstreamMaxResponseSize: config.DefaultUpstreamMaxResponseSize,
+		DownstreamTimeout:       config.DefaultDownstreamTimeout,
+	}
+
+	fetcherCfg := httpfetcher.DefaultConfig()
+	fetcherCfg.AllowHTTP = true
+	fetcherCfg.DialContext = func(
+		ctx context.Context, network, _ string,
+	) (net.Conn, error) {
+		var dialer net.Dialer
+
+		return dialer.DialContext(ctx, network, upstream.Listener.Addr().String())
+	}
+	fetcher := httpfetcher.New(fetcherCfg)
+
+	var (
+		h  *handlers.Handlers
+		mw *middleware.Middleware
+		db *database.Database
+	)
+
+	app := fxtest.New(t,
+		fx.Supply(cfg),
+		fx.Provide(
+			globals.New,
+			logger.New,
+			database.New,
+			healthcheck.New,
+			handlers.New,
+			middleware.New,
+			func() httpfetcher.Fetcher { return fetcher },
+		),
+		fx.Populate(&h, &mw, &db),
+	)
+	app.RequireStart()
+	t.Cleanup(app.RequireStop)
+
+	// Requests go straight to the router, as in newTestServer; the server's
+	// own start hook, which listens on a port, is left out.
+	s := &Server{config: cfg, mw: mw, h: h}
+	s.SetupRoutes()
+
+	return s, db.DB(), stateDir
+}
+
+// getImage sends a GET for target to s and fails unless it answers 200.
+func getImage(t *testing.T, s *Server, target string) *httptest.ResponseRecorder {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, target, nil))
+	t.Logf("GET %s: %d, X-Pixa-Cache %s",
+		target, rec.Code, rec.Header().Get("X-Pixa-Cache"))
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET %s status = %d, want %d; body %s",
+			target, rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	return rec
+}
+
+// checkSourceCached checks that source is stored under its SHA-256 in
+// cache/sources, recorded in source_content, and that the source URL's row in
+// source_metadata points at it.
+func checkSourceCached(t *testing.T, db *sql.DB, stateDir string, source []byte) {
+	t.Helper()
+
+	sum := sha256.Sum256(source)
+	hash := hex.EncodeToString(sum[:])
+
+	checkFile(t, filepath.Join(stateDir, "cache", "sources", hash[0:2], hash[2:4], hash),
+		source)
+
+	var rows int
+
+	err := db.QueryRowContext(t.Context(),
+		"SELECT COUNT(*) FROM source_content WHERE content_hash = ?", hash,
+	).Scan(&rows)
+	if err != nil || rows != 1 {
+		t.Errorf("source_content rows for the source = %d (error %v), want 1",
+			rows, err)
+	}
+
+	var metadataHash string
+
+	err = db.QueryRowContext(t.Context(),
+		`SELECT content_hash FROM source_metadata
+			WHERE source_host = ? AND source_path = ?`,
+		upstreamHost, "/photo.png",
+	).Scan(&metadataHash)
+	if err != nil || metadataHash != hash {
+		t.Errorf("source_metadata content_hash = %q (error %v), want %q",
+			metadataHash, err, hash)
+	}
+}
+
+// checkVariantCached checks that the converted image served is recorded in
+// variant_content with contentType, and stored under its cache key in
+// cache/variants.
+func checkVariantCached(
+	t *testing.T, db *sql.DB, stateDir string, served []byte, contentType string,
+) {
+	t.Helper()
+
+	var cacheKey, storedType string
+
+	err := db.QueryRowContext(t.Context(),
+		"SELECT cache_key, content_type FROM variant_content",
+	).Scan(&cacheKey, &storedType)
+	if err != nil {
+		t.Fatalf("variant_content row: %v", err)
+	}
+
+	if storedType != contentType {
+		t.Errorf("variant_content content_type = %q, want %q",
+			storedType, contentType)
+	}
+
+	checkFile(t, filepath.Join(stateDir, "cache", "variants",
+		cacheKey[0:2], cacheKey[2:4], cacheKey), served)
+}
+
+// checkFile checks that the file at path holds want.
+func checkFile(t *testing.T, path string, want []byte) {
+	t.Helper()
+
+	//nolint:gosec // G304: a path under the test's state directory
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Errorf("reading %s: %v", path, err)
+
+		return
+	}
+
+	if !bytes.Equal(got, want) {
+		t.Errorf("%s holds %d bytes that are not the %d expected",
+			path, len(got), len(want))
+	}
+}
+
+// encodeTestPNG returns an opaque width x height PNG of one color.
+func encodeTestPNG(t *testing.T, width, height int) []byte {
+	t.Helper()
+
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	for y := range height {
+		for x := range width {
+			img.Set(x, y, color.RGBA{R: 200, G: 40, B: 40, A: 255})
+		}
+	}
+
+	var buf bytes.Buffer
+
+	err := png.Encode(&buf, img)
+	if err != nil {
+		t.Fatalf("encoding the test PNG: %v", err)
+	}
+
+	return buf.Bytes()
+}

internal/server/jpegxl_internal_test.go

@@ -0,0 +1,72 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/davidbyttow/govips/v2/vips"
+)
+
+// TestImageProxyFlowJPEGXL requests the JPEG XL testdata/red.jxl, 64x48 and
+// made with libvips, through pixa's router, upstream fetcher, image processor
+// and disk cache: resized as PNG, resized as JPEG XL, and at its own size and
+// format, which is JPEG XL. The second request for each URL is a cache hit.
+func TestImageProxyFlowJPEGXL(t *testing.T) {
+	t.Parallel()
+
+	source, err := os.ReadFile("testdata/red.jxl")
+	if err != nil {
+		t.Fatalf("reading the test image: %v", err)
+	}
+
+	upstream := httptest.NewServer(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.Header().Set("Content-Type", "image/jxl")
+			_, _ = w.Write(source)
+		}))
+	t.Cleanup(upstream.Close)
+
+	s, _, _ := startImageProxy(t, upstream)
+
+	tests := []struct {
+		sizeFormat    string // the <size>.<format> part of the image URL
+		contentType   string
+		imageType     vips.ImageType
+		width, height int
+	}{
+		{"32x24.png", "image/png", vips.ImageTypePNG, 32, 24},
+		{"32x24.jxl", "image/jxl", vips.ImageTypeJXL, 32, 24},
+		{"orig.orig", "image/jxl", vips.ImageTypeJXL, 64, 48},
+	}
+
+	for _, tt := range tests {
+		target := "/v1/image/" + upstreamHost + "/red.jxl/" + tt.sizeFormat
+
+		for _, wantCache := range []string{"MISS", "HIT"} {
+			rec := getImage(t, s, target)
+			gotType := rec.Header().Get("Content-Type")
+			gotCache := rec.Header().Get("X-Pixa-Cache")
+
+			if gotType != tt.contentType || gotCache != wantCache {
+				t.Errorf("%s: %s, X-Pixa-Cache %s, want %s, %s",
+					target, gotType, gotCache, tt.contentType, wantCache)
+			}
+
+			img, err := vips.NewImageFromBuffer(rec.Body.Bytes())
+			if err != nil {
+				t.Fatalf("%s: loading the image: %v", target, err)
+			}
+
+			if img.Format() != tt.imageType ||
+				img.Width() != tt.width || img.Height() != tt.height {
+				t.Errorf("%s: %s %dx%d, want %s %dx%d", target,
+					vips.ImageTypes[img.Format()], img.Width(), img.Height(),
+					vips.ImageTypes[tt.imageType], tt.width, tt.height)
+			}
+
+			img.Close()
+		}
+	}
+}

internal/server/metrics_internal_test.go

@@ -0,0 +1,32 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+// TestNoMetricsRecordedWithoutMetricsUsername checks that with no metrics
+// username set the router records nothing about the requests it serves.
+// /metrics is not served then, so the process-wide Prometheus registry is
+// read directly. TestMaintenanceModeKeepsOtherRoutes records into the same
+// registry, but never a GET /robots.txt.
+func TestNoMetricsRecordedWithoutMetricsUsername(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+	s.ServeHTTP(httptest.NewRecorder(), httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/robots.txt", nil))
+
+	rec := httptest.NewRecorder()
+	promhttp.Handler().ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodGet, "/metrics", nil))
+
+	if strings.Contains(rec.Body.String(), `handler="/robots.txt"`) {
+		t.Errorf("with no metrics username GET /robots.txt was recorded:\n%s",
+			rec.Body.String())
+	}
+}

internal/server/request_id_internal_test.go

@@ -0,0 +1,58 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// requestIDHeader is the header that carries a request's ID.
+const requestIDHeader = "X-Request-Id"
+
+// TestResponsesCarryRequestID verifies that every response, whatever its route
+// and status, carries the request's ID as X-Request-Id, so a client can quote
+// it when reporting a problem: one pixa made up when the request brought none,
+// and the request's own X-Request-Id when it brought one.
+func TestResponsesCarryRequestID(t *testing.T) {
+	t.Parallel()
+
+	const clientRequestID = "client-request-id"
+
+	s := newTestServer(t)
+
+	paths := []string{
+		"/robots.txt",
+		"/no-such-path",
+		unsignedImagePath,
+		encryptedImagePath,
+	}
+
+	for _, path := range paths {
+		t.Run(path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			s.ServeHTTP(rec, httptest.NewRequestWithContext(
+				t.Context(), http.MethodGet, path, nil))
+			t.Logf("status %d, %s %q",
+				rec.Code, requestIDHeader, rec.Header().Get(requestIDHeader))
+
+			if rec.Header().Get(requestIDHeader) == "" {
+				t.Errorf("response has no %s", requestIDHeader)
+			}
+
+			req := httptest.NewRequestWithContext(
+				t.Context(), http.MethodGet, path, nil)
+			req.Header.Set(requestIDHeader, clientRequestID)
+
+			rec = httptest.NewRecorder()
+			s.ServeHTTP(rec, req)
+
+			got := rec.Header().Get(requestIDHeader)
+			if got != clientRequestID {
+				t.Errorf("%s = %q, want the request's own %q",
+					requestIDHeader, got, clientRequestID)
+			}
+		})
+	}
+}

internal/server/routes.go

@@ -28,7 +28,7 @@ func (s *Server) SetupRoutes() {
 	s.router = chi.NewRouter()
 
 	s.router.Use(middleware.Recoverer)
-	s.router.Use(middleware.RequestID)
+	s.router.Use(s.mw.RequestID())
 	s.router.Use(s.mw.ClientIP())
 	s.router.Use(s.mw.SecurityHeaders())
 	s.router.Use(s.mw.Logging())
@@ -53,7 +53,7 @@ func (s *Server) SetupRoutes() {
 	// Robots.txt
 	s.router.Get("/robots.txt", s.h.HandleRobotsTxt())
 
-	// Static files (Tailwind CSS, etc.)
+	// The login and generator pages' stylesheet and script
 	s.router.Handle("/static/*", http.StripPrefix("/static/", static.Handler()))
 
 	// Login/generator UI. The form routes carry CSRF protection; the
@@ -89,7 +89,8 @@ func (s *Server) SetupRoutes() {
 			r.Use(s.refuseDuringMaintenance)
 
 			// Main image proxy route
-			// /v1/image/<host>/<path>/<width>x<height>.<format>
+			// /v1/image/<host>/<path>/<width>x<height>.<format>, or with no
+			// format /v1/image/<host>/<path>/<width>x<height>
 			r.Get("/image/*", s.h.HandleImage())
 			r.Head("/image/*", s.h.HandleImage())
 
@@ -97,6 +98,7 @@ func (s *Server) SetupRoutes() {
 			// The trailing filename (e.g., /img.jpg) is ignored but helps
 			// browsers with content type
 			r.Get("/e/{token}/*", s.h.HandleImageEnc())
+			r.Head("/e/{token}/*", s.h.HandleImageEnc())
 		})
 	})
 

internal/server/routes_internal_test.go

@@ -0,0 +1,27 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestEncryptedImageRouteAnswersHEAD verifies that HEAD on the encrypted image
+// route reaches its handler, as GET does, instead of being answered 405 Method
+// Not Allowed. The handler refuses a token it cannot decrypt with 400, so that
+// status shows the request got through.
+func TestEncryptedImageRouteAnswersHEAD(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequestWithContext(
+		t.Context(), http.MethodHead, encryptedImagePath, nil))
+	t.Logf("status %d", rec.Code)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Errorf("status = %d, want %d from the encrypted image handler",
+			rec.Code, http.StatusBadRequest)
+	}
+}

internal/server/server.go

@@ -3,12 +3,10 @@ package server
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
-	"os"
-	"os/signal"
-	"syscall"
 	"time"
 
 	"github.com/getsentry/sentry-go"
@@ -27,6 +25,14 @@ const (
 	SentryFlushTimeout = 2 * time.Second
 )
 
+// errStillProcessing is returned by the server's stop hook when images are
+// still being processed once ShutdownTimeout has passed.
+var errStillProcessing = errors.New("images still being processed at shutdown")
+
+// errStillWritingCounts is returned by the server's stop hook when counts
+// are still being written to the database once ShutdownTimeout has passed.
+var errStillWritingCounts = errors.New("counts still being written at shutdown")
+
 // Params defines dependencies for Server.
 type Params struct {
 	fx.In
@@ -36,6 +42,7 @@ type Params struct {
 	Config     *config.Config
 	Middleware *middleware.Middleware
 	Handlers   *handlers.Handlers
+	Shutdowner fx.Shutdowner
 }
 
 // Server is the main HTTP server.
@@ -45,59 +52,58 @@ type Server struct {
 	globals       *globals.Globals
 	mw            *middleware.Middleware
 	h             *handlers.Handlers
+	shutdowner    fx.Shutdowner
 	startupTime   time.Time
-	exitCode      int
 	sentryEnabled bool
-	cancelFunc    context.CancelFunc
 	httpServer    *http.Server
 	router        *chi.Mux
 }
 
-// New creates a new Server instance.
+// New creates a new Server instance. Its start hook starts Sentry and the
+// HTTP server; its stop hook, which fx runs on SIGINT, SIGTERM or a
+// shutdown request, shuts them down.
 func New(lc fx.Lifecycle, params Params) (*Server, error) {
 	s := &Server{
-		log:     params.Logger.Get(),
-		config:  params.Config,
-		globals: params.Globals,
-		mw:      params.Middleware,
-		h:       params.Handlers,
+		log:        params.Logger.Get(),
+		config:     params.Config,
+		globals:    params.Globals,
+		mw:         params.Middleware,
+		h:          params.Handlers,
+		shutdowner: params.Shutdowner,
 	}
 
 	lc.Append(fx.Hook{
-		OnStart: func(ctx context.Context) error {
+		OnStart: func(_ context.Context) error {
 			s.startupTime = time.Now()
-			go s.Run(context.WithoutCancel(ctx))
 
-			return nil
-		},
-		OnStop: func(_ context.Context) error {
-			if s.cancelFunc != nil {
-				s.cancelFunc()
+			err := s.enableSentry()
+			if err != nil {
+				return err
 			}
 
+			s.SetupRoutes()
+			s.httpServer = s.newHTTPServer()
+
+			go s.serveUntilShutdown()
+
 			return nil
 		},
+		OnStop: s.cleanShutdown,
 	})
 
 	return s, nil
 }
 
-// Run starts the server.
-func (s *Server) Run(ctx context.Context) {
-	s.enableSentry()
-	s.serve(ctx)
-}
-
 // MaintenanceMode returns whether maintenance mode is enabled.
 func (s *Server) MaintenanceMode() bool {
 	return s.config.MaintenanceMode
 }
 
-func (s *Server) enableSentry() {
+func (s *Server) enableSentry() error {
 	s.sentryEnabled = false
 
 	if s.config.SentryDSN == "" {
-		return
+		return nil
 	}
 
 	err := sentry.Init(sentry.ClientOptions{
@@ -105,55 +111,53 @@ func (s *Server) enableSentry() {
 		Release: fmt.Sprintf("%s-%s", s.globals.Appname, s.globals.Version),
 	})
 	if err != nil {
-		s.log.Error("sentry init failure", "error", err)
-		os.Exit(1)
+		return fmt.Errorf("sentry init failure: %w", err)
 	}
 
 	s.log.Info("sentry error reporting activated")
 	s.sentryEnabled = true
+
+	return nil
 }
 
-func (s *Server) serve(ctx context.Context) int {
-	ctx, cancelFunc := context.WithCancel(ctx)
-	s.cancelFunc = cancelFunc
+// cleanShutdown stops the HTTP server, waits for the images still being
+// processed and then for the counts still being written to the database,
+// which closes after this hook, then flushes Sentry. The first three share
+// ShutdownTimeout. It returns errStillProcessing and errStillWritingCounts
+// for the images and counts still unfinished after that, as their work is
+// abandoned.
+func (s *Server) cleanShutdown(ctx context.Context) error {
+	s.log.Info("shutting down")
 
-	go func() {
-		c := make(chan os.Signal, 1)
-
-		signal.Ignore(syscall.SIGPIPE)
-		signal.Notify(c, os.Interrupt, syscall.SIGTERM)
-
-		sig := <-c
-		s.log.Info("signal received", "signal", sig)
-
-		if s.cancelFunc != nil {
-			s.cancelFunc()
-		}
-	}()
-
-	go s.serveUntilShutdown()
-
-	<-ctx.Done()
-	s.cleanShutdown(ctx)
-
-	return s.exitCode
-}
-
-func (s *Server) cleanShutdown(ctx context.Context) {
-	s.exitCode = 0
-
-	ctxShutdown, shutdownCancel := context.WithTimeout(
-		context.WithoutCancel(ctx), ShutdownTimeout)
+	ctxShutdown, shutdownCancel := context.WithTimeout(ctx, ShutdownTimeout)
 	defer shutdownCancel()
 
-	if s.httpServer != nil {
-		err := s.httpServer.Shutdown(ctxShutdown)
-		if err != nil {
-			s.log.Error("server clean shutdown failed", "error", err)
-		}
+	err := s.httpServer.Shutdown(ctxShutdown)
+	if err != nil {
+		s.log.Error("server clean shutdown failed", "error", err)
 	}
 
+	stillProcessing := s.h.WaitForProcessing(ctxShutdown)
+	countsWritten := s.h.WaitForCountWrites(ctxShutdown)
+
 	if s.sentryEnabled {
 		sentry.Flush(SentryFlushTimeout)
 	}
+
+	var unfinished []error
+
+	if stillProcessing > 0 {
+		s.log.Error("images still being processed at shutdown",
+			"count", stillProcessing)
+
+		unfinished = append(unfinished, errStillProcessing)
+	}
+
+	if !countsWritten {
+		s.log.Error("counts still being written at shutdown")
+
+		unfinished = append(unfinished, errStillWritingCounts)
+	}
+
+	return errors.Join(unfinished...)
 }

internal/server/shutdown_internal_test.go

@@ -0,0 +1,96 @@
+package server
+
+import (
+	"log/slog"
+	"net"
+	"testing"
+	"time"
+
+	"go.uber.org/fx"
+	"go.uber.org/fx/fxtest"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/logger"
+)
+
+// shutdownRecorder is an fx.Shutdowner that sends the options of each
+// shutdown request on requests.
+type shutdownRecorder struct {
+	requests chan []fx.ShutdownOption
+}
+
+func (r shutdownRecorder) Shutdown(opts ...fx.ShutdownOption) error {
+	r.requests <- opts
+
+	return nil
+}
+
+// TestSentryInitFailureFailsStartup checks that a Sentry DSN that cannot be
+// used makes the server's start hook fail, so fx stops what has already
+// started, instead of the process exiting from a goroutine.
+func TestSentryInitFailureFailsStartup(t *testing.T) {
+	t.Parallel()
+
+	lc := fxtest.NewLifecycle(t)
+
+	log, err := logger.New(lc, logger.Params{Globals: &globals.Globals{}})
+	if err != nil {
+		t.Fatalf("logger.New() error = %v", err)
+	}
+
+	_, err = New(lc, Params{
+		Logger:  log,
+		Globals: &globals.Globals{Appname: "pixad"},
+		Config:  &config.Config{SentryDSN: "not-a-dsn"},
+	})
+	if err != nil {
+		t.Fatalf("New() error = %v", err)
+	}
+
+	err = lc.Start(t.Context())
+	t.Logf("Start() error = %v", err)
+
+	if err == nil {
+		t.Fatal("Start() error = nil, want the Sentry initialization error")
+	}
+}
+
+// TestListenErrorRequestsShutdownWithExitCode1 occupies the server's port
+// and checks that the listen error asks fx to shut down with exit code 1.
+func TestListenErrorRequestsShutdownWithExitCode1(t *testing.T) {
+	t.Parallel()
+
+	busy, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", ":0")
+	if err != nil {
+		t.Fatalf("Listen() error = %v", err)
+	}
+
+	t.Cleanup(func() { _ = busy.Close() })
+
+	addr, ok := busy.Addr().(*net.TCPAddr)
+	if !ok {
+		t.Fatalf("listener address %v is not a TCP address", busy.Addr())
+	}
+
+	requests := make(chan []fx.ShutdownOption, 1)
+	s := &Server{
+		log:        slog.New(slog.DiscardHandler),
+		config:     &config.Config{Port: addr.Port},
+		shutdowner: shutdownRecorder{requests: requests},
+	}
+	s.httpServer = s.newHTTPServer()
+
+	go s.serveUntilShutdown()
+
+	select {
+	case opts := <-requests:
+		t.Logf("shutdown options = %v", opts)
+
+		if len(opts) != 1 || opts[0] != fx.ExitCode(1) {
+			t.Errorf("shutdown options = %v, want [fx.ExitCode(1)]", opts)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("no shutdown was requested after the listen error")
+	}
+}

internal/static/generator.js

@@ -0,0 +1,10 @@
+// Generator page: a click on the generated URL selects it, and the Copy
+// button copies it. Both are on the page only once a URL has been generated.
+const generatedURL = document.getElementById("generated-url");
+
+if (generatedURL) {
+    generatedURL.addEventListener("click", () => generatedURL.select());
+    document.getElementById("copy-url").addEventListener("click", () => {
+        navigator.clipboard.writeText(generatedURL.value);
+    });
+}

internal/static/static.go

@@ -7,7 +7,7 @@ import (
 	"net/http"
 )
 
-//go:embed *.js
+//go:embed *.css *.js
 var files embed.FS
 
 // FS returns the embedded filesystem containing static files.

internal/static/style.css

@@ -0,0 +1,190 @@
+/* The login and generator pages. */
+
+* {
+    box-sizing: border-box;
+}
+
+body {
+    margin: 0;
+    min-height: 100vh;
+    background: #f3f4f6;
+    font-family: system-ui, sans-serif;
+    line-height: 1.5;
+}
+
+h1 {
+    margin: 0;
+    font-size: 1.5rem;
+    line-height: 2rem;
+    font-weight: 700;
+    color: #1f2937;
+}
+
+label {
+    display: block;
+    margin-bottom: 0.25rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: #374151;
+}
+
+input,
+select {
+    width: 100%;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid #d1d5db;
+    border-radius: 0.375rem;
+    box-shadow: 0 1px 2px rgb(0 0 0 / 5%);
+    font: inherit;
+}
+
+input:focus,
+select:focus {
+    outline: none;
+    border-color: #3b82f6;
+    box-shadow: 0 0 0 2px #3b82f6;
+}
+
+button {
+    width: 100%;
+    padding: 0.5rem 1rem;
+    border: none;
+    border-radius: 0.375rem;
+    background: #2563eb;
+    color: #fff;
+    font: inherit;
+    cursor: pointer;
+    transition: background-color 0.15s;
+}
+
+button:hover {
+    background: #1d4ed8;
+}
+
+button:focus {
+    outline: 2px solid #3b82f6;
+    outline-offset: 2px;
+}
+
+form > * + * {
+    margin-top: 1rem;
+}
+
+.card {
+    padding: 1.5rem;
+    border-radius: 0.5rem;
+    background: #fff;
+    box-shadow:
+        0 4px 6px -1px rgb(0 0 0 / 10%),
+        0 2px 4px -2px rgb(0 0 0 / 10%);
+}
+
+.error {
+    margin-bottom: 1rem;
+    padding: 0.75rem 1rem;
+    border: 1px solid #f87171;
+    border-radius: 0.25rem;
+    background: #fee2e2;
+    color: #b91c1c;
+}
+
+/* Login page: the card centred on the screen. */
+
+.login {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.login .card {
+    width: 100%;
+    max-width: 28rem;
+    padding: 2rem;
+}
+
+.login h1 {
+    margin-bottom: 1.5rem;
+    text-align: center;
+}
+
+/* Generator page. */
+
+.page {
+    max-width: 42rem;
+    margin: 0 auto;
+    padding: 2rem 1rem;
+}
+
+header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 2rem;
+}
+
+header a {
+    font-size: 0.875rem;
+    color: #4b5563;
+}
+
+header a:hover {
+    color: #1f2937;
+}
+
+.result {
+    margin-bottom: 1.5rem;
+    padding: 1rem;
+    border: 1px solid #bbf7d0;
+    border-radius: 0.5rem;
+    background: #f0fdf4;
+}
+
+.result h2 {
+    margin: 0 0 0.5rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: #166534;
+}
+
+.result div {
+    display: flex;
+    gap: 0.5rem;
+}
+
+.result input {
+    flex: 1;
+    border-color: #86efac;
+    box-shadow: none;
+    font-family: ui-monospace, monospace;
+    font-size: 0.875rem;
+}
+
+.result button {
+    width: auto;
+    padding: 0.5rem 0.75rem;
+    background: #16a34a;
+    font-size: 0.875rem;
+}
+
+.result button:hover {
+    background: #15803d;
+}
+
+.result p {
+    margin: 0.5rem 0 0;
+    font-size: 0.75rem;
+    color: #16a34a;
+}
+
+.columns {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 1rem;
+}
+
+.note {
+    margin-top: 1rem;
+    font-size: 0.75rem;
+    color: #6b7280;
+    text-align: center;
+}