Test the image proxy flow end to end (closes #80)

TestImageProxyFlow in internal/server starts the database, handlers and
middleware from the constructors pixad uses, in an fx app with a fresh
state directory, and replaces only the upstream origin with a local test
server, reached through the real fetcher by its new DialContext. For a
resize with a change to JPEG and for orig, the first request answers 200
with the right content type, decoded size and X-Pixa-Cache MISS; the
second answers HIT with the same image while the upstream has had one
request; the source and the converted image are then on disk with their
rows in SQLite. TODO.md records it and drops the item from Future Steps.

Model: opus-5-5

.dockerignore

@@ -1,4 +1,8 @@
-.git
+# .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
+# password in a remote URL or the token the CI checkout step stores there.
+.git/config
 .gitignore
 .DS_Store
 .env*

.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

@@ -7,3 +7,4 @@ jobs:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
             - run: script/cibuild
+            - run: script/docker-smoke

.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

Dockerfile

@@ -1,21 +1,31 @@
 # 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
 
-RUN apk add --no-cache make build-base vips-dev libheif-dev pkgconfig
-
 WORKDIR /src
 
-# Copy go mod files first for better layer caching
+# 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.
+COPY script/ ./script/
 COPY go.mod go.sum ./
-RUN go mod download
+RUN script/bootstrap
 
 # Copy source code
 COPY . .
 
-# Run formatting check and linter
+# Tells script/lint it is inside a container, so it runs the linter.
-RUN make fmt-check
+ENV container=docker
-RUN make lint
+
+# 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
 # golang:1.25.4-alpine, 2026-02-25
@@ -24,29 +34,39 @@ FROM golang:1.25.4-alpine@sha256:d3f0cf7723f3429e3f9ed846243970b20a2de7bae6a5b66
 # Depend on lint stage passing
 COPY --from=lint /src/go.sum /dev/null
 
-ARG VERSION=dev
-
-# Install build dependencies for CGO image libraries
-RUN apk add --no-cache \
-    build-base \
-    vips-dev \
-    libheif-dev \
-    pkgconfig
-
 WORKDIR /src
 
-# Copy go mod files first for better layer caching
+# Build dependencies and Go modules, as in the lint stage
+COPY script/ ./script/
 COPY go.mod go.sum ./
-RUN GOTOOLCHAIN=auto go mod download
+RUN script/bootstrap
 
 # Copy source code
 COPY . .
 
-# Run tests
+# Run tests; a new CHECK_EPOCH reruns them, as in the lint stage.
-RUN make test
+ARG CHECK_EPOCH
+RUN echo "check epoch: ${CHECK_EPOCH}" && make test
 
-# Build with CGO enabled
+# VERSION is declared here, not earlier: a new value reruns only the
-RUN CGO_ENABLED=1 GOTOOLCHAIN=auto go build -ldflags "-X main.Version=${VERSION}" -o /pixad ./cmd/pixad
+# build, not script/bootstrap or the tests. 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
+# carries .git and still yields no version fails the build; one without
+# .git, as from a source tarball, stamps an empty version. CGO stays
+# enabled for govips; -trimpath keeps build paths out of the binary, and
+# -s -w leave out the symbol table and debug information.
+ARG VERSION
+RUN version="${VERSION:-$(git describe --tags --always)}"; \
+    if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
+        [ "$version" = unknown ]; }; then \
+        echo "the build context carries .git but yields no version" >&2; \
+        exit 1; \
+    fi; \
+    CGO_ENABLED=1 GOTOOLCHAIN=auto go build -trimpath \
+        -ldflags "-s -w -X main.Version=${version}" \
+        -o /pixad ./cmd/pixad
 
 # Runtime stage
 # alpine:3.21, 2026-02-25
@@ -57,22 +77,34 @@ RUN apk add --no-cache \
     vips \
     libheif \
     ca-certificates \
-    tzdata
+    tzdata \
+    su-exec
 
 # Copy binary from builder
 COPY --from=builder /pixad /usr/local/bin/pixad
+COPY deploy/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 
-# Create non-root user, config directory, and data directory
+# Create non-root user, config directory, and data directory. pixad
-RUN adduser -D -H -s /sbin/nologin pixad && \
+# gets uid and gid 65532, which host login and system accounts do not
+# use: a bind-mounted /var/lib/pixa is given to pixad, and on the host
+# it must not belong to a person's account.
+RUN addgroup -g 65532 pixad && \
+    adduser -D -H -s /sbin/nologin -u 65532 -G pixad pixad && \
     mkdir -p /var/lib/pixa /etc/pixa && \
     chown pixad:pixad /var/lib/pixa
 
-# Copy default config (edit signing_key before use)
+# No USER: the entrypoint must start as root to give a bind-mounted
-COPY config.example.yml /etc/pixa/config.yml
+# /var/lib/pixa to pixad; it then runs the server as pixad.
-
-USER pixad
 WORKDIR /var/lib/pixa
 
 EXPOSE 8080
 
-ENTRYPOINT ["/usr/local/bin/pixad", "--config", "/etc/pixa/config.yml"]
+# Shell form so the probe follows PORT; a port set only in a mounted
+# config file is not seen here.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --spider -q "http://localhost:${PORT:-8080}/.well-known/healthcheck.json" || exit 1
+
+# Settings come from PORT and the PIXA_ environment variables; only
+# PIXA_SIGNING_KEY is required. A config file mounted at
+# /etc/pixa/config.yml is optional and is read when present.
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

Dockerfile.lint

@@ -0,0 +1,34 @@
+# 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,4 +1,4 @@
-.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker 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
 
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS := -X main.Version=$(VERSION)
@@ -10,7 +10,7 @@ ifdef HAS_PKGCONFIG
   NIX_RUN_PREFIX =
   NIX_RUN_SUFFIX =
 else
-  NIX_RUN_PREFIX = nix-shell -p pkg-config vips libheif golangci-lint git --run '
+  NIX_RUN_PREFIX = nix-shell -p pkg-config vips libheif git --run '
   NIX_RUN_SUFFIX = '
 endif
 
@@ -54,6 +54,11 @@ clean:
 docker:
 	@script/docker
 
+# Build the image, start it, and wait for its healthcheck (needs Docker;
+# not part of check)
+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 .

README.md

@@ -15,14 +15,110 @@ git clone https://git.eeqj.de/sneak/pixa.git
 cd pixa
 make build
 
-# run with a config file
+# run with a config file: copy the example and set a real signing key
-./bin/pixad --config config.example.yml
+# (the example placeholder is refused at startup), e.g. with
+# openssl rand -base64 32
+cp configs/config.example.yml config.yml
+$EDITOR config.yml   # replace the signing_key placeholder
+./bin/pixad --config config.yml
 
 # or build and run via Docker
 make docker
-docker run -p 8080:8080 pixad:latest
+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.
+
+## 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 and the images being processed 5 seconds to finish, and exits: with 0,
+or with 1 when images were still being processed after those 5 seconds or
+another part of pixa failed to stop. A request not finished by then is cut off.
+`docker stop` waits 10 seconds before it kills the container.
+
+Outside Docker, pixa needs libvips (the image has 8.15) and libheif to run, as
+it uses libvips through CGO; building it also needs their development files,
+`pkg-config` and a C compiler. `script/bootstrap` installs all of these with
+nix, apt, brew or apk.
+
+## Running under upaas
+
+What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
+
+- **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.
+- **Environment variables:**
+    - `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 + 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`.
+
 ## Rationale
 
 Image-heavy web applications need a fast, caching reverse proxy that
@@ -36,28 +132,202 @@ prevent abuse, and allowlisted source hosts for open access.
 ### 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`
+  `<state_dir>/cache/metadata/<hostname>/<sha256 of path and query>.json`
-  (fetch time, original headers, request, content hash)
+  (host, path and query, content hash, upstream status and headers, fetch time)
-- **Database**: `<statedir>/state.sqlite3` (SQLite)
+- **Database**: `<state_dir>/state.sqlite3` (SQLite)
-- **Output documents**:
+- **Transformed images**:
-  `<statedir>/cache/dst-content/<ab>/<cd>/<sha256 of output content>`
+  `<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
+
+`<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.
-In-process caching of request-to-output mappings targets 1-5k r/s.
+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.
 
 ### 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>` — 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; 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; 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 this form:
+
 ```
-/v1/image/<host>/<path>/<size>.<format>?sig=<signature>&exp=<expiration>
+/v1/image/<host>/<path>/<size>.<format>?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.
 
-- `<format>`: one of `orig`, `png`, `jpeg`, `webp`
+A request whose query string cannot be decoded, or gives any parameter more
+than once, is refused with 400.
+
+- `<format>`: one of `orig` (or `original`), `jpeg` (or `jpg`), `png`, `webp`,
+  `avif`, `gif`
 - `<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.
+
+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 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
+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`). 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`.
+
+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
+the output: EXIF (GPS position, camera make, model and serial number, capture
+time, embedded thumbnail), XMP, IPTC and the ICC colour profile. This cannot be
+turned off.
+
+- The `orig` format means the source's own format, not the source's bytes: an
+  `orig` image is re-encoded and stripped like any other.
+- An image with an EXIF orientation is turned upright first, so it displays the
+  same without the tag; a requested size applies to the upright image.
+- 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.
 
 ### Source Hosts
 
@@ -68,14 +338,14 @@ hosts require an HMAC-SHA256 signature.
 
 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) must
+component (host, path, query, dimensions, format, expiration, quality,
-match exactly what was signed. No suffix matching, wildcard matching,
+fit) must match exactly what was signed. No suffix matching, wildcard
-or partial matching is supported.
+matching, or partial matching is supported.
 
 **Signed data format** (colon-separated):
 
 ```
-HMAC-SHA256(secret, "host:path:query:width:height:format:expiration")
+HMAC-SHA256(secret, "host:path:query:width:height:format:expiration:quality:fit")
 ```
 
 Where:
@@ -85,19 +355,39 @@ 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)
+- `format` — output format, one of those listed under Routes, with `original`
-- `expiration` — Unix timestamp when signature expires
+  signed as `orig` and `jpg` as `jpeg`
+- `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
 
-**Example:** resize
+The URL's `sig` is the HMAC-SHA256 result in base64url (the URL-safe alphabet
-`https://cdn.example.com/photos/cat.jpg` to 800x600 WebP with
+of RFC 4648) with the trailing `=` padding kept, 44 characters in all. pixa
-expiration 1704067200:
+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:
 
 1. Build input:
-   `cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200`
+   `cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200:85:cover`
-2. Compute HMAC-SHA256 with your secret key
+2. Compute HMAC-SHA256 of it with the signing key
-3. Base64URL-encode the result
+3. Base64URL-encode the result, keeping the `=` padding:
+   `-ay7KHpfqmtIGbibDGbUuBDkymi-Ymdn0NkC6j5EJag=`
 4. URL:
-   `/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp?sig=<base64url>&exp=1704067200`
+   `/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp?sig=-ay7KHpfqmtIGbibDGbUuBDkymi-Ymdn0NkC6j5EJag=&exp=1704067200`
+
+For the same image at quality 40 with fit `contain`, the input ends in
+`:40:contain`, the signature is `5IwXUx6vf7yefhaUvFzgXZvG2o0Df4RJxPTK3pKq5VU=`,
+and the URL is
+`/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp?sig=5IwXUx6vf7yefhaUvFzgXZvG2o0Df4RJxPTK3pKq5VU=&exp=1704067200&q=40&fit=contain`.
 
 **Allowlist patterns:**
 
@@ -105,21 +395,153 @@ expiration 1704067200:
 - **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
 
-Configured via YAML file (`--config`). Key settings:
+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.
 
-- `access_control_allow_origin` — CORS origin
+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                                                                      |
+| ------------------------------------ | ------------------------------- | ---------------------------------------------------------------------------- |
+| `PIXA_SIGNING_KEY`                   | `signing_key`                   | Required: secret for signed and encrypted URLs and login, 32+ characters     |
+| `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 + 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`                |
+| `PIXA_UPSTREAM_CONNECTIONS_PER_HOST` | `upstream_connections_per_host` | Concurrent connections per upstream host; default `20`                       |
+| `PIXA_UPSTREAM_CONNECTIONS`          | `upstream_connections`          | Concurrent connections to all upstream hosts together; default `64`          |
+| `PIXA_MAX_CONCURRENT_PROCESSING`     | `max_concurrent_processing`     | Images processed at once; default the number of CPUs                         |
+| `PIXA_UPSTREAM_FETCH_TIMEOUT`        | `upstream_fetch_timeout`        | Time allowed for one fetch from an upstream host; default `30s`              |
+| `PIXA_UPSTREAM_MAX_RESPONSE_SIZE`    | `upstream_max_response_size`    | Largest upstream response accepted, in bytes; default 50 MiB                 |
+| `PIXA_DOWNSTREAM_TIMEOUT`            | `downstream_timeout`            | Time allowed for answering one client request; default `60s`                 |
+| `PIXA_ACCESS_CONTROL_ALLOW_ORIGIN`   | `access_control_allow_origin`   | CORS origin allowed to read image responses: `*` or one origin; default `*`  |
+| `PIXA_METRICS_USERNAME`              | `metrics.username`              | Username for `/metrics`, which is served only when both are set              |
+| `PIXA_METRICS_PASSWORD`              | `metrics.password`              | Password for `/metrics`; set together with the username                      |
+| `PIXA_SENTRY_DSN`                    | `sentry_dsn`                    | Sentry DSN for error reporting; empty disables it                            |
+| `PIXA_DEBUG`                         | `debug`                         | Debug logging and plain-HTTP local development; default `false`              |
+| `PIXA_MAINTENANCE_MODE`              | `maintenance_mode`              | Answer image requests with 503; the health check stays 200; default `false`  |
+
+Key settings in more detail:
+
+- `access_control_allow_origin` — the origin a browser lets read the responses
+  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
 - `allowlist_hosts` — list of allowed upstream hosts
-- `upstream_fetch_timeout` — timeout for origin requests
+- `referer_blocklist` — list of hosts whose pages may not show pixa's images, to
-- `upstream_max_response_size` — max origin response size
+  stop other sites hotlinking them. Entries are written and matched as for
-- `downstream_timeout` — client response timeout
+  `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
+- `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 adds `_pragma=busy_timeout(5000)` to any `db_url`,
+  so a write that finds another in progress 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 free space on
+  disk cache entirely; omitted defaults to 75% of the sum of the free space on
-  the filesystem containing `<state_dir>/cache/` (minimum 500 MiB)
+  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
+  finds all of them in use waits up to 10 seconds for one to free up; if none
+  does, and `downstream_timeout` has not ended first, the request is answered
+  503 with the error `server busy, try again later`
+- `max_concurrent_processing` — the most images decoded and encoded at once;
+  default the number of CPUs pixa can use (`GOMAXPROCS`), which follows a
+  container's CPU limit. A request that finds all of them in use waits up to 10
+  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 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
 
@@ -128,7 +550,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
@@ -144,13 +569,16 @@ them. We provide:
   (bootstrap, then install-precommit)
 - `script/projectname` — output the project name ("pixa")
 - `script/test` — run the test suite
-- `script/lint` — run golangci-lint
+- `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/check` — run test, lint, and fmt-check
 - `script/docker` — build the Docker image tagged via `script/projectname`
-- `script/cibuild` — CI entrypoint: `docker build .` (the Dockerfile
+- `script/docker-smoke` — build the image, start it, wait for it to be healthy
-  runs the checks, so a green build implies a green repo)
+- `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/precommit` — pre-commit checks (`go mod tidy` guard, then
   `script/check`)
 - `script/install-precommit` — install the git pre-commit hook that

TODO.md

@@ -1,28 +1,506 @@
 # Workflow
 
-* branch (from `main`)
+* 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)
-* merge to `main` if the branch is not protected, otherwise open a PR
+* 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. Recent work extracted the internal/magic,
+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
+packages. The gosec findings from the 2026-07-06 survey are resolved.
-and `make check` is green on main. The disk cache is now size-bounded
+The disk cache is now size-bounded with LRU eviction
-with LRU eviction (`cache_max_bytes`), closing the unbounded disk
+(`cache_max_bytes`), closing the unbounded disk growth DoS vector.
-growth DoS vector.
 
 # Next Step
 
-P1: implement blocked networks configuration to extend SSRF protection
+P2: security: per-IP rate limiting on the image routes
 
 # Completed Steps
 
+- 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,
+  and each of those steps names it in its command; both scripts pass a new value
+  on every run, so Docker runs the checks instead of reusing cached results,
+  while the `script/bootstrap` steps stay cached; a plain `docker build .` still
+  works, leaves it empty, and reuses the check steps only for an identical build
+  context; the `script/cibuild` comment and `README.md` no longer say that any
+  successful build implies a green repo.
+- 2026-09-29 share concurrent misses (closes #65): requests that miss the same
+  variant at once (the same cache key, so quality and fit included) share one
+  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
+  `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
+  middleware, with the `access_control_allow_origin` origin, moved from the
+  router root onto a `/v1` subrouter holding `/v1/image/` and `/v1/e/`, where it
+  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-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
+  `GetVariant` after it reads a `.meta` file, where a type `StoreVariant` added
+  meanwhile is kept over the one read, and never with the
+  `application/octet-stream` served for a variant without one; for a variant it
+  holds, `GetVariant` skips the `.meta` read, still opening the variant file and
+  taking the size from it; eviction removes the entry before deleting the files,
+  and `GetVariant` removes it when the file will not open; the cap is a
+  constant, not a setting; the unused `variantMeta` type is gone; `README.md`
+  describes it.
+- 2026-09-29 maintenance mode refuses image requests (closes #71): while
+  `maintenance_mode` is on, `/v1/image/` and `/v1/e/` answer 503 with a
+  `Retry-After` header and the JSON error body, from one middleware in
+  `internal/server/routes.go`; the health check stays 200 and reports
+  `maintenance_mode`, as the image's Docker `HEALTHCHECK` requests it and upaas
+  marks a deploy failed when its container is unhealthy; the login and URL
+  generator pages and `/metrics` keep working; documented in `README.md` and
+  `config.example.yml`.
+- 2026-09-29 bound concurrent image processing and upstream fetches (closes
+  #64): `max_concurrent_processing` (default the number of CPUs pixa can use)
+  limits the images decoded and encoded at once, and `upstream_connections`
+  (default 64) the connections to all upstream hosts together, on top of
+  `upstream_connections_per_host`; a fetch holds its connection until its image
+  has been processed, and a request whose source is cached reads it only once it
+  has a processing slot; a request that finds either limit reached waits up to
+  10 seconds for a free one, then gets 503 `server busy, try again later`;
+  libvips runs one worker thread per image with its operation cache off;
+  documented in `README.md` and `config.example.yml`.
+- 2026-09-29 Dockerfiles install through `script/bootstrap` (closes #95): the
+  `Dockerfile` lint and build stages and `Dockerfile.lint` copy `script/`,
+  `go.mod` and `go.sum`, then run `script/bootstrap` in place of their own
+  `apk add` lines, so the build dependencies are listed in one place;
+  `script/bootstrap` now also installs a C compiler when `gcc` is missing; the
+  build uses `-trimpath` and `-s -w` and keeps `CGO_ENABLED=1` for govips;
+  `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
+  `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
+  versions 0 and 1 runs neither again.
+- 2026-09-29 `trusted_proxies` advice and signature padding in `README.md`
+  (closes #150): the login-limit paragraph, the `trusted_proxies` entry and
+  `config.example.yml` say to set `trusted_proxies` to the address pixa sees for
+  requests that come through the proxy, which the request log shows as
+  `remoteIP` while it is not trusted; for a proxy on the Docker host that
+  connects over `127.0.0.1` that is the Docker network's gateway, not the
+  proxy's own address; the signature section says `sig` is base64url with the
+  `=` 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
+  "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
+  URL's expiry now fills too; `max-age` is one year, or the whole seconds left
+  until the `exp` of a `/v1/image/` URL or the expiry of an encrypted URL when
+  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):
+  `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.
+- 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
+  worked out) and, when it has an ICC profile, converted to sRGB; the `orig`
+  format is re-encoded and stripped like any other, as pixa never serves the
+  source bytes; there is no setting to keep metadata; documented in `README.md`.
+- 2026-09-28 rate limit the login form (closes #66): `POST /` is limited to 5
+  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
+  `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-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`.
+- 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
@@ -116,30 +594,16 @@ P1: implement blocked networks configuration to extend SSRF protection
 
 # Future Steps
 
-- P1: rate limit global concurrent upstream fetches to prevent
-  resource exhaustion
-- P1: strip EXIF and other metadata from processed images (privacy)
 - P2: security
-    - referer blacklist
-    - per-IP rate limiting
     - 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
-    - add all configuration options from README
-    - environment variable overrides
     - 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

cmd/pixad/main.go

@@ -4,6 +4,8 @@ package main
 import (
 	"fmt"
 	"os"
+	"os/signal"
+	"syscall"
 
 	"github.com/spf13/cobra"
 	"go.uber.org/fx"
@@ -45,6 +47,9 @@ func run(_ *cobra.Command, _ []string) {
 		_ = 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,
@@ -56,6 +61,9 @@ func run(_ *cobra.Command, _ []string) {
 			middleware.New,
 			healthcheck.New,
 		),
-		fx.Invoke(func(*server.Server) {}),
+		fx.Invoke(
+			func(log *logger.Logger) { log.Identify() },
+			func(*server.Server) {},
+		),
 	).Run()
 }

config.example.yml

@@ -1,44 +0,0 @@
-# Pixa Example Configuration
-
-# Server settings
-port: 8080
-debug: false
-maintenance_mode: false
-
-# Data directory for SQLite database and cache files
-state_dir: ./data
-
-# 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
-# Use "." prefix for wildcard subdomain matching (e.g., ".example.com" matches "cdn.example.com")
-allowlist_hosts:
-  - s3.sneak.cloud
-  - static.sneak.cloud
-  - sneak.berlin
-  - github.com
-  - user-images.githubusercontent.com
-
-# Allow HTTP upstream (only for testing, always use HTTPS in production)
-allow_http: false
-
-# Maximum concurrent connections per upstream host (default: 20)
-upstream_connections_per_host: 20
-
-# 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,
-# with a minimum of 500 MiB.
-# cache_max_bytes: 10737418240
-
-# Sentry error reporting (optional)
-sentry_dsn: ""
-
-# Metrics endpoint authentication (optional)
-# metrics:
-#   username: "admin"
-#   password: "secret"

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

@@ -0,0 +1,162 @@
+# Pixa Example Configuration
+#
+# Every key can also be set by an environment variable, which wins over
+# this file: PIXA_ plus the key in upper case, with "." written as "_"
+# (state_dir is PIXA_STATE_DIR, metrics.username is
+# PIXA_METRICS_USERNAME). The one exception is port, which is set by
+# PORT. In a variable, a list is comma-separated. A variable named in
+# this file's env: section is set while the file loads, so it overrides
+# both the environment the process was started with and this file's own
+# key.
+#
+# 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.
+
+# 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
+# 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 (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
+  - sneak.berlin
+  - 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. (default: none)
+# blocked_networks:
+#   - 100.64.0.0/10
+#   - 2001:db8::/32
+
+# CIDR ranges of the reverse proxies in front of pixa. X-Forwarded-For
+# is believed only when the direct peer is inside one of these ranges;
+# the client address in the access log and login records is then the
+# rightmost forwarded entry that is not itself a trusted proxy. A client
+# connecting directly (peer outside these ranges) cannot spoof its
+# address: the header is ignored and the peer address is used. When
+# omitted, this 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; an
+# explicit list replaces the default. An invalid CIDR aborts startup.
+# Uncomment to override the defaults with the address pixa sees for
+# requests that come through your proxy. That is not always the proxy's own
+# address: a proxy on the Docker host that connects over 127.0.0.1 is seen
+# as the gateway of the container's Docker network (172.17.0.1 on the
+# default bridge), and one that connects through another host address is
+# seen with that address. To be sure, look it up in the request log as the
+# trusted_proxies entry in README.md describes.
+# trusted_proxies:
+#   - 10.0.0.0/8
+#   - 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)
+upstream_connections_per_host: 20
+
+# Maximum concurrent connections to all upstream hosts together, on top of
+# the per-host limit (default: 64). A fetch holds its connection until its
+# image has been processed. A fetch that finds none free waits up to 10
+# seconds for one, and if none frees up the request is answered 503, unless
+# downstream_timeout has ended first.
+upstream_connections: 64
+
+# Maximum number of images decoded and encoded at once (default: the
+# number of CPUs pixa can use, which follows a container's CPU limit). A
+# request that finds none free waits up to 10 seconds for one, and if none
+# frees up it is answered 503, unless downstream_timeout has ended first.
+# max_concurrent_processing: 4
+
+# Time allowed for one fetch from an upstream host (default: 30s)
+upstream_fetch_timeout: 30s
+
+# Largest upstream response accepted, in bytes, at most 1073741824
+# (1 GiB) (default: 52428800, 50 MiB)
+upstream_max_response_size: 52428800
+
+# Time allowed for answering one client request (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.
+downstream_timeout: 60s
+
+# The origin a browser lets read the responses 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.
+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 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 DSN for error reporting (default: empty, which turns it off)
+sentry_dsn: ""
+
+# 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"

deploy/docker-entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# deploy/docker-entrypoint.sh: the Docker image's ENTRYPOINT. It runs as
+# root only to make /var/lib/pixa usable by pixad: a host directory
+# bind-mounted there keeps its host owner, often root, and data from an
+# earlier run may belong to another uid. The server itself always runs
+# as pixad.
+set -eu
+
+main() {
+    mkdir -p /var/lib/pixa
+    # Only the directory and its top-level entries are checked, so a
+    # normal start does not walk the cache. -depth gives each directory
+    # to pixad after its contents, so a start stopped part way leaves
+    # something at the top for the next start to find; -h changes a
+    # symlink itself, never the file it points to.
+    if [ -n "$(find /var/lib/pixa -maxdepth 1 \( ! -user pixad -o ! -group pixad \))" ]; then
+        find /var/lib/pixa -depth -exec chown -h pixad:pixad {} +
+    fi
+    chmod 750 /var/lib/pixa
+    exec su-exec pixad /usr/local/bin/pixad "$@"
+}
+
+main "$@"

go.mod

@@ -11,12 +11,16 @@ require (
 	github.com/getsentry/sentry-go v0.40.0
 	github.com/go-chi/chi/v5 v5.2.3
 	github.com/go-chi/cors v1.2.2
+	github.com/go-chi/httprate v0.16.0
+	github.com/gorilla/csrf v1.7.3
 	github.com/gorilla/securecookie v1.1.2
+	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/prometheus/client_golang v1.23.2
 	github.com/slok/go-http-metrics v0.13.0
 	github.com/spf13/cobra v1.10.2
 	go.uber.org/fx v1.24.0
 	golang.org/x/crypto v0.41.0
+	golang.org/x/sync v0.19.0
 	modernc.org/sqlite v1.42.2
 )
 
@@ -90,6 +94,7 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
@@ -112,6 +117,7 @@ require (
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.0 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
+	github.com/zeebo/xxh3 v1.0.2 // indirect
 	go.etcd.io/etcd/api/v3 v3.6.2 // indirect
 	go.etcd.io/etcd/client/pkg/v3 v3.6.2 // indirect
 	go.etcd.io/etcd/client/v3 v3.6.2 // indirect
@@ -129,7 +135,6 @@ require (
 	golang.org/x/image v0.34.0 // indirect
 	golang.org/x/net v0.43.0 // indirect
 	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
 	golang.org/x/sys v0.36.0 // indirect
 	golang.org/x/term v0.34.0 // indirect
 	golang.org/x/text v0.32.0 // indirect

go.sum

@@ -114,6 +114,8 @@ github.com/go-chi/chi/v5 v5.2.3 h1:WQIt9uxdsAbgIYgid+BpYc+liqQZGMHRaUwp0JUcvdE=
 github.com/go-chi/chi/v5 v5.2.3/go.mod h1:L2yAIGWB3H+phAw1NxKwWM+7eUH/lU8pOMm5hHcoops=
 github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
 github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/go-chi/httprate v0.16.0 h1:8V5DH9j6pSK6UQoBsTpvMyFxycqaKEIToyPKzHJjUa8=
+github.com/go-chi/httprate v0.16.0/go.mod h1:A8lo+qRhk+s9LiuP5saS7XCGDXRXMcrueq0NfIuCa/I=
 github.com/go-errors/errors v1.4.2 h1:J6MZopCL4uSllY1OfXM374weqZFFItUbrImctkmUxIA=
 github.com/go-errors/errors v1.4.2/go.mod h1:sIVyrIiJhuEF+Pj9Ebtd6P/rEYROXFi3BopGUQ5a5Og=
 github.com/go-jose/go-jose/v4 v4.0.5 h1:M6T8+mKZl/+fNNuFHvGIzDz7BTLQPIounk/b9dw3AaE=
@@ -175,6 +177,8 @@ github.com/googleapis/enterprise-certificate-proxy v0.3.6 h1:GW/XbdyBFQ8Qe+YAmFU
 github.com/googleapis/enterprise-certificate-proxy v0.3.6/go.mod h1:MkHOF77EYAE7qfSuSS9PU6g4Nt4e11cnsDUowfwewLA=
 github.com/googleapis/gax-go/v2 v2.14.2 h1:eBLnkZ9635krYIPD+ag1USrOAI0Nr0QYF3+/3GqO0k0=
 github.com/googleapis/gax-go/v2 v2.14.2/go.mod h1:ON64QhlJkhVtSqp4v1uaK92VyZ2gmvDQsweuyLV+8+w=
+github.com/gorilla/csrf v1.7.3 h1:BHWt6FTLZAb2HtWT5KDBf6qgpZzvtbp9QWDRKZMXJC0=
+github.com/gorilla/csrf v1.7.3/go.mod h1:F1Fj3KG23WYHE6gozCmBAezKookxbIvUJT+121wTuLk=
 github.com/gorilla/securecookie v1.1.2 h1:YCIWL56dvtr73r6715mJs5ZvhtnY73hBvEF8kXD8ePA=
 github.com/gorilla/securecookie v1.1.2/go.mod h1:NfCASbcHqRSY+3a8tlWJwsQap2VX5pwzwo4h3eOamfo=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 h1:5ZPtiqj0JL5oKWmcsq4VMaAW5ukBEgSGXEN89zeH1Jo=
@@ -224,6 +228,8 @@ github.com/hashicorp/go-version v1.2.1/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09
 github.com/hashicorp/golang-lru v0.5.0/go.mod h1:/m3WP610KZHVQ1SGc6re/UDhFvYD7pJ4Ao+sR/qLZy8=
 github.com/hashicorp/golang-lru v0.5.4 h1:YDjusn29QI/Das2iO9M0BHnIbxPeyuCHsjMW+lJfyTc=
 github.com/hashicorp/golang-lru v0.5.4/go.mod h1:iADmTwqILo4mZ8BN3D2Q6+9jd8WM5uGBxy+E8yxSoD4=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hashicorp/hcl v1.0.1-vault-7 h1:ag5OxFVy3QYTFTJODRzTKVZ6xvdfLLCA1cy/Y6xGI0I=
 github.com/hashicorp/hcl v1.0.1-vault-7/go.mod h1:XYhtn6ijBSAj6n4YqAaf7RBPS4I06AItNorpy+MoQNM=
 github.com/hashicorp/logutils v1.0.0/go.mod h1:QIAnNjmIWmVIIkWDTG1z5v++HQmx9WQRO+LraFDTW64=
@@ -249,6 +255,8 @@ github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
 github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
+github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
 github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
@@ -394,6 +402,10 @@ github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcY
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
+github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
+github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
+github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
 go.etcd.io/etcd/api/v3 v3.6.2 h1:25aCkIMjUmiiOtnBIp6PhNj4KdcURuBak0hU2P1fgRc=
 go.etcd.io/etcd/api/v3 v3.6.2/go.mod h1:eFhhvfR8Px1P6SEuLT600v+vrhdDTdcfMzmnxVXXSbk=
 go.etcd.io/etcd/client/pkg/v3 v3.6.2 h1:zw+HRghi/G8fKpgKdOcEKpnBTE4OO39T6MegA0RopVU=

internal/clientip/clientip.go

@@ -0,0 +1,119 @@
+// Package clientip resolves the real client IP address of an HTTP request
+// when pixa runs behind a reverse proxy. Forwarding headers are believed
+// only when the immediate peer is a configured trusted proxy, so an
+// untrusted client cannot spoof its address by sending the header.
+package clientip
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"slices"
+	"strings"
+)
+
+// ForwardedForHeader is the request header carrying the proxy chain. It is
+// honored only when the immediate peer is a trusted proxy.
+const ForwardedForHeader = "X-Forwarded-For"
+
+// Resolver determines the client IP of a request against a fixed set of
+// trusted proxy networks.
+type Resolver struct {
+	trusted []netip.Prefix
+}
+
+// NewResolver returns a Resolver that trusts forwarding headers only from
+// peers inside the given CIDR ranges. A nil or empty list trusts no one,
+// so the peer address is always used.
+func NewResolver(trusted []netip.Prefix) *Resolver {
+	return &Resolver{trusted: trusted}
+}
+
+// Resolve returns the client IP for a request whose direct peer is
+// remoteAddr (a "host:port" string as in http.Request.RemoteAddr) and
+// whose X-Forwarded-For header lines are forwardedFor (as returned by
+// http.Header.Values). When the peer is not a trusted proxy, the peer
+// address is returned and the header is ignored entirely. When the peer is
+// trusted, the header is walked right to left and the first address that is
+// not itself a trusted proxy is returned; this is the client the outermost
+// trusted proxy observed, and entries an untrusted client may have prepended
+// sit to its left and are never reached.
+func (r *Resolver) Resolve(remoteAddr string, forwardedFor []string) string {
+	peer := hostOnly(remoteAddr)
+
+	peerAddr, err := netip.ParseAddr(peer)
+	if err != nil || !r.isTrusted(peerAddr) {
+		return peer
+	}
+
+	for _, hop := range slices.Backward(forwardedForChain(forwardedFor)) {
+		hopAddr, err := netip.ParseAddr(hop)
+		if err != nil || r.isTrusted(hopAddr) {
+			continue
+		}
+
+		return hopAddr.String()
+	}
+
+	return peerAddr.String()
+}
+
+// isTrusted reports whether addr falls inside one of the trusted proxy
+// ranges. Addresses are unmapped first so an IPv4-mapped IPv6 form matches
+// an IPv4 range, matching the fetcher's blocklist comparison.
+func (r *Resolver) isTrusted(addr netip.Addr) bool {
+	if !addr.IsValid() {
+		return false
+	}
+
+	unmapped := addr.Unmap()
+
+	return slices.ContainsFunc(r.trusted, func(prefix netip.Prefix) bool {
+		return prefix.Contains(unmapped)
+	})
+}
+
+// hostOnly strips the port from a "host:port" address. A value without a
+// port (already a bare host) is returned unchanged.
+func hostOnly(remoteAddr string) string {
+	host, _, err := net.SplitHostPort(remoteAddr)
+	if err != nil {
+		return remoteAddr
+	}
+
+	return host
+}
+
+// forwardedForChain flattens the comma-separated entries of every
+// X-Forwarded-For header line into a single ordered, trimmed list.
+func forwardedForChain(values []string) []string {
+	var chain []string
+
+	for _, value := range values {
+		for part := range strings.SplitSeq(value, ",") {
+			trimmed := strings.TrimSpace(part)
+			if trimmed != "" {
+				chain = append(chain, trimmed)
+			}
+		}
+	}
+
+	return chain
+}
+
+// contextKey is the private key type under which the resolved client IP is
+// stored in a request context.
+type contextKey struct{}
+
+// WithClientIP returns a copy of ctx carrying the resolved client IP.
+func WithClientIP(ctx context.Context, ip string) context.Context {
+	return context.WithValue(ctx, contextKey{}, ip)
+}
+
+// FromContext returns the resolved client IP stored in ctx, or an empty
+// string if none was set.
+func FromContext(ctx context.Context) string {
+	ip, _ := ctx.Value(contextKey{}).(string)
+
+	return ip
+}

internal/clientip/clientip_test.go

@@ -0,0 +1,189 @@
+package clientip_test
+
+import (
+	"net/netip"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/clientip"
+)
+
+// Addresses reused across the resolver cases.
+const (
+	trustedRangeV4 = "10.0.0.0/8"
+	forwardedV4    = "203.0.113.7"
+	untrustedV4    = "198.51.100.9"
+	trustedPeer    = "10.0.0.1:5000"
+)
+
+// mustPrefixes parses CIDR strings into prefixes for building a resolver.
+func mustPrefixes(t *testing.T, cidrs ...string) []netip.Prefix {
+	t.Helper()
+
+	prefixes := make([]netip.Prefix, 0, len(cidrs))
+
+	for _, c := range cidrs {
+		p, err := netip.ParsePrefix(c)
+		if err != nil {
+			t.Fatalf("netip.ParsePrefix(%q) error = %v", c, err)
+		}
+
+		prefixes = append(prefixes, p)
+	}
+
+	return prefixes
+}
+
+type resolveCase struct {
+	name         string
+	trusted      []string
+	remoteAddr   string
+	forwardedFor []string
+	want         string
+}
+
+// runResolveCases runs each case against a resolver built from its trusted
+// list and checks the resolved address.
+func runResolveCases(t *testing.T, cases []resolveCase) {
+	t.Helper()
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			r := clientip.NewResolver(mustPrefixes(t, tt.trusted...))
+
+			got := r.Resolve(tt.remoteAddr, tt.forwardedFor)
+			if got != tt.want {
+				t.Errorf("Resolve(%q, %v) = %q, want %q",
+					tt.remoteAddr, tt.forwardedFor, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestResolvePeerTrust covers the trust decision on the direct peer: a
+// forwarded header is believed only from a trusted peer, and a client
+// connecting directly cannot spoof its address.
+func TestResolvePeerTrust(t *testing.T) {
+	t.Parallel()
+
+	runResolveCases(t, []resolveCase{
+		{
+			name:         "trusted peer honors forwarded client",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{forwardedV4},
+			want:         forwardedV4,
+		},
+		{
+			name:         "untrusted peer ignores forwarded header",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   untrustedV4 + ":33333",
+			forwardedFor: []string{forwardedV4},
+			want:         untrustedV4,
+		},
+		{
+			name:         "spoofed chain from untrusted peer cannot influence result",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   untrustedV4 + ":33333",
+			forwardedFor: []string{"1.2.3.4, 10.9.9.9, 127.0.0.1"},
+			want:         untrustedV4,
+		},
+		{
+			name:         "empty trusted list always uses peer",
+			trusted:      nil,
+			remoteAddr:   forwardedV4 + ":80",
+			forwardedFor: []string{"10.0.0.5"},
+			want:         forwardedV4,
+		},
+		{
+			name:         "trusted peer with no forwarded header uses peer",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: nil,
+			want:         "10.0.0.1",
+		},
+		{
+			name:         "unparseable peer is returned unchanged",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   "garbage",
+			forwardedFor: []string{forwardedV4},
+			want:         "garbage",
+		},
+	})
+}
+
+// TestResolveChainWalk covers walking the X-Forwarded-For chain from a
+// trusted peer to the rightmost entry that is not itself a trusted proxy.
+func TestResolveChainWalk(t *testing.T) {
+	t.Parallel()
+
+	runResolveCases(t, []resolveCase{
+		{
+			name:         "rightmost untrusted entry across a mixed chain",
+			trusted:      []string{trustedRangeV4, "192.168.0.0/16"},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{forwardedV4 + ", 192.168.1.1, 10.0.0.2"},
+			want:         forwardedV4,
+		},
+		{
+			name:         "spoofed client behind a trusted proxy is not believed",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{"1.2.3.4, " + untrustedV4},
+			want:         untrustedV4,
+		},
+		{
+			name:         "chain split across multiple header lines",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{forwardedV4, "10.0.0.2"},
+			want:         forwardedV4,
+		},
+		{
+			name:         "garbage entries are skipped",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{forwardedV4 + ", not-an-ip"},
+			want:         forwardedV4,
+		},
+		{
+			name:         "all-trusted chain falls back to peer",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   trustedPeer,
+			forwardedFor: []string{"10.0.0.9, 10.0.0.2"},
+			want:         "10.0.0.1",
+		},
+		{
+			name:         "trusted IPv6 peer honors forwarded client",
+			trusted:      []string{"2001:db8::/32"},
+			remoteAddr:   "[2001:db8::1]:9000",
+			forwardedFor: []string{forwardedV4},
+			want:         forwardedV4,
+		},
+		{
+			name:         "IPv4-mapped peer matches IPv4 trusted range",
+			trusted:      []string{trustedRangeV4},
+			remoteAddr:   "[::ffff:10.0.0.1]:5000",
+			forwardedFor: []string{forwardedV4},
+			want:         forwardedV4,
+		},
+	})
+}
+
+func TestContextRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	ctx := clientip.WithClientIP(t.Context(), forwardedV4)
+	if got := clientip.FromContext(ctx); got != forwardedV4 {
+		t.Errorf("FromContext = %q, want %q", got, forwardedV4)
+	}
+}
+
+func TestFromContextAbsent(t *testing.T) {
+	t.Parallel()
+
+	if got := clientip.FromContext(t.Context()); got != "" {
+		t.Errorf("FromContext with no value = %q, want empty", got)
+	}
+}

internal/config/blocked_networks_internal_test.go

@@ -0,0 +1,90 @@
+package config
+
+import (
+	"testing"
+)
+
+// TestBlockedNetworksParsed loads a valid blocked_networks list and checks
+// each CIDR is parsed into the resolved prefixes in order.
+func TestBlockedNetworksParsed(t *testing.T) {
+	t.Parallel()
+
+	yamlContent := signingKeyLine + `blocked_networks:
+  - 203.0.113.0/24
+  - 2001:db8::/32
+`
+
+	c, err := configFromYAML(t, yamlContent)
+	if err != nil {
+		t.Fatalf("valid blocked_networks should load, got error: %v", err)
+	}
+
+	want := []string{"203.0.113.0/24", "2001:db8::/32"}
+	if len(c.BlockedNetworks) != len(want) {
+		t.Fatalf("BlockedNetworks = %v, want %d entries", c.BlockedNetworks, len(want))
+	}
+
+	for i, w := range want {
+		if got := c.BlockedNetworks[i].String(); got != w {
+			t.Errorf("BlockedNetworks[%d] = %q, want %q", i, got, w)
+		}
+	}
+}
+
+// TestBlockedNetworksOmittedIsEmpty confirms an omitted key leaves the
+// operator list empty; the built-in defaults still apply in the fetcher.
+func TestBlockedNetworksOmittedIsEmpty(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.BlockedNetworks) != 0 {
+		t.Errorf("BlockedNetworks = %v, want empty", c.BlockedNetworks)
+	}
+}
+
+// TestBlockedNetworksInvalidAbortsStartup checks that malformed values abort
+// startup with an error naming the key and the offending value.
+func TestBlockedNetworksInvalidAbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	runAbortCases(t, []abortCase{
+		{
+			name: "not-a-cidr",
+			yaml: signingKeyLine + `blocked_networks:
+  - not-a-cidr
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks, "not-a-cidr"},
+		},
+		{
+			name: "bare-address-without-prefix",
+			yaml: signingKeyLine + `blocked_networks:
+  - 10.0.0.1
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks, "10.0.0.1"},
+		},
+		{
+			name: "empty-entry",
+			yaml: signingKeyLine + `blocked_networks:
+  - ""
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks},
+		},
+		{
+			name: "non-string-entry",
+			yaml: signingKeyLine + `blocked_networks:
+  - 42
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks},
+		},
+		{
+			name: "null-value",
+			yaml: signingKeyLine + `blocked_networks:
+`,
+			wantErrSubstrings: []string{keyBlockedNetworks, nullValueText},
+		},
+	})
+}

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
+// TestCacheMaxBytesExplicitIsRecorded verifies that an omitted
-// computed default is 75% of the probed free space when that exceeds
+// cache_max_bytes is recorded as not explicit, so the cache works out
-// the floor.
+// the default when it opens, and that an explicit zero is recorded as
-func TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace(t *testing.T) {
+// explicit, so it disables the disk cache instead.
+func TestCacheMaxBytesExplicitIsRecorded(t *testing.T) {
 	t.Parallel()
 
-	// 4 GiB free -> 3 GiB default.
+	signingKeyLine := "signing_key: " + validTestSigningKey + "\n"
-	probe := func(string) (uint64, error) { return 4294967296, nil }
 
-	got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
+	omitted, err := configFromYAML(t, signingKeyLine)
-	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")
 	if err != nil {
 		t.Fatalf("minimal config should be valid, got error: %v", err)
 	}
 
-	c.StateDir = t.TempDir()
+	if omitted.CacheMaxBytesExplicit {
-	wantCacheDir := filepath.Join(c.StateDir, "cache")
+		t.Error("omitted cache_max_bytes recorded as explicit")
-
-	var probedPath string
-
-	// 4 GiB free -> 3 GiB default.
-	probe := func(path string) (uint64, error) {
-		probedPath = path
-
-		return 4294967296, nil
 	}
 
-	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 {
+	if !zero.CacheMaxBytesExplicit {
-		t.Errorf("CacheMaxBytes = %d, want computed default 3221225472",
+		t.Error("cache_max_bytes: 0 not recorded as explicit")
-			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)
 	}
 }

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/concurrency_limits_internal_test.go

@@ -0,0 +1,162 @@
+package config
+
+import (
+	"runtime"
+	"testing"
+)
+
+// The variables that set the two concurrency limits.
+const (
+	testMaxConcurrentProcessingVar = "PIXA_MAX_CONCURRENT_PROCESSING"
+	testUpstreamConnectionsVar     = "PIXA_UPSTREAM_CONNECTIONS"
+)
+
+// TestOmittedConcurrencyLimitsUseDefaults checks that an omitted
+// max_concurrent_processing is the number of CPUs Go uses and an omitted
+// upstream_connections is 64.
+func TestOmittedConcurrencyLimitsUseDefaults(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 c.MaxConcurrentProcessing != runtime.GOMAXPROCS(0) {
+		t.Errorf("MaxConcurrentProcessing = %d, want %d, one per CPU",
+			c.MaxConcurrentProcessing, runtime.GOMAXPROCS(0))
+	}
+
+	if c.UpstreamConnections != 64 {
+		t.Errorf("UpstreamConnections = %d, want 64", c.UpstreamConnections)
+	}
+}
+
+// TestExplicitConcurrencyLimitsAreUsed checks that valid values for the
+// two limits are used as given.
+func TestExplicitConcurrencyLimitsAreUsed(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+
+		"max_concurrent_processing: 3\nupstream_connections: 10\n")
+	if err != nil {
+		t.Fatalf("valid config should load, got error: %v", err)
+	}
+
+	if c.MaxConcurrentProcessing != 3 {
+		t.Errorf("MaxConcurrentProcessing = %d, want 3", c.MaxConcurrentProcessing)
+	}
+
+	if c.UpstreamConnections != 10 {
+		t.Errorf("UpstreamConnections = %d, want 10", c.UpstreamConnections)
+	}
+}
+
+// TestInvalidConcurrencyLimitAbortsStartup checks that a limit that is
+// not a whole number of at least 1, or is null, aborts startup naming the
+// key and the value, and the variable too where the value could have come
+// from it.
+func TestInvalidConcurrencyLimitAbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	processing := keyMaxConcurrentProcessing
+	connections := keyUpstreamConnections
+
+	runAbortCases(t, []abortCase{
+		{
+			name: "max_concurrent_processing zero",
+			yaml: signingKeyLine + processing + ": 0\n",
+			wantErrSubstrings: []string{
+				processing, testMaxConcurrentProcessingVar, "value 0",
+			},
+		},
+		{
+			name: "max_concurrent_processing negative",
+			yaml: signingKeyLine + processing + ": -2\n",
+			wantErrSubstrings: []string{
+				processing, testMaxConcurrentProcessingVar, "value -2",
+			},
+		},
+		{
+			name: "max_concurrent_processing not a number",
+			yaml: signingKeyLine + processing + ": lots\n",
+			wantErrSubstrings: []string{
+				processing, testMaxConcurrentProcessingVar, "lots",
+			},
+		},
+		{
+			name:              "max_concurrent_processing fractional",
+			yaml:              signingKeyLine + processing + ": 1.5\n",
+			wantErrSubstrings: []string{processing, "1.5"},
+		},
+		{
+			name:              "max_concurrent_processing null",
+			yaml:              signingKeyLine + processing + ": null\n",
+			wantErrSubstrings: []string{processing, nullValueText},
+		},
+		{
+			name: "upstream_connections zero",
+			yaml: signingKeyLine + connections + ": 0\n",
+			wantErrSubstrings: []string{
+				connections, testUpstreamConnectionsVar, "value 0",
+			},
+		},
+		{
+			name: "upstream_connections negative",
+			yaml: signingKeyLine + connections + ": -5\n",
+			wantErrSubstrings: []string{
+				connections, testUpstreamConnectionsVar, "value -5",
+			},
+		},
+		{
+			name: "upstream_connections not a number",
+			yaml: signingKeyLine + connections + ": many\n",
+			wantErrSubstrings: []string{
+				connections, testUpstreamConnectionsVar, "many",
+			},
+		},
+		{
+			name:              "upstream_connections null",
+			yaml:              signingKeyLine + connections + ": null\n",
+			wantErrSubstrings: []string{connections, nullValueText},
+		},
+	})
+}
+
+// TestConcurrencyLimitsFromEnvironment checks that the two variables set
+// the limits over the config file, and that an invalid value in either
+// aborts startup naming the variable and the value.
+func TestConcurrencyLimitsFromEnvironment(t *testing.T) {
+	t.Setenv(testMaxConcurrentProcessingVar, "3")
+	t.Setenv(testUpstreamConnectionsVar, "10")
+
+	c, err := configFromYAML(t, signingKeyLine+
+		"max_concurrent_processing: 5\nupstream_connections: 50\n")
+	if err != nil {
+		t.Fatalf("limits from the environment should load: %v", err)
+	}
+
+	if c.MaxConcurrentProcessing != 3 || c.UpstreamConnections != 10 {
+		t.Errorf("limits = %d and %d, want 3 and 10 from the environment",
+			c.MaxConcurrentProcessing, c.UpstreamConnections)
+	}
+
+	cases := []struct {
+		variable string
+		value    string
+	}{
+		{testMaxConcurrentProcessingVar, "lots"},
+		{testMaxConcurrentProcessingVar, "0"},
+		{testUpstreamConnectionsVar, "-1"},
+		{testUpstreamConnectionsVar, "ten"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.variable+"="+tc.value, func(t *testing.T) {
+			t.Setenv(tc.variable, tc.value)
+
+			_, err := configFromYAML(t, signingKeyLine)
+			wantStartupError(t, err, tc.variable, tc.value)
+		})
+	}
+}

internal/config/config_validation_internal_test.go

@@ -1,13 +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
@@ -93,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()
 
@@ -181,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) {
@@ -283,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",
@@ -303,6 +372,11 @@ func invalidHostAndCredentialCases() []abortCase {
 			yaml:              "signing_key: short\n",
 			wantErrSubstrings: []string{keySigningKey},
 		},
+		{
+			name:              "signing_key is the documented placeholder",
+			yaml:              "signing_key: " + placeholderSigningKey + "\n",
+			wantErrSubstrings: []string{keySigningKey},
+		},
 		{
 			name:              "signing_key missing",
 			yaml:              "port: 8080\n",
@@ -558,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()
 
@@ -594,3 +778,244 @@ func TestEnsureStateDirFailsOnUncreatablePath(t *testing.T) {
 		t.Errorf("error %q does not name the offending key state_dir", err.Error())
 	}
 }
+
+// TestOmittedOriginTimeoutsAndSizeUseDefaults checks that the CORS
+// origin, the upstream fetch timeout, the upstream response size limit
+// and the downstream timeout default to the values pixa used before they
+// could be configured.
+func TestOmittedOriginTimeoutsAndSizeUseDefaults(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 c.AccessControlAllowOrigin != "*" {
+		t.Errorf("AccessControlAllowOrigin = %q, want *", c.AccessControlAllowOrigin)
+	}
+
+	if c.UpstreamFetchTimeout != 30*time.Second {
+		t.Errorf("UpstreamFetchTimeout = %v, want 30s", c.UpstreamFetchTimeout)
+	}
+
+	if c.UpstreamMaxResponseSize != 50<<20 {
+		t.Errorf("UpstreamMaxResponseSize = %d, want %d (50 MiB)",
+			c.UpstreamMaxResponseSize, 50<<20)
+	}
+
+	if c.DownstreamTimeout != 60*time.Second {
+		t.Errorf("DownstreamTimeout = %v, want 60s", c.DownstreamTimeout)
+	}
+}
+
+// TestExplicitOriginTimeoutsAndSizeAreUsed checks that valid values for
+// the CORS origin, the two timeouts and the response size limit are used
+// as given. The size is the largest accepted, 1 GiB.
+func TestExplicitOriginTimeoutsAndSizeAreUsed(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+`
+access_control_allow_origin: https://app.example.com
+upstream_fetch_timeout: 10s
+upstream_max_response_size: 1073741824
+downstream_timeout: 2m
+`)
+	if err != nil {
+		t.Fatalf("valid config should load, got error: %v", err)
+	}
+
+	if c.AccessControlAllowOrigin != "https://app.example.com" {
+		t.Errorf("AccessControlAllowOrigin = %q, want https://app.example.com",
+			c.AccessControlAllowOrigin)
+	}
+
+	if c.UpstreamFetchTimeout != 10*time.Second {
+		t.Errorf("UpstreamFetchTimeout = %v, want 10s", c.UpstreamFetchTimeout)
+	}
+
+	if c.UpstreamMaxResponseSize != 1073741824 {
+		t.Errorf("UpstreamMaxResponseSize = %d, want 1073741824",
+			c.UpstreamMaxResponseSize)
+	}
+
+	if c.DownstreamTimeout != 2*time.Minute {
+		t.Errorf("DownstreamTimeout = %v, want 2m", c.DownstreamTimeout)
+	}
+}
+
+// TestOriginWithPortOrAnyOriginIsAccepted checks the other accepted forms
+// of access_control_allow_origin: "*", an origin with a port, and origins
+// whose host is an IPv4 or IPv6 address.
+func TestOriginWithPortOrAnyOriginIsAccepted(t *testing.T) {
+	t.Parallel()
+
+	for _, origin := range []string{
+		"*", "http://localhost:3000", "http://192.0.2.1", "http://[2001:db8::1]:8080",
+	} {
+		c, err := configFromYAML(t, signingKeyLine+
+			"access_control_allow_origin: \""+origin+"\"\n")
+		if err != nil {
+			t.Fatalf("origin %q should be accepted, got error: %v", origin, err)
+		}
+
+		if c.AccessControlAllowOrigin != origin {
+			t.Errorf("AccessControlAllowOrigin = %q, want %q",
+				c.AccessControlAllowOrigin, origin)
+		}
+	}
+}
+
+// invalidTimeoutCases are configs where upstream_fetch_timeout or
+// downstream_timeout is not a positive Go duration string; each must
+// abort startup naming the key and the value.
+func invalidTimeoutCases() []abortCase {
+	return []abortCase{
+		{
+			name:              "upstream_fetch_timeout not a duration",
+			yaml:              signingKeyLine + "upstream_fetch_timeout: soon\n",
+			wantErrSubstrings: []string{keyUpstreamFetchTimeout, "soon"},
+		},
+		{
+			name:              "upstream_fetch_timeout number without a unit",
+			yaml:              signingKeyLine + "upstream_fetch_timeout: 45\n",
+			wantErrSubstrings: []string{keyUpstreamFetchTimeout, "45"},
+		},
+		{
+			name:              "upstream_fetch_timeout zero",
+			yaml:              signingKeyLine + "upstream_fetch_timeout: 0s\n",
+			wantErrSubstrings: []string{keyUpstreamFetchTimeout, "0s"},
+		},
+		{
+			name:              "upstream_fetch_timeout negative",
+			yaml:              signingKeyLine + "upstream_fetch_timeout: -5s\n",
+			wantErrSubstrings: []string{keyUpstreamFetchTimeout, "-5s"},
+		},
+		{
+			name:              "upstream_fetch_timeout null",
+			yaml:              signingKeyLine + "upstream_fetch_timeout: null\n",
+			wantErrSubstrings: []string{keyUpstreamFetchTimeout, nullValueText},
+		},
+		{
+			name:              "downstream_timeout not a duration",
+			yaml:              signingKeyLine + "downstream_timeout: 1 minute\n",
+			wantErrSubstrings: []string{keyDownstreamTimeout, "1 minute"},
+		},
+		{
+			name:              "downstream_timeout zero",
+			yaml:              signingKeyLine + "downstream_timeout: 0s\n",
+			wantErrSubstrings: []string{keyDownstreamTimeout, "0s"},
+		},
+		{
+			name:              "downstream_timeout negative",
+			yaml:              signingKeyLine + "downstream_timeout: -1m\n",
+			wantErrSubstrings: []string{keyDownstreamTimeout, "-1m"},
+		},
+		{
+			name:              "downstream_timeout null",
+			yaml:              signingKeyLine + "downstream_timeout:\n",
+			wantErrSubstrings: []string{keyDownstreamTimeout, nullValueText},
+		},
+	}
+}
+
+// invalidSizeAndOriginCases are configs where upstream_max_response_size
+// is not a whole number of bytes from 1 to 1 GiB, or
+// access_control_allow_origin is neither "*" nor an origin; each must
+// abort startup naming the key and the value.
+func invalidSizeAndOriginCases() []abortCase {
+	badOrigins := []string{
+		"",                           // empty
+		"example.com",                // no scheme
+		"https://example.com/images", // a path
+		"https://example.com/",       // a trailing slash
+		// The CORS middleware reads a * inside an origin as a pattern
+		// that lets other sites read responses.
+		"https://*",
+		"https://*.example.com",
+		"https://*example.com",
+		"https://a.com,b.com",       // two hosts
+		"https://example.com:",      // an empty port
+		"https://:8443",             // no host
+		"https://example.com:0",     // a port below 1
+		"https://example.com:99999", // a port above 65535
+		"https://exämple.com",       // a host name that is not ASCII
+		"https://example.com:443",   // the default port for https
+		"http://example.com:80",     // the default port for http
+		"https://example.com:08080", // a port with a leading zero
+		"https://01.2.3.4",          // an IPv4 address with a leading zero
+		"https://10.0.0",            // an IPv4 address with three parts
+		"https://192.168.1.256",     // an IPv4 address part above 255
+		"https://example.123",       // a host name whose last part is a number
+		"https://[0:0:0:0:0:0:0:1]", // an IPv6 address not in its shortest form
+		"file://example.com",        // a scheme other than http or https
+		"HTTPS://example.com",       // a scheme in upper case
+		"https://Example.com",       // a host name in upper case
+	}
+
+	cases := make([]abortCase, 0, len(badOrigins))
+	for _, origin := range badOrigins {
+		cases = append(cases, abortCase{
+			name: "access_control_allow_origin " + origin,
+			yaml: signingKeyLine +
+				"access_control_allow_origin: \"" + origin + "\"\n",
+			wantErrSubstrings: []string{keyAccessControlAllowOrigin, origin},
+		})
+	}
+
+	return append(cases, []abortCase{
+		{
+			name:              "access_control_allow_origin null",
+			yaml:              signingKeyLine + "access_control_allow_origin: null\n",
+			wantErrSubstrings: []string{keyAccessControlAllowOrigin, nullValueText},
+		},
+		{
+			name:              "upstream_max_response_size with a unit",
+			yaml:              signingKeyLine + "upstream_max_response_size: 50MB\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, "50MB"},
+		},
+		{
+			name:              "upstream_max_response_size fractional",
+			yaml:              signingKeyLine + "upstream_max_response_size: 1.5\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, "1.5"},
+		},
+		{
+			name:              "upstream_max_response_size zero",
+			yaml:              signingKeyLine + "upstream_max_response_size: 0\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, "0"},
+		},
+		{
+			name:              "upstream_max_response_size negative",
+			yaml:              signingKeyLine + "upstream_max_response_size: -1\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, "-1"},
+		},
+		{
+			name:              "upstream_max_response_size null",
+			yaml:              signingKeyLine + "upstream_max_response_size: null\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, nullValueText},
+		},
+		{
+			name:              "upstream_max_response_size above 1 GiB",
+			yaml:              signingKeyLine + "upstream_max_response_size: 1073741825\n",
+			wantErrSubstrings: []string{keyUpstreamMaxResponseSize, "1073741825"},
+		},
+		{
+			name: "upstream_max_response_size largest 64-bit integer",
+			yaml: signingKeyLine +
+				"upstream_max_response_size: 9223372036854775807\n",
+			wantErrSubstrings: []string{
+				keyUpstreamMaxResponseSize, "9223372036854775807",
+			},
+		},
+	}...)
+}
+
+// TestInvalidOriginTimeoutOrSizeAbortsStartup verifies the
+// no-silent-fallback rule for the CORS origin, the two timeouts and the
+// response size limit: a value that does not parse or is out of range
+// aborts startup naming the key and the value.
+func TestInvalidOriginTimeoutOrSizeAbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	runAbortCases(t, append(invalidTimeoutCases(), invalidSizeAndOriginCases()...))
+}

internal/config/env_internal_test.go

@@ -0,0 +1,406 @@
+package config
+
+import (
+	"net/netip"
+	"os"
+	"path/filepath"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/globals"
+	"sneak.berlin/go/pixa/internal/logger"
+)
+
+// TestMain unsets PORT and every PIXA_ environment variable before the
+// tests run, so each test sees only the variables it sets itself, not
+// whatever the shell running the tests exports.
+func TestMain(m *testing.M) {
+	for _, entry := range os.Environ() {
+		name, _, _ := strings.Cut(entry, "=")
+		if name != "PORT" && !strings.HasPrefix(name, "PIXA_") {
+			continue
+		}
+
+		err := os.Unsetenv(name)
+		if err != nil {
+			panic(err)
+		}
+	}
+
+	m.Run()
+}
+
+// wantStartupError fails the test unless err is a startup error that
+// mentions every one of wants.
+func wantStartupError(t *testing.T, err error, wants ...string) {
+	t.Helper()
+
+	if err == nil {
+		t.Fatalf("want a startup error mentioning %q, got none", wants)
+	}
+
+	t.Logf("got expected error: %v", err)
+
+	for _, want := range wants {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not mention %q", err.Error(), want)
+		}
+	}
+}
+
+// TestEnvironmentSetsEveryKey sets every key from its environment
+// variable, with no config file at all: PORT for the port, and PIXA_
+// plus the key in upper case, "." written as "_", for every other key.
+func TestEnvironmentSetsEveryKey(t *testing.T) {
+	t.Setenv("PIXA_DEBUG", "true")
+	t.Setenv("PIXA_MAINTENANCE_MODE", "1")
+	t.Setenv("PORT", "9090")
+	t.Setenv("PIXA_STATE_DIR", "/srv/pixa-env")
+	t.Setenv("PIXA_SENTRY_DSN", "https://abc123@sentry.example.com/42")
+	t.Setenv("PIXA_DB_URL", "file:/srv/pixa-env/other.sqlite3")
+	t.Setenv("PIXA_METRICS_USERNAME", "metricsuser")
+	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")
+	t.Setenv("PIXA_MAX_CONCURRENT_PROCESSING", "3")
+	t.Setenv("PIXA_CACHE_MAX_BYTES", "1024")
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24")
+	t.Setenv("PIXA_TRUSTED_PROXIES", "192.0.2.0/24")
+	t.Setenv("PIXA_ACCESS_CONTROL_ALLOW_ORIGIN", "https://app.example.com")
+	t.Setenv("PIXA_UPSTREAM_FETCH_TIMEOUT", "10s")
+	t.Setenv("PIXA_UPSTREAM_MAX_RESPONSE_SIZE", "1048576")
+	t.Setenv("PIXA_DOWNSTREAM_TIMEOUT", "2m")
+
+	c, err := newFromSmartConfig(nil)
+	if err != nil {
+		t.Fatalf("configuration from the environment alone should load: %v", err)
+	}
+
+	want := Config{
+		Debug:                      true,
+		MaintenanceMode:            true,
+		Port:                       9090,
+		StateDir:                   "/srv/pixa-env",
+		SentryDSN:                  "https://abc123@sentry.example.com/42",
+		DBURL:                      "file:/srv/pixa-env/other.sqlite3",
+		MetricsUsername:            "metricsuser",
+		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,
+		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",
+		UpstreamFetchTimeout:       10 * time.Second,
+		UpstreamMaxResponseSize:    1048576,
+		DownstreamTimeout:          2 * time.Minute,
+	}
+
+	if !reflect.DeepEqual(*c, want) {
+		t.Errorf("config from the environment =\n%+v\nwant\n%+v", *c, want)
+	}
+}
+
+// TestUnknownPixaVariableAbortsStartup checks that a PIXA_ variable that
+// is not a setting's variable, such as a misspelled one, aborts startup
+// naming it, as an unknown config key does, instead of being ignored.
+func TestUnknownPixaVariableAbortsStartup(t *testing.T) {
+	t.Setenv("PIXA_TRUSTED_PROXY", "192.0.2.0/24")
+	t.Setenv("PIXA_SIGNINGKEY", validTestSigningKey)
+
+	err := validateKnownEnvVars()
+	wantStartupError(t, err, "PIXA_TRUSTED_PROXY", "PIXA_SIGNINGKEY")
+}
+
+// TestPixaPortAbortsStartupPointingToPort checks that PIXA_PORT aborts
+// startup with a message saying to use PORT, which sets the port.
+func TestPixaPortAbortsStartupPointingToPort(t *testing.T) {
+	t.Setenv("PIXA_PORT", "9090")
+
+	err := validateKnownEnvVars()
+	wantStartupError(t, err, "PIXA_PORT", "use PORT")
+}
+
+// TestSettingVariablesAndConfigPathAreAccepted checks that every
+// setting's variable and PIXA_CONFIG_PATH pass the check for unknown
+// PIXA_ variables. TestEnvironmentSetsEveryKey pins the names in the list.
+func TestSettingVariablesAndConfigPathAreAccepted(t *testing.T) {
+	// A config file's env section loaded by another test can leave a
+	// PIXA_ variable set for the whole process, so every one is unset
+	// here first; t.Setenv restores each when the test ends.
+	for _, entry := range os.Environ() {
+		name, _, _ := strings.Cut(entry, "=")
+		if !strings.HasPrefix(name, "PIXA_") {
+			continue
+		}
+
+		t.Setenv(name, "")
+
+		err := os.Unsetenv(name)
+		if err != nil {
+			t.Fatalf("failed to unset %s: %v", name, err)
+		}
+	}
+
+	t.Setenv("PIXA_CONFIG_PATH", "/etc/pixa/config.yml")
+
+	for _, name := range envVarNames() {
+		t.Setenv(name, "")
+	}
+
+	err := validateKnownEnvVars()
+	if err != nil {
+		t.Fatalf("PIXA_CONFIG_PATH and every setting's variable "+
+			"must be accepted: %v", err)
+	}
+}
+
+// configFromNew writes yamlContent to a temporary config file, points
+// PIXA_CONFIG_PATH at it, and runs New, as the server does at startup.
+// The state directory is a temporary one and the disk cache is off, so
+// New succeeds unless something in the test is wrong.
+func configFromNew(t *testing.T, yamlContent string) (*Config, error) {
+	t.Helper()
+
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yml")
+
+	err := os.WriteFile(configPath, []byte(yamlContent), 0o600)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	t.Setenv("PIXA_CONFIG_PATH", configPath)
+	t.Setenv("PIXA_STATE_DIR", filepath.Join(tmpDir, "state"))
+	t.Setenv("PIXA_CACHE_MAX_BYTES", "0")
+
+	testLogger, err := logger.New(nil, logger.Params{Globals: &globals.Globals{}})
+	if err != nil {
+		t.Fatalf("failed to create logger: %v", err)
+	}
+
+	return New(nil, Params{Logger: testLogger})
+}
+
+// TestUnknownPixaVariableAbortsNew checks that New, which the server
+// calls at startup, aborts on a misspelled PIXA_ variable.
+func TestUnknownPixaVariableAbortsNew(t *testing.T) {
+	t.Setenv("PIXA_TRUSTED_PROXY", "192.0.2.0/24")
+
+	_, err := configFromNew(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_TRUSTED_PROXY")
+}
+
+// TestUnknownPixaVariableInEnvSectionAbortsNew checks that New aborts
+// on a misspelled PIXA_ name in the config file's env section, which
+// loading the file sets as an environment variable.
+func TestUnknownPixaVariableInEnvSectionAbortsNew(t *testing.T) {
+	// The variable must be absent until the file loads. t.Setenv makes
+	// sure the one the file sets is removed when the test ends.
+	t.Setenv("PIXA_TRUSTED_PROXY", "")
+
+	err := os.Unsetenv("PIXA_TRUSTED_PROXY")
+	if err != nil {
+		t.Fatalf("failed to unset PIXA_TRUSTED_PROXY: %v", err)
+	}
+
+	_, err = configFromNew(t, signingKeyLine+
+		"env:\n  PIXA_TRUSTED_PROXY: 192.0.2.0/24\n")
+	wantStartupError(t, err, "PIXA_TRUSTED_PROXY")
+}
+
+// TestPortFromEnvironmentOverridesConfigFile checks that PORT wins over
+// the port in the config file.
+func TestPortFromEnvironmentOverridesConfigFile(t *testing.T) {
+	t.Setenv("PORT", "9090")
+
+	c, err := configFromYAML(t, signingKeyLine+"port: 8080\n")
+	if err != nil {
+		t.Fatalf("PORT=9090 with port 8080 in the file should load: %v", err)
+	}
+
+	if c.Port != 9090 {
+		t.Errorf("Port = %d, want 9090 from PORT, not 8080 from the file", c.Port)
+	}
+}
+
+// TestInvalidPortFromEnvironmentAbortsStartup checks that a PORT that is
+// not a number, or is outside the port range, aborts startup naming PORT
+// and the value, even though the file's port is valid.
+func TestInvalidPortFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PORT", "banana")
+
+	_, err := configFromYAML(t, signingKeyLine+"port: 8080\n")
+	wantStartupError(t, err, "PORT", "banana")
+
+	t.Setenv("PORT", "70000")
+
+	_, err = configFromYAML(t, signingKeyLine+"port: 8080\n")
+	wantStartupError(t, err, "PORT", "70000")
+}
+
+// TestListFromEnvironmentReplacesConfigFileList checks that a list
+// variable replaces the file's list, split on commas with the spaces
+// around each entry trimmed.
+func TestListFromEnvironmentReplacesConfigFileList(t *testing.T) {
+	t.Setenv("PIXA_ALLOWLIST_HOSTS", " cdn.example.com , .example.org ")
+
+	c, err := configFromYAML(t, signingKeyLine+
+		"allowlist_hosts:\n  - s3.sneak.cloud\n  - sneak.berlin\n")
+	if err != nil {
+		t.Fatalf("PIXA_ALLOWLIST_HOSTS should load: %v", err)
+	}
+
+	want := []string{"cdn.example.com", ".example.org"}
+	if !slices.Equal(c.AllowlistHosts, want) {
+		t.Errorf("AllowlistHosts = %v, want %v from PIXA_ALLOWLIST_HOSTS",
+			c.AllowlistHosts, want)
+	}
+}
+
+// TestInvalidBlockedNetworksFromEnvironmentAbortsStartup checks that an
+// invalid CIDR, or an empty entry, in PIXA_BLOCKED_NETWORKS aborts
+// startup naming the variable, as the same list in the file does.
+func TestInvalidBlockedNetworksFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24,not-a-cidr")
+
+	_, err := configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_BLOCKED_NETWORKS", "not-a-cidr")
+
+	t.Setenv("PIXA_BLOCKED_NETWORKS", "203.0.113.0/24,,198.51.100.0/24")
+
+	_, err = configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_BLOCKED_NETWORKS")
+}
+
+// TestInvalidDebugFromEnvironmentAbortsStartup checks that a PIXA_DEBUG
+// that strconv.ParseBool rejects aborts startup instead of defaulting.
+func TestInvalidDebugFromEnvironmentAbortsStartup(t *testing.T) {
+	t.Setenv("PIXA_DEBUG", "maybe")
+
+	_, err := configFromYAML(t, signingKeyLine)
+	wantStartupError(t, err, "PIXA_DEBUG", "maybe")
+}
+
+// TestInvalidOriginTimeoutOrSizeFromEnvironmentAbortsStartup checks that
+// an invalid CORS origin, timeout or response size limit in its variable
+// aborts startup naming the variable and the value.
+func TestInvalidOriginTimeoutOrSizeFromEnvironmentAbortsStartup(t *testing.T) {
+	cases := []struct {
+		variable string
+		value    string
+	}{
+		{"PIXA_ACCESS_CONTROL_ALLOW_ORIGIN", "example.com"},
+		{"PIXA_UPSTREAM_FETCH_TIMEOUT", "soon"},
+		{"PIXA_UPSTREAM_MAX_RESPONSE_SIZE", "50MB"},
+		{"PIXA_DOWNSTREAM_TIMEOUT", "0s"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.variable, func(t *testing.T) {
+			t.Setenv(tc.variable, tc.value)
+
+			_, err := configFromYAML(t, signingKeyLine)
+			wantStartupError(t, err, tc.variable, tc.value)
+		})
+	}
+}
+
+// TestConfigFileAloneBehavesAsBefore checks that with no variables set
+// (TestMain unsets them) the config file's values are used and omitted
+// keys take their defaults.
+func TestConfigFileAloneBehavesAsBefore(t *testing.T) {
+	t.Parallel()
+
+	c, err := configFromYAML(t, signingKeyLine+"port: 9191\n")
+	if err != nil {
+		t.Fatalf("config file should load: %v", err)
+	}
+
+	if c.Port != 9191 {
+		t.Errorf("Port = %d, want 9191 from the file", c.Port)
+	}
+
+	if c.StateDir != DefaultStateDir {
+		t.Errorf("StateDir = %q, want default %q", c.StateDir, DefaultStateDir)
+	}
+
+	if !slices.Equal(c.TrustedProxies, defaultTrustedProxies()) {
+		t.Errorf("TrustedProxies = %v, want default %v",
+			c.TrustedProxies, defaultTrustedProxies())
+	}
+}
+
+// TestEmptyTrustedProxiesFromEnvironmentTrustsNoOne checks that an empty
+// PIXA_TRUSTED_PROXIES is an empty list, like [] in the file: it trusts
+// no proxy instead of taking the default ranges.
+func TestEmptyTrustedProxiesFromEnvironmentTrustsNoOne(t *testing.T) {
+	t.Setenv("PIXA_TRUSTED_PROXIES", "")
+
+	c, err := configFromYAML(t, signingKeyLine)
+	if err != nil {
+		t.Fatalf("empty PIXA_TRUSTED_PROXIES should load: %v", err)
+	}
+
+	if len(c.TrustedProxies) != 0 {
+		t.Errorf("TrustedProxies = %v, want none", c.TrustedProxies)
+	}
+}
+
+// TestEmptyVariableDoesNotFallBackToConfigFile checks that a variable
+// that is present but empty is a set value: an empty PIXA_STATE_DIR
+// aborts startup like state_dir: "" in the file, instead of falling
+// through to the file's state_dir.
+func TestEmptyVariableDoesNotFallBackToConfigFile(t *testing.T) {
+	t.Setenv("PIXA_STATE_DIR", "")
+
+	_, err := configFromYAML(t, signingKeyLine+"state_dir: /srv/pixa-file\n")
+	wantStartupError(t, err, "PIXA_STATE_DIR")
+}
+
+// TestMissingSigningKeyNamesItsVariable checks that with no config file
+// and no PIXA_SIGNING_KEY, startup aborts naming the variable, which is
+// how a container started without it reports the problem.
+func TestMissingSigningKeyNamesItsVariable(t *testing.T) {
+	t.Parallel()
+
+	_, err := newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_SIGNING_KEY")
+}
+
+// TestSecretsFromEnvironmentAreNotPrinted checks that errors about the
+// signing key and the metrics password name their variables but never
+// print their values.
+func TestSecretsFromEnvironmentAreNotPrinted(t *testing.T) {
+	t.Setenv("PIXA_SIGNING_KEY", "short-signing-secret")
+
+	_, err := newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_SIGNING_KEY")
+
+	if strings.Contains(err.Error(), "short-signing-secret") {
+		t.Errorf("error %q prints the signing key", err.Error())
+	}
+
+	t.Setenv("PIXA_SIGNING_KEY", validTestSigningKey)
+	t.Setenv("PIXA_METRICS_PASSWORD", "metrics-password-secret")
+
+	_, err = newFromSmartConfig(nil)
+	wantStartupError(t, err, "PIXA_METRICS_PASSWORD")
+
+	if strings.Contains(err.Error(), "metrics-password-secret") {
+		t.Errorf("error %q prints the metrics password", err.Error())
+	}
+}

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/config/trusted_proxies_internal_test.go

@@ -0,0 +1,85 @@
+package config
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestTrustedProxiesConfig checks the trusted_proxies key wiring: an
+// explicit CIDR list lands in TrustedProxies in order and replaces the
+// default, an omitted key falls back to the RFC 1918 private ranges, and an
+// explicitly empty list trusts no one. The list parser itself is shared with
+// blocked_networks and is exercised in depth by that key's tests.
+func TestTrustedProxiesConfig(t *testing.T) {
+	t.Parallel()
+
+	t.Run("explicit list replaces the default in order", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := configFromYAML(t,
+			signingKeyLine+`trusted_proxies: ["10.0.0.0/8", "2001:db8::/32"]`+"\n")
+		if err != nil {
+			t.Fatalf("valid trusted_proxies should load: %v", err)
+		}
+
+		got := make([]string, len(c.TrustedProxies))
+		for i, p := range c.TrustedProxies {
+			got[i] = p.String()
+		}
+
+		if joined := strings.Join(got, ","); joined != "10.0.0.0/8,2001:db8::/32" {
+			t.Errorf("TrustedProxies = %v, want the two ranges in order", got)
+		}
+	})
+
+	t.Run("omitted key defaults to the RFC 1918 ranges", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := configFromYAML(t, signingKeyLine)
+		if err != nil {
+			t.Fatalf("minimal config should load: %v", err)
+		}
+
+		got := make([]string, len(c.TrustedProxies))
+		for i, p := range c.TrustedProxies {
+			got[i] = p.String()
+		}
+
+		want := "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+		if joined := strings.Join(got, ","); joined != want {
+			t.Errorf("TrustedProxies = %v, want the RFC 1918 ranges %q", got, want)
+		}
+	})
+
+	t.Run("explicitly empty list trusts no one", func(t *testing.T) {
+		t.Parallel()
+
+		c, err := configFromYAML(t, signingKeyLine+"trusted_proxies: []\n")
+		if err != nil {
+			t.Fatalf("empty trusted_proxies should load: %v", err)
+		}
+
+		if len(c.TrustedProxies) != 0 {
+			t.Errorf("TrustedProxies = %v, want empty", c.TrustedProxies)
+		}
+	})
+}
+
+// TestTrustedProxiesInvalidAbortsStartup checks that an invalid or null
+// value aborts startup with an error naming the key and the offending value.
+func TestTrustedProxiesInvalidAbortsStartup(t *testing.T) {
+	t.Parallel()
+
+	runAbortCases(t, []abortCase{
+		{
+			name:              "invalid cidr",
+			yaml:              signingKeyLine + `trusted_proxies: ["999.0.0.0/8"]` + "\n",
+			wantErrSubstrings: []string{keyTrustedProxies, "999.0.0.0/8"},
+		},
+		{
+			name:              "null value",
+			yaml:              signingKeyLine + "trusted_proxies:\n",
+			wantErrSubstrings: []string{keyTrustedProxies, nullValueText},
+		},
+	})
+}

internal/database/concurrent_writes_internal_test.go

@@ -0,0 +1,153 @@
+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, so the writes run on
+// separate connections, 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

@@ -4,9 +4,9 @@ package database
 import (
 	"context"
 	"database/sql"
-	"embed"
 	"errors"
 	"fmt"
+	"io/fs"
 	"log/slog"
 	"path/filepath"
 	"sort"
@@ -15,14 +15,12 @@ import (
 
 	"go.uber.org/fx"
 	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/db/migrations"
 	"sneak.berlin/go/pixa/internal/logger"
 
 	_ "modernc.org/sqlite" // SQLite driver registration
 )
 
-//go:embed schema/*.sql
-var schemaFS embed.FS
-
 // bootstrapVersion is the migration that creates the schema_migrations
 // table itself. It is applied before the normal migration loop.
 const bootstrapVersion = 0
@@ -113,29 +111,29 @@ func New(lc fx.Lifecycle, params Params) (*Database, error) {
 	return s, nil
 }
 
-// collectMigrations reads the embedded schema directory and returns
+// collectMigrations reads the embedded migrations directory and returns
 // migration filenames sorted lexicographically.
 func collectMigrations() ([]string, error) {
-	entries, err := schemaFS.ReadDir("schema")
+	entries, err := fs.ReadDir(migrations.FS(), ".")
 	if err != nil {
-		return nil, fmt.Errorf("failed to read schema directory: %w", err)
+		return nil, fmt.Errorf("failed to read migrations directory: %w", err)
 	}
 
-	var migrations []string
+	var filenames []string
 
 	for _, entry := range entries {
 		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
-			migrations = append(migrations, entry.Name())
+			filenames = append(filenames, entry.Name())
 		}
 	}
 
-	sort.Strings(migrations)
+	sort.Strings(filenames)
 
-	return migrations, nil
+	return filenames, nil
 }
 
 // bootstrapMigrationsTable ensures the schema_migrations table exists
-// by applying 000.sql if the table is missing.
+// by applying 000_migration.sql if the table is missing.
 func bootstrapMigrationsTable(ctx context.Context, db *sql.DB, log *slog.Logger) error {
 	var tableExists int
 
@@ -150,9 +148,9 @@ func bootstrapMigrationsTable(ctx context.Context, db *sql.DB, log *slog.Logger)
 		return nil
 	}
 
-	content, err := schemaFS.ReadFile("schema/000.sql")
+	content, err := fs.ReadFile(migrations.FS(), "000_migration.sql")
 	if err != nil {
-		return fmt.Errorf("failed to read bootstrap migration 000.sql: %w", err)
+		return fmt.Errorf("failed to read bootstrap migration 000_migration.sql: %w", err)
 	}
 
 	if log != nil {
@@ -177,12 +175,12 @@ func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
 		return err
 	}
 
-	migrations, err := collectMigrations()
+	filenames, err := collectMigrations()
 	if err != nil {
 		return err
 	}
 
-	for _, migration := range migrations {
+	for _, migration := range filenames {
 		version, parseErr := ParseMigrationVersion(migration)
 		if parseErr != nil {
 			return parseErr
@@ -208,7 +206,7 @@ func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
 		}
 
 		// Read and apply migration.
-		content, readErr := schemaFS.ReadFile(filepath.Join("schema", migration))
+		content, readErr := fs.ReadFile(migrations.FS(), migration)
 		if readErr != nil {
 			return fmt.Errorf("failed to read migration %s: %w", migration, readErr)
 		}
@@ -245,7 +243,17 @@ func (s *Database) DB() *sql.DB {
 }
 
 func (s *Database) connect(ctx context.Context) error {
-	dbURL := s.config.DBURL
+	// Requests and the eviction pass write on separate connections. With
+	// a busy timeout, a write that finds another one in progress 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)
 

internal/database/migrations_internal_test.go

@@ -0,0 +1,54 @@
+package database
+
+import (
+	"bytes"
+	"database/sql"
+	"log/slog"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	_ "modernc.org/sqlite" // SQLite driver registration
+)
+
+// TestApplyMigrations_SecondRunAppliesNothing applies the migrations twice
+// to one database file, as happens when pixad starts again on the database
+// it created, and checks that the second run applies none of them.
+// ApplyMigrations logs a message starting with "applying" before it runs
+// any migration, the bootstrap one included.
+func TestApplyMigrations_SecondRunAppliesNothing(t *testing.T) {
+	t.Parallel()
+
+	ctx := t.Context()
+
+	db, err := sql.Open("sqlite", filepath.Join(t.TempDir(), "state.sqlite3"))
+	if err != nil {
+		t.Fatalf("failed to open test db: %v", err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	var firstLog bytes.Buffer
+
+	err = ApplyMigrations(ctx, db, slog.New(slog.NewTextHandler(&firstLog, nil)))
+	if err != nil {
+		t.Fatalf("first ApplyMigrations failed: %v", err)
+	}
+
+	if !strings.Contains(firstLog.String(), "applying") {
+		t.Fatalf("first ApplyMigrations logged no applied migration:\n%s",
+			firstLog.String())
+	}
+
+	var secondLog bytes.Buffer
+
+	err = ApplyMigrations(ctx, db, slog.New(slog.NewTextHandler(&secondLog, nil)))
+	if err != nil {
+		t.Fatalf("second ApplyMigrations failed: %v", err)
+	}
+
+	if strings.Contains(secondLog.String(), "applying") {
+		t.Errorf("second ApplyMigrations ran a migration again:\n%s",
+			secondLog.String())
+	}
+}

internal/db/migrations/001_schema.sql

@@ -2,7 +2,7 @@
 -- Creates all tables for the pixa caching image proxy
 
 -- Source content blobs
--- Files stored at: cache/src-content/<ab>/<cd>/<sha256>
+-- Files stored at: cache/sources/<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.
 CREATE TABLE IF NOT EXISTS source_content (
@@ -16,7 +16,7 @@ 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,
@@ -56,7 +56,8 @@ CREATE INDEX IF NOT EXISTS idx_variant_content_last_accessed
     ON variant_content(last_accessed_at);
 
 -- 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/db/migrations/migrations.go

@@ -0,0 +1,15 @@
+// Package migrations provides the embedded SQL migration files.
+package migrations
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed *.sql
+var files embed.FS
+
+// FS returns the embedded filesystem containing the migration files.
+func FS() fs.FS {
+	return files
+}

internal/encurl/encurl.go

@@ -103,7 +103,8 @@ func (g *Generator) Parse(token string) (*Payload, error) {
 }
 
 // ToImageRequest converts the payload to an ImageRequest.
-// Applies default values for omitted optional fields.
+// Applies default values for omitted optional fields. An ExpiresAt of 0, a URL
+// that never expires, gives the zero Expires.
 func (p *Payload) ToImageRequest() *imgcache.ImageRequest {
 	format := p.Format
 	if format == "" {
@@ -120,6 +121,11 @@ func (p *Payload) ToImageRequest() *imgcache.ImageRequest {
 		fitMode = DefaultFitMode
 	}
 
+	var expires time.Time
+	if p.ExpiresAt != 0 {
+		expires = time.Unix(p.ExpiresAt, 0)
+	}
+
 	return &imgcache.ImageRequest{
 		SourceHost:  p.SourceHost,
 		SourcePath:  p.SourcePath,
@@ -131,6 +137,7 @@ func (p *Payload) ToImageRequest() *imgcache.ImageRequest {
 		Format:  format,
 		Quality: quality,
 		FitMode: fitMode,
+		Expires: expires,
 	}
 }
 

internal/handlers/auth.go

@@ -1,17 +1,37 @@
 package handlers
 
 import (
+	"bytes"
 	"crypto/subtle"
+	"errors"
+	"fmt"
+	"html/template"
+	"math"
 	"net/http"
 	"net/url"
 	"strconv"
 	"time"
 
+	"sneak.berlin/go/pixa/internal/clientip"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/imgcache"
 	"sneak.berlin/go/pixa/internal/templates"
 )
 
+// errInvalidFormField reports a generator form field, or the q or exp
+// parameter of /v1/image/, whose value is non-numeric or out of range. The
+// offending field name is wrapped in so the response can name it.
+var errInvalidFormField = errors.New("invalid")
+
+// Bounds for the generator's quality and ttl fields; the quality bounds also
+// apply to the q parameter of /v1/image/. maxTTL is in seconds: the expiry
+// calculation time.Duration(ttl) * time.Second overflows above it.
+const (
+	minQuality = 1
+	maxQuality = 100
+	maxTTL     = int(math.MaxInt64 / time.Second)
+)
+
 // HandleRoot serves the login page or generator page based on authentication state.
 func (s *Handlers) HandleRoot() http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
@@ -23,13 +43,13 @@ func (s *Handlers) HandleRoot() http.HandlerFunc {
 
 		// Check if authenticated
 		if s.sessMgr.IsAuthenticated(r) {
-			s.renderGenerator(w, nil)
+			s.renderGenerator(w, r, nil)
 
 			return
 		}
 
 		// Show login page
-		s.renderLogin(w, "")
+		s.renderLogin(w, r, "")
 	}
 }
 
@@ -37,7 +57,7 @@ func (s *Handlers) HandleRoot() http.HandlerFunc {
 func (s *Handlers) handleLoginPost(w http.ResponseWriter, r *http.Request) {
 	err := r.ParseForm()
 	if err != nil {
-		s.renderLogin(w, "Invalid form data")
+		s.renderLogin(w, r, "Invalid form data")
 
 		return
 	}
@@ -46,8 +66,9 @@ func (s *Handlers) handleLoginPost(w http.ResponseWriter, r *http.Request) {
 
 	// Constant-time comparison to prevent timing attacks
 	if subtle.ConstantTimeCompare([]byte(submittedKey), []byte(s.config.SigningKey)) != 1 {
-		s.log.Warn("failed login attempt", "remote_addr", r.RemoteAddr)
+		s.log.Warn("failed login attempt",
-		s.renderLogin(w, "Invalid signing key")
+			"remote_addr", clientip.FromContext(r.Context()))
+		s.renderLogin(w, r, "Invalid signing key")
 
 		return
 	}
@@ -56,12 +77,13 @@ func (s *Handlers) handleLoginPost(w http.ResponseWriter, r *http.Request) {
 	err = s.sessMgr.CreateSession(w)
 	if err != nil {
 		s.log.Error("failed to create session", "error", err)
-		s.renderLogin(w, "Failed to create session")
+		s.renderLogin(w, r, "Failed to create session")
 
 		return
 	}
 
-	s.log.Info("successful login", "remote_addr", r.RemoteAddr)
+	s.log.Info("successful login",
+		"remote_addr", clientip.FromContext(r.Context()))
 
 	// Redirect to generator page
 	http.Redirect(w, r, "/", http.StatusSeeOther)
@@ -87,7 +109,7 @@ func (s *Handlers) HandleGenerateURL() http.HandlerFunc {
 
 		err := r.ParseForm()
 		if err != nil {
-			s.renderGenerator(w, &generatorData{Error: "Invalid form data"})
+			s.renderGenerator(w, r, &generatorData{Error: "Invalid form data"})
 
 			return
 		}
@@ -97,18 +119,26 @@ func (s *Handlers) HandleGenerateURL() http.HandlerFunc {
 		// Validate source URL
 		parsed, err := url.Parse(sourceURL)
 		if err != nil || parsed.Host == "" {
-			s.renderGeneratorWithForm(w, "Invalid source URL", r.Form)
+			s.renderGeneratorWithForm(w, r, "Invalid source URL", r.Form,
+				http.StatusBadRequest)
 
 			return
 		}
 
-		payload, expiresAt, ttl := buildGeneratePayload(parsed, r.Form)
+		payload, expiresAt, ttl, err := buildGeneratePayload(parsed, r.Form)
+		if err != nil {
+			s.renderGeneratorWithForm(w, r, err.Error(), r.Form,
+				http.StatusBadRequest)
+
+			return
+		}
 
 		// Generate encrypted token
 		token, err := s.encGen.Generate(payload)
 		if err != nil {
 			s.log.Error("failed to generate encrypted URL", "error", err)
-			s.renderGeneratorWithForm(w, "Failed to generate URL", r.Form)
+			s.renderGeneratorWithForm(w, r, "Failed to generate URL", r.Form,
+				http.StatusInternalServerError)
 
 			return
 		}
@@ -121,7 +151,7 @@ func (s *Handlers) HandleGenerateURL() http.HandlerFunc {
 			expiresAtStr = expiresAt.Format(time.RFC3339)
 		}
 
-		s.renderGenerator(w, &generatorData{
+		s.renderGenerator(w, r, &generatorData{
 			GeneratedURL: generatedURL,
 			ExpiresAt:    expiresAtStr,
 			FormURL:      sourceURL,
@@ -136,17 +166,40 @@ func (s *Handlers) HandleGenerateURL() http.HandlerFunc {
 }
 
 // buildGeneratePayload parses the numeric form fields and assembles the
-// encrypted URL payload. ttl=0 means never expires (ExpiresAt stays 0).
+// encrypted URL payload. ttl=0 means never expires (ExpiresAt stays 0). A
+// non-numeric or out-of-range width, height, quality or ttl, or an
+// unrecognized fit mode, is a client error naming the offending field. The
+// format field is passed through unchecked.
 func buildGeneratePayload(
 	parsed *url.URL, form url.Values,
-) (*encurl.Payload, time.Time, int) {
+) (*encurl.Payload, time.Time, int, error) {
-	width, _ := strconv.Atoi(form.Get("width"))
+	width, err := parseFormDimension(form, "width")
-	height, _ := strconv.Atoi(form.Get("height"))
+	if err != nil {
-	quality, _ := strconv.Atoi(form.Get("quality"))
+		return nil, time.Time{}, 0, err
-	ttl, _ := strconv.Atoi(form.Get("ttl"))
+	}
 
-	if quality <= 0 {
+	height, err := parseFormDimension(form, "height")
-		quality = 85
+	if err != nil {
+		return nil, time.Time{}, 0, err
+	}
+
+	quality, err := parseFormInt(form, "quality",
+		encurl.DefaultQuality, minQuality, maxQuality)
+	if err != nil {
+		return nil, time.Time{}, 0, err
+	}
+
+	ttl, err := parseFormInt(form, "ttl", 0, 0, maxTTL)
+	if err != nil {
+		return nil, time.Time{}, 0, err
+	}
+
+	fitMode := imgcache.FitMode(form.Get("fit"))
+
+	err = imgcache.ValidateFitMode(fitMode)
+	if err != nil {
+		return nil, time.Time{}, 0,
+			fmt.Errorf("%w: %s", imgcache.ErrInvalidFitMode, form.Get("fit"))
 	}
 
 	var (
@@ -167,11 +220,57 @@ func buildGeneratePayload(
 		Height:      height,
 		Format:      imgcache.ImageFormat(form.Get("format")),
 		Quality:     quality,
-		FitMode:     imgcache.FitMode(form.Get("fit")),
+		FitMode:     fitMode,
 		ExpiresAt:   expiresAtUnix,
 	}
 
-	return payload, expiresAt, ttl
+	return payload, expiresAt, ttl, nil
+}
+
+// parseFormDimension reads an optional width or height form field. An empty
+// value means "original size" (0). A non-numeric value, or one
+// imgcache.ValidateDimension rejects, is an error naming the field.
+func parseFormDimension(form url.Values, field string) (int, error) {
+	raw := form.Get(field)
+	if raw == "" {
+		return 0, nil
+	}
+
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		return 0, fmt.Errorf("%w %s: not a number", errInvalidFormField, field)
+	}
+
+	err = imgcache.ValidateDimension(field, value)
+	if err != nil {
+		return 0, err
+	}
+
+	return value, nil
+}
+
+// parseFormInt reads an optional integer form field or URL query parameter,
+// returning def when the field is empty and an error naming the field when the
+// value is non-numeric or outside minValue to maxValue.
+func parseFormInt(
+	form url.Values, field string, def, minValue, maxValue int,
+) (int, error) {
+	raw := form.Get(field)
+	if raw == "" {
+		return def, nil
+	}
+
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		return 0, fmt.Errorf("%w %s: not a number", errInvalidFormField, field)
+	}
+
+	if value < minValue || value > maxValue {
+		return 0, fmt.Errorf("%w %s: must be from %d to %d",
+			errInvalidFormField, field, minValue, maxValue)
+	}
+
+	return value, nil
 }
 
 // generatorData holds template data for the generator page.
@@ -186,15 +285,20 @@ type generatorData struct {
 	FormQuality  string
 	FormFit      string
 	FormTTL      string
+	CSRFField    template.HTML
 }
 
-func (s *Handlers) renderLogin(w http.ResponseWriter, errorMsg string) {
+func (s *Handlers) renderLogin(
+	w http.ResponseWriter, r *http.Request, errorMsg string,
+) {
 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
 
 	data := struct {
-		Error string
+		Error     string
+		CSRFField template.HTML
 	}{
-		Error: errorMsg,
+		Error:     errorMsg,
+		CSRFField: csrfField(r),
 	}
 
 	err := templates.Render(w, "login.html", data)
@@ -204,24 +308,49 @@ func (s *Handlers) renderLogin(w http.ResponseWriter, errorMsg string) {
 	}
 }
 
-func (s *Handlers) renderGenerator(w http.ResponseWriter, data *generatorData) {
+func (s *Handlers) renderGenerator(
+	w http.ResponseWriter, r *http.Request, data *generatorData,
+) {
+	s.renderGeneratorStatus(w, r, data, http.StatusOK)
+}
+
+// renderGeneratorStatus renders the generator page with an explicit HTTP
+// status; a rejected form uses 400. The page is rendered into a buffer before
+// the status is written, so a template failure can still answer 500.
+func (s *Handlers) renderGeneratorStatus(
+	w http.ResponseWriter, r *http.Request, data *generatorData, status int,
+) {
 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
 
 	if data == nil {
 		data = &generatorData{}
 	}
 
-	err := templates.Render(w, "generator.html", data)
+	data.CSRFField = csrfField(r)
+
+	var page bytes.Buffer
+
+	err := templates.Render(&page, "generator.html", data)
 	if err != nil {
 		s.log.Error("failed to render generator template", "error", err)
 		http.Error(w, "Internal server error", http.StatusInternalServerError)
+
+		return
+	}
+
+	w.WriteHeader(status)
+
+	_, err = page.WriteTo(w)
+	if err != nil {
+		s.log.Error("failed to write generator page", "error", err)
 	}
 }
 
 func (s *Handlers) renderGeneratorWithForm(
-	w http.ResponseWriter, errorMsg string, form url.Values,
+	w http.ResponseWriter, r *http.Request, errorMsg string,
+	form url.Values, status int,
 ) {
-	s.renderGenerator(w, &generatorData{
+	s.renderGeneratorStatus(w, r, &generatorData{
 		Error:       errorMsg,
 		FormURL:     form.Get("url"),
 		FormWidth:   form.Get("width"),
@@ -230,7 +359,7 @@ func (s *Handlers) renderGeneratorWithForm(
 		FormQuality: form.Get("quality"),
 		FormFit:     form.Get("fit"),
 		FormTTL:     form.Get("ttl"),
-	})
+	}, status)
 }
 
 func (s *Handlers) buildGeneratedURL(r *http.Request, token, format string) string {

internal/handlers/auth_clientip_internal_test.go

@@ -0,0 +1,41 @@
+package handlers
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/clientip"
+	"sneak.berlin/go/pixa/internal/config"
+)
+
+// TestFailedLoginLogsResolvedClientIP verifies the failed-login record
+// carries the resolved client IP from the request context, not the raw
+// proxy peer address.
+func TestFailedLoginLogsResolvedClientIP(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	h := &Handlers{
+		log:    slog.New(slog.NewJSONHandler(&buf, nil)),
+		config: &config.Config{SigningKey: testSigningKey},
+	}
+
+	form := url.Values{loginKeyField: {"wrong-key"}}
+	req := httptest.NewRequestWithContext(
+		t.Context(), http.MethodPost, "/",
+		strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req = req.WithContext(clientip.WithClientIP(req.Context(), "203.0.113.7"))
+
+	h.handleLoginPost(httptest.NewRecorder(), req)
+
+	if !strings.Contains(buf.String(), `"remote_addr":"203.0.113.7"`) {
+		t.Errorf("failed-login log missing resolved client IP; got %q", buf.String())
+	}
+}

internal/handlers/auth_csrf_internal_test.go

@@ -0,0 +1,273 @@
+package handlers
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/session"
+)
+
+// testSigningKey is a throwaway signing key for the CSRF flow tests. It
+// seeds the session manager, the encrypted-URL generator, and the CSRF
+// token key, exactly as the real signing key does in production.
+const testSigningKey = "test-signing-key-0123456789abcdef"
+
+// Form field names used in the CSRF flow tests.
+const (
+	loginKeyField = "key"
+	// gorilla/csrf's default form field name, not a credential.
+	csrfTokenField = "gorilla.csrf.Token" //nolint:gosec // G101 false positive
+)
+
+// csrfFieldPattern extracts the token rendered by csrf.TemplateField into
+// the form. The field name is gorilla/csrf's default.
+var csrfFieldPattern = regexp.MustCompile(
+	`name="gorilla\.csrf\.Token" value="([^"]+)"`)
+
+// newCSRFTestRouter builds a router that mirrors the production wiring for
+// the CSRF-protected UI routes (see server.SetupRoutes): the login and
+// generator forms and their POST targets sit behind the real CSRF
+// middleware. Requests are marked plaintext (Debug: true) so the flow runs
+// over httptest's http transport without an https Referer.
+func newCSRFTestRouter(t *testing.T) (*Handlers, http.Handler) {
+	t.Helper()
+
+	cfg := &config.Config{SigningKey: testSigningKey, Debug: true}
+
+	sessMgr, err := session.NewManager(testSigningKey)
+	if err != nil {
+		t.Fatalf("session.NewManager() error = %v", err)
+	}
+
+	encGen, err := encurl.NewGenerator(testSigningKey)
+	if err != nil {
+		t.Fatalf("encurl.NewGenerator() error = %v", err)
+	}
+
+	protect, err := newCSRFProtect(testSigningKey, cfg.Debug)
+	if err != nil {
+		t.Fatalf("newCSRFProtect() error = %v", err)
+	}
+
+	h := &Handlers{
+		log:         slog.New(slog.DiscardHandler),
+		config:      cfg,
+		sessMgr:     sessMgr,
+		encGen:      encGen,
+		csrfProtect: protect,
+	}
+
+	r := chi.NewRouter()
+	r.Group(func(r chi.Router) {
+		r.Use(h.CSRF())
+		r.Get("/", h.HandleRoot())
+		r.Post("/", h.HandleRoot())
+		r.Post("/generate", h.HandleGenerateURL())
+	})
+
+	return h, r
+}
+
+// csrfCredentials performs a GET that renders a form and returns the CSRF
+// cookies the middleware set and the token embedded in the form. Passing
+// the authenticated session cookie renders the generator form instead of
+// the login form.
+func csrfCredentials(
+	t *testing.T, srv http.Handler, reqCookies []*http.Cookie,
+) ([]*http.Cookie, string) {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(
+		context.Background(), http.MethodGet, "/", nil)
+	for _, c := range reqCookies {
+		req.AddCookie(c)
+	}
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET / status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	match := csrfFieldPattern.FindStringSubmatch(rec.Body.String())
+	if match == nil {
+		t.Fatalf("no CSRF token field found in rendered form")
+	}
+
+	return rec.Result().Cookies(), match[1]
+}
+
+// postForm submits form values with the given cookies and returns the
+// recorder.
+func postForm(
+	srv http.Handler, path string,
+	cookies []*http.Cookie, form url.Values,
+) *httptest.ResponseRecorder {
+	req := httptest.NewRequestWithContext(
+		context.Background(), http.MethodPost, path,
+		strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	for _, c := range cookies {
+		req.AddCookie(c)
+	}
+
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	return rec
+}
+
+// TestLoginPostRejectedWithoutToken verifies that POST / with no CSRF token
+// is rejected. This is login CSRF: no session cookie exists yet, so the
+// protection must rest on a token bound to a pre-session cookie.
+func TestLoginPostRejectedWithoutToken(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	rec := postForm(srv, "/", nil, url.Values{loginKeyField: {testSigningKey}})
+
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("POST / without token status = %d, want %d",
+			rec.Code, http.StatusForbidden)
+	}
+}
+
+// TestLoginPostRejectedWithForeignToken verifies that a token that does not
+// match the request's CSRF cookie is rejected: a token minted for one
+// cookie cannot authorize a request carrying a different cookie.
+func TestLoginPostRejectedWithForeignToken(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newCSRFTestRouter(t)
+
+	cookiesA, _ := csrfCredentials(t, srv, nil)
+	_, tokenB := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/", cookiesA, url.Values{
+		loginKeyField:  {testSigningKey},
+		csrfTokenField: {tokenB},
+	})
+
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("POST / with foreign token status = %d, want %d",
+			rec.Code, http.StatusForbidden)
+	}
+}
+
+// TestLoginPostAcceptedWithValidToken verifies that POST / with a matching
+// cookie and token succeeds: the login is processed and a session is
+// established (303 redirect).
+func TestLoginPostAcceptedWithValidToken(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 {
+		t.Fatalf("POST / with valid token status = %d, want %d",
+			rec.Code, http.StatusSeeOther)
+	}
+
+	var authed bool
+
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == session.CookieName && c.Value != "" {
+			authed = true
+		}
+	}
+
+	if !authed {
+		t.Error("valid login did not set a session cookie")
+	}
+}
+
+// TestGeneratePostRejectedWithoutToken verifies that POST /generate is
+// rejected without a CSRF token even when the request carries a valid
+// authenticated session. The session cookie is not sufficient; the policy
+// requires a CSRF token on this cookie-authenticated form.
+func TestGeneratePostRejectedWithoutToken(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newCSRFTestRouter(t)
+
+	sessionCookie := newSessionCookie(t, h)
+
+	rec := postForm(srv, "/generate",
+		[]*http.Cookie{sessionCookie},
+		url.Values{"url": {"https://example.com/a.jpg"}})
+
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("POST /generate without token status = %d, want %d",
+			rec.Code, http.StatusForbidden)
+	}
+}
+
+// TestGeneratePostAcceptedWithValidToken verifies that POST /generate
+// succeeds with a valid session and a matching CSRF cookie and token.
+func TestGeneratePostAcceptedWithValidToken(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newCSRFTestRouter(t)
+
+	sessionCookie := newSessionCookie(t, h)
+
+	cookies, token := csrfCredentials(t, srv, []*http.Cookie{sessionCookie})
+	cookies = append(cookies, sessionCookie)
+
+	rec := postForm(srv, "/generate", cookies, url.Values{
+		"url":          {"https://example.com/a.jpg"},
+		"format":       {"jpeg"},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("POST /generate with valid token status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+
+	if !strings.Contains(rec.Body.String(), "/v1/e/") {
+		t.Error("generator response did not contain a generated URL")
+	}
+}
+
+// newSessionCookie creates an authenticated session cookie via the
+// handler's session manager.
+func newSessionCookie(t *testing.T, h *Handlers) *http.Cookie {
+	t.Helper()
+
+	rec := httptest.NewRecorder()
+
+	err := h.sessMgr.CreateSession(rec)
+	if err != nil {
+		t.Fatalf("CreateSession() error = %v", err)
+	}
+
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == session.CookieName {
+			return c
+		}
+	}
+
+	t.Fatalf("session manager did not set a %q cookie", session.CookieName)
+
+	return nil
+}

internal/handlers/auth_generate_internal_test.go

@@ -0,0 +1,163 @@
+package handlers
+
+import (
+	"maps"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// Generator form field names, and a value that is not a number.
+const (
+	widthField   = "width"
+	heightField  = "height"
+	qualityField = "quality"
+	ttlField     = "ttl"
+	fitField     = "fit"
+	notANumber   = "abc"
+)
+
+// generatePost submits the /generate form with a valid session and CSRF token
+// plus the caller's extra fields, returning the recorder.
+func generatePost(
+	t *testing.T, extra url.Values,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	h, srv := newCSRFTestRouter(t)
+
+	sessionCookie := newSessionCookie(t, h)
+	cookies, token := csrfCredentials(t, srv, []*http.Cookie{sessionCookie})
+	cookies = append(cookies, sessionCookie)
+
+	form := url.Values{
+		sourceURLField: {testSourceURL},
+		csrfTokenField: {token},
+	}
+	maps.Copy(form, extra)
+
+	return postForm(srv, "/generate", cookies, form)
+}
+
+// TestGeneratePostRejectsNonNumericWidth verifies that a non-numeric width is
+// rejected with 400 naming the field rather than being coerced to 0 and
+// minting a 0-width token.
+func TestGeneratePostRejectsNonNumericWidth(t *testing.T) {
+	t.Parallel()
+
+	rec := generatePost(t, url.Values{"width": {"abc"}})
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+
+	if strings.Contains(rec.Body.String(), "/v1/e/") {
+		t.Error("a token was generated for non-numeric width")
+	}
+}
+
+// TestGeneratePostRejectsOverLimitWidth verifies that a width beyond
+// MaxDimension is rejected at generation time so an unusable token cannot be
+// minted.
+func TestGeneratePostRejectsOverLimitWidth(t *testing.T) {
+	t.Parallel()
+
+	rec := generatePost(t, url.Values{"width": {"100000"}})
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+
+	if strings.Contains(rec.Body.String(), "/v1/e/") {
+		t.Error("a token was generated for an over-limit width")
+	}
+}
+
+// TestGeneratePostRejectsBadField verifies that each generator field whose
+// value is not a number, out of range, or unrecognized is rejected with 400,
+// mints no token, and is named in the error shown on the page.
+func TestGeneratePostRejectsBadField(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		field, value, wantError string
+	}{
+		{widthField, notANumber, "invalid width: not a number"},
+		{widthField, "-1", "width is negative"},
+		{widthField, "8193", "width is above 8192"},
+		{heightField, notANumber, "invalid height: not a number"},
+		{heightField, "8193", "height is above 8192"},
+		{qualityField, notANumber, "invalid quality: not a number"},
+		{qualityField, "0", "invalid quality: must be from 1 to 100"},
+		{qualityField, "101", "invalid quality: must be from 1 to 100"},
+		{ttlField, notANumber, "invalid ttl: not a number"},
+		{ttlField, "-1", "invalid ttl: must be from 0 to"},
+		{ttlField, "10000000000", "invalid ttl: must be from 0 to"},
+		{fitField, "bogus", "invalid fit mode: bogus"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.field+"="+tt.value, func(t *testing.T) {
+			t.Parallel()
+
+			rec := generatePost(t, url.Values{tt.field: {tt.value}})
+			body := rec.Body.String()
+
+			if rec.Code != http.StatusBadRequest {
+				t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+			}
+
+			if strings.Contains(body, "/v1/e/") {
+				t.Error("a token was generated")
+			}
+
+			if !strings.Contains(body, tt.wantError) {
+				t.Errorf("page does not show %q", tt.wantError)
+			}
+		})
+	}
+}
+
+// TestBuildGeneratePayloadDefaultAndLimits verifies that an empty quality
+// takes the default, and that the largest accepted width, height, quality and
+// ttl are accepted with an expiry still in the future.
+func TestBuildGeneratePayloadDefaultAndLimits(t *testing.T) {
+	t.Parallel()
+
+	parsed, err := url.Parse(testSourceURL)
+	if err != nil {
+		t.Fatalf("url.Parse() error = %v", err)
+	}
+
+	payload, _, _, err := buildGeneratePayload(parsed, url.Values{})
+	if err != nil {
+		t.Fatalf("empty form: error = %v", err)
+	}
+
+	if payload.Quality != encurl.DefaultQuality {
+		t.Errorf("empty quality gave %d, want %d",
+			payload.Quality, encurl.DefaultQuality)
+	}
+
+	_, expiresAt, _, err := buildGeneratePayload(parsed, url.Values{
+		widthField:   {strconv.Itoa(imgcache.MaxDimension)},
+		heightField:  {strconv.Itoa(imgcache.MaxDimension)},
+		qualityField: {strconv.Itoa(maxQuality)},
+		ttlField:     {strconv.Itoa(maxTTL)},
+	})
+	if err != nil {
+		t.Fatalf("largest accepted values: error = %v", err)
+	}
+
+	if !expiresAt.After(time.Now()) {
+		t.Errorf("ttl %d gave expiry %v, want a time in the future",
+			maxTTL, expiresAt)
+	}
+}

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/bodylimit.go

@@ -0,0 +1,45 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+)
+
+// MaxFormBytes bounds the request body accepted on the HTML form POST
+// routes (POST / and POST /generate). The forms carry a handful of short
+// fields, so 1 MiB is generous while making the bound explicit rather than
+// resting on ParseForm's incidental 10 MB cap.
+const MaxFormBytes = 1 << 20 // 1 MiB
+
+// LimitBody returns middleware that caps the request body on POST requests
+// at maxBytes and rejects an oversized body with 413 Request Entity Too
+// Large.
+//
+// It parses the form here, before the CSRF middleware reads the token from
+// it. The CSRF middleware reads the token with PostFormValue, which
+// swallows a parse error, so if the body were only capped there an
+// oversized body would read as a missing token and be refused as 403. By
+// parsing under the cap first, an oversized body is refused as 413. A
+// successful parse is cached on the request, so the CSRF check and the
+// handler reuse it rather than reading the body again.
+func (s *Handlers) LimitBody(maxBytes int64) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == http.MethodPost {
+				r.Body = http.MaxBytesReader(w, r.Body, maxBytes)
+
+				err := r.ParseForm()
+
+				var tooLarge *http.MaxBytesError
+				if errors.As(err, &tooLarge) {
+					http.Error(w, "Request body too large",
+						http.StatusRequestEntityTooLarge)
+
+					return
+				}
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}

internal/handlers/bodylimit_internal_test.go

@@ -0,0 +1,177 @@
+package handlers
+
+import (
+	"log/slog"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"sneak.berlin/go/pixa/internal/config"
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/session"
+)
+
+// Form field names and a throwaway source image URL for the body-limit
+// tests.
+const (
+	sourceURLField = "url"
+	testSourceURL  = "https://example.com/a.jpg"
+)
+
+// newBodyLimitTestRouter mirrors the production wiring for the form POST
+// routes (see server.SetupRoutes): LimitBody sits in front of the CSRF
+// middleware, which sits in front of the handlers. maxBytes is the body
+// cap under test, so a test can trip the limit with a small body.
+func newBodyLimitTestRouter(
+	t *testing.T, maxBytes int64,
+) (*Handlers, http.Handler) {
+	t.Helper()
+
+	cfg := &config.Config{SigningKey: testSigningKey, Debug: true}
+
+	sessMgr, err := session.NewManager(testSigningKey)
+	if err != nil {
+		t.Fatalf("session.NewManager() error = %v", err)
+	}
+
+	encGen, err := encurl.NewGenerator(testSigningKey)
+	if err != nil {
+		t.Fatalf("encurl.NewGenerator() error = %v", err)
+	}
+
+	protect, err := newCSRFProtect(testSigningKey, cfg.Debug)
+	if err != nil {
+		t.Fatalf("newCSRFProtect() error = %v", err)
+	}
+
+	h := &Handlers{
+		log:         slog.New(slog.DiscardHandler),
+		config:      cfg,
+		sessMgr:     sessMgr,
+		encGen:      encGen,
+		csrfProtect: protect,
+	}
+
+	r := chi.NewRouter()
+	r.Group(func(r chi.Router) {
+		r.Use(h.LimitBody(maxBytes))
+		r.Use(h.CSRF())
+		r.Get("/", h.HandleRoot())
+		r.Post("/", h.HandleRoot())
+		r.Post("/generate", h.HandleGenerateURL())
+	})
+
+	return h, r
+}
+
+// TestOversizedLoginPostRejectedBeforeCSRF is the core regression: an
+// oversized POST / carrying an otherwise valid CSRF cookie and token must
+// be rejected with 413. If the body limit ran after CSRF, the truncated
+// body would read as a missing token and return 403; if it ran after the
+// handler, a valid token would return 303. Getting 413 proves the limit
+// fires before CSRF parses the form.
+func TestOversizedLoginPostRejectedBeforeCSRF(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newBodyLimitTestRouter(t, 16)
+
+	cookies, token := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/", cookies, url.Values{
+		loginKeyField:  {testSigningKey},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("oversized POST / status = %d, want %d",
+			rec.Code, http.StatusRequestEntityTooLarge)
+	}
+}
+
+// TestOversizedGeneratePostRejectedBeforeCSRF is the same regression for
+// POST /generate, which also parses a form behind CSRF.
+func TestOversizedGeneratePostRejectedBeforeCSRF(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newBodyLimitTestRouter(t, 16)
+
+	sessionCookie := newSessionCookie(t, h)
+
+	cookies, token := csrfCredentials(t, srv, []*http.Cookie{sessionCookie})
+	cookies = append(cookies, sessionCookie)
+
+	rec := postForm(srv, "/generate", cookies, url.Values{
+		sourceURLField: {testSourceURL},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("oversized POST /generate status = %d, want %d",
+			rec.Code, http.StatusRequestEntityTooLarge)
+	}
+}
+
+// TestWithinLimitLoginPostSucceeds verifies the limit does not disturb a
+// normal request: under the production cap, a valid login still parses and
+// establishes a session (303). This guards against the body limit
+// consuming or corrupting the form the CSRF check and handler depend on.
+func TestWithinLimitLoginPostSucceeds(t *testing.T) {
+	t.Parallel()
+
+	_, srv := newBodyLimitTestRouter(t, MaxFormBytes)
+
+	cookies, token := csrfCredentials(t, srv, nil)
+
+	rec := postForm(srv, "/", cookies, url.Values{
+		loginKeyField:  {testSigningKey},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusSeeOther {
+		t.Fatalf("within-limit POST / status = %d, want %d",
+			rec.Code, http.StatusSeeOther)
+	}
+
+	var authed bool
+
+	for _, c := range rec.Result().Cookies() {
+		if c.Name == session.CookieName && c.Value != "" {
+			authed = true
+		}
+	}
+
+	if !authed {
+		t.Error("within-limit valid login did not set a session cookie")
+	}
+}
+
+// TestWithinLimitGeneratePostSucceeds is the same non-regression check for
+// POST /generate.
+func TestWithinLimitGeneratePostSucceeds(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newBodyLimitTestRouter(t, MaxFormBytes)
+
+	sessionCookie := newSessionCookie(t, h)
+
+	cookies, token := csrfCredentials(t, srv, []*http.Cookie{sessionCookie})
+	cookies = append(cookies, sessionCookie)
+
+	rec := postForm(srv, "/generate", cookies, url.Values{
+		sourceURLField: {testSourceURL},
+		"format":       {"jpeg"},
+		csrfTokenField: {token},
+	})
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("within-limit POST /generate status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+
+	if !strings.Contains(rec.Body.String(), "/v1/e/") {
+		t.Error("within-limit generate response did not contain a generated URL")
+	}
+}

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/csrf.go

@@ -0,0 +1,65 @@
+package handlers
+
+import (
+	"html/template"
+	"net/http"
+
+	"github.com/gorilla/csrf"
+
+	"sneak.berlin/go/pixa/internal/seal"
+)
+
+// csrfKeySalt provides domain separation for the CSRF authentication key,
+// derived from the signing key so tokens survive restarts without extra
+// configuration and never reuse the session or encrypted-URL key material.
+const csrfKeySalt = "pixa-csrf-v1"
+
+// newCSRFProtect builds the CSRF-protection middleware for the
+// state-mutating HTML form routes. The token lives in its own cookie,
+// independent of the session cookie, so it also protects the login POST
+// where no session exists yet (login CSRF).
+//
+// When plaintext is true (local HTTP development), requests are marked
+// plaintext so the library neither demands an https Referer nor sets a
+// Secure cookie the browser would withhold over http. In production the
+// service runs behind a TLS-terminating proxy, so plaintext is false and
+// the library enforces its https Referer origin check.
+func newCSRFProtect(
+	signingKey string, plaintext bool,
+) (func(http.Handler) http.Handler, error) {
+	key, err := seal.DeriveKey([]byte(signingKey), csrfKeySalt)
+	if err != nil {
+		return nil, err
+	}
+
+	protect := csrf.Protect(
+		key[:],
+		csrf.Path("/"),
+		csrf.Secure(!plaintext),
+		csrf.SameSite(csrf.SameSiteStrictMode),
+	)
+
+	if !plaintext {
+		return protect, nil
+	}
+
+	return func(next http.Handler) http.Handler {
+		protected := protect(next)
+
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			protected.ServeHTTP(w, csrf.PlaintextHTTPRequest(r))
+		})
+	}, nil
+}
+
+// CSRF returns the CSRF-protection middleware for the login and generator
+// form routes.
+func (s *Handlers) CSRF() func(http.Handler) http.Handler {
+	return s.csrfProtect
+}
+
+// csrfField returns the hidden form input carrying the CSRF token for the
+// given request, to be embedded verbatim in a rendered form.
+func csrfField(r *http.Request) template.HTML {
+	return csrf.TemplateField(r)
+}

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/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,65 +28,90 @@ 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.
 type Handlers struct {
-	log      *slog.Logger
+	log         *slog.Logger
-	hc       *healthcheck.Healthcheck
+	hc          *healthcheck.Healthcheck
-	db       *database.Database
+	db          *database.Database
-	config   *config.Config
+	config      *config.Config
-	imgSvc   *imgcache.Service
+	fetcher     httpfetcher.Fetcher
-	imgCache *imgcache.Cache
+	imgSvc      *imgcache.Service
-	sessMgr  *session.Manager
+	imgCache    *imgcache.Cache
-	encGen   *encurl.Generator
+	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.
 func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
+	csrfProtect, err := newCSRFProtect(params.Config.SigningKey, params.Config.Debug)
+	if err != nil {
+		return nil, err
+	}
+
 	s := &Handlers{
-		log:    params.Logger.Get(),
+		log:              params.Logger.Get(),
-		hc:     params.Healthcheck,
+		hc:               params.Healthcheck,
-		db:     params.Database,
+		db:               params.Database,
-		config: params.Config,
+		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
+		//nolint:contextcheck // the eviction loop outlives OnStart; OnStop cancels it
-		// 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
 		OnStart: func(_ context.Context) error {
 			return s.initImageService()
 		},
-		OnStop: func(_ context.Context) error {
+		OnStop: func(ctx context.Context) error {
-			if s.imgCache != nil {
+			if s.imgCache == nil {
-				s.imgCache.StopEviction()
+				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)
+}
+
+// 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
+	cache, err := imgcache.NewCache(s.db.DB(), newCacheConfig(s.config, s.log))
-	// 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,
-	})
 	if err != nil {
 		return err
 	}
@@ -99,18 +125,26 @@ func (s *Handlers) initImageService() error {
 	// Create the fetcher config
 	fetcherCfg := httpfetcher.DefaultConfig()
 	fetcherCfg.AllowHTTP = s.config.AllowHTTP
+	fetcherCfg.Timeout = s.config.UpstreamFetchTimeout
+	fetcherCfg.MaxResponseSize = s.config.UpstreamMaxResponseSize
 
 	if s.config.UpstreamConnectionsPerHost > 0 {
 		fetcherCfg.MaxConnectionsPerHost = s.config.UpstreamConnectionsPerHost
 	}
 
-	// Create the service
+	fetcherCfg.MaxConnections = s.config.UpstreamConnections
+	fetcherCfg.BlockedNetworks = s.config.BlockedNetworks
+
+	// Create the service. With no fetcher provided, it builds its own from
+	// fetcherCfg.
 	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
-		Cache:         cache,
+		Cache:                   cache,
-		FetcherConfig: fetcherCfg,
+		FetcherConfig:           fetcherCfg,
-		SigningKey:    s.config.SigningKey,
+		Fetcher:                 s.fetcher,
-		Allowlist:     s.config.AllowlistHosts,
+		SigningKey:              s.config.SigningKey,
-		Logger:        s.log,
+		Allowlist:               s.config.AllowlistHosts,
+		MaxConcurrentProcessing: s.config.MaxConcurrentProcessing,
+		Logger:                  s.log,
 	})
 	if err != nil {
 		return err

internal/handlers/handlers_internal_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"database/sql"
+	"encoding/json"
 	"image"
 	"image/color"
 	"image/jpeg"
@@ -276,3 +277,120 @@ func TestHandleImage_ETagHeader(t *testing.T) {
 		t.Errorf("ETag should be quoted, got %q", etag)
 	}
 }
+
+// TestHandleImage_InvalidFitMode_Returns400 verifies that the plain image
+// route rejects an unrecognized fit mode with 400.
+func TestHandleImage_InvalidFitMode_Returns400(t *testing.T) {
+	t.Parallel()
+
+	fix := setupTestHandler(t)
+
+	status := getImage(t, fix,
+		"/v1/image/"+fix.goodHost+"/images/photo.jpg/50x50.jpeg?fit=bogus")
+
+	if status != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", status, http.StatusBadRequest)
+	}
+}
+
+// TestHandleImage_InvalidQuery_Returns400 verifies that the plain image route
+// answers a q that is not a whole number from 1 to 100, an empty one
+// included, with 400 naming q and the value, a parameter given more than once
+// with 400 naming it, and a query string that cannot be decoded with 400
+// showing it, instead of serving the image at the default quality 85 or at
+// the first value given.
+func TestHandleImage_InvalidQuery_Returns400(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		query, wantError string
+	}{
+		{"q=banana", `invalid q: not a number, got "banana"`},
+		{"q=0", `invalid q: must be from 1 to 100, got "0"`},
+		{"q=101", `invalid q: must be from 1 to 100, got "101"`},
+		{"q=", `invalid q: not a number, got ""`},
+		{"q=80&q=500", `invalid q: given more than once`},
+		{"q=80&q=", `invalid q: given more than once`},
+		{"fit=cover&fit=contain", `invalid fit: given more than once`},
+		{"q=80%", `invalid query string "q=80%": invalid URL escape "%"`},
+		{
+			"q=50;fit=contain",
+			`invalid query string "q=50;fit=contain": ` +
+				`invalid semicolon separator in query`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			r := chi.NewRouter()
+			r.Get("/v1/image/*", fix.handler.HandleImage())
+
+			req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+				"/v1/image/"+fix.goodHost+"/images/photo.jpg/50x50.jpeg?"+tt.query, nil)
+			rec := httptest.NewRecorder()
+
+			r.ServeHTTP(rec, req)
+
+			if rec.Code != http.StatusBadRequest {
+				t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+			}
+
+			t.Logf("GET %s: %d %s", req.URL, rec.Code, rec.Body)
+
+			var body struct {
+				Error string `json:"error"`
+			}
+
+			err := json.NewDecoder(rec.Body).Decode(&body)
+			if err != nil {
+				t.Fatalf("decoding response body: %v", err)
+			}
+
+			if body.Error != tt.wantError {
+				t.Errorf("error = %q, want %q", body.Error, tt.wantError)
+			}
+		})
+	}
+}
+
+// TestHandleImage_EmptyFit_Returns400 verifies that the plain image route
+// answers a fit that is in the URL but empty with 400 naming fit, instead of
+// serving the image as cover. Only a fit missing from the URL means cover.
+func TestHandleImage_EmptyFit_Returns400(t *testing.T) {
+	t.Parallel()
+
+	fix := setupTestHandler(t)
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", fix.handler.HandleImage())
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+		"/v1/image/"+fix.goodHost+"/images/photo.jpg/50x50.jpeg?fit=", nil)
+	rec := httptest.NewRecorder()
+
+	r.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+
+	t.Logf("GET %s: %d %s", req.URL, rec.Code, rec.Body)
+
+	var body struct {
+		Error string `json:"error"`
+	}
+
+	err := json.NewDecoder(rec.Body).Decode(&body)
+	if err != nil {
+		t.Fatalf("decoding response body: %v", err)
+	}
+
+	wantError := `invalid fit: not a fit mode, got ""`
+	if body.Error != wantError {
+		t.Errorf("error = %q, want %q", body.Error, wantError)
+	}
+}

internal/handlers/image.go

@@ -2,13 +2,18 @@ package handlers
 
 import (
 	"errors"
+	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"strconv"
 	"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"
 	"sneak.berlin/go/pixa/internal/imgcache"
 )
 
@@ -16,6 +21,10 @@ import (
 // /v1/image/<host>/<path>/<width>x<height>.<format>
 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
@@ -89,39 +98,66 @@ func (s *Handlers) parseImageRequest(
 	// Convert to ImageRequest
 	req := parsed.ToImageRequest()
 
-	// Parse signature params from query string
+	// Parse signature params from query string. r.URL.Query() would silently
-	query := r.URL.Query()
+	// drop a pair it cannot decode, such as q=80%, so that q would be served
-	req.Signature = query.Get("sig")
+	// at 85; a query string that cannot be decoded is refused instead. A
+	// parameter given more than once is refused too, as only its first value
+	// would be read.
+	query, err := url.ParseQuery(r.URL.RawQuery)
+	if err != nil {
+		s.respondError(w, fmt.Sprintf("invalid query string %q: %v",
+			r.URL.RawQuery, err), http.StatusBadRequest)
 
-	if expStr := query.Get("exp"); expStr != "" {
+		return nil, false
-		exp, parseErr := strconv.ParseInt(expStr, 10, 64)
-		if parseErr == nil {
-			req.Expires = time.Unix(exp, 0)
-		}
 	}
 
-	// Parse optional quality and fit params
+	for name, values := range query {
-	if qStr := query.Get("q"); qStr != "" {
+		if len(values) > 1 {
-		q, parseErr := strconv.Atoi(qStr)
+			s.respondError(w, fmt.Sprintf("invalid %s: given more than once",
-		if parseErr == nil && q > 0 && q <= 100 {
+				name), http.StatusBadRequest)
-			req.Quality = q
-		}
-	}
-
-	if fit := query.Get("fit"); fit != "" {
-		req.FitMode = imgcache.FitMode(fit)
-
-		fitErr := imgcache.ValidateFitMode(req.FitMode)
-		if fitErr != nil {
-			s.respondError(w, "invalid fit mode: "+fit, http.StatusBadRequest)
 
 			return nil, false
 		}
 	}
 
-	// Default quality if not set
+	req.Signature = query.Get("sig")
-	if req.Quality == 0 {
+
-		req.Quality = 85
+	req.Expires, err = parseExpires(query)
+	if err != nil {
+		s.respondError(w, err.Error(), http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Parse optional quality and fit params. Only a q missing from the URL is
+	// 85. A q in the URL that is not a whole number from 1 to 100, an empty
+	// one included, is refused, checked as the generator checks its quality
+	// field; that check alone would take an empty q as missing.
+	qStr := query.Get("q")
+	if query.Has("q") && qStr == "" {
+		s.respondError(w, `invalid q: not a number, got ""`,
+			http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	req.Quality, err = parseFormInt(query, "q",
+		encurl.DefaultQuality, minQuality, maxQuality)
+	if err != nil {
+		s.respondError(w, fmt.Sprintf("%v, got %q", err, qStr),
+			http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Only a fit missing from the URL is cover. A fit in the URL that is not a
+	// fit mode is refused by the fit-mode check below; that check would take an
+	// empty fit as missing, so an empty one is refused here.
+	req.FitMode = imgcache.FitMode(query.Get("fit"))
+	if query.Has("fit") && req.FitMode == "" {
+		s.respondError(w, `invalid fit: not a fit mode, got ""`, http.StatusBadRequest)
+
+		return nil, false
 	}
 
 	// Default fit mode if not set
@@ -129,9 +165,41 @@ func (s *Handlers) parseImageRequest(
 		req.FitMode = imgcache.FitCover
 	}
 
+	// Enforce dimension and fit-mode bounds, shared with the encrypted-URL
+	// route. Dimensions are already bounded by the path parser above; this
+	// also rejects an unrecognized fit mode with 400 instead of letting it
+	// reach the processor as a 500.
+	err = imgcache.ValidateImageRequest(req)
+	if err != nil {
+		s.respondError(w, "invalid image request: "+err.Error(),
+			http.StatusBadRequest)
+
+		return nil, false
+	}
+
 	return req, true
 }
 
+// parseExpires reads the exp query parameter, a Unix time in seconds. An exp
+// missing from the URL gives the zero time, which the signature check takes
+// as no expiration. An exp in the URL that is not a whole number, an empty
+// one included, is an error naming exp and the value.
+func parseExpires(query url.Values) (time.Time, error) {
+	if !query.Has("exp") {
+		return time.Time{}, nil
+	}
+
+	expStr := query.Get("exp")
+
+	exp, err := strconv.ParseInt(expStr, 10, 64)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("%w exp: not a number, got %q",
+			errInvalidFormField, expStr)
+	}
+
+	return time.Unix(exp, 0), nil
+}
+
 // respondImageError maps image retrieval errors to HTTP responses.
 func (s *Handlers) respondImageError(
 	w http.ResponseWriter, req *imgcache.ImageRequest, err error,
@@ -155,9 +223,71 @@ func (s *Handlers) respondImageError(
 		return
 	}
 
+	if errors.Is(err, httpfetcher.ErrTooManyConnections) ||
+		errors.Is(err, imageprocessor.ErrTooManyImages) {
+		s.respondError(w, "server busy, try again later",
+			http.StatusServiceUnavailable)
+
+		return
+	}
+
 	s.respondError(w, "internal error", http.StatusInternalServerError)
 }
 
+// cacheControl returns the Cache-Control header for an image served through a
+// URL that expires at expires, or never when expires is the zero time. A cache
+// may keep the image for a year, but not past the URL's expiry, after which
+// pixa refuses the URL. The seconds left are rounded down and never negative.
+// immutable only stops revalidation while the image is fresh, so it also ends
+// at the expiry.
+func cacheControl(expires time.Time) string {
+	const oneYear = 365 * 24 * time.Hour
+
+	maxAge := oneYear
+
+	if !expires.IsZero() {
+		maxAge = min(maxAge, max(time.Until(expires), 0))
+	}
+
+	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(
@@ -173,20 +303,11 @@ func (s *Handlers) writeImageResponse(
 	}
 
 	// Cache control headers
-	w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+	w.Header().Set("Cache-Control", cacheControl(req.Expires))
 	w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
-	if resp.ETag != "" {
+	if notModified(w, r, resp.ETag) {
-		w.Header().Set("ETag", resp.ETag)
+		return
-
-		// 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
-			}
-		}
 	}
 
 	// Handle HEAD request - return headers only
@@ -209,6 +330,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

@@ -0,0 +1,206 @@
+package handlers
+
+import (
+	"image/color"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// photoPath is the path of the JPEG that newSignedHostServer serves.
+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. 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{
+		StateDir:    t.TempDir(),
+		CacheTTL:    time.Hour,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("imgcache.NewCache() error = %v", err)
+	}
+
+	jpegData := generateTestJPEG(t, 100, 100, color.RGBA{255, 0, 0, 255})
+
+	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
+		Cache: cache,
+		Fetcher: newMockFetcher(fstest.MapFS{
+			signedHost + photoPath: &fstest.MapFile{Data: jpegData},
+		}),
+		SigningKey: testSigningKey,
+		Logger:     log,
+	})
+	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:    log,
+		imgSvc: svc,
+		encGen: encGen,
+	}
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", h.HandleImage())
+	r.Get("/v1/e/{token}/*", h.HandleImageEnc())
+
+	return h, r
+}
+
+// getMaxAge sends a GET for target to srv, requires a 200, and returns the
+// max-age of the response's Cache-Control header, which must read
+// "public, max-age=<seconds>, immutable".
+func getMaxAge(t *testing.T, srv http.Handler, target string) int {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, target, nil)
+	rec := httptest.NewRecorder()
+
+	srv.ServeHTTP(rec, req)
+
+	header := rec.Header().Get("Cache-Control")
+	t.Logf("GET %s: %d, Cache-Control: %s", target, rec.Code, header)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	value, hasPrefix := strings.CutPrefix(header, "public, max-age=")
+	value, hasSuffix := strings.CutSuffix(value, ", immutable")
+
+	maxAge, err := strconv.Atoi(value)
+	if !hasPrefix || !hasSuffix || err != nil {
+		t.Fatalf("Cache-Control = %q, want public, max-age=<seconds>, immutable",
+			header)
+	}
+
+	return maxAge
+}
+
+// TestHandleImage_SignedURL_MaxAgeEndsAtExp verifies that an image served
+// through a signed URL expiring in 60 seconds may be cached for at most those
+// 60 seconds. The lower bound of 50 shows the max-age is the time left, not 0.
+func TestHandleImage_SignedURL_MaxAgeEndsAtExp(t *testing.T) {
+	t.Parallel()
+
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+
+	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)
+	}
+
+	maxAge := getMaxAge(t, srv, signedURL)
+	if maxAge < 50 || maxAge > 60 {
+		t.Errorf("max-age = %d, want 50 to 60", maxAge)
+	}
+}
+
+// TestHandleImage_AllowlistedHost_MaxAge verifies the max-age of an image from
+// an allowlisted host, which is served without checking sig or exp. A URL with
+// no exp may be cached for a year. A URL whose exp has passed is the one request
+// that reaches the header after its expiry, and must get 0, never less.
+func TestHandleImage_AllowlistedHost_MaxAge(t *testing.T) {
+	t.Parallel()
+
+	pastExp := strconv.FormatInt(time.Now().Add(-time.Hour).Unix(), 10)
+
+	tests := []struct {
+		name       string
+		query      string
+		wantMaxAge int
+	}{
+		{"no exp", "", 31536000},
+		{"exp already past", "?exp=" + pastExp, 0},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			r := chi.NewRouter()
+			r.Get("/v1/image/*", fix.handler.HandleImage())
+
+			maxAge := getMaxAge(t, r,
+				"/v1/image/"+fix.goodHost+"/images/photo.jpg/50x50.jpeg"+tt.query)
+			if maxAge != tt.wantMaxAge {
+				t.Errorf("max-age = %d, want %d", maxAge, tt.wantMaxAge)
+			}
+		})
+	}
+}
+
+// TestHandleImageEnc_MaxAge verifies that an image served through an encrypted
+// URL with a 60 second TTL may be cached for at most those 60 seconds, that one
+// with a two-year TTL may be cached for a year, and that one made without a
+// TTL, which never expires, may be cached for a year.
+func TestHandleImageEnc_MaxAge(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		expiresAt   int64
+		wantAtLeast int
+		wantAtMost  int
+	}{
+		{"60 second TTL", time.Now().Add(time.Minute).Unix(), 50, 60},
+		{"two-year TTL", time.Now().Add(2 * 365 * 24 * time.Hour).Unix(), 31536000, 31536000},
+		{"no TTL", 0, 31536000, 31536000},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(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,
+				Format:     imgcache.FormatJPEG,
+				ExpiresAt:  tt.expiresAt,
+			})
+			if err != nil {
+				t.Fatalf("Generate() error = %v", err)
+			}
+
+			maxAge := getMaxAge(t, srv, "/v1/e/"+token+"/img.jpg")
+			if maxAge < tt.wantAtLeast || maxAge > tt.wantAtMost {
+				t.Errorf("max-age = %d, want %d to %d",
+					maxAge, tt.wantAtLeast, tt.wantAtMost)
+			}
+		})
+	}
+}

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/image_signature_internal_test.go

@@ -0,0 +1,171 @@
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"sneak.berlin/go/pixa/internal/imgcache"
+	"sneak.berlin/go/pixa/internal/signature"
+)
+
+// signedHost is not on the allowlist setupTestHandler builds, so a request
+// for it needs a valid signature. setupTestHandler serves no image for it: a
+// request that passes the signature check gets 502 from the failed fetch, and
+// one that fails the check gets 401.
+const signedHost = "signed.example.com"
+
+// getImage sends a GET for target to the image route of fix and returns the
+// response status.
+func getImage(t *testing.T, fix *testFixtures, target string) int {
+	t.Helper()
+
+	r := chi.NewRouter()
+	r.Get("/v1/image/*", fix.handler.HandleImage())
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, target, nil)
+	rec := httptest.NewRecorder()
+
+	r.ServeHTTP(rec, req)
+	t.Logf("GET %s: %d", target, rec.Code)
+
+	return rec.Code
+}
+
+// TestHandleImage_SignatureCoversQualityAndFit signs a URL for quality 85
+// and fit cover, the values the route uses when a URL has no q or fit, and
+// sends that signature with each q and fit below.
+func TestHandleImage_SignatureCoversQualityAndFit(t *testing.T) {
+	t.Parallel()
+
+	expires := time.Now().Add(time.Hour)
+	signer := signature.New("test-signing-key-must-be-32-chars")
+	sig := signer.Sign(&signature.Request{
+		SourceHost: signedHost,
+		SourcePath: "/images/photo.jpg",
+		Width:      50,
+		Height:     50,
+		Format:     string(imgcache.FormatJPEG),
+		Quality:    85,
+		FitMode:    string(imgcache.FitCover),
+		Expires:    expires,
+	})
+	signedURL := fmt.Sprintf("/v1/image/%s/images/photo.jpg/50x50.jpeg?sig=%s&exp=%d",
+		signedHost, sig, expires.Unix())
+
+	tests := []struct {
+		name       string
+		query      string
+		wantStatus int
+	}{
+		{"no q or fit", "", http.StatusBadGateway},
+		{"q=85 and fit=cover", "&q=85&fit=cover", http.StatusBadGateway},
+		{"replayed with q=40", "&q=40", http.StatusUnauthorized},
+		{"replayed with fit=contain", "&fit=contain", http.StatusUnauthorized},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			status := getImage(t, setupTestHandler(t), signedURL+tt.query)
+			if status != tt.wantStatus {
+				t.Errorf("status = %d, want %d", status, tt.wantStatus)
+			}
+		})
+	}
+}
+
+// TestHandleImage_GeneratedSignedURLVerifies sends URLs built by the
+// service's signed-URL generator to the route.
+func TestHandleImage_GeneratedSignedURLVerifies(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		quality int
+		fitMode imgcache.FitMode
+	}{
+		{"quality 40 and fit contain", 40, imgcache.FitContain},
+		{"quality and fit unset", 0, ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imgcache.ImageRequest{
+				SourceHost: signedHost,
+				SourcePath: "/images/photo.jpg",
+				Size:       imgcache.Size{Width: 50, Height: 50},
+				Format:     imgcache.FormatJPEG,
+				Quality:    tt.quality,
+				FitMode:    tt.fitMode,
+			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
+
+			status := getImage(t, fix, signedURL)
+			if status != http.StatusBadGateway {
+				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
+			}
+		})
+	}
+}
+
+// TestHandleImage_InvalidExp_Returns400 sends a signed-host URL whose exp is
+// not a whole number, and one whose exp is empty. Each is refused with 400
+// naming exp and the value, not with the 401 a URL without exp still gets.
+func TestHandleImage_InvalidExp_Returns400(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		query      string
+		wantStatus int
+		wantError  string
+	}{
+		{"sig=x&exp=banana", http.StatusBadRequest,
+			`invalid exp: not a number, got "banana"`},
+		{"sig=x&exp=", http.StatusBadRequest, `invalid exp: not a number, got ""`},
+		{"sig=x", http.StatusUnauthorized, "unauthorized"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.query, func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			r := chi.NewRouter()
+			r.Get("/v1/image/*", fix.handler.HandleImage())
+
+			req := httptest.NewRequestWithContext(t.Context(), http.MethodGet,
+				"/v1/image/"+signedHost+"/images/photo.jpg/50x50.jpeg?"+tt.query, nil)
+			rec := httptest.NewRecorder()
+
+			r.ServeHTTP(rec, req)
+			t.Logf("GET %s: %d %s", req.URL, rec.Code, rec.Body)
+
+			var body struct {
+				Error string `json:"error"`
+			}
+
+			err := json.NewDecoder(rec.Body).Decode(&body)
+			if err != nil {
+				t.Fatalf("decoding response body: %v", err)
+			}
+
+			if rec.Code != tt.wantStatus || body.Error != tt.wantError {
+				t.Errorf("got %d %q, want %d %q",
+					rec.Code, body.Error, tt.wantStatus, tt.wantError)
+			}
+		})
+	}
+}

internal/handlers/imageenc.go

@@ -9,9 +9,11 @@ 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"
 	"sneak.berlin/go/pixa/internal/imgcache"
 )
 
@@ -20,36 +22,18 @@ 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
+		req, ok := s.parseImageEncRequest(w, r)
-		token := chi.URLParam(r, "token")
+		if !ok {
-		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()
-
 		// Log the request
 		s.log.Debug("encrypted image request",
 			"host", req.SourceHost,
@@ -76,10 +60,21 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 			w.Header().Set("Content-Length", strconv.FormatInt(resp.ContentLength, 10))
 		}
 
-		// Cache headers - encrypted URLs can be cached since they're immutable
+		// Cache headers: max-age ends at the URL's expiry
-		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+		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 {
@@ -91,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,
@@ -102,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 {
@@ -111,6 +157,10 @@ func (s *Handlers) handleImageError(w http.ResponseWriter, err error) {
 		s.respondError(w, "upstream error", http.StatusBadGateway)
 	case errors.Is(err, httpfetcher.ErrUpstreamTimeout):
 		s.respondError(w, "upstream timeout", http.StatusGatewayTimeout)
+	case errors.Is(err, httpfetcher.ErrTooManyConnections),
+		errors.Is(err, imageprocessor.ErrTooManyImages):
+		s.respondError(w, "server busy, try again later",
+			http.StatusServiceUnavailable)
 	default:
 		s.log.Error("image request failed", "error", err)
 		s.respondError(w, "internal error", http.StatusInternalServerError)

internal/handlers/imageenc_internal_test.go

@@ -0,0 +1,165 @@
+package handlers
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"sneak.berlin/go/pixa/internal/encurl"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// newEncTestServer builds a router serving the encrypted-URL route with a
+// generator seeded by the shared test signing key. The image service is left
+// nil: these tests exercise validation that rejects a token before any image
+// is fetched, so the handler must never reach the service.
+func newEncTestServer(t *testing.T) (*encurl.Generator, http.Handler) {
+	t.Helper()
+
+	encGen, err := encurl.NewGenerator(testSigningKey)
+	if err != nil {
+		t.Fatalf("encurl.NewGenerator() error = %v", err)
+	}
+
+	h := &Handlers{
+		log:    slog.New(slog.DiscardHandler),
+		encGen: encGen,
+	}
+
+	r := chi.NewRouter()
+	r.Get("/v1/e/{token}/*", h.HandleImageEnc())
+
+	return encGen, r
+}
+
+// getEncToken issues a GET for the given token and returns the recorder.
+func getEncToken(srv http.Handler, token string) *httptest.ResponseRecorder {
+	req := httptest.NewRequestWithContext(
+		context.Background(), http.MethodGet, "/v1/e/"+token+"/img.jpg", nil)
+	rec := httptest.NewRecorder()
+	srv.ServeHTTP(rec, req)
+
+	return rec
+}
+
+// TestHandleImageEnc_OverLimitDimension_Returns400 verifies that a decrypted
+// token requesting a dimension beyond MaxDimension is rejected with 400
+// instead of reaching the image processor and libvips.
+func TestHandleImageEnc_OverLimitDimension_Returns400(t *testing.T) {
+	t.Parallel()
+
+	encGen, srv := newEncTestServer(t)
+
+	token, err := encGen.Generate(&encurl.Payload{
+		SourceHost: "cdn.example.com",
+		SourcePath: "/photo.jpg",
+		Width:      100000,
+		Height:     100000,
+	})
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	rec := getEncToken(srv, token)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+}
+
+// TestHandleImageEnc_InvalidFitMode_Returns400 verifies that a decrypted token
+// carrying an unrecognized fit mode is rejected with 400 rather than surfacing
+// as a 500 from the image processor's default branch.
+func TestHandleImageEnc_InvalidFitMode_Returns400(t *testing.T) {
+	t.Parallel()
+
+	encGen, srv := newEncTestServer(t)
+
+	token, err := encGen.Generate(&encurl.Payload{
+		SourceHost: "cdn.example.com",
+		SourcePath: "/photo.jpg",
+		Width:      800,
+		Height:     600,
+		FitMode:    imgcache.FitMode("bogus"),
+	})
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	rec := getEncToken(srv, token)
+
+	if rec.Code != http.StatusBadRequest {
+		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/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/handlers/server_busy_internal_test.go

@@ -0,0 +1,49 @@
+package handlers
+
+import (
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/imageprocessor"
+	"sneak.berlin/go/pixa/internal/imgcache"
+)
+
+// TestServerBusyAnswers503 checks that both image routes answer 503 with
+// a clear error when the image service gives up waiting for a free upstream
+// connection or processing slot, wrapped as the service wraps them.
+func TestServerBusyAnswers503(t *testing.T) {
+	t.Parallel()
+
+	h := &Handlers{log: slog.New(slog.DiscardHandler)}
+	req := &imgcache.ImageRequest{SourceHost: "img.example.com", SourcePath: "/a.jpg"}
+
+	for _, err := range []error{
+		fmt.Errorf("upstream fetch failed: %w", httpfetcher.ErrTooManyConnections),
+		fmt.Errorf("image processing failed: %w", imageprocessor.ErrTooManyImages),
+	} {
+		plain := httptest.NewRecorder()
+		h.respondImageError(plain, req, err)
+
+		encrypted := httptest.NewRecorder()
+		h.handleImageError(encrypted, err)
+
+		for route, rec := range map[string]*httptest.ResponseRecorder{
+			"/v1/image/": plain, "/v1/e/": encrypted,
+		} {
+			if rec.Code != http.StatusServiceUnavailable {
+				t.Errorf("%s for %v: status = %d, want %d",
+					route, err, rec.Code, http.StatusServiceUnavailable)
+			}
+
+			if !strings.Contains(rec.Body.String(), "server busy, try again later") {
+				t.Errorf("%s for %v: body = %q, want the server busy error",
+					route, err, rec.Body.String())
+			}
+		}
+	}
+}

internal/httpfetcher/blocked_networks_internal_test.go

@@ -0,0 +1,111 @@
+package httpfetcher
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/netip"
+	"testing"
+)
+
+// TestIsPrivateIPBlocksSpecialRanges covers the internal and special-use
+// ranges added to the built-in blocklist, in IPv4, IPv6, and IPv4-mapped
+// forms, alongside public controls that must stay reachable.
+func TestIsPrivateIPBlocksSpecialRanges(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		ip   string
+		want bool
+	}{
+		{"cgnat-low", "100.64.0.1", true},
+		{"cgnat-high", "100.127.255.254", true},
+		{"ietf-protocol", "192.0.0.1", true},
+		{"benchmark-low", "198.18.0.1", true},
+		{"benchmark-high", "198.19.255.254", true},
+		{"nat64", "64:ff9b::1", true},
+		{"nat64-embeds-private", "64:ff9b::a00:1", true}, // maps 10.0.0.1
+		{"ipv4-mapped-private", "::ffff:10.0.0.1", true},
+		{"cloud-metadata", "169.254.169.254", true},
+		{"public-v4", "8.8.8.8", false},
+		{"test-net-1-public", testPublicHost, false}, // TEST-NET-1, stays public
+		{"public-v6", "2001:4860:4860::8888", false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			ip := net.ParseIP(tc.ip)
+			if ip == nil {
+				t.Fatalf("failed to parse IP %q", tc.ip)
+			}
+
+			got := isPrivateIP(ip)
+			if got != tc.want {
+				t.Errorf("isPrivateIP(%q) = %v, want %v", tc.ip, got, tc.want)
+			}
+		})
+	}
+}
+
+// transportOf returns the *http.Transport backing a fetcher, so a test can
+// exercise the SSRF-safe dialer New installed with the operator blocklist.
+func transportOf(t *testing.T, f *HTTPFetcher) *http.Transport {
+	t.Helper()
+
+	transport, ok := f.client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("transport is %T, want *http.Transport", f.client.Transport)
+	}
+
+	return transport
+}
+
+// TestDialerEnforcesBlockedNetworks proves an operator-supplied
+// blocked_networks entry is enforced by the dialer, in addition to the
+// built-in ranges, while an address outside both stays dialable.
+func TestDialerEnforcesBlockedNetworks(t *testing.T) {
+	t.Parallel()
+
+	cfg := DefaultConfig()
+	// TEST-NET-2 (198.51.100.0/24) is public to the built-in check, so
+	// blocking it can only come from the operator-supplied list.
+	cfg.BlockedNetworks = []netip.Prefix{netip.MustParsePrefix("198.51.100.0/24")}
+
+	transport := transportOf(t, New(cfg))
+
+	blocked := []string{
+		"198.51.100.5:80", // operator-supplied range
+		"10.0.0.5:80",     // built-in RFC 1918, still enforced
+		"100.64.0.1:80",   // built-in CGNAT range
+	}
+
+	for _, addr := range blocked {
+		t.Run("blocked/"+addr, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := transport.DialContext(context.Background(), "tcp", addr)
+			if !errors.Is(err, ErrSSRFBlocked) {
+				t.Errorf("DialContext(%q) = %v, want ErrSSRFBlocked", addr, err)
+			}
+		})
+	}
+
+	t.Run("public-not-blocked", func(t *testing.T) {
+		t.Parallel()
+
+		// A cancelled context makes the dial fail without touching the
+		// network; the point is only that a public literal outside every
+		// blocked range is not SSRF-blocked.
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+
+		_, err := transport.DialContext(ctx, "tcp", testPublicHost+":80")
+		if errors.Is(err, ErrSSRFBlocked) {
+			t.Errorf("public target SSRF-blocked with operator list set: %v", err)
+		}
+	})
+}

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

@@ -0,0 +1,437 @@
+package httpfetcher
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"slices"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// testPublicHost is a TEST-NET-1 (RFC 5737) literal. isPrivateIP treats it as
+// public, so validateURL and the redirect check accept it with no DNS lookup,
+// while the recording dialer routes it to the local httptest server. The
+// address is reserved for documentation and is never routed on the network.
+const testPublicHost = "192.0.2.10"
+
+// imagePayload is the body served by the fake upstream's image route.
+const imagePayload = "fake-jpeg-bytes"
+
+// errUnexpectedDial reports a dial to any host other than testPublicHost, which
+// would mean SSRF protection let a forbidden target reach the transport.
+var errUnexpectedDial = errors.New("unexpected dial target")
+
+// upstreamURL builds a fetch URL on the fake public host for the given path.
+func upstreamURL(path string) string {
+	return "http://" + testPublicHost + path
+}
+
+// recordingDialer records every address the transport asks it to dial and
+// routes connections for testPublicHost to a real local server, so the SSRF
+// checks run against a public-looking host while bytes go to httptest.
+type recordingDialer struct {
+	target string
+
+	mu     sync.Mutex
+	dialed []string
+}
+
+func (d *recordingDialer) dialContext(
+	ctx context.Context,
+	network, addr string,
+) (net.Conn, error) {
+	d.mu.Lock()
+	d.dialed = append(d.dialed, addr)
+	d.mu.Unlock()
+
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	if host != testPublicHost {
+		return nil, fmt.Errorf("%w: %s", errUnexpectedDial, addr)
+	}
+
+	var dialer net.Dialer
+
+	return dialer.DialContext(ctx, network, d.target)
+}
+
+// dialedAddrs returns a copy of the addresses the dialer was asked to reach.
+func (d *recordingDialer) dialedAddrs() []string {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	return slices.Clone(d.dialed)
+}
+
+// startUpstream launches a fake upstream with the routes the fetch tests
+// exercise and stops it when the test finishes.
+func startUpstream(t *testing.T) *httptest.Server {
+	t.Helper()
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/image", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", contentTypeJPEG)
+		_, _ = io.WriteString(w, imagePayload)
+	})
+	mux.HandleFunc("/status/500", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	})
+	mux.HandleFunc("/html", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		_, _ = io.WriteString(w, "<html></html>")
+	})
+	mux.HandleFunc("/redirect/private", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "http://169.254.169.254/latest/meta-data/", http.StatusFound)
+	})
+	mux.HandleFunc("/redirect/public", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/image", http.StatusFound)
+	})
+	mux.HandleFunc("/redirect/chain", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/redirect/hop", http.StatusFound)
+	})
+	mux.HandleFunc("/redirect/hop", func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, "/image", http.StatusFound)
+	})
+
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+
+	return srv
+}
+
+// newServerFetcher builds a fetcher whose transport routes testPublicHost to
+// srv, leaving the real SSRF validation and redirect checks in place.
+func newServerFetcher(
+	t *testing.T,
+	srv *httptest.Server,
+	cfg *Config,
+) (*HTTPFetcher, *recordingDialer) {
+	t.Helper()
+
+	if cfg == nil {
+		cfg = DefaultConfig()
+	}
+
+	cfg.AllowHTTP = true
+
+	f := New(cfg)
+
+	transport, ok := f.client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("transport is %T, want *http.Transport", f.client.Transport)
+	}
+
+	dialer := &recordingDialer{target: srv.Listener.Addr().String()}
+	transport.DialContext = dialer.dialContext
+
+	return f, dialer
+}
+
+// testContext returns a context cancelled when the test ends, bounding any
+// fetch that would otherwise block on a leaked semaphore slot.
+func testContext(t *testing.T) context.Context {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	t.Cleanup(cancel)
+
+	return ctx
+}
+
+// fetchImage fetches path from the fake upstream and fails on error.
+func fetchImage(t *testing.T, f *HTTPFetcher, path string) *FetchResult {
+	t.Helper()
+
+	res, err := f.Fetch(testContext(t), upstreamURL(path))
+	if err != nil {
+		t.Fatalf("Fetch(%s) error = %v", path, err)
+	}
+
+	return res
+}
+
+// fetchExpectError fetches path and fails unless Fetch returns an error.
+func fetchExpectError(t *testing.T, f *HTTPFetcher, path string) error {
+	t.Helper()
+
+	res, err := f.Fetch(testContext(t), upstreamURL(path))
+	if err == nil {
+		_ = res.Content.Close()
+
+		t.Fatalf("Fetch(%s) = nil error, want an error", path)
+	}
+
+	return err
+}
+
+// fetchBody fetches path and returns the fully read, closed response body.
+func fetchBody(t *testing.T, f *HTTPFetcher, path string) string {
+	t.Helper()
+
+	res := fetchImage(t, f, path)
+	defer func() { _ = res.Content.Close() }()
+
+	data, err := io.ReadAll(res.Content)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+
+	return string(data)
+}
+
+// semLen reports how many per-host semaphore slots are currently held.
+func semLen(f *HTTPFetcher, host string) int {
+	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) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, dialer := newServerFetcher(t, srv, nil)
+
+	_, err := f.Fetch(testContext(t), upstreamURL("/redirect/private"))
+	if !errors.Is(err, ErrSSRFBlocked) {
+		t.Fatalf("Fetch() error = %v, want ErrSSRFBlocked", err)
+	}
+
+	for _, addr := range dialer.dialedAddrs() {
+		if strings.Contains(addr, "169.254.169.254") {
+			t.Errorf("dialer connected to the private redirect target: %s", addr)
+		}
+	}
+}
+
+func TestFetchRedirectToPublicSucceeds(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, _ := newServerFetcher(t, srv, nil)
+
+	if body := fetchBody(t, f, "/redirect/public"); body != imagePayload {
+		t.Errorf("body = %q, want %q", body, imagePayload)
+	}
+}
+
+func TestFetchRedirectChainSucceeds(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, _ := newServerFetcher(t, srv, nil)
+
+	if body := fetchBody(t, f, "/redirect/chain"); body != imagePayload {
+		t.Errorf("body = %q, want %q", body, imagePayload)
+	}
+}
+
+func TestFetchRejectsNon2xx(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, _ := newServerFetcher(t, srv, nil)
+
+	err := fetchExpectError(t, f, "/status/500")
+	if !errors.Is(err, ErrUpstreamError) {
+		t.Fatalf("Fetch() error = %v, want ErrUpstreamError", err)
+	}
+}
+
+func TestFetchRejectsDisallowedContentType(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+	f, _ := newServerFetcher(t, srv, nil)
+
+	err := fetchExpectError(t, f, "/html")
+	if !errors.Is(err, ErrInvalidContentType) {
+		t.Fatalf("Fetch() error = %v, want ErrInvalidContentType", err)
+	}
+}
+
+func TestFetchMaxResponseSizeEnforced(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxResponseSize = 8
+
+	f, _ := newServerFetcher(t, srv, cfg)
+
+	res := fetchImage(t, f, "/image")
+	defer func() { _ = res.Content.Close() }()
+
+	data, err := io.ReadAll(res.Content)
+	if !errors.Is(err, ErrResponseTooLarge) {
+		t.Fatalf("read error = %v, want ErrResponseTooLarge", err)
+	}
+
+	if int64(len(data)) > cfg.MaxResponseSize {
+		t.Errorf("read %d bytes, exceeds limit %d", len(data), cfg.MaxResponseSize)
+	}
+}
+
+func TestFetchSemaphoreReleasedOnError(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxConnectionsPerHost = 1
+
+	f, _ := newServerFetcher(t, srv, cfg)
+
+	err := fetchExpectError(t, f, "/status/500")
+	if !errors.Is(err, ErrUpstreamError) {
+		t.Fatalf("Fetch() error = %v, want ErrUpstreamError", err)
+	}
+
+	if held := semLen(f, testPublicHost); held != 0 {
+		t.Fatalf("semaphore slot leaked after error: %d held", held)
+	}
+
+	// One slot per host: this fetch proceeds only if the slot was released.
+	res := fetchImage(t, f, "/image")
+	_ = res.Content.Close()
+}
+
+// assertSlotReleasedByClose fetches an image over a one-slot host, hands the
+// open result to consume, and asserts the slot is held before and freed after,
+// then that a follow-up fetch can still acquire it.
+func assertSlotReleasedByClose(
+	t *testing.T,
+	consume func(*testing.T, *FetchResult),
+) {
+	t.Helper()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxConnectionsPerHost = 1
+
+	f, _ := newServerFetcher(t, srv, cfg)
+
+	res := fetchImage(t, f, "/image")
+	if held := semLen(f, testPublicHost); held != 1 {
+		t.Fatalf("slot not held while body is open: %d held", held)
+	}
+
+	consume(t, res)
+
+	if held := semLen(f, testPublicHost); held != 0 {
+		t.Fatalf("slot not released after close: %d held", held)
+	}
+
+	next := fetchImage(t, f, "/image")
+	_ = next.Content.Close()
+}
+
+func TestFetchSemaphoreReleasedOnBodyClose(t *testing.T) {
+	t.Parallel()
+
+	assertSlotReleasedByClose(t, func(t *testing.T, res *FetchResult) {
+		t.Helper()
+
+		_, err := io.ReadAll(res.Content)
+		if err != nil {
+			t.Fatalf("read body: %v", err)
+		}
+
+		err = res.Content.Close()
+		if err != nil {
+			t.Fatalf("close body: %v", err)
+		}
+	})
+}
+
+func TestFetchSemaphoreReleasedOnPartialReadClose(t *testing.T) {
+	t.Parallel()
+
+	assertSlotReleasedByClose(t, func(t *testing.T, res *FetchResult) {
+		t.Helper()
+
+		buf := make([]byte, 1)
+
+		_, err := res.Content.Read(buf)
+		if err != nil {
+			t.Fatalf("partial read: %v", err)
+		}
+
+		err = res.Content.Close()
+		if err != nil {
+			t.Fatalf("close body: %v", err)
+		}
+	})
+}
+
+// The dial-time re-resolution in ssrfSafeDialer is what closes the DNS
+// rebinding window: even if validateURL saw a public answer earlier, the
+// dialer independently re-checks the address it is about to connect to. A full
+// rebinding simulation (a resolver returning public, then private) would mean
+// replacing the global net.DefaultResolver with a fake DNS server, which is
+// heavyweight and unsafe to mutate under parallel -race tests. The property is
+// proven directly here instead: the dialer rejects a private target outright,
+// which is exactly the check that fires when a validated host later resolves
+// to a private address.
+func TestSSRFSafeDialerBlocksPrivateTarget(t *testing.T) {
+	t.Parallel()
+
+	for _, addr := range []string{
+		"169.254.169.254:80", // link-local (cloud metadata)
+		"127.0.0.1:80",       // loopback
+		"10.0.0.5:80",        // RFC 1918 private
+	} {
+		t.Run(addr, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := ssrfSafeDialer(context.Background(), "tcp", addr)
+			if !errors.Is(err, ErrSSRFBlocked) {
+				t.Errorf("ssrfSafeDialer(%q) = %v, want ErrSSRFBlocked", addr, err)
+			}
+		})
+	}
+}
+
+func TestSSRFSafeDialerAllowsPublicTarget(t *testing.T) {
+	t.Parallel()
+
+	// A cancelled context makes the dial fail immediately without touching the
+	// network; the point is only that a public literal is not SSRF-blocked.
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err := ssrfSafeDialer(ctx, "tcp", testPublicHost+":80")
+	if err == nil {
+		t.Fatal("expected a dial error for an unreachable public target")
+	}
+
+	if errors.Is(err, ErrSSRFBlocked) {
+		t.Errorf("public target was SSRF-blocked: %v", err)
+	}
+}

internal/httpfetcher/httpfetcher.go

@@ -1,5 +1,6 @@
 // Package httpfetcher fetches content from upstream HTTP origins with SSRF
-// protection, per-host connection limits, and content-type validation.
+// protection, connection limits per host and for all hosts together, and
+// content-type validation.
 package httpfetcher
 
 import (
@@ -11,11 +12,14 @@ import (
 	"net"
 	"net/http"
 	"net/http/httptrace"
+	"net/netip"
 	neturl "net/url"
 	"slices"
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/go-chi/chi/v5/middleware"
 )
 
 // Fetcher configuration constants.
@@ -27,8 +31,13 @@ const (
 	DefaultIdleConnTimeout       = 90 * time.Second
 	DefaultMaxRedirects          = 10
 	DefaultMaxConnectionsPerHost = 20
+	DefaultMaxConnections        = 64
 )
 
+// ConnectionWaitTimeout is how long Fetch waits for a free connection when
+// MaxConnections fetches are already in progress.
+const ConnectionWaitTimeout = 10 * time.Second
+
 // MIME content types.
 const (
 	contentTypeJPEG        = "image/jpeg"
@@ -46,6 +55,20 @@ const (
 	localhostIPv6 = "::1"
 )
 
+// builtinBlockedPrefixes are internal or special-use ranges that Go's
+// net.IP predicates (IsPrivate, IsLinkLocalUnicast, and the like) do not
+// already cover. They are always blocked, in addition to any
+// operator-supplied networks. IPv4-mapped IPv6 addresses are unmapped
+// before matching, so these IPv4 ranges are caught in both forms.
+//
+//nolint:gochecknoglobals // immutable built-in blocklist
+var builtinBlockedPrefixes = []netip.Prefix{
+	netip.MustParsePrefix("100.64.0.0/10"), // RFC 6598 CGNAT / carrier-grade NAT
+	netip.MustParsePrefix("192.0.0.0/24"),  // RFC 6890 IETF protocol assignments
+	netip.MustParsePrefix("198.18.0.0/15"), // RFC 2544 benchmarking range
+	netip.MustParsePrefix("64:ff9b::/96"),  // RFC 6052 NAT64 (maps onto IPv4)
+}
+
 // Fetcher errors.
 var (
 	ErrSSRFBlocked        = errors.New("request blocked: private or internal IP")
@@ -55,6 +78,7 @@ var (
 	ErrInvalidContentType = errors.New("invalid or unsupported content type")
 	ErrUpstreamError      = errors.New("upstream server error")
 	ErrUpstreamTimeout    = errors.New("upstream request timeout")
+	ErrTooManyConnections = errors.New("too many concurrent upstream connections")
 )
 
 // Internal fetcher errors.
@@ -107,6 +131,17 @@ type Config struct {
 	AllowHTTP bool
 	// MaxConnectionsPerHost limits concurrent connections to each upstream host.
 	MaxConnectionsPerHost int
+	// MaxConnections limits concurrent connections to all upstream hosts
+	// together.
+	MaxConnections int
+	// 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.
@@ -125,15 +160,33 @@ func DefaultConfig() *Config {
 		},
 		AllowHTTP:             false,
 		MaxConnectionsPerHost: DefaultMaxConnectionsPerHost,
+		MaxConnections:        DefaultMaxConnections,
 	}
 }
 
-// HTTPFetcher implements Fetcher with SSRF protection and per-host connection limits.
+// HTTPFetcher implements Fetcher with SSRF protection and connection limits
+// per host and for all hosts together.
 type HTTPFetcher struct {
-	client    *http.Client
+	client *http.Client
-	config    *Config
+	config *Config
-	hostSems  map[string]chan struct{} // per-host semaphores
+	// hostSems holds the semaphore of each host with a fetch holding or
-	hostSemMu sync.Mutex               // protects hostSems map
+	// 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{}
+	// connectionWaitTimeout is ConnectionWaitTimeout; tests shorten it.
+	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.
@@ -142,9 +195,19 @@ func New(config *Config) *HTTPFetcher {
 		config = DefaultConfig()
 	}
 
-	// Create transport with SSRF-safe dialer
+	// 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:         ssrfSafeDialer,
+		DialContext:         dialContext,
 		TLSHandshakeTimeout: DefaultTLSTimeout,
 		MaxIdleConns:        DefaultMaxIdleConns,
 		IdleConnTimeout:     DefaultIdleConnTimeout,
@@ -170,13 +233,18 @@ func New(config *Config) *HTTPFetcher {
 	}
 
 	return &HTTPFetcher{
-		client:   client,
+		client:                client,
-		config:   config,
+		config:                config,
-		hostSems: make(map[string]chan struct{}),
+		hostSems:              make(map[string]*hostSemaphore),
+		allHostsSemaphore:     make(chan struct{}, config.MaxConnections),
+		connectionWaitTimeout: ConnectionWaitTimeout,
 	}
 }
 
-// Fetch retrieves content from the given URL with SSRF protection.
+// Fetch retrieves content from the given URL with SSRF protection. When
+// MaxConnections fetches are already in progress, it waits up to
+// ConnectionWaitTimeout for one to finish, then fails with
+// ErrTooManyConnections.
 func (f *HTTPFetcher) Fetch(ctx context.Context, url string) (*FetchResult, error) {
 	// Validate URL before making request
 	err := validateURL(ctx, url, f.config.AllowHTTP)
@@ -184,24 +252,17 @@ func (f *HTTPFetcher) Fetch(ctx context.Context, url string) (*FetchResult, erro
 		return nil, err
 	}
 
-	// Extract host for rate limiting
+	release, err := f.acquireConnection(ctx, extractHost(url))
-	host := extractHost(url)
+	if err != nil {
-
+		return nil, err
-	// Acquire semaphore slot for this host
-	sem := f.getHostSemaphore(host)
-	select {
-	case sem <- struct{}{}:
-		// Acquired slot
-	case <-ctx.Done():
-		return nil, ctx.Err()
 	}
 
-	// If we fail before returning a result, release the slot
+	// If we fail before returning a result, release the connection
 	success := false
 
 	defer func() {
 		if !success {
-			<-sem
+			release()
 		}
 	}()
 
@@ -219,6 +280,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
 
@@ -245,38 +313,98 @@ func (f *HTTPFetcher) Fetch(ctx context.Context, url string) (*FetchResult, erro
 		return nil, fmt.Errorf("upstream request failed: %w", err)
 	}
 
-	result, err := f.buildResult(resp, remoteAddr, fetchDuration, sem)
+	result, err := f.buildResult(resp, remoteAddr, fetchDuration, release)
 	if err != nil {
 		return nil, err
 	}
 
-	// Mark success so defer doesn't release the semaphore
+	// Mark success so defer doesn't release the connection; closing the
+	// result's Content does
 	success = true
 
 	return result, nil
 }
 
-// getHostSemaphore returns the semaphore for a host, creating it if necessary.
+// acquireConnection takes a slot for host, then one of the slots shared by
+// all hosts, and returns the func that gives both back. The host's slot
+// comes first, so fetches queued for one busy host hold no shared slot.
+// Only the wait for a shared slot is bounded: after connectionWaitTimeout
+// it fails with ErrTooManyConnections.
+func (f *HTTPFetcher) acquireConnection(
+	ctx context.Context, host string,
+) (func(), error) {
+	hostSem := f.getHostSemaphore(host)
+
+	select {
+	case hostSem <- struct{}{}:
+	case <-ctx.Done():
+		f.putHostSemaphore(host)
+
+		return nil, ctx.Err()
+	}
+
+	select {
+	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, 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
-// whose Content releases the host semaphore slot when closed.
+// whose Content calls release when closed.
 func (f *HTTPFetcher) buildResult(
 	resp *http.Response,
 	remoteAddr string,
 	fetchDuration time.Duration,
-	sem chan struct{},
+	release func(),
 ) (*FetchResult, error) {
 	// Extract HTTP version (strip "HTTP/" prefix)
 	httpVersion := strings.TrimPrefix(resp.Proto, "HTTP/")
@@ -311,7 +439,7 @@ func (f *HTTPFetcher) buildResult(
 	}
 
 	return &FetchResult{
-		Content:         &semaphoreReleasingReadCloser{limitedBody, resp.Body, sem},
+		Content:         &semaphoreReleasingReadCloser{limitedBody, resp.Body, release},
 		ContentLength:   resp.ContentLength,
 		ContentType:     contentType,
 		Headers:         resp.Header,
@@ -451,11 +579,53 @@ func isPrivateIP(ip net.IP) bool {
 		}
 	}
 
-	return false
+	// Special-use ranges the net.IP predicates above do not cover.
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		return true
+	}
+
+	addr = addr.Unmap()
+
+	return slices.ContainsFunc(builtinBlockedPrefixes, func(prefix netip.Prefix) bool {
+		return prefix.Contains(addr)
+	})
 }
 
-// ssrfSafeDialer is a custom dialer that validates IP addresses before connecting.
+// isBlockedIP reports whether ip is refused, either by the built-in
+// internal-range check or by one of the operator-supplied prefixes.
+func isBlockedIP(ip net.IP, blocked []netip.Prefix) bool {
+	if isPrivateIP(ip) {
+		return true
+	}
+
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		return true
+	}
+
+	addr = addr.Unmap()
+
+	return slices.ContainsFunc(blocked, func(prefix netip.Prefix) bool {
+		return prefix.Contains(addr)
+	})
+}
+
+// ssrfSafeDialer validates IP addresses against the built-in blocked ranges
+// before connecting. New wraps dialSSRFSafe with the operator-supplied
+// blocklist; this entry point enforces the built-in ranges alone.
 func ssrfSafeDialer(ctx context.Context, network, addr string) (net.Conn, error) {
+	return dialSSRFSafe(ctx, network, addr, nil)
+}
+
+// dialSSRFSafe re-resolves addr and refuses to connect to any built-in
+// internal range or operator-supplied blocked prefix, closing the
+// DNS-rebinding window at connect time.
+func dialSSRFSafe(
+	ctx context.Context,
+	network, addr string,
+	blocked []netip.Prefix,
+) (net.Conn, error) {
 	host, port, err := net.SplitHostPort(addr)
 	if err != nil {
 		return nil, err
@@ -468,8 +638,10 @@ func ssrfSafeDialer(ctx context.Context, network, addr string) (net.Conn, error)
 	}
 
 	// Check all resolved IPs
-	if slices.ContainsFunc(ips, isPrivateIP) {
+	for _, ip := range ips {
-		return nil, ErrSSRFBlocked
+		if isBlockedIP(ip, blocked) {
+			return nil, ErrSSRFBlocked
+		}
 	}
 
 	// Connect using the first valid IP
@@ -508,17 +680,18 @@ func (r *limitedReader) Read(p []byte) (int, error) {
 	return n, err
 }
 
-// semaphoreReleasingReadCloser releases a semaphore slot when closed.
+// semaphoreReleasingReadCloser releases the fetch's connection slots when
+// closed.
 type semaphoreReleasingReadCloser struct {
 	*limitedReader
 
-	closer io.Closer
+	closer  io.Closer
-	sem    chan struct{}
+	release func()
 }
 
 func (r *semaphoreReleasingReadCloser) Close() error {
 	err := r.closer.Close()
-	<-r.sem // Release semaphore slot
+	r.release()
 
 	return err
 }

internal/httpfetcher/max_connections_internal_test.go

@@ -0,0 +1,258 @@
+package httpfetcher
+
+import (
+	"context"
+	"errors"
+	"net"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+)
+
+// imageURLOnPort is the fake upstream's image route on testPublicHost at
+// port. Each port is a different host to the per-host limit, while the test
+// dialer sends every port to the one test server.
+func imageURLOnPort(port int) string {
+	return "http://" + net.JoinHostPort(testPublicHost, strconv.Itoa(port)) +
+		"/image"
+}
+
+func TestDefaultConfigMaxConnections(t *testing.T) {
+	t.Parallel()
+
+	if got := DefaultConfig().MaxConnections; got != DefaultMaxConnections {
+		t.Errorf("MaxConnections = %d, want %d", got, DefaultMaxConnections)
+	}
+}
+
+// TestFetchLimitsConnectionsToAllHostsTogether checks that MaxConnections
+// counts the fetches to every host together, apart from the per-host
+// limit: with MaxConnections at 2 and two responses open from two hosts, a
+// fetch from a third host, which has nothing open, waits the whole wait
+// timeout and fails with ErrTooManyConnections. Closing one response lets
+// it through.
+func TestFetchLimitsConnectionsToAllHostsTogether(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxConnections = 2
+
+	f, _ := newServerFetcher(t, srv, cfg)
+	f.connectionWaitTimeout = 100 * time.Millisecond
+
+	first, err := f.Fetch(testContext(t), imageURLOnPort(81))
+	if err != nil {
+		t.Fatalf("first Fetch() error = %v", err)
+	}
+
+	second, err := f.Fetch(testContext(t), imageURLOnPort(82))
+	if err != nil {
+		t.Fatalf("second Fetch() error = %v", err)
+	}
+
+	defer func() { _ = second.Content.Close() }()
+
+	start := time.Now()
+
+	_, err = f.Fetch(testContext(t), imageURLOnPort(83))
+	if !errors.Is(err, ErrTooManyConnections) {
+		t.Fatalf("third Fetch() error = %v, want ErrTooManyConnections", err)
+	}
+
+	if waited := time.Since(start); waited < f.connectionWaitTimeout {
+		t.Errorf("third Fetch() failed after %v, before waiting %v",
+			waited, f.connectionWaitTimeout)
+	}
+
+	if held := semLen(f, testPublicHost+":83"); held != 0 {
+		t.Errorf("the refused fetch kept its host's slot: %d held", held)
+	}
+
+	err = first.Content.Close()
+	if err != nil {
+		t.Fatalf("close first body: %v", err)
+	}
+
+	third, err := f.Fetch(testContext(t), imageURLOnPort(83))
+	if err != nil {
+		t.Fatalf("Fetch() after a response was closed: error = %v", err)
+	}
+
+	_ = third.Content.Close()
+}
+
+// TestFetchFreesHostSlotWhenContextEndsWaitingForConnection checks that a
+// fetch whose request context ends while it waits for a connection shared
+// by all hosts gives its host's slot back. With MaxConnections at 1 and one
+// response open, a fetch from another host takes that host's slot and waits;
+// its context ends long before the 10 second wait timeout.
+func TestFetchFreesHostSlotWhenContextEndsWaitingForConnection(t *testing.T) {
+	t.Parallel()
+
+	srv := startUpstream(t)
+
+	cfg := DefaultConfig()
+	cfg.MaxConnections = 1
+
+	f, _ := newServerFetcher(t, srv, cfg)
+
+	first, err := f.Fetch(testContext(t), imageURLOnPort(81))
+	if err != nil {
+		t.Fatalf("first Fetch() error = %v", err)
+	}
+
+	defer func() { _ = first.Content.Close() }()
+
+	ctx, cancel := context.WithTimeout(t.Context(), 100*time.Millisecond)
+	defer cancel()
+
+	_, err = f.Fetch(ctx, imageURLOnPort(82))
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("second Fetch() error = %v, want context.DeadlineExceeded", err)
+	}
+
+	if held := semLen(f, testPublicHost+":82"); held != 0 {
+		t.Errorf("the fetch kept its host's slot after its context ended: "+
+			"%d held", held)
+	}
+}
+
+// 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.
+func TestFetchReleasesConnectionOnError(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name string
+		url  string
+		want error
+	}{
+		{"upstream answers 500", upstreamURL("/status/500"), ErrUpstreamError},
+		{"upstream sends HTML", upstreamURL("/html"), ErrInvalidContentType},
+		// 198.51.100.7 (TEST-NET-2) passes the SSRF checks, and the test
+		// dialer refuses every host but testPublicHost.
+		{"connecting fails", "http://198.51.100.7/image", errUnexpectedDial},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			srv := startUpstream(t)
+
+			cfg := DefaultConfig()
+			cfg.MaxConnections = 1
+
+			f, _ := newServerFetcher(t, srv, cfg)
+			f.connectionWaitTimeout = 100 * time.Millisecond
+
+			_, err := f.Fetch(testContext(t), tc.url)
+			if !errors.Is(err, tc.want) {
+				t.Fatalf("Fetch() error = %v, want %v", err, tc.want)
+			}
+
+			if held := len(f.allHostsSemaphore); held != 0 {
+				t.Fatalf("connection still held after the error: %d held", held)
+			}
+
+			res := fetchImage(t, f, "/image")
+			_ = res.Content.Close()
+		})
+	}
+}

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/imageprocessor.go

@@ -7,7 +7,9 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"runtime"
 	"sync"
+	"time"
 
 	"github.com/davidbyttow/govips/v2/vips"
 )
@@ -17,11 +19,21 @@ import (
 //nolint:gochecknoglobals // package-level sync.Once for one-time vips init
 var vipsOnce sync.Once
 
-// initVips initializes libvips with quiet logging.
+// initVips initializes libvips with quiet logging, one worker thread per
+// image and no operation cache. Process already works on one image per CPU
+// by default, so more threads per image would only compete for the CPUs.
+// Each request decodes different source bytes, so the operation cache
+// would rarely be hit and would hold memory outside MaxConcurrentProcessing;
+// repeated requests are served from pixa's disk cache instead.
 func initVips() {
 	vipsOnce.Do(func() {
 		vips.LoggingSettings(nil, vips.LogLevelError)
-		vips.Startup(nil)
+		vips.Startup(&vips.Config{
+			ConcurrencyLevel: 1,
+			MaxCacheSize:     0,
+			MaxCacheMem:      0,
+			MaxCacheFiles:    0,
+		})
 	})
 }
 
@@ -106,9 +118,23 @@ var ErrInputDataTooLarge = errors.New("input data exceeds maximum allowed size")
 // not supported.
 var ErrUnsupportedOutputFormat = errors.New("unsupported output format")
 
+// ErrTooManyImages is returned when MaxConcurrentProcessing images are being
+// processed and none finishes within ProcessingWaitTimeout.
+var ErrTooManyImages = errors.New("too many images being processed at once")
+
+// ProcessingWaitTimeout is how long Process waits for a free slot when
+// MaxConcurrentProcessing images are already being processed.
+const ProcessingWaitTimeout = 10 * time.Second
+
 // ImageProcessor implements image transformation using libvips via govips.
 type ImageProcessor struct {
 	maxInputBytes int64
+	// processingSemaphore has one slot per image that may be processed at
+	// once. Process holds a slot from before it reads its input until it
+	// returns, so the input, the decoded image and the output all count.
+	processingSemaphore chan struct{}
+	// processingWaitTimeout is ProcessingWaitTimeout; tests shorten it.
+	processingWaitTimeout time.Duration
 }
 
 // Params holds configuration for creating an ImageProcessor.
@@ -117,6 +143,9 @@ type Params struct {
 	// MaxInputBytes is the maximum allowed input size in bytes.
 	// If <= 0, DefaultMaxInputBytes is used.
 	MaxInputBytes int64
+	// MaxConcurrentProcessing is the most images processed at once.
+	// If <= 0, the number of CPUs Go uses (runtime.GOMAXPROCS(0)) is used.
+	MaxConcurrentProcessing int
 }
 
 // New creates a new image processor with the given parameters.
@@ -129,17 +158,34 @@ func New(params Params) *ImageProcessor {
 		maxInputBytes = DefaultMaxInputBytes
 	}
 
+	maxConcurrentProcessing := params.MaxConcurrentProcessing
+	if maxConcurrentProcessing <= 0 {
+		maxConcurrentProcessing = runtime.GOMAXPROCS(0)
+	}
+
 	return &ImageProcessor{
-		maxInputBytes: maxInputBytes,
+		maxInputBytes:         maxInputBytes,
+		processingSemaphore:   make(chan struct{}, maxConcurrentProcessing),
+		processingWaitTimeout: ProcessingWaitTimeout,
 	}
 }
 
-// Process transforms an image according to the request.
+// Process transforms an image according to the request. When
+// MaxConcurrentProcessing images are already being processed, it waits up
+// to ProcessingWaitTimeout for one to finish, then fails with
+// ErrTooManyImages.
 func (p *ImageProcessor) Process(
-	_ context.Context,
+	ctx context.Context,
 	input io.Reader,
 	req *Request,
 ) (*Result, error) {
+	release, err := p.acquireSlot(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	defer release()
+
 	// Read input with a size limit to prevent unbounded memory consumption.
 	// We read at most maxInputBytes+1 so we can detect if the input exceeds
 	// the limit without consuming additional memory.
@@ -161,6 +207,13 @@ func (p *ImageProcessor) Process(
 	}
 	defer img.Close()
 
+	// Turn the image upright now: encode strips the EXIF orientation tag,
+	// and sizes below must be worked out on the upright image.
+	err = img.AutoRotate()
+	if err != nil {
+		return nil, fmt.Errorf("failed to auto-rotate: %w", err)
+	}
+
 	// Get original dimensions
 	origWidth := img.Width()
 	origHeight := img.Height()
@@ -278,6 +331,54 @@ 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
+// one stops when ctx ends, as the rest of Process does not check ctx.
+func (p *ImageProcessor) acquireSlot(ctx context.Context) (func(), error) {
+	release := func() { <-p.processingSemaphore }
+
+	select {
+	case p.processingSemaphore <- struct{}{}:
+		return release, nil
+	default:
+	}
+
+	select {
+	case p.processingSemaphore <- struct{}{}:
+		return release, nil
+	case <-time.After(p.processingWaitTimeout):
+		return nil, ErrTooManyImages
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+}
+
 // detectFormat returns the format string from a vips image.
 func (p *ImageProcessor) detectFormat(img *vips.ImageRef) string {
 	format := img.Format()
@@ -404,6 +505,21 @@ func (p *ImageProcessor) encode(
 		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
+	// first use but read without a lock, so concurrent requests race on it.
+	if img.HasICCProfile() {
+		err := img.TransformICCProfileWithFallback("srgb", "srgb")
+		if err != nil {
+			return nil, fmt.Errorf("failed to convert to sRGB: %w", err)
+		}
+	}
+
+	// Drop EXIF, XMP, IPTC and the ICC profile. govips ignores this for
+	// GIF, which carries none of them.
+	params.StripMetadata = true
+
 	output, _, err := img.Export(&params)
 	if err != nil {
 		return nil, err

internal/imageprocessor/imageprocessor_internal_test.go

@@ -9,7 +9,9 @@ import (
 	"image/jpeg"
 	"image/png"
 	"io"
+	"math"
 	"os"
+	"slices"
 	"testing"
 
 	"github.com/davidbyttow/govips/v2/vips"
@@ -561,3 +563,152 @@ func TestImageProcessor_EncodeAVIF(t *testing.T) {
 
 	encodeAndCheck(t, FormatAVIF, 85, mimeAVIF)
 }
+
+// processAndDecode runs input through Process and decodes the output with
+// vips, so a test can inspect the image a client would receive.
+func processAndDecode(t *testing.T, input []byte, req *Request) *vips.ImageRef {
+	t.Helper()
+
+	result, err := New(Params{}).Process(
+		context.Background(), bytes.NewReader(input), req,
+	)
+	if err != nil {
+		t.Fatalf("Process() error = %v", err)
+	}
+
+	defer func() { _ = result.Content.Close() }()
+
+	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 decode output: %v", err)
+	}
+
+	t.Cleanup(output.Close)
+
+	return output
+}
+
+func TestImageProcessor_StripsEXIF(t *testing.T) {
+	t.Parallel()
+
+	// gps-exif.jpg carries GPS coordinates, a camera make, model and serial
+	// number, and a capture time.
+	input, err := os.ReadFile("testdata/gps-exif.jpg")
+	if err != nil {
+		t.Fatalf("failed to read test JPEG: %v", err)
+	}
+
+	fixture, err := vips.NewImageFromBuffer(input)
+	if err != nil {
+		t.Fatalf("failed to decode test JPEG: %v", err)
+	}
+
+	t.Cleanup(fixture.Close)
+
+	if !slices.Contains(fixture.GetFields(), "exif-ifd3-GPSLatitude") {
+		t.Fatal("testdata/gps-exif.jpg has no GPS latitude")
+	}
+
+	formats := []Format{
+		FormatJPEG, FormatPNG, FormatWebP, FormatAVIF, FormatGIF, FormatOriginal,
+	}
+
+	for _, format := range formats {
+		t.Run(string(format), func(t *testing.T) {
+			t.Parallel()
+
+			output := processAndDecode(t, input, &Request{Format: format})
+
+			if output.HasExif() {
+				t.Errorf("output has EXIF: %v", output.GetExif())
+			}
+		})
+	}
+}
+
+func TestImageProcessor_AppliesEXIFOrientation(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)
+	}
+
+	tests := []struct {
+		name  string
+		size  Size
+		wantW int
+		wantH int
+	}{
+		{name: "original size", size: Size{}, wantW: 8, wantH: 16},
+		{name: "width only", size: Size{Width: 4}, wantW: 4, wantH: 8},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			output := processAndDecode(t, input, &Request{
+				Size:   tt.size,
+				Format: FormatPNG,
+			})
+
+			if output.Width() != tt.wantW || output.Height() != tt.wantH {
+				t.Fatalf("output is %dx%d, want %dx%d",
+					output.Width(), output.Height(), tt.wantW, tt.wantH)
+			}
+
+			top, err := output.GetPoint(tt.wantW/2, 0)
+			if err != nil {
+				t.Fatalf("GetPoint() error = %v", err)
+			}
+
+			bottom, err := output.GetPoint(tt.wantW/2, tt.wantH-1)
+			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)
+			}
+		})
+	}
+}
+
+func TestImageProcessor_ConvertsWideGamutToSRGB(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: FormatPNG})
+
+	if output.HasICCProfile() {
+		t.Error("output has an ICC profile")
+	}
+
+	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)
+		}
+	}
+}

internal/imageprocessor/max_concurrent_processing_internal_test.go

@@ -0,0 +1,368 @@
+package imageprocessor
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"runtime"
+	"strings"
+	"sync"
+	"testing"
+	"testing/iotest"
+	"time"
+)
+
+// errTestReadFailed is the error the unreadable test input returns.
+var errTestReadFailed = errors.New("test input cannot be read")
+
+// readingCounter counts the Process calls reading their input at the same
+// time and remembers the most there ever were.
+type readingCounter struct {
+	mu      sync.Mutex
+	reading int
+	most    int
+}
+
+func (c *readingCounter) start() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.reading++
+	c.most = max(c.most, c.reading)
+}
+
+func (c *readingCounter) stop() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	c.reading--
+}
+
+func (c *readingCounter) mostReading() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	return c.most
+}
+
+// gatedReader is a Process input. Its first Read counts the call in,
+// reports it on entered and blocks until gate is closed; it counts the call
+// out when it returns io.EOF. Process reads its input only while it holds a
+// processing slot, so the count never goes above MaxConcurrentProcessing.
+type gatedReader struct {
+	data    *bytes.Reader
+	gate    <-chan struct{}
+	entered chan<- struct{}
+	counter *readingCounter
+	started bool
+}
+
+func (r *gatedReader) Read(p []byte) (int, error) {
+	if !r.started {
+		r.started = true
+		r.counter.start()
+
+		r.entered <- struct{}{}
+
+		<-r.gate
+	}
+
+	n, err := r.data.Read(p)
+	if errors.Is(err, io.EOF) {
+		r.counter.stop()
+	}
+
+	return n, err
+}
+
+// smallJPEGRequest asks for a 5x5 JPEG.
+func smallJPEGRequest() *Request {
+	return &Request{
+		Size:    Size{Width: 5, Height: 5},
+		Format:  FormatJPEG,
+		Quality: 85,
+		FitMode: FitCover,
+	}
+}
+
+// processInBackground runs Process on reader in a new goroutine and sends
+// its error on results.
+func processInBackground(
+	proc *ImageProcessor, reader *gatedReader, results chan<- error,
+) {
+	go func() {
+		result, err := proc.Process(context.Background(), reader, smallJPEGRequest())
+		if err == nil {
+			_ = result.Content.Close()
+		}
+
+		results <- err
+	}()
+}
+
+// waitForEntries fails the test unless count Process calls report on
+// entered within a few seconds.
+func waitForEntries(t *testing.T, entered <-chan struct{}, count int) {
+	t.Helper()
+
+	for range count {
+		select {
+		case <-entered:
+		case <-time.After(5 * time.Second):
+			t.Fatal("Process calls did not start reading their input")
+		}
+	}
+}
+
+func TestNewDefaultsMaxConcurrentProcessingToCPUs(t *testing.T) {
+	t.Parallel()
+
+	for _, limit := range []int{0, -1} {
+		proc := New(Params{MaxConcurrentProcessing: limit})
+		if got := cap(proc.processingSemaphore); got != runtime.GOMAXPROCS(0) {
+			t.Errorf("MaxConcurrentProcessing %d: %d slots, want %d, one per CPU",
+				limit, got, runtime.GOMAXPROCS(0))
+		}
+	}
+
+	proc := New(Params{MaxConcurrentProcessing: 3})
+	if got := cap(proc.processingSemaphore); got != 3 {
+		t.Errorf("MaxConcurrentProcessing 3: %d slots, want 3", got)
+	}
+}
+
+// TestProcessNeverExceedsMaxConcurrentProcessing starts more Process calls
+// than MaxConcurrentProcessing allows and holds the first ones inside
+// Process until the test lets them go. No more than the limit may be
+// working at once, and the calls held back must wait for a slot and then
+// succeed.
+func TestProcessNeverExceedsMaxConcurrentProcessing(t *testing.T) {
+	t.Parallel()
+
+	const (
+		limit = 2
+		calls = 6
+	)
+
+	proc := New(Params{MaxConcurrentProcessing: limit})
+	input := createTestJPEG(t, 50, 50)
+
+	counter := &readingCounter{}
+	gate := make(chan struct{})
+	entered := make(chan struct{}, calls)
+	results := make(chan error, calls)
+
+	openGate := sync.OnceFunc(func() { close(gate) })
+	t.Cleanup(openGate)
+
+	for range calls {
+		processInBackground(proc, &gatedReader{
+			data: bytes.NewReader(input), gate: gate, entered: entered,
+			counter: counter,
+		}, results)
+	}
+
+	waitForEntries(t, entered, limit)
+
+	// A call beyond the limit would start reading its input now.
+	select {
+	case <-entered:
+		t.Fatalf("a Process call started while %d were already working", limit)
+	case <-time.After(100 * time.Millisecond):
+	}
+
+	openGate()
+
+	for range calls {
+		err := <-results
+		if err != nil {
+			t.Errorf("Process() error = %v, want nil once a slot is free", err)
+		}
+	}
+
+	if most := counter.mostReading(); most > limit {
+		t.Errorf("%d Process calls worked at once, want at most %d", most, limit)
+	}
+}
+
+// TestProcessWaitsThenFailsWhenNoSlotFrees holds the only slot and checks
+// that another call waits the whole wait timeout, then fails with
+// ErrTooManyImages instead of processing anyway.
+func TestProcessWaitsThenFailsWhenNoSlotFrees(t *testing.T) {
+	t.Parallel()
+
+	proc := New(Params{MaxConcurrentProcessing: 1})
+	proc.processingWaitTimeout = 100 * time.Millisecond
+
+	input := createTestJPEG(t, 10, 10)
+
+	gate := make(chan struct{})
+	entered := make(chan struct{}, 1)
+	held := make(chan error, 1)
+
+	openGate := sync.OnceFunc(func() { close(gate) })
+	t.Cleanup(openGate)
+
+	processInBackground(proc, &gatedReader{
+		data: bytes.NewReader(input), gate: gate, entered: entered,
+		counter: &readingCounter{},
+	}, held)
+	waitForEntries(t, entered, 1)
+
+	start := time.Now()
+
+	_, err := proc.Process(context.Background(), bytes.NewReader(input),
+		smallJPEGRequest())
+	if !errors.Is(err, ErrTooManyImages) {
+		t.Fatalf("Process() error = %v, want ErrTooManyImages", err)
+	}
+
+	if waited := time.Since(start); waited < proc.processingWaitTimeout {
+		t.Errorf("Process() failed after %v, before waiting %v",
+			waited, proc.processingWaitTimeout)
+	}
+
+	openGate()
+
+	err = <-held
+	if err != nil {
+		t.Errorf("Process() holding the slot: error = %v, want nil", err)
+	}
+}
+
+// TestProcessReleasesSlotOnError checks that Process gives its slot back
+// when it fails, whether it fails early or late: with one slot, the slot
+// must be free after the failure and the next call must succeed.
+func TestProcessReleasesSlotOnError(t *testing.T) {
+	t.Parallel()
+
+	valid := createTestJPEG(t, 10, 10)
+
+	unsupported := smallJPEGRequest()
+	unsupported.Format = "bmp"
+
+	cases := []struct {
+		name  string
+		input io.Reader
+		req   *Request
+		// want is the error Process must return; nil means any error.
+		want error
+	}{
+		{
+			name:  "input cannot be read",
+			input: iotest.ErrReader(errTestReadFailed),
+			req:   smallJPEGRequest(),
+			want:  errTestReadFailed,
+		},
+		{
+			name:  "input over the byte limit",
+			input: bytes.NewReader(createTestJPEG(t, 800, 600)),
+			req:   smallJPEGRequest(),
+			want:  ErrInputDataTooLarge,
+		},
+		{
+			name:  "input not an image",
+			input: strings.NewReader("not an image"),
+			req:   smallJPEGRequest(),
+		},
+		{
+			name:  "output format not supported",
+			input: bytes.NewReader(valid),
+			req:   unsupported,
+			want:  ErrUnsupportedOutputFormat,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			proc := New(Params{MaxInputBytes: 4096, MaxConcurrentProcessing: 1})
+			proc.processingWaitTimeout = 100 * time.Millisecond
+
+			_, err := proc.Process(context.Background(), tc.input, tc.req)
+			if err == nil || (tc.want != nil && !errors.Is(err, tc.want)) {
+				t.Fatalf("Process() error = %v, want %v", err, tc.want)
+			}
+
+			if held := len(proc.processingSemaphore); held != 0 {
+				t.Fatalf("slot still held after the error: %d held", held)
+			}
+
+			result, err := proc.Process(context.Background(), bytes.NewReader(valid),
+				smallJPEGRequest())
+			if err != nil {
+				t.Fatalf("Process() after the error = %v, want nil", err)
+			}
+
+			_ = result.Content.Close()
+		})
+	}
+}
+
+// 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,9 +11,9 @@ import (
 	"io"
 	"log/slog"
 	"path/filepath"
-	"sync"
 	"time"
 
+	lru "github.com/hashicorp/golang-lru/v2"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 )
 
@@ -26,6 +26,10 @@ var (
 // HTTP status code for successful fetch.
 const httpStatusOK = 200
 
+// metaCacheSize is how many variants' content types metaCache holds. A
+// variant not among them is served as before, reading its .meta file.
+const metaCacheSize = 10000
+
 // CacheConfig holds cache configuration.
 type CacheConfig struct {
 	StateDir    string
@@ -33,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
+	// enforces. Zero means no limit is enforced (no eviction).
-	// config layer supplies the computed default when the operator
-	// omits cache_max_bytes.
 	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
@@ -49,12 +58,6 @@ type CacheConfig struct {
 	Logger *slog.Logger
 }
 
-// variantMeta stores content type for fast cache hits without reading .meta file.
-type variantMeta struct {
-	ContentType string
-	Size        int64
-}
-
 // Cache implements the caching layer for the image proxy.
 type Cache struct {
 	db          *sql.DB
@@ -70,15 +73,16 @@ 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
+	evictionCancel   context.CancelFunc
-	evictionStopOnce sync.Once
 
-	// In-memory cache of variant metadata (content type, size) to avoid
+	// metaCache holds the content types of the variants most recently
-	// reading .meta files
+	// stored or served, so a hit does not read the variant's .meta file.
-	metaCache map[VariantKey]variantMeta
+	// It never stands in for the variant file, which is always opened.
+	metaCache *lru.Cache[VariantKey, string]
 
 	// contentLocks serializes StoreSource and evictSourceBlob per
 	// content hash, closing the race window between an eviction's row
@@ -96,20 +100,32 @@ type Cache struct {
 
 // 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()
 	}
 
+	metaCache, err := lru.New[VariantKey, string](metaCacheSize)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create variant content type cache: %w", err)
+	}
+
 	c := &Cache{
 		db:               db,
 		config:           config,
 		log:              log,
 		disabled:         config.DisableDiskCache,
 		evictionPressure: make(chan struct{}, 1),
-		evictionStop:     make(chan struct{}),
 		evictionDone:     make(chan struct{}),
-		metaCache:        make(map[VariantKey]variantMeta),
+		metaCache:        metaCache,
 		contentLocks:     newContentLock(),
 	}
 
@@ -125,7 +141,7 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 	}
 
 	variants, err := NewVariantStorage(
-		filepath.Join(config.StateDir, "cache", "variants"),
+		filepath.Join(config.StateDir, "cache", "variants"), log,
 	)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create variant storage: %w", err)
@@ -142,6 +158,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
 }
 
@@ -177,13 +207,30 @@ func (c *Cache) Lookup(ctx context.Context, req *ImageRequest) (*LookupResult, e
 	}, nil
 }
 
-// GetVariant returns a reader, size, and content type for a cached variant.
+// GetVariant returns a reader, size, and content type for a cached
+// variant. The content type comes from metaCache, or else from the
+// variant's .meta file and is then kept in metaCache. A variant with
+// no .meta file is served as application/octet-stream, which is not
+// kept.
 func (c *Cache) GetVariant(cacheKey VariantKey) (io.ReadCloser, int64, string, error) {
 	if c.disabled {
 		return nil, 0, "", ErrNotFound
 	}
 
-	return c.variants.LoadWithMeta(cacheKey)
+	contentType, known := c.metaCache.Get(cacheKey)
+	if !known {
+		return c.loadVariantWithMeta(cacheKey)
+	}
+
+	reader, size, err := c.variants.LoadWithSize(cacheKey)
+	if err != nil {
+		// The file is gone, e.g. deleted outside pixa
+		c.metaCache.Remove(cacheKey)
+
+		return nil, 0, "", err
+	}
+
+	return reader, size, contentType, nil
 }
 
 // StoreSource stores fetched source content and metadata. On a
@@ -263,23 +310,7 @@ func (c *Cache) StoreSource(
 		return "", fmt.Errorf("failed to insert source metadata: %w", err)
 	}
 
-	// Store metadata JSON file
+	c.writeMetadataSidecar(req, pathHash, contentHash, result)
-	meta := &SourceMetadata{
-		Host:            req.SourceHost,
-		Path:            req.SourcePath,
-		Query:           req.SourceQuery,
-		ContentHash:     string(contentHash),
-		StatusCode:      result.StatusCode,
-		ContentType:     result.ContentType,
-		ContentLength:   result.ContentLength,
-		ResponseHeaders: result.Headers,
-		FetchedAt:       time.Now().UTC().Unix(),
-		FetchDurationMs: result.FetchDurationMs,
-		RemoteAddr:      result.RemoteAddr,
-	}
-
-	// A failure here is non-fatal; the metadata is in the database.
-	_ = c.srcMetadata.Store(req.SourceHost, pathHash, meta)
 
 	c.notifyWritePressure()
 
@@ -302,6 +333,8 @@ func (c *Cache) StoreVariant(
 		return err
 	}
 
+	c.metaCache.Add(cacheKey, contentType)
+
 	_, err = c.db.ExecContext(ctx, `
 		INSERT INTO variant_content (cache_key, size_bytes, content_type)
 		VALUES (?, ?, ?)
@@ -399,13 +432,16 @@ func (c *Cache) GetSourceMetadataID(
 	return id, nil
 }
 
-// GetSourceContent returns a reader for cached source content by its hash.
+// GetSourceContent returns a reader for cached source content by its hash,
-func (c *Cache) GetSourceContent(contentHash ContentHash) (io.ReadCloser, error) {
+// and the content's size in bytes.
+func (c *Cache) GetSourceContent(
+	contentHash ContentHash,
+) (io.ReadCloser, int64, error) {
 	if c.disabled {
-		return nil, ErrNotFound
+		return nil, 0, ErrNotFound
 	}
 
-	return c.srcContent.Load(contentHash)
+	return c.srcContent.LoadWithSize(contentHash)
 }
 
 // CleanExpired removes expired entries from the cache.
@@ -435,13 +471,22 @@ func (c *Cache) Stats(ctx context.Context) (*CacheStats, error) {
 		return nil, fmt.Errorf("failed to get cache stats: %w", err)
 	}
 
-	// Get actual item count and total size from content tables
+	// Count and size the cached source images and processed variants. A
-	_ = c.db.QueryRowContext(ctx,
+	// disabled cache holds none, whatever rows an earlier run left.
-		`SELECT COUNT(*) FROM request_cache`,
+	if !c.disabled {
-	).Scan(&stats.TotalItems)
+		err = c.db.QueryRowContext(ctx, `
-	_ = c.db.QueryRowContext(ctx,
+			SELECT (SELECT COUNT(*) FROM source_content)
-		`SELECT COALESCE(SUM(size_bytes), 0) FROM output_content`,
+			     + (SELECT COUNT(*) FROM variant_content)
-	).Scan(&stats.TotalSizeBytes)
+		`).Scan(&stats.TotalItems)
+		if err != nil {
+			c.log.Warn("failed to count cache items for stats", "error", err)
+		}
+
+		stats.TotalSizeBytes, err = c.UsageBytes(ctx)
+		if err != nil {
+			c.log.Warn("failed to sum cache size for stats", "error", err)
+		}
+	}
 
 	// Compute hit rate as a ratio
 	if stats.HitCount+stats.MissCount > 0 {
@@ -451,17 +496,20 @@ func (c *Cache) Stats(ctx context.Context) (*CacheStats, error) {
 	return &stats, nil
 }
 
-// IncrementStats increments cache statistics.
+// IncrementStats counts a cache hit or miss, and an upstream fetch that read
+// fetchBytes bytes, as IncrementUpstreamFetch does.
 func (c *Cache) IncrementStats(ctx context.Context, hit bool, fetchBytes int64) {
+	var err error
+
 	if hit {
-		_, _ = c.db.ExecContext(ctx, `
+		_, err = c.db.ExecContext(ctx, `
 			UPDATE cache_stats
 			SET hit_count = hit_count + 1,
 			    last_updated_at = CURRENT_TIMESTAMP
 			WHERE id = 1
 		`)
 	} else {
-		_, _ = c.db.ExecContext(ctx, `
+		_, err = c.db.ExecContext(ctx, `
 			UPDATE cache_stats
 			SET miss_count = miss_count + 1,
 			    last_updated_at = CURRENT_TIMESTAMP
@@ -469,14 +517,98 @@ func (c *Cache) IncrementStats(ctx context.Context, hit bool, fetchBytes int64)
 		`)
 	}
 
-	if fetchBytes > 0 {
+	if err != nil {
-		_, _ = c.db.ExecContext(ctx, `
+		c.log.Warn("failed to count cache hit or miss", "hit", hit, "error", err)
-			UPDATE cache_stats
+	}
-			SET upstream_fetch_count = upstream_fetch_count + 1,
+
-			    upstream_fetch_bytes = upstream_fetch_bytes + ?,
+	c.IncrementUpstreamFetch(ctx, fetchBytes)
-			    last_updated_at = CURRENT_TIMESTAMP
+}
-			WHERE id = 1
+
-		`, fetchBytes)
+// IncrementUpstreamFetch counts one upstream fetch that read fetchBytes bytes.
+// A fetch that read no bytes is not counted.
+func (c *Cache) IncrementUpstreamFetch(ctx context.Context, fetchBytes int64) {
+	if fetchBytes <= 0 {
+		return
+	}
+
+	_, err := c.db.ExecContext(ctx, `
+		UPDATE cache_stats
+		SET upstream_fetch_count = upstream_fetch_count + 1,
+		    upstream_fetch_bytes = upstream_fetch_bytes + ?,
+		    last_updated_at = CURRENT_TIMESTAMP
+		WHERE id = 1
+	`, fetchBytes)
+	if err != nil {
+		c.log.Warn("failed to count upstream fetch",
+			"fetch_bytes", fetchBytes, "error", err)
+	}
+}
+
+// IncrementTransformCount counts one image transcoded by the image processor.
+func (c *Cache) IncrementTransformCount(ctx context.Context) {
+	_, err := c.db.ExecContext(ctx, `
+		UPDATE cache_stats
+		SET transform_count = transform_count + 1,
+		    last_updated_at = CURRENT_TIMESTAMP
+		WHERE id = 1
+	`)
+	if err != nil {
+		c.log.Warn("failed to count transform", "error", err)
+	}
+}
+
+// loadVariantWithMeta is GetVariant for a variant metaCache does not
+// hold: it reads the content type from the variant's .meta file and
+// keeps it in metaCache, unless a StoreVariant has put one there
+// meanwhile, as the store's is newer. A read that finds no .meta file,
+// as one can between a store's writing of the variant file and of its
+// .meta file, serves application/octet-stream and keeps nothing, so
+// metaCache only ever holds a type read from a .meta file or passed to
+// StoreVariant.
+func (c *Cache) loadVariantWithMeta(
+	cacheKey VariantKey,
+) (io.ReadCloser, int64, string, error) {
+	reader, size, contentType, err := c.variants.LoadWithMeta(cacheKey)
+	if err != nil {
+		return nil, 0, "", err
+	}
+
+	if contentType == "" {
+		return reader, size, fallbackContentType, nil
+	}
+
+	c.metaCache.ContainsOrAdd(cacheKey, contentType)
+
+	return reader, size, contentType, nil
+}
+
+// writeMetadataSidecar writes the JSON metadata sidecar of a stored source.
+// A failure is logged and is otherwise non-fatal; the metadata is in the
+// database.
+func (c *Cache) writeMetadataSidecar(
+	req *ImageRequest,
+	pathHash PathHash,
+	contentHash ContentHash,
+	result *httpfetcher.FetchResult,
+) {
+	meta := &SourceMetadata{
+		Host:            req.SourceHost,
+		Path:            req.SourcePath,
+		Query:           req.SourceQuery,
+		ContentHash:     string(contentHash),
+		StatusCode:      result.StatusCode,
+		ContentType:     result.ContentType,
+		ContentLength:   result.ContentLength,
+		ResponseHeaders: result.Headers,
+		FetchedAt:       time.Now().UTC().Unix(),
+		FetchDurationMs: result.FetchDurationMs,
+		RemoteAddr:      result.RemoteAddr,
+	}
+
+	err := c.srcMetadata.Store(req.SourceHost, pathHash, meta)
+	if err != nil {
+		c.log.Warn("failed to write metadata sidecar",
+			"host", req.SourceHost, "path_hash", pathHash, "error", err)
 	}
 }
 
@@ -528,10 +660,14 @@ func (c *Cache) checkNegativeCache(
 	// Check if expired
 	if time.Now().After(expiresAt) {
 		// Clean up expired entry
-		_, _ = c.db.ExecContext(ctx, `
+		_, err = c.db.ExecContext(ctx, `
 			DELETE FROM negative_cache
 			WHERE source_host = ? AND source_path = ? AND source_query = ?
 		`, req.SourceHost, req.SourcePath, req.SourceQuery)
+		if err != nil {
+			c.log.Warn("failed to delete expired negative cache entry",
+				"host", req.SourceHost, "path", req.SourcePath, "error", err)
+		}
 
 		return false, nil
 	}

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 sums file sizes, 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/concurrent_misses_internal_test.go

@@ -0,0 +1,509 @@
+package imgcache
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"image/jpeg"
+	"io"
+	"io/fs"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/getsentry/sentry-go"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/magic"
+)
+
+// arrivalWait is how long a test gives requests it has started to reach the
+// point where they wait for a held fetch.
+const arrivalWait = 100 * time.Millisecond
+
+// heldFetcher counts the fetches it is asked for and holds each one until
+// releaseFetches is called, so that a test can have requests arrive while a
+// fetch is in progress. started receives once for every fetch.
+type heldFetcher struct {
+	upstream    httpfetcher.Fetcher
+	fetches     atomic.Int32
+	started     chan struct{}
+	release     chan struct{}
+	releaseOnce sync.Once
+}
+
+func (f *heldFetcher) Fetch(
+	ctx context.Context, url string,
+) (*httpfetcher.FetchResult, error) {
+	f.fetches.Add(1)
+
+	f.started <- struct{}{}
+
+	select {
+	case <-f.release:
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	}
+
+	return f.upstream.Fetch(ctx, url)
+}
+
+// releaseFetches lets every held fetch, and every later one, go on.
+func (f *heldFetcher) releaseFetches() {
+	f.releaseOnce.Do(func() { close(f.release) })
+}
+
+// setupHeldFetchService returns a test service whose fetches go through a
+// heldFetcher. Its database is limited to one connection: each connection to
+// an in-memory SQLite database opens a new, empty one, so requests running at
+// once must share the connection that holds the schema.
+func setupHeldFetchService(t *testing.T) (*Service, *TestFixtures, *heldFetcher) {
+	t.Helper()
+
+	svc, fixtures := SetupTestService(t)
+	svc.cache.db.SetMaxOpenConns(1)
+
+	fetcher := &heldFetcher{
+		upstream: svc.fetcher,
+		started:  make(chan struct{}, 100),
+		release:  make(chan struct{}),
+	}
+	svc.fetcher = fetcher
+
+	t.Cleanup(fetcher.releaseFetches)
+
+	return svc, fixtures, fetcher
+}
+
+// photoVariant asks for the test photo, 100x100, at 50x25 as a JPEG of the
+// given quality and fit mode. Each call returns a new request, as Get writes
+// to the request it is given.
+func photoVariant(fixtures *TestFixtures, quality int, fit FitMode) *ImageRequest {
+	return &ImageRequest{
+		SourceHost: fixtures.GoodHost,
+		SourcePath: testPathPhoto,
+		Size:       Size{Width: 50, Height: 25},
+		Format:     FormatJPEG,
+		Quality:    quality,
+		FitMode:    fit,
+	}
+}
+
+// getResult is what one Get call returned, with the image read out.
+type getResult struct {
+	image []byte
+	err   error
+}
+
+// startGet calls Get in a goroutine of its own and delivers what it returned
+// on the channel.
+func startGet(
+	ctx context.Context, svc *Service, req *ImageRequest,
+) <-chan getResult {
+	results := make(chan getResult, 1)
+
+	go func() {
+		resp, err := svc.Get(ctx, req)
+		if err != nil {
+			results <- getResult{err: err}
+
+			return
+		}
+
+		defer func() { _ = resp.Content.Close() }()
+
+		image, err := io.ReadAll(resp.Content)
+		results <- getResult{image: image, err: err}
+	}()
+
+	return results
+}
+
+// jpegSize returns the width and height of the JPEG image in data, or 0 and 0
+// if data is not one.
+func jpegSize(data []byte) (int, int) {
+	config, err := jpeg.DecodeConfig(bytes.NewReader(data))
+	if err != nil {
+		return 0, 0
+	}
+
+	return config.Width, config.Height
+}
+
+// TestService_Get_ConcurrentMissesShareOneFetch starts several requests for
+// one uncached variant while the first one's fetch is held. Between them they
+// must fetch the source once and transcode it once, every one must be answered
+// with the same 50x25 JPEG, and each must count one miss.
+func TestService_Get_ConcurrentMissesShareOneFetch(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	const requests = 8
+
+	pending := make([]<-chan getResult, 0, requests)
+	for range requests {
+		pending = append(pending,
+			startGet(t.Context(), svc, photoVariant(fixtures, 85, FitCover)))
+	}
+
+	<-fetcher.started
+	time.Sleep(arrivalWait)
+	fetcher.releaseFetches()
+
+	var first []byte
+
+	for i, results := range pending {
+		got := <-results
+		if got.err != nil {
+			t.Fatalf("request %d: Get() error = %v", i, got.err)
+		}
+
+		if width, height := jpegSize(got.image); width != 50 || height != 25 {
+			t.Errorf("request %d: image is %dx%d, want a 50x25 JPEG", i, width, height)
+		}
+
+		if first == nil {
+			first = got.image
+		} else if !bytes.Equal(got.image, first) {
+			t.Errorf("request %d: image differs from request 0's", i)
+		}
+	}
+
+	if fetches := fetcher.fetches.Load(); fetches != 1 {
+		t.Errorf("%d requests made %d upstream fetches, want 1", requests, fetches)
+	}
+
+	// NewTestFS builds the same files the test service's fetcher serves.
+	testFS, _ := NewTestFS(t)
+
+	photo, err := fs.ReadFile(testFS, fixtures.GoodHostJPEG)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	want := cacheStatsCounters{0, requests, 1, int64(len(photo)), 1}
+
+	if got := readCacheStatsCounters(t, svc.cache); got != want {
+		t.Errorf("counters = %+v, want %+v", got, want)
+	}
+}
+
+// TestService_Get_ConcurrentVariantsStayApart requests three variants of the
+// test photo at once that differ only in quality or fit. Each must be made by
+// a fetch and a transcode of its own, and each answer must be its own variant.
+func TestService_Get_ConcurrentVariantsStayApart(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	cover := startGet(t.Context(), svc, photoVariant(fixtures, 85, FitCover))
+	lowQuality := startGet(t.Context(), svc, photoVariant(fixtures, 40, FitCover))
+	contain := startGet(t.Context(), svc, photoVariant(fixtures, 85, FitContain))
+
+	for range 3 {
+		select {
+		case <-fetcher.started:
+		case <-time.After(5 * time.Second):
+			t.Fatal("fewer fetches started than variants requested: " +
+				"variants differing in quality or fit were merged")
+		}
+	}
+
+	fetcher.releaseFetches()
+
+	images := make(map[string][]byte)
+
+	for _, variant := range []struct {
+		name          string
+		results       <-chan getResult
+		width, height int
+	}{
+		{"q=85 fit=cover", cover, 50, 25},
+		{"q=40 fit=cover", lowQuality, 50, 25},
+		{"q=85 fit=contain", contain, 25, 25},
+	} {
+		got := <-variant.results
+		if got.err != nil {
+			t.Fatalf("%s: Get() error = %v", variant.name, got.err)
+		}
+
+		width, height := jpegSize(got.image)
+		if width != variant.width || height != variant.height {
+			t.Errorf("%s: image is %dx%d, want a %dx%d JPEG", variant.name,
+				width, height, variant.width, variant.height)
+		}
+
+		images[variant.name] = got.image
+	}
+
+	if bytes.Equal(images["q=85 fit=cover"], images["q=40 fit=cover"]) {
+		t.Error("q=40 was answered with the q=85 image")
+	}
+}
+
+// TestService_Get_WaiterStopsWhenItsContextEnds has a second request for a
+// variant join the first one's held fetch, then ends the second request's
+// context. The second request must return at once with the context's error,
+// while the fetch is still held, and the first must still be answered.
+func TestService_Get_WaiterStopsWhenItsContextEnds(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	first := startGet(t.Context(), svc, photoVariant(fixtures, 85, FitCover))
+
+	<-fetcher.started
+
+	waiterCtx, cancelWaiter := context.WithCancel(t.Context())
+	waiter := startGet(waiterCtx, svc, photoVariant(fixtures, 85, FitCover))
+
+	time.Sleep(arrivalWait)
+	cancelWaiter()
+
+	select {
+	case got := <-waiter:
+		if !errors.Is(got.err, context.Canceled) {
+			t.Errorf("waiting request: Get() error = %v, want %v",
+				got.err, context.Canceled)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("waiting request did not return when its context ended")
+	}
+
+	fetcher.releaseFetches()
+
+	got := <-first
+	if got.err != nil {
+		t.Fatalf("first request: Get() error = %v", got.err)
+	}
+
+	if width, height := jpegSize(got.image); width != 50 || height != 25 {
+		t.Errorf("first request: image is %dx%d, want a 50x25 JPEG", width, height)
+	}
+
+	if fetches := fetcher.fetches.Load(); fetches != 1 {
+		t.Errorf("upstream fetches = %d, want 1", fetches)
+	}
+}
+
+// TestService_Get_FirstRequestLeavingKeepsTheWork ends the context of the
+// request whose fetch is held, after a second request has joined it. The fetch
+// and transcode must go on and answer the second request. The first request
+// waits for its own work, as every request did before misses were shared, and
+// is answered too.
+func TestService_Get_FirstRequestLeavingKeepsTheWork(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	firstCtx, cancelFirst := context.WithCancel(t.Context())
+	first := startGet(firstCtx, svc, photoVariant(fixtures, 85, FitCover))
+
+	<-fetcher.started
+
+	second := startGet(t.Context(), svc, photoVariant(fixtures, 85, FitCover))
+
+	time.Sleep(arrivalWait)
+	cancelFirst()
+	fetcher.releaseFetches()
+
+	for name, results := range map[string]<-chan getResult{
+		"first request": first, "second request": second,
+	} {
+		got := <-results
+		if got.err != nil {
+			t.Fatalf("%s: Get() error = %v", name, got.err)
+		}
+
+		if width, height := jpegSize(got.image); width != 50 || height != 25 {
+			t.Errorf("%s: image is %dx%d, want a 50x25 JPEG", name, width, height)
+		}
+	}
+
+	if fetches := fetcher.fetches.Load(); fetches != 1 {
+		t.Errorf("upstream fetches = %d, want 1", fetches)
+	}
+}
+
+// TestService_Get_ConcurrentMissesShareAFailure has several requests for an
+// image that cannot be served arrive while its fetch is held: the one fetch
+// answers all of them with its error. The request after them is answered from
+// the negative cache when the failure is kept there, and fetches again when it
+// is not.
+func TestService_Get_ConcurrentMissesShareAFailure(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		path        string
+		wantErr     error // what every request at once gets
+		wantNextErr error // what the request after them gets
+		wantFetches int32 // fetches once the request after them is answered
+	}{
+		{"upstream answers 404, kept in the negative cache",
+			"/images/missing.jpg", httpfetcher.ErrUpstreamError,
+			ErrNegativeCached, 1},
+		{"source fails the magic byte check, not kept",
+			"/images/text.png", magic.ErrUnknownFormat, magic.ErrUnknownFormat, 2},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			svc, fixtures, fetcher := setupHeldFetchService(t)
+
+			request := func() *ImageRequest {
+				req := photoVariant(fixtures, 85, FitCover)
+				req.SourcePath = tc.path
+
+				return req
+			}
+
+			pending := make([]<-chan getResult, 0, 4)
+			for range 4 {
+				pending = append(pending, startGet(t.Context(), svc, request()))
+			}
+
+			<-fetcher.started
+			time.Sleep(arrivalWait)
+			fetcher.releaseFetches()
+
+			for i, results := range pending {
+				if got := <-results; !errors.Is(got.err, tc.wantErr) {
+					t.Errorf("request %d: Get() error = %v, want %v", i, got.err, tc.wantErr)
+				}
+			}
+
+			_, err := svc.Get(t.Context(), request())
+			if !errors.Is(err, tc.wantNextErr) {
+				t.Errorf("next request: Get() error = %v, want %v", err, tc.wantNextErr)
+			}
+
+			if fetches := fetcher.fetches.Load(); fetches != tc.wantFetches {
+				t.Errorf("upstream fetches = %d, want %d", fetches, tc.wantFetches)
+			}
+		})
+	}
+}
+
+// TestService_Get_EndedRequestFetchesNothing checks that a request whose
+// context has already ended when it misses the cache starts no fetch.
+func TestService_Get_EndedRequestFetchesNothing(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	_, err := svc.Get(ctx, photoVariant(fixtures, 85, FitCover))
+	if !errors.Is(err, context.Canceled) {
+		t.Errorf("Get() error = %v, want %v", err, context.Canceled)
+	}
+
+	if fetches := fetcher.fetches.Load(); fetches != 0 {
+		t.Errorf("upstream fetches = %d, want 0", fetches)
+	}
+}
+
+// TestService_Get_ReturnsByItsDeadline gives a request a deadline and holds
+// its fetch until the fetch's context ends, as the fetcher does while it waits
+// for a free connection to the host. The request must return by its deadline
+// with the deadline's error.
+func TestService_Get_ReturnsByItsDeadline(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, _ := setupHeldFetchService(t)
+
+	const timeout = 200 * time.Millisecond
+
+	ctx, cancel := context.WithTimeout(t.Context(), timeout)
+	defer cancel()
+
+	results := startGet(ctx, svc, photoVariant(fixtures, 85, FitCover))
+
+	select {
+	case got := <-results:
+		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")
+	}
+}
+
+// panickingFetcher panics on every fetch.
+type panickingFetcher struct{}
+
+func (panickingFetcher) Fetch(
+	context.Context, string,
+) (*httpfetcher.FetchResult, error) {
+	panic("upstream fetcher panicked")
+}
+
+// TestService_Get_PanicBecomesAnError checks that a panic while a variant is
+// being made reaches its request as an error naming the panic, instead of
+// being raised again.
+func TestService_Get_PanicBecomesAnError(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures := SetupTestService(t)
+	svc.fetcher = panickingFetcher{}
+
+	var err error
+
+	func() {
+		defer func() {
+			if recovered := recover(); recovered != nil {
+				t.Fatalf("Get() panicked: %v", recovered)
+			}
+		}()
+
+		_, err = svc.Get(t.Context(), photoVariant(fixtures, 85, FitCover))
+	}()
+
+	if err == nil || !strings.Contains(err.Error(), "upstream fetcher panicked") {
+		t.Errorf("Get() error = %v, want one naming the panic", err)
+	}
+}
+
+// TestService_Get_PanicIsReportedToSentry checks that a panic while a variant
+// is being made is reported through the Sentry hub on the request's context,
+// where the Sentry middleware puts one when sentry_dsn is set.
+func TestService_Get_PanicIsReportedToSentry(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures := SetupTestService(t)
+	svc.fetcher = panickingFetcher{}
+
+	transport := &sentry.MockTransport{}
+
+	client, err := sentry.NewClient(sentry.ClientOptions{
+		Dsn:       "https://abc123@sentry.example.com/42",
+		Transport: transport,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx := sentry.SetHubOnContext(t.Context(),
+		sentry.NewHub(client, sentry.NewScope()))
+
+	func() {
+		defer func() {
+			if recovered := recover(); recovered != nil {
+				t.Fatalf("Get() panicked: %v", recovered)
+			}
+		}()
+
+		_, _ = svc.Get(ctx, photoVariant(fixtures, 85, FitCover))
+	}()
+
+	events := transport.Events()
+	if len(events) != 1 || events[0].Message != "upstream fetcher panicked" {
+		t.Errorf("Sentry events = %+v, want one for the panic", events)
+	}
+}

internal/imgcache/eviction.go

@@ -39,8 +39,8 @@ const tempFilePrefix = ".tmp-"
 // to each variant file.
 const variantMetaSuffix = ".meta"
 
-// fallbackContentType is recorded when a reconciled variant file has
+// fallbackContentType is the content type given to a variant file that
-// no readable .meta sidecar.
+// has no readable .meta sidecar, when it is served or reconciled.
 const fallbackContentType = "application/octet-stream"
 
 // UsageBytes returns the total number of bytes of cache content
@@ -117,7 +117,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 +136,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,
@@ -271,7 +278,9 @@ func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, erro
 
 // evictVariant removes one variant: accounting row first, then the
 // content and .meta files, so the database never references a deleted
-// file.
+// file. The metaCache entry goes before the files; a GetVariant that
+// read them just before may put it back, and the next GetVariant then
+// fails to open the file and removes it again.
 func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 	_, err := c.db.ExecContext(ctx,
 		`DELETE FROM variant_content WHERE cache_key = ?`, string(cacheKey))
@@ -279,7 +288,9 @@ func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 		return fmt.Errorf("failed to delete variant accounting row: %w", err)
 	}
 
-	err = c.variants.DeleteWithMeta(cacheKey)
+	c.metaCache.Remove(cacheKey)
+
+	err = c.variants.Delete(cacheKey)
 	if err != nil {
 		return err
 	}
@@ -420,37 +431,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
+// StopEviction cancels the background eviction goroutine, which
-// it to exit. It is safe to call when eviction was never started, and
+// interrupts a pass in progress, and waits for it to exit or for ctx to
-// safe to call more than once.
+// end, whichever comes first. In the second case it returns an error
-func (c *Cache) StopEviction() {
+// wrapping ctx's error. It is safe to call when eviction was never
-	if !c.evictionStarted {
+// started, and safe to call more than once.
-		return
+func (c *Cache) StopEviction(ctx context.Context) error {
+	if c.evictionCancel == nil {
+		return nil
 	}
 
-	c.evictionStopOnce.Do(func() {
+	c.evictionCancel()
-		close(c.evictionStop)
+
-		<-c.evictionDone
+	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.
+// evictionLoop is the body of the background eviction goroutine. It
-func (c *Cache) evictionLoop(interval time.Duration) {
+// 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)
 
@@ -459,7 +477,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
@@ -480,8 +498,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)
@@ -489,8 +512,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)
@@ -507,7 +535,8 @@ func (c *Cache) runReconciliationPass(ctx context.Context) {
 // 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.
+// 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
@@ -542,6 +571,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
 			}
@@ -630,6 +663,10 @@ func (c *Cache) reconcileVariantRows(ctx context.Context) error {
 	}
 
 	for _, key := range keys {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
 		if c.variants.Exists(key) {
 			continue
 		}
@@ -695,6 +732,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
 			}
@@ -756,6 +797,10 @@ func (c *Cache) reconcileSourceRows(ctx context.Context) error {
 	}
 
 	for _, hash := range hashes {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
 		if c.srcContent.Exists(hash) {
 			continue
 		}

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
+	// Hold the test database's only connection, so the startup pass
-	// over-limit state WITHOUT going through the store methods, so no
+	// waits for it after walking the still empty variant directory: the
-	// write-pressure notification fires and only the periodic ticker
+	// files written while it waits are first seen by a periodic pass.
-	// can trigger eviction.
+	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(),
+	_ = conn.Close()
-			`INSERT INTO variant_content (cache_key, size_bytes, content_type)
+
-			 VALUES (?, ?, ?)`,
+	// Only one of the 1000-byte files fits under the limit: wait until
-			string(key), len(content), "image/webp",
+	// the evictor has removed the other two.
-		)
+	stored := len(keys)
-		if err != nil {
+	deadline = time.Now().Add(5 * time.Second)
-			t.Fatalf("failed to insert variant accounting row: %v", err)
+
+	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",
+		t.Errorf("usage after eviction = %d, want <= %d", usage, limit)
-			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 func() { _ = conn.Close() }()
-	defer cache.StopEviction()
 
-	// Let startup reconciliation run and settle on an empty cache
+	cache.StartEviction(100 * time.Millisecond)
-	// before introducing the untracked file, so the adoption we assert
+	defer func() { _ = cache.StopEviction(t.Context()) }()
-	// below can only be the work of a later, periodic pass.
+
-	time.Sleep(3 * interval)
+	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"
 )
 
@@ -59,6 +58,24 @@ func ValidateFitMode(fit FitMode) error {
 	}
 }
 
+// ValidateImageRequest checks a request's width and height with
+// ValidateDimension and its fit mode with ValidateFitMode. Both the plain
+// /v1/image/ route and the encrypted /v1/e/ route validate through this
+// function so a request from either source enforces identical bounds.
+func ValidateImageRequest(req *ImageRequest) error {
+	err := ValidateDimension("width", req.Size.Width)
+	if err != nil {
+		return err
+	}
+
+	err = ValidateDimension("height", req.Size.Height)
+	if err != nil {
+		return err
+	}
+
+	return ValidateFitMode(req.FitMode)
+}
+
 // ImageRequest represents a request for a processed image
 type ImageRequest struct {
 	// SourceHost is the origin host (e.g., "cdn.example.com")
@@ -77,7 +94,8 @@ type ImageRequest struct {
 	FitMode FitMode
 	// Signature is the HMAC signature for non-allowlisted hosts
 	Signature string
-	// Expires is the signature expiration timestamp
+	// Expires is when the URL expires: the exp of a signed URL, or the expiry
+	// of an encrypted URL; the zero time if it has none
 	Expires time.Time
 	// AllowHTTP indicates whether HTTP (non-TLS) is allowed for this request
 	AllowHTTP bool
@@ -135,18 +153,17 @@ 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)
 }
 
 // CacheStats contains cache statistics
 type CacheStats struct {
-	// TotalItems is the number of cached items
+	// TotalItems is the number of cached source images plus processed
+	// variants
 	TotalItems int64
-	// TotalSizeBytes is the total size of cached content
+	// TotalSizeBytes is the total size of cached source images and
+	// processed variants
 	TotalSizeBytes int64
 	// HitCount is the number of cache hits
 	HitCount int64
@@ -155,29 +172,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/max_concurrent_processing_internal_test.go

@@ -0,0 +1,125 @@
+package imgcache
+
+import (
+	"image/color"
+	"image/jpeg"
+	"io"
+	"os"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/imageprocessor"
+)
+
+// widthOnlyRequest asks for the test photo at width, its height scaled to
+// keep the photo's aspect ratio.
+func widthOnlyRequest(fixtures *TestFixtures, width int) *ImageRequest {
+	return &ImageRequest{
+		SourceHost: fixtures.GoodHost,
+		SourcePath: testPathPhoto,
+		Size:       Size{Width: width},
+		Format:     FormatJPEG,
+		Quality:    85,
+		FitMode:    FitCover,
+	}
+}
+
+// holdProcessingSlot takes one of proc's processing slots and returns the
+// func that gives it back. Process takes its slot before it reads its input,
+// so once it has read a byte from the pipe it holds the slot, until the pipe
+// is closed.
+func holdProcessingSlot(
+	t *testing.T, proc *imageprocessor.ImageProcessor,
+) func() {
+	t.Helper()
+
+	input, feed := io.Pipe()
+
+	go func() {
+		_, _ = proc.Process(t.Context(), input, &imageprocessor.Request{})
+	}()
+
+	_, err := feed.Write([]byte{0})
+	if err != nil {
+		t.Fatalf("Process call to hold the slot did not start: %v", err)
+	}
+
+	release := func() { _ = feed.Close() }
+	t.Cleanup(release)
+
+	return release
+}
+
+// TestService_Get_WaitsForSlotBeforeReadingCachedSource checks that a
+// request whose source is cached holds none of it while it waits for a
+// processing slot: it reads the cached file only once it has a slot. With
+// the only slot held, a request for a new width of the cached 100x100 photo
+// waits; the cached file is then rewritten as a 100x50 image before the slot
+// is freed, so the request must answer with that image scaled to 40x20.
+func TestService_Get_WaitsForSlotBeforeReadingCachedSource(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures := SetupTestService(t)
+	svc.processor = imageprocessor.New(
+		imageprocessor.Params{MaxConcurrentProcessing: 1},
+	)
+
+	// A first request caches the photo as a source.
+	resp, err := svc.Get(t.Context(), widthOnlyRequest(fixtures, 50))
+	if err != nil {
+		t.Fatalf("first Get() error = %v", err)
+	}
+
+	_ = resp.Content.Close()
+
+	contentHash, _, err := svc.cache.LookupSource(t.Context(),
+		widthOnlyRequest(fixtures, 50))
+	if err != nil || contentHash == "" {
+		t.Fatalf("LookupSource() = %q, %v; want the cached source",
+			contentHash, err)
+	}
+
+	release := holdProcessingSlot(t, svc.processor)
+
+	var (
+		waited    *ImageResponse
+		waitedErr error
+	)
+
+	done := make(chan struct{})
+
+	go func() {
+		defer close(done)
+
+		waited, waitedErr = svc.Get(t.Context(), widthOnlyRequest(fixtures, 40))
+	}()
+
+	// Give the request time to reach the slot: had it read the cached source
+	// before waiting, it would have read it by now.
+	time.Sleep(100 * time.Millisecond)
+
+	err = os.WriteFile(svc.cache.srcContent.hashToPath(contentHash),
+		generateTestJPEG(t, 100, 50, color.RGBA{0, 0, 255, 255}), 0o600)
+	if err != nil {
+		t.Fatalf("failed to rewrite the cached source: %v", err)
+	}
+
+	release()
+	<-done
+
+	if waitedErr != nil {
+		t.Fatalf("Get() error = %v", waitedErr)
+	}
+
+	defer func() { _ = waited.Content.Close() }()
+
+	output, err := jpeg.DecodeConfig(waited.Content)
+	if err != nil {
+		t.Fatalf("failed to decode the response: %v", err)
+	}
+
+	if output.Width != 40 || output.Height != 20 {
+		t.Errorf("response is %dx%d, want 40x20: the request read the cached "+
+			"source before it had a processing slot", output.Width, output.Height)
+	}
+}

internal/imgcache/metacache_internal_test.go

@@ -0,0 +1,349 @@
+package imgcache
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"sync"
+	"testing"
+	"time"
+)
+
+// webpRequest returns a request for a 100x100 WebP variant of path.
+func webpRequest(path string) *ImageRequest {
+	return &ImageRequest{
+		SourceHost: testHostCDN,
+		SourcePath: path,
+		Size:       Size{Width: 100, Height: 100},
+		Format:     FormatWebP,
+		Quality:    85,
+		FitMode:    FitCover,
+	}
+}
+
+// assertVariantServed checks that GetVariant serves key with the given
+// content and the image/webp content type storeEvictionTestVariant stores.
+func assertVariantServed(t *testing.T, cache *Cache, key VariantKey, content []byte) {
+	t.Helper()
+
+	reader, size, contentType, err := cache.GetVariant(key)
+	if err != nil {
+		t.Fatalf("GetVariant(%s) error = %v", key, err)
+	}
+
+	defer func() { _ = reader.Close() }()
+
+	got, err := io.ReadAll(reader)
+	if err != nil {
+		t.Fatalf("reading variant %s: %v", key, err)
+	}
+
+	if !bytes.Equal(got, content) {
+		t.Errorf("GetVariant(%s) content = %q, want %q", key, got, content)
+	}
+
+	if size != int64(len(content)) {
+		t.Errorf("GetVariant(%s) size = %d, want %d", key, size, len(content))
+	}
+
+	if contentType != testContentTypeWebP {
+		t.Errorf("GetVariant(%s) content type = %q, want %q",
+			key, contentType, testContentTypeWebP)
+	}
+}
+
+// assertVariantNotFound checks that GetVariant refuses key with
+// ErrNotFound.
+func assertVariantNotFound(t *testing.T, cache *Cache, key VariantKey) {
+	t.Helper()
+
+	reader, _, _, err := cache.GetVariant(key)
+	if err == nil {
+		_ = reader.Close()
+	}
+
+	if !errors.Is(err, ErrNotFound) {
+		t.Errorf("GetVariant(%s) error = %v, want ErrNotFound", key, err)
+	}
+}
+
+// assertLookupMisses checks that Lookup reports request as a miss.
+func assertLookupMisses(t *testing.T, cache *Cache, request *ImageRequest) {
+	t.Helper()
+
+	lookup, err := cache.Lookup(t.Context(), request)
+	if err != nil {
+		t.Fatalf("Lookup(%s) error = %v", request.SourcePath, err)
+	}
+
+	if lookup.Hit {
+		t.Errorf("Lookup(%s) is a hit, want a miss", request.SourcePath)
+	}
+}
+
+// renameFile renames the file at from to to.
+func renameFile(t *testing.T, from, to string) {
+	t.Helper()
+
+	err := os.Rename(from, to)
+	if err != nil {
+		t.Fatalf("renaming %s: %v", from, err)
+	}
+}
+
+// TestSecondHitDoesNotReadMetaFile checks that once a variant has been
+// stored or read, a hit takes its content type from memory: with the
+// .meta file deleted, GetVariant must still return the stored content
+// type rather than the application/octet-stream it uses without one.
+func TestSecondHitDoesNotReadMetaFile(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	content := []byte("webp variant bytes")
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne, content)
+
+	// A second Cache on the same state directory starts with nothing in
+	// memory, as pixad does after a restart, so its first read uses the
+	// .meta file.
+	restarted, err := NewCache(cache.db, cache.config)
+	if err != nil {
+		t.Fatalf("NewCache() error = %v", err)
+	}
+
+	assertVariantServed(t, restarted, testVariantKeyOne, content)
+
+	err = os.Remove(cache.variants.keyToPath(testVariantKeyOne) + ".meta")
+	if err != nil {
+		t.Fatalf("removing .meta file: %v", err)
+	}
+
+	assertVariantServed(t, cache, testVariantKeyOne, content)
+	assertVariantServed(t, restarted, testVariantKeyOne, content)
+}
+
+// TestReadDuringStoreKeepsStoredContentType checks that a GetVariant
+// which began before StoreVariant finished cannot replace the content
+// type the store kept in memory. Such a read can find the variant file
+// but not yet its .meta file, and so gets application/octet-stream. The
+// test deletes the .meta file after the store, then runs the part of
+// GetVariant that comes after its check of memory.
+func TestReadDuringStoreKeepsStoredContentType(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	content := []byte("webp variant bytes")
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne, content)
+
+	err := os.Remove(cache.variants.keyToPath(testVariantKeyOne) + ".meta")
+	if err != nil {
+		t.Fatalf("removing .meta file: %v", err)
+	}
+
+	reader, _, contentType, err := cache.loadVariantWithMeta(testVariantKeyOne)
+	if err != nil {
+		t.Fatalf("loadVariantWithMeta(%s) error = %v", testVariantKeyOne, err)
+	}
+
+	_ = reader.Close()
+
+	t.Logf("the read without a .meta file got content type %q", contentType)
+
+	assertVariantServed(t, cache, testVariantKeyOne, content)
+}
+
+// TestReadOfOlderMetaFileKeepsStoredContentType checks that a read
+// which got its content type from a .meta file that StoreVariant had
+// not yet rewritten cannot replace the type the store kept in memory.
+// The test writes such a .meta file, with a different content type,
+// after the store, then runs the part of GetVariant that comes after
+// its check of memory.
+func TestReadOfOlderMetaFileKeepsStoredContentType(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	content := []byte("webp variant bytes")
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne, content)
+
+	olderMeta, err := json.Marshal(VariantMeta{
+		ContentType: testContentTypeJPEG,
+		Size:        int64(len(content)),
+	})
+	if err != nil {
+		t.Fatalf("encoding .meta file: %v", err)
+	}
+
+	metaPath := cache.variants.keyToPath(testVariantKeyOne) + ".meta"
+
+	err = os.WriteFile(metaPath, olderMeta, StorageFilePerm)
+	if err != nil {
+		t.Fatalf("writing .meta file: %v", err)
+	}
+
+	reader, _, contentType, err := cache.loadVariantWithMeta(testVariantKeyOne)
+	if err != nil {
+		t.Fatalf("loadVariantWithMeta(%s) error = %v", testVariantKeyOne, err)
+	}
+
+	_ = reader.Close()
+
+	if contentType != testContentTypeJPEG {
+		t.Fatalf("loadVariantWithMeta(%s) content type = %q, want %q from the .meta file",
+			testVariantKeyOne, contentType, testContentTypeJPEG)
+	}
+
+	kept, _ := cache.metaCache.Get(testVariantKeyOne)
+	if kept != testContentTypeWebP {
+		t.Errorf("content type in memory = %q, want the stored %q",
+			kept, testContentTypeWebP)
+	}
+}
+
+// TestFailedReadDuringStoreKeepsStoredContentType checks that a read
+// which found no .meta file cannot leave application/octet-stream in
+// memory, even when another read has removed the content type
+// StoreVariant kept there. In this order: the store; a read that finds
+// the variant in memory but cannot open its file, and so removes it
+// from memory; a read that opened the variant file before the store
+// wrote its .meta file. Later hits must get the stored content type.
+func TestFailedReadDuringStoreKeepsStoredContentType(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	content := []byte("webp variant bytes")
+	variantPath := cache.variants.keyToPath(testVariantKeyOne)
+	metaPath := variantPath + ".meta"
+
+	storeEvictionTestVariant(t, cache, testVariantKeyOne, content)
+
+	renameFile(t, variantPath, variantPath+".hidden")
+	assertVariantNotFound(t, cache, testVariantKeyOne)
+	renameFile(t, variantPath+".hidden", variantPath)
+
+	renameFile(t, metaPath, metaPath+".hidden")
+
+	reader, _, contentType, err := cache.GetVariant(testVariantKeyOne)
+	if err != nil {
+		t.Fatalf("GetVariant(%s) error = %v", testVariantKeyOne, err)
+	}
+
+	_ = reader.Close()
+
+	t.Logf("the read without a .meta file got content type %q", contentType)
+
+	renameFile(t, metaPath+".hidden", metaPath)
+
+	assertVariantServed(t, cache, testVariantKeyOne, content)
+}
+
+// TestEvictedVariantIsNotServed checks that a variant the evictor
+// removed is a miss and cannot be read, although it had been stored
+// and served before.
+func TestEvictedVariantIsNotServed(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1500)
+
+	oldRequest := webpRequest("/old.jpg")
+	newRequest := webpRequest("/new.jpg")
+	oldKey := CacheKey(oldRequest)
+	newKey := CacheKey(newRequest)
+	oldContent := bytes.Repeat([]byte{0x01}, 1000)
+	newContent := bytes.Repeat([]byte{0x02}, 1000)
+
+	storeEvictionTestVariant(t, cache, oldKey, oldContent)
+	storeEvictionTestVariant(t, cache, newKey, newContent)
+	assertVariantServed(t, cache, oldKey, oldContent)
+	setVariantLastAccessed(t, cache, oldKey, time.Now().Add(-time.Hour))
+
+	err := cache.EvictToLimit(t.Context())
+	if err != nil {
+		t.Fatalf("EvictToLimit() error = %v", err)
+	}
+
+	assertLookupMisses(t, cache, oldRequest)
+	assertVariantNotFound(t, cache, oldKey)
+	assertVariantServed(t, cache, newKey, newContent)
+}
+
+// TestVariantDeletedFromDiskIsNotServed checks that a variant whose
+// file was deleted by something other than the evictor cannot be read,
+// and is a miss afterwards.
+func TestVariantDeletedFromDiskIsNotServed(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+
+	request := webpRequest("/deleted.jpg")
+	key := CacheKey(request)
+	content := []byte("webp variant bytes")
+
+	storeEvictionTestVariant(t, cache, key, content)
+	assertVariantServed(t, cache, key, content)
+
+	err := os.Remove(cache.variants.keyToPath(key))
+	if err != nil {
+		t.Fatalf("removing variant file: %v", err)
+	}
+
+	assertVariantNotFound(t, cache, key)
+	assertLookupMisses(t, cache, request)
+}
+
+// TestConcurrentVariantStoreReadAndEvict stores, reads and evicts
+// variants from several goroutines at once, for the race detector.
+func TestConcurrentVariantStoreReadAndEvict(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	ctx := t.Context()
+
+	var wg sync.WaitGroup
+
+	for goroutine := range 8 {
+		wg.Go(func() {
+			key := VariantKey(fmt.Sprintf("aabbccdd01%02d", goroutine))
+			content := []byte(key)
+
+			for range 20 {
+				err := cache.StoreVariant(
+					ctx, key, bytes.NewReader(content), testContentTypeWebP)
+				if err != nil {
+					t.Errorf("StoreVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				reader, _, contentType, err := cache.GetVariant(key)
+				if err != nil {
+					t.Errorf("GetVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				_ = reader.Close()
+
+				if contentType != testContentTypeWebP {
+					t.Errorf("GetVariant(%s) content type = %q, want %q",
+						key, contentType, testContentTypeWebP)
+				}
+
+				err = cache.evictVariant(ctx, key)
+				if err != nil {
+					t.Errorf("evictVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				assertVariantNotFound(t, cache, key)
+			}
+		})
+	}
+
+	wg.Wait()
+}

internal/imgcache/service.go

@@ -8,9 +8,13 @@ import (
 	"io"
 	"log/slog"
 	"net/url"
+	"runtime/debug"
 	"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"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
@@ -29,13 +33,17 @@ type Service struct {
 	log             *slog.Logger
 	allowHTTP       bool
 	maxResponseSize int64
+	// variantsInProgress lets the requests that miss the same variant at the
+	// same time share one fetch and one transcode.
+	variantsInProgress singleflight.Group
 }
 
 // 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
@@ -43,15 +51,17 @@ type ServiceConfig struct {
 	SigningKey string
 	// Allowlist is the list of hosts that don't require signatures
 	Allowlist []string
+	// MaxConcurrentProcessing is the most images processed at once; zero
+	// uses the image processor's default, one per CPU
+	MaxConcurrentProcessing int
 	// Logger for logging
 	Logger *slog.Logger
 }
 
-// Static errors for service construction and unimplemented operations.
+// Static errors for service construction.
 var (
-	errCacheRequired       = errors.New("cache is required")
+	errCacheRequired      = errors.New("cache is required")
-	errSigningKeyRequired  = errors.New("signing key is required")
+	errSigningKeyRequired = errors.New("signing key is required")
-	errPurgeNotImplemented = errors.New("purge not implemented")
 )
 
 // NewService creates a new image service.
@@ -91,9 +101,10 @@ func NewService(cfg *ServiceConfig) (*Service, error) {
 	}
 
 	maxResponseSize := fetcherCfg.MaxResponseSize
-	processor := imageprocessor.New(
+	processor := imageprocessor.New(imageprocessor.Params{
-		imageprocessor.Params{MaxInputBytes: maxResponseSize},
+		MaxInputBytes:           maxResponseSize,
-	)
+		MaxConcurrentProcessing: cfg.MaxConcurrentProcessing,
+	})
 
 	return &Service{
 		cache:           cfg.Cache,
@@ -143,7 +154,8 @@ 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 {
-			s.cache.IncrementStats(ctx, true, 0)
+			// Counted also when the request context has ended meanwhile
+			s.cache.IncrementStats(context.WithoutCancel(ctx), true, 0)
 
 			return &ImageResponse{
 				Content:       reader,
@@ -155,12 +167,13 @@ func (s *Service) Get(ctx context.Context, req *ImageRequest) (*ImageResponse, e
 		}
 	}
 
-	// Cache miss - check if we have source content cached
+	// Cache miss - get the variant, processed once for all the requests that
-	cacheKey := CacheKey(req)
+	// miss it at the same time, then count this request's miss, also when it
+	// failed or the request context has ended meanwhile
+	response, err := s.processOrWait(ctx, req)
 
-	s.cache.IncrementStats(ctx, false, 0)
+	s.cache.IncrementStats(context.WithoutCancel(ctx), false, 0)
 
-	response, err := s.processFromSourceOrFetch(ctx, req, cacheKey)
 	if err != nil {
 		return nil, err
 	}
@@ -177,16 +190,17 @@ 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)
+}
+
 // ValidateRequest validates the request signature if required.
 func (s *Service) ValidateRequest(req *ImageRequest) error {
 	// Check if host is allowed (no signature required)
@@ -205,12 +219,23 @@ func (s *Service) ValidateRequest(req *ImageRequest) error {
 	return s.signer.Verify(signatureRequest(req))
 }
 
-// GenerateSignedURL generates a signed URL for the given request.
+// GenerateSignedURL generates a signed URL for the given request. The URL
+// carries q and fit next to sig and exp, so the image route verifies it for
+// the quality and fit it was signed with. An unset quality or fit is first
+// set to 85 or cover, the values the route uses when a URL has no q or fit.
 func (s *Service) GenerateSignedURL(
 	baseURL string,
 	req *ImageRequest,
 	ttl time.Duration,
 ) (string, error) {
+	if req.Quality == 0 {
+		req.Quality = 85
+	}
+
+	if req.FitMode == "" {
+		req.FitMode = FitCover
+	}
+
 	sigReq := signatureRequest(req)
 	path, sig, exp := s.signer.GenerateSignedURL(sigReq, ttl)
 
@@ -218,41 +243,131 @@ func (s *Service) GenerateSignedURL(
 	req.Expires = sigReq.Expires
 	req.Signature = sigReq.Signature
 
-	return fmt.Sprintf("%s%s?sig=%s&exp=%d", baseURL, path, sig, exp), nil
+	return fmt.Sprintf("%s%s?sig=%s&exp=%d&q=%d&fit=%s",
+		baseURL, path, sig, exp, req.Quality, req.FitMode), nil
 }
 
-// loadCachedSource attempts to load source content from cache, returning nil
+// errPanicked is returned when processing a variant panicked.
-// if the cached data is unavailable or exceeds maxResponseSize.
+var errPanicked = errors.New("panic while processing image")
-func (s *Service) loadCachedSource(contentHash ContentHash) []byte {
+
-	reader, err := s.cache.GetSourceContent(contentHash)
+// processOrWait returns the variant req asks for. The first of the requests
+// that miss a variant at the same time processes it, and singleflight hands
+// its result, or its error, to the others: they fetch nothing, read no source
+// and take no upstream connection or processing slot. The processing ignores
+// the first request's cancellation, so the others are still served if that
+// client goes away, but keeps its deadline.
+func (s *Service) processOrWait(
+	ctx context.Context, req *ImageRequest,
+) (*ImageResponse, error) {
+	// A request that has already ended starts no processing
+	if ctx.Err() != nil {
+		return nil, ctx.Err()
+	}
+
+	cacheKey := CacheKey(req)
+
+	// Closed when this request's own function runs, which singleflight does
+	// only when no other request is processing the variant
+	processing := make(chan struct{})
+
+	results := s.variantsInProgress.DoChan(string(cacheKey),
+		func() (_ any, err error) {
+			close(processing)
+
+			// singleflight would raise a panic again in a goroutine of its
+			// own, where no handler recovers it, and stop pixad. It is
+			// reported through the Sentry hub that the Sentry middleware puts
+			// on the request's context when sentry_dsn is set.
+			defer func() {
+				recovered := recover()
+				if recovered != nil {
+					s.log.Error("panic while processing image",
+						"host", req.SourceHost, "path", req.SourcePath,
+						"panic", recovered, "stack", string(debug.Stack()))
+
+					if hub := sentry.GetHubFromContext(ctx); hub != nil {
+						hub.RecoverWithContext(ctx, recovered)
+					}
+
+					err = fmt.Errorf("%w: %v", errPanicked, recovered)
+				}
+			}()
+
+			processingCtx := context.WithoutCancel(ctx)
+
+			if deadline, ok := ctx.Deadline(); ok {
+				var cancel context.CancelFunc
+
+				processingCtx, cancel = context.WithDeadline(processingCtx, deadline)
+				defer cancel()
+			}
+
+			return s.processFromSourceOrFetch(processingCtx, req, cacheKey)
+		})
+
+	var result singleflight.Result
+
+	select {
+	case result = <-results:
+	case <-ctx.Done():
+		select {
+		case <-processing:
+			// This request is processing the variant: it waits for the
+			// result, as every request did before misses were shared
+			result = <-results
+		default:
+			// Another request is processing the variant, or this request's
+			// function has not started yet; the processing goes on without it
+			return nil, ctx.Err()
+		}
+	}
+
+	if result.Err != nil {
+		return nil, result.Err
+	}
+
+	variant, _ := result.Val.(*processedVariant)
+
+	return &ImageResponse{
+		Content:       io.NopCloser(bytes.NewReader(variant.data)),
+		ContentLength: int64(len(variant.data)),
+		ContentType:   variant.contentType,
+		FetchedBytes:  variant.fetchedBytes,
+		ETag:          formatETag(cacheKey),
+	}, nil
+}
+
+// loadCachedSource opens source content from cache, without reading it, and
+// returns it with its size; nil if the cached data is unavailable, empty or
+// exceeds maxResponseSize.
+func (s *Service) loadCachedSource(
+	contentHash ContentHash,
+) (io.ReadCloser, int64) {
+	reader, size, err := s.cache.GetSourceContent(contentHash)
 	if err != nil {
 		s.log.Warn("failed to load cached source, fetching", "error", err)
 
-		return nil
+		return nil, 0
 	}
 
-	// Bound the read to maxResponseSize to prevent unbounded memory use
+	if size > s.maxResponseSize {
-	// from unexpectedly large cached files.
+		_ = reader.Close()
-	limited := io.LimitReader(reader, s.maxResponseSize+1)
-	data, err := io.ReadAll(limited)
-	_ = reader.Close()
 
-	if err != nil {
-		s.log.Warn("failed to read cached source, fetching", "error", err)
-
-		return nil
-	}
-
-	if int64(len(data)) > s.maxResponseSize {
 		s.log.Warn("cached source exceeds max response size, discarding",
 			"hash", contentHash,
 			"max_bytes", s.maxResponseSize,
 		)
 
-		return nil
+		return nil, 0
 	}
 
-	return data
+	if size == 0 {
+		_ = reader.Close()
+
+		return nil, 0
+	}
+
+	return reader, size
 }
 
 // processFromSourceOrFetch processes an image, using cached source content
@@ -261,7 +376,7 @@ func (s *Service) processFromSourceOrFetch(
 	ctx context.Context,
 	req *ImageRequest,
 	cacheKey VariantKey,
-) (*ImageResponse, error) {
+) (*processedVariant, error) {
 	// Check if we have cached source content
 	contentHash, _, err := s.cache.LookupSource(ctx, req)
 	if err != nil {
@@ -269,37 +384,36 @@ func (s *Service) processFromSourceOrFetch(
 	}
 
 	var (
-		sourceData []byte
+		source     io.ReadCloser
-		fetchBytes int64
+		sourceSize int64
 	)
 
 	if contentHash != "" {
 		s.log.Debug("using cached source", "hash", contentHash)
-		sourceData = s.loadCachedSource(contentHash)
+		source, sourceSize = s.loadCachedSource(contentHash)
 	}
 
 	// Fetch from upstream if we don't have source data or it's empty
-	if len(sourceData) == 0 {
+	if source == nil {
-		resp, err := s.fetchAndProcess(ctx, req, cacheKey)
+		return s.fetchAndProcess(ctx, req, cacheKey)
-		if err != nil {
-			return nil, err
-		}
-
-		return resp, nil
 	}
 
-	// Process using cached source
+	defer func() { _ = source.Close() }()
-	fetchBytes = int64(len(sourceData))
 
-	return s.processAndStore(ctx, req, cacheKey, sourceData, fetchBytes)
+	// Process using cached source; nothing was fetched from upstream. The
+	// image processor reads the source only once it has a processing slot,
+	// so a request waiting for one holds none of it in memory.
+	return s.processAndStore(ctx, req, cacheKey, source, sourceSize)
 }
 
 // fetchAndProcess fetches from upstream, processes, and caches the result.
+// It counts the fetch with the bytes read from upstream, including when
+// reading the response or a later step fails.
 func (s *Service) fetchAndProcess(
 	ctx context.Context,
 	req *ImageRequest,
 	cacheKey VariantKey,
-) (*ImageResponse, error) {
+) (*processedVariant, error) {
 	// Fetch from upstream
 	sourceURL := req.SourceURL()
 
@@ -310,23 +424,35 @@ func (s *Service) fetchAndProcess(
 		// Store negative cache for certain errors
 		if isNegativeCacheable(err) {
 			statusCode := extractStatusCode(err)
-			_ = s.cache.StoreNegative(ctx, req, statusCode, err.Error())
+
+			storeErr := s.cache.StoreNegative(ctx, req, statusCode, err.Error())
+			if storeErr != nil {
+				s.log.Warn("failed to store negative cache entry",
+					"host", req.SourceHost, "path", req.SourcePath, "error", storeErr)
+			}
 		}
 
 		return nil, fmt.Errorf("upstream fetch failed: %w", err)
 	}
 
+	// Closing the body frees the upstream connection. It is closed only
+	// after processing, so the fetcher's connection limit also bounds the
+	// fetched sources held in memory while their requests wait for a
+	// processing slot.
 	defer func() { _ = fetchResult.Content.Close() }()
 
 	// Read and validate the source content
 	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)
+
 	if err != nil {
 		return nil, fmt.Errorf("failed to read upstream response: %w", err)
 	}
 
 	// Calculate download bitrate
-	fetchBytes := int64(len(sourceData))
-
 	var downloadRate string
 
 	if fetchResult.FetchDurationMs > 0 {
@@ -337,6 +463,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,
@@ -361,17 +488,28 @@ func (s *Service) fetchAndProcess(
 		// Continue even if caching fails
 	}
 
-	return s.processAndStore(ctx, req, cacheKey, sourceData, fetchBytes)
+	return s.processAndStore(
+		ctx, req, cacheKey, bytes.NewReader(sourceData), fetchBytes,
+	)
 }
 
-// processAndStore processes an image and stores the result.
+// processedVariant is a variant as processAndStore made it. Each request that
+// shared its processing serves it through a reader of its own.
+type processedVariant struct {
+	data         []byte
+	contentType  string
+	fetchedBytes int64
+}
+
+// processAndStore processes the image read from source and stores the
+// result.
 func (s *Service) processAndStore(
 	ctx context.Context,
 	req *ImageRequest,
 	cacheKey VariantKey,
-	sourceData []byte,
+	source io.Reader,
 	fetchBytes int64,
-) (*ImageResponse, error) {
+) (*processedVariant, error) {
 	// Process the image
 	processStart := time.Now()
 
@@ -382,13 +520,16 @@ func (s *Service) processAndStore(
 		FitMode: imageprocessor.FitMode(req.FitMode),
 	}
 
-	processResult, err := s.processor.Process(ctx, bytes.NewReader(sourceData), processReq)
+	processResult, err := s.processor.Process(ctx, source, processReq)
 	if err != nil {
 		return nil, fmt.Errorf("image processing failed: %w", err)
 	}
 
 	processDuration := time.Since(processStart)
 
+	// Counted also when the request context has ended meanwhile
+	s.cache.IncrementTransformCount(context.WithoutCancel(ctx))
+
 	// Read processed content
 	processedData, err := io.ReadAll(processResult.Content)
 	_ = processResult.Content.Close()
@@ -407,6 +548,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,
@@ -432,12 +574,10 @@ func (s *Service) processAndStore(
 		// Continue even if caching fails
 	}
 
-	return &ImageResponse{
+	return &processedVariant{
-		Content:       io.NopCloser(bytes.NewReader(processedData)),
+		data:         processedData,
-		ContentLength: outputSize,
+		contentType:  processResult.ContentType,
-		ContentType:   processResult.ContentType,
+		fetchedBytes: fetchBytes,
-		FetchedBytes:  fetchBytes,
-		ETag:          formatETag(cacheKey),
 	}, nil
 }
 
@@ -452,6 +592,8 @@ func signatureRequest(req *ImageRequest) *signature.Request {
 		Width:       req.Size.Width,
 		Height:      req.Size.Height,
 		Format:      string(req.Format),
+		Quality:     req.Quality,
+		FitMode:     string(req.FitMode),
 		Signature:   req.Signature,
 		Expires:     req.Expires,
 	}

internal/imgcache/stats_internal_test.go

@@ -1,13 +1,20 @@
 package imgcache
 
 import (
+	"bytes"
 	"context"
 	"database/sql"
+	"image/color"
+	"io"
+	"io/fs"
+	"log/slog"
 	"math"
+	"strings"
 	"testing"
 	"time"
 
 	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
 )
 
 func setupStatsTestDB(t *testing.T) *sql.DB {
@@ -101,3 +108,392 @@ func TestStats_ZeroCounts(t *testing.T) {
 		t.Errorf("HitRate = %f, want 0.0 for zero counts", stats.HitRate)
 	}
 }
+
+// TestStats_LogsFailedCountQueries verifies that a failed item count query
+// and a failed size query are each logged at warn and Stats still succeeds.
+func TestStats_LogsFailedCountQueries(t *testing.T) {
+	t.Parallel()
+
+	db := setupStatsTestDB(t)
+
+	var logBuf bytes.Buffer
+
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    t.TempDir(),
+		CacheTTL:    time.Hour,
+		NegativeTTL: 5 * time.Minute,
+		Logger:      slog.New(slog.NewJSONHandler(&logBuf, nil)),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(t.Context(),
+		`DROP TABLE source_content; DROP TABLE variant_content`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = cache.Stats(t.Context())
+	if err != nil {
+		t.Fatalf("Stats() error = %v, want nil", err)
+	}
+
+	for _, msg := range []string{
+		"failed to count cache items for stats",
+		"failed to sum cache size for stats",
+	} {
+		want := `"level":"WARN","msg":"` + msg + `"`
+		if !strings.Contains(logBuf.String(), want) {
+			t.Errorf("log missing %s; got %q", want, logBuf.String())
+		}
+	}
+}
+
+// TestIncrementStats_LogsFailedUpdates verifies that a failed hit or miss
+// count update and a failed upstream fetch count update are each logged at
+// warn.
+func TestIncrementStats_LogsFailedUpdates(t *testing.T) {
+	t.Parallel()
+
+	db := setupStatsTestDB(t)
+
+	var logBuf bytes.Buffer
+
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    t.TempDir(),
+		CacheTTL:    time.Hour,
+		NegativeTTL: 5 * time.Minute,
+		Logger:      slog.New(slog.NewJSONHandler(&logBuf, nil)),
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, err = db.ExecContext(t.Context(), `DROP TABLE cache_stats`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	cache.IncrementStats(t.Context(), false, 1024)
+
+	for _, msg := range []string{
+		"failed to count cache hit or miss",
+		"failed to count upstream fetch",
+	} {
+		want := `"level":"WARN","msg":"` + msg + `"`
+		if !strings.Contains(logBuf.String(), want) {
+			t.Errorf("log missing %s; got %q", want, logBuf.String())
+		}
+	}
+}
+
+// TestStats_TotalsCountSourcesAndVariants verifies that TotalItems and
+// TotalSizeBytes cover the stored source images and processed variants.
+func TestStats_TotalsCountSourcesAndVariants(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	storeEvictionTestSource(t, cache, testHostCDN, testPathCat,
+		bytes.Repeat([]byte{0xAA}, 1000))
+	storeEvictionTestVariant(t, cache, testVariantKeyOne,
+		bytes.Repeat([]byte{0xAB}, 500))
+	storeEvictionTestVariant(t, cache, testVariantKeyTwo,
+		bytes.Repeat([]byte{0xAC}, 250))
+
+	stats, err := cache.Stats(t.Context())
+	if err != nil {
+		t.Fatalf("Stats() error = %v", err)
+	}
+
+	if stats.TotalItems != 3 {
+		t.Errorf("TotalItems = %d, want 3 (1 source, 2 variants)", stats.TotalItems)
+	}
+
+	if stats.TotalSizeBytes != 1750 {
+		t.Errorf("TotalSizeBytes = %d, want 1750 (1000+500+250)",
+			stats.TotalSizeBytes)
+	}
+}
+
+// TestStats_DisabledCacheReportsNoItems verifies that a disabled disk cache
+// reports no items and no size, even when its database still holds the
+// rows of an earlier run with the disk cache enabled.
+func TestStats_DisabledCacheReportsNoItems(t *testing.T) {
+	t.Parallel()
+
+	enabled, _ := newEvictionTestCache(t, 1<<30)
+
+	storeEvictionTestSource(t, enabled, testHostCDN, testPathCat,
+		bytes.Repeat([]byte{0xAA}, 1000))
+	storeEvictionTestVariant(t, enabled, testVariantKeyOne,
+		bytes.Repeat([]byte{0xAB}, 500))
+
+	disabled, err := NewCache(enabled.db, CacheConfig{
+		StateDir:         t.TempDir(),
+		CacheTTL:         time.Hour,
+		NegativeTTL:      5 * time.Minute,
+		DisableDiskCache: true,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stats, err := disabled.Stats(t.Context())
+	if err != nil {
+		t.Fatalf("Stats() error = %v", err)
+	}
+
+	if stats.TotalItems != 0 || stats.TotalSizeBytes != 0 {
+		t.Errorf("TotalItems = %d, TotalSizeBytes = %d, want 0 and 0",
+			stats.TotalItems, stats.TotalSizeBytes)
+	}
+}
+
+// cacheStatsCounters holds the counters of the cache_stats row, in column
+// order.
+type cacheStatsCounters struct {
+	hitCount           int64
+	missCount          int64
+	upstreamFetchCount int64
+	upstreamFetchBytes int64
+	transformCount     int64
+}
+
+// readCacheStatsCounters reads the counters of the cache_stats row.
+func readCacheStatsCounters(t *testing.T, cache *Cache) cacheStatsCounters {
+	t.Helper()
+
+	var got cacheStatsCounters
+
+	err := cache.db.QueryRowContext(t.Context(), `
+		SELECT hit_count, miss_count, upstream_fetch_count,
+		       upstream_fetch_bytes, transform_count
+		FROM cache_stats WHERE id = 1
+	`).Scan(&got.hitCount, &got.missCount, &got.upstreamFetchCount,
+		&got.upstreamFetchBytes, &got.transformCount)
+	if err != nil {
+		t.Fatalf("failed to read cache_stats: %v", err)
+	}
+
+	return got
+}
+
+// TestService_Get_CountsStats walks Get through a miss that fetches the
+// source, a hit, a miss that reuses the cached source, and two misses whose
+// source cannot be used, checking every cache_stats counter after each.
+func TestService_Get_CountsStats(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures := SetupTestService(t)
+
+	// NewTestFS builds the same files the test service's fetcher serves.
+	testFS, _ := NewTestFS(t)
+
+	photo, err := fs.ReadFile(testFS, fixtures.GoodHostJPEG)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	fake, err := fs.ReadFile(testFS, fixtures.InvalidFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	photoBytes, fakeBytes := int64(len(photo)), int64(len(fake))
+
+	// want is hits, misses, upstream fetches, upstream bytes, transforms.
+	steps := []struct {
+		name    string
+		path    string
+		size    int
+		wantErr bool
+		want    cacheStatsCounters
+	}{
+		{"miss that fetches the source", testPathPhoto, 50, false,
+			cacheStatsCounters{0, 1, 1, photoBytes, 1}},
+		{"hit", testPathPhoto, 50, false,
+			cacheStatsCounters{1, 1, 1, photoBytes, 1}},
+		{"miss that reuses the cached source", testPathPhoto, 25, false,
+			cacheStatsCounters{1, 2, 1, photoBytes, 2}},
+		{"miss whose source fails the magic byte check", "/images/fake.jpg", 50, true,
+			cacheStatsCounters{1, 3, 2, photoBytes + fakeBytes, 2}},
+		{"miss whose source is not found", "/images/nonexistent.jpg", 50, true,
+			cacheStatsCounters{1, 4, 2, photoBytes + fakeBytes, 2}},
+	}
+
+	for _, step := range steps {
+		resp, err := svc.Get(t.Context(), &ImageRequest{
+			SourceHost: fixtures.GoodHost,
+			SourcePath: step.path,
+			Size:       Size{Width: step.size, Height: step.size},
+			Format:     FormatJPEG,
+			Quality:    85,
+			FitMode:    FitCover,
+		})
+		if (err != nil) != step.wantErr {
+			t.Fatalf("%s: Get() error = %v, want error %t", step.name, err, step.wantErr)
+		}
+
+		if err == nil {
+			_ = resp.Content.Close()
+		}
+
+		got := readCacheStatsCounters(t, svc.cache)
+		if got != step.want {
+			t.Fatalf("after the %s: counters = %+v, want %+v", step.name, got, step.want)
+		}
+	}
+}
+
+// fakeUpstream answers every fetch with itself as a JPEG body. The body
+// serves data, then calls cancel, when set, and returns err; io.EOF ends
+// the body normally.
+type fakeUpstream struct {
+	data   *bytes.Reader
+	cancel context.CancelFunc
+	err    error
+}
+
+func (u *fakeUpstream) Fetch(
+	context.Context, string,
+) (*httpfetcher.FetchResult, error) {
+	return &httpfetcher.FetchResult{
+		Content:       io.NopCloser(u),
+		ContentLength: -1,
+		ContentType:   testContentTypeJPEG,
+	}, nil
+}
+
+func (u *fakeUpstream) Read(p []byte) (int, error) {
+	if u.data.Len() > 0 {
+		return u.data.Read(p)
+	}
+
+	if u.cancel != nil {
+		u.cancel()
+	}
+
+	return 0, u.err
+}
+
+// TestService_Get_CountsInterruptedMisses checks every cache_stats counter
+// after a miss whose request context ends during or after the upstream
+// fetch, and after a miss whose upstream body is over the size limit.
+func TestService_Get_CountsInterruptedMisses(t *testing.T) {
+	t.Parallel()
+
+	photo := generateTestJPEG(t, 100, 100, color.RGBA{255, 0, 0, 255})
+	half := len(photo) / 2
+
+	// want is hits, misses, upstream fetches, upstream bytes, transforms.
+	tests := []struct {
+		name    string
+		served  int   // bytes of the photo the upstream body serves
+		cancel  bool  // whether the body then ends the request context
+		readErr error // what the body then returns
+		wantErr bool
+		want    cacheStatsCounters
+	}{
+		{"request context ends during the fetch", half, true, context.Canceled, true,
+			cacheStatsCounters{0, 1, 1, int64(half), 0}},
+		{"request context ends after the fetch", len(photo), true, io.EOF, false,
+			cacheStatsCounters{0, 1, 1, int64(len(photo)), 1}},
+		{"upstream body over the size limit", half, false,
+			httpfetcher.ErrResponseTooLarge, true,
+			cacheStatsCounters{0, 1, 1, int64(half), 0}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			svc, fixtures := SetupTestService(t)
+
+			ctx, cancel := context.WithCancel(t.Context())
+			defer cancel()
+
+			upstream := &fakeUpstream{
+				data: bytes.NewReader(photo[:tc.served]),
+				err:  tc.readErr,
+			}
+			if tc.cancel {
+				upstream.cancel = cancel
+			}
+
+			svc.fetcher = upstream
+
+			resp, err := svc.Get(ctx, &ImageRequest{
+				SourceHost: fixtures.GoodHost,
+				SourcePath: testPathPhoto,
+				Size:       Size{Width: 50, Height: 50},
+				Format:     FormatJPEG,
+				Quality:    85,
+				FitMode:    FitCover,
+			})
+			t.Logf("Get() error = %v", err)
+
+			if (err != nil) != tc.wantErr {
+				t.Fatalf("Get() error = %v, want error %t", err, tc.wantErr)
+			}
+
+			if err == nil {
+				_ = resp.Content.Close()
+			}
+
+			got := readCacheStatsCounters(t, svc.cache)
+			if got != tc.want {
+				t.Errorf("counters = %+v, want %+v", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestService_Get_CountsHitAfterRequestEnds checks every cache_stats counter
+// after a hit served with a request context that has already ended: only
+// the hit count moves.
+func TestService_Get_CountsHitAfterRequestEnds(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures := SetupTestService(t)
+
+	req := &ImageRequest{
+		SourceHost: fixtures.GoodHost,
+		SourcePath: testPathPhoto,
+		Size:       Size{Width: 50, Height: 50},
+		Format:     FormatJPEG,
+		Quality:    85,
+		FitMode:    FitCover,
+	}
+
+	// A first request caches the variant.
+	resp, err := svc.Get(t.Context(), req)
+	if err != nil {
+		t.Fatalf("first Get() error = %v", err)
+	}
+
+	_ = resp.Content.Close()
+
+	want := readCacheStatsCounters(t, svc.cache)
+	want.hitCount++
+
+	ctx, cancel := context.WithCancel(t.Context())
+	cancel()
+
+	resp, err = svc.Get(ctx, req)
+	if err != nil {
+		t.Fatalf("Get() with an ended request context: error = %v", err)
+	}
+
+	_ = resp.Content.Close()
+
+	if resp.CacheStatus != CacheHit {
+		t.Fatalf("CacheStatus = %v, want %v", resp.CacheStatus, CacheHit)
+	}
+
+	got := readCacheStatsCounters(t, svc.cache)
+	if got != want {
+		t.Errorf("counters = %+v, want %+v", got, want)
+	}
+}

internal/imgcache/storage.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"time"
@@ -392,6 +393,7 @@ func CacheKey(req *ImageRequest) VariantKey {
 // Unlike ContentStorage, the key is provided by the caller (not computed from content).
 type VariantStorage struct {
 	baseDir string
+	log     *slog.Logger
 }
 
 // VariantMeta contains metadata about a cached variant.
@@ -404,13 +406,14 @@ type VariantMeta struct {
 }
 
 // NewVariantStorage creates a new variant storage at the given base directory.
-func NewVariantStorage(baseDir string) (*VariantStorage, error) {
+// A failed .meta write is logged to log.
+func NewVariantStorage(baseDir string, log *slog.Logger) (*VariantStorage, error) {
 	err := os.MkdirAll(baseDir, StorageDirPerm)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create variant storage directory: %w", err)
 	}
 
-	return &VariantStorage{baseDir: baseDir}, nil
+	return &VariantStorage{baseDir: baseDir, log: log}, nil
 }
 
 // Store writes content and metadata to storage at the given key.
@@ -478,7 +481,11 @@ func (s *VariantStorage) Store(
 	}
 
 	// Metadata write failure is non-fatal; content is already stored.
-	_ = os.WriteFile(metaPath, metaData, StorageFilePerm)
+	err = os.WriteFile(metaPath, metaData, StorageFilePerm)
+	if err != nil {
+		s.log.Warn("failed to write variant metadata sidecar",
+			"path", metaPath, "error", err)
+	}
 
 	return size, nil
 }
@@ -499,32 +506,44 @@ func (s *VariantStorage) Load(key VariantKey) (io.ReadCloser, error) {
 	return f, nil
 }
 
-// LoadWithMeta returns a reader, size, and content type for the content at
+// LoadWithSize returns a reader and file size for the content at the
-// the given key.
+// given key.
-func (s *VariantStorage) LoadWithMeta(
+func (s *VariantStorage) LoadWithSize(key VariantKey) (io.ReadCloser, int64, error) {
-	key VariantKey,
-) (io.ReadCloser, int64, string, error) {
 	path := s.keyToPath(key)
-	metaPath := path + ".meta"
 
 	f, err := os.Open(path) //nolint:gosec // path derived from cache key
 	if err != nil {
 		if os.IsNotExist(err) {
-			return nil, 0, "", ErrNotFound
+			return nil, 0, ErrNotFound
 		}
 
-		return nil, 0, "", fmt.Errorf("failed to open content: %w", err)
+		return nil, 0, fmt.Errorf("failed to open content: %w", err)
 	}
 
 	stat, err := f.Stat()
 	if err != nil {
 		_ = f.Close()
 
-		return nil, 0, "", fmt.Errorf("failed to stat content: %w", err)
+		return nil, 0, fmt.Errorf("failed to stat content: %w", err)
 	}
 
-	// Load metadata for content type
+	return f, stat.Size(), nil
-	contentType := "application/octet-stream" // fallback
+}
+
+// LoadWithMeta returns a reader, size, and content type for the content at
+// the given key. The content type is read from the .meta file, and is
+// empty when that file is missing or unreadable.
+func (s *VariantStorage) LoadWithMeta(
+	key VariantKey,
+) (io.ReadCloser, int64, string, error) {
+	f, size, err := s.LoadWithSize(key)
+	if err != nil {
+		return nil, 0, "", err
+	}
+
+	var contentType string
+
+	metaPath := s.keyToPath(key) + ".meta"
 
 	metaData, err := os.ReadFile(metaPath) //nolint:gosec // path derived from cache key
 	if err == nil {
@@ -534,7 +553,7 @@ func (s *VariantStorage) LoadWithMeta(
 		}
 	}
 
-	return f, stat.Size(), contentType, nil
+	return f, size, contentType, nil
 }
 
 // Exists checks if content exists at the given key.
@@ -545,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)
 
@@ -554,18 +574,7 @@ func (s *VariantStorage) Delete(key VariantKey) error {
 		return fmt.Errorf("failed to delete content: %w", err)
 	}
 
-	return nil
+	metaPath := path + ".meta"
-}
-
-// 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"
 
 	err = os.Remove(metaPath)
 	if err != nil && !os.IsNotExist(err) {

internal/imgcache/storage_internal_test.go

@@ -4,8 +4,10 @@ import (
 	"bytes"
 	"errors"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -404,3 +406,105 @@ func TestCacheKey(t *testing.T) {
 		t.Error("CacheKey() produced same key for different quality")
 	}
 }
+
+// TestVariantStorage_StoreLogsFailedMetaWrite verifies that a .meta write
+// that fails is logged at warn and the store still succeeds.
+func TestVariantStorage_StoreLogsFailedMetaWrite(t *testing.T) {
+	t.Parallel()
+
+	var logBuf bytes.Buffer
+
+	storage, err := NewVariantStorage(
+		t.TempDir(), slog.New(slog.NewJSONHandler(&logBuf, nil)))
+	if err != nil {
+		t.Fatalf("NewVariantStorage() error = %v", err)
+	}
+
+	key := CacheKey(&ImageRequest{SourceHost: testHostCDN, SourcePath: testPathCat})
+
+	// A directory where the .meta file goes makes the .meta write fail.
+	err = os.MkdirAll(storage.keyToPath(key)+".meta", StorageDirPerm)
+	if err != nil {
+		t.Fatalf("failed to create directory: %v", err)
+	}
+
+	_, err = storage.Store(key, bytes.NewReader([]byte("variant data")), "image/webp")
+	if err != nil {
+		t.Fatalf("Store() error = %v, want nil", err)
+	}
+
+	want := `"level":"WARN","msg":"failed to write variant metadata sidecar"`
+	if !strings.Contains(logBuf.String(), want) {
+		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/testutil_internal_test.go

@@ -24,6 +24,7 @@ const (
 	testHostExample       = "example.com"
 	testPathCat           = "/photos/cat.jpg"
 	testContentTypeJPEG   = "image/jpeg"
+	testContentTypeWebP   = "image/webp"
 	testHeaderContentType = "Content-Type"
 )
 

internal/imgcache/urlparser.go

@@ -23,6 +23,21 @@ var (
 // MaxDimension is the maximum allowed width or height.
 const MaxDimension = 8192
 
+// ValidateDimension checks one requested width or height; name ("width" or
+// "height") appears in the error. 0 means "original size" and is valid.
+func ValidateDimension(name string, value int) error {
+	if value < 0 {
+		return fmt.Errorf("%w: %s is negative", ErrInvalidSize, name)
+	}
+
+	if value > MaxDimension {
+		return fmt.Errorf("%w: %s is above %d",
+			ErrDimensionTooLarge, name, MaxDimension)
+	}
+
+	return nil
+}
+
 // sizeFormatRegex matches patterns like "800x600.webp", "0x0.jpeg", "orig.png"
 var sizeFormatRegex = regexp.MustCompile(`^(\d+)x(\d+)\.(\w+)$|^(orig)\.(\w+)$`)
 
@@ -225,14 +240,20 @@ func parseSizeFormat(s string) (Size, ImageFormat, error) {
 			return Size{}, "", ErrInvalidSize
 		}
 
-		if width > MaxDimension || height > MaxDimension {
-			return Size{}, "", ErrDimensionTooLarge
-		}
-
 		size = Size{Width: width, Height: height}
 		formatStr = matches[3]
 	}
 
+	err := ValidateDimension("width", size.Width)
+	if err != nil {
+		return Size{}, "", err
+	}
+
+	err = ValidateDimension("height", size.Height)
+	if err != nil {
+		return Size{}, "", err
+	}
+
 	format, err := parseFormat(formatStr)
 	if err != nil {
 		return Size{}, "", err

internal/imgcache/validate_internal_test.go

@@ -0,0 +1,64 @@
+package imgcache
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestValidateImageRequest(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		req     ImageRequest
+		wantErr error
+	}{
+		{
+			name: "within bounds",
+			req:  ImageRequest{Size: Size{Width: 800, Height: 600}, FitMode: FitCover},
+		},
+		{
+			name: "original size and empty fit",
+			req:  ImageRequest{Size: Size{Width: 0, Height: 0}},
+		},
+		{
+			name:    "width over limit",
+			req:     ImageRequest{Size: Size{Width: MaxDimension + 1, Height: 600}},
+			wantErr: ErrDimensionTooLarge,
+		},
+		{
+			name:    "height over limit",
+			req:     ImageRequest{Size: Size{Width: 800, Height: MaxDimension + 1}},
+			wantErr: ErrDimensionTooLarge,
+		},
+		{
+			name:    "negative width",
+			req:     ImageRequest{Size: Size{Width: -1, Height: 600}},
+			wantErr: ErrInvalidSize,
+		},
+		{
+			name:    "invalid fit mode",
+			req:     ImageRequest{Size: Size{Width: 800, Height: 600}, FitMode: "bogus"},
+			wantErr: ErrInvalidFitMode,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := ValidateImageRequest(&tt.req)
+			if tt.wantErr == nil {
+				if err != nil {
+					t.Fatalf("ValidateImageRequest() error = %v, want nil", err)
+				}
+
+				return
+			}
+
+			if !errors.Is(err, tt.wantErr) {
+				t.Fatalf("ValidateImageRequest() error = %v, want %v", err, tt.wantErr)
+			}
+		})
+	}
+}

internal/middleware/client_ip_internal_test.go

@@ -0,0 +1,118 @@
+package middleware
+
+import (
+	"bytes"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"strings"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/clientip"
+	"sneak.berlin/go/pixa/internal/config"
+)
+
+// testForwardedClient is the client address the proxy forwards.
+const testForwardedClient = "203.0.113.7"
+
+// newTestMiddleware builds a Middleware whose resolver trusts the given
+// CIDRs and whose logger writes JSON to buf.
+func newTestMiddleware(t *testing.T, buf *bytes.Buffer, trusted ...string) *Middleware {
+	t.Helper()
+
+	prefixes := make([]netip.Prefix, 0, len(trusted))
+
+	for _, c := range trusted {
+		p, err := netip.ParsePrefix(c)
+		if err != nil {
+			t.Fatalf("netip.ParsePrefix(%q) error = %v", c, err)
+		}
+
+		prefixes = append(prefixes, p)
+	}
+
+	return &Middleware{
+		log:      slog.New(slog.NewJSONHandler(buf, nil)),
+		config:   &config.Config{TrustedProxies: prefixes},
+		clientIP: clientip.NewResolver(prefixes),
+	}
+}
+
+// TestClientIPMiddlewareStoresResolvedIP verifies the ClientIP middleware
+// puts the resolved address into the request context for a trusted and an
+// untrusted peer.
+func TestClientIPMiddlewareStoresResolvedIP(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		remoteAddr string
+		forwarded  string
+		want       string
+	}{
+		{
+			name:       "trusted peer honors forwarded client",
+			remoteAddr: "10.0.0.1:5000",
+			forwarded:  testForwardedClient,
+			want:       testForwardedClient,
+		},
+		{
+			name:       "untrusted peer ignores forwarded header",
+			remoteAddr: "198.51.100.9:5000",
+			forwarded:  testForwardedClient,
+			want:       "198.51.100.9",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			mw := newTestMiddleware(t, &bytes.Buffer{}, "10.0.0.0/8")
+
+			var got string
+
+			handler := mw.ClientIP()(http.HandlerFunc(
+				func(_ http.ResponseWriter, r *http.Request) {
+					got = clientip.FromContext(r.Context())
+				}))
+
+			req := httptest.NewRequestWithContext(
+				t.Context(), http.MethodGet, "/", nil)
+			req.RemoteAddr = tt.remoteAddr
+			req.Header.Set("X-Forwarded-For", tt.forwarded)
+
+			handler.ServeHTTP(httptest.NewRecorder(), req)
+
+			if got != tt.want {
+				t.Errorf("client IP in context = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestLoggingUsesResolvedClientIP verifies the logging middleware records
+// the resolved forwarded client IP rather than the proxy peer address.
+func TestLoggingUsesResolvedClientIP(t *testing.T) {
+	t.Parallel()
+
+	var buf bytes.Buffer
+
+	mw := newTestMiddleware(t, &buf, "10.0.0.0/8")
+
+	handler := mw.ClientIP()(mw.Logging()(http.HandlerFunc(
+		func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(http.StatusOK)
+		})))
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/", nil)
+	req.RemoteAddr = "10.0.0.1:5000"
+	req.Header.Set("X-Forwarded-For", testForwardedClient)
+
+	handler.ServeHTTP(httptest.NewRecorder(), req)
+
+	if !strings.Contains(buf.String(), `"remoteIP":"`+testForwardedClient+`"`) {
+		t.Errorf("log output missing resolved client IP; got %q", buf.String())
+	}
+}

internal/middleware/middleware.go

@@ -2,18 +2,23 @@
 package middleware
 
 import (
+	"context"
+	"crypto/rand"
 	"log/slog"
-	"net"
 	"net/http"
+	"net/netip"
+	"regexp"
 	"time"
 
 	basicauth "github.com/99designs/basicauth-go"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/go-chi/cors"
+	"github.com/go-chi/httprate"
 	metrics "github.com/slok/go-http-metrics/metrics/prometheus"
 	ghmm "github.com/slok/go-http-metrics/middleware"
 	"github.com/slok/go-http-metrics/middleware/std"
 	"go.uber.org/fx"
+	"sneak.berlin/go/pixa/internal/clientip"
 	"sneak.berlin/go/pixa/internal/config"
 	"sneak.berlin/go/pixa/internal/logger"
 )
@@ -21,6 +26,30 @@ import (
 // CORSMaxAgeSeconds is the max age for CORS preflight cache (24 hours).
 const CORSMaxAgeSeconds = 86400
 
+// HSTSValue is the Strict-Transport-Security header value: one year with
+// includeSubDomains. Emitted unconditionally even though pixa listens plain
+// HTTP behind a TLS-terminating proxy; browsers ignore an HSTS header received
+// over plaintext (RFC 6797 section 8.1), so it never lies about the connection,
+// and emitting it here avoids trusting a forwarded-proto header.
+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.
+const ContentSecurityPolicyValue = "default-src 'self'; " +
+	"script-src 'self'; " +
+	"style-src 'self'; " +
+	"object-src 'none'; " +
+	"base-uri 'self'; " +
+	"form-action 'self'; " +
+	"frame-ancestors 'none'"
+
+// PermissionsPolicyValue is the Permissions-Policy header value. Every listed
+// feature is denied because pixa uses none of them.
+const PermissionsPolicyValue = "accelerometer=(), autoplay=(), camera=(), " +
+	"display-capture=(), geolocation=(), gyroscope=(), magnetometer=(), " +
+	"microphone=(), payment=(), usb=()"
+
 // Params defines dependencies for Middleware.
 type Params struct {
 	fx.In
@@ -31,31 +60,85 @@ type Params struct {
 
 // Middleware provides HTTP middleware functions.
 type Middleware struct {
-	log    *slog.Logger
+	log      *slog.Logger
-	config *config.Config
+	config   *config.Config
+	clientIP *clientip.Resolver
 }
 
 // New creates a new Middleware instance.
 func New(_ fx.Lifecycle, params Params) (*Middleware, error) {
 	s := &Middleware{
-		log:    params.Logger.Get(),
+		log:      params.Logger.Get(),
-		config: params.Config,
+		config:   params.Config,
+		clientIP: clientip.NewResolver(params.Config.TrustedProxies),
 	}
 
 	return s, nil
 }
 
-func ipFromHostPort(hp string) string {
+// ClientIP returns a middleware that resolves the real client IP,
-	h, _, err := net.SplitHostPort(hp)
+// honoring X-Forwarded-For only from trusted proxies, and stores it in
-	if err != nil {
+// the request context for the logging middleware and handlers to read.
-		return ""
+func (s *Middleware) ClientIP() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			ip := s.clientIP.Resolve(
+				r.RemoteAddr, r.Header.Values(clientip.ForwardedForHeader))
+			ctx := clientip.WithClientIP(r.Context(), ip)
+			next.ServeHTTP(w, r.WithContext(ctx))
+		})
 	}
+}
 
-	if len(h) > 0 && h[0] == '[' {
+// RateLimit returns a middleware that limits each client to requestLimit
-		return h[1 : len(h)-1]
+// requests per window and refuses a request over the limit with 429 Too Many
+// Requests and a Retry-After header. Clients are told apart by the address
+// the ClientIP middleware stored in the request context, so ClientIP must
+// run first. An IPv6 client is counted by its /64, which one client usually
+// holds whole; an IPv4-mapped address (::ffff:a.b.c.d) is counted as the
+// IPv4 address it carries, since every such address falls in the same /64.
+// Counts are kept only for the current and the previous window, so memory
+// stays bounded.
+func (s *Middleware) RateLimit(
+	requestLimit int, window time.Duration,
+) func(http.Handler) http.Handler {
+	return httprate.LimitBy(requestLimit, window,
+		func(r *http.Request) (string, error) {
+			ip := clientip.FromContext(r.Context())
+
+			addr, err := netip.ParseAddr(ip)
+			if err == nil {
+				ip = addr.Unmap().String()
+			}
+
+			return httprate.CanonicalizeIP(ip), nil
+		})
+}
+
+// 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))
+		})
 	}
-
-	return h
 }
 
 type loggingResponseWriter struct {
@@ -100,7 +183,7 @@ func (s *Middleware) Logging() func(http.Handler) http.Handler {
 					"request_id", reqID,
 					"referer", r.Referer(),
 					"proto", r.Proto,
-					"remoteIP", ipFromHostPort(r.RemoteAddr),
+					"remoteIP", clientip.FromContext(ctx),
 					"status", lrw.statusCode,
 					"response_bytes", lrw.bytesWritten,
 					"latency_ms", latency.Milliseconds(),
@@ -115,7 +198,7 @@ func (s *Middleware) Logging() func(http.Handler) http.Handler {
 // CORS returns a CORS middleware.
 func (s *Middleware) CORS() func(http.Handler) http.Handler {
 	return cors.Handler(cors.Options{
-		AllowedOrigins:   []string{"*"},
+		AllowedOrigins:   []string{s.config.AccessControlAllowOrigin},
 		AllowedMethods:   []string{"GET", "HEAD", "OPTIONS"},
 		AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type"},
 		ExposedHeaders:   []string{"Link"},
@@ -164,6 +247,16 @@ func (s *Middleware) SecurityHeaders() func(http.Handler) http.Handler {
 			// Disable XSS filtering (modern browsers don't need it, can cause issues)
 			w.Header().Set("X-XSS-Protection", "0")
 
+			// Force HTTPS on future visits (ignored by browsers over plaintext)
+			w.Header().Set("Strict-Transport-Security", HSTSValue)
+
+			// Restrict content sources; frame-ancestors is the primary
+			// clickjacking control, X-Frame-Options the legacy fallback
+			w.Header().Set("Content-Security-Policy", ContentSecurityPolicyValue)
+
+			// Deny browser features pixa does not use
+			w.Header().Set("Permissions-Policy", PermissionsPolicyValue)
+
 			next.ServeHTTP(w, r)
 		})
 	}

internal/middleware/middleware_internal_test.go

@@ -1,14 +1,263 @@
 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"
 )
 
+// TestCORSAnswersWithConfiguredOrigin checks that the CORS middleware
+// answers with access_control_allow_origin, where "*" lets any origin read
+// responses and a single origin lets only that origin read them.
+func TestCORSAnswersWithConfiguredOrigin(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)
+
+		req := httptest.NewRequestWithContext(
+			t.Context(), http.MethodGet, "/v1/image/example.com/a.jpg/1x1.png", nil)
+		req.Header.Set("Origin", tc.requestOrigin)
+
+		rec := httptest.NewRecorder()
+
+		handler.ServeHTTP(rec, req)
+
+		got := rec.Header().Get("Access-Control-Allow-Origin")
+		if got != tc.want {
+			t.Errorf("configured %q, request from %q: "+
+				"Access-Control-Allow-Origin = %q, want %q",
+				tc.configured, tc.requestOrigin, got, tc.want)
+		}
+	}
+}
+
+// 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()
 
@@ -56,6 +305,68 @@ func TestSecurityHeaders(t *testing.T) {
 	}
 }
 
+func TestSecurityHeaders_PolicyHeaders(t *testing.T) {
+	t.Parallel()
+
+	cfg := &config.Config{}
+	mw := &Middleware{
+		log:    slog.Default(),
+		config: cfg,
+	}
+
+	testHandler := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+
+	handler := mw.SecurityHeaders()(testHandler)
+
+	req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/test", nil)
+	rec := httptest.NewRecorder()
+
+	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
+	}{
+		{"Strict-Transport-Security", "max-age=31536000; includeSubDomains"},
+		{
+			"Content-Security-Policy",
+			"default-src 'self'; " +
+				"script-src 'self'; " +
+				"style-src 'self'; " +
+				"object-src 'none'; " +
+				"base-uri 'self'; " +
+				"form-action 'self'; " +
+				"frame-ancestors 'none'",
+		},
+		{
+			"Permissions-Policy",
+			"accelerometer=(), autoplay=(), camera=(), " +
+				"display-capture=(), geolocation=(), gyroscope=(), " +
+				"magnetometer=(), microphone=(), payment=(), usb=()",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.header, func(t *testing.T) {
+			t.Parallel()
+
+			got := rec.Header().Get(tt.header)
+			if got != tt.want {
+				t.Errorf("%s = %q, want %q", tt.header, got, tt.want)
+			}
+		})
+	}
+}
+
 func TestSecurityHeaders_PreservesExistingHeaders(t *testing.T) {
 	t.Parallel()
 

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/cors_internal_test.go

@@ -0,0 +1,64 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestCORSOnlyOnImageRoutes verifies that the image routes answer with the
+// configured access_control_allow_origin, a preflight request included, and
+// that the login and URL generator pages send no Access-Control-Allow-Origin,
+// so no other site can read them. /metrics is left out: its middleware
+// registers with the process-wide Prometheus registry, which only one test
+// in this package can do.
+func TestCORSOnlyOnImageRoutes(t *testing.T) {
+	t.Parallel()
+
+	const appOrigin = "https://app.example.com"
+
+	s := newTestServer(t)
+	s.config.AccessControlAllowOrigin = appOrigin
+	s.SetupRoutes()
+
+	requests := []struct {
+		method string
+		path   string
+		want   string
+	}{
+		{http.MethodGet, unsignedImagePath, appOrigin},
+		{http.MethodHead, unsignedImagePath, appOrigin},
+		{http.MethodOptions, unsignedImagePath, appOrigin},
+		{http.MethodGet, encryptedImagePath, appOrigin},
+		{http.MethodGet, "/", ""},
+		{http.MethodOptions, "/", ""},
+		{http.MethodPost, "/generate", ""},
+		{http.MethodGet, "/logout", ""},
+	}
+
+	for _, tc := range requests {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			t.Parallel()
+
+			req := httptest.NewRequestWithContext(
+				t.Context(), tc.method, tc.path, nil)
+			req.Header.Set("Origin", appOrigin)
+
+			// An OPTIONS request naming the method it asks about is the
+			// preflight a browser sends before some cross-origin requests.
+			if tc.method == http.MethodOptions {
+				req.Header.Set("Access-Control-Request-Method", http.MethodGet)
+			}
+
+			rec := httptest.NewRecorder()
+			s.ServeHTTP(rec, req)
+			t.Logf("status %d", rec.Code)
+
+			got := rec.Header().Get("Access-Control-Allow-Origin")
+			if got != tc.want {
+				t.Errorf("Access-Control-Allow-Origin = %q, want %q",
+					got, tc.want)
+			}
+		})
+	}
+}

internal/server/http.go

@@ -5,35 +5,52 @@ import (
 	"fmt"
 	"net/http"
 	"time"
+
+	"go.uber.org/fx"
 )
 
 // HTTP server configuration constants.
 const (
-	HTTPReadTimeout    = 30 * time.Second
+	HTTPReadTimeout = 30 * time.Second
-	HTTPWriteTimeout   = 60 * time.Second
+	// HTTPReadHeaderTimeout bounds the request-header read on its own,
+	// short, so a slowloris client dribbling headers is dropped well
+	// before it ties up a connection for the whole ReadTimeout window.
+	HTTPReadHeaderTimeout = 10 * time.Second
+	// HTTPIdleTimeout bounds how long an idle keep-alive connection is
+	// held open, so idle connections cannot accumulate without limit on a
+	// service targeting high concurrency.
+	HTTPIdleTimeout    = 120 * time.Second
 	HTTPMaxHeaderBytes = 8 << 10 // 8KB
 )
 
-func (s *Server) serveUntilShutdown() {
+// newHTTPServer builds the http.Server with the hardening timeouts and
-	listenAddr := fmt.Sprintf(":%d", s.config.Port)
+// limits applied. It is separate from serveUntilShutdown so the
-	s.httpServer = &http.Server{
+// configuration can be asserted in a test without binding a listener.
-		Addr:           listenAddr,
+func (s *Server) newHTTPServer() *http.Server {
-		ReadTimeout:    HTTPReadTimeout,
+	return &http.Server{
-		WriteTimeout:   HTTPWriteTimeout,
+		Addr:              fmt.Sprintf(":%d", s.config.Port),
-		MaxHeaderBytes: HTTPMaxHeaderBytes,
+		ReadTimeout:       HTTPReadTimeout,
-		Handler:        s,
+		ReadHeaderTimeout: HTTPReadHeaderTimeout,
+		WriteTimeout:      s.config.DownstreamTimeout,
+		IdleTimeout:       HTTPIdleTimeout,
+		MaxHeaderBytes:    HTTPMaxHeaderBytes,
+		Handler:           s,
 	}
+}
 
-	s.SetupRoutes()
+// 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
-	s.log.Info("http begin listen", "listenaddr", listenAddr)
+// shut down with exit code 1.
+func (s *Server) serveUntilShutdown() {
+	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 {
+		err = s.shutdowner.Shutdown(fx.ExitCode(1))
-			s.cancelFunc()
+		if err != nil {
+			s.log.Error("shutdown request failed", "error", err)
 		}
 	}
 }

internal/server/http_internal_test.go

@@ -0,0 +1,69 @@
+package server
+
+import (
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/config"
+)
+
+// TestNewHTTPServerTimeouts verifies that the constructed http.Server
+// carries every hardening timeout wired onto it, including the slowloris
+// defense (ReadHeaderTimeout) and the keep-alive bound (IdleTimeout). This
+// guards against a field being defined but never set on the server, so
+// each assertion compares the server field to its constant, or, for
+// WriteTimeout, to downstream_timeout from the config.
+func TestNewHTTPServerTimeouts(t *testing.T) {
+	t.Parallel()
+
+	s := &Server{config: &config.Config{
+		Port:              8080,
+		DownstreamTimeout: 45 * time.Second,
+	}}
+
+	srv := s.newHTTPServer()
+
+	fields := []struct {
+		name string
+		got  time.Duration
+		want time.Duration
+	}{
+		{"ReadTimeout", srv.ReadTimeout, HTTPReadTimeout},
+		{"ReadHeaderTimeout", srv.ReadHeaderTimeout, HTTPReadHeaderTimeout},
+		{"WriteTimeout", srv.WriteTimeout, 45 * time.Second},
+		{"IdleTimeout", srv.IdleTimeout, HTTPIdleTimeout},
+	}
+
+	for _, f := range fields {
+		if f.got != f.want {
+			t.Errorf("%s = %v, want %v", f.name, f.got, f.want)
+		}
+	}
+
+	if srv.MaxHeaderBytes != HTTPMaxHeaderBytes {
+		t.Errorf("MaxHeaderBytes = %d, want %d",
+			srv.MaxHeaderBytes, HTTPMaxHeaderBytes)
+	}
+
+	if srv.Handler != s {
+		t.Error("Handler is not the server")
+	}
+}
+
+// TestHardeningTimeoutValues pins the intent behind the two new timeouts
+// without hard-coding brittle exact durations: the header-read phase is
+// bounded strictly shorter than the whole-request read (the slowloris
+// dribble), and idle keep-alive connections are bounded rather than held
+// open forever.
+func TestHardeningTimeoutValues(t *testing.T) {
+	t.Parallel()
+
+	if HTTPReadHeaderTimeout <= 0 || HTTPReadHeaderTimeout > HTTPReadTimeout {
+		t.Errorf("ReadHeaderTimeout = %v, want positive and <= ReadTimeout %v",
+			HTTPReadHeaderTimeout, HTTPReadTimeout)
+	}
+
+	if HTTPIdleTimeout <= 0 {
+		t.Errorf("IdleTimeout = %v, want positive bound", HTTPIdleTimeout)
+	}
+}

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/login_rate_limit_internal_test.go

@@ -0,0 +1,289 @@
+package server
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/netip"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"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/handlers"
+	"sneak.berlin/go/pixa/internal/healthcheck"
+	"sneak.berlin/go/pixa/internal/logger"
+	"sneak.berlin/go/pixa/internal/middleware"
+)
+
+// testSigningKey is a throwaway signing key; submitting it logs in.
+const testSigningKey = "test-signing-key-0123456789abcdef"
+
+// wrongKey is submitted for a failed login.
+const wrongKey = "not-the-signing-key"
+
+// Addresses for the login rate limit tests. The test server trusts
+// 10.0.0.0/8 as its proxies, so the X-Forwarded-For sent by proxyPeer is
+// believed and the one sent by firstClient or secondClient is ignored.
+const (
+	firstClient     = "198.51.100.1:40000"
+	secondClient    = "198.51.100.2:40000"
+	proxyPeer       = "10.0.0.1:40000"
+	firstForwarded  = "203.0.113.1"
+	secondForwarded = "203.0.113.2"
+)
+
+// csrfFieldPattern extracts the CSRF token rendered into the login form.
+var csrfFieldPattern = regexp.MustCompile(
+	`name="gorilla\.csrf\.Token" value="([^"]+)"`)
+
+// newTestServer builds the server's real routes from the constructors
+// cmd/pixad uses, with a throwaway state directory. Debug marks requests
+// as plain HTTP, so the CSRF check runs without an https Referer.
+func newTestServer(t *testing.T) *Server {
+	t.Helper()
+
+	stateDir := t.TempDir()
+	cfg := &config.Config{
+		Debug:             true,
+		SigningKey:        testSigningKey,
+		StateDir:          stateDir,
+		DBURL:             "file:" + filepath.Join(stateDir, "state.sqlite3"),
+		TrustedProxies:    []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		DownstreamTimeout: config.DefaultDownstreamTimeout,
+	}
+
+	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)
+	}
+
+	hc, err := healthcheck.New(lc, healthcheck.Params{
+		Globals: &globals.Globals{}, Config: cfg, Logger: log, Database: db,
+	})
+	if err != nil {
+		t.Fatalf("healthcheck.New() error = %v", err)
+	}
+
+	h, err := handlers.New(lc, handlers.Params{
+		Logger: log, Healthcheck: hc, Database: db, Config: cfg,
+	})
+	if err != nil {
+		t.Fatalf("handlers.New() error = %v", err)
+	}
+
+	mw, err := middleware.New(lc, middleware.Params{Logger: log, Config: cfg})
+	if err != nil {
+		t.Fatalf("middleware.New() error = %v", err)
+	}
+
+	lc.RequireStart()
+	t.Cleanup(lc.RequireStop)
+
+	s := &Server{config: cfg, mw: mw, h: h}
+	s.SetupRoutes()
+
+	return s
+}
+
+// clientRequest builds a request for / arriving from remoteAddr, carrying
+// forwardedFor as its X-Forwarded-For header when that is not empty.
+func clientRequest(
+	t *testing.T, method string, body io.Reader, remoteAddr, forwardedFor string,
+) *http.Request {
+	t.Helper()
+
+	req := httptest.NewRequestWithContext(t.Context(), method, "/", body)
+	req.RemoteAddr = remoteAddr
+
+	if forwardedFor != "" {
+		req.Header.Set("X-Forwarded-For", forwardedFor)
+	}
+
+	return req
+}
+
+// postLogin loads the login form with GET / and submits key in it with
+// POST /, as a browser does, both from the same client. GET / is not rate
+// limited, so the form must load even for a client over the limit.
+func postLogin(
+	t *testing.T, s *Server, remoteAddr, forwardedFor, key string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	page := httptest.NewRecorder()
+	s.ServeHTTP(page,
+		clientRequest(t, http.MethodGet, nil, remoteAddr, forwardedFor))
+
+	if page.Code != http.StatusOK {
+		t.Fatalf("GET / status = %d, want %d", page.Code, http.StatusOK)
+	}
+
+	match := csrfFieldPattern.FindStringSubmatch(page.Body.String())
+	if match == nil {
+		t.Fatalf("no CSRF token field found in the login form")
+	}
+
+	form := url.Values{"key": {key}, "gorilla.csrf.Token": {match[1]}}
+	req := clientRequest(t, http.MethodPost,
+		strings.NewReader(form.Encode()), remoteAddr, forwardedFor)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	for _, c := range page.Result().Cookies() {
+		req.AddCookie(c)
+	}
+
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, req)
+
+	return rec
+}
+
+// tripLoginRateLimit makes LoginAttemptsPerMinute failed logins from one
+// client, each answered with the login form again, then one more, which
+// must be refused with 429. It returns the response to that last attempt.
+func tripLoginRateLimit(
+	t *testing.T, s *Server, remoteAddr, forwardedFor string,
+) *httptest.ResponseRecorder {
+	t.Helper()
+
+	for attempt := range LoginAttemptsPerMinute {
+		rec := postLogin(t, s, remoteAddr, forwardedFor, wrongKey)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("failed login %d status = %d, want %d",
+				attempt+1, rec.Code, http.StatusOK)
+		}
+	}
+
+	rec := postLogin(t, s, remoteAddr, forwardedFor, wrongKey)
+	if rec.Code != http.StatusTooManyRequests {
+		t.Fatalf("login over the limit status = %d, want %d",
+			rec.Code, http.StatusTooManyRequests)
+	}
+
+	return rec
+}
+
+// TestLoginRateLimitRefusesAttemptOverLimit verifies the login attempt
+// after LoginAttemptsPerMinute failed ones from one client is refused with
+// 429 and a Retry-After header, and that the client cannot get around the
+// limit by sending X-Forwarded-For: from a peer that is not a trusted
+// proxy, the header is ignored.
+func TestLoginRateLimitRefusesAttemptOverLimit(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	rec := tripLoginRateLimit(t, s, firstClient, "")
+
+	retryAfter := rec.Header().Get("Retry-After")
+
+	seconds, err := strconv.Atoi(retryAfter)
+	if err != nil || seconds <= 0 {
+		t.Errorf("Retry-After = %q, want a positive number of seconds",
+			retryAfter)
+	}
+
+	rec = postLogin(t, s, firstClient, secondForwarded, wrongKey)
+	if rec.Code != http.StatusTooManyRequests {
+		t.Errorf("login with X-Forwarded-For from an untrusted peer "+
+			"status = %d, want %d", rec.Code, http.StatusTooManyRequests)
+	}
+}
+
+// TestLoginRateLimitLeavesOtherClientsAlone verifies one client going over
+// the limit does not limit another: a failed login from a different
+// address is answered with the login form, and the signing key still logs
+// it in.
+func TestLoginRateLimitLeavesOtherClientsAlone(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	tripLoginRateLimit(t, s, firstClient, "")
+
+	rec := postLogin(t, s, secondClient, "", wrongKey)
+	if rec.Code != http.StatusOK {
+		t.Errorf("failed login from another client status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+
+	rec = postLogin(t, s, secondClient, "", testSigningKey)
+	if rec.Code != http.StatusSeeOther {
+		t.Errorf("login with the signing key from another client "+
+			"status = %d, want %d", rec.Code, http.StatusSeeOther)
+	}
+}
+
+// TestLoginRateLimitCountsClientsBehindProxySeparately verifies the limit
+// counts the client address resolved from X-Forwarded-For, not the address
+// of the trusted proxy the requests arrive from, so two clients behind the
+// same proxy are counted separately.
+func TestLoginRateLimitCountsClientsBehindProxySeparately(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	tripLoginRateLimit(t, s, proxyPeer, firstForwarded)
+
+	rec := postLogin(t, s, proxyPeer, secondForwarded, wrongKey)
+	if rec.Code != http.StatusOK {
+		t.Errorf("failed login from a second client behind the proxy "+
+			"status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+// TestLoginRateLimitCountsIPv6ClientsByPrefix verifies an IPv6 client is
+// counted by its /64: another address in the same /64 is refused too,
+// while an address in a different /64 is not.
+func TestLoginRateLimitCountsIPv6ClientsByPrefix(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	tripLoginRateLimit(t, s, proxyPeer, "2001:db8::1")
+
+	rec := postLogin(t, s, proxyPeer, "2001:db8::2", wrongKey)
+	if rec.Code != http.StatusTooManyRequests {
+		t.Errorf("login from the same /64 status = %d, want %d",
+			rec.Code, http.StatusTooManyRequests)
+	}
+
+	rec = postLogin(t, s, proxyPeer, "2001:db8:0:1::1", wrongKey)
+	if rec.Code != http.StatusOK {
+		t.Errorf("login from another /64 status = %d, want %d",
+			rec.Code, http.StatusOK)
+	}
+}
+
+// TestLoginRateLimitCountsIPv4MappedClientsSeparately verifies an IPv4
+// client that the proxy forwards in IPv4-mapped IPv6 form (::ffff:a.b.c.d)
+// is counted by its IPv4 address, not by the /64 that every such address
+// shares, so two of them behind the proxy are counted separately.
+func TestLoginRateLimitCountsIPv4MappedClientsSeparately(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+
+	tripLoginRateLimit(t, s, proxyPeer, "::ffff:"+firstForwarded)
+
+	rec := postLogin(t, s, proxyPeer, "::ffff:"+secondForwarded, wrongKey)
+	if rec.Code != http.StatusOK {
+		t.Errorf("failed login from a second IPv4-mapped client "+
+			"status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}

internal/server/maintenance_internal_test.go

@@ -0,0 +1,173 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+
+	"sneak.berlin/go/pixa/internal/healthcheck"
+)
+
+// unsignedImagePath is an image URL that carries no signature.
+const unsignedImagePath = "/v1/image/cdn.example.com/cat.jpg/100x100.jpeg"
+
+// encryptedImagePath is an encrypted image URL whose token cannot be
+// decrypted.
+const encryptedImagePath = "/v1/e/token/cat.jpg"
+
+// TestMaintenanceModeRefusesImageRequests verifies that while maintenance
+// mode is on, both image routes answer 503 Service Unavailable with a
+// Retry-After header and the JSON error body the image handlers send.
+func TestMaintenanceModeRefusesImageRequests(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+	s.config.MaintenanceMode = true
+
+	requests := []struct {
+		method string
+		path   string
+	}{
+		{http.MethodGet, unsignedImagePath},
+		{http.MethodHead, unsignedImagePath},
+		{http.MethodGet, encryptedImagePath},
+	}
+
+	for _, tc := range requests {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			s.ServeHTTP(rec, httptest.NewRequestWithContext(
+				t.Context(), tc.method, tc.path, nil))
+			t.Logf("status %d, body %s", rec.Code, rec.Body.String())
+
+			if rec.Code != http.StatusServiceUnavailable {
+				t.Fatalf("status = %d, want %d",
+					rec.Code, http.StatusServiceUnavailable)
+			}
+
+			retryAfter := rec.Header().Get("Retry-After")
+
+			seconds, err := strconv.Atoi(retryAfter)
+			if err != nil || seconds <= 0 {
+				t.Errorf("Retry-After = %q, want a positive number of seconds",
+					retryAfter)
+			}
+
+			// A HEAD response carries no body.
+			if tc.method == http.MethodHead {
+				return
+			}
+
+			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("body is not JSON: %v", err)
+			}
+
+			if body.Error == "" || body.Status != http.StatusServiceUnavailable ||
+				body.Timestamp == "" {
+				t.Errorf("body = %+v, want an error, status %d and a timestamp",
+					body, http.StatusServiceUnavailable)
+			}
+		})
+	}
+}
+
+// TestImageRequestsServedWithoutMaintenanceMode verifies that while
+// maintenance mode is off, image requests reach the image handlers instead
+// of the 503. The handlers refuse an unsigned image URL with 401 and a token
+// they cannot decrypt with 400, so either status shows a request got through.
+func TestImageRequestsServedWithoutMaintenanceMode(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+	s.config.MaintenanceMode = false
+
+	requests := []struct {
+		method string
+		path   string
+		want   int
+	}{
+		{http.MethodGet, unsignedImagePath, http.StatusUnauthorized},
+		{http.MethodHead, unsignedImagePath, http.StatusUnauthorized},
+		{http.MethodGet, encryptedImagePath, http.StatusBadRequest},
+	}
+
+	for _, tc := range requests {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			s.ServeHTTP(rec, httptest.NewRequestWithContext(
+				t.Context(), tc.method, tc.path, nil))
+			t.Logf("status %d, body %s", rec.Code, rec.Body.String())
+
+			if rec.Code != tc.want {
+				t.Errorf("status = %d, want %d from the image handler",
+					rec.Code, tc.want)
+			}
+		})
+	}
+}
+
+// TestMaintenanceModeKeepsOtherRoutes verifies that while maintenance mode
+// is on, the health check still answers 200 and reports it, and the login
+// page and /metrics still answer 200. The image's Docker HEALTHCHECK
+// requests the health check: a 503 there would make the container
+// unhealthy, and upaas marks a deploy failed when its container is
+// unhealthy.
+func TestMaintenanceModeKeepsOtherRoutes(t *testing.T) {
+	t.Parallel()
+
+	s := newTestServer(t)
+	s.config.MaintenanceMode = true
+
+	// /metrics is routed only when its username is set.
+	s.config.MetricsUsername = "metrics"
+	s.config.MetricsPassword = "metrics-password"
+	s.SetupRoutes()
+
+	rec := httptest.NewRecorder()
+	s.ServeHTTP(rec, httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/.well-known/healthcheck.json", nil))
+	t.Logf("health check status %d, body %s", rec.Code, rec.Body.String())
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("health check status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var health healthcheck.Response
+
+	err := json.NewDecoder(rec.Body).Decode(&health)
+	if err != nil || !health.Maintenance {
+		t.Errorf("health check maintenance_mode = %v (error %v), want true",
+			health.Maintenance, err)
+	}
+
+	rec = httptest.NewRecorder()
+	s.ServeHTTP(rec, clientRequest(t, http.MethodGet, nil, firstClient, ""))
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("login page status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	req := httptest.NewRequestWithContext(t.Context(),
+		http.MethodGet, "/metrics", nil)
+	req.SetBasicAuth(s.config.MetricsUsername, s.config.MetricsPassword)
+
+	rec = httptest.NewRecorder()
+	s.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Errorf("/metrics status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}

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

@@ -1,22 +1,35 @@
 package server
 
 import (
+	"encoding/json"
 	"net/http"
+	"strconv"
+	"time"
 
 	sentryhttp "github.com/getsentry/sentry-go/http"
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
 
+	"sneak.berlin/go/pixa/internal/handlers"
 	"sneak.berlin/go/pixa/internal/static"
 )
 
+// LoginAttemptsPerMinute is how many login attempts (POST /) one client may
+// make per minute; the next is refused with 429 Too Many Requests.
+const LoginAttemptsPerMinute = 5
+
+// MaintenanceRetryAfterSeconds is the Retry-After, in seconds, sent with
+// the 503 that the image routes answer while maintenance mode is on.
+const MaintenanceRetryAfterSeconds = 300
+
 // SetupRoutes configures all HTTP routes.
 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())
 
@@ -25,8 +38,7 @@ func (s *Server) SetupRoutes() {
 		s.router.Use(s.mw.Metrics())
 	}
 
-	s.router.Use(s.mw.CORS())
+	s.router.Use(middleware.Timeout(s.config.DownstreamTimeout))
-	s.router.Use(middleware.Timeout(HTTPWriteTimeout))
 
 	if s.sentryEnabled {
 		sentryHandler := sentryhttp.New(sentryhttp.Options{
@@ -41,24 +53,53 @@ 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
+	// Login/generator UI. The form routes carry CSRF protection; the
-	s.router.Get("/", s.h.HandleRoot())
+	// token cookie is independent of the session cookie, so it also
-	s.router.Post("/", s.h.HandleRoot())
+	// covers the login POST, where no session exists yet. LimitBody caps
+	// the POST body ahead of CSRF, which reads its token from that body.
+	// The login POST is rate limited per client after both, so every
+	// attempt that reaches the signing key comparison is counted.
+	s.router.Group(func(r chi.Router) {
+		r.Use(s.h.LimitBody(handlers.MaxFormBytes))
+		r.Use(s.h.CSRF())
+		r.Get("/", s.h.HandleRoot())
+		r.With(s.mw.RateLimit(LoginAttemptsPerMinute, time.Minute)).
+			Post("/", s.h.HandleRoot())
+		r.Post("/generate", s.h.HandleGenerateURL())
+	})
+
 	s.router.Get("/logout", s.h.HandleLogout())
-	s.router.Post("/generate", s.h.HandleGenerateURL())
 
-	// Main image proxy route
+	// Image routes, the only ones that send CORS headers, as pages on other
-	// /v1/image/<host>/<path>/<width>x<height>.<format>
+	// sites read them. They are a subrouter rather than a group: a group's
-	s.router.Get("/v1/image/*", s.h.HandleImage())
+	// middleware runs only for a request that matches one of its routes,
-	s.router.Head("/v1/image/*", s.h.HandleImage())
+	// and a browser's preflight OPTIONS request matches none, so the CORS
+	// middleware could not answer it.
+	s.router.Route("/v1", func(r chi.Router) {
+		r.Use(s.mw.CORS())
 
-	// Encrypted image URL route
+		// Refused while maintenance mode is on. Only these: the image's
-	// The trailing filename (e.g., /img.jpg) is ignored but helps
+		// Docker HEALTHCHECK requests the health check, a 503 there would
-	// browsers with content type
+		// make the container unhealthy, and upaas marks a deploy failed
-	s.router.Get("/v1/e/{token}/*", s.h.HandleImageEnc())
+		// when its container is unhealthy.
+		r.Group(func(r chi.Router) {
+			r.Use(s.refuseDuringMaintenance)
+
+			// Main image proxy route
+			// /v1/image/<host>/<path>/<width>x<height>.<format>
+			r.Get("/image/*", s.h.HandleImage())
+			r.Head("/image/*", s.h.HandleImage())
+
+			// Encrypted image URL route
+			// 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())
+		})
+	})
 
 	// Metrics endpoint with auth
 	if s.config.MetricsUsername != "" {
@@ -68,3 +109,30 @@ func (s *Server) SetupRoutes() {
 		})
 	}
 }
+
+// refuseDuringMaintenance answers a request with 503 Service Unavailable,
+// a Retry-After header and a JSON error body while maintenance mode is on,
+// and passes it on otherwise. The body has the fields of the JSON errors
+// the image handlers send.
+func (s *Server) refuseDuringMaintenance(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !s.MaintenanceMode() {
+			next.ServeHTTP(w, r)
+
+			return
+		}
+
+		w.Header().Set("Retry-After", strconv.Itoa(MaintenanceRetryAfterSeconds))
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusServiceUnavailable)
+
+		err := json.NewEncoder(w).Encode(map[string]any{
+			"error":     "down for maintenance, try again later",
+			"status":    http.StatusServiceUnavailable,
+			"timestamp": time.Now().UTC().Format(time.RFC3339),
+		})
+		if err != nil {
+			s.log.Error("json encode error", "error", err)
+		}
+	})
+}