One image request type instead of five (closes #307)

The new package internal/imagerequest holds the request type, its two
parts Source and Transform, the Format and Fit types, the dimension and
fit checks, the /v1/image/ path parsing and the variant key; it imports
no other package of pixa. imgcache.ParsedURL, imgcache.ImageRequest,
signature.Request, imageprocessor.Request, the second Size, format and
fit types and the conversions between them are gone. The image
processor takes a Transform only. encurl keeps a private struct with the
token's CBOR field names, so tokens made before still decode. VariantKey
moves with the function that makes it. Tests follow the moved and
renamed code; the tests of the removed conversions go with them.

Model: opus-5-5

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-smoke docker-versioned docker-test devserver devserver-stop hooks loadtest bench
+.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-smoke docker-versioned docker-test devserver devserver-stop hooks loadtest
 
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS := -X main.Version=$(VERSION)
@@ -64,12 +64,6 @@ docker-smoke:
 loadtest:
 	@script/loadtest
 
-# Serve cache hits in parallel through the image handler and report hits per
-# second (needs Go on the host after `script/bootstrap --cgo`, not Docker; a
-# benchmark, not part of check)
-bench:
-	@script/bench
-
 # Build Docker image as `make docker` does, and also tag it pixa:$(VERSION)
 docker-versioned:
 	@script/docker

README.md

@@ -76,7 +76,8 @@ database and the disk cache:
   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 and files still being written come on top, and eviction runs in 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
@@ -88,17 +89,13 @@ 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. The requests in progress
+On SIGTERM or SIGINT pixa stops accepting connections, gives the requests in
-and the images being processed get 5 seconds to finish. A request not finished
+progress and the images being processed 5 seconds to finish, then writes to the
-by then is cut off. pixa then writes the waiting last-used times of cached
+database the counts of cache hits, misses, fetches and conversions that requests
-images to the database (see Storage) and exits. It exits with 1 when:
+could not write by their deadline, and exits: with 0, or with 1 when images were
-
+still being processed after those 5 seconds, some of those counts could not be
-- images were still being processed after those 5 seconds,
+written, or another part of pixa failed to stop. A request not finished by then
-- some of those times could not be written, or
+is cut off. `docker stop` waits 10 seconds before it kills the container.
-- another part of pixa failed to stop.
-
-Otherwise it exits with 0. `docker stop` waits 10 seconds before it kills the
-container.
 
 Outside Docker, pixa needs libvips (the image has 8.16) and libheif to run, as
 it uses libvips through CGO. pixad does not start unless libvips has its JPEG XL
@@ -180,46 +177,38 @@ allowlisted source hosts for open access.
 
 ### Storage
 
-- **Source images**:
+- **Source content**:
-  `<state_dir>/cache/sources/<ab>/<cd>/<sha256 of host, path and query>`, one
+  `<state_dir>/cache/sources/<ab>/<cd>/<sha256 of source content>`
-  file for each source URL
+- **Source metadata**:
+  `<state_dir>/cache/metadata/<hostname>/<sha256 of path and query>.json` (host,
+  path and query, content hash, upstream status and headers, fetch time)
 - **Database**: `<state_dir>/state.sqlite3` (SQLite)
 - **Transformed images**:
-  `<state_dir>/cache/variants/<ab>/<cd>/<sha256 of host, path, query, size, format, quality and fit>`
+  `<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.
 
-Each source image and each transformed image has one row in the database,
+Multiple source paths may reference the same content blob; the database tracks
-holding its size and when it was last used. Two source URLs that serve the same
+references rather than using filesystem refcounting.
-bytes are stored twice, once under each URL. A source image is stored by writing
-its file and then its row; when the row cannot be written, the file is removed
-again.
 
-Source and transformed image files are written under a temporary name, synced to
+Source and transformed image files, and the `.meta` file beside each transformed
-disk, and only then renamed into place, so a crash leaves no file under its own
+image, are written under a temporary name, synced to disk, and only then renamed
-name with part of its data. When pixa starts, and every five minutes after, it
+into place, so a crash leaves no file under its own name with part of its data.
-removes each cached source or transformed image whose file is empty, or not the
+When pixa starts, and every five minutes after, it removes each cached source or
-size the database records for it, with a warning naming the file; the next
+transformed image whose file is empty, or not the size the database records for
-request for it fetches the source or converts the image again. Looking for those
+it, with a warning naming the file; the next request for it fetches the source
-files reads the database once for every cached file, so pixa skips each
+or converts the image again. Looking for those files reads the database once for
-five-minute look that would start less than ten times as long after the last
+every cached file, so pixa skips each five-minute look that would start less
-look ended as that look took. After a look that took one minute, the next one
+than ten times as long after the last look ended as that look took. After a look
-starts 10 to 15 minutes after that look ended.
+that took one minute, the next one starts 10 to 15 minutes after that look
+ended.
 
 pixa's target is 1-5k r/s, which has not been measured at that rate (see Load
-Test). Toward it, a cache hit opens the transformed image's file and nothing
+Test). Toward it, pixa keeps in memory the content types of the 10,000
-else, and makes no database call. The content type comes from the file's first
+transformed images most recently cached or served, so a cache hit on one of them
-bytes, which are those of the format pixa wrote it in; a file whose first bytes
+reads only the image file from disk and not the metadata file stored beside it.
-are not those of a format pixa writes is not served, and the image is converted
-again. A hit hands the time it was served to a background writer and does not
-wait for the writer. Eviction orders by that time. The hit is counted in memory.
-A miss that uses a cached source image also hands that writer the time it used
-the image. Once a second that writer writes the waiting times in one
-transaction. While 10,000 times of transformed images, or 10,000 of source
-images, wait to be written, a further one is dropped, and that image only looks
-less recently used to eviction. `script/bench` measures how many hits pixa
-serves per second (see Load Test).
 
 ### Routes
 
@@ -817,27 +806,15 @@ See `configs/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, at `/metrics`. pixa serves `/metrics` and measures
+- **Metrics**: Prometheus, at `/metrics`: generic HTTP request metrics
-  HTTP requests only when `metrics.username` and `metrics.password` are set.
+  (duration, response size, requests in flight) and the Go runtime and process
-  `/metrics` holds:
+  metrics; requests are measured and `/metrics` is served only when
-    - the duration of HTTP requests
+  `metrics.username` and `metrics.password` are set. A request's `handler` label
-    - the size of HTTP responses
+  is the pattern of the route it matches, such as `/v1/image/*`, never its path.
-    - the HTTP requests in flight
+  Requests that match no route share the label `unmatched`: those the router
-    - the Go runtime and process metrics
+  answers 404 or 405, and CORS preflights. A request's `method` label is its
-    - `pixa_cache_hits_total`: image requests served from the cache
+  method when that is `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`,
-    - `pixa_cache_misses_total`: image requests not served from the cache
+  `OPTIONS`, `CONNECT` or `TRACE`, and `other` for any other method
-    - `pixa_upstream_fetches_total`: fetches of a source image that read any
-      bytes
-    - `pixa_upstream_fetch_bytes_total`: the bytes those fetches read
-    - `pixa_transforms_total`: images converted
-
-    A request's `handler` label is the pattern of the route it matches, such as
-    `/v1/image/*`, never its path. Requests that match no route share the label
-    `unmatched`: those the router answers 404 or 405, and CORS preflights. A
-    request's `method` label is its method when that is `GET`, `HEAD`, `POST`,
-    `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `CONNECT` or `TRACE`, and `other` for
-    any other method.
-
 - **Logging**: stdlib slog
 
 ## Entrypoints
@@ -869,9 +846,6 @@ provide:
 - `script/docker-smoke` — build the image, start it, wait for it to be healthy
 - `script/loadtest` — measure pixad's throughput, latency and peak memory; a
   benchmark, not part of `script/check` (see Load Test)
-- `script/bench` — run the Go benchmark that serves cache hits in parallel
-  through the image handler, with Go on the host after `script/bootstrap --cgo`;
-  a benchmark, not part of `script/check` (see Load Test)
 - `script/cibuild` — CI entrypoint: run `script/bootstrap` (without `--cgo`),
   then `script/check`, then build the image as `script/docker` does
 - `script/precommit` — pre-commit checks (`go mod tidy` guard, then
@@ -952,17 +926,6 @@ The numbers depend on the machine and on whatever else runs on it. The first
 measurement, made on a shared machine with few clients, is in `TODO.md`; it says
 nothing about the target.
 
-`script/bench` (or `make bench`) measures cache hits alone, without the network
-and with no pixad process: a Go benchmark in `internal/handlers` serves one
-cached image through the `/v1/image/` handler from as many goroutines at once as
-the machine has CPUs, and reports the hits served per second as `hits/s`. Each
-run starts with an empty cache and an empty database, a SQLite file of its own,
-and puts the image in the cache before it measures. The benchmark fails if
-serving the hits ran any statement on the database. Like the load test it is not
-part of `script/check`. It runs Go on the host, as the load test does, and
-compiles pixa there, so it needs the C compiler and libraries that
-`script/bootstrap --cgo` installs, but not Docker.
-
 ## TODO
 
 See [TODO.md](TODO.md) for the full prioritized task list.

TODO.md

@@ -30,68 +30,6 @@ P2: security: per-origin rate limiting
 
 # Completed Steps
 
-- 2026-10-26 the code nothing in production called is gone (closes #312). The
-  handlers tests sign their image URLs with `generateSignedURL`, a test helper
-  that writes them as the removed generator did. Removed:
-    - `Service.Warm` and the `ImageCache` interface
-    - `Service.GenerateSignedURL` and `Signer.GenerateSignedURL`
-    - `signature.ParseParams`
-    - `imagerequest.ParseImagePath`
-    - `PeekAndValidate`, `IsSupportedMIMEType`, `ImageFormatToMIME` and
-      `FormatOriginal` of `internal/magic`
-    - `SupportedInputFormats` and `SupportedOutputFormats` of the image
-      processor
-    - `IsEmpty` and `Count` of the allowlist
-    - `ssrfSafeDialer`
-    - `CacheStale`, `ErrCacheMiss`, `ErrNegativeCache` and
-      `ImageResponse.LastModified`
-    - `ContentStorage.Load` and `VariantStorage.Load`
-- 2026-10-26 cache hits, misses, upstream fetches, the bytes those fetches read
-  and transforms are counted as Prometheus counters in memory (closes #311).
-  They are `pixa_cache_hits_total`, `pixa_cache_misses_total`,
-  `pixa_upstream_fetches_total`, `pixa_upstream_fetch_bytes_total` and
-  `pixa_transforms_total`, fields of the cache. `NewCache` makes them and
-  registers them on the registry it is given (`internal/imgcache/counters.go`).
-  pixad gives it Prometheus' default registry, which `/metrics` serves; each
-  test gives it a new one. The `Increment` methods add to their cache's
-  counters. `cache_stats`, `Cache.Stats`, `Service.Stats`, `CacheStats` and the
-  pending counts are gone. The background goroutine writes only access times
-  now: `StartPendingAccessTimeWrites` starts it and
-  `StopPendingAccessTimeWrites` stops it, in `pendingaccesstimes.go`.
-- 2026-10-21 the schema file declares only the tables and columns pixa writes
-  and reads (closes #310): `output_content` and `request_cache` are gone, and so
-  are the columns nothing read: the host, path, query, `content_type` and
-  `fetched_at` of `source_content`, the `content_type` and `created_at` of
-  `variant_content`, and the `status_code`, `error_message` and `fetched_at` of
-  `negative_cache`. `StoreSource` no longer takes the fetch result,
-  `LookupSource` returns only the source key, `StoreVariant` no longer takes a
-  content type, `StoreNegative` no longer takes a status code or message, and
-  reconciliation adopts a variant file without reading its first bytes.
-- 2026-10-21 a cache hit makes no database call (closes #309): `Service.Get`
-  opens the variant file with `Cache.GetVariant` and nothing else, with no
-  existence check first. The content type comes from the file's first bytes; a
-  file whose first bytes are not those of an output format, SVG included, is a
-  miss, and the variant is made again. A hit hands its access time to a channel
-  that holds up to 10,000 and drops the rest, and its hit count to the pending
-  counts, without waiting; every count is now a pending count. A miss that finds
-  a cached source hands that source's access time to a second such channel. The
-  goroutine `StartPendingCountWrites` starts writes, once a second, the access
-  times in one transaction and the counts in one `UPDATE`;
-  `StopPendingCountWrites` writes what is left once at shutdown and logs
-  separately the access times and the counts it could not write.
-  `checkNegativeCache` no longer deletes an expired row; `CleanExpired` in the
-  eviction goroutine does. The `.meta` files, `VariantMeta`, `LoadWithMeta`,
-  `variantContentTypeFromSidecar`, `metaCache`, `Lookup` and `golang-lru` are
-  gone. `make bench` (`script/bench`) runs `BenchmarkHandleImage_CacheHits` with
-  Go on the host after `script/bootstrap --cgo`, outside `make check`.
-- 2026-10-21 a source is stored the way a variant is (closes #308): one
-  `source_content` row and one file per source URL, the file named by the
-  source's `SourceKey`, the SHA-256 of its host, path and query made as the
-  variant key is, under `cache/sources/`. A store writes the file, then the row,
-  and removes the file when the row cannot be written; an eviction deletes the
-  row, then the file, with no lock and no transaction. `source_metadata`, the
-  JSON files under `cache/metadata/`, `MetadataStorage` and the content lock are
-  gone. Two source URLs that serve the same bytes now store them twice.
 - 2026-10-21 one image request type instead of five (closes #307): the new
   package `internal/imagerequest`, which imports no other package of pixa, holds
   `imagerequest.Request` with its two parts, `Source` (host, path and query) and

go.mod

@@ -14,6 +14,7 @@ require (
 	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.sum

@@ -228,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=

internal/allowlist/allowlist.go

@@ -72,3 +72,13 @@ func (w *HostAllowList) IsAllowed(u *url.URL) bool {
 
 	return false
 }
+
+// IsEmpty returns true if the allow list has no entries.
+func (w *HostAllowList) IsEmpty() bool {
+	return len(w.exactHosts) == 0 && len(w.suffixHosts) == 0
+}
+
+// Count returns the total number of allow list entries.
+func (w *HostAllowList) Count() int {
+	return len(w.exactHosts) + len(w.suffixHosts)
+}

internal/allowlist/allowlist_test.go

@@ -139,3 +139,87 @@ func TestHostAllowList_IsAllowed_SuffixMatch(t *testing.T) {
 		},
 	})
 }
+
+func TestHostAllowList_IsEmpty(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		patterns []string
+		want     bool
+	}{
+		{
+			name:     "empty",
+			patterns: []string{},
+			want:     true,
+		},
+		{
+			name:     "nil",
+			patterns: nil,
+			want:     true,
+		},
+		{
+			name:     "whitespace only",
+			patterns: []string{"  ", ""},
+			want:     true,
+		},
+		{
+			name:     "has entries",
+			patterns: []string{"example.com"},
+			want:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			w := allowlist.New(tt.patterns)
+			if got := w.IsEmpty(); got != tt.want {
+				t.Errorf("IsEmpty() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestHostAllowList_Count(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		patterns []string
+		want     int
+	}{
+		{
+			name:     "empty",
+			patterns: []string{},
+			want:     0,
+		},
+		{
+			name:     "exact hosts only",
+			patterns: []string{"a.com", "b.com", "c.com"},
+			want:     3,
+		},
+		{
+			name:     "suffix hosts only",
+			patterns: []string{".a.com", ".b.com"},
+			want:     2,
+		},
+		{
+			name:     "mixed",
+			patterns: []string{"exact.com", ".suffix.com"},
+			want:     2,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			w := allowlist.New(tt.patterns)
+			if got := w.Count(); got != tt.want {
+				t.Errorf("Count() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

internal/app/app.go

@@ -7,7 +7,6 @@ import (
 	"os/signal"
 	"syscall"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"github.com/spf13/cobra"
 	"go.uber.org/fx"
 	"sneak.berlin/go/pixa/internal/config"
@@ -62,8 +61,6 @@ func run(_ *cobra.Command, _ []string) {
 			server.New,
 			middleware.New,
 			healthcheck.New,
-			// The registry /metrics serves
-			func() prometheus.Registerer { return prometheus.DefaultRegisterer },
 		),
 		fx.Invoke(
 			func(log *logger.Logger) { log.Identify() },

internal/database/concurrent_writes_internal_test.go

@@ -104,31 +104,40 @@ func writeConcurrently(t *testing.T, db *sql.DB) {
 
 	wg.Wait()
 
-	var sources int
+	var hits, sources int
 
-	err := db.QueryRowContext(ctx, `SELECT COUNT(*) FROM source_content`).
+	err := db.QueryRowContext(ctx, `
-		Scan(&sources)
+		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 sources != totalRequests {
+	if hits != totalRequests || sources != totalRequests {
-		t.Errorf("%d source_content rows, want %d", 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 stores a source, records a transformed image and deletes that
+// make: it counts a cache hit, stores a source, records a transformed image
-// record again.
+// and deletes that record again.
 func writeLikeOneRequest(ctx context.Context, db *sql.DB, key string) error {
-	_, err := db.ExecContext(ctx, `INSERT INTO source_content
+	_, err := db.ExecContext(ctx,
-		(source_key, size_bytes) VALUES (?, 1)`, key)
+		`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) VALUES (?, 1)`, key)
+		(cache_key, size_bytes, content_type) VALUES (?, 1, 'image/png')`, key)
 	if err != nil {
 		return fmt.Errorf("recording a transformed image: %w", err)
 	}

internal/database/database_internal_test.go

@@ -159,7 +159,10 @@ func TestApplyMigrations_CreatesSchemaAndTables(t *testing.T) {
 	}
 
 	// Verify that the application tables created by 001.sql exist.
-	tables := []string{"source_content", "negative_cache"}
+	tables := []string{
+		"source_content", "source_metadata", "output_content",
+		"request_cache", "negative_cache", "cache_stats",
+	}
 	for _, table := range tables {
 		var count int
 

internal/db/migrations/001_schema.sql

@@ -1,27 +1,52 @@
 -- Migration 001: Initial schema
 -- Creates all tables for the pixa caching image proxy
 
--- Source images, one row per source URL
+-- Source content blobs
--- Files stored at: cache/sources/<ab>/<cd>/<source_key>, where source_key
+-- Files stored at: cache/sources/<ab>/<cd>/<sha256>
--- is the SHA-256 of the source's host, path and query
 CREATE TABLE IF NOT EXISTS source_content (
-    source_key TEXT PRIMARY KEY,
+    content_hash TEXT PRIMARY KEY,
+    content_type TEXT NOT NULL,
     size_bytes INTEGER NOT NULL,
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 CREATE INDEX IF NOT EXISTS idx_source_content_last_accessed
     ON source_content(last_accessed_at);
 
+-- Source URL metadata - maps URLs to content hashes
+-- JSON stored at: cache/metadata/<hostname>/<path_hash>.json
+CREATE TABLE IF NOT EXISTS source_metadata (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_host TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    source_query TEXT NOT NULL DEFAULT '',
+    path_hash TEXT NOT NULL,
+    content_hash TEXT,
+    status_code INTEGER NOT NULL,
+    content_type TEXT,
+    response_headers TEXT,
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    expires_at DATETIME,
+    etag TEXT,
+    last_modified TEXT,
+    UNIQUE(source_host, source_path, source_query),
+    FOREIGN KEY (content_hash) REFERENCES source_content(content_hash)
+);
+CREATE INDEX IF NOT EXISTS idx_source_meta_host ON source_metadata(source_host);
+CREATE INDEX IF NOT EXISTS idx_source_meta_path_hash ON source_metadata(path_hash);
+CREATE INDEX IF NOT EXISTS idx_source_meta_expires ON source_metadata(expires_at);
+CREATE INDEX IF NOT EXISTS idx_source_meta_content_hash ON source_metadata(content_hash);
+
 -- Processed variant blobs
--- Files stored at: cache/variants/<ab>/<cd>/<cache_key>. Tracked here
+-- Files stored at: cache/variants/<ab>/<cd>/<cache_key> (plus a .meta
--- (like source content blobs above) so total cache usage is known
+-- sidecar with the content type). Tracked here (like source content
--- without a directory scan, and so LRU eviction has a timestamp to order
+-- blobs above) so total cache usage is known without a directory scan,
--- on. A cache hit does not read this table: it takes the content type
+-- and so LRU eviction has a timestamp to order on.
--- from the file's first bytes, and its last_accessed_at is written
--- later, in a batch.
 CREATE TABLE IF NOT EXISTS variant_content (
     cache_key TEXT PRIMARY KEY,
     size_bytes INTEGER NOT NULL,
+    content_type TEXT NOT NULL,
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
     last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 CREATE INDEX IF NOT EXISTS idx_variant_content_last_accessed
@@ -95,19 +120,63 @@ BEGIN
     WHERE id = 1;
 END;
 
--- Negative cache: source URLs whose fetch failed with an upstream error
+-- Output/transformed content blobs
--- status, or whose first bytes did not match their Content-Type. pixa does
+-- Not written: transformed images are stored in cache/variants and
--- not fetch such a URL again until its row expires.
+-- tracked in variant_content above.
+CREATE TABLE IF NOT EXISTS output_content (
+    content_hash TEXT PRIMARY KEY,
+    content_type TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL,
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Request cache - maps full request params to output content
+CREATE TABLE IF NOT EXISTS request_cache (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    cache_key TEXT NOT NULL UNIQUE,
+    source_metadata_id INTEGER NOT NULL,
+    output_hash TEXT NOT NULL,
+    width INTEGER NOT NULL,
+    height INTEGER NOT NULL,
+    format TEXT NOT NULL,
+    quality INTEGER NOT NULL DEFAULT 85,
+    fit_mode TEXT NOT NULL DEFAULT 'cover',
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    access_count INTEGER NOT NULL DEFAULT 1,
+    FOREIGN KEY (source_metadata_id) REFERENCES source_metadata(id),
+    FOREIGN KEY (output_hash) REFERENCES output_content(content_hash)
+);
+CREATE INDEX IF NOT EXISTS idx_request_cache_key ON request_cache(cache_key);
+CREATE INDEX IF NOT EXISTS idx_request_cache_source ON request_cache(source_metadata_id);
+CREATE INDEX IF NOT EXISTS idx_request_cache_output ON request_cache(output_hash);
+CREATE INDEX IF NOT EXISTS idx_request_cache_fetched ON request_cache(fetched_at);
+
+-- Negative cache for failed fetches (404s, timeouts, etc.)
 CREATE TABLE IF NOT EXISTS negative_cache (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     source_host TEXT NOT NULL,
     source_path TEXT NOT NULL,
     source_query TEXT NOT NULL DEFAULT '',
+    status_code INTEGER NOT NULL,
+    error_message TEXT,
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     expires_at DATETIME NOT NULL,
     UNIQUE(source_host, source_path, source_query)
 );
 CREATE INDEX IF NOT EXISTS idx_negative_cache_expires ON negative_cache(expires_at);
 
+-- Cache statistics for monitoring
+CREATE TABLE IF NOT EXISTS cache_stats (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    hit_count INTEGER NOT NULL DEFAULT 0,
+    miss_count INTEGER NOT NULL DEFAULT 0,
+    upstream_fetch_count INTEGER NOT NULL DEFAULT 0,
+    upstream_fetch_bytes INTEGER NOT NULL DEFAULT 0,
+    transform_count INTEGER NOT NULL DEFAULT 0,
+    last_updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+INSERT OR IGNORE INTO cache_stats (id) VALUES (1);
+
 -- A random value that a login session carries from its login. pixa makes it
 -- when the table has no row, and each logout replaces it; a login session
 -- carrying another value is refused, so logging out ends every login session.

internal/handlers/cache_hit_internal_test.go

@@ -1,265 +0,0 @@
-package handlers
-
-import (
-	"bytes"
-	"context"
-	"database/sql"
-	"database/sql/driver"
-	"image"
-	"image/jpeg"
-	"log/slog"
-	"net/http"
-	"net/http/httptest"
-	"path/filepath"
-	"sync/atomic"
-	"testing"
-	"testing/fstest"
-	"time"
-
-	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
-
-	"sneak.berlin/go/pixa/internal/database"
-	"sneak.berlin/go/pixa/internal/encurl"
-	"sneak.berlin/go/pixa/internal/imagerequest"
-	"sneak.berlin/go/pixa/internal/imgcache"
-)
-
-// countingHost is the allowlisted host whose photoPath the server of
-// newCountingDatabaseServer serves.
-const countingHost = "counting.example.com"
-
-// countingConnector opens connections to the SQLite database file name with
-// sqliteDriver, each one counting in statements the statements run on it.
-type countingConnector struct {
-	sqliteDriver driver.Driver
-	name         string
-	statements   *atomic.Int64
-}
-
-func (c countingConnector) Connect(context.Context) (driver.Conn, error) {
-	conn, err := c.sqliteDriver.Open(c.name)
-	if err != nil {
-		return nil, err
-	}
-
-	return countingConn{Conn: conn, statements: c.statements}, nil
-}
-
-func (c countingConnector) Driver() driver.Driver {
-	return c.sqliteDriver
-}
-
-// countingConn counts the statements run on its connection. It has only the
-// methods of driver.Conn, so database/sql prepares every query and every
-// other statement with Prepare, which counts it.
-type countingConn struct {
-	driver.Conn
-
-	statements *atomic.Int64
-}
-
-func (c countingConn) Prepare(query string) (driver.Stmt, error) {
-	c.statements.Add(1)
-
-	return c.Conn.Prepare(query)
-}
-
-// newCountingDatabase returns a database with pixa's schema, in a file of
-// its own and with one connection, and the count of the statements run on
-// it once the schema is in place.
-func newCountingDatabase(tb testing.TB) (*sql.DB, *atomic.Int64) {
-	tb.Helper()
-
-	path := filepath.Join(tb.TempDir(), "state.sqlite3")
-
-	schemaDB, err := sql.Open("sqlite", path)
-	if err != nil {
-		tb.Fatalf("opening the database: %v", err)
-	}
-
-	defer func() { _ = schemaDB.Close() }()
-
-	err = database.ApplyMigrations(tb.Context(), schemaDB, nil)
-	if err != nil {
-		tb.Fatalf("applying the migrations: %v", err)
-	}
-
-	statements := new(atomic.Int64)
-
-	db := sql.OpenDB(countingConnector{
-		sqliteDriver: schemaDB.Driver(),
-		name:         path,
-		statements:   statements,
-	})
-	db.SetMaxOpenConns(1)
-
-	tb.Cleanup(func() { _ = db.Close() })
-
-	return db, statements
-}
-
-// newCountingDatabaseServer returns a router for both image routes whose
-// image cache uses newCountingDatabase, the count of the statements run on
-// that database, and a URL on each route for a different image of
-// photoPath on countingHost. Nothing writes the cache's access times in the
-// background, so every statement counted comes from a request.
-func newCountingDatabaseServer(
-	tb testing.TB,
-) (http.Handler, *atomic.Int64, []string) {
-	tb.Helper()
-
-	db, statements := newCountingDatabase(tb)
-
-	var photo bytes.Buffer
-
-	err := jpeg.Encode(&photo, image.NewRGBA(image.Rect(0, 0, 100, 100)), nil)
-	if err != nil {
-		tb.Fatalf("encoding the photo: %v", err)
-	}
-
-	cache, err := imgcache.NewCache(db, imgcache.CacheConfig{
-		StateDir:    tb.TempDir(),
-		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
-	if err != nil {
-		tb.Fatalf("imgcache.NewCache() error = %v", err)
-	}
-
-	svc, err := imgcache.NewService(&imgcache.ServiceConfig{
-		Cache: cache,
-		Fetcher: newMockFetcher(fstest.MapFS{
-			countingHost + photoPath: &fstest.MapFile{Data: photo.Bytes()},
-		}),
-		SigningKey: testSigningKey,
-		Allowlist:  []string{countingHost},
-		Logger:     slog.New(slog.DiscardHandler),
-	})
-	if err != nil {
-		tb.Fatalf("imgcache.NewService() error = %v", err)
-	}
-
-	encGen, err := encurl.NewGenerator(testSigningKey)
-	if err != nil {
-		tb.Fatalf("encurl.NewGenerator() error = %v", err)
-	}
-
-	token, err := encGen.Generate(&imagerequest.Request{
-		Source: imagerequest.Source{Host: countingHost, Path: photoPath},
-		Transform: imagerequest.Transform{
-			Size:    imagerequest.Size{Width: 40, Height: 40},
-			Format:  imagerequest.FormatJPEG,
-			Quality: 85,
-			FitMode: imagerequest.FitCover,
-		},
-	})
-	if err != nil {
-		tb.Fatalf("encGen.Generate() error = %v", err)
-	}
-
-	h := &Handlers{
-		log:    slog.New(slog.DiscardHandler),
-		imgSvc: svc,
-		encGen: encGen,
-	}
-
-	r := chi.NewRouter()
-	r.Get("/v1/image/*", h.HandleImage())
-	r.Get("/v1/e/{token}/*", h.HandleImageEnc())
-
-	return r, statements, []string{
-		"/v1/image/" + countingHost + photoPath + "/50x50.jpeg",
-		"/v1/e/" + token + "/img.jpg",
-	}
-}
-
-// serveImage sends srv a GET for target and returns the response, failing
-// the test unless it is a 200 with an image.
-func serveImage(
-	tb testing.TB, srv http.Handler, target string,
-) *httptest.ResponseRecorder {
-	tb.Helper()
-
-	rec := httptest.NewRecorder()
-	srv.ServeHTTP(rec,
-		httptest.NewRequestWithContext(tb.Context(), http.MethodGet, target, nil))
-
-	if rec.Code != http.StatusOK || rec.Body.Len() == 0 {
-		tb.Errorf("GET %s: %d with %d bytes, want 200 with an image",
-			target, rec.Code, rec.Body.Len())
-	}
-
-	return rec
-}
-
-// TestImageRoutes_CacheHitsMakeNoDatabaseCall serves an image on each image
-// route once, which makes and caches it, then serves it again from the cache.
-// Serving those cache hits must run no statement on the database.
-func TestImageRoutes_CacheHitsMakeNoDatabaseCall(t *testing.T) {
-	t.Parallel()
-
-	srv, statements, targets := newCountingDatabaseServer(t)
-
-	for _, target := range targets {
-		before := statements.Load()
-
-		serveImage(t, srv, target)
-
-		afterMiss := statements.Load()
-		t.Logf("GET %s, a miss: %d statements", target, afterMiss-before)
-
-		if afterMiss == before {
-			t.Fatalf("GET %s, a miss: no statement counted, want some", target)
-		}
-
-		for range 3 {
-			rec := serveImage(t, srv, target)
-
-			cacheStatus := rec.Header().Get("X-Pixa-Cache")
-			if cacheStatus != string(imgcache.CacheHit) {
-				t.Errorf("GET %s: X-Pixa-Cache = %q, want %s",
-					target, cacheStatus, imgcache.CacheHit)
-			}
-		}
-
-		if hitStatements := statements.Load() - afterMiss; hitStatements != 0 {
-			t.Errorf("GET %s: 3 cache hits ran %d statements, want 0",
-				target, hitStatements)
-		}
-	}
-}
-
-// BenchmarkHandleImage_CacheHits serves one cached image through the
-// /v1/image/ route from b.RunParallel's goroutines, and reports the cache
-// hits served per second. It fails if serving them ran any statement on the
-// database. script/bench runs it.
-func BenchmarkHandleImage_CacheHits(b *testing.B) {
-	srv, statements, targets := newCountingDatabaseServer(b)
-	target := targets[0]
-
-	serveImage(b, srv, target)
-
-	before := statements.Load()
-
-	b.ResetTimer()
-
-	b.RunParallel(func(pb *testing.PB) {
-		for pb.Next() {
-			rec := serveImage(b, srv, target)
-
-			cacheStatus := rec.Header().Get("X-Pixa-Cache")
-			if cacheStatus != string(imgcache.CacheHit) {
-				b.Errorf("GET %s: X-Pixa-Cache = %q, want %s",
-					target, cacheStatus, imgcache.CacheHit)
-
-				return
-			}
-		}
-	})
-
-	b.ReportMetric(float64(b.N)/b.Elapsed().Seconds(), "hits/s")
-
-	if hitStatements := statements.Load() - before; hitStatements != 0 {
-		b.Fatalf("%d cache hits ran %d statements, want 0", b.N, hitStatements)
-	}
-}

internal/handlers/cache_max_bytes_internal_test.go

@@ -5,7 +5,6 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx/fxtest"
 
 	"sneak.berlin/go/pixa/internal/config"
@@ -128,10 +127,7 @@ func TestDiskCacheOffOnlyForExplicitZeroCacheMaxBytes(t *testing.T) {
 				t.Fatalf("database.New() error = %v", err)
 			}
 
-			_, err = New(lc, Params{
+			_, err = New(lc, Params{Logger: log, Database: db, Config: cfg})
-				Logger: log, Database: db, Config: cfg,
-				MetricsRegistry: prometheus.NewRegistry(),
-			})
 			if err != nil {
 				t.Fatalf("New() error = %v", err)
 			}

internal/handlers/fetcher_internal_test.go

@@ -8,7 +8,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx"
 	"go.uber.org/fx/fxtest"
 
@@ -48,8 +47,7 @@ func TestHandlersBuildTheirOwnFetcherWhenNoneIsProvided(t *testing.T) {
 
 	app := fxtest.New(t,
 		fx.Supply(cfg),
-		fx.Provide(globals.New, logger.New, database.New, healthcheck.New, New,
+		fx.Provide(globals.New, logger.New, database.New, healthcheck.New, New),
-			func() prometheus.Registerer { return prometheus.NewRegistry() }),
 		fx.Populate(&h),
 	)
 	app.RequireStart()

internal/handlers/first_bytes_internal_test.go

@@ -12,7 +12,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imagerequest"
@@ -36,7 +35,7 @@ func newRoutesFetchingThrough(
 	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
 		StateDir:    t.TempDir(),
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("imgcache.NewCache() error = %v", err)
 	}

internal/handlers/format_auto_internal_test.go

@@ -75,13 +75,11 @@ func TestFormatForAccept(t *testing.T) {
 
 // autoPhotoURLs returns a signed /v1/image/ URL and an encrypted /v1/e/ URL,
 // both valid for a minute, for the JPEG at photoPath on signedHost at 50x50 in
-// the format auto. The first is signed with testSigningKey, the key of the
+// the format auto, made with h's image service and generator.
-// image service newSignedHostServer builds, and the second is made with h's
-// generator.
 func autoPhotoURLs(t *testing.T, h *Handlers) (string, string) {
 	t.Helper()
 
-	signedURL := generateSignedURL(testSigningKey, &imagerequest.Request{
+	signedURL, err := h.imgSvc.GenerateSignedURL("", &imagerequest.Request{
 		Source: imagerequest.Source{
 			Host: signedHost,
 			Path: photoPath,
@@ -91,6 +89,9 @@ func autoPhotoURLs(t *testing.T, h *Handlers) (string, string) {
 			Format: imagerequest.FormatAuto,
 		},
 	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
 
 	token, err := h.encGen.Generate(&imagerequest.Request{
 		Source: imagerequest.Source{
@@ -187,9 +188,9 @@ func TestFormatAuto_ChosenFromAccept(t *testing.T) {
 func TestFormatAuto_SignatureCoversAuto(t *testing.T) {
 	t.Parallel()
 
-	_, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
 
-	signedForAVIF := generateSignedURL(testSigningKey, &imagerequest.Request{
+	signedForAVIF, err := h.imgSvc.GenerateSignedURL("", &imagerequest.Request{
 		Source: imagerequest.Source{
 			Host: signedHost,
 			Path: photoPath,
@@ -199,6 +200,9 @@ func TestFormatAuto_SignatureCoversAuto(t *testing.T) {
 			Format: imagerequest.FormatAVIF,
 		},
 	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
 
 	target := strings.Replace(signedForAVIF, "/50x50.avif?", "/50x50.auto?", 1)
 	if target == signedForAVIF {

internal/handlers/handlers.go

@@ -9,7 +9,6 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx"
 	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/config"
@@ -31,11 +30,6 @@ type Params struct {
 	Database    *database.Database
 	Config      *config.Config
 
-	// MetricsRegistry is the registry the image cache registers its
-	// counters on. pixad provides Prometheus' default registry, the one
-	// /metrics serves.
-	MetricsRegistry prometheus.Registerer
-
 	// Fetcher, when provided, fetches upstream images in place of the
 	// fetcher the handlers build from the config. Only tests provide one;
 	// pixad does not.
@@ -58,10 +52,6 @@ type Handlers struct {
 	// refererBlocklist matches the hosts of referer_blocklist; its IsAllowed
 	// reports whether a URL's host is on that list.
 	refererBlocklist *allowlist.HostAllowList
-
-	// metricsRegistry is the registry the image cache registers its
-	// counters on.
-	metricsRegistry prometheus.Registerer
 }
 
 // New creates a new Handlers instance.
@@ -79,7 +69,6 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 		fetcher:          params.Fetcher,
 		csrfProtect:      csrfProtect,
 		refererBlocklist: allowlist.New(params.Config.RefererBlocklist),
-		metricsRegistry:  params.MetricsRegistry,
 	}
 
 	lc.Append(fx.Hook{
@@ -87,8 +76,8 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 		OnStart: func(_ context.Context) error {
 			return s.initImageService()
 		},
-		// The pending access times are written here, before the database's
+		// The pending counts are written here, before the database's stop
-		// stop hook closes it.
+		// hook closes it.
 		OnStop: func(ctx context.Context) error {
 			if s.imgCache == nil {
 				return nil
@@ -96,7 +85,7 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 
 			return errors.Join(
 				s.imgCache.StopEviction(ctx),
-				s.imgCache.StopPendingAccessTimeWrites(ctx),
+				s.imgCache.StopPendingCountWrites(ctx),
 			)
 		},
 	})
@@ -127,8 +116,7 @@ func newCacheConfig(cfg *config.Config, log *slog.Logger) imgcache.CacheConfig {
 
 // initImageService initializes the image cache and service.
 func (s *Handlers) initImageService() error {
-	cache, err := imgcache.NewCache(
+	cache, err := imgcache.NewCache(s.db.DB(), newCacheConfig(s.config, s.log))
-		s.db.DB(), newCacheConfig(s.config, s.log), s.metricsRegistry)
 	if err != nil {
 		return err
 	}
@@ -140,9 +128,8 @@ func (s *Handlers) initImageService() error {
 	// rows, which is all it does when the disk cache is disabled.
 	cache.StartEviction(imgcache.DefaultEvictionInterval)
 
-	// Writes the access times that requests hand over, so that no request
+	// Writes the counts requests could not write by their deadline
-	// waits for the database to record them
+	cache.StartPendingCountWrites()
-	cache.StartPendingAccessTimeWrites()
 
 	// Create the fetcher config
 	fetcherCfg := httpfetcher.DefaultConfig()

internal/handlers/handlers_internal_test.go

@@ -18,7 +18,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imgcache"
@@ -27,6 +26,7 @@ import (
 // testFixtures contains test data.
 type testFixtures struct {
 	handler  *Handlers
+	service  *imgcache.Service
 	goodHost string
 }
 
@@ -48,7 +48,7 @@ func setupTestHandler(t *testing.T) *testFixtures {
 	cache, err := imgcache.NewCache(db, imgcache.CacheConfig{
 		StateDir:    tmpDir,
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
@@ -70,6 +70,7 @@ func setupTestHandler(t *testing.T) *testFixtures {
 
 	return &testFixtures{
 		handler:  h,
+		service:  svc,
 		goodHost: goodHost,
 	}
 }

internal/handlers/image_cache_control_internal_test.go

@@ -12,7 +12,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/imagerequest"
@@ -34,7 +33,7 @@ func newSignedHostServer(
 	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
 		StateDir:    t.TempDir(),
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("imgcache.NewCache() error = %v", err)
 	}
@@ -107,9 +106,9 @@ func getMaxAge(t *testing.T, srv http.Handler, target string) int {
 func TestHandleImage_SignedURL_MaxAgeEndsAtExp(t *testing.T) {
 	t.Parallel()
 
-	_, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
+	h, srv := newSignedHostServer(t, slog.New(slog.DiscardHandler))
 
-	signedURL := generateSignedURL(testSigningKey, &imagerequest.Request{
+	signedURL, err := h.imgSvc.GenerateSignedURL("", &imagerequest.Request{
 		Source: imagerequest.Source{
 			Host: signedHost,
 			Path: photoPath,
@@ -119,6 +118,9 @@ func TestHandleImage_SignedURL_MaxAgeEndsAtExp(t *testing.T) {
 			Format: imagerequest.FormatJPEG,
 		},
 	}, time.Minute)
+	if err != nil {
+		t.Fatalf("GenerateSignedURL() error = %v", err)
+	}
 
 	maxAge := getMaxAge(t, srv, signedURL)
 	if maxAge < 50 || maxAge > 60 {

internal/handlers/image_errors_internal_test.go

@@ -13,7 +13,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/imgcache"
@@ -32,7 +31,7 @@ func newImageRoute(t *testing.T, fetcher httpfetcher.Fetcher) http.Handler {
 	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
 		StateDir:    t.TempDir(),
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}

internal/handlers/image_signature_internal_test.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"net/http"
 	"net/http/httptest"
-	"net/url"
 	"testing"
 	"time"
 
@@ -37,43 +36,6 @@ func getImage(t *testing.T, fix *testFixtures, target string) int {
 	return rec.Code
 }
 
-// generateSignedURL returns the /v1/image/ URL of req, signed with key and
-// expiring after ttl, and sets req's expiry. An unset quality or fit of req is
-// first set to 85 or cover, the values the route uses when a URL has no q or
-// fit. The URL carries q and fit next to sig and exp, so the route verifies it
-// for the quality and fit it was signed with.
-func generateSignedURL(
-	key string, req *imagerequest.Request, ttl time.Duration,
-) string {
-	if req.Transform.Quality == 0 {
-		req.Transform.Quality = 85
-	}
-
-	if req.Transform.FitMode == "" {
-		req.Transform.FitMode = imagerequest.FitCover
-	}
-
-	req.Expires = time.Now().Add(ttl)
-	sig := signature.New(key).Sign(req)
-
-	// A source query follows the source path after a "?". The image route
-	// reads the path decoded once, so the whole path is written in Go's own
-	// percent-encoding of a URL path, which writes "?" as %3F and "%" as %25,
-	// and leaves "/", ";", ",", "=" and "&" as they are.
-	sourcePathAndQuery := req.Source.Path
-	if req.Source.Query != "" {
-		sourcePathAndQuery += "?" + req.Source.Query
-	}
-
-	unescapedPath := fmt.Sprintf("/v1/image/%s%s/%dx%d.%s",
-		req.Source.Host, sourcePathAndQuery,
-		req.Transform.Size.Width, req.Transform.Size.Height, req.Transform.Format)
-
-	return fmt.Sprintf("%s?sig=%s&exp=%d&q=%d&fit=%s",
-		(&url.URL{Path: unescapedPath}).EscapedPath(), sig, req.Expires.Unix(),
-		req.Transform.Quality, req.Transform.FitMode)
-}
-
 // 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.
@@ -121,8 +83,8 @@ func TestHandleImage_SignatureCoversQualityAndFit(t *testing.T) {
 	}
 }
 
-// TestHandleImage_GeneratedSignedURLVerifies sends URLs built by
+// TestHandleImage_GeneratedSignedURLVerifies sends URLs built by the
-// generateSignedURL to the route.
+// service's signed-URL generator to the route.
 func TestHandleImage_GeneratedSignedURLVerifies(t *testing.T) {
 	t.Parallel()
 
@@ -139,8 +101,9 @@ func TestHandleImage_GeneratedSignedURLVerifies(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			signedURL := generateSignedURL("test-signing-key-must-be-32-chars",
+			fix := setupTestHandler(t)
-				&imagerequest.Request{
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imagerequest.Request{
 				Source: imagerequest.Source{
 					Host: signedHost,
 					Path: "/images/photo.jpg",
@@ -152,8 +115,11 @@ func TestHandleImage_GeneratedSignedURLVerifies(t *testing.T) {
 					FitMode: tt.fitMode,
 				},
 			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
 
-			status := getImage(t, setupTestHandler(t), signedURL)
+			status := getImage(t, fix, signedURL)
 			if status != http.StatusBadGateway {
 				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
 			}
@@ -212,10 +178,10 @@ func TestHandleImage_InvalidExp_Returns400(t *testing.T) {
 }
 
 // TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies sends URLs built
-// by generateSignedURL for source URLs with a query to the route, through a
+// by the service's signed-URL generator for source URLs with a query to the
-// chi router: chi routes on the path as the client wrote it whenever that is
+// route, through a chi router: chi routes on the path as the client wrote it
-// not Go's own encoding of it. A 502 means the signature passed, so the route
+// whenever that is not Go's own encoding of it. A 502 means the signature
-// read the source path and query that were signed.
+// passed, so the route read the source path and query that were signed.
 func TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies(t *testing.T) {
 	t.Parallel()
 
@@ -235,8 +201,9 @@ func TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			signedURL := generateSignedURL("test-signing-key-must-be-32-chars",
+			fix := setupTestHandler(t)
-				&imagerequest.Request{
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imagerequest.Request{
 				Source: imagerequest.Source{
 					Host:  signedHost,
 					Path:  photoPath,
@@ -247,8 +214,11 @@ func TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies(t *testing.T) {
 					Format: imagerequest.FormatJPEG,
 				},
 			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
 
-			status := getImage(t, setupTestHandler(t), signedURL)
+			status := getImage(t, fix, signedURL)
 			if status != http.StatusBadGateway {
 				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
 			}
@@ -310,7 +280,7 @@ func TestHandleImage_SourceQueryEncodedAnyWay(t *testing.T) {
 // TestHandleImage_SourceURLHoldingPercent25Verifies signs a source path and a
 // source query that each hold %25, the percent-escape of a literal "%", and
 // sends each to the route written as the README says, with that "%" written as
-// %25, and as generateSignedURL writes it. A 502 means the signature passed.
+// %25, and as GenerateSignedURL writes it. A 502 means the signature passed.
 func TestHandleImage_SourceURLHoldingPercent25Verifies(t *testing.T) {
 	t.Parallel()
 
@@ -356,11 +326,12 @@ func TestHandleImage_SourceURLHoldingPercent25Verifies(t *testing.T) {
 			}
 		})
 
-		t.Run(tt.name+" written by generateSignedURL", func(t *testing.T) {
+		t.Run(tt.name+" written by GenerateSignedURL", func(t *testing.T) {
 			t.Parallel()
 
-			signedURL := generateSignedURL("test-signing-key-must-be-32-chars",
+			fix := setupTestHandler(t)
-				&imagerequest.Request{
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imagerequest.Request{
 				Source: imagerequest.Source{
 					Host:  signedHost,
 					Path:  tt.sourcePath,
@@ -371,8 +342,11 @@ func TestHandleImage_SourceURLHoldingPercent25Verifies(t *testing.T) {
 					Format: imagerequest.FormatJPEG,
 				},
 			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
 
-			status := getImage(t, setupTestHandler(t), signedURL)
+			status := getImage(t, fix, signedURL)
 			if status != http.StatusBadGateway {
 				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
 			}

internal/handlers/referer_blocklist_internal_test.go

@@ -10,7 +10,6 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
@@ -51,7 +50,7 @@ func newRefererRoutes(t *testing.T) (http.Handler, *Handlers, *countingFetcher)
 	cache, err := imgcache.NewCache(setupTestDB(t), imgcache.CacheConfig{
 		StateDir:    t.TempDir(),
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("imgcache.NewCache() error = %v", err)
 	}

internal/handlers/request_id_internal_test.go

@@ -17,13 +17,11 @@ import (
 )
 
 // signedPhotoURL returns a signed /v1/image/ URL, valid for a minute, for the
-// JPEG at photoPath on signedHost at 50x50. It is signed with testSigningKey,
+// JPEG at photoPath on signedHost at 50x50, made with h's image service.
-// the key of the image service newSignedHostServer builds. It takes a Handlers
+func signedPhotoURL(t *testing.T, h *Handlers) string {
-// it does not use, so that it has the type of encPhotoURL.
-func signedPhotoURL(t *testing.T, _ *Handlers) string {
 	t.Helper()
 
-	return generateSignedURL(testSigningKey, &imagerequest.Request{
+	signedURL, err := h.imgSvc.GenerateSignedURL("", &imagerequest.Request{
 		Source: imagerequest.Source{
 			Host: signedHost,
 			Path: photoPath,
@@ -33,6 +31,11 @@ func signedPhotoURL(t *testing.T, _ *Handlers) string {
 			Format: imagerequest.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

internal/httpfetcher/fetch_internal_test.go

@@ -524,7 +524,7 @@ func TestFetchSemaphoreReleasedOnPartialReadClose(t *testing.T) {
 	})
 }
 
-// The dial-time re-resolution in dialSSRFSafe is what closes the DNS
+// 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
@@ -544,9 +544,9 @@ func TestSSRFSafeDialerBlocksPrivateTarget(t *testing.T) {
 		t.Run(addr, func(t *testing.T) {
 			t.Parallel()
 
-			_, err := dialSSRFSafe(context.Background(), "tcp", addr, nil)
+			_, err := ssrfSafeDialer(context.Background(), "tcp", addr)
 			if !errors.Is(err, ErrSSRFBlocked) {
-				t.Errorf("dialSSRFSafe(%q) = %v, want ErrSSRFBlocked", addr, err)
+				t.Errorf("ssrfSafeDialer(%q) = %v, want ErrSSRFBlocked", addr, err)
 			}
 		})
 	}
@@ -560,7 +560,7 @@ func TestSSRFSafeDialerAllowsPublicTarget(t *testing.T) {
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
 
-	_, err := dialSSRFSafe(ctx, "tcp", testPublicHost+":80", nil)
+	_, err := ssrfSafeDialer(ctx, "tcp", testPublicHost+":80")
 	if err == nil {
 		t.Fatal("expected a dial error for an unreachable public target")
 	}

internal/httpfetcher/httpfetcher.go

@@ -639,6 +639,13 @@ func ipv4CompatibleToIPv4(ip net.IP) net.IP {
 	return ip
 }
 
+// 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.

internal/imageprocessor/imageprocessor.go

@@ -322,6 +322,30 @@ const (
 	mimeJXL  = "image/jxl"
 )
 
+// SupportedInputFormats returns MIME types this processor can read.
+func (p *ImageProcessor) SupportedInputFormats() []string {
+	return []string{
+		mimeJPEG,
+		mimePNG,
+		mimeGIF,
+		mimeWebP,
+		mimeAVIF,
+		mimeJXL,
+	}
+}
+
+// SupportedOutputFormats returns formats this processor can write.
+func (p *ImageProcessor) SupportedOutputFormats() []imagerequest.Format {
+	return []imagerequest.Format{
+		imagerequest.FormatJPEG,
+		imagerequest.FormatPNG,
+		imagerequest.FormatGIF,
+		imagerequest.FormatWebP,
+		imagerequest.FormatAVIF,
+		imagerequest.FormatJXL,
+	}
+}
+
 // FormatToMIME converts a Format to its MIME type string.
 func FormatToMIME(format imagerequest.Format) string {
 	switch format {

internal/imageprocessor/imageprocessor_internal_test.go

@@ -312,6 +312,22 @@ func TestImageProcessor_ProcessPNG(t *testing.T) {
 	}
 }
 
+func TestImageProcessor_SupportedFormats(t *testing.T) {
+	t.Parallel()
+
+	proc := New(Params{})
+
+	inputFormats := proc.SupportedInputFormats()
+	if len(inputFormats) == 0 {
+		t.Error("SupportedInputFormats() returned empty slice")
+	}
+
+	outputFormats := proc.SupportedOutputFormats()
+	if len(outputFormats) == 0 {
+		t.Error("SupportedOutputFormats() returned empty slice")
+	}
+}
+
 func TestImageProcessor_RejectsOversizedInput(t *testing.T) {
 	t.Parallel()
 

internal/imagerequest/imagerequest.go

@@ -1,7 +1,7 @@
 // Package imagerequest holds the image request type, its parts, its checks,
-// the parsing of the /v1/image/ path, the variant key and the source key. It
+// the parsing of the /v1/image/ path and the variant key. It imports no other
-// imports no other package of this repo, so every package that handles an
+// package of this repo, so every package that handles an image request can
-// image request can import it.
+// import it.
 package imagerequest
 
 import (

internal/imagerequest/sourcekey.go

@@ -1,26 +0,0 @@
-package imagerequest
-
-import (
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-)
-
-// SourceKey is a SHA256 hash identifying a cached source image (hex-encoded).
-type SourceKey string
-
-// Key returns the key the source is cached under, made as CacheKey makes a
-// variant key.
-// Format: sha256(host:path:query)
-// The path and query go through escapePercentAndColon, so that a ":" in
-// either cannot be taken for the one between them.
-func (s Source) Key() SourceKey {
-	data := fmt.Sprintf("%s:%s:%s",
-		s.Host,
-		escapePercentAndColon(s.Path),
-		escapePercentAndColon(s.Query),
-	)
-	h := sha256.Sum256([]byte(data))
-
-	return SourceKey(hex.EncodeToString(h[:]))
-}

internal/imagerequest/sourcekey_internal_test.go

@@ -1,40 +0,0 @@
-package imagerequest
-
-import "testing"
-
-// TestSourceKey_DiffersForEachSource checks that each source gets a key of
-// 64 hex characters, the same each time, and that no two of these sources
-// share one, also when they differ only by a ":" or "%" in the path or query.
-func TestSourceKey_DiffersForEachSource(t *testing.T) {
-	t.Parallel()
-
-	sources := []Source{
-		{Host: testHostCDN, Path: testPathCat},
-		{Host: testHostCDN, Path: testPathCat, Query: "v=2"},
-		{Host: "other.example.com", Path: testPathCat},
-		{Host: testHostCDN, Path: "/c:d"},
-		{Host: testHostCDN, Path: "/c", Query: "d:"},
-		{Host: testHostCDN, Path: "/c%3Ad"},
-	}
-
-	seen := make(map[SourceKey]Source)
-
-	for _, source := range sources {
-		key := source.Key()
-		t.Logf("Key() of %+v = %s", source, key)
-
-		if len(key) != 64 {
-			t.Errorf("Key() of %+v length = %d, want 64", source, len(key))
-		}
-
-		if again := source.Key(); again != key {
-			t.Errorf("Key() of %+v not deterministic: %s vs %s", source, key, again)
-		}
-
-		if earlier, found := seen[key]; found {
-			t.Errorf("Key() gave %+v and %+v the same key", earlier, source)
-		}
-
-		seen[key] = source
-	}
-}

internal/imagerequest/urlparser.go

@@ -66,6 +66,23 @@ var queryEscapeRegex = regexp.MustCompile(`%[0-9A-Fa-f]{2}|[^!-~]|["#'<>%]`)
 var hostRegex = regexp.MustCompile(
 	`^(?:[A-Za-z0-9_.-]+|\[([0-9A-Fa-f:.]+)\])(?::[0-9]*)?$`)
 
+// ParseImagePath parses an image URL's path after /v1/image/, decoded once:
+// <host>/<path>/<size>.<format>, or <host>/<path>/<size> for JPEG XL.
+// Examples:
+//   - cdn.example.com/photos/cat.jpg/800x600.webp
+//   - cdn.example.com/photos/cat.jpg/0x0.jpeg
+//   - cdn.example.com/photos/cat.jpg/orig.png
+//   - cdn.example.com/photos/cat.jpg/800x600
+func ParseImagePath(path string) (*Request, error) {
+	// Strip leading slash if present (chi may include it)
+	path = strings.TrimPrefix(path, "/")
+	if path == "" {
+		return nil, ErrMissingHost
+	}
+
+	return parseImageComponents(path)
+}
+
 // ParseImageURL parses an image URL's path, decoded once as r.URL.Path holds
 // it: /v1/image/<host>/<path>/<size>.<format>, or /v1/image/<host>/<path>/<size>
 // for JPEG XL. A source query follows the source path after a "?", which the

internal/imagerequest/urlparser_internal_test.go

@@ -192,16 +192,76 @@ func TestParseImageURL_Errors(t *testing.T) {
 	}
 }
 
-// TestParseImageURL_LowerCasesHost verifies that the host is lower-cased, so
+func TestParseImagePath(t *testing.T) {
+	t.Parallel()
+
+	// ParseImagePath is for chi wildcard capture (no /v1/image/ prefix)
+	tests := []struct {
+		name    string
+		input   string
+		want    *Request
+		wantErr bool
+	}{
+		{
+			name:  "chi wildcard capture",
+			input: "cdn.example.com/photos/cat.jpg/800x600.webp",
+			want: &Request{
+				Source: Source{
+					Host: testHostCDN,
+					Path: testPathCat,
+				},
+				Transform: Transform{
+					Size:   Size{Width: 800, Height: 600},
+					Format: FormatWebP,
+				},
+			},
+		},
+		{
+			name:  "with leading slash from chi",
+			input: "/cdn.example.com/photos/cat.jpg/800x600.webp",
+			want: &Request{
+				Source: Source{
+					Host: testHostCDN,
+					Path: testPathCat,
+				},
+				Transform: Transform{
+					Size:   Size{Width: 800, Height: 600},
+					Format: FormatWebP,
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := ParseImagePath(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ParseImagePath() error = %v, wantErr %v", err, tt.wantErr)
+
+				return
+			}
+
+			if err != nil {
+				return
+			}
+
+			assertRequest(t, got, tt.want)
+		})
+	}
+}
+
+// TestParseImagePath_LowerCasesHost verifies that the host is lower-cased, so
 // that every spelling of its letter case is the same host to the allowlist,
 // the upstream connection limits and the cache, and that the path keeps its
 // case.
-func TestParseImageURL_LowerCasesHost(t *testing.T) {
+func TestParseImagePath_LowerCasesHost(t *testing.T) {
 	t.Parallel()
 
-	got, err := ParseImageURL("/v1/image/CDN.Example.COM/Photos/Cat.jpg/800x600.webp")
+	got, err := ParseImagePath("CDN.Example.COM/Photos/Cat.jpg/800x600.webp")
 	if err != nil {
-		t.Fatalf("ParseImageURL() error = %v", err)
+		t.Fatalf("ParseImagePath() error = %v", err)
 	}
 
 	t.Logf("parsed host %q, path %q", got.Source.Host, got.Source.Path)
@@ -215,21 +275,21 @@ func TestParseImageURL_LowerCasesHost(t *testing.T) {
 	}
 }
 
-// TestParseImageURL_RefusesUserinfo verifies that a host holding "@" is
+// TestParseImagePath_RefusesUserinfo verifies that a host holding "@" is
 // refused: a URL reads what comes before the "@" as a user name and password
 // and the rest as the host.
-func TestParseImageURL_RefusesUserinfo(t *testing.T) {
+func TestParseImagePath_RefusesUserinfo(t *testing.T) {
 	t.Parallel()
 
 	for _, input := range []string{
-		"/v1/image/user@cdn.example.com/photos/cat.jpg/800x600.webp",
+		"user@cdn.example.com/photos/cat.jpg/800x600.webp",
-		"/v1/image/user:password@cdn.example.com/photos/cat.jpg/800x600.webp",
+		"user:password@cdn.example.com/photos/cat.jpg/800x600.webp",
 	} {
-		got, err := ParseImageURL(input)
+		got, err := ParseImagePath(input)
-		t.Logf("ParseImageURL(%q) = %+v, error = %v", input, got, err)
+		t.Logf("ParseImagePath(%q) = %+v, error = %v", input, got, err)
 
 		if !errors.Is(err, ErrInvalidHost) {
-			t.Errorf("ParseImageURL(%q) error = %v, want %v",
+			t.Errorf("ParseImagePath(%q) error = %v, want %v",
 				input, err, ErrInvalidHost)
 		}
 	}
@@ -255,10 +315,6 @@ func TestParseImageURL_PathTraversal(t *testing.T) {
 			name:  "parent in middle of path",
 			input: "/v1/image/cdn.example.com/photos/../../../etc/passwd/800x600.jpeg",
 		},
-		{
-			name:  "parent directory in path",
-			input: "/v1/image/cdn.example.com/photos/../secret/800x600.jpeg",
-		},
 		{
 			name:  "encoded parent directory",
 			input: "/v1/image/cdn.example.com/photos/%2e%2e/secret/800x600.jpeg",
@@ -301,6 +357,40 @@ func TestParseImageURL_PathTraversal(t *testing.T) {
 	}
 }
 
+func TestParseImagePath_PathTraversal(t *testing.T) {
+	t.Parallel()
+
+	// Test path traversal via ParseImagePath (chi wildcard)
+	tests := []struct {
+		name  string
+		input string
+	}{
+		{
+			name:  "parent directory in path",
+			input: "cdn.example.com/photos/../secret/800x600.jpeg",
+		},
+		{
+			name:  "encoded traversal",
+			input: "cdn.example.com/photos/%2e%2e/secret/800x600.jpeg",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			_, err := ParseImagePath(tt.input)
+			if err == nil {
+				t.Error("ParseImagePath() should reject path traversal attempts")
+			}
+
+			if !errors.Is(err, ErrPathTraversal) {
+				t.Errorf("ParseImagePath() error = %v, want ErrPathTraversal", err)
+			}
+		})
+	}
+}
+
 // TestParseImageURL_SourceURLHoldingPercent25 verifies that a source path and
 // a source query holding %25, the percent-escape of a literal "%", are
 // accepted as they are, although decoding them once more leaves a "%" that

internal/imgcache/cache.go

@@ -2,23 +2,36 @@ package imgcache
 
 import (
 	"context"
+	"crypto/sha256"
 	"database/sql"
+	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"path/filepath"
+	"sync"
+	"sync/atomic"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
+	lru "github.com/hashicorp/golang-lru/v2"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
-// maxPendingAccessTimes is how many access times of variants served from
+// Cache errors.
-// the cache, and how many of cached sources a miss used, may each wait to be
+var (
-// written, at about 80 bytes each. An access time handed over while that
+	ErrCacheMiss     = errors.New("cache miss")
-// many of its kind wait is dropped.
+	ErrNegativeCache = errors.New("negative cache hit")
-const maxPendingAccessTimes = 10000
+)
+
+// 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
 
 // cleanExpiredBatchSize is the most expired negative cache rows one
 // statement of CleanExpired deletes. Each batch is a statement of its
@@ -57,8 +70,9 @@ type CacheConfig struct {
 // Cache implements the caching layer for the image proxy.
 type Cache struct {
 	db          *sql.DB
-	srcContent *ContentStorage // source images by source key
+	srcContent  *ContentStorage  // source images by content hash
 	variants    *VariantStorage  // processed variants by cache key
+	srcMetadata *MetadataStorage // source metadata by host/path
 	config      CacheConfig
 	log         *slog.Logger
 
@@ -74,30 +88,47 @@ type Cache struct {
 	evictionDone     chan struct{}
 	evictionCancel   context.CancelFunc
 
-	// pendingVariantAccessTimes holds the variants served from the cache,
+	// The pending counts: hits, misses, upstream fetches and transforms
-	// and pendingSourceAccessTimes the cached sources a miss used, whose
+	// whose write to the database missed its request's deadline, kept
-	// access time is still to be written by the goroutine that
+	// here until they are written by the goroutine that
-	// StartPendingAccessTimeWrites starts, so that no request waits for the
+	// StartPendingCountWrites starts. As for eviction, the channels are
-	// database to record it. As for eviction, the channels are created in
+	// created in NewCache: pendingCountsAdded wakes that goroutine, and
-	// NewCache, so that requests can hand over access times before that
+	// pendingCountsDone is closed when it returns. pendingCountsCancel,
-	// goroutine starts; pendingAccessTimesDone is closed when it returns.
+	// set by StartPendingCountWrites, cancels its context, which tells it
-	// pendingAccessTimesCancel, set by StartPendingAccessTimeWrites,
+	// to finish.
-	// cancels its context, which tells it to finish.
+	pendingHits               atomic.Int64
-	pendingVariantAccessTimes chan imagerequest.VariantKey
+	pendingMisses             atomic.Int64
-	pendingSourceAccessTimes  chan imagerequest.SourceKey
+	pendingUpstreamFetches    atomic.Int64
-	pendingAccessTimesDone    chan struct{}
+	pendingUpstreamFetchBytes atomic.Int64
-	pendingAccessTimesCancel  context.CancelFunc
+	pendingTransforms         atomic.Int64
+	pendingCountsAdded        chan struct{}
+	pendingCountsDone         chan struct{}
+	pendingCountsCancel       context.CancelFunc
 
-	// The counts of what the cache does, made and registered by
+	// Held through each write of the pending counts, and by
-	// registerCounters (see counters.go)
+	// readHitAndMissCounts to read them
-	cacheHits          prometheus.Counter
+	pendingCountsWriteMutex sync.Mutex
-	cacheMisses        prometheus.Counter
+
-	upstreamFetches    prometheus.Counter
+	// metaCache holds the content types of the variants most recently
-	upstreamFetchBytes prometheus.Counter
+	// stored or served, so a hit does not read the variant's .meta file.
-	transforms         prometheus.Counter
+	// It never stands in for the variant file, which is always opened.
+	metaCache *lru.Cache[imagerequest.VariantKey, string]
+
+	// contentLocks serializes StoreSource and evictSourceBlob per
+	// content hash, closing the race window between an eviction's row
+	// deletion and its file unlink against a concurrent store of
+	// identical content.
+	contentLocks *contentLock
+
+	// evictSourceBlobTestHook, when set, is invoked by evictSourceBlob
+	// after its row-deletion transaction commits and before the
+	// content file is unlinked. It exists solely so tests can
+	// deterministically pause inside that window to exercise
+	// concurrent stores against it; production code leaves it nil.
+	evictSourceBlobTestHook func(ContentHash)
 
 	// reconciliationPageSize is the most rows one read of a content table
-	// returns in the reconciliation pass. newCache sets it to
+	// returns in the reconciliation pass and in Stats. newCache sets it to
 	// defaultReconciliationPageSize; tests set it smaller.
 	reconciliationPageSize int
 
@@ -108,28 +139,26 @@ type Cache struct {
 	reconciliationReadTestHook func(rows int)
 }
 
-// NewCache creates a new cache instance and registers its counters on
+// NewCache creates a new cache instance.
-// metricsRegistry. pixad passes Prometheus' default registry, the one
+func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
-// /metrics serves.
+	return newCache(db, config, defaultFreeSpaceProbe)
-func NewCache(
-	db *sql.DB, config CacheConfig, metricsRegistry prometheus.Registerer,
-) (*Cache, error) {
-	return newCache(db, config, metricsRegistry, 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,
+	db *sql.DB, config CacheConfig, probe FreeSpaceProbeFunc,
-	config CacheConfig,
-	metricsRegistry prometheus.Registerer,
-	probe FreeSpaceProbeFunc,
 ) (*Cache, error) {
 	log := config.Logger
 	if log == nil {
 		log = slog.Default()
 	}
 
+	metaCache, err := lru.New[imagerequest.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,
@@ -137,19 +166,15 @@ func newCache(
 		disabled:         config.DisableDiskCache,
 		evictionPressure: make(chan struct{}, 1),
 		evictionDone:     make(chan struct{}),
+		metaCache:        metaCache,
+		contentLocks:     newContentLock(),
 
-		pendingVariantAccessTimes: make(chan imagerequest.VariantKey, maxPendingAccessTimes),
+		pendingCountsAdded: make(chan struct{}, 1),
-		pendingSourceAccessTimes:  make(chan imagerequest.SourceKey, maxPendingAccessTimes),
+		pendingCountsDone:  make(chan struct{}),
-		pendingAccessTimesDone:    make(chan struct{}),
 
 		reconciliationPageSize: defaultReconciliationPageSize,
 	}
 
-	err := c.registerCounters(metricsRegistry)
-	if err != nil {
-		return nil, err
-	}
-
 	if c.disabled {
 		return c, nil
 	}
@@ -162,14 +187,22 @@ func newCache(
 	}
 
 	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)
 	}
 
+	srcMetadata, err := NewMetadataStorage(
+		filepath.Join(config.StateDir, "cache", "metadata"),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create source metadata storage: %w", err)
+	}
+
 	c.srcContent = srcContent
 	c.variants = variants
+	c.srcMetadata = srcMetadata
 
 	if config.UseDefaultMaxBytes {
 		limit, err := c.computeDefaultMaxBytes(context.Background(), probe)
@@ -188,11 +221,45 @@ func newCache(
 	return c, nil
 }
 
-// GetVariant opens a cached variant and returns a reader, its size and its
+// LookupResult contains the result of a cache lookup.
-// content type, read from the variant file's first bytes. It opens that one
+type LookupResult struct {
-// file and makes no database call. A variant not in the cache, or any
+	Hit         bool
-// variant of a disabled cache, is ErrNotFound; a variant file whose first
+	CacheKey    imagerequest.VariantKey
-// bytes are not those of an output format is another error.
+	ContentType string
+	SizeBytes   int64
+	CacheStatus CacheStatus
+}
+
+// Lookup checks if a processed variant exists on disk. Hits touch the
+// variant's LRU timestamp; a disabled cache always misses.
+func (c *Cache) Lookup(
+	ctx context.Context, req *imagerequest.Request,
+) (*LookupResult, error) {
+	cacheKey := imagerequest.CacheKey(req)
+
+	// Check variant storage directly - no DB needed for cache hits
+	if !c.disabled && c.variants.Exists(cacheKey) {
+		c.touchVariant(ctx, cacheKey)
+
+		return &LookupResult{
+			Hit:         true,
+			CacheKey:    cacheKey,
+			CacheStatus: CacheHit,
+		}, nil
+	}
+
+	return &LookupResult{
+		Hit:         false,
+		CacheKey:    cacheKey,
+		CacheStatus: CacheMiss,
+	}, nil
+}
+
+// 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 imagerequest.VariantKey,
 ) (io.ReadCloser, int64, string, error) {
@@ -200,56 +267,104 @@ func (c *Cache) GetVariant(
 		return nil, 0, "", ErrNotFound
 	}
 
-	return c.variants.LoadWithContentType(cacheKey)
+	contentType, known := c.metaCache.Get(cacheKey)
+	if !known {
+		return c.loadVariantWithMeta(cacheKey)
 	}
 
-// StoreSource stores fetched source content: it writes the file named by
+	reader, size, err := c.variants.LoadWithSize(cacheKey)
-// the source's key, then the source's row. When the row cannot be written
+	if err != nil {
-// the file is removed and the store fails, as a file with no row is never
+		// The file is gone, e.g. deleted outside pixa
-// served or evicted; if that removal fails too, the next reconciliation
+		c.metaCache.Remove(cacheKey)
-// pass removes the file. On a disabled cache it is a no-op returning an
+
-// empty key.
+		return nil, 0, "", err
+	}
+
+	return reader, size, contentType, nil
+}
+
+// StoreSource stores fetched source content and metadata. On a
+// disabled cache it is a no-op returning an empty hash.
 func (c *Cache) StoreSource(
 	ctx context.Context,
 	req *imagerequest.Request,
 	content io.Reader,
-) (imagerequest.SourceKey, error) {
+	result *httpfetcher.FetchResult,
+) (ContentHash, error) {
 	if c.disabled {
 		return "", nil
 	}
 
+	// Hash the content ourselves (rather than via srcContent.Store,
+	// which would hash internally) so the content hash is known before
+	// any file or database work happens: that lets the entire store be
+	// serialized, per hash, against a concurrent eviction of the same
+	// content below.
 	data, err := io.ReadAll(content)
 	if err != nil {
 		return "", fmt.Errorf("failed to read source content: %w", err)
 	}
 
-	key := req.Source.Key()
+	sum := sha256.Sum256(data)
+	contentHash := ContentHash(hex.EncodeToString(sum[:]))
 
-	size, err := c.srcContent.Store(key, data)
+	// Hold the content hash's lock for the whole store operation. A
+	// concurrent eviction of this exact hash (the real SHA-256 dedup
+	// case: a different source path whose bytes hash identically)
+	// deletes the accounting rows and unlinks the file inside the same
+	// lock, so the two can never interleave: either this store
+	// completes first (and a subsequent eviction removes it together
+	// with its rows and file, correctly), or eviction completes first
+	// (and this store finds the file already gone and recreates it
+	// fresh) — never a fresh row left pointing at a file eviction is
+	// mid-unlink on.
+	unlock := c.contentLocks.Lock(string(contentHash))
+	defer unlock()
+
+	size, err := c.srcContent.StoreHashed(contentHash, data)
 	if err != nil {
 		return "", fmt.Errorf("failed to store source content: %w", err)
 	}
 
-	_, err = c.db.ExecContext(ctx, `
+	// Store in database
-		INSERT INTO source_content (source_key, size_bytes)
+	pathHash := HashPath(req.Source.Path + "?" + req.Source.Query)
-		VALUES (?, ?)
+
-		ON CONFLICT(source_key) DO UPDATE SET
+	headersJSON, err := json.Marshal(result.Headers)
-			size_bytes = excluded.size_bytes,
-			last_accessed_at = CURRENT_TIMESTAMP
-	`, string(key), size)
 	if err != nil {
-		deleteErr := c.srcContent.Delete(key)
+		return "", fmt.Errorf("failed to marshal response headers: %w", err)
-		if deleteErr != nil {
-			c.log.Warn("failed to remove source file whose row was not written",
-				"source_key", key, "error", deleteErr)
 	}
 
+	_, err = c.db.ExecContext(ctx, `
+		INSERT INTO source_content (content_hash, content_type, size_bytes)
+		VALUES (?, ?, ?)
+		ON CONFLICT(content_hash) DO NOTHING
+	`, contentHash, result.ContentType, size)
+	if err != nil {
 		return "", fmt.Errorf("failed to insert source content: %w", err)
 	}
 
+	_, err = c.db.ExecContext(ctx, `
+		INSERT INTO source_metadata
+			(source_host, source_path, source_query, path_hash,
+			 content_hash, status_code, content_type, response_headers)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(source_host, source_path, source_query) DO UPDATE SET
+			content_hash = excluded.content_hash,
+			status_code = excluded.status_code,
+			content_type = excluded.content_type,
+			response_headers = excluded.response_headers,
+			fetched_at = CURRENT_TIMESTAMP
+	`, req.Source.Host, req.Source.Path, req.Source.Query, pathHash,
+		contentHash, httpStatusOK, result.ContentType, string(headersJSON))
+	if err != nil {
+		return "", fmt.Errorf("failed to insert source metadata: %w", err)
+	}
+
+	c.writeMetadataSidecar(req, pathHash, contentHash, result)
+
 	c.notifyWritePressure()
 
-	return key, nil
+	return contentHash, nil
 }
 
 // StoreVariant stores a processed variant by its cache key and records
@@ -257,24 +372,28 @@ func (c *Cache) StoreSource(
 // accounting insert is best-effort (the startup reconciliation pass
 // adopts any variant file that misses its accounting row).
 func (c *Cache) StoreVariant(
-	ctx context.Context, cacheKey imagerequest.VariantKey, content io.Reader,
+	ctx context.Context, cacheKey imagerequest.VariantKey,
+	content io.Reader, contentType string,
 ) error {
 	if c.disabled {
 		return nil
 	}
 
-	size, err := c.variants.Store(cacheKey, content)
+	size, err := c.variants.Store(cacheKey, content, contentType)
 	if err != nil {
 		return err
 	}
 
+	c.metaCache.Add(cacheKey, contentType)
+
 	_, err = c.db.ExecContext(ctx, `
-		INSERT INTO variant_content (cache_key, size_bytes)
+		INSERT INTO variant_content (cache_key, size_bytes, content_type)
-		VALUES (?, ?)
+		VALUES (?, ?, ?)
 		ON CONFLICT(cache_key) DO UPDATE SET
 			size_bytes = excluded.size_bytes,
+			content_type = excluded.content_type,
 			last_accessed_at = CURRENT_TIMESTAMP
-	`, string(cacheKey), size)
+	`, string(cacheKey), size, contentType)
 	if err != nil {
 		c.log.Warn("failed to record variant in size accounting",
 			"cache_key", cacheKey, "error", err)
@@ -286,53 +405,60 @@ func (c *Cache) StoreVariant(
 }
 
 // LookupSource checks if we have cached source content for a request.
-// Returns the source key if found, or an empty key if not; a row whose
+// Returns the content hash and content type if found, or empty values
-// file is missing is not found. A source found has its access time
+// if not. Hits touch the blob's LRU timestamp; a disabled cache always
-// handed to the background writer without waiting (see
+// reports no cached source.
-// touchSourceContent); a disabled cache always reports no cached source.
 func (c *Cache) LookupSource(
 	ctx context.Context, req *imagerequest.Request,
-) (imagerequest.SourceKey, error) {
+) (ContentHash, string, error) {
 	if c.disabled {
-		return "", nil
+		return "", "", nil
 	}
 
-	key := req.Source.Key()
+	var hashStr, contentType string
-
-	var rowExists bool
 
 	err := c.db.QueryRowContext(ctx, `
-		SELECT EXISTS(SELECT 1 FROM source_content WHERE source_key = ?)
+		SELECT content_hash, content_type FROM source_metadata
-	`, string(key)).Scan(&rowExists)
+		WHERE source_host = ? AND source_path = ? AND source_query = ?
-	if err != nil {
+	`, req.Source.Host, req.Source.Path, req.Source.Query).Scan(&hashStr, &contentType)
-		return "", fmt.Errorf("failed to lookup source: %w", err)
+
+	if errors.Is(err, sql.ErrNoRows) {
+		return "", "", nil
 	}
 
-	if !rowExists {
+	if err != nil {
-		return "", nil
+		return "", "", fmt.Errorf("failed to lookup source: %w", err)
 	}
 
+	contentHash := ContentHash(hashStr)
+
 	// Verify the content file exists
-	if !c.srcContent.Exists(key) {
+	if !c.srcContent.Exists(contentHash) {
-		return "", nil
+		return "", "", nil
 	}
 
-	c.touchSourceContent(key)
+	c.touchSourceContent(ctx, contentHash)
 
-	return key, nil
+	return contentHash, contentType, nil
 }
 
 // StoreNegative stores a negative cache entry for a failed fetch.
-func (c *Cache) StoreNegative(ctx context.Context, req *imagerequest.Request) error {
+func (c *Cache) StoreNegative(
+	ctx context.Context, req *imagerequest.Request, statusCode int, errMsg string,
+) error {
 	expiresAt := time.Now().UTC().Add(c.config.NegativeTTL)
 
 	_, err := c.db.ExecContext(ctx, `
 		INSERT INTO negative_cache
-			(source_host, source_path, source_query, expires_at)
+			(source_host, source_path, source_query, status_code,
-		VALUES (?, ?, ?, ?)
+			 error_message, expires_at)
+		VALUES (?, ?, ?, ?, ?, ?)
 		ON CONFLICT(source_host, source_path, source_query) DO UPDATE SET
+			status_code = excluded.status_code,
+			error_message = excluded.error_message,
+			fetched_at = CURRENT_TIMESTAMP,
 			expires_at = excluded.expires_at
-	`, req.Source.Host, req.Source.Path, req.Source.Query, expiresAt)
+	`, req.Source.Host, req.Source.Path, req.Source.Query, statusCode, errMsg, expiresAt)
 	if err != nil {
 		return fmt.Errorf("failed to insert negative cache: %w", err)
 	}
@@ -340,16 +466,33 @@ func (c *Cache) StoreNegative(ctx context.Context, req *imagerequest.Request) er
 	return nil
 }
 
-// GetSourceContent returns a reader for cached source content by its key,
+// GetSourceMetadataID returns the source metadata ID for a request.
+func (c *Cache) GetSourceMetadataID(
+	ctx context.Context, req *imagerequest.Request,
+) (int64, error) {
+	var id int64
+
+	err := c.db.QueryRowContext(ctx, `
+		SELECT id FROM source_metadata
+		WHERE source_host = ? AND source_path = ? AND source_query = ?
+	`, req.Source.Host, req.Source.Path, req.Source.Query).Scan(&id)
+	if err != nil {
+		return 0, fmt.Errorf("failed to get source metadata ID: %w", err)
+	}
+
+	return id, nil
+}
+
+// GetSourceContent returns a reader for cached source content by its hash,
 // and the content's size in bytes.
 func (c *Cache) GetSourceContent(
-	key imagerequest.SourceKey,
+	contentHash ContentHash,
 ) (io.ReadCloser, int64, error) {
 	if c.disabled {
 		return nil, 0, ErrNotFound
 	}
 
-	return c.srcContent.LoadWithSize(key)
+	return c.srcContent.LoadWithSize(contentHash)
 }
 
 // CleanExpired removes the negative cache rows past their expiry, one
@@ -375,63 +518,232 @@ func (c *Cache) CleanExpired(ctx context.Context) error {
 	}
 }
 
-// IncrementStats counts a cache hit or miss, and an upstream fetch that read
+// Stats returns cache statistics.
-// fetchBytes bytes, as IncrementUpstreamFetch does. Like the other Increment
+func (c *Cache) Stats(ctx context.Context) (*CacheStats, error) {
-// methods, it only adds to the cache's Prometheus counters in memory (see
+	var stats CacheStats
-// counters.go), so it never waits for the database or fails.
+
-func (c *Cache) IncrementStats(hit bool, fetchBytes int64) {
+	err := c.readHitAndMissCounts(ctx, &stats)
-	if hit {
+	if err != nil && !errors.Is(err, sql.ErrNoRows) {
-		c.cacheHits.Inc()
+		return nil, fmt.Errorf("failed to get cache stats: %w", err)
-	} else {
-		c.cacheMisses.Inc()
 	}
 
-	c.IncrementUpstreamFetch(fetchBytes)
+	// Count and size the cached source images and processed variants from
+	// their tables. A disabled cache holds none, whatever rows an earlier
+	// run left.
+	if !c.disabled {
+		err = c.db.QueryRowContext(ctx, `
+			SELECT (SELECT COUNT(*) FROM source_content)
+			     + (SELECT COUNT(*) FROM variant_content)
+		`).Scan(&stats.TotalItems)
+		if err != nil {
+			c.log.Warn("failed to count cache items for stats", "error", err)
+		}
+
+		stats.TotalSizeBytes, err = c.sumContentSizeBytes(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 {
+		stats.HitRate = float64(stats.HitCount) / float64(stats.HitCount+stats.MissCount)
+	}
+
+	return &stats, nil
+}
+
+// IncrementStats counts a cache hit or miss, and an upstream fetch that read
+// fetchBytes bytes, as IncrementUpstreamFetch does. Like the other Increment
+// methods, it writes to the database with ctx's deadline but not its
+// cancellation, so an ended request is still counted but does not wait for
+// the database past its deadline; a count not written by then becomes a
+// pending count (see StartPendingCountWrites).
+func (c *Cache) IncrementStats(ctx context.Context, hit bool, fetchBytes int64) {
+	countCtx, cancel := withoutCancelKeepingDeadline(ctx)
+	defer cancel()
+
+	var err error
+
+	pendingCount := &c.pendingMisses
+
+	if hit {
+		pendingCount = &c.pendingHits
+
+		_, err = c.db.ExecContext(countCtx, `
+			UPDATE cache_stats
+			SET hit_count = hit_count + 1,
+			    last_updated_at = CURRENT_TIMESTAMP
+			WHERE id = 1
+		`)
+	} else {
+		_, err = c.db.ExecContext(countCtx, `
+			UPDATE cache_stats
+			SET miss_count = miss_count + 1,
+			    last_updated_at = CURRENT_TIMESTAMP
+			WHERE id = 1
+		`)
+	}
+
+	switch {
+	case errors.Is(err, context.DeadlineExceeded):
+		c.addPendingCount(pendingCount, 1)
+	case err != nil:
+		c.log.Warn("failed to count cache hit or miss", "hit", hit, "error", err)
+	}
+
+	c.IncrementUpstreamFetch(ctx, fetchBytes)
 }
 
 // IncrementUpstreamFetch counts one upstream fetch that read fetchBytes bytes.
 // A fetch that read no bytes is not counted.
-func (c *Cache) IncrementUpstreamFetch(fetchBytes int64) {
+func (c *Cache) IncrementUpstreamFetch(ctx context.Context, fetchBytes int64) {
 	if fetchBytes <= 0 {
 		return
 	}
 
-	c.upstreamFetches.Inc()
+	countCtx, cancel := withoutCancelKeepingDeadline(ctx)
-	c.upstreamFetchBytes.Add(float64(fetchBytes))
+	defer cancel()
+
+	_, err := c.db.ExecContext(countCtx, `
+		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)
+
+	switch {
+	case errors.Is(err, context.DeadlineExceeded):
+		c.addPendingCount(&c.pendingUpstreamFetches, 1)
+		c.addPendingCount(&c.pendingUpstreamFetchBytes, fetchBytes)
+	case 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() {
+func (c *Cache) IncrementTransformCount(ctx context.Context) {
-	c.transforms.Inc()
+	countCtx, cancel := withoutCancelKeepingDeadline(ctx)
-}
+	defer cancel()
 
-// touchVariant hands the access time of a variant served from the cache to
+	_, err := c.db.ExecContext(countCtx, `
-// the goroutine StartPendingAccessTimeWrites starts, which writes it in its
+		UPDATE cache_stats
-// next batch. It never waits: while maxPendingAccessTimes access times of
+		SET transform_count = transform_count + 1,
-// variants wait to be written, this one is dropped, and the variant only
+		    last_updated_at = CURRENT_TIMESTAMP
-// looks colder to eviction.
+		WHERE id = 1
-func (c *Cache) touchVariant(cacheKey imagerequest.VariantKey) {
+	`)
-	select {
+
-	case c.pendingVariantAccessTimes <- cacheKey:
+	switch {
-	default:
+	case errors.Is(err, context.DeadlineExceeded):
+		c.addPendingCount(&c.pendingTransforms, 1)
+	case err != nil:
+		c.log.Warn("failed to count transform", "error", err)
 	}
 }
 
-// touchSourceContent hands the access time of a cached source a miss used to
+// readHitAndMissCounts sets the hit and miss counts of stats to those of the
-// the goroutine StartPendingAccessTimeWrites starts, which writes it in its
+// cache_stats row plus the pending hits and misses (see
-// next batch. It never waits: while maxPendingAccessTimes access times of
+// StartPendingCountWrites). It holds pendingCountsWriteMutex, so that no
-// sources wait to be written, this one is dropped, and the source only looks
+// write of the pending counts falls between the two reads.
-// colder to eviction.
+func (c *Cache) readHitAndMissCounts(ctx context.Context, stats *CacheStats) error {
-func (c *Cache) touchSourceContent(key imagerequest.SourceKey) {
+	c.pendingCountsWriteMutex.Lock()
-	select {
+	defer c.pendingCountsWriteMutex.Unlock()
-	case c.pendingSourceAccessTimes <- key:
+
-	default:
+	err := c.db.QueryRowContext(ctx, `
+		SELECT hit_count, miss_count
+		FROM cache_stats WHERE id = 1
+	`).Scan(&stats.HitCount, &stats.MissCount)
+
+	stats.HitCount += c.pendingHits.Load()
+	stats.MissCount += c.pendingMisses.Load()
+
+	return 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 when the store's .meta write failed or an eviction removed
+// the file after the read opened the variant, 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 imagerequest.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.Request,
+	pathHash PathHash,
+	contentHash ContentHash,
+	result *httpfetcher.FetchResult,
+) {
+	meta := &SourceMetadata{
+		Host:            req.Source.Host,
+		Path:            req.Source.Path,
+		Query:           req.Source.Query,
+		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.Source.Host, pathHash, meta)
+	if err != nil {
+		c.log.Warn("failed to write metadata sidecar",
+			"host", req.Source.Host, "path_hash", pathHash, "error", err)
 	}
 }
 
-// checkNegativeCache checks if a request is in the negative cache. It only
+// touchVariant updates the LRU timestamp of a variant, best-effort:
-// reads: a row past its expiry is not a hit, and the eviction goroutine
+// a failed touch only makes the entry look colder to eviction.
-// deletes it with the other expired rows (see CleanExpired).
+func (c *Cache) touchVariant(ctx context.Context, cacheKey imagerequest.VariantKey) {
+	_, err := c.db.ExecContext(ctx, `
+		UPDATE variant_content SET last_accessed_at = CURRENT_TIMESTAMP
+		WHERE cache_key = ?
+	`, string(cacheKey))
+	if err != nil {
+		c.log.Debug("failed to touch variant LRU timestamp",
+			"cache_key", cacheKey, "error", err)
+	}
+}
+
+// touchSourceContent updates the LRU timestamp of a source content
+// blob, best-effort: a failed touch only makes the blob look colder.
+func (c *Cache) touchSourceContent(ctx context.Context, contentHash ContentHash) {
+	_, err := c.db.ExecContext(ctx, `
+		UPDATE source_content SET last_accessed_at = CURRENT_TIMESTAMP
+		WHERE content_hash = ?
+	`, string(contentHash))
+	if err != nil {
+		c.log.Debug("failed to touch source content LRU timestamp",
+			"content_hash", contentHash, "error", err)
+	}
+}
+
+// checkNegativeCache checks if a request is in the negative cache.
 func (c *Cache) checkNegativeCache(
 	ctx context.Context, req *imagerequest.Request,
 ) (bool, error) {
@@ -450,9 +762,22 @@ func (c *Cache) checkNegativeCache(
 		return false, fmt.Errorf("failed to check negative cache: %w", err)
 	}
 
-	expired := time.Now().After(expiresAt)
+	// Check if expired
+	if time.Now().After(expiresAt) {
+		// Clean up expired entry
+		_, err = c.db.ExecContext(ctx, `
+			DELETE FROM negative_cache
+			WHERE source_host = ? AND source_path = ? AND source_query = ?
+		`, req.Source.Host, req.Source.Path, req.Source.Query)
+		if err != nil {
+			c.log.Warn("failed to delete expired negative cache entry",
+				"host", req.Source.Host, "path", req.Source.Path, "error", err)
+		}
 
-	return !expired, nil
+		return false, nil
+	}
+
+	return true, nil
 }
 
 // cleanExpiredBatch deletes up to cleanExpiredBatchSize negative cache

internal/imgcache/cache_hit_internal_test.go

@@ -1,300 +0,0 @@
-package imgcache
-
-import (
-	"bytes"
-	"errors"
-	"fmt"
-	"image/color"
-	"io"
-	"os"
-	"testing"
-	"time"
-
-	"sneak.berlin/go/pixa/internal/imageprocessor"
-	"sneak.berlin/go/pixa/internal/imagerequest"
-	"sneak.berlin/go/pixa/internal/magic"
-)
-
-// TestGetVariant_ContentTypeFromFirstBytes stores an image in each output
-// format as a variant and checks that GetVariant serves it whole with the
-// content type of its format, read from the file.
-func TestGetVariant_ContentTypeFromFirstBytes(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	processor := imageprocessor.New(imageprocessor.Params{})
-	source := generateTestJPEG(t, 40, 30, color.RGBA{200, 40, 40, 255})
-
-	for _, format := range []imagerequest.Format{
-		imagerequest.FormatJPEG, imagerequest.FormatPNG, imagerequest.FormatGIF,
-		imagerequest.FormatWebP, imagerequest.FormatAVIF, imagerequest.FormatJXL,
-	} {
-		result, err := processor.Process(t.Context(), bytes.NewReader(source),
-			&imagerequest.Transform{
-				Size:    imagerequest.Size{Width: 20, Height: 15},
-				Format:  format,
-				Quality: 85,
-				FitMode: imagerequest.FitCover,
-			})
-		if err != nil {
-			t.Fatalf("making a %s image: %v", format, err)
-		}
-
-		image, err := io.ReadAll(result.Content)
-		if err != nil {
-			t.Fatalf("reading the %s image: %v", format, err)
-		}
-
-		key := imagerequest.VariantKey("aabbccdd10" + string(format))
-
-		err = cache.StoreVariant(t.Context(), key, bytes.NewReader(image))
-		if err != nil {
-			t.Fatalf("StoreVariant(%s) error = %v", format, err)
-		}
-
-		reader, size, contentType, err := cache.GetVariant(key)
-		if err != nil {
-			t.Fatalf("GetVariant(%s) error = %v", format, err)
-		}
-
-		served, err := io.ReadAll(reader)
-		_ = reader.Close()
-
-		if err != nil {
-			t.Fatalf("reading the %s variant: %v", format, err)
-		}
-
-		t.Logf("%s: %d bytes served as %s", format, size, contentType)
-
-		if want := imageprocessor.FormatToMIME(format); contentType != want {
-			t.Errorf("%s variant content type = %q, want %q", format, contentType, want)
-		}
-
-		if size != int64(len(image)) || !bytes.Equal(served, image) {
-			t.Errorf("%s variant served %d bytes, size %d, want the %d bytes stored",
-				format, len(served), size, len(image))
-		}
-	}
-}
-
-// TestGetVariant_RefusesFileOfNoOutputFormat checks that GetVariant refuses
-// a variant file whose first bytes are not those of an output format, with
-// an error other than ErrNotFound, and that a variant with no file, or any
-// variant of a disabled cache, is ErrNotFound.
-func TestGetVariant_RefusesFileOfNoOutputFormat(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	jpegImage := generateTestJPEG(t, 10, 10, color.RGBA{0, 0, 255, 255})
-
-	tests := []struct {
-		name    string
-		content []byte
-		wantErr error
-	}{
-		{"text", []byte("this is text, not an image"), magic.ErrUnknownFormat},
-		{"SVG", []byte(`<svg xmlns="http://www.w3.org/2000/svg"></svg>`),
-			errNotAnOutputFormat},
-		{"JPEG cut to 10 bytes", jpegImage[:10], io.EOF},
-		{"empty", nil, io.EOF},
-	}
-
-	for i, tt := range tests {
-		key := imagerequest.VariantKey(fmt.Sprintf("aabbccdd20%02d", i))
-
-		_, err := cache.variants.Store(key, bytes.NewReader(tt.content))
-		if err != nil {
-			t.Fatalf("%s: storing the variant file: %v", tt.name, err)
-		}
-
-		reader, _, contentType, err := cache.GetVariant(key)
-		t.Logf("%s: GetVariant() error = %v", tt.name, err)
-
-		if reader != nil || contentType != "" || !errors.Is(err, tt.wantErr) {
-			t.Errorf("%s: GetVariant() = reader %v, content type %q, error %v; "+
-				"want no reader and %v", tt.name, reader, contentType, err, tt.wantErr)
-		}
-	}
-
-	reader, _, _, err := cache.GetVariant(testVariantKeyFour)
-	if reader != nil || !errors.Is(err, ErrNotFound) {
-		t.Errorf("GetVariant() of a variant with no file = reader %v, error %v; "+
-			"want no reader and %v", reader, err, ErrNotFound)
-	}
-
-	disabled, _ := newEvictionTestCache(t, 0)
-
-	reader, _, _, err = disabled.GetVariant(testVariantKeyOne)
-	if reader != nil || !errors.Is(err, ErrNotFound) {
-		t.Errorf("GetVariant() on a disabled cache = reader %v, error %v; "+
-			"want no reader and %v", reader, err, ErrNotFound)
-	}
-}
-
-// TestService_Get_MakesAgainVariantOfNoOutputFormat replaces a cached
-// variant's file with text, and checks that the next request is a miss
-// answered with the variant made again, and the one after a hit.
-func TestService_Get_MakesAgainVariantOfNoOutputFormat(t *testing.T) {
-	t.Parallel()
-
-	svc, fixtures := SetupTestService(t)
-	req := photoVariant(fixtures, 85, imagerequest.FitCover)
-
-	want, _ := getImage(t, svc, req)
-
-	path := svc.cache.variants.keyToPath(imagerequest.CacheKey(req))
-
-	err := os.WriteFile(path, []byte("this is text, not an image"), StorageFilePerm)
-	if err != nil {
-		t.Fatalf("replacing the variant file: %v", err)
-	}
-
-	got, status := getImage(t, svc, req)
-	t.Logf("after the replacement: %d bytes, %s", len(got), status)
-
-	if status != CacheMiss || !bytes.Equal(got, want) {
-		t.Errorf("after the replacement: Get() = %d bytes, %s; want the %d bytes "+
-			"made again, %s", len(got), status, len(want), CacheMiss)
-	}
-
-	got, status = getImage(t, svc, req)
-
-	if status != CacheHit || !bytes.Equal(got, want) {
-		t.Errorf("next request: Get() = %d bytes, %s; want the %d bytes, %s",
-			len(got), status, len(want), CacheHit)
-	}
-}
-
-// TestService_Get_HitWaitsForNoDatabaseWrite holds the database's one
-// connection while a cached variant is requested. The hit must be answered
-// while the connection is still held, and its access time must reach the
-// database once it is free.
-func TestService_Get_HitWaitsForNoDatabaseWrite(t *testing.T) {
-	t.Parallel()
-
-	svc, fixtures := SetupTestService(t)
-	req := photoVariant(fixtures, 85, imagerequest.FitCover)
-	key := imagerequest.CacheKey(req)
-
-	getImage(t, svc, req)
-
-	// Each connection to an in-memory SQLite database opens a new, empty one,
-	// so the goroutine that writes the access times must share the
-	// connection that holds the schema.
-	svc.cache.db.SetMaxOpenConns(1)
-	svc.cache.StartPendingAccessTimeWrites()
-
-	defer func() { _ = svc.cache.StopPendingAccessTimeWrites(t.Context()) }()
-
-	anHourAgo := time.Now().Add(-time.Hour)
-	setVariantLastAccessed(t, svc.cache, key, anHourAgo)
-
-	releaseDatabase := holdDatabase(t, svc.cache)
-	defer releaseDatabase()
-
-	results := startGet(t.Context(), svc, req)
-
-	select {
-	case got := <-results:
-		if got.err != nil {
-			t.Fatalf("Get() of the cached variant error = %v", got.err)
-		}
-	case <-time.After(pendingAccessTimesWait):
-		t.Fatal("the cache hit waited for the database")
-	}
-
-	releaseDatabase()
-
-	deadline := time.Now().Add(pendingAccessTimesWait)
-
-	for countRows(t, svc.cache, `
-		SELECT COUNT(*) FROM variant_content
-		WHERE cache_key = ? AND last_accessed_at > ?
-	`, string(key), anHourAgo.UTC().Format(sqliteTimestampFormat)) == 0 {
-		if time.Now().After(deadline) {
-			t.Fatal("the hit's access time was not written")
-		}
-
-		time.Sleep(10 * time.Millisecond)
-	}
-}
-
-// TestTouchVariantAndTouchSourceContent_DropAccessTimesPastTheLimit hands one
-// more access time of a variant, and one more of a source, than may wait to
-// be written. touchVariant and touchSourceContent must return each time
-// without waiting, and the last of each must be dropped.
-func TestTouchVariantAndTouchSourceContent_DropAccessTimesPastTheLimit(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-
-	done := make(chan struct{})
-
-	go func() {
-		defer close(done)
-
-		for range maxPendingAccessTimes + 1 {
-			cache.touchVariant(testVariantKeyOne)
-			cache.touchSourceContent("aabbccdd3001")
-		}
-	}()
-
-	select {
-	case <-done:
-	case <-time.After(pendingAccessTimesWait):
-		t.Fatal("touchVariant or touchSourceContent waited once the access " +
-			"times reached the limit")
-	}
-
-	if waiting := len(cache.pendingVariantAccessTimes); waiting != maxPendingAccessTimes {
-		t.Errorf("%d access times of variants wait to be written, want %d",
-			waiting, maxPendingAccessTimes)
-	}
-
-	if waiting := len(cache.pendingSourceAccessTimes); waiting != maxPendingAccessTimes {
-		t.Errorf("%d access times of sources wait to be written, want %d",
-			waiting, maxPendingAccessTimes)
-	}
-}
-
-// TestStopPendingAccessTimeWrites_WritesPendingAccessTimes hands the access
-// time of one of two variants, three times, then stops the goroutine that
-// writes them, which never started. The stop must write that access time and
-// leave the other variant's.
-func TestStopPendingAccessTimeWrites_WritesPendingAccessTimes(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	anHourAgo := time.Now().Add(-time.Hour)
-
-	for _, key := range []imagerequest.VariantKey{testVariantKeyOne, testVariantKeyTwo} {
-		storeEvictionTestVariant(t, cache, key, []byte("variant bytes"))
-		setVariantLastAccessed(t, cache, key, anHourAgo)
-	}
-
-	for range 3 {
-		cache.touchVariant(testVariantKeyOne)
-	}
-
-	err := cache.StopPendingAccessTimeWrites(t.Context())
-	if err != nil {
-		t.Fatalf("StopPendingAccessTimeWrites() error = %v", err)
-	}
-
-	for key, wantTouched := range map[imagerequest.VariantKey]int{
-		testVariantKeyOne: 1, testVariantKeyTwo: 0,
-	} {
-		touched := countRows(t, cache, `
-			SELECT COUNT(*) FROM variant_content
-			WHERE cache_key = ? AND last_accessed_at > ?
-		`, string(key), anHourAgo.UTC().Format(sqliteTimestampFormat))
-		if touched != wantTouched {
-			t.Errorf("variant %s: %d rows with a new access time, want %d",
-				key, touched, wantTouched)
-		}
-	}
-
-	if waiting := len(cache.pendingVariantAccessTimes); waiting != 0 {
-		t.Errorf("%d access times still wait to be written, want 0", waiting)
-	}
-}

internal/imgcache/cache_internal_test.go

@@ -1,14 +1,16 @@
 package imgcache
 
 import (
+	"bytes"
 	"context"
 	"database/sql"
 	"os"
 	"testing"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
 	_ "modernc.org/sqlite"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
+	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
 func setupTestDB(t *testing.T) *sql.DB {
@@ -22,18 +24,67 @@ func setupTestDB(t *testing.T) *sql.DB {
 	// Create schema
 	schema := `
 		CREATE TABLE source_content (
-			source_key TEXT PRIMARY KEY,
+			content_hash TEXT PRIMARY KEY,
+			content_type TEXT NOT NULL,
 			size_bytes INTEGER NOT NULL,
-			last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+			fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP
+		);
+		CREATE TABLE source_metadata (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			source_host TEXT NOT NULL,
+			source_path TEXT NOT NULL,
+			source_query TEXT NOT NULL DEFAULT '',
+			path_hash TEXT NOT NULL,
+			content_hash TEXT,
+			status_code INTEGER NOT NULL,
+			content_type TEXT,
+			response_headers TEXT,
+			fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+			expires_at DATETIME,
+			etag TEXT,
+			last_modified TEXT,
+			UNIQUE(source_host, source_path, source_query)
+		);
+		CREATE TABLE output_content (
+			content_hash TEXT PRIMARY KEY,
+			content_type TEXT NOT NULL,
+			size_bytes INTEGER NOT NULL,
+			fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP
+		);
+		CREATE TABLE request_cache (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			cache_key TEXT NOT NULL UNIQUE,
+			source_metadata_id INTEGER NOT NULL,
+			output_hash TEXT NOT NULL,
+			width INTEGER NOT NULL,
+			height INTEGER NOT NULL,
+			format TEXT NOT NULL,
+			quality INTEGER NOT NULL DEFAULT 85,
+			fit_mode TEXT NOT NULL DEFAULT 'cover',
+			fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+			access_count INTEGER NOT NULL DEFAULT 1
 		);
 		CREATE TABLE negative_cache (
 			id INTEGER PRIMARY KEY AUTOINCREMENT,
 			source_host TEXT NOT NULL,
 			source_path TEXT NOT NULL,
 			source_query TEXT NOT NULL DEFAULT '',
+			status_code INTEGER NOT NULL,
+			error_message TEXT,
+			fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 			expires_at DATETIME NOT NULL,
 			UNIQUE(source_host, source_path, source_query)
 		);
+		CREATE TABLE cache_stats (
+			id INTEGER PRIMARY KEY CHECK (id = 1),
+			hit_count INTEGER NOT NULL DEFAULT 0,
+			miss_count INTEGER NOT NULL DEFAULT 0,
+			upstream_fetch_count INTEGER NOT NULL DEFAULT 0,
+			upstream_fetch_bytes INTEGER NOT NULL DEFAULT 0,
+			transform_count INTEGER NOT NULL DEFAULT 0,
+			last_updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+		);
+		INSERT INTO cache_stats (id) VALUES (1);
 	`
 
 	_, err = db.ExecContext(t.Context(), schema)
@@ -44,6 +95,389 @@ func setupTestDB(t *testing.T) *sql.DB {
 	return db
 }
 
+func setupTestCache(t *testing.T) *Cache {
+	t.Helper()
+
+	tmpDir := t.TempDir()
+	db := setupTestDB(t)
+
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    tmpDir,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatalf("failed to create cache: %v", err)
+	}
+
+	return cache
+}
+
+func TestCache_LookupMiss(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: testPathCat,
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 800, Height: 600},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.FitCover,
+		},
+	}
+
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v", err)
+	}
+
+	if result.Hit {
+		t.Error("Lookup() hit = true, want false for cache miss")
+	}
+
+	if result.CacheStatus != CacheMiss {
+		t.Errorf("Lookup() status = %v, want %v", result.CacheStatus, CacheMiss)
+	}
+}
+
+func TestCache_StoreAndLookup(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: testPathCat,
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 800, Height: 600},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.FitCover,
+		},
+	}
+
+	// Store source content
+	sourceContent := []byte("fake jpeg data")
+	fetchResult := &httpfetcher.FetchResult{
+		ContentType: testContentTypeJPEG,
+		Headers:     map[string][]string{testHeaderContentType: {testContentTypeJPEG}},
+	}
+
+	contentHash, err := cache.StoreSource(
+		ctx, req, bytes.NewReader(sourceContent), fetchResult)
+	if err != nil {
+		t.Fatalf("StoreSource() error = %v", err)
+	}
+
+	if contentHash == "" {
+		t.Error("StoreSource() returned empty hash")
+	}
+
+	// Store variant
+	cacheKey := imagerequest.CacheKey(req)
+	outputContent := []byte("fake webp data")
+
+	err = cache.StoreVariant(
+		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
+	if err != nil {
+		t.Fatalf("StoreVariant() error = %v", err)
+	}
+
+	// Now lookup should hit
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v", err)
+	}
+
+	if !result.Hit {
+		t.Error("Lookup() hit = false, want true after store")
+	}
+
+	if result.CacheStatus != CacheHit {
+		t.Errorf("Lookup() status = %v, want %v", result.CacheStatus, CacheHit)
+	}
+
+	if result.CacheKey == "" {
+		t.Error("Lookup() returned empty cache key")
+	}
+}
+
+func TestCache_NegativeCache(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: "/photos/notfound.jpg",
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 800, Height: 600},
+			Format: imagerequest.FormatWebP,
+		},
+	}
+
+	// Store negative cache entry
+	err := cache.StoreNegative(ctx, req, 404, "not found")
+	if err != nil {
+		t.Fatalf("StoreNegative() error = %v", err)
+	}
+
+	// Lookup should return miss (negative cache is checked at service level)
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v", err)
+	}
+
+	if result.Hit {
+		t.Error("Lookup() hit = true, want false for negative cache entry")
+	}
+}
+
+func TestCache_NegativeCacheExpiry(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+	db := setupTestDB(t)
+
+	// Very short negative TTL for testing
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    tmpDir,
+		NegativeTTL: 1 * time.Millisecond,
+	})
+	if err != nil {
+		t.Fatalf("failed to create cache: %v", err)
+	}
+
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: "/photos/expired.jpg",
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 800, Height: 600},
+			Format: imagerequest.FormatWebP,
+		},
+	}
+
+	// Store negative cache entry
+	err = cache.StoreNegative(ctx, req, 404, "not found")
+	if err != nil {
+		t.Fatalf("StoreNegative() error = %v", err)
+	}
+
+	// Wait for expiry
+	time.Sleep(10 * time.Millisecond)
+
+	// Lookup should return miss after expiry
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v, want nil after expiry", err)
+	}
+
+	if result.Hit {
+		t.Error("Lookup() hit = true, want false after negative cache expiry")
+	}
+}
+
+func TestCache_VariantLookup(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: "/photos/variant.jpg",
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 800, Height: 600},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.FitCover,
+		},
+	}
+
+	// Store variant
+	cacheKey := imagerequest.CacheKey(req)
+	outputContent := []byte("output data")
+
+	err := cache.StoreVariant(
+		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
+	if err != nil {
+		t.Fatalf("StoreVariant() error = %v", err)
+	}
+
+	// First lookup
+	result1, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() first error = %v", err)
+	}
+
+	if !result1.Hit {
+		t.Error("Lookup() first hit = false")
+	}
+
+	// Second lookup should also hit (from disk)
+	result2, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() second error = %v", err)
+	}
+
+	if !result2.Hit {
+		t.Error("Lookup() second hit = false")
+	}
+
+	if result1.CacheKey != result2.CacheKey {
+		t.Error("Lookup() returned different cache keys")
+	}
+}
+
+func TestCache_GetVariant_ReturnsContentType(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: "/photos/variantct.jpg",
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 800, Height: 600},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.FitCover,
+		},
+	}
+
+	// Store variant
+	cacheKey := imagerequest.CacheKey(req)
+	outputContent := []byte("output webp data")
+
+	err := cache.StoreVariant(
+		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
+	if err != nil {
+		t.Fatalf("StoreVariant() error = %v", err)
+	}
+
+	// Lookup
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v", err)
+	}
+
+	if !result.Hit {
+		t.Fatal("Lookup() hit = false, want true")
+	}
+
+	// GetVariant should return content type
+	reader, size, contentType, err := cache.GetVariant(result.CacheKey)
+	if err != nil {
+		t.Fatalf("GetVariant() error = %v", err)
+	}
+
+	defer func() { _ = reader.Close() }()
+
+	if contentType != "image/webp" {
+		t.Errorf("GetVariant() ContentType = %q, want %q", contentType, "image/webp")
+	}
+
+	if size != int64(len(outputContent)) {
+		t.Errorf("GetVariant() size = %d, want %d", size, len(outputContent))
+	}
+}
+
+func TestCache_GetVariant(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: "/photos/output.jpg",
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 800, Height: 600},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.FitCover,
+		},
+	}
+
+	// Store variant
+	cacheKey := imagerequest.CacheKey(req)
+	outputContent := []byte("the actual output content")
+
+	err := cache.StoreVariant(
+		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
+	if err != nil {
+		t.Fatalf("StoreVariant() error = %v", err)
+	}
+
+	// Lookup to get cache key
+	result, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup() error = %v", err)
+	}
+
+	// Get variant content
+	reader, _, _, err := cache.GetVariant(result.CacheKey)
+	if err != nil {
+		t.Fatalf("GetVariant() error = %v", err)
+	}
+
+	defer func() { _ = reader.Close() }()
+
+	buf := make([]byte, 100)
+	n, _ := reader.Read(buf)
+
+	if !bytes.Equal(buf[:n], outputContent) {
+		t.Errorf("GetVariant() content = %q, want %q", buf[:n], outputContent)
+	}
+}
+
+func TestCache_Stats(t *testing.T) {
+	t.Parallel()
+
+	cache := setupTestCache(t)
+	ctx := context.Background()
+
+	// Increment some stats
+	cache.IncrementStats(ctx, true, 0)
+	cache.IncrementStats(ctx, true, 0)
+	cache.IncrementStats(ctx, false, 1024)
+
+	stats, err := cache.Stats(ctx)
+	if err != nil {
+		t.Fatalf("Stats() error = %v", err)
+	}
+
+	if stats.HitCount != 2 {
+		t.Errorf("Stats() HitCount = %d, want 2", stats.HitCount)
+	}
+
+	if stats.MissCount != 1 {
+		t.Errorf("Stats() MissCount = %d, want 1", stats.MissCount)
+	}
+}
+
 func TestCache_CleanExpired(t *testing.T) {
 	t.Parallel()
 
@@ -53,15 +487,15 @@ func TestCache_CleanExpired(t *testing.T) {
 	cache, _ := NewCache(db, CacheConfig{
 		StateDir:    tmpDir,
 		NegativeTTL: 1 * time.Millisecond,
-	}, prometheus.NewRegistry())
+	})
 
 	ctx := context.Background()
 
 	// Insert expired negative cache entry directly
 	_, err := db.ExecContext(ctx, `
 		INSERT INTO negative_cache
-			(source_host, source_path, source_query, expires_at)
+			(source_host, source_path, source_query, status_code, expires_at)
-		VALUES ('example.com', '/old.jpg', '', datetime('now', '-1 hour'))
+		VALUES ('example.com', '/old.jpg', '', 404, datetime('now', '-1 hour'))
 	`)
 	if err != nil {
 		t.Fatalf("failed to insert test data: %v", err)
@@ -104,7 +538,7 @@ func TestCache_StorageDirectoriesCreated(t *testing.T) {
 
 	_, err := NewCache(db, CacheConfig{
 		StateDir: tmpDir,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("NewCache() error = %v", err)
 	}
@@ -113,6 +547,7 @@ func TestCache_StorageDirectoriesCreated(t *testing.T) {
 	dirs := []string{
 		"cache/sources",
 		"cache/variants",
+		"cache/metadata",
 	}
 
 	for _, dir := range dirs {

internal/imgcache/cache_usage_internal_test.go

@@ -31,10 +31,10 @@ func TestEvictionReadsTheUsageTotal(t *testing.T) {
 	storeEvictionTestVariant(t, cache, testVariantKeyTwo,
 		bytes.Repeat([]byte{0x75}, 200))
 
-	// Storing a source URL again changes its size, so the total must
+	// pixa never changes a source's size, but a statement that does must
-	// follow a statement that changes it.
+	// change the total too.
 	_, err := cache.db.ExecContext(ctx,
-		`UPDATE source_content SET size_bytes = 900 WHERE source_key = ?`,
+		`UPDATE source_content SET size_bytes = 900 WHERE content_hash = ?`,
 		string(kept))
 	if err != nil {
 		t.Fatalf("failed to change the source's size: %v", err)
@@ -155,9 +155,8 @@ func TestUsageTotalNotCorrectedFromAnOlderSum(t *testing.T) {
 // pass. No read the pass makes of a content table, to check its rows or
 // to sum them, may cover more than two rows, so a request's query waits
 // for one page at most. Between them the reads must still cover every
-// variant row twice, once to check it and once to sum it, and every
+// row of both tables twice, once to check it and once to sum it, and the
-// source row once, as source rows are read only to sum them, and the sum
+// sum must put a wrong total right.
-// must put a wrong total right.
 func TestReconciliationReadsAPageAtATime(t *testing.T) {
 	t.Parallel()
 
@@ -208,10 +207,9 @@ func TestReconciliationReadsAPageAtATime(t *testing.T) {
 		coveredRows += rows
 	}
 
-	// Five variant rows, each read once to check it and once to sum it,
+	// Ten rows, each read once to check it and once to sum it.
-	// and five source rows, read only to sum them.
+	if coveredRows != 20 {
-	if coveredRows != 15 {
+		t.Errorf("the reads covered %d rows in all, want 20", coveredRows)
-		t.Errorf("the reads covered %d rows in all, want 15", coveredRows)
 	}
 
 	usage, err := cache.UsageBytes(ctx)

internal/imgcache/cachesize_internal_test.go

@@ -6,8 +6,6 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-
-	"github.com/prometheus/client_golang/prometheus"
 )
 
 // Static errors returned by the stub free-space probes below.
@@ -41,8 +39,9 @@ func TestComputeDefaultMaxBytesCountsWhatTheCacheHolds(t *testing.T) {
 
 	// 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) VALUES (?, ?)`,
+		`INSERT INTO variant_content (cache_key, size_bytes, content_type)
-		string(testVariantKeyOne), 3221225472,
+		 VALUES (?, ?, ?)`,
+		string(testVariantKeyOne), 3221225472, testContentTypeWebP,
 	)
 	if err != nil {
 		t.Fatalf("failed to insert variant accounting row: %v", err)
@@ -146,7 +145,7 @@ func TestNewCacheComputesDefaultMaxBytesWhenAsked(t *testing.T) {
 	cache, err := newCache(evictionTestDB(t), CacheConfig{
 		StateDir:           stateDir,
 		UseDefaultMaxBytes: true,
-	}, prometheus.NewRegistry(), probe)
+	}, probe)
 	if err != nil {
 		t.Fatalf("newCache returned error: %v", err)
 	}
@@ -177,7 +176,7 @@ func TestNewCacheKeepsExplicitMaxBytes(t *testing.T) {
 	cache, err := newCache(evictionTestDB(t), CacheConfig{
 		StateDir: t.TempDir(),
 		MaxBytes: 1024,
-	}, prometheus.NewRegistry(), probe)
+	}, probe)
 	if err != nil {
 		t.Fatalf("newCache returned error: %v", err)
 	}

internal/imgcache/concurrent_misses_internal_test.go

@@ -191,9 +191,9 @@ func TestService_Get_ConcurrentMissesShareOneFetch(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	want := counterValues{0, requests, 1, int64(len(photo)), 1}
+	want := cacheStatsCounters{0, requests, 1, int64(len(photo)), 1}
 
-	if got := readCounters(svc.cache); got != want {
+	if got := readCacheStatsCounters(t, svc.cache); got != want {
 		t.Errorf("counters = %+v, want %+v", got, want)
 	}
 }

internal/imgcache/contentlock.go

@@ -0,0 +1,64 @@
+package imgcache
+
+import "sync"
+
+// contentLock provides per-key mutual exclusion for content-hash keyed
+// operations. StoreSource and evictSourceBlob each hold a content
+// hash's lock for the full duration of their file-plus-accounting-row
+// work, so a store and an eviction racing on identical content bytes
+// (the real SHA-256 content-addressed dedup case, not a contrived one)
+// can never interleave: the unlink of an evicted blob's file can never
+// race the creation of a fresh database row for a concurrently
+// re-stored copy of the same content. Entries are removed once no
+// goroutine holds or is waiting for them, so a long-running process
+// does not accumulate memory proportional to the number of distinct
+// content hashes it has ever seen.
+type contentLock struct {
+	mu      sync.Mutex
+	entries map[string]*contentLockEntry
+}
+
+// contentLockEntry is one key's exclusion lock plus a count of
+// goroutines currently holding or waiting to acquire it, used to know
+// when it is safe to remove the entry from the map.
+type contentLockEntry struct {
+	mu    sync.Mutex
+	count int
+}
+
+// newContentLock creates an empty contentLock.
+func newContentLock() *contentLock {
+	return &contentLock{entries: make(map[string]*contentLockEntry)}
+}
+
+// Lock acquires exclusive access for key, blocking until it is
+// available, and returns a function that releases it. The caller must
+// invoke the returned function exactly once to release the lock.
+func (c *contentLock) Lock(key string) func() {
+	c.mu.Lock()
+
+	entry, ok := c.entries[key]
+	if !ok {
+		entry = &contentLockEntry{}
+		c.entries[key] = entry
+	}
+
+	entry.count++
+
+	c.mu.Unlock()
+
+	entry.mu.Lock()
+
+	return func() {
+		entry.mu.Unlock()
+
+		c.mu.Lock()
+
+		entry.count--
+		if entry.count == 0 {
+			delete(c.entries, key)
+		}
+
+		c.mu.Unlock()
+	}
+}

internal/imgcache/contentlock_internal_test.go

@@ -0,0 +1,142 @@
+package imgcache
+
+import (
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestContentLockExcludesSameKey verifies that two goroutines locking
+// the same key never run their critical sections concurrently.
+func TestContentLockExcludesSameKey(t *testing.T) {
+	t.Parallel()
+
+	lock := newContentLock()
+
+	var (
+		active  atomic.Int32
+		maxSeen int32
+		wg      sync.WaitGroup
+	)
+
+	const goroutines = 20
+
+	wg.Add(goroutines)
+
+	for range goroutines {
+		go func() {
+			defer wg.Done()
+
+			unlock := lock.Lock("same-key")
+			defer unlock()
+
+			n := active.Add(1)
+
+			for {
+				seen := atomic.LoadInt32(&maxSeen)
+				if n <= seen || atomic.CompareAndSwapInt32(&maxSeen, seen, n) {
+					break
+				}
+			}
+
+			time.Sleep(time.Millisecond)
+
+			active.Add(-1)
+		}()
+	}
+
+	wg.Wait()
+
+	if maxSeen != 1 {
+		t.Errorf("max concurrent holders of the same key = %d, want 1", maxSeen)
+	}
+}
+
+// TestContentLockAllowsDifferentKeys verifies that locking distinct
+// keys does not serialize unrelated work: all goroutines must be able
+// to enter their critical sections at once, proven by every one of
+// them reaching the rendezvous point before any is allowed to
+// proceed.
+func TestContentLockAllowsDifferentKeys(t *testing.T) {
+	t.Parallel()
+
+	lock := newContentLock()
+
+	const goroutines = 20
+
+	var (
+		wg      sync.WaitGroup
+		inside  atomic.Int32
+		reached = make(chan struct{}, goroutines)
+	)
+
+	wg.Add(goroutines)
+
+	release := make(chan struct{})
+
+	for i := range goroutines {
+		key := string(rune('a' + i))
+
+		go func() {
+			defer wg.Done()
+
+			unlock := lock.Lock(key)
+			defer unlock()
+
+			inside.Add(1)
+
+			reached <- struct{}{}
+
+			<-release
+		}()
+	}
+
+	// Every goroutine must reach the rendezvous point (i.e. acquire its
+	// own key's lock) without needing any other to release first. If
+	// keys were incorrectly serialized onto one underlying lock, only
+	// one would get here and this would time out.
+	for i := range goroutines {
+		select {
+		case <-reached:
+		case <-time.After(2 * time.Second):
+			t.Fatalf("only %d/%d goroutines locking distinct keys made progress; "+
+				"keys may be incorrectly serialized", i, goroutines)
+		}
+	}
+
+	if n := inside.Load(); n != goroutines {
+		t.Errorf("goroutines inside their critical section = %d, want %d",
+			n, goroutines)
+	}
+
+	close(release)
+	wg.Wait()
+}
+
+// TestContentLockRemovesEntryAfterUnlock verifies that the internal
+// entries map does not grow without bound: once no goroutine holds or
+// awaits a key, its entry is removed.
+func TestContentLockRemovesEntryAfterUnlock(t *testing.T) {
+	t.Parallel()
+
+	lock := newContentLock()
+
+	unlock := lock.Lock("k")
+
+	lock.mu.Lock()
+	if _, ok := lock.entries["k"]; !ok {
+		lock.mu.Unlock()
+		t.Fatal("entry missing while lock is held")
+	}
+	lock.mu.Unlock()
+
+	unlock()
+
+	lock.mu.Lock()
+	defer lock.mu.Unlock()
+
+	if _, ok := lock.entries["k"]; ok {
+		t.Error("entry for key still present after the last holder unlocked")
+	}
+}

internal/imgcache/counters.go

@@ -1,45 +0,0 @@
-package imgcache
-
-import (
-	"fmt"
-
-	"github.com/prometheus/client_golang/prometheus"
-)
-
-// registerCounters makes the cache's counters and registers them on
-// metricsRegistry. The counters are kept in memory, so adding to one waits
-// for nothing and makes no database call. It fails when metricsRegistry
-// already holds counters of the same names.
-func (c *Cache) registerCounters(metricsRegistry prometheus.Registerer) error {
-	c.cacheHits = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "pixa_cache_hits_total",
-		Help: "Image requests served from the cache.",
-	})
-	c.cacheMisses = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "pixa_cache_misses_total",
-		Help: "Image requests not served from the cache.",
-	})
-	c.upstreamFetches = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "pixa_upstream_fetches_total",
-		Help: "Fetches of a source image from upstream that read any bytes.",
-	})
-	c.upstreamFetchBytes = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "pixa_upstream_fetch_bytes_total",
-		Help: "Bytes read from upstream by fetches of source images.",
-	})
-	c.transforms = prometheus.NewCounter(prometheus.CounterOpts{
-		Name: "pixa_transforms_total",
-		Help: "Images the image processor transformed.",
-	})
-
-	for _, counter := range []prometheus.Counter{
-		c.cacheHits, c.cacheMisses, c.upstreamFetches, c.upstreamFetchBytes, c.transforms,
-	} {
-		err := metricsRegistry.Register(counter)
-		if err != nil {
-			return fmt.Errorf("failed to register the cache's counters: %w", err)
-		}
-	}
-
-	return nil
-}

internal/imgcache/counters_internal_test.go

@@ -1,84 +0,0 @@
-package imgcache
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/prometheus/client_golang/prometheus"
-	"github.com/prometheus/client_golang/prometheus/testutil"
-)
-
-// counterValues holds the values of a cache's counters.
-type counterValues struct {
-	hitCount           int64
-	missCount          int64
-	upstreamFetchCount int64
-	upstreamFetchBytes int64
-	transformCount     int64
-}
-
-// readCounters reads cache's counters.
-func readCounters(cache *Cache) counterValues {
-	return counterValues{
-		hitCount:           int64(testutil.ToFloat64(cache.cacheHits)),
-		missCount:          int64(testutil.ToFloat64(cache.cacheMisses)),
-		upstreamFetchCount: int64(testutil.ToFloat64(cache.upstreamFetches)),
-		upstreamFetchBytes: int64(testutil.ToFloat64(cache.upstreamFetchBytes)),
-		transformCount:     int64(testutil.ToFloat64(cache.transforms)),
-	}
-}
-
-// TestNewCache_RegistersItsCountersOnItsRegistry checks that NewCache
-// registers the cache's counters on the registry it is given, under the
-// names README.md gives them.
-func TestNewCache_RegistersItsCountersOnItsRegistry(t *testing.T) {
-	t.Parallel()
-
-	registry := prometheus.NewRegistry()
-
-	_, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()}, registry)
-	if err != nil {
-		t.Fatalf("NewCache() error = %v", err)
-	}
-
-	names := []string{
-		"pixa_cache_hits_total",
-		"pixa_cache_misses_total",
-		"pixa_upstream_fetches_total",
-		"pixa_upstream_fetch_bytes_total",
-		"pixa_transforms_total",
-	}
-
-	count, err := testutil.GatherAndCount(registry, names...)
-	if err != nil {
-		t.Fatalf("testutil.GatherAndCount() error = %v", err)
-	}
-
-	if count != len(names) {
-		t.Errorf("%d of the counters %v are on the registry, want %d",
-			count, names, len(names))
-	}
-}
-
-// TestNewCache_FailsWhenItsCountersCannotBeRegistered makes a second cache
-// on the registry of a first. Its counters have the same names, so the
-// registry refuses them, and NewCache must return that error.
-func TestNewCache_FailsWhenItsCountersCannotBeRegistered(t *testing.T) {
-	t.Parallel()
-
-	registry := prometheus.NewRegistry()
-
-	_, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()}, registry)
-	if err != nil {
-		t.Fatalf("NewCache() of the first cache error = %v", err)
-	}
-
-	_, err = NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()}, registry)
-	t.Logf("NewCache() of the second cache error = %v", err)
-
-	var alreadyRegistered prometheus.AlreadyRegisteredError
-	if !errors.As(err, &alreadyRegistered) {
-		t.Errorf("NewCache() of the second cache error = %v, want %T",
-			err, alreadyRegistered)
-	}
-}

internal/imgcache/eviction.go

@@ -3,6 +3,7 @@ package imgcache
 import (
 	"context"
 	"database/sql"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io/fs"
@@ -51,6 +52,14 @@ const sqliteTimestampLayout = "2006-01-02 15:04:05"
 // writes (".tmp-*" patterns in the storage layer).
 const tempFilePrefix = ".tmp-"
 
+// variantMetaSuffix is the sidecar suffix VariantStorage writes next
+// to each variant file.
+const variantMetaSuffix = ".meta"
+
+// fallbackContentType is the content type given to a variant file that
+// 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
 // tracked in the database (source content blobs plus processed
 // variants). It reads the total the database keeps up to date as rows
@@ -75,11 +84,11 @@ func (c *Cache) UsageBytes(ctx context.Context) (int64, error) {
 
 // evictionCandidate is one LRU eviction victim candidate: either a
 // processed variant (isVariant true, identified by cacheKey) or a
-// source content blob (identified by sourceKey).
+// source content blob (identified by contentHash).
 type evictionCandidate struct {
 	isVariant      bool
 	cacheKey       imagerequest.VariantKey
-	sourceKey      imagerequest.SourceKey
+	contentHash    ContentHash
 	sizeBytes      int64
 	lastAccessedAt string
 }
@@ -151,7 +160,7 @@ func (c *Cache) evictBatch(ctx context.Context, excessBytes int64) (int64, error
 
 			c.log.Warn("failed to evict cache entry",
 				"cache_key", candidate.cacheKey,
-				"source_key", candidate.sourceKey,
+				"content_hash", candidate.contentHash,
 				"error", err,
 			)
 
@@ -170,7 +179,7 @@ func (c *Cache) evictCandidate(ctx context.Context, candidate evictionCandidate)
 		return c.evictVariant(ctx, candidate.cacheKey)
 	}
 
-	return c.evictSourceBlob(ctx, candidate.sourceKey)
+	return c.evictSourceBlob(ctx, candidate.contentHash)
 }
 
 // evictionCandidates returns up to evictionBatchSize variants and
@@ -250,9 +259,9 @@ func (c *Cache) variantCandidates(ctx context.Context) ([]evictionCandidate, err
 // SQLite reads the rows in order from that column's index instead of
 // sorting the whole table.
 const sourceCandidatesQuery = `
-	SELECT source_key, size_bytes, last_accessed_at
+	SELECT content_hash, size_bytes, last_accessed_at
 	FROM source_content
-	ORDER BY last_accessed_at ASC, source_key ASC
+	ORDER BY last_accessed_at ASC, content_hash ASC
 	LIMIT ?`
 
 // sourceCandidates returns the least recently used source blobs.
@@ -269,14 +278,14 @@ func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, erro
 	for rows.Next() {
 		var candidate evictionCandidate
 
-		var key string
+		var hash string
 
-		err := rows.Scan(&key, &candidate.sizeBytes, &candidate.lastAccessedAt)
+		err := rows.Scan(&hash, &candidate.sizeBytes, &candidate.lastAccessedAt)
 		if err != nil {
 			return nil, fmt.Errorf("failed to scan source candidate: %w", err)
 		}
 
-		candidate.sourceKey = imagerequest.SourceKey(key)
+		candidate.contentHash = ContentHash(hash)
 		candidates = append(candidates, candidate)
 	}
 
@@ -289,7 +298,10 @@ func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, erro
 }
 
 // evictVariant removes one variant: accounting row first, then the
-// file, so the database never references a deleted file.
+// content and .meta files, so the database never references a deleted
+// 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 imagerequest.VariantKey,
 ) error {
@@ -299,6 +311,8 @@ func (c *Cache) evictVariant(
 		return fmt.Errorf("failed to delete variant accounting row: %w", err)
 	}
 
+	c.metaCache.Remove(cacheKey)
+
 	err = c.variants.Delete(cacheKey)
 	if err != nil {
 		return err
@@ -307,18 +321,117 @@ func (c *Cache) evictVariant(
 	return nil
 }
 
-// evictSourceBlob removes one source: its row first, then its file, as
+// sourceReference identifies one source_metadata row's JSON sidecar.
-// evictVariant does for a variant. It holds no lock: a store of the same
+type sourceReference struct {
-// source in between can leave the source's row with no file, which
+	host     string
-// LookupSource treats as a miss.
+	pathHash PathHash
-func (c *Cache) evictSourceBlob(ctx context.Context, key imagerequest.SourceKey) error {
+}
-	_, err := c.db.ExecContext(ctx,
+
-		`DELETE FROM source_content WHERE source_key = ?`, string(key))
+// evictSourceBlob removes one source content blob. All source_metadata
+// rows referencing the blob are deleted together with its
+// source_content row in a single transaction BEFORE the file is
+// unlinked: a blob referenced by multiple source paths is only ever
+// removed together with all of its references, and database rows never
+// point at deleted files. The JSON metadata sidecars for the removed
+// rows are deleted afterwards.
+//
+// The whole operation holds the content hash's lock (the same one
+// StoreSource holds for its full store), so a concurrent store of
+// identical content bytes can never observe the file gone but a row
+// still present, or insert a fresh row between this transaction's
+// commit and the file unlink below: it either runs entirely before
+// this eviction starts, or is blocked until this eviction (row
+// deletion and unlink together) has fully completed.
+func (c *Cache) evictSourceBlob(ctx context.Context, contentHash ContentHash) error {
+	unlock := c.contentLocks.Lock(string(contentHash))
+	defer unlock()
+
+	references, err := c.sourceReferences(ctx, contentHash)
+	if err != nil {
+		return err
+	}
+
+	tx, err := c.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("failed to begin eviction transaction: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	_, err = tx.ExecContext(ctx,
+		`DELETE FROM source_metadata WHERE content_hash = ?`, string(contentHash))
+	if err != nil {
+		return fmt.Errorf("failed to delete source metadata rows: %w", err)
+	}
+
+	_, err = tx.ExecContext(ctx,
+		`DELETE FROM source_content WHERE content_hash = ?`, string(contentHash))
 	if err != nil {
 		return fmt.Errorf("failed to delete source content row: %w", err)
 	}
 
-	return c.srcContent.Delete(key)
+	err = tx.Commit()
+	if err != nil {
+		return fmt.Errorf("failed to commit eviction transaction: %w", err)
+	}
+
+	if c.evictSourceBlobTestHook != nil {
+		c.evictSourceBlobTestHook(contentHash)
+	}
+
+	// Only after the rows are gone may the files be removed.
+	for _, reference := range references {
+		err := c.srcMetadata.Delete(reference.host, reference.pathHash)
+		if err != nil {
+			c.log.Warn("failed to delete metadata sidecar",
+				"host", reference.host, "path_hash", reference.pathHash, "error", err)
+		}
+	}
+
+	err = c.srcContent.Delete(contentHash)
+	if err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// sourceReferences lists the metadata sidecar locations of every
+// source_metadata row referencing the given blob.
+func (c *Cache) sourceReferences(
+	ctx context.Context, contentHash ContentHash,
+) ([]sourceReference, error) {
+	rows, err := c.db.QueryContext(ctx, `
+		SELECT source_host, path_hash FROM source_metadata WHERE content_hash = ?
+	`, string(contentHash))
+	if err != nil {
+		return nil, fmt.Errorf("failed to query source references: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var references []sourceReference
+
+	for rows.Next() {
+		var reference sourceReference
+
+		var pathHash string
+
+		err := rows.Scan(&reference.host, &pathHash)
+		if err != nil {
+			return nil, fmt.Errorf("failed to scan source reference: %w", err)
+		}
+
+		reference.pathHash = PathHash(pathHash)
+		references = append(references, reference)
+	}
+
+	err = rows.Err()
+	if err != nil {
+		return nil, fmt.Errorf("source reference iteration failed: %w", err)
+	}
+
+	return references, nil
 }
 
 // notifyWritePressure wakes the background evictor after a store, so
@@ -473,12 +586,12 @@ func (c *Cache) runCleanExpired(ctx context.Context) {
 // as long after the last pass ended as that pass took, off the request
 // hot path: it adopts variant files that predate the accounting table
 // (or whose accounting insert failed, e.g. StoreVariant's best-effort
-// insert under transient DB contention), drops variant accounting rows
+// insert under transient DB contention), drops accounting rows whose
-// whose files are missing, removes source blob files the database does
+// files are missing, removes source blob files the database does not
-// not know, removes source and variant files that are empty or not the
+// know (and rows whose files are gone), removes source and variant files
-// size their rows record, sweeps stale temp files left behind by crashed
+// that are empty or not the size their rows record, sweeps stale temp
-// writes, and last checks the total cache usage against the tables. It
+// files left behind by crashed writes, and last checks the total cache
-// reads the tables a page at a time.
+// usage against the tables. It reads the tables a page at a time.
 // Running it periodically, not just once, bounds how long such drift can
 // accumulate unaccounted for on a long-running process to about one
 // eviction interval plus ten times the last pass's time.
@@ -504,19 +617,20 @@ func (c *Cache) reconcileAccounting(ctx context.Context) error {
 		return err
 	}
 
+	err = c.reconcileSourceRows(ctx)
+	if err != nil {
+		return err
+	}
+
 	return c.reconcileUsageTotal(ctx)
 }
 
-// reconcileFiles walks baseDir, one of the cache's storage directories,
+// reconcileVariantFiles walks the variant storage directory, checking
-// sweeping stale temp files and passing each other file, with its name, to
+// each variant file against its accounting row (reconcileVariantFile)
-// reconcileFile. Once ctx is cancelled it stops at the next file and
+// and sweeping stale temp files.
-// returns ctx's error.
+func (c *Cache) reconcileVariantFiles(ctx context.Context) error {
-func (c *Cache) reconcileFiles(
-	ctx context.Context, baseDir string,
-	reconcileFile func(path string, entry fs.DirEntry, name string) error,
-) error {
 	return filepath.WalkDir(
-		baseDir,
+		c.variants.baseDir,
 		func(path string, entry fs.DirEntry, err error) error {
 			if ctx.Err() != nil {
 				return ctx.Err()
@@ -534,19 +648,13 @@ func (c *Cache) reconcileFiles(
 				return nil
 			}
 
-			return reconcileFile(path, entry, name)
+			if strings.HasSuffix(name, variantMetaSuffix) {
-		},
+				return nil
-	)
 			}
 
-// reconcileVariantFiles walks the variant storage directory, checking
-// each variant file against its accounting row (reconcileVariantFile)
-// and sweeping stale temp files.
-func (c *Cache) reconcileVariantFiles(ctx context.Context) error {
-	return c.reconcileFiles(ctx, c.variants.baseDir,
-		func(path string, entry fs.DirEntry, name string) error {
 			return c.reconcileVariantFile(ctx, path, entry, imagerequest.VariantKey(name))
-		})
+		},
+	)
 }
 
 // reconcileVariantFile checks one variant file against its accounting
@@ -570,7 +678,7 @@ func (c *Cache) reconcileVariantFile(
 
 	switch {
 	case errors.Is(err, sql.ErrNoRows) && info.Size() > 0:
-		return c.adoptVariantFile(ctx, info, cacheKey)
+		return c.adoptVariantFile(ctx, path, info, cacheKey)
 	case err != nil && !errors.Is(err, sql.ErrNoRows):
 		return fmt.Errorf("failed to check variant accounting row: %w", err)
 	case info.Size() > 0 && info.Size() == recordedSize:
@@ -587,14 +695,16 @@ func (c *Cache) reconcileVariantFile(
 // adoptVariantFile inserts an accounting row for a variant file that
 // has none, using the file's size and modification time.
 func (c *Cache) adoptVariantFile(
-	ctx context.Context, info fs.FileInfo, cacheKey imagerequest.VariantKey,
+	ctx context.Context, path string, info fs.FileInfo, cacheKey imagerequest.VariantKey,
 ) error {
 	modTime := info.ModTime().UTC().Format(sqliteTimestampLayout)
+	contentType := c.variantContentTypeFromSidecar(path)
 
 	_, err := c.db.ExecContext(ctx, `
-		INSERT INTO variant_content (cache_key, size_bytes, last_accessed_at)
+		INSERT INTO variant_content
-		VALUES (?, ?, ?)
+			(cache_key, size_bytes, content_type, created_at, last_accessed_at)
-	`, string(cacheKey), info.Size(), modTime)
+		VALUES (?, ?, ?, ?, ?)
+	`, string(cacheKey), info.Size(), contentType, modTime, modTime)
 	if err != nil {
 		return fmt.Errorf("failed to adopt variant file into accounting: %w", err)
 	}
@@ -605,6 +715,23 @@ func (c *Cache) adoptVariantFile(
 	return nil
 }
 
+// variantContentTypeFromSidecar reads the content type from a variant
+// .meta sidecar, falling back to application/octet-stream.
+func (c *Cache) variantContentTypeFromSidecar(variantPath string) string {
+	//nolint:gosec // path from cache walk
+	metaData, err := os.ReadFile(variantPath + variantMetaSuffix)
+	if err != nil {
+		return fallbackContentType
+	}
+
+	var meta VariantMeta
+	if json.Unmarshal(metaData, &meta) != nil || meta.ContentType == "" {
+		return fallbackContentType
+	}
+
+	return meta.ContentType
+}
+
 // reconcileVariantRows drops accounting rows whose variant files are
 // missing, so the database never references deleted content.
 func (c *Cache) reconcileVariantRows(ctx context.Context) error {
@@ -696,20 +823,38 @@ func queryStringColumn[T ~string](
 // each blob file against its source_content row (reconcileSourceFile)
 // and sweeping stale temp files.
 func (c *Cache) reconcileSourceFiles(ctx context.Context) error {
-	return c.reconcileFiles(ctx, c.srcContent.baseDir,
+	return filepath.WalkDir(
-		func(path string, entry fs.DirEntry, name string) error {
+		c.srcContent.baseDir,
-			return c.reconcileSourceFile(ctx, path, entry, imagerequest.SourceKey(name))
+		func(path string, entry fs.DirEntry, err error) error {
-		})
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
+			if err != nil || entry.IsDir() {
+				return err
+			}
+
+			name := entry.Name()
+
+			if strings.HasPrefix(name, tempFilePrefix) {
+				c.sweepStaleTempFile(path, entry)
+
+				return nil
+			}
+
+			return c.reconcileSourceFile(ctx, path, entry, ContentHash(name))
+		},
+	)
 }
 
 // reconcileSourceFile checks one source blob file against its
-// source_content row. A file without a row is removed, as no lookup
+// source_content row. A file without a row is removed: it is
-// serves it and no eviction removes it. A file that is empty, or not the
+// unreachable, as source lookups always go through source_metadata. A
-// size its row records, as a crash or a restored snapshot can leave it,
+// file that is empty, or not the size its row records, as a crash or a
-// is removed with its row and a warning naming it, so the source is
+// restored snapshot can leave it, is removed with its rows and a warning
-// fetched again.
+// naming it, so the source is fetched again.
 func (c *Cache) reconcileSourceFile(
-	ctx context.Context, path string, entry fs.DirEntry, key imagerequest.SourceKey,
+	ctx context.Context, path string, entry fs.DirEntry, contentHash ContentHash,
 ) error {
 	info, err := entry.Info()
 	if err != nil {
@@ -719,13 +864,13 @@ func (c *Cache) reconcileSourceFile(
 	var recordedSize int64
 
 	err = c.db.QueryRowContext(ctx,
-		`SELECT size_bytes FROM source_content WHERE source_key = ?`,
+		`SELECT size_bytes FROM source_content WHERE content_hash = ?`,
-		string(key),
+		string(contentHash),
 	).Scan(&recordedSize)
 
 	switch {
 	case errors.Is(err, sql.ErrNoRows):
-		return c.removeUntrackedSourceFile(path, key)
+		return c.removeUntrackedSourceFile(ctx, path, contentHash)
 	case err != nil:
 		return fmt.Errorf("failed to check source content row: %w", err)
 	case info.Size() > 0 && info.Size() == recordedSize:
@@ -736,34 +881,96 @@ func (c *Cache) reconcileSourceFile(
 	c.log.Warn("removing damaged cached source file", "path", path,
 		"file_bytes", info.Size(), "recorded_bytes", recordedSize)
 
-	return c.evictSourceBlob(ctx, key)
+	return c.evictSourceBlob(ctx, contentHash)
 }
 
 // removeUntrackedSourceFile deletes a source blob file that has no
-// source_content row.
+// source_content row. Any source_metadata rows referencing the hash
+// are removed first so no row ever points at a deleted file.
 func (c *Cache) removeUntrackedSourceFile(
-	path string, key imagerequest.SourceKey,
+	ctx context.Context, path string, contentHash ContentHash,
 ) error {
-	err := os.Remove(path)
+	_, err := c.db.ExecContext(ctx,
+		`DELETE FROM source_metadata WHERE content_hash = ?`, string(contentHash))
+	if err != nil {
+		return fmt.Errorf("failed to delete metadata rows for untracked blob: %w", err)
+	}
+
+	err = os.Remove(path)
 	if err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("failed to remove untracked source file: %w", err)
 	}
 
-	c.log.Info("removed untracked source content file", "source_key", key)
+	c.log.Info("removed untracked source content file", "content_hash", contentHash)
 
 	return nil
 }
 
+// reconcileSourceRows removes source_content rows (and their metadata
+// references and sidecars) whose blob files are missing on disk.
+func (c *Cache) reconcileSourceRows(ctx context.Context) error {
+	var after ContentHash
+
+	for {
+		hashes, err := c.sourceContentHashesAfter(ctx, after)
+		if err != nil {
+			return err
+		}
+
+		if c.reconciliationReadTestHook != nil {
+			c.reconciliationReadTestHook(len(hashes))
+		}
+
+		if len(hashes) == 0 {
+			return nil
+		}
+
+		for _, hash := range hashes {
+			if ctx.Err() != nil {
+				return ctx.Err()
+			}
+
+			if c.srcContent.Exists(hash) {
+				continue
+			}
+
+			// The blob file is already gone; evictSourceBlob removes the
+			// rows and sidecars and tolerates the missing file.
+			err := c.evictSourceBlob(ctx, hash)
+			if err != nil {
+				return err
+			}
+
+			c.log.Info("dropped rows for missing source content file", "content_hash", hash)
+		}
+
+		after = hashes[len(hashes)-1]
+	}
+}
+
+// sourceContentHashesAfter returns, in order, up to
+// c.reconciliationPageSize tracked source content hashes that sort after
+// the given one.
+func (c *Cache) sourceContentHashesAfter(
+	ctx context.Context, after ContentHash,
+) ([]ContentHash, error) {
+	return queryStringColumn[ContentHash](ctx, c.db, `
+		SELECT content_hash FROM source_content
+		WHERE content_hash > ? ORDER BY content_hash LIMIT ?
+	`, "source content hashes", "content hash", string(after),
+		c.reconciliationPageSize)
+}
+
 // Each of these queries sums size_bytes over the next page of rows of
 // one content table, the rows that sort after a key, and returns the
 // page's last key, the sum and the number of rows in the page. Past the
 // last row the page has no rows and the key is NULL.
 const (
 	sourceSizePageQuery = `
-		SELECT MAX(source_key), COALESCE(SUM(size_bytes), 0), COUNT(*)
+		SELECT MAX(content_hash), COALESCE(SUM(size_bytes), 0), COUNT(*)
 		FROM (
-			SELECT source_key, size_bytes FROM source_content
+			SELECT content_hash, size_bytes FROM source_content
-			WHERE source_key > ? ORDER BY source_key LIMIT ?
+			WHERE content_hash > ? ORDER BY content_hash LIMIT ?
 		)`
 	variantSizePageQuery = `
 		SELECT MAX(cache_key), COALESCE(SUM(size_bytes), 0), COUNT(*)

internal/imgcache/eviction_internal_test.go

@@ -10,13 +10,12 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
-	"sync"
 	"testing"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
+	_ "modernc.org/sqlite"
-	"modernc.org/sqlite"
 	"sneak.berlin/go/pixa/internal/database"
+	"sneak.berlin/go/pixa/internal/httpfetcher"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
@@ -75,7 +74,7 @@ func newEvictionTestCache(t *testing.T, maxBytes int64) (*Cache, string) {
 		NegativeTTL:      5 * time.Minute,
 		MaxBytes:         maxBytes,
 		DisableDiskCache: maxBytes == 0,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
@@ -84,10 +83,10 @@ func newEvictionTestCache(t *testing.T, maxBytes int64) (*Cache, string) {
 }
 
 // storeEvictionTestSource stores content as a fetched source for
-// host/path and returns the resulting source key.
+// host/path and returns the resulting content hash.
 func storeEvictionTestSource(
 	t *testing.T, cache *Cache, host, path string, content []byte,
-) imagerequest.SourceKey {
+) ContentHash {
 	t.Helper()
 
 	req := &imagerequest.Request{
@@ -102,14 +101,23 @@ func storeEvictionTestSource(
 		},
 	}
 
-	key, err := cache.StoreSource(
+	result := &httpfetcher.FetchResult{
-		context.Background(), req, bytes.NewReader(content),
+		StatusCode:    200,
+		ContentType:   testContentTypeJPEG,
+		ContentLength: int64(len(content)),
+		Headers: map[string][]string{
+			testHeaderContentType: {testContentTypeJPEG},
+		},
+	}
+
+	hash, err := cache.StoreSource(
+		context.Background(), req, bytes.NewReader(content), result,
 	)
 	if err != nil {
 		t.Fatalf("StoreSource(%s%s) failed: %v", host, path, err)
 	}
 
-	return key
+	return hash
 }
 
 // storeEvictionTestVariant stores content as a processed variant under
@@ -119,7 +127,7 @@ func storeEvictionTestVariant(
 ) {
 	t.Helper()
 
-	err := cache.StoreVariant(t.Context(), key, bytes.NewReader(content))
+	err := cache.StoreVariant(t.Context(), key, bytes.NewReader(content), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant(%s) failed: %v", key, err)
 	}
@@ -154,13 +162,13 @@ func setVariantLastAccessed(
 // setSourceLastAccessed backdates the last access time of a tracked
 // source content blob.
 func setSourceLastAccessed(
-	t *testing.T, cache *Cache, key imagerequest.SourceKey, when time.Time,
+	t *testing.T, cache *Cache, hash ContentHash, when time.Time,
 ) {
 	t.Helper()
 
 	res, err := cache.db.ExecContext(t.Context(),
-		`UPDATE source_content SET last_accessed_at = ? WHERE source_key = ?`,
+		`UPDATE source_content SET last_accessed_at = ? WHERE content_hash = ?`,
-		when.UTC().Format(sqliteTimestampFormat), string(key),
+		when.UTC().Format(sqliteTimestampFormat), string(hash),
 	)
 	if err != nil {
 		t.Fatalf("failed to set source last_accessed_at: %v", err)
@@ -172,7 +180,7 @@ func setSourceLastAccessed(
 	}
 
 	if affected != 1 {
-		t.Fatalf("source %s has no accounting row (affected=%d)", key, affected)
+		t.Fatalf("source %s has no accounting row (affected=%d)", hash, affected)
 	}
 }
 
@@ -197,31 +205,32 @@ func assertNoDanglingReferences(t *testing.T, cache *Cache) {
 	t.Helper()
 
 	rows, err := cache.db.QueryContext(t.Context(),
-		`SELECT source_key FROM source_content`,
+		`SELECT content_hash FROM source_metadata
+		 WHERE content_hash IS NOT NULL AND content_hash != ''`,
 	)
 	if err != nil {
-		t.Fatalf("failed to query source_content: %v", err)
+		t.Fatalf("failed to query source_metadata: %v", err)
 	}
 
 	defer func() { _ = rows.Close() }()
 
 	for rows.Next() {
-		var key string
+		var hash string
 
-		err := rows.Scan(&key)
+		err := rows.Scan(&hash)
 		if err != nil {
-			t.Fatalf("failed to scan source_key: %v", err)
+			t.Fatalf("failed to scan content_hash: %v", err)
 		}
 
-		if !cache.srcContent.Exists(imagerequest.SourceKey(key)) {
+		if !cache.srcContent.Exists(ContentHash(hash)) {
-			t.Errorf("source_content references content %s but the file is missing",
+			t.Errorf("source_metadata references content %s but the file is missing",
-				key)
+				hash)
 		}
 	}
 
 	err = rows.Err()
 	if err != nil {
-		t.Fatalf("source_content iteration failed: %v", err)
+		t.Fatalf("source_metadata iteration failed: %v", err)
 	}
 
 	variantRows, err := cache.db.QueryContext(t.Context(),
@@ -304,6 +313,33 @@ func TestUsageBytesAccountsSourceAndVariantBytes(t *testing.T) {
 	}
 }
 
+func TestUsageBytesCountsMultiReferencedBlobOnce(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	content := bytes.Repeat([]byte{0xCC}, 1200)
+
+	hashOne := storeEvictionTestSource(t, cache,
+		"src.example.com", "/one.jpg", content)
+	hashTwo := storeEvictionTestSource(t, cache,
+		"src.example.com", "/two.jpg", content)
+
+	if hashOne != hashTwo {
+		t.Fatalf("identical content produced different hashes: %s vs %s",
+			hashOne, hashTwo)
+	}
+
+	usage, err := cache.UsageBytes(context.Background())
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
+	if usage != 1200 {
+		t.Errorf("UsageBytes = %d, want 1200 (deduplicated blob counted once)", usage)
+	}
+}
+
 func TestEvictToLimitEvictsLeastRecentlyUsedFirst(t *testing.T) {
 	t.Parallel()
 
@@ -357,15 +393,102 @@ func TestEvictToLimitEvictsLeastRecentlyUsedFirst(t *testing.T) {
 	assertNoDanglingReferences(t, cache)
 }
 
+func TestEvictionRemovesMultiReferencedBlobTogetherWithAllReferences(t *testing.T) {
+	t.Parallel()
+
+	const limit = 1000
+
+	cache, _ := newEvictionTestCache(t, limit)
+
+	now := time.Now()
+
+	// One 800-byte blob referenced by two source paths.
+	sharedContent := bytes.Repeat([]byte{0xDD}, 800)
+	sharedHash := storeEvictionTestSource(t, cache,
+		"src.example.com", "/a.jpg", sharedContent)
+
+	h := storeEvictionTestSource(t, cache,
+		"src.example.com", "/b.jpg", sharedContent)
+	if h != sharedHash {
+		t.Fatalf("identical content produced different hashes: %s vs %s",
+			h, sharedHash)
+	}
+
+	// A newer 600-byte blob referenced by one source path.
+	recentHash := storeEvictionTestSource(t, cache, "src.example.com", "/c.jpg",
+		bytes.Repeat([]byte{0xEE}, 600))
+
+	setSourceLastAccessed(t, cache, sharedHash, now.Add(-2*time.Hour))
+	setSourceLastAccessed(t, cache, recentHash, now.Add(-time.Minute))
+
+	err := cache.EvictToLimit(context.Background())
+	if err != nil {
+		t.Fatalf("EvictToLimit failed: %v", err)
+	}
+
+	usage, err := cache.UsageBytes(context.Background())
+	if err != nil {
+		t.Fatalf("UsageBytes failed: %v", err)
+	}
+
+	if usage > limit {
+		t.Errorf("usage after eviction = %d, want <= %d", usage, limit)
+	}
+
+	// The multi-referenced blob must be gone from disk, from
+	// source_content, and from BOTH source_metadata rows: references
+	// are removed together with the blob, never left dangling.
+	if cache.srcContent.Exists(sharedHash) {
+		t.Errorf("evicted blob %s still exists on disk", sharedHash)
+	}
+
+	if n := countRows(t, cache,
+		`SELECT COUNT(*) FROM source_content WHERE content_hash = ?`, string(sharedHash),
+	); n != 0 {
+		t.Errorf("evicted blob %s still has %d source_content rows", sharedHash, n)
+	}
+
+	if n := countRows(t, cache,
+		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(sharedHash),
+	); n != 0 {
+		t.Errorf("evicted blob %s still has %d source_metadata references", sharedHash, n)
+	}
+
+	// The JSON metadata sidecars for both referencing paths must be
+	// removed along with the rows.
+	for _, path := range []string{"/a.jpg", "/b.jpg"} {
+		pathHash := HashPath(path + "?")
+		if cache.srcMetadata.Exists("src.example.com", pathHash) {
+			t.Errorf("metadata sidecar for %s must be removed with its row", path)
+		}
+	}
+
+	// The more recently used blob survives fully intact.
+	if !cache.srcContent.Exists(recentHash) {
+		t.Errorf("recently used blob %s must survive eviction", recentHash)
+	}
+
+	if n := countRows(t, cache,
+		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(recentHash),
+	); n != 1 {
+		t.Errorf("recently used blob %s has %d source_metadata rows, want 1",
+			recentHash, n)
+	}
+
+	assertNoDanglingReferences(t, cache)
+}
+
 func TestEvictionKeepsEverythingWhenUnderLimit(t *testing.T) {
 	t.Parallel()
 
 	cache, _ := newEvictionTestCache(t, 1<<30)
 
 	content := bytes.Repeat([]byte{0xDF}, 800)
-	keys := []imagerequest.SourceKey{
+	hash := storeEvictionTestSource(t, cache, "src.example.com", "/a.jpg", content)
-		storeEvictionTestSource(t, cache, "src.example.com", "/a.jpg", content),
+
-		storeEvictionTestSource(t, cache, "src.example.com", "/b.jpg", content),
+	h := storeEvictionTestSource(t, cache, "src.example.com", "/b.jpg", content)
+	if h != hash {
+		t.Fatalf("identical content produced different hashes: %s vs %s", h, hash)
 	}
 
 	storeEvictionTestVariant(t, cache, testVariantKeyOne,
@@ -376,16 +499,14 @@ func TestEvictionKeepsEverythingWhenUnderLimit(t *testing.T) {
 		t.Fatalf("EvictToLimit failed: %v", err)
 	}
 
-	for _, key := range keys {
+	if !cache.srcContent.Exists(hash) {
-		if !cache.srcContent.Exists(key) {
+		t.Errorf("blob %s must not be evicted while usage is under the limit", hash)
-			t.Errorf("source %s must not be evicted while usage is under the limit", key)
 	}
 
 	if n := countRows(t, cache,
-			`SELECT COUNT(*) FROM source_content WHERE source_key = ?`, string(key),
+		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(hash),
-		); n != 1 {
+	); n != 2 {
-			t.Errorf("source %s has %d source_content rows, want 1", key, n)
+		t.Errorf("blob %s has %d source_metadata rows, want 2", hash, n)
-		}
 	}
 
 	if !cache.variants.Exists(testVariantKeyOne) {
@@ -428,19 +549,26 @@ func assertDisabledCacheWritesAreNoOps(
 	ctx := t.Context()
 
 	err := cache.StoreVariant(
-		ctx, imagerequest.CacheKey(req), bytes.NewReader([]byte("data")),
+		ctx, imagerequest.CacheKey(req), bytes.NewReader([]byte("data")), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("StoreVariant on disabled cache must be a no-op, got error: %v", err)
 	}
 
-	key, err := cache.StoreSource(ctx, req, bytes.NewReader([]byte("data")))
+	result := &httpfetcher.FetchResult{
+		StatusCode:    200,
+		ContentType:   testContentTypeJPEG,
+		ContentLength: 4,
+		Headers:       map[string][]string{},
+	}
+
+	hash, err := cache.StoreSource(ctx, req, bytes.NewReader([]byte("data")), result)
 	if err != nil {
 		t.Fatalf("StoreSource on disabled cache must be a no-op, got error: %v", err)
 	}
 
-	if key != "" {
+	if hash != "" {
-		t.Errorf("StoreSource on disabled cache returned key %q, want empty", key)
+		t.Errorf("StoreSource on disabled cache returned hash %q, want empty", hash)
 	}
 }
 
@@ -453,13 +581,23 @@ func assertDisabledCacheReadsAlwaysMiss(
 
 	ctx := t.Context()
 
-	key, err := cache.LookupSource(ctx, req)
+	lookup, err := cache.Lookup(ctx, req)
+	if err != nil {
+		t.Fatalf("Lookup on disabled cache failed: %v", err)
+	}
+
+	if lookup.Hit {
+		t.Error("Lookup on disabled cache must always miss")
+	}
+
+	srcHash, srcType, err := cache.LookupSource(ctx, req)
 	if err != nil {
 		t.Fatalf("LookupSource on disabled cache failed: %v", err)
 	}
 
-	if key != "" {
+	if srcHash != "" || srcType != "" {
-		t.Errorf("LookupSource on disabled cache = %q, want empty", key)
+		t.Errorf("LookupSource on disabled cache = (%q, %q), want empty",
+			srcHash, srcType)
 	}
 }
 
@@ -480,6 +618,10 @@ func assertDisabledCacheTracksNothing(t *testing.T, cache *Cache) {
 	if n := countRows(t, cache, `SELECT COUNT(*) FROM source_content`); n != 0 {
 		t.Errorf("disabled cache wrote %d source_content rows, want 0", n)
 	}
+
+	if n := countRows(t, cache, `SELECT COUNT(*) FROM source_metadata`); n != 0 {
+		t.Errorf("disabled cache wrote %d source_metadata rows, want 0", n)
+	}
 }
 
 // assertDisabledCacheWroteNothingToDisk verifies that a disabled cache
@@ -590,7 +732,7 @@ 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))
+		_, err = cache.variants.Store(key, bytes.NewReader(content), "image/webp")
 		if err != nil {
 			t.Fatalf("failed to store variant file: %v", err)
 		}
@@ -642,7 +784,7 @@ func TestStartEvictionReconcilesAccountingWithDisk(t *testing.T) {
 	untracked := bytes.Repeat([]byte{0x31}, 1000)
 
 	_, err := cache.variants.Store(
-		testVariantKeyOne, bytes.NewReader(untracked),
+		testVariantKeyOne, bytes.NewReader(untracked), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to store untracked variant file: %v", err)
@@ -650,8 +792,9 @@ func TestStartEvictionReconcilesAccountingWithDisk(t *testing.T) {
 
 	// An accounting row whose file is missing must be dropped.
 	_, err = cache.db.ExecContext(t.Context(),
-		`INSERT INTO variant_content (cache_key, size_bytes) VALUES (?, ?)`,
+		`INSERT INTO variant_content (cache_key, size_bytes, content_type)
-		"deadbeef0001", 700,
+		 VALUES (?, ?, ?)`,
+		"deadbeef0001", 700, "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to insert stale variant accounting row: %v", err)
@@ -743,7 +886,7 @@ func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 	untracked := bytes.Repeat([]byte{0x41}, 900)
 
 	_, err = cache.variants.Store(
-		"aabbccdd0099", bytes.NewReader(untracked),
+		"aabbccdd0099", bytes.NewReader(untracked), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to store untracked variant file: %v", err)
@@ -921,15 +1064,9 @@ func TestStopEvictionInterruptsPassInProgress(t *testing.T) {
 }
 
 // TestEvictToLimitStopsAtNextCandidateOnceCancelled cancels the context
-// once the oldest of three sources is evicted, while the next one waits
+// while the oldest of three source blobs is being evicted, and checks that
-// for the database, and checks that EvictToLimit then returns
+// EvictToLimit then returns context.Canceled without evicting the other
-// context.Canceled, with that source gone and the other two kept, and
+// two or logging a warning for either of them.
-// logs no warning. The test database has one connection. When the
-// deletion of the oldest source's row commits, a commit hook holds the
-// deletion until the test waits for the connection, so the test takes it
-// as soon as the deletion is done. The eviction of the next source then
-// waits for the connection, and the test cancels the context while it
-// waits.
 func TestEvictToLimitStopsAtNextCandidateOnceCancelled(t *testing.T) {
 	t.Parallel()
 
@@ -939,7 +1076,7 @@ func TestEvictToLimitStopsAtNextCandidateOnceCancelled(t *testing.T) {
 
 	cache.log = slog.New(slog.NewJSONHandler(&logBuf, nil))
 
-	keys := []imagerequest.SourceKey{
+	hashes := []ContentHash{
 		storeEvictionTestSource(t, cache, "cancel.example.com", "/a.jpg",
 			bytes.Repeat([]byte{0x61}, 1000)),
 		storeEvictionTestSource(t, cache, "cancel.example.com", "/b.jpg",
@@ -950,155 +1087,69 @@ func TestEvictToLimitStopsAtNextCandidateOnceCancelled(t *testing.T) {
 
 	base := time.Now().Add(-time.Hour)
 
-	for i, key := range keys {
+	for i, hash := range hashes {
-		setSourceLastAccessed(t, cache, key, base.Add(time.Duration(i)*time.Minute))
+		setSourceLastAccessed(t, cache, hash, base.Add(time.Duration(i)*time.Minute))
 	}
 
-	waitsBefore := cache.db.Stats().WaitCount
-	oldestRowDeleted := make(chan struct{})
-
-	var oldestRowDeletedOnce sync.Once
-
-	setCommitHook(t, cache, func() int32 {
-		oldestRowDeletedOnce.Do(func() {
-			close(oldestRowDeleted)
-
-			deadline := time.Now().Add(5 * time.Second)
-
-			for cache.db.Stats().WaitCount == waitsBefore && time.Now().Before(deadline) {
-				time.Sleep(time.Millisecond)
-			}
-		})
-
-		return 0
-	})
-
 	ctx, cancel := context.WithCancel(t.Context())
 	defer cancel()
 
-	evicted := make(chan error, 1)
+	cache.evictSourceBlobTestHook = func(ContentHash) { cancel() }
 
-	go func() { evicted <- cache.EvictToLimit(ctx) }()
+	err := cache.EvictToLimit(ctx)
-
-	select {
-	case <-oldestRowDeleted:
-	case err := <-evicted:
-		t.Fatalf("EvictToLimit() returned %v without deleting a row", err)
-	case <-time.After(5 * time.Second):
-		t.Fatal("EvictToLimit never deleted a row")
-	}
-
-	releaseDatabase := holdDatabase(t, cache)
-	defer releaseDatabase()
-
-	waitForConnectionWaits(t, cache.db, waitsBefore+2)
-	cancel()
-
-	err := <-evicted
 	t.Logf("EvictToLimit() error = %v", err)
 	t.Logf("log output: %s", logBuf.String())
 
-	// The checks below read the database, so the connection goes back.
-	releaseDatabase()
-
-	setCommitHook(t, cache, nil)
-
 	if !errors.Is(err, context.Canceled) {
 		t.Errorf("EvictToLimit() error = %v, want context.Canceled", err)
 	}
 
-	assertOnlyOldestSourceEvicted(t, cache, keys)
+	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")
 	}
-}
-
-// setCommitHook makes the SQLite driver call hook each time a write on
-// the test database's one connection commits, or stops it when hook is
-// nil.
-func setCommitHook(t *testing.T, cache *Cache, hook sqlite.CommitHookFn) {
-	t.Helper()
-
-	conn, err := cache.db.Conn(t.Context())
-	if err != nil {
-		t.Fatalf("failed to take the database connection: %v", err)
-	}
-
-	defer func() { _ = conn.Close() }()
-
-	err = conn.Raw(func(driverConn any) error {
-		hooks, ok := driverConn.(sqlite.HookRegisterer)
-		if !ok {
-			t.Fatalf("the database connection is a %T, which takes no hooks",
-				driverConn)
-		}
-
-		hooks.RegisterCommitHook(hook)
-
-		return nil
-	})
-	if err != nil {
-		t.Fatalf("failed to set the commit hook: %v", err)
-	}
-}
-
-// assertOnlyOldestSourceEvicted checks that the first of keys has neither
-// its file nor its row, and that every other one has both.
-func assertOnlyOldestSourceEvicted(
-	t *testing.T, cache *Cache, keys []imagerequest.SourceKey,
-) {
-	t.Helper()
-
-	if cache.srcContent.Exists(keys[0]) {
-		t.Errorf("source %s, evicted when the context was cancelled, "+
-			"is still on disk", keys[0])
-	}
-
-	for _, key := range keys[1:] {
-		if !cache.srcContent.Exists(key) {
-			t.Errorf("source %s was evicted after the context was cancelled", key)
-		}
-
-		if n := countRows(t, cache,
-			`SELECT COUNT(*) FROM source_content WHERE source_key = ?`, string(key),
-		); n != 1 {
-			t.Errorf("source %s, kept, has %d source_content rows, want 1", key, n)
-		}
-	}
 
 	assertNoDanglingReferences(t, cache)
 }
 
-// TestStopEvictionReturnsWhenItsContextEnds pauses the startup
+// TestStopEvictionReturnsWhenItsContextEnds pauses an eviction pass where
-// reconciliation pass in the hook called after each of its reads, where
+// cancellation cannot reach it, after a source blob's rows are deleted and
-// cancellation cannot reach it, and checks that StopEviction returns an
+// before its file is removed, and checks that StopEviction returns its
-// error wrapping its context's error when that context ends, instead of
+// context's error when that context ends instead of waiting for the pass.
-// waiting for the pass. Once the pass goes on, the goroutine exits, and a
+// Once the pass goes on, the goroutine exits and no row points at a
-// second StopEviction returns nil.
+// missing file.
 func TestStopEvictionReturnsWhenItsContextEnds(t *testing.T) {
 	t.Parallel()
 
-	cache, _ := newEvictionTestCache(t, 1<<30)
+	cache, _ := newEvictionTestCache(t, 1)
 
 	paused := make(chan struct{})
 	resume := make(chan struct{})
 
-	var pauseOnce sync.Once
+	cache.evictSourceBlobTestHook = func(ContentHash) {
-
-	cache.reconciliationReadTestHook = func(int) {
-		pauseOnce.Do(func() {
 		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 reconciliation pass never made a read")
+		t.Fatal("the eviction pass never reached the source blob")
 	}
 
 	ctx, cancel := context.WithTimeout(t.Context(), 50*time.Millisecond)
@@ -1117,6 +1168,12 @@ func TestStopEvictionReturnsWhenItsContextEnds(t *testing.T) {
 	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
@@ -1188,3 +1245,131 @@ func TestReconciliationPassLogsNoWarningOnceCancelled(t *testing.T) {
 		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
+// StoreSource for a different source path whose content hashes to the
+// same value (real SHA-256 dedup, not a contrived case) must not be
+// able to insert a fresh row referencing the file while eviction is
+// mid-unlink, and must not lose its own store once eviction has fully
+// released the content hash.
+func TestEvictSourceBlobExcludesConcurrentStoreOfIdenticalContent(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+	ctx := context.Background()
+
+	content := bytes.Repeat([]byte{0x55}, 400)
+
+	hash := storeEvictionTestSource(t, cache,
+		"race.example.com", "/first.jpg", content)
+
+	proceed := make(chan struct{})
+	storeAttempted := make(chan struct{})
+
+	cache.evictSourceBlobTestHook = func(gotHash ContentHash) {
+		if gotHash != hash {
+			t.Errorf("test hook invoked for hash %s, want %s", gotHash, hash)
+		}
+
+		close(storeAttempted)
+		<-proceed
+	}
+
+	evictDone := make(chan error, 1)
+
+	go func() {
+		evictDone <- cache.evictSourceBlob(ctx, hash)
+	}()
+
+	// Wait until eviction has committed its delete transaction and is
+	// paused (inside the test hook) immediately before unlinking the
+	// content file: exactly the window the review flagged.
+	<-storeAttempted
+
+	storeDone := storeIdenticalContentConcurrently(ctx, cache, content)
+
+	// The concurrent store must not be able to complete while eviction
+	// still holds the content hash (i.e. before the file is unlinked):
+	// if it could, it would insert a row referencing a file about to be
+	// removed out from under it.
+	select {
+	case err := <-storeDone:
+		t.Fatalf("StoreSource for identical content completed (err=%v) while eviction "+
+			"still held the content hash open between commit and unlink; the store and "+
+			"the evict of identical content are not mutually exclusive", err)
+	case <-time.After(200 * time.Millisecond):
+		// Expected: the store is blocked behind eviction's exclusion.
+	}
+
+	close(proceed)
+
+	err := <-evictDone
+	if err != nil {
+		t.Fatalf("evictSourceBlob failed: %v", err)
+	}
+
+	err = <-storeDone
+	if err != nil {
+		t.Fatalf("StoreSource failed: %v", err)
+	}
+
+	assertNoDanglingReferences(t, cache)
+
+	dupHash, _, err := cache.LookupSource(ctx, &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: "race.example.com",
+			Path: "/dup.jpg",
+		},
+	})
+	if err != nil {
+		t.Fatalf("LookupSource failed: %v", err)
+	}
+
+	if dupHash == "" {
+		t.Fatal("re-stored blob was lost: the store legitimately ran after eviction " +
+			"released the content hash and must have recreated the file and row")
+	}
+
+	if !cache.srcContent.Exists(dupHash) {
+		t.Errorf("source_content/source_metadata references %s but its file is missing",
+			dupHash)
+	}
+}
+
+// storeIdenticalContentConcurrently starts a StoreSource for a second
+// source path whose body hashes to the same content hash, returning the
+// channel its error is delivered on.
+func storeIdenticalContentConcurrently(
+	ctx context.Context, cache *Cache, content []byte,
+) chan error {
+	storeDone := make(chan error, 1)
+
+	go func() {
+		req := &imagerequest.Request{
+			Source: imagerequest.Source{
+				Host: "race.example.com",
+				Path: "/dup.jpg",
+			},
+			Transform: imagerequest.Transform{
+				Format:  imagerequest.FormatJPEG,
+				Quality: 85,
+				FitMode: imagerequest.FitCover,
+			},
+		}
+		result := &httpfetcher.FetchResult{
+			StatusCode:    200,
+			ContentType:   testContentTypeJPEG,
+			ContentLength: int64(len(content)),
+			Headers: map[string][]string{
+				testHeaderContentType: {testContentTypeJPEG},
+			},
+		}
+
+		_, err := cache.StoreSource(ctx, req, bytes.NewReader(content), result)
+		storeDone <- err
+	}()
+
+	return storeDone
+}

internal/imgcache/imgcache.go

@@ -1,7 +1,13 @@
-// Package imgcache provides types for the image caching proxy.
+// Package imgcache provides interfaces and types for the image caching proxy.
 package imgcache
 
-import "io"
+import (
+	"context"
+	"io"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/imagerequest"
+)
 
 // ImageResponse represents a processed image ready to serve
 type ImageResponse struct {
@@ -13,7 +19,9 @@ type ImageResponse struct {
 	ContentType string
 	// ETag is the entity tag for caching
 	ETag string
-	// CacheStatus indicates HIT or MISS
+	// LastModified is when the content was last modified
+	LastModified time.Time
+	// CacheStatus indicates HIT, MISS, or STALE
 	CacheStatus CacheStatus
 	// FetchedBytes is the number of bytes fetched from upstream (0 if cache hit)
 	FetchedBytes int64
@@ -26,4 +34,33 @@ type CacheStatus string
 const (
 	CacheHit   CacheStatus = "HIT"
 	CacheMiss  CacheStatus = "MISS"
+	CacheStale CacheStatus = "STALE"
 )
+
+// ImageCache is the main interface for the image caching proxy
+type ImageCache interface {
+	// Get retrieves a processed image, fetching and processing if necessary
+	Get(ctx context.Context, req *imagerequest.Request) (*ImageResponse, error)
+
+	// Warm pre-fetches and caches an image without returning it
+	Warm(ctx context.Context, req *imagerequest.Request) error
+
+	// Stats returns cache statistics
+	Stats(ctx context.Context) (*CacheStats, error)
+}
+
+// CacheStats contains cache statistics
+type CacheStats struct {
+	// TotalItems is the number of cached source images plus processed
+	// variants
+	TotalItems int64
+	// TotalSizeBytes is the total size of cached source images and
+	// processed variants
+	TotalSizeBytes int64
+	// HitCount is the number of cache hits
+	HitCount int64
+	// MissCount is the number of cache misses
+	MissCount int64
+	// HitRate is HitCount / (HitCount + MissCount)
+	HitRate float64
+}

internal/imgcache/max_concurrent_processing_internal_test.go

@@ -77,11 +77,11 @@ func TestService_Get_WaitsForSlotBeforeReadingCachedSource(t *testing.T) {
 
 	_ = resp.Content.Close()
 
-	sourceKey, err := svc.cache.LookupSource(t.Context(),
+	contentHash, _, err := svc.cache.LookupSource(t.Context(),
 		widthOnlyRequest(fixtures, 50))
-	if err != nil || sourceKey == "" {
+	if err != nil || contentHash == "" {
 		t.Fatalf("LookupSource() = %q, %v; want the cached source",
-			sourceKey, err)
+			contentHash, err)
 	}
 
 	release := holdProcessingSlot(t, svc.processor)
@@ -103,7 +103,7 @@ func TestService_Get_WaitsForSlotBeforeReadingCachedSource(t *testing.T) {
 	// before waiting, it would have read it by now.
 	time.Sleep(100 * time.Millisecond)
 
-	err = os.WriteFile(svc.cache.srcContent.keyToPath(sourceKey),
+	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)

internal/imgcache/metacache_internal_test.go

@@ -0,0 +1,361 @@
+package imgcache
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/imagerequest"
+)
+
+// webpRequest returns a request for a 100x100 WebP variant of path.
+func webpRequest(path string) *imagerequest.Request {
+	return &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHostCDN,
+			Path: path,
+		},
+		Transform: imagerequest.Transform{
+			Size:    imagerequest.Size{Width: 100, Height: 100},
+			Format:  imagerequest.FormatWebP,
+			Quality: 85,
+			FitMode: imagerequest.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 imagerequest.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 imagerequest.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.Request,
+) {
+	t.Helper()
+
+	lookup, err := cache.Lookup(t.Context(), request)
+	if err != nil {
+		t.Fatalf("Lookup(%s) error = %v", request.Source.Path, err)
+	}
+
+	if lookup.Hit {
+		t.Errorf("Lookup(%s) is a hit, want a miss", request.Source.Path)
+	}
+}
+
+// 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 := imagerequest.CacheKey(oldRequest)
+	newKey := imagerequest.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 := imagerequest.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 := imagerequest.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/negative_cache_internal_test.go

@@ -7,7 +7,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
@@ -20,7 +19,7 @@ func TestNegativeCache_StoreAndCheck(t *testing.T) {
 	cache, err := NewCache(db, CacheConfig{
 		StateDir:    dir,
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -44,7 +43,7 @@ func TestNegativeCache_StoreAndCheck(t *testing.T) {
 	}
 
 	// Store a negative entry
-	err = cache.StoreNegative(ctx, req)
+	err = cache.StoreNegative(ctx, req, 404, "not found")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -69,7 +68,7 @@ func TestNegativeCache_Expired(t *testing.T) {
 	cache, err := NewCache(db, CacheConfig{
 		StateDir:    dir,
 		NegativeTTL: 1 * time.Millisecond, // very short TTL
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -83,7 +82,7 @@ func TestNegativeCache_Expired(t *testing.T) {
 	}
 
 	// Store a negative entry with very short TTL
-	err = cache.StoreNegative(ctx, req)
+	err = cache.StoreNegative(ctx, req, 500, "server error")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -121,7 +120,8 @@ func TestService_Get_ServesCachedVariantOfNegativeCachedURL(t *testing.T) {
 	_ = resp.Content.Close()
 
 	err = svc.cache.StoreNegative(t.Context(),
-		photoVariant(fixtures, 85, imagerequest.FitCover))
+		photoVariant(fixtures, 85, imagerequest.FitCover),
+		httpStatusBadGateway, "upstream answered 503")
 	if err != nil {
 		t.Fatalf("StoreNegative() error = %v", err)
 	}
@@ -147,13 +147,13 @@ func TestService_Get_ServesCachedVariantOfNegativeCachedURL(t *testing.T) {
 
 	_ = resp.Content.Close()
 
-	sourceKey, err := svc.cache.LookupSource(t.Context(),
+	contentHash, _, err := svc.cache.LookupSource(t.Context(),
 		photoVariant(fixtures, 85, imagerequest.FitCover))
-	if err != nil || sourceKey == "" {
+	if err != nil || contentHash == "" {
-		t.Fatalf("LookupSource() = %q, %v, want the cached source", sourceKey, err)
+		t.Fatalf("LookupSource() = %q, %v, want the cached source", contentHash, err)
 	}
 
-	err = svc.cache.evictSourceBlob(t.Context(), sourceKey)
+	err = svc.cache.evictSourceBlob(t.Context(), contentHash)
 	if err != nil {
 		t.Fatalf("evictSourceBlob() error = %v", err)
 	}
@@ -192,7 +192,7 @@ func TestEvictionLoopRemovesExpiredNegativeCacheRows(t *testing.T) {
 				StateDir:         t.TempDir(),
 				NegativeTTL:      time.Second,
 				DisableDiskCache: tt.disableDiskCache,
-			}, prometheus.NewRegistry())
+			})
 			if err != nil {
 				t.Fatalf("failed to create cache: %v", err)
 			}
@@ -201,7 +201,7 @@ func TestEvictionLoopRemovesExpiredNegativeCacheRows(t *testing.T) {
 				Source: imagerequest.Source{Host: testHostExample, Path: "/gone.jpg"},
 			}
 
-			err = cache.StoreNegative(t.Context(), expired)
+			err = cache.StoreNegative(t.Context(), expired, 404, "not found")
 			if err != nil {
 				t.Fatalf("StoreNegative failed: %v", err)
 			}
@@ -210,8 +210,8 @@ func TestEvictionLoopRemovesExpiredNegativeCacheRows(t *testing.T) {
 
 			_, err = cache.db.ExecContext(t.Context(), `
 				INSERT INTO negative_cache
-					(source_host, source_path, expires_at)
+					(source_host, source_path, status_code, expires_at)
-				VALUES (?, ?, datetime('now', '+1 hour'))
+				VALUES (?, ?, 404, datetime('now', '+1 hour'))
 			`, testHostExample, notExpiredPath)
 			if err != nil {
 				t.Fatalf("failed to insert a row that has not expired: %v", err)
@@ -266,8 +266,7 @@ func negativeCacheRowCount(tb testing.TB, cache *Cache, sourcePath string) int {
 func TestCleanExpiredDeletesInBatches(t *testing.T) {
 	t.Parallel()
 
-	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()},
+	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()})
-		prometheus.NewRegistry())
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
@@ -280,8 +279,8 @@ func TestCleanExpiredDeletesInBatches(t *testing.T) {
 
 	_, err = cache.db.ExecContext(ctx, `
 		INSERT INTO negative_cache
-			(source_host, source_path, expires_at)
+			(source_host, source_path, status_code, expires_at)
-		VALUES (?, ?, datetime('now', '+1 hour'))
+		VALUES (?, ?, 404, datetime('now', '+1 hour'))
 	`, testHostExample, notExpiredPath)
 	if err != nil {
 		t.Fatalf("failed to insert a row that has not expired: %v", err)
@@ -321,8 +320,7 @@ func TestCleanExpiredDeletesInBatches(t *testing.T) {
 func TestCleanExpiredRemovesMoreThanOneBatch(t *testing.T) {
 	t.Parallel()
 
-	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()},
+	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()})
-		prometheus.NewRegistry())
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
@@ -352,8 +350,7 @@ func TestCleanExpiredRemovesMoreThanOneBatch(t *testing.T) {
 func TestCleanExpiredStopsOnceContextEnds(t *testing.T) {
 	t.Parallel()
 
-	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()},
+	cache, err := NewCache(evictionTestDB(t), CacheConfig{StateDir: t.TempDir()})
-		prometheus.NewRegistry())
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
@@ -381,8 +378,8 @@ func insertExpiredNegativeCacheRows(t *testing.T, cache *Cache, count int) {
 	for i := range count {
 		_, err := cache.db.ExecContext(t.Context(), `
 			INSERT INTO negative_cache
-				(source_host, source_path, expires_at)
+				(source_host, source_path, status_code, expires_at)
-			VALUES (?, ?, datetime('now', '-1 hour'))
+			VALUES (?, ?, 404, datetime('now', '-1 hour'))
 		`, testHostExample, "/expired/"+strconv.Itoa(i)+".jpg")
 		if err != nil {
 			t.Fatalf("failed to insert an expired row: %v", err)

internal/imgcache/partial_cache_files_internal_test.go

@@ -2,6 +2,8 @@ package imgcache
 
 import (
 	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
 	"io"
 	"log/slog"
 	"os"
@@ -65,12 +67,12 @@ func cachedSourcePath(
 ) string {
 	t.Helper()
 
-	sourceKey, err := svc.cache.LookupSource(t.Context(), req)
+	contentHash, _, err := svc.cache.LookupSource(t.Context(), req)
-	if err != nil || sourceKey == "" {
+	if err != nil || contentHash == "" {
-		t.Fatalf("LookupSource() = %q, %v; want the cached source", sourceKey, err)
+		t.Fatalf("LookupSource() = %q, %v; want the cached source", contentHash, err)
 	}
 
-	return svc.cache.srcContent.keyToPath(sourceKey)
+	return svc.cache.srcContent.hashToPath(contentHash)
 }
 
 // reconcileAsAtStartup runs the cache's reconciliation pass, as pixa does
@@ -128,7 +130,7 @@ func TestService_Get_FetchesAgainForEmptyCachedSource(t *testing.T) {
 	getImage(t, svc, photoVariant(fixtures, 40, imagerequest.FitCover))
 	getImage(t, svc, photoVariant(fixtures, 30, imagerequest.FitCover))
 
-	fetches := readCounters(svc.cache).upstreamFetchCount
+	fetches := readCacheStatsCounters(t, svc.cache).upstreamFetchCount
 	t.Logf("upstream fetches = %d", fetches)
 
 	if fetches != 2 {
@@ -164,7 +166,7 @@ func TestService_Get_FetchesAgainForPartialCachedSource(t *testing.T) {
 	getImage(t, svc, photoVariant(fixtures, 40, imagerequest.FitCover))
 	getImage(t, svc, photoVariant(fixtures, 30, imagerequest.FitCover))
 
-	fetches := readCounters(svc.cache).upstreamFetchCount
+	fetches := readCacheStatsCounters(t, svc.cache).upstreamFetchCount
 	t.Logf("upstream fetches = %d", fetches)
 
 	if fetches != 2 {
@@ -239,7 +241,8 @@ func TestReconciliationRemovesEmptyVariantFileWithoutRow(t *testing.T) {
 
 	cache, _ := newEvictionTestCache(t, 1<<30)
 
-	_, err := cache.variants.Store(testVariantKeyOne, bytes.NewReader(nil))
+	_, err := cache.variants.Store(testVariantKeyOne, bytes.NewReader(nil),
+		testContentTypeWebP)
 	if err != nil {
 		t.Fatalf("failed to store an empty variant file: %v", err)
 	}
@@ -260,10 +263,63 @@ func TestReconciliationRemovesEmptyVariantFileWithoutRow(t *testing.T) {
 	}
 }
 
-// TestContentStorage_StoreReplacesFileOfAnotherSize checks that a
+// TestVariantStorage_StoreReplacesMetaFile stores a variant over one
-// store over a file of another size at the source's path, such as a
+// already stored and checks that Store puts a new .meta file in place of
+// the old one, as it does the image, rather than writing into the old
+// file, which a crash could leave empty. The old .meta file is given a
+// second name before the store, so that it can be told apart from the new
+// one after it.
+func TestVariantStorage_StoreReplacesMetaFile(t *testing.T) {
+	t.Parallel()
+
+	storage, key := storeTestVariant(t)
+	metaPath := storage.keyToPath(key) + variantMetaSuffix
+	oldMetaPath := metaPath + ".old"
+
+	err := os.Link(metaPath, oldMetaPath)
+	if err != nil {
+		t.Fatalf("giving the .meta file a second name: %v", err)
+	}
+
+	_, err = storage.Store(key, bytes.NewReader([]byte("new variant data")),
+		testContentTypeJPEG)
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	oldMeta, err := os.Stat(oldMetaPath)
+	if err != nil {
+		t.Fatalf("stat of the old .meta file: %v", err)
+	}
+
+	newMeta, err := os.Stat(metaPath)
+	if err != nil {
+		t.Fatalf("stat of the new .meta file: %v", err)
+	}
+
+	if os.SameFile(oldMeta, newMeta) {
+		t.Error("Store() wrote into the old .meta file instead of putting " +
+			"a new one in its place")
+	}
+
+	reader, _, contentType, err := storage.LoadWithMeta(key)
+	if err != nil {
+		t.Fatalf("LoadWithMeta() error = %v", err)
+	}
+
+	_ = reader.Close()
+
+	t.Logf("content type after the store: %s", contentType)
+
+	if contentType != testContentTypeJPEG {
+		t.Errorf("content type = %q, want %q", contentType, testContentTypeJPEG)
+	}
+}
+
+// TestContentStorage_StoreHashedReplacesFileOfAnotherSize checks that a
+// store over a file of another size at the content's path, such as a
 // partial file a crash left, replaces it with the content.
-func TestContentStorage_StoreReplacesFileOfAnotherSize(t *testing.T) {
+func TestContentStorage_StoreHashedReplacesFileOfAnotherSize(t *testing.T) {
 	t.Parallel()
 
 	storage, err := NewContentStorage(t.TempDir())
@@ -272,12 +328,13 @@ func TestContentStorage_StoreReplacesFileOfAnotherSize(t *testing.T) {
 	}
 
 	content := []byte("the whole source image")
-	key := imagerequest.Source{Host: testHostCDN, Path: testPathCat}.Key()
+	sum := sha256.Sum256(content)
-	path := storage.keyToPath(key)
+	hash := ContentHash(hex.EncodeToString(sum[:]))
+	path := storage.hashToPath(hash)
 
 	err = os.MkdirAll(filepath.Dir(path), StorageDirPerm)
 	if err != nil {
-		t.Fatalf("creating the source's directory: %v", err)
+		t.Fatalf("creating the content's directory: %v", err)
 	}
 
 	err = os.WriteFile(path, content[:5], StorageFilePerm)
@@ -285,14 +342,14 @@ func TestContentStorage_StoreReplacesFileOfAnotherSize(t *testing.T) {
 		t.Fatalf("writing a partial file: %v", err)
 	}
 
-	_, err = storage.Store(key, content)
+	_, err = storage.StoreHashed(hash, content)
 	if err != nil {
-		t.Fatalf("Store() error = %v", err)
+		t.Fatalf("StoreHashed() error = %v", err)
 	}
 
-	stored, _, err := storage.LoadWithSize(key)
+	stored, err := storage.Load(hash)
 	if err != nil {
-		t.Fatalf("LoadWithSize() error = %v", err)
+		t.Fatalf("Load() error = %v", err)
 	}
 
 	defer func() { _ = stored.Close() }()

internal/imgcache/pendingaccesstimes.go

@@ -1,160 +0,0 @@
-package imgcache
-
-import (
-	"context"
-	"fmt"
-	"time"
-
-	"sneak.berlin/go/pixa/internal/imagerequest"
-)
-
-// pendingWriteInterval is how often the goroutine
-// StartPendingAccessTimeWrites starts writes the pending access times.
-// SQLite's CURRENT_TIMESTAMP, which an access time is written as, counts
-// whole seconds.
-const pendingWriteInterval = time.Second
-
-// StartPendingAccessTimeWrites starts the goroutine that writes, every
-// pendingWriteInterval, the pending access times in one transaction.
-// Requests only hand these to it, so none waits for the database to record
-// them, and only this goroutine's write ever waits for it. It is a no-op
-// when already started. The goroutine outlives the caller, so it runs with
-// its own context, which StopPendingAccessTimeWrites cancels to tell it to
-// finish.
-func (c *Cache) StartPendingAccessTimeWrites() {
-	if c.pendingAccessTimesCancel != nil {
-		return
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	c.pendingAccessTimesCancel = cancel
-
-	go func() {
-		c.pendingAccessTimeWriteLoop(ctx)
-	}()
-}
-
-// StopPendingAccessTimeWrites tells the goroutine
-// StartPendingAccessTimeWrites started, if it did, to finish, and waits for
-// its write under way to end and for it to return. It then writes the
-// pending access times left, once, so that they are written before the
-// database closes. It waits for all of this at most until ctx ends. When
-// access times are not written, it logs that and returns an error.
-func (c *Cache) StopPendingAccessTimeWrites(ctx context.Context) error {
-	var err error
-
-	if c.pendingAccessTimesCancel != nil {
-		c.pendingAccessTimesCancel()
-
-		select {
-		case <-c.pendingAccessTimesDone:
-		case <-ctx.Done():
-			// The write given up on here may not reach the database:
-			// database/sql closes without waiting for a query, and a write
-			// still waiting for the connection fails when the database
-			// closes. Nothing is written here.
-			err = fmt.Errorf("access times still being written: %w", ctx.Err())
-		}
-	}
-
-	if err == nil {
-		err = c.writePendingAccessTimes(ctx)
-	}
-
-	if err != nil {
-		c.log.Error("access times not written at shutdown", "error", err)
-	}
-
-	return err
-}
-
-// pendingAccessTimeWriteLoop is the body of the goroutine
-// StartPendingAccessTimeWrites starts. Once ctx is cancelled it starts no
-// write and returns, but does not cut off a write under way then. Access
-// times whose write fails are dropped.
-func (c *Cache) pendingAccessTimeWriteLoop(ctx context.Context) {
-	defer close(c.pendingAccessTimesDone)
-
-	ticker := time.NewTicker(pendingWriteInterval)
-	defer ticker.Stop()
-
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-		}
-
-		// select picks at random when ctx is cancelled and a tick waits
-		// too.
-		if ctx.Err() != nil {
-			return
-		}
-
-		err := c.writePendingAccessTimes(context.WithoutCancel(ctx))
-		if err != nil {
-			c.log.Warn("failed to write access times", "error", err)
-		}
-	}
-}
-
-// writePendingAccessTimes takes out the variants waiting in
-// pendingVariantAccessTimes and the sources waiting in
-// pendingSourceAccessTimes, and sets their last_accessed_at to now in one
-// transaction, once for each however often it was used. Nothing else takes
-// from those channels while it runs: only the goroutine
-// StartPendingAccessTimeWrites starts calls it, or
-// StopPendingAccessTimeWrites once that goroutine has returned.
-func (c *Cache) writePendingAccessTimes(ctx context.Context) error {
-	variants := make(map[imagerequest.VariantKey]struct{})
-
-	for range len(c.pendingVariantAccessTimes) {
-		variants[<-c.pendingVariantAccessTimes] = struct{}{}
-	}
-
-	sources := make(map[imagerequest.SourceKey]struct{})
-
-	for range len(c.pendingSourceAccessTimes) {
-		sources[<-c.pendingSourceAccessTimes] = struct{}{}
-	}
-
-	accessTimes := len(variants) + len(sources)
-	if accessTimes == 0 {
-		return nil
-	}
-
-	tx, err := c.db.BeginTx(ctx, nil)
-	if err != nil {
-		return fmt.Errorf("failed to write %d access times: %w", accessTimes, err)
-	}
-
-	// Does nothing once the transaction is committed
-	defer func() { _ = tx.Rollback() }()
-
-	for cacheKey := range variants {
-		_, err = tx.ExecContext(ctx, `
-			UPDATE variant_content SET last_accessed_at = CURRENT_TIMESTAMP
-			WHERE cache_key = ?
-		`, string(cacheKey))
-		if err != nil {
-			return fmt.Errorf("failed to write %d access times: %w", accessTimes, err)
-		}
-	}
-
-	for sourceKey := range sources {
-		_, err = tx.ExecContext(ctx, `
-			UPDATE source_content SET last_accessed_at = CURRENT_TIMESTAMP
-			WHERE source_key = ?
-		`, string(sourceKey))
-		if err != nil {
-			return fmt.Errorf("failed to write %d access times: %w", accessTimes, err)
-		}
-	}
-
-	err = tx.Commit()
-	if err != nil {
-		return fmt.Errorf("failed to write %d access times: %w", accessTimes, err)
-	}
-
-	return nil
-}

internal/imgcache/pendingaccesstimes_internal_test.go

@@ -1,319 +0,0 @@
-package imgcache
-
-import (
-	"bytes"
-	"context"
-	"database/sql"
-	"errors"
-	"log/slog"
-	"strings"
-	"testing"
-	"time"
-
-	"sneak.berlin/go/pixa/internal/imagerequest"
-)
-
-// pendingAccessTimesWait is how long a test waits for the database's
-// connection, for an access time to reach the database, for a write to start
-// waiting for the connection, for a request to return past its deadline, or
-// for StopPendingAccessTimeWrites to return.
-const pendingAccessTimesWait = 5 * time.Second
-
-// otherWritesWait is how long a test gives other writes, once one write waits
-// for the database's connection, to start waiting for it too.
-const otherWritesWait = 100 * time.Millisecond
-
-// holdDatabase takes the one connection of cache's database, so that every
-// other query waits for it, and returns the func that frees it.
-func holdDatabase(t *testing.T, cache *Cache) func() {
-	t.Helper()
-
-	ctx, cancel := context.WithTimeout(t.Context(), pendingAccessTimesWait)
-	defer cancel()
-
-	conn, err := cache.db.Conn(ctx)
-	if err != nil {
-		t.Fatalf("failed to take the database connection: %v", err)
-	}
-
-	return func() { _ = conn.Close() }
-}
-
-// waitForConnectionWaits waits until db.Stats().WaitCount, the number of
-// times a caller has waited for a connection, reaches waits.
-func waitForConnectionWaits(t *testing.T, db *sql.DB, waits int64) {
-	t.Helper()
-
-	deadline := time.Now().Add(pendingAccessTimesWait)
-
-	for db.Stats().WaitCount < waits {
-		if time.Now().After(deadline) {
-			t.Fatalf("callers waited for the database connection %d times, want %d",
-				db.Stats().WaitCount, waits)
-		}
-
-		time.Sleep(10 * time.Millisecond)
-	}
-}
-
-// TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy holds the
-// database's one connection while a request whose fetch is held reaches its
-// deadline. The request must return with the deadline's error while the
-// connection is still held, as it waits for no database write past its
-// deadline.
-func TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy(t *testing.T) {
-	t.Parallel()
-
-	svc, fixtures, fetcher := setupHeldFetchService(t)
-
-	svc.cache.StartPendingAccessTimeWrites()
-	defer func() { _ = svc.cache.StopPendingAccessTimeWrites(t.Context()) }()
-
-	// Room for the request to reach its fetch on a busy host
-	const timeout = 2 * time.Second
-
-	ctx, cancel := context.WithTimeout(t.Context(), timeout)
-	defer cancel()
-
-	deadline, _ := ctx.Deadline()
-
-	results := startGet(ctx, svc, photoVariant(fixtures, 85, imagerequest.FitCover))
-
-	// The request has made its database reads by the time it fetches.
-	select {
-	case <-fetcher.started:
-	case <-time.After(timeout):
-		t.Fatal("request did not reach its fetch by its deadline")
-	}
-
-	releaseDatabase := holdDatabase(t, svc.cache)
-	defer releaseDatabase()
-
-	select {
-	case got := <-results:
-		t.Logf("Get() returned %v after its deadline, error = %v",
-			time.Since(deadline), got.err)
-
-		if !errors.Is(got.err, context.DeadlineExceeded) {
-			t.Errorf("Get() error = %v, want %v", got.err, context.DeadlineExceeded)
-		}
-	case <-time.After(time.Until(deadline) + pendingAccessTimesWait):
-		t.Fatal("request did not return while the database was busy")
-	}
-}
-
-// TestStopPendingAccessTimeWrites_LetsTheWriteUnderWayFinish holds the
-// database's one connection while the goroutine that writes the pending
-// access times waits for it, hands over another access time, then stops that
-// goroutine. The stop must leave the write under way to finish rather than
-// cut it off, and once the connection is free it must write the access time
-// that write left.
-func TestStopPendingAccessTimeWrites_LetsTheWriteUnderWayFinish(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	anHourAgo := time.Now().Add(-time.Hour)
-
-	for _, key := range []imagerequest.VariantKey{testVariantKeyOne, testVariantKeyTwo} {
-		storeEvictionTestVariant(t, cache, key, []byte("variant bytes"))
-		setVariantLastAccessed(t, cache, key, anHourAgo)
-	}
-
-	cache.StartPendingAccessTimeWrites()
-	defer func() { _ = cache.StopPendingAccessTimeWrites(t.Context()) }()
-
-	releaseDatabase := holdDatabase(t, cache)
-	defer releaseDatabase()
-
-	waitsBefore := cache.db.Stats().WaitCount
-
-	cache.touchVariant(testVariantKeyOne)
-
-	// The goroutine's write waits for the connection.
-	waitForConnectionWaits(t, cache.db, waitsBefore+1)
-
-	// Handed over after that write took the pending access times
-	cache.touchVariant(testVariantKeyTwo)
-
-	// The goroutine is told to finish here as well as by the stop, so that it
-	// is told before its write under way ends, however late the stop runs.
-	// The access time above then reaches the database only through the
-	// stop's own write.
-	cache.pendingAccessTimesCancel()
-
-	stopped := make(chan error, 1)
-
-	go func() {
-		stopped <- cache.StopPendingAccessTimeWrites(t.Context())
-	}()
-
-	// Had the stop cut off the write under way, its own write would wait for
-	// the connection too.
-	time.Sleep(otherWritesWait)
-
-	waits := cache.db.Stats().WaitCount - waitsBefore
-	t.Logf("%d writes waited for the database", waits)
-
-	if waits > 1 {
-		t.Errorf("%d writes waited for the database, want 1: "+
-			"the stop cut off the write under way", waits)
-	}
-
-	releaseDatabase()
-
-	select {
-	case err := <-stopped:
-		if err != nil {
-			t.Fatalf("StopPendingAccessTimeWrites() error = %v", err)
-		}
-	case <-time.After(pendingAccessTimesWait):
-		t.Fatal("StopPendingAccessTimeWrites() did not return once the database was free")
-	}
-
-	for _, key := range []imagerequest.VariantKey{testVariantKeyOne, testVariantKeyTwo} {
-		if countRows(t, cache, `
-			SELECT COUNT(*) FROM variant_content
-			WHERE cache_key = ? AND last_accessed_at > ?
-		`, string(key), anHourAgo.UTC().Format(sqliteTimestampFormat)) != 1 {
-			t.Errorf("the access time of variant %s was not written", key)
-		}
-	}
-}
-
-// TestStopPendingAccessTimeWrites_ReturnsWhenItsContextEnds holds the
-// database's one connection while the goroutine that writes the pending
-// access times waits for it, then stops that goroutine with a context that
-// ends first. The stop must return the context's error, and the write under
-// way must still reach the database once the connection is free.
-func TestStopPendingAccessTimeWrites_ReturnsWhenItsContextEnds(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	storeEvictionTestVariant(t, cache, testVariantKeyOne, []byte("variant bytes"))
-
-	anHourAgo := time.Now().Add(-time.Hour)
-	setVariantLastAccessed(t, cache, testVariantKeyOne, anHourAgo)
-
-	cache.StartPendingAccessTimeWrites()
-	defer func() { _ = cache.StopPendingAccessTimeWrites(t.Context()) }()
-
-	releaseDatabase := holdDatabase(t, cache)
-	defer releaseDatabase()
-
-	waitsBefore := cache.db.Stats().WaitCount
-
-	cache.touchVariant(testVariantKeyOne)
-
-	// The goroutine's write waits for the connection.
-	waitForConnectionWaits(t, cache.db, waitsBefore+1)
-
-	stopCtx, cancelStop := context.WithCancel(t.Context())
-	cancelStop()
-
-	stopped := make(chan error, 1)
-
-	go func() {
-		stopped <- cache.StopPendingAccessTimeWrites(stopCtx)
-	}()
-
-	select {
-	case err := <-stopped:
-		if !errors.Is(err, context.Canceled) {
-			t.Errorf("StopPendingAccessTimeWrites() error = %v, want %v",
-				err, context.Canceled)
-		}
-	case <-time.After(pendingAccessTimesWait):
-		t.Fatal("StopPendingAccessTimeWrites() did not return once its context ended")
-	}
-
-	releaseDatabase()
-
-	deadline := time.Now().Add(pendingAccessTimesWait)
-
-	for countRows(t, cache, `
-		SELECT COUNT(*) FROM variant_content
-		WHERE cache_key = ? AND last_accessed_at > ?
-	`, string(testVariantKeyOne), anHourAgo.UTC().Format(sqliteTimestampFormat)) == 0 {
-		if time.Now().After(deadline) {
-			t.Fatal("the access time being written was not written")
-		}
-
-		time.Sleep(10 * time.Millisecond)
-	}
-}
-
-// TestLookupSource_HandsAccessTimeToTheBackgroundWriter finds a cached source
-// whose access time is an hour old. LookupSource must not write the access
-// time itself but hand it over to be written, and StopPendingAccessTimeWrites
-// must then write it.
-func TestLookupSource_HandsAccessTimeToTheBackgroundWriter(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	key := storeEvictionTestSource(t, cache, "example.com", "/photo.jpg",
-		[]byte("source bytes"))
-	anHourAgo := time.Now().Add(-time.Hour)
-	setSourceLastAccessed(t, cache, key, anHourAgo)
-
-	touchedQuery := `
-		SELECT COUNT(*) FROM source_content
-		WHERE source_key = ? AND last_accessed_at > ?
-	`
-	anHourAgoInDatabase := anHourAgo.UTC().Format(sqliteTimestampFormat)
-
-	found, err := cache.LookupSource(t.Context(), &imagerequest.Request{
-		Source: imagerequest.Source{Host: "example.com", Path: "/photo.jpg"},
-	})
-	if err != nil || found != key {
-		t.Fatalf("LookupSource() = %q, %v; want %q", found, err, key)
-	}
-
-	if countRows(t, cache, touchedQuery, string(key), anHourAgoInDatabase) != 0 {
-		t.Error("LookupSource wrote the source's access time itself")
-	}
-
-	if waiting := len(cache.pendingSourceAccessTimes); waiting != 1 {
-		t.Errorf("%d access times of sources wait to be written, want 1", waiting)
-	}
-
-	err = cache.StopPendingAccessTimeWrites(t.Context())
-	if err != nil {
-		t.Fatalf("StopPendingAccessTimeWrites() error = %v", err)
-	}
-
-	if countRows(t, cache, touchedQuery, string(key), anHourAgoInDatabase) != 1 {
-		t.Error("the source's access time was not written")
-	}
-}
-
-// TestStopPendingAccessTimeWrites_LogsWhatWasNotWritten makes the write of
-// the access times fail at shutdown, by dropping the table they are written
-// to. The stop must return an error and log that access times were not
-// written.
-func TestStopPendingAccessTimeWrites_LogsWhatWasNotWritten(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-
-	var logs bytes.Buffer
-
-	cache.log = slog.New(slog.NewJSONHandler(&logs, nil))
-
-	cache.touchVariant(testVariantKeyOne)
-
-	_, err := cache.db.ExecContext(t.Context(), `DROP TABLE variant_content`)
-	if err != nil {
-		t.Fatalf("dropping variant_content: %v", err)
-	}
-
-	err = cache.StopPendingAccessTimeWrites(t.Context())
-	t.Logf("StopPendingAccessTimeWrites() error = %v; logged:\n%s", err, logs.String())
-
-	if err == nil {
-		t.Error("StopPendingAccessTimeWrites() error = nil, want the access times' error")
-	}
-
-	if !strings.Contains(logs.String(), "access times not written at shutdown") {
-		t.Error("the access times not written were not logged")
-	}
-}

internal/imgcache/pendingcounts.go

@@ -0,0 +1,149 @@
+package imgcache
+
+import (
+	"context"
+	"fmt"
+	"sync/atomic"
+)
+
+// StartPendingCountWrites starts the goroutine that writes the pending
+// counts to the database whenever there are some, one UPDATE at a time:
+// however many requests pass their deadline before their counts are
+// written, at most this one write waits for the database. It is a no-op
+// when already started. The goroutine outlives the caller, so it runs with
+// its own context, which StopPendingCountWrites cancels to tell it to
+// finish.
+func (c *Cache) StartPendingCountWrites() {
+	if c.pendingCountsCancel != nil {
+		return
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	c.pendingCountsCancel = cancel
+
+	go func() {
+		c.pendingCountWriteLoop(ctx)
+	}()
+}
+
+// StopPendingCountWrites tells the goroutine StartPendingCountWrites
+// started, if it did, to finish, and waits for its write under way to end
+// and for it to return. It then writes the pending counts left, so that
+// they are written before the database closes. It waits for all of this at
+// most until ctx ends, then logs the counts not written and returns an
+// error.
+func (c *Cache) StopPendingCountWrites(ctx context.Context) error {
+	var err error
+
+	if c.pendingCountsCancel != nil {
+		c.pendingCountsCancel()
+
+		select {
+		case <-c.pendingCountsDone:
+		case <-ctx.Done():
+			// The write given up on here may not reach the database:
+			// database/sql closes without waiting for a query, and a
+			// write still waiting for the connection fails when the
+			// database closes.
+			err = fmt.Errorf("pending counts still being written: %w", ctx.Err())
+		}
+	}
+
+	if err == nil {
+		err = c.writePendingCounts(ctx)
+	}
+
+	if err != nil {
+		c.log.Error("counts not written at shutdown",
+			"hits", c.pendingHits.Load(),
+			"misses", c.pendingMisses.Load(),
+			"upstream_fetches", c.pendingUpstreamFetches.Load(),
+			"upstream_fetch_bytes", c.pendingUpstreamFetchBytes.Load(),
+			"transforms", c.pendingTransforms.Load(),
+			"error", err,
+		)
+
+		return err
+	}
+
+	return nil
+}
+
+// pendingCountWriteLoop is the body of the goroutine
+// StartPendingCountWrites starts. Once ctx is cancelled it starts no write
+// and returns, but does not cut off a write under way then. A write that
+// fails leaves the counts pending, for the next write.
+func (c *Cache) pendingCountWriteLoop(ctx context.Context) {
+	defer close(c.pendingCountsDone)
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-c.pendingCountsAdded:
+		}
+
+		// select picks at random when ctx is cancelled and a wakeup
+		// waits too.
+		if ctx.Err() != nil {
+			return
+		}
+
+		err := c.writePendingCounts(context.WithoutCancel(ctx))
+		if err != nil {
+			c.log.Warn("failed to write pending counts", "error", err)
+		}
+	}
+}
+
+// addPendingCount adds n to pendingCount, one of the pending counts, and
+// wakes the goroutine that writes them. pendingCountsAdded has capacity one,
+// so a wakeup already waiting is enough.
+func (c *Cache) addPendingCount(pendingCount *atomic.Int64, n int64) {
+	pendingCount.Add(n)
+
+	select {
+	case c.pendingCountsAdded <- struct{}{}:
+	default:
+	}
+}
+
+// writePendingCounts adds the pending counts to the cache_stats row in one
+// UPDATE, then takes what it wrote out of them, leaving any added
+// meanwhile. When the UPDATE fails, they all stay pending.
+func (c *Cache) writePendingCounts(ctx context.Context) error {
+	c.pendingCountsWriteMutex.Lock()
+	defer c.pendingCountsWriteMutex.Unlock()
+
+	hits := c.pendingHits.Load()
+	misses := c.pendingMisses.Load()
+	upstreamFetches := c.pendingUpstreamFetches.Load()
+	upstreamFetchBytes := c.pendingUpstreamFetchBytes.Load()
+	transforms := c.pendingTransforms.Load()
+
+	if hits+misses+upstreamFetches+upstreamFetchBytes+transforms == 0 {
+		return nil
+	}
+
+	_, err := c.db.ExecContext(ctx, `
+		UPDATE cache_stats
+		SET hit_count = hit_count + ?,
+		    miss_count = miss_count + ?,
+		    upstream_fetch_count = upstream_fetch_count + ?,
+		    upstream_fetch_bytes = upstream_fetch_bytes + ?,
+		    transform_count = transform_count + ?,
+		    last_updated_at = CURRENT_TIMESTAMP
+		WHERE id = 1
+	`, hits, misses, upstreamFetches, upstreamFetchBytes, transforms)
+	if err != nil {
+		return fmt.Errorf("failed to write pending counts: %w", err)
+	}
+
+	c.pendingHits.Add(-hits)
+	c.pendingMisses.Add(-misses)
+	c.pendingUpstreamFetches.Add(-upstreamFetches)
+	c.pendingUpstreamFetchBytes.Add(-upstreamFetchBytes)
+	c.pendingTransforms.Add(-transforms)
+
+	return nil
+}

internal/imgcache/pendingcounts_internal_test.go

@@ -0,0 +1,329 @@
+package imgcache
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"testing"
+	"time"
+
+	"sneak.berlin/go/pixa/internal/imagerequest"
+)
+
+// pendingCountsWait is how long a test waits for the database's connection,
+// for a count to reach the database, for a write to start waiting for the
+// connection, for a request to return past its deadline, or for
+// StopPendingCountWrites to return.
+const pendingCountsWait = 5 * time.Second
+
+// otherWritesWait is how long a test gives other writes, once one write waits
+// for the database's connection, to start waiting for it too.
+const otherWritesWait = 100 * time.Millisecond
+
+// holdDatabase takes the one connection of cache's database, so that every
+// other query waits for it, and returns the func that frees it.
+func holdDatabase(t *testing.T, cache *Cache) func() {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(t.Context(), pendingCountsWait)
+	defer cancel()
+
+	conn, err := cache.db.Conn(ctx)
+	if err != nil {
+		t.Fatalf("failed to take the database connection: %v", err)
+	}
+
+	return func() { _ = conn.Close() }
+}
+
+// waitForConnectionWaits waits until db.Stats().WaitCount, the number of
+// times a caller has waited for a connection, reaches waits.
+func waitForConnectionWaits(t *testing.T, db *sql.DB, waits int64) {
+	t.Helper()
+
+	deadline := time.Now().Add(pendingCountsWait)
+
+	for db.Stats().WaitCount < waits {
+		if time.Now().After(deadline) {
+			t.Fatalf("callers waited for the database connection %d times, want %d",
+				db.Stats().WaitCount, waits)
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+// waitForCounters waits until the cache_stats row holds want.
+func waitForCounters(t *testing.T, cache *Cache, want cacheStatsCounters) {
+	t.Helper()
+
+	deadline := time.Now().Add(pendingCountsWait)
+
+	for {
+		got := readCacheStatsCounters(t, cache)
+		if got == want {
+			return
+		}
+
+		if time.Now().After(deadline) {
+			t.Fatalf("counters = %+v, want %+v", got, want)
+		}
+
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+// TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy holds the
+// database's one connection while a request whose fetch is held reaches its
+// deadline. The request must return with the deadline's error while the
+// connection is still held, as it waits for no database write past its
+// deadline, and its miss must reach the database once the connection is free.
+func TestService_Get_ReturnsByItsDeadlineWhileTheDatabaseIsBusy(t *testing.T) {
+	t.Parallel()
+
+	svc, fixtures, fetcher := setupHeldFetchService(t)
+
+	svc.cache.StartPendingCountWrites()
+	defer func() { _ = svc.cache.StopPendingCountWrites(t.Context()) }()
+
+	// Room for the request to reach its fetch on a busy host
+	const timeout = 2 * time.Second
+
+	ctx, cancel := context.WithTimeout(t.Context(), timeout)
+	defer cancel()
+
+	deadline, _ := ctx.Deadline()
+
+	results := startGet(ctx, svc, photoVariant(fixtures, 85, imagerequest.FitCover))
+
+	// The request has made its database reads by the time it fetches.
+	select {
+	case <-fetcher.started:
+	case <-time.After(timeout):
+		t.Fatal("request did not reach its fetch by its deadline")
+	}
+
+	releaseDatabase := holdDatabase(t, svc.cache)
+	defer releaseDatabase()
+
+	select {
+	case got := <-results:
+		t.Logf("Get() returned %v after its deadline, error = %v",
+			time.Since(deadline), got.err)
+
+		if !errors.Is(got.err, context.DeadlineExceeded) {
+			t.Errorf("Get() error = %v, want %v", got.err, context.DeadlineExceeded)
+		}
+	case <-time.After(time.Until(deadline) + pendingCountsWait):
+		t.Fatal("request did not return while the database was busy")
+	}
+
+	releaseDatabase()
+
+	waitForCounters(t, svc.cache, cacheStatsCounters{missCount: 1})
+}
+
+// TestIncrementStats_ManyCountsPastTheirDeadlineLeaveOneWriteWaiting holds the
+// database's one connection while many misses are counted past their
+// deadline. At most one write may then wait for the connection, and every
+// miss must reach the database once it is free.
+func TestIncrementStats_ManyCountsPastTheirDeadlineLeaveOneWriteWaiting(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	cache.StartPendingCountWrites()
+	defer func() { _ = cache.StopPendingCountWrites(t.Context()) }()
+
+	releaseDatabase := holdDatabase(t, cache)
+	defer releaseDatabase()
+
+	waitsBefore := cache.db.Stats().WaitCount
+
+	// Writes given a context past its deadline fail at once.
+	ended, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	const misses = 20
+
+	for range misses {
+		cache.IncrementStats(ended, false, 0)
+	}
+
+	// Once one write waits for the connection, any others start waiting too.
+	waitForConnectionWaits(t, cache.db, waitsBefore+1)
+	time.Sleep(otherWritesWait)
+
+	waits := cache.db.Stats().WaitCount - waitsBefore
+	t.Logf("%d writes waited for the database", waits)
+
+	if waits > 1 {
+		t.Errorf("%d writes waited for the database, want at most 1", waits)
+	}
+
+	releaseDatabase()
+
+	waitForCounters(t, cache, cacheStatsCounters{missCount: misses})
+}
+
+// TestStats_IncludesPendingCounts counts hits and misses whose writes miss
+// their deadline, and checks that Stats adds them to the database's counts
+// before they are written.
+func TestStats_IncludesPendingCounts(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	_, err := cache.db.ExecContext(t.Context(),
+		`UPDATE cache_stats SET hit_count = 75, miss_count = 25 WHERE id = 1`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Writes given a context past its deadline fail at once.
+	ended, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	cache.IncrementStats(ended, true, 0)
+	cache.IncrementStats(ended, true, 0)
+	cache.IncrementStats(ended, false, 0)
+
+	stats, err := cache.Stats(t.Context())
+	if err != nil {
+		t.Fatalf("Stats() error = %v", err)
+	}
+
+	if stats.HitCount != 77 || stats.MissCount != 26 {
+		t.Errorf("HitCount = %d, MissCount = %d, want 77 and 26",
+			stats.HitCount, stats.MissCount)
+	}
+
+	want := cacheStatsCounters{hitCount: 75, missCount: 25}
+	if got := readCacheStatsCounters(t, cache); got != want {
+		t.Errorf("counters in the database = %+v, want %+v", got, want)
+	}
+}
+
+// TestStopPendingCountWrites_WritesPendingCounts holds the database's one
+// connection while the goroutine that writes the pending counts waits for it,
+// counts more, then stops that goroutine. The stop must leave the write under
+// way to finish rather than cut it off, and once the connection is free it
+// must write the counts that write left.
+func TestStopPendingCountWrites_WritesPendingCounts(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	cache.StartPendingCountWrites()
+	defer func() { _ = cache.StopPendingCountWrites(t.Context()) }()
+
+	releaseDatabase := holdDatabase(t, cache)
+	defer releaseDatabase()
+
+	waitsBefore := cache.db.Stats().WaitCount
+
+	// Writes given a context past its deadline fail at once.
+	ended, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	cache.IncrementStats(ended, true, 0)
+
+	// The goroutine's write waits for the connection.
+	waitForConnectionWaits(t, cache.db, waitsBefore+1)
+
+	// Counted after that write read the pending counts
+	cache.IncrementStats(ended, false, 0)
+	cache.IncrementUpstreamFetch(ended, 1024)
+	cache.IncrementTransformCount(ended)
+
+	// The goroutine is told to finish here as well as by the stop, so that it
+	// is told before its write under way ends, however late the stop runs.
+	// The counts above then reach the database only through the stop's own
+	// write.
+	cache.pendingCountsCancel()
+
+	stopped := make(chan error, 1)
+
+	go func() {
+		stopped <- cache.StopPendingCountWrites(t.Context())
+	}()
+
+	// Had the stop cut off the write under way, its own write would wait for
+	// the connection too.
+	time.Sleep(otherWritesWait)
+
+	waits := cache.db.Stats().WaitCount - waitsBefore
+	t.Logf("%d writes waited for the database", waits)
+
+	if waits > 1 {
+		t.Errorf("%d writes waited for the database, want 1: "+
+			"the stop cut off the write under way", waits)
+	}
+
+	releaseDatabase()
+
+	select {
+	case err := <-stopped:
+		if err != nil {
+			t.Fatalf("StopPendingCountWrites() error = %v", err)
+		}
+	case <-time.After(pendingCountsWait):
+		t.Fatal("StopPendingCountWrites() did not return once the database was free")
+	}
+
+	want := cacheStatsCounters{1, 1, 1, 1024, 1}
+	if got := readCacheStatsCounters(t, cache); got != want {
+		t.Errorf("counters = %+v, want %+v", got, want)
+	}
+}
+
+// TestStopPendingCountWrites_ReturnsWhenItsContextEnds holds the database's
+// one connection while the goroutine that writes the pending counts waits for
+// it, then stops that goroutine with a context that ends first. The stop must
+// return the context's error, and the write under way must still reach the
+// database once the connection is free.
+func TestStopPendingCountWrites_ReturnsWhenItsContextEnds(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<30)
+
+	cache.StartPendingCountWrites()
+	defer func() { _ = cache.StopPendingCountWrites(t.Context()) }()
+
+	releaseDatabase := holdDatabase(t, cache)
+	defer releaseDatabase()
+
+	waitsBefore := cache.db.Stats().WaitCount
+
+	// Writes given a context past its deadline fail at once.
+	ended, cancel := context.WithDeadline(t.Context(), time.Now())
+	defer cancel()
+
+	cache.IncrementStats(ended, true, 0)
+
+	// The goroutine's write waits for the connection.
+	waitForConnectionWaits(t, cache.db, waitsBefore+1)
+
+	stopCtx, cancelStop := context.WithCancel(t.Context())
+	cancelStop()
+
+	stopped := make(chan error, 1)
+
+	go func() {
+		stopped <- cache.StopPendingCountWrites(stopCtx)
+	}()
+
+	select {
+	case err := <-stopped:
+		if !errors.Is(err, context.Canceled) {
+			t.Errorf("StopPendingCountWrites() error = %v, want %v",
+				err, context.Canceled)
+		}
+	case <-time.After(pendingCountsWait):
+		t.Fatal("StopPendingCountWrites() did not return once its context ended")
+	}
+
+	releaseDatabase()
+
+	waitForCounters(t, cache, cacheStatsCounters{hitCount: 1})
+}

internal/imgcache/service.go

@@ -24,7 +24,8 @@ import (
 	"sneak.berlin/go/pixa/internal/signature"
 )
 
-// Service orchestrates the cache, fetcher, and processor.
+// Service implements the ImageCache interface, orchestrating cache,
+// fetcher, and processor.
 type Service struct {
 	cache           *Cache
 	fetcher         httpfetcher.Fetcher
@@ -139,37 +140,36 @@ var ErrProcessingTimedOut = errors.New(
 // While its source URL is in the negative cache, a cached variant is still
 // served and a variant not in the cache is still made from a cached source;
 // only a request that needs the source fetched is refused.
-//
-// A cache hit opens the variant file and makes no database call: its access
-// time is handed to the goroutine that StartPendingAccessTimeWrites starts,
-// without waiting for it, and its hit is counted in memory. A variant file
-// that cannot be served, such as one whose first bytes are not those of an
-// output format, is a miss, and the variant is made again.
 func (s *Service) Get(
 	ctx context.Context, req *imagerequest.Request,
 ) (*ImageResponse, error) {
 	// Propagate AllowHTTP setting to the request
 	req.AllowHTTP = s.allowHTTP
 
-	cacheKey := imagerequest.CacheKey(req)
+	// Check variant cache first (disk only, no DB)
+	result, err := s.cache.Lookup(ctx, req)
+	if err != nil {
+		s.log.Warn("cache lookup failed", "error", err)
+	}
 
-	reader, size, contentType, err := s.cache.GetVariant(cacheKey)
+	// Cache hit - serve directly from disk
-	if err == nil {
+	if result != nil && result.Hit {
-		s.cache.touchVariant(cacheKey)
+		reader, size, contentType, err := s.cache.GetVariant(result.CacheKey)
-		s.cache.IncrementStats(true, 0)
+		if err != nil {
+			s.log.Error("failed to get cached variant", "key", result.CacheKey, "error", err)
+			// Fall through to re-process
+		} else {
+			// Counted also when the request context has ended meanwhile
+			s.cache.IncrementStats(ctx, true, 0)
 
 			return &ImageResponse{
 				Content:       reader,
 				ContentLength: size,
 				ContentType:   contentType,
 				CacheStatus:   CacheHit,
-			ETag:          formatETag(cacheKey),
+				ETag:          formatETag(result.CacheKey),
 			}, nil
 		}
-
-	if !errors.Is(err, ErrNotFound) {
-		s.log.Warn("cached variant not served, making it again",
-			"cache_key", cacheKey, "error", err)
 	}
 
 	// Cache miss - get the variant, processed once for all the requests that
@@ -177,7 +177,7 @@ func (s *Service) Get(
 	// failed or the request context has ended meanwhile
 	response, err := s.processOrWait(ctx, req)
 
-	s.cache.IncrementStats(false, 0)
+	s.cache.IncrementStats(ctx, false, 0)
 
 	if err != nil {
 		return nil, err
@@ -188,6 +188,18 @@ func (s *Service) Get(
 	return response, nil
 }
 
+// Warm pre-fetches and caches an image without returning it.
+func (s *Service) Warm(ctx context.Context, req *imagerequest.Request) error {
+	_, err := s.Get(ctx, req)
+
+	return err
+}
+
+// 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 {
@@ -221,6 +233,30 @@ func (s *Service) ValidateRequest(req *imagerequest.Request) error {
 	return s.signer.Verify(req)
 }
 
+// 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.Request,
+	ttl time.Duration,
+) (string, error) {
+	if req.Transform.Quality == 0 {
+		req.Transform.Quality = 85
+	}
+
+	if req.Transform.FitMode == "" {
+		req.Transform.FitMode = imagerequest.FitCover
+	}
+
+	// Sets the request's Expires and Signature
+	path, sig, exp := s.signer.GenerateSignedURL(req, ttl)
+
+	return fmt.Sprintf("%s%s?sig=%s&exp=%d&q=%d&fit=%s",
+		baseURL, path, sig, exp, req.Transform.Quality, req.Transform.FitMode), nil
+}
+
 // errPanicked is returned when processing a variant panicked.
 var errPanicked = errors.New("panic while processing image")
 
@@ -323,9 +359,9 @@ func withoutCancelKeepingDeadline(
 // returns it with its size; nil if the cached data is unavailable, empty or
 // exceeds maxResponseSize.
 func (s *Service) loadCachedSource(
-	sourceKey imagerequest.SourceKey,
+	contentHash ContentHash,
 ) (io.ReadCloser, int64) {
-	reader, size, err := s.cache.GetSourceContent(sourceKey)
+	reader, size, err := s.cache.GetSourceContent(contentHash)
 	if err != nil {
 		s.log.Warn("failed to load cached source, fetching", "error", err)
 
@@ -336,7 +372,7 @@ func (s *Service) loadCachedSource(
 		_ = reader.Close()
 
 		s.log.Warn("cached source exceeds max response size, discarding",
-			"source_key", sourceKey,
+			"hash", contentHash,
 			"max_bytes", s.maxResponseSize,
 		)
 
@@ -360,7 +396,7 @@ func (s *Service) processFromSourceOrFetch(
 	cacheKey imagerequest.VariantKey,
 ) (*processedVariant, error) {
 	// Check if we have cached source content
-	sourceKey, err := s.cache.LookupSource(ctx, req)
+	contentHash, _, err := s.cache.LookupSource(ctx, req)
 	if err != nil {
 		s.log.Warn("source lookup failed", "error", err)
 	}
@@ -370,9 +406,9 @@ func (s *Service) processFromSourceOrFetch(
 		sourceSize int64
 	)
 
-	if sourceKey != "" {
+	if contentHash != "" {
-		s.log.Debug("using cached source", "source_key", sourceKey)
+		s.log.Debug("using cached source", "hash", contentHash)
-		source, sourceSize = s.loadCachedSource(sourceKey)
+		source, sourceSize = s.loadCachedSource(contentHash)
 	}
 
 	// Fetch from upstream if we don't have source data or it's empty
@@ -421,7 +457,7 @@ func (s *Service) fetchAndProcess(
 	if err != nil {
 		// Store negative cache for certain errors
 		if isNegativeCacheable(err) {
-			s.storeNegative(ctx, req)
+			s.storeNegative(ctx, req, extractStatusCode(err), err)
 		}
 
 		return nil, fmt.Errorf("upstream fetch failed: %w", err)
@@ -438,7 +474,7 @@ func (s *Service) fetchAndProcess(
 	fetchBytes := int64(len(sourceData))
 
 	// Counted also when the request context has ended meanwhile
-	s.cache.IncrementUpstreamFetch(fetchBytes)
+	s.cache.IncrementUpstreamFetch(ctx, fetchBytes)
 
 	if err != nil {
 		return nil, fmt.Errorf("failed to read upstream response: %w", err)
@@ -475,13 +511,13 @@ func (s *Service) fetchAndProcess(
 		s.log.Warn("source refused", "request_id", middleware.GetReqID(ctx),
 			"host", req.Source.Host, "path", req.Source.Path,
 			"content_type", fetchResult.ContentType, "error", err)
-		s.storeNegative(ctx, req)
+		s.storeNegative(ctx, req, httpStatusUnsupportedMediaType, err)
 
 		return nil, fmt.Errorf("content validation failed: %w", err)
 	}
 
 	// Store source content
-	_, err = s.cache.StoreSource(ctx, req, bytes.NewReader(sourceData))
+	_, err = s.cache.StoreSource(ctx, req, bytes.NewReader(sourceData), fetchResult)
 	if err != nil {
 		s.log.Warn("failed to store source content", "error", err)
 		// Continue even if caching fails
@@ -493,13 +529,15 @@ func (s *Service) fetchAndProcess(
 }
 
 // storeNegative stores a negative cache entry for req's source, whose fetch
-// failed, so the source is not fetched again until the entry expires. A
+// failed with err, so the source is not fetched again until the entry
-// failure to store the entry is only logged.
+// expires. A failure to store the entry is only logged.
-func (s *Service) storeNegative(ctx context.Context, req *imagerequest.Request) {
+func (s *Service) storeNegative(
-	err := s.cache.StoreNegative(ctx, req)
+	ctx context.Context, req *imagerequest.Request, statusCode int, err error,
-	if err != nil {
+) {
+	storeErr := s.cache.StoreNegative(ctx, req, statusCode, err.Error())
+	if storeErr != nil {
 		s.log.Warn("failed to store negative cache entry",
-			"host", req.Source.Host, "path", req.Source.Path, "error", err)
+			"host", req.Source.Host, "path", req.Source.Path, "error", storeErr)
 	}
 }
 
@@ -537,7 +575,7 @@ func (s *Service) processAndStore(
 	processDuration := time.Since(processStart)
 
 	// Counted also when the request context has ended meanwhile
-	s.cache.IncrementTransformCount()
+	s.cache.IncrementTransformCount(ctx)
 
 	// Read processed content
 	processedData, err := io.ReadAll(processResult.Content)
@@ -575,7 +613,9 @@ func (s *Service) processAndStore(
 	)
 
 	// Store variant to cache
-	err = s.cache.StoreVariant(ctx, cacheKey, bytes.NewReader(processedData))
+	err = s.cache.StoreVariant(
+		ctx, cacheKey, bytes.NewReader(processedData), processResult.ContentType,
+	)
 	if err != nil {
 		s.log.Warn("failed to store variant", "error", err)
 		// Continue even if caching fails
@@ -588,11 +628,28 @@ func (s *Service) processAndStore(
 	}, nil
 }
 
+// HTTP status codes for error responses.
+const (
+	httpStatusBadGateway           = 502
+	httpStatusInternalError        = 500
+	httpStatusUnsupportedMediaType = 415
+)
+
 // isNegativeCacheable returns true if the error should be cached.
 func isNegativeCacheable(err error) bool {
 	return errors.Is(err, httpfetcher.ErrUpstreamError)
 }
 
+// extractStatusCode extracts HTTP status code from error message.
+func extractStatusCode(err error) int {
+	// Default to 502 Bad Gateway for upstream errors
+	if errors.Is(err, httpfetcher.ErrUpstreamError) {
+		return httpStatusBadGateway
+	}
+
+	return httpStatusInternalError
+}
+
 // etagHashLength is the number of hash characters to use for ETags.
 const etagHashLength = 16
 

internal/imgcache/service_internal_test.go

@@ -2,6 +2,7 @@ package imgcache
 
 import (
 	"context"
+	"encoding/json"
 	"io"
 	"os"
 	"testing"
@@ -549,15 +550,21 @@ func TestService_Get_Caching(t *testing.T) {
 
 // TestService_Get_ServesSourceAndVariantCachedTwoDaysAgo caches a source and
 // a variant of it and sets back two days every time pixa stored for them.
-// For the source: last_accessed_at in source_content, and the access and
+// For the source: fetched_at in source_metadata, fetched_at and
-// modification times of its file. For the variant: last_accessed_at in
+// last_accessed_at in source_content, the fetched_at in its metadata file,
-// variant_content, and the access and modification times of its file. It
+// and the access and modification times of its file and of its metadata
-// then checks that the variant is still served from the cache and that a new
+// file. For the variant: created_at and last_accessed_at in variant_content,
-// variant is made from the cached source without fetching it again.
+// the created_at in its .meta file, and the access and modification times of
+// its file and of its .meta file. It then checks that the variant is still
+// served from the cache and that a new variant is made from the cached source
+// without fetching it again.
 //
 // Left at the present: the files' status change and birth times, which a
 // program cannot set, and the times of the directories holding the files,
-// which other entries share.
+// which other entries share. The source's stored response headers are empty,
+// as the mock fetcher sends none. expires_at, etag and last_modified in
+// source_metadata and in the metadata file are never written, nor are the
+// request_cache and output_content tables.
 func TestService_Get_ServesSourceAndVariantCachedTwoDaysAgo(t *testing.T) {
 	t.Parallel()
 
@@ -595,7 +602,7 @@ func TestService_Get_ServesSourceAndVariantCachedTwoDaysAgo(t *testing.T) {
 
 	_ = resp.Content.Close()
 
-	fetches := readCounters(svc.cache).upstreamFetchCount
+	fetches := readCacheStatsCounters(t, svc.cache).upstreamFetchCount
 	if fetches != 1 {
 		t.Errorf("upstream fetches = %d, want 1", fetches)
 	}
@@ -608,16 +615,41 @@ func backdateSource(
 ) {
 	t.Helper()
 
-	key := req.Source.Key()
+	pathHash := HashPath(req.Source.Path + "?" + req.Source.Query)
-	setSourceLastAccessed(t, cache, key, when)
 
-	path := cache.srcContent.keyToPath(key)
+	meta, err := cache.srcMetadata.Load(req.Source.Host, pathHash)
+	if err != nil {
+		t.Fatalf("reading the source's metadata file: %v", err)
+	}
 
-	err := os.Chtimes(path, when, when)
+	meta.FetchedAt = when.Unix()
+
+	err = cache.srcMetadata.Store(req.Source.Host, pathHash, meta)
+	if err != nil {
+		t.Fatalf("writing the source's metadata file: %v", err)
+	}
+
+	dbTime := when.UTC().Format(sqliteTimestampFormat)
+
+	updateOneRow(t, cache, `
+		UPDATE source_metadata SET fetched_at = ?
+		WHERE source_host = ? AND source_path = ? AND source_query = ?
+	`, dbTime, req.Source.Host, req.Source.Path, req.Source.Query)
+	updateOneRow(t, cache,
+		`UPDATE source_content SET fetched_at = ? WHERE content_hash = ?`,
+		dbTime, meta.ContentHash)
+	setSourceLastAccessed(t, cache, ContentHash(meta.ContentHash), when)
+
+	for _, path := range []string{
+		cache.srcContent.hashToPath(ContentHash(meta.ContentHash)),
+		cache.srcMetadata.metaPath(req.Source.Host, pathHash),
+	} {
+		err = os.Chtimes(path, when, when)
 		if err != nil {
 			t.Fatalf("setting back the times of %s: %v", path, err)
 		}
 	}
+}
 
 // backdateVariant sets every time pixa stored for the cached variant req asks
 // for to when, as listed on
@@ -628,13 +660,57 @@ func backdateVariant(
 	t.Helper()
 
 	key := imagerequest.CacheKey(req)
+
+	content, size, contentType, err := cache.variants.LoadWithMeta(key)
+	if err != nil || contentType == "" {
+		t.Fatalf("reading the variant's .meta file: content type %q, error %v",
+			contentType, err)
+	}
+
+	_ = content.Close()
+
+	meta, err := json.Marshal(VariantMeta{
+		ContentType: contentType,
+		Size:        size,
+		CreatedAt:   when.Unix(),
+	})
+	if err != nil {
+		t.Fatalf("encoding the variant's .meta file: %v", err)
+	}
+
 	path := cache.variants.keyToPath(key)
 
+	err = os.WriteFile(path+variantMetaSuffix, meta, StorageFilePerm)
+	if err != nil {
+		t.Fatalf("writing the variant's .meta file: %v", err)
+	}
+
+	updateOneRow(t, cache,
+		`UPDATE variant_content SET created_at = ? WHERE cache_key = ?`,
+		when.UTC().Format(sqliteTimestampFormat), string(key))
 	setVariantLastAccessed(t, cache, key, when)
 
-	err := os.Chtimes(path, when, when)
+	for _, file := range []string{path, path + variantMetaSuffix} {
+		err = os.Chtimes(file, when, when)
 		if err != nil {
-		t.Fatalf("setting back the times of %s: %v", path, err)
+			t.Fatalf("setting back the times of %s: %v", file, err)
+		}
+	}
+}
+
+// updateOneRow runs the UPDATE statement query and fails the test unless it
+// changed exactly one row.
+func updateOneRow(t *testing.T, cache *Cache, query string, args ...any) {
+	t.Helper()
+
+	result, err := cache.db.ExecContext(t.Context(), query, args...)
+	if err != nil {
+		t.Fatalf("%s: %v", query, err)
+	}
+
+	rows, err := result.RowsAffected()
+	if err != nil || rows != 1 {
+		t.Fatalf("%s: rows = %d, error = %v, want 1 row", query, rows, err)
 	}
 }
 

internal/imgcache/source_content_internal_test.go

@@ -1,141 +0,0 @@
-package imgcache
-
-import (
-	"bytes"
-	"io"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"sneak.berlin/go/pixa/internal/imagerequest"
-)
-
-// TestStoreSource_StoresIdenticalBytesOfTwoURLsTwice stores the same bytes
-// for two source URLs and checks that each URL has a source_content row of
-// its own and a file of its own, named by its source key under
-// cache/sources/<ab>/<cd>/.
-func TestStoreSource_StoresIdenticalBytesOfTwoURLsTwice(t *testing.T) {
-	t.Parallel()
-
-	cache, stateDir := newEvictionTestCache(t, 1<<30)
-	content := bytes.Repeat([]byte{0x5A}, 400)
-
-	keys := map[string]imagerequest.SourceKey{
-		"/a.jpg": storeEvictionTestSource(t, cache, testHostCDN, "/a.jpg", content),
-		"/b.jpg": storeEvictionTestSource(t, cache, testHostCDN, "/b.jpg", content),
-	}
-	t.Logf("source keys: %v", keys)
-
-	if keys["/a.jpg"] == keys["/b.jpg"] {
-		t.Fatalf("both source URLs got the key %s", keys["/a.jpg"])
-	}
-
-	for sourcePath, key := range keys {
-		rows := countRows(t, cache,
-			`SELECT COUNT(*) FROM source_content WHERE source_key = ?`, string(key))
-		if rows != 1 {
-			t.Errorf("%s has %d source_content rows, want 1", sourcePath, rows)
-		}
-
-		name := string(key)
-		file := filepath.Join(stateDir, "cache", "sources", name[0:2], name[2:4], name)
-
-		stored, err := os.ReadFile(file) //nolint:gosec // path in the test's state dir
-		if err != nil || !bytes.Equal(stored, content) {
-			t.Errorf("file of %s at %s holds %d bytes (error %v), want the %d stored",
-				sourcePath, file, len(stored), err, len(content))
-		}
-	}
-
-	usage, err := cache.UsageBytes(t.Context())
-	if err != nil {
-		t.Fatalf("UsageBytes() error = %v", err)
-	}
-
-	if usage != 800 {
-		t.Errorf("UsageBytes() = %d, want 800, the 400 bytes once for each URL", usage)
-	}
-}
-
-// TestEvictSourceBlob_LeavesSourceWithIdenticalBytesServed stores the same
-// bytes for two source URLs and evicts the first. Its row and file must be
-// gone, and the second must still be found and read from the cache.
-func TestEvictSourceBlob_LeavesSourceWithIdenticalBytesServed(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-	content := bytes.Repeat([]byte{0x5B}, 400)
-
-	evicted := storeEvictionTestSource(t, cache, testHostCDN, "/evicted.jpg", content)
-	storeEvictionTestSource(t, cache, testHostCDN, "/kept.jpg", content)
-
-	err := cache.evictSourceBlob(t.Context(), evicted)
-	if err != nil {
-		t.Fatalf("evictSourceBlob() error = %v", err)
-	}
-
-	if cache.srcContent.Exists(evicted) {
-		t.Error("the evicted source's file is still on disk")
-	}
-
-	if n := countRows(t, cache,
-		`SELECT COUNT(*) FROM source_content WHERE source_key = ?`, string(evicted),
-	); n != 0 {
-		t.Errorf("the evicted source still has %d source_content rows", n)
-	}
-
-	kept, err := cache.LookupSource(t.Context(), &imagerequest.Request{
-		Source: imagerequest.Source{Host: testHostCDN, Path: "/kept.jpg"},
-	})
-	t.Logf("LookupSource() of the kept source = %q, error %v", kept, err)
-
-	if err != nil || kept == "" {
-		t.Fatalf("LookupSource() of the kept source = %q, %v; want it cached", kept, err)
-	}
-
-	reader, _, err := cache.GetSourceContent(kept)
-	if err != nil {
-		t.Fatalf("GetSourceContent() of the kept source error = %v", err)
-	}
-
-	defer func() { _ = reader.Close() }()
-
-	served, err := io.ReadAll(reader)
-	if err != nil {
-		t.Fatalf("reading the kept source: %v", err)
-	}
-
-	if !bytes.Equal(served, content) {
-		t.Errorf("the kept source reads as %d bytes, want the %d stored",
-			len(served), len(content))
-	}
-}
-
-// TestStoreSource_FailedRowWriteLeavesNoFile drops source_content, so that
-// StoreSource cannot write the source's row, and checks that the store fails
-// and leaves no file under the source's key.
-func TestStoreSource_FailedRowWriteLeavesNoFile(t *testing.T) {
-	t.Parallel()
-
-	cache, _ := newEvictionTestCache(t, 1<<30)
-
-	_, err := cache.db.ExecContext(t.Context(), `DROP TABLE source_content`)
-	if err != nil {
-		t.Fatalf("failed to drop source_content: %v", err)
-	}
-
-	req := &imagerequest.Request{
-		Source: imagerequest.Source{Host: testHostCDN, Path: testPathCat},
-	}
-	key, err := cache.StoreSource(t.Context(), req,
-		bytes.NewReader([]byte("source bytes")))
-	t.Logf("StoreSource() = %q, error = %v", key, err)
-
-	if err == nil {
-		t.Error("StoreSource() error = nil, want the failed row write")
-	}
-
-	if cache.srcContent.Exists(req.Source.Key()) {
-		t.Error("the source's file is on disk although its row was not written")
-	}
-}

internal/imgcache/stats_internal_test.go

@@ -3,18 +3,282 @@ 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"
 	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
+func setupStatsTestDB(t *testing.T) *sql.DB {
+	t.Helper()
+
+	db, err := sql.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	err = database.ApplyMigrations(context.Background(), db, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	return db
+}
+
+func TestStats_HitRateIsRatio(t *testing.T) {
+	t.Parallel()
+
+	db := setupStatsTestDB(t)
+	dir := t.TempDir()
+
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    dir,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx := context.Background()
+
+	// Set some hit/miss counts and a transform_count
+	_, err = db.ExecContext(ctx, `
+		UPDATE cache_stats
+		SET hit_count = 75, miss_count = 25, transform_count = 9999
+		WHERE id = 1
+	`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stats, err := cache.Stats(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if stats.HitCount != 75 {
+		t.Errorf("HitCount = %d, want 75", stats.HitCount)
+	}
+
+	if stats.MissCount != 25 {
+		t.Errorf("MissCount = %d, want 25", stats.MissCount)
+	}
+
+	// HitRate should be 0.75, NOT 9999 (transform_count)
+	expectedRate := 0.75
+	if math.Abs(stats.HitRate-expectedRate) > 0.001 {
+		t.Errorf("HitRate = %f, want %f (was it scanning transform_count?)",
+			stats.HitRate, expectedRate)
+	}
+}
+
+func TestStats_ZeroCounts(t *testing.T) {
+	t.Parallel()
+
+	db := setupStatsTestDB(t)
+	dir := t.TempDir()
+
+	cache, err := NewCache(db, CacheConfig{
+		StateDir:    dir,
+		NegativeTTL: 5 * time.Minute,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	stats, err := cache.Stats(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// With zero hits and misses, HitRate should be 0, not some garbage value
+	if stats.HitRate != 0.0 {
+		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(),
+		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(),
+		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(),
+		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 counter of the cache after each.
+// source cannot be used, checking every cache_stats counter after each.
 func TestService_Get_CountsStats(t *testing.T) {
 	t.Parallel()
 
@@ -41,18 +305,18 @@ func TestService_Get_CountsStats(t *testing.T) {
 		path    string
 		size    int
 		wantErr bool
-		want    counterValues
+		want    cacheStatsCounters
 	}{
 		{"miss that fetches the source", testPathPhoto, 50, false,
-			counterValues{0, 1, 1, photoBytes, 1}},
+			cacheStatsCounters{0, 1, 1, photoBytes, 1}},
 		{"hit", testPathPhoto, 50, false,
-			counterValues{1, 1, 1, photoBytes, 1}},
+			cacheStatsCounters{1, 1, 1, photoBytes, 1}},
 		{"miss that reuses the cached source", testPathPhoto, 25, false,
-			counterValues{1, 2, 1, photoBytes, 2}},
+			cacheStatsCounters{1, 2, 1, photoBytes, 2}},
 		{"miss whose source fails the magic byte check", "/images/fake.jpg", 50, true,
-			counterValues{1, 3, 2, photoBytes + fakeBytes, 2}},
+			cacheStatsCounters{1, 3, 2, photoBytes + fakeBytes, 2}},
 		{"miss whose source is not found", "/images/nonexistent.jpg", 50, true,
-			counterValues{1, 4, 2, photoBytes + fakeBytes, 2}},
+			cacheStatsCounters{1, 4, 2, photoBytes + fakeBytes, 2}},
 	}
 
 	for _, step := range steps {
@@ -76,7 +340,7 @@ func TestService_Get_CountsStats(t *testing.T) {
 			_ = resp.Content.Close()
 		}
 
-		got := readCounters(svc.cache)
+		got := readCacheStatsCounters(t, svc.cache)
 		if got != step.want {
 			t.Fatalf("after the %s: counters = %+v, want %+v", step.name, got, step.want)
 		}
@@ -114,7 +378,7 @@ func (u *fakeUpstream) Read(p []byte) (int, error) {
 	return 0, u.err
 }
 
-// TestService_Get_CountsInterruptedMisses checks every counter of the cache
+// 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) {
@@ -130,15 +394,15 @@ func TestService_Get_CountsInterruptedMisses(t *testing.T) {
 		cancel  bool  // whether the body then ends the request context
 		readErr error // what the body then returns
 		wantErr bool
-		want    counterValues
+		want    cacheStatsCounters
 	}{
 		{"request context ends during the fetch", half, true, context.Canceled, true,
-			counterValues{0, 1, 1, int64(half), 0}},
+			cacheStatsCounters{0, 1, 1, int64(half), 0}},
 		{"request context ends after the fetch", len(photo), true, io.EOF, false,
-			counterValues{0, 1, 1, int64(len(photo)), 1}},
+			cacheStatsCounters{0, 1, 1, int64(len(photo)), 1}},
 		{"upstream body over the size limit", half, false,
 			httpfetcher.ErrResponseTooLarge, true,
-			counterValues{0, 1, 1, int64(half), 0}},
+			cacheStatsCounters{0, 1, 1, int64(half), 0}},
 	}
 
 	for _, tc := range tests {
@@ -182,7 +446,7 @@ func TestService_Get_CountsInterruptedMisses(t *testing.T) {
 				_ = resp.Content.Close()
 			}
 
-			got := readCounters(svc.cache)
+			got := readCacheStatsCounters(t, svc.cache)
 			if got != tc.want {
 				t.Errorf("counters = %+v, want %+v", got, tc.want)
 			}
@@ -190,9 +454,9 @@ func TestService_Get_CountsInterruptedMisses(t *testing.T) {
 	}
 }
 
-// TestService_Get_CountsHitAfterRequestEnds checks every counter of the
+// TestService_Get_CountsHitAfterRequestEnds checks every cache_stats counter
-// cache after a hit served with a request context that has already ended:
+// after a hit served with a request context that has already ended: only
-// only the hit count moves.
+// the hit count moves.
 func TestService_Get_CountsHitAfterRequestEnds(t *testing.T) {
 	t.Parallel()
 
@@ -219,7 +483,7 @@ func TestService_Get_CountsHitAfterRequestEnds(t *testing.T) {
 
 	_ = resp.Content.Close()
 
-	want := readCounters(svc.cache)
+	want := readCacheStatsCounters(t, svc.cache)
 	want.hitCount++
 
 	ctx, cancel := context.WithCancel(t.Context())
@@ -236,7 +500,7 @@ func TestService_Get_CountsHitAfterRequestEnds(t *testing.T) {
 		t.Fatalf("CacheStatus = %v, want %v", resp.CacheStatus, CacheHit)
 	}
 
-	got := readCounters(svc.cache)
+	got := readCacheStatsCounters(t, svc.cache)
 	if got != want {
 		t.Errorf("counters = %+v, want %+v", got, want)
 	}

internal/imgcache/storage.go

@@ -1,14 +1,18 @@
 package imgcache
 
 import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
+	"time"
 
 	"sneak.berlin/go/pixa/internal/imagerequest"
-	"sneak.berlin/go/pixa/internal/magic"
 )
 
 // Storage constants.
@@ -26,8 +30,14 @@ var (
 	ErrNotFound = errors.New("content not found")
 )
 
-// ContentStorage handles source image file storage, one file per source
+// ContentHash is a SHA256 hash of file content (hex-encoded).
-// URL. Files are stored at: <basedir>/<ab>/<cd>/<source key>
+type ContentHash string
+
+// PathHash is a SHA256 hash of a URL path (hex-encoded).
+type PathHash string
+
+// ContentStorage handles content-addressable file storage.
+// Files are stored at: <basedir>/<ab>/<cd>/<abcdef...sha256>
 type ContentStorage struct {
 	baseDir string
 }
@@ -42,19 +52,38 @@ func NewContentStorage(baseDir string) (*ContentStorage, error) {
 	return &ContentStorage{baseDir: baseDir}, nil
 }
 
-// Store writes data with writeFileSynced to the path derived from key,
+// Store writes content to storage and returns its SHA256 hash.
-// replacing any file already there, and returns its size.
+// The content is read fully into memory to compute the hash before writing.
-func (s *ContentStorage) Store(
+func (s *ContentStorage) Store(r io.Reader) (ContentHash, int64, error) {
-	key imagerequest.SourceKey, data []byte,
+	// Read all content to compute hash
-) (int64, error) {
+	data, err := io.ReadAll(r)
-	path := s.keyToPath(key)
-
-	err := os.MkdirAll(filepath.Dir(path), StorageDirPerm)
 	if err != nil {
-		return 0, fmt.Errorf("failed to create directory: %w", err)
+		return "", 0, fmt.Errorf("failed to read content: %w", err)
 	}
 
-	err = writeFileSynced(path, data)
+	// Compute hash
+	h := sha256.Sum256(data)
+	hash := ContentHash(hex.EncodeToString(h[:]))
+	size := int64(len(data))
+
+	err = s.writeIfAbsent(hash, data)
+	if err != nil {
+		return "", 0, err
+	}
+
+	return hash, size, nil
+}
+
+// StoreHashed writes pre-hashed content to storage at the path derived
+// from hash, without recomputing it. Callers that already know the
+// hash before writing (e.g. because they must hold a hash-keyed lock
+// across the whole store operation) use this instead of Store. Like
+// Store, it is idempotent: a file of the content's size already at that
+// path is left untouched, and a file of another size is replaced.
+func (s *ContentStorage) StoreHashed(
+	hash ContentHash, data []byte,
+) (int64, error) {
+	err := s.writeIfAbsent(hash, data)
 	if err != nil {
 		return 0, err
 	}
@@ -62,13 +91,27 @@ func (s *ContentStorage) Store(
 	return int64(len(data)), nil
 }
 
-// LoadWithSize returns a reader and file size for the content with the given key.
+// Load returns a reader for the content with the given hash.
-func (s *ContentStorage) LoadWithSize(
+func (s *ContentStorage) Load(hash ContentHash) (io.ReadCloser, error) {
-	key imagerequest.SourceKey,
+	path := s.hashToPath(hash)
-) (io.ReadCloser, int64, error) {
-	path := s.keyToPath(key)
 
-	f, err := os.Open(path) //nolint:gosec // path derived from source key
+	f, err := os.Open(path) //nolint:gosec // path derived from content hash
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, ErrNotFound
+		}
+
+		return nil, fmt.Errorf("failed to open content: %w", err)
+	}
+
+	return f, nil
+}
+
+// LoadWithSize returns a reader and file size for the content with the given hash.
+func (s *ContentStorage) LoadWithSize(hash ContentHash) (io.ReadCloser, int64, error) {
+	path := s.hashToPath(hash)
+
+	f, err := os.Open(path) //nolint:gosec // path derived from content hash
 	if err != nil {
 		if os.IsNotExist(err) {
 			return nil, 0, ErrNotFound
@@ -87,9 +130,9 @@ func (s *ContentStorage) LoadWithSize(
 	return f, stat.Size(), nil
 }
 
-// Delete removes content with the given key.
+// Delete removes content with the given hash.
-func (s *ContentStorage) Delete(key imagerequest.SourceKey) error {
+func (s *ContentStorage) Delete(hash ContentHash) error {
-	path := s.keyToPath(key)
+	path := s.hashToPath(hash)
 
 	err := os.Remove(path)
 	if err != nil && !os.IsNotExist(err) {
@@ -99,14 +142,34 @@ func (s *ContentStorage) Delete(key imagerequest.SourceKey) error {
 	return nil
 }
 
-// Exists checks if content with the given key exists.
+// Exists checks if content with the given hash exists.
-func (s *ContentStorage) Exists(key imagerequest.SourceKey) bool {
+func (s *ContentStorage) Exists(hash ContentHash) bool {
-	path := s.keyToPath(key)
+	path := s.hashToPath(hash)
 	_, err := os.Stat(path)
 
 	return err == nil
 }
 
+// writeIfAbsent writes data with writeFileSynced to the path derived
+// from hash, unless a file of the data's size is already there.
+func (s *ContentStorage) writeIfAbsent(hash ContentHash, data []byte) error {
+	// Build path: <basedir>/<ab>/<cd>/<hash>
+	path := s.hashToPath(hash)
+
+	// A file of another size there is damaged, and is replaced
+	info, statErr := os.Stat(path)
+	if statErr == nil && info.Size() == int64(len(data)) {
+		return nil
+	}
+
+	err := os.MkdirAll(filepath.Dir(path), StorageDirPerm)
+	if err != nil {
+		return fmt.Errorf("failed to create directory: %w", err)
+	}
+
+	return writeFileSynced(path, data)
+}
+
 // writeFileSynced writes data to path through a temp file in the same
 // directory: the temp file is synced to disk, renamed to path, and the
 // directory synced after, so that neither a concurrent reader nor a
@@ -181,117 +244,305 @@ func syncDirectory(dir string) error {
 	return nil
 }
 
-// keyToPath converts a key to a file path: <basedir>/<ab>/<cd>/<key>
+// hashToPath converts a hash to a file path: <basedir>/<ab>/<cd>/<hash>
-func (s *ContentStorage) keyToPath(key imagerequest.SourceKey) string {
+func (s *ContentStorage) hashToPath(hash ContentHash) string {
-	k := string(key)
+	h := string(hash)
-	if len(k) < MinHashLength {
+	if len(h) < MinHashLength {
-		return filepath.Clean(filepath.Join(s.baseDir, k))
+		return filepath.Clean(filepath.Join(s.baseDir, h))
 	}
 
-	return filepath.Clean(filepath.Join(s.baseDir, k[0:2], k[2:4], k))
+	return filepath.Clean(filepath.Join(s.baseDir, h[0:2], h[2:4], h))
+}
+
+// MetadataStorage handles JSON metadata file storage.
+// Files are stored at: <basedir>/<hostname>/<path_hash>.json
+type MetadataStorage struct {
+	baseDir string
+}
+
+// NewMetadataStorage creates a new metadata storage at the given base directory.
+func NewMetadataStorage(baseDir string) (*MetadataStorage, error) {
+	err := os.MkdirAll(baseDir, StorageDirPerm)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create metadata directory: %w", err)
+	}
+
+	return &MetadataStorage{baseDir: baseDir}, nil
+}
+
+// SourceMetadata represents cached metadata about a source URL.
+//
+//nolint:tagliatelle // stored metadata format uses snake_case
+type SourceMetadata struct {
+	Host            string              `json:"host"`
+	Path            string              `json:"path"`
+	Query           string              `json:"query,omitempty"`
+	ContentHash     string              `json:"content_hash,omitempty"`
+	StatusCode      int                 `json:"status_code"`
+	ContentType     string              `json:"content_type,omitempty"`
+	ContentLength   int64               `json:"content_length,omitempty"`
+	ResponseHeaders map[string][]string `json:"response_headers,omitempty"`
+	FetchedAt       int64               `json:"fetched_at"`
+	FetchDurationMs int64               `json:"fetch_duration_ms,omitempty"`
+	ExpiresAt       int64               `json:"expires_at,omitempty"`
+	ETag            string              `json:"etag,omitempty"`
+	LastModified    string              `json:"last_modified,omitempty"`
+	RemoteAddr      string              `json:"remote_addr,omitempty"`
+}
+
+// Store writes metadata to storage.
+func (s *MetadataStorage) Store(
+	host string, pathHash PathHash, meta *SourceMetadata,
+) error {
+	path := s.metaPath(host, pathHash)
+
+	// Create directory structure
+	dir := filepath.Dir(path)
+
+	err := os.MkdirAll(dir, StorageDirPerm)
+	if err != nil {
+		return fmt.Errorf("failed to create directory: %w", err)
+	}
+
+	// Marshal to JSON
+	data, err := json.MarshalIndent(meta, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal metadata: %w", err)
+	}
+
+	// Write to temp file first, then rename for atomicity
+	tmpFile, err := os.CreateTemp(dir, ".tmp-*.json")
+	if err != nil {
+		return fmt.Errorf("failed to create temp file: %w", err)
+	}
+
+	tmpPath := tmpFile.Name()
+
+	_, err = tmpFile.Write(data)
+	if err != nil {
+		_ = tmpFile.Close()
+		_ = os.Remove(tmpPath)
+
+		return fmt.Errorf("failed to write metadata: %w", err)
+	}
+
+	err = tmpFile.Close()
+	if err != nil {
+		_ = os.Remove(tmpPath)
+
+		return fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	// Atomic rename
+	err = os.Rename(filepath.Clean(tmpPath), filepath.Clean(path))
+	if err != nil {
+		_ = os.Remove(tmpPath)
+
+		return fmt.Errorf("failed to rename temp file: %w", err)
+	}
+
+	return nil
+}
+
+// Load reads metadata from storage.
+func (s *MetadataStorage) Load(
+	host string, pathHash PathHash,
+) (*SourceMetadata, error) {
+	path := s.metaPath(host, pathHash)
+
+	data, err := os.ReadFile(path) //nolint:gosec // path derived from host+hash
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, ErrNotFound
+		}
+
+		return nil, fmt.Errorf("failed to read metadata: %w", err)
+	}
+
+	var meta SourceMetadata
+
+	err = json.Unmarshal(data, &meta)
+	if err != nil {
+		return nil, fmt.Errorf("failed to unmarshal metadata: %w", err)
+	}
+
+	return &meta, nil
+}
+
+// Delete removes metadata for the given host and path hash.
+func (s *MetadataStorage) Delete(host string, pathHash PathHash) error {
+	path := s.metaPath(host, pathHash)
+
+	err := os.Remove(path)
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("failed to delete metadata: %w", err)
+	}
+
+	return nil
+}
+
+// Exists checks if metadata exists for the given host and path hash.
+func (s *MetadataStorage) Exists(host string, pathHash PathHash) bool {
+	path := s.metaPath(host, pathHash)
+	_, err := os.Stat(path)
+
+	return err == nil
+}
+
+// metaPath returns the file path for metadata: <basedir>/<host>/<path_hash>.json
+func (s *MetadataStorage) metaPath(host string, pathHash PathHash) string {
+	return filepath.Clean(filepath.Join(s.baseDir, host, string(pathHash)+".json"))
+}
+
+// HashPath computes the SHA256 hash of a path string.
+func HashPath(path string) PathHash {
+	h := sha256.Sum256([]byte(path))
+
+	return PathHash(hex.EncodeToString(h[:]))
 }
 
 // VariantStorage handles key-based file storage for processed image variants.
 // Files are stored at: <basedir>/<ab>/<cd>/<cache_key>
+// Metadata is stored at: <basedir>/<ab>/<cd>/<cache_key>.meta
+// Unlike ContentStorage, the key is provided by the caller (not computed from content).
 type VariantStorage struct {
 	baseDir string
+	log     *slog.Logger
 }
 
-// errNotAnOutputFormat is returned for a variant file whose first bytes are
+// VariantMeta contains metadata about a cached variant.
-// those of a format pixa reads but never writes, such as SVG.
+//
-var errNotAnOutputFormat = errors.New("variant file is not in an output format")
+//nolint:tagliatelle // stored metadata format uses snake_case
+type VariantMeta struct {
+	ContentType string `json:"content_type"`
+	Size        int64  `json:"size"`
+	CreatedAt   int64  `json:"created_at"`
+}
 
 // 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 to storage at the given key with writeFileSynced.
+// Store writes content and metadata to storage at the given key, each
+// with writeFileSynced. The .meta file is written first, so that a crash
+// cannot leave the content in place without it.
 func (s *VariantStorage) Store(
-	key imagerequest.VariantKey, r io.Reader,
+	key imagerequest.VariantKey, r io.Reader, contentType string,
 ) (int64, error) {
 	data, err := io.ReadAll(r)
 	if err != nil {
 		return 0, fmt.Errorf("failed to read content: %w", err)
 	}
 
+	size := int64(len(data))
 	path := s.keyToPath(key)
+	metaPath := path + ".meta"
 
 	err = os.MkdirAll(filepath.Dir(path), StorageDirPerm)
 	if err != nil {
 		return 0, fmt.Errorf("failed to create directory: %w", err)
 	}
 
+	meta := VariantMeta{
+		ContentType: contentType,
+		Size:        size,
+		CreatedAt:   time.Now().UTC().Unix(),
+	}
+
+	metaData, err := json.Marshal(meta)
+	if err != nil {
+		return 0, fmt.Errorf("failed to marshal metadata: %w", err)
+	}
+
+	// Metadata write failure is non-fatal: the content is then served as
+	// application/octet-stream.
+	err = writeFileSynced(metaPath, metaData)
+	if err != nil {
+		s.log.Warn("failed to write variant metadata sidecar",
+			"path", metaPath, "error", err)
+	}
+
 	err = writeFileSynced(path, data)
 	if err != nil {
 		return 0, err
 	}
 
-	return int64(len(data)), nil
+	return size, nil
 }
 
-// LoadWithContentType opens the content at the given key and returns a
+// Load returns a reader for the content at the given key.
-// reader, the file size and the content type, which is read from the
+func (s *VariantStorage) Load(key imagerequest.VariantKey) (io.ReadCloser, error) {
-// file's first bytes. A missing file is ErrNotFound. A file whose first
-// bytes are not those of an output format, an empty one included, is
-// closed again and the reason returned.
-func (s *VariantStorage) LoadWithContentType(
-	key imagerequest.VariantKey,
-) (io.ReadCloser, int64, string, error) {
 	path := s.keyToPath(key)
 
 	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, ErrNotFound
 		}
 
-		return nil, 0, "", fmt.Errorf("failed to open content: %w", err)
+		return nil, fmt.Errorf("failed to open content: %w", err)
+	}
+
+	return f, nil
+}
+
+// LoadWithSize returns a reader and file size for the content at the
+// given key.
+func (s *VariantStorage) LoadWithSize(
+	key imagerequest.VariantKey,
+) (io.ReadCloser, int64, error) {
+	path := s.keyToPath(key)
+
+	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, 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)
 	}
 
-	contentType, err := outputContentType(f)
+	return f, stat.Size(), nil
-	if err != nil {
+}
-		_ = f.Close()
 
+// 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 imagerequest.VariantKey,
+) (io.ReadCloser, int64, string, error) {
+	f, size, err := s.LoadWithSize(key)
+	if err != nil {
 		return nil, 0, "", err
 	}
 
-	return f, stat.Size(), contentType, nil
+	var contentType string
+
+	metaPath := s.keyToPath(key) + ".meta"
+
+	metaData, err := os.ReadFile(metaPath) //nolint:gosec // path derived from cache key
+	if err == nil {
+		var meta VariantMeta
+		if json.Unmarshal(metaData, &meta) == nil && meta.ContentType != "" {
+			contentType = meta.ContentType
+		}
 	}
 
-// outputContentType reads the first bytes of content, without moving its
+	return f, size, contentType, nil
-// offset, and returns the content type of the output format they show.
-func outputContentType(content io.ReaderAt) (string, error) {
-	firstBytes := make([]byte, magic.MinMagicBytes)
-
-	_, err := content.ReadAt(firstBytes, 0)
-	if err != nil {
-		return "", fmt.Errorf("failed to read the first bytes: %w", err)
-	}
-
-	detected, err := magic.DetectFormat(firstBytes)
-	if err != nil {
-		return "", err
-	}
-
-	_, isOutputFormat := magic.MIMEToImageFormat(string(detected))
-	if !isOutputFormat {
-		return "", fmt.Errorf("%w: %s", errNotAnOutputFormat, detected)
-	}
-
-	return string(detected), nil
 }
 
 // Exists checks if content exists at the given key.
@@ -302,8 +553,8 @@ func (s *VariantStorage) Exists(key imagerequest.VariantKey) bool {
 	return err == nil
 }
 
-// Delete removes the content at the given key. A missing file is not an
+// Delete removes the content at the given key together with its .meta
-// error.
+// sidecar file. A missing file is not an error.
 func (s *VariantStorage) Delete(key imagerequest.VariantKey) error {
 	path := s.keyToPath(key)
 
@@ -312,6 +563,13 @@ func (s *VariantStorage) Delete(key imagerequest.VariantKey) error {
 		return fmt.Errorf("failed to delete content: %w", err)
 	}
 
+	metaPath := path + ".meta"
+
+	err = os.Remove(metaPath)
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("failed to delete variant metadata: %w", err)
+	}
+
 	return nil
 }
 

internal/imgcache/storage_internal_test.go

@@ -4,14 +4,16 @@ import (
 	"bytes"
 	"errors"
 	"io"
+	"log/slog"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"sneak.berlin/go/pixa/internal/imagerequest"
 )
 
-func TestContentStorage_StoreAndLoadWithSize(t *testing.T) {
+func TestContentStorage_StoreAndLoad(t *testing.T) {
 	t.Parallel()
 
 	tmpDir := t.TempDir()
@@ -22,9 +24,8 @@ func TestContentStorage_StoreAndLoadWithSize(t *testing.T) {
 	}
 
 	content := []byte("hello world")
-	key := imagerequest.Source{Host: testHostCDN, Path: testPathCat}.Key()
 
-	size, err := storage.Store(key, content)
+	hash, size, err := storage.Store(bytes.NewReader(content))
 	if err != nil {
 		t.Fatalf("Store() error = %v", err)
 	}
@@ -33,10 +34,14 @@ func TestContentStorage_StoreAndLoadWithSize(t *testing.T) {
 		t.Errorf("Store() size = %d, want %d", size, len(content))
 	}
 
-	// Verify file exists at expected path
+	if hash == "" {
-	keyStr := string(key)
+		t.Error("Store() returned empty hash")
+	}
 
-	expectedPath := filepath.Join(tmpDir, keyStr[0:2], keyStr[2:4], keyStr)
+	// Verify file exists at expected path
+	hashStr := string(hash)
+
+	expectedPath := filepath.Join(tmpDir, hashStr[0:2], hashStr[2:4], hashStr)
 
 	_, err = os.Stat(expectedPath)
 	if err != nil {
@@ -44,9 +49,9 @@ func TestContentStorage_StoreAndLoadWithSize(t *testing.T) {
 	}
 
 	// Load and verify content
-	r, _, err := storage.LoadWithSize(key)
+	r, err := storage.Load(hash)
 	if err != nil {
-		t.Fatalf("LoadWithSize() error = %v", err)
+		t.Fatalf("Load() error = %v", err)
 	}
 
 	defer func() { _ = r.Close() }()
@@ -57,11 +62,11 @@ func TestContentStorage_StoreAndLoadWithSize(t *testing.T) {
 	}
 
 	if !bytes.Equal(loaded, content) {
-		t.Errorf("LoadWithSize() content = %q, want %q", loaded, content)
+		t.Errorf("Load() content = %q, want %q", loaded, content)
 	}
 }
 
-func TestContentStorage_LoadWithSizeNotFound(t *testing.T) {
+func TestContentStorage_StoreIdempotent(t *testing.T) {
 	t.Parallel()
 
 	tmpDir := t.TempDir()
@@ -71,9 +76,36 @@ func TestContentStorage_LoadWithSizeNotFound(t *testing.T) {
 		t.Fatalf("NewContentStorage() error = %v", err)
 	}
 
-	_, _, err = storage.LoadWithSize(imagerequest.SourceKey("nonexistent"))
+	content := []byte("same content")
+
+	hash1, _, err := storage.Store(bytes.NewReader(content))
+	if err != nil {
+		t.Fatalf("Store() first error = %v", err)
+	}
+
+	hash2, _, err := storage.Store(bytes.NewReader(content))
+	if err != nil {
+		t.Fatalf("Store() second error = %v", err)
+	}
+
+	if hash1 != hash2 {
+		t.Errorf("Store() hashes differ: %s vs %s", hash1, hash2)
+	}
+}
+
+func TestContentStorage_LoadNotFound(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+
+	storage, err := NewContentStorage(tmpDir)
+	if err != nil {
+		t.Fatalf("NewContentStorage() error = %v", err)
+	}
+
+	_, err = storage.Load(ContentHash("nonexistent"))
 	if !errors.Is(err, ErrNotFound) {
-		t.Errorf("LoadWithSize() error = %v, want ErrNotFound", err)
+		t.Errorf("Load() error = %v, want ErrNotFound", err)
 	}
 }
 
@@ -88,23 +120,22 @@ func TestContentStorage_Delete(t *testing.T) {
 	}
 
 	content := []byte("to be deleted")
-	key := imagerequest.Source{Host: testHostCDN, Path: testPathCat}.Key()
 
-	_, err = storage.Store(key, content)
+	hash, _, err := storage.Store(bytes.NewReader(content))
 	if err != nil {
 		t.Fatalf("Store() error = %v", err)
 	}
 
-	if !storage.Exists(key) {
+	if !storage.Exists(hash) {
 		t.Error("Exists() = false, want true")
 	}
 
-	err = storage.Delete(key)
+	err = storage.Delete(hash)
 	if err != nil {
 		t.Fatalf("Delete() error = %v", err)
 	}
 
-	if storage.Exists(key) {
+	if storage.Exists(hash) {
 		t.Error("Exists() = true after delete, want false")
 	}
 }
@@ -120,13 +151,13 @@ func TestContentStorage_DeleteNonexistent(t *testing.T) {
 	}
 
 	// Should not error
-	err = storage.Delete(imagerequest.SourceKey("nonexistent"))
+	err = storage.Delete(ContentHash("nonexistent"))
 	if err != nil {
 		t.Errorf("Delete() error = %v, want nil", err)
 	}
 }
 
-func TestContentStorage_KeyToPath(t *testing.T) {
+func TestContentStorage_HashToPath(t *testing.T) {
 	t.Parallel()
 
 	tmpDir := t.TempDir()
@@ -138,19 +169,263 @@ func TestContentStorage_KeyToPath(t *testing.T) {
 
 	// Test by storing and verifying the resulting path structure
 	content := []byte("test content for path verification")
-	key := imagerequest.Source{Host: testHostCDN, Path: testPathCat}.Key()
 
-	_, err = storage.Store(key, content)
+	hash, _, err := storage.Store(bytes.NewReader(content))
 	if err != nil {
 		t.Fatalf("Store() error = %v", err)
 	}
 
-	keyStr := string(key)
+	hashStr := string(hash)
 
-	expectedPath := filepath.Join(tmpDir, keyStr[0:2], keyStr[2:4], keyStr)
+	expectedPath := filepath.Join(tmpDir, hashStr[0:2], hashStr[2:4], hashStr)
 
 	_, err = os.Stat(expectedPath)
 	if err != nil {
 		t.Errorf("File not at expected path %s: %v", expectedPath, err)
 	}
 }
+
+func TestMetadataStorage_StoreAndLoad(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+
+	storage, err := NewMetadataStorage(tmpDir)
+	if err != nil {
+		t.Fatalf("NewMetadataStorage() error = %v", err)
+	}
+
+	meta := &SourceMetadata{
+		Host:        testHostCDN,
+		Path:        testPathCat,
+		ContentHash: "abc123",
+		StatusCode:  200,
+		ContentType: testContentTypeJPEG,
+		FetchedAt:   1704067200,
+		ETag:        `"etag123"`,
+	}
+
+	pathHash := HashPath(testPathCat)
+
+	err = storage.Store(testHostCDN, pathHash, meta)
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	// Verify file exists at expected path
+	expectedPath := filepath.Join(tmpDir, testHostCDN, string(pathHash)+".json")
+
+	_, err = os.Stat(expectedPath)
+	if err != nil {
+		t.Errorf("File not at expected path %s: %v", expectedPath, err)
+	}
+
+	// Load and verify
+	loaded, err := storage.Load(testHostCDN, pathHash)
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+
+	if loaded.Host != meta.Host {
+		t.Errorf("Host = %q, want %q", loaded.Host, meta.Host)
+	}
+
+	if loaded.Path != meta.Path {
+		t.Errorf("Path = %q, want %q", loaded.Path, meta.Path)
+	}
+
+	if loaded.ContentHash != meta.ContentHash {
+		t.Errorf("ContentHash = %q, want %q", loaded.ContentHash, meta.ContentHash)
+	}
+
+	if loaded.StatusCode != meta.StatusCode {
+		t.Errorf("StatusCode = %d, want %d", loaded.StatusCode, meta.StatusCode)
+	}
+
+	if loaded.ETag != meta.ETag {
+		t.Errorf("ETag = %q, want %q", loaded.ETag, meta.ETag)
+	}
+}
+
+func TestMetadataStorage_LoadNotFound(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+
+	storage, err := NewMetadataStorage(tmpDir)
+	if err != nil {
+		t.Fatalf("NewMetadataStorage() error = %v", err)
+	}
+
+	_, err = storage.Load(testHostExample, PathHash("nonexistent"))
+	if !errors.Is(err, ErrNotFound) {
+		t.Errorf("Load() error = %v, want ErrNotFound", err)
+	}
+}
+
+func TestMetadataStorage_Delete(t *testing.T) {
+	t.Parallel()
+
+	tmpDir := t.TempDir()
+
+	storage, err := NewMetadataStorage(tmpDir)
+	if err != nil {
+		t.Fatalf("NewMetadataStorage() error = %v", err)
+	}
+
+	meta := &SourceMetadata{
+		Host:       testHostExample,
+		Path:       "/test.jpg",
+		StatusCode: 200,
+	}
+
+	pathHash := HashPath("/test.jpg")
+
+	err = storage.Store(testHostExample, pathHash, meta)
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	if !storage.Exists(testHostExample, pathHash) {
+		t.Error("Exists() = false, want true")
+	}
+
+	err = storage.Delete(testHostExample, pathHash)
+	if err != nil {
+		t.Fatalf("Delete() error = %v", err)
+	}
+
+	if storage.Exists(testHostExample, pathHash) {
+		t.Error("Exists() = true after delete, want false")
+	}
+}
+
+func TestHashPath(t *testing.T) {
+	t.Parallel()
+
+	// Same input should produce same hash
+	hash1 := HashPath(testPathCat)
+	hash2 := HashPath(testPathCat)
+
+	if hash1 != hash2 {
+		t.Errorf("HashPath() not deterministic: %s vs %s", hash1, hash2)
+	}
+
+	// Different input should produce different hash
+	hash3 := HashPath("/photos/dog.jpg")
+
+	if hash1 == hash3 {
+		t.Error("HashPath() produced same hash for different inputs")
+	}
+
+	// Hash should be 64 hex chars (256 bits)
+	if len(string(hash1)) != 64 {
+		t.Errorf("HashPath() length = %d, want 64", len(string(hash1)))
+	}
+}
+
+// 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 := imagerequest.CacheKey(&imagerequest.Request{
+		Source: imagerequest.Source{Host: testHostCDN, Path: 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, imagerequest.VariantKey) {
+	t.Helper()
+
+	storage, err := NewVariantStorage(t.TempDir(), slog.New(slog.DiscardHandler))
+	if err != nil {
+		t.Fatalf("NewVariantStorage() error = %v", err)
+	}
+
+	key := imagerequest.CacheKey(&imagerequest.Request{
+		Source: imagerequest.Source{Host: testHostCDN, Path: 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

@@ -14,7 +14,6 @@ import (
 	"testing/fstest"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 )
@@ -25,6 +24,8 @@ const (
 	testHostExample       = "example.com"
 	testPathCat           = "/photos/cat.jpg"
 	testContentTypeJPEG   = "image/jpeg"
+	testContentTypeWebP   = "image/webp"
+	testHeaderContentType = "Content-Type"
 )
 
 // TestFixtures contains paths to test files in the mock filesystem.
@@ -185,7 +186,7 @@ func SetupTestService(
 	cache, err := NewCache(db, CacheConfig{
 		StateDir:    tmpDir,
 		NegativeTTL: 5 * time.Minute,
-	}, prometheus.NewRegistry())
+	})
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}

internal/magic/jpegxl_internal_test.go

@@ -37,13 +37,22 @@ func TestDetectFormatJPEGXL(t *testing.T) {
 	}
 }
 
-// TestJPEGXLMIMEType verifies that image/jxl maps to the format jxl.
+// TestJPEGXLMIMEType verifies that image/jxl is a supported input type and
+// maps to and from the format jxl.
 func TestJPEGXLMIMEType(t *testing.T) {
 	t.Parallel()
 
+	if !IsSupportedMIMEType(testMIMEJXL) {
+		t.Errorf("IsSupportedMIMEType(%q) = false", testMIMEJXL)
+	}
+
 	format, ok := MIMEToImageFormat(testMIMEJXL)
 	if format != FormatJXL || !ok {
 		t.Errorf("MIMEToImageFormat(%q) = %q, %v, want %q, true",
 			testMIMEJXL, format, ok, FormatJXL)
 	}
+
+	if got := ImageFormatToMIME(FormatJXL); got != testMIMEJXL {
+		t.Errorf("ImageFormatToMIME(%q) = %q, want %q", FormatJXL, got, testMIMEJXL)
+	}
 }

internal/magic/magic.go

@@ -5,6 +5,7 @@ package magic
 import (
 	"bytes"
 	"errors"
+	"io"
 	"strings"
 )
 
@@ -35,6 +36,7 @@ type ImageFormat string
 
 // Supported image output formats.
 const (
+	FormatOriginal ImageFormat = "orig"
 	FormatJPEG     ImageFormat = "jpeg"
 	FormatPNG      ImageFormat = "png"
 	FormatWebP     ImageFormat = "webp"
@@ -46,6 +48,10 @@ const (
 // MinMagicBytes is the minimum number of bytes needed to detect format.
 const MinMagicBytes = 12
 
+// mimeOctetStream is the fallback MIME type for formats without a
+// specific MIME type.
+const mimeOctetStream = "application/octet-stream"
+
 // Magic byte signatures for supported formats.
 // These are effectively constants but Go doesn't support const slices.
 //
@@ -184,6 +190,42 @@ func normalizeMIMEType(mimeType string) string {
 	return strings.TrimSpace(strings.ToLower(mimeType))
 }
 
+// IsSupportedMIMEType checks if a MIME type is supported for input.
+func IsSupportedMIMEType(mimeType string) bool {
+	normalized := normalizeMIMEType(mimeType)
+	switch MIMEType(normalized) {
+	case MIMETypeJPEG, MIMETypePNG, MIMETypeWebP, MIMETypeGIF, MIMETypeAVIF,
+		MIMETypeJXL, MIMETypeSVG:
+		return true
+	default:
+		return false
+	}
+}
+
+// PeekAndValidate reads the minimum bytes needed for format detection,
+// validates against the declared type, and returns a reader that includes
+// those bytes for subsequent reading.
+func PeekAndValidate(r io.Reader, declaredType string) (io.Reader, error) {
+	// Read minimum bytes for detection
+	buf := make([]byte, MinMagicBytes)
+
+	n, err := io.ReadFull(r, buf)
+	if err != nil && !errors.Is(err, io.ErrUnexpectedEOF) {
+		return nil, err
+	}
+
+	buf = buf[:n]
+
+	// Validate magic bytes
+	err = ValidateMagicBytes(buf, declaredType)
+	if err != nil {
+		return nil, err
+	}
+
+	// Return a reader that includes the peeked bytes
+	return io.MultiReader(bytes.NewReader(buf), r), nil
+}
+
 // MIMEToImageFormat converts a MIME type to an ImageFormat.
 func MIMEToImageFormat(mimeType string) (ImageFormat, bool) {
 	normalized := normalizeMIMEType(mimeType)
@@ -207,3 +249,26 @@ func MIMEToImageFormat(mimeType string) (ImageFormat, bool) {
 		return "", false
 	}
 }
+
+// ImageFormatToMIME converts an ImageFormat to a MIME type string.
+func ImageFormatToMIME(format ImageFormat) string {
+	switch format {
+	case FormatJPEG:
+		return string(MIMETypeJPEG)
+	case FormatPNG:
+		return string(MIMETypePNG)
+	case FormatWebP:
+		return string(MIMETypeWebP)
+	case FormatGIF:
+		return string(MIMETypeGIF)
+	case FormatAVIF:
+		return string(MIMETypeAVIF)
+	case FormatJXL:
+		return string(MIMETypeJXL)
+	case FormatOriginal:
+		// Original format passes content through unchanged.
+		return mimeOctetStream
+	default:
+		return mimeOctetStream
+	}
+}

internal/magic/magic_internal_test.go

@@ -3,6 +3,9 @@ package magic
 import (
 	"bytes"
 	"errors"
+	"io"
+	"slices"
+	"strings"
 	"testing"
 )
 
@@ -152,6 +155,119 @@ func TestValidateMagicBytes(t *testing.T) {
 	}
 }
 
+func TestIsSupportedMIMEType(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		mimeType string
+		want     bool
+	}{
+		{testMIMEJPEG, true},
+		{testMIMEPNG, true},
+		{testMIMEWebP, true},
+		{testMIMEGIF, true},
+		{testMIMEAVIF, true},
+		{"image/svg+xml", true},
+		{"IMAGE/JPEG", true},
+		{testMIMEJPEGParams, true},
+		{"image/tiff", false},
+		{"image/bmp", false},
+		{mimeOctetStream, false},
+		{"text/plain", false},
+		{"", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.mimeType, func(t *testing.T) {
+			t.Parallel()
+
+			if got := IsSupportedMIMEType(tt.mimeType); got != tt.want {
+				t.Errorf("IsSupportedMIMEType(%q) = %v, want %v", tt.mimeType, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestPeekAndValidate(t *testing.T) {
+	t.Parallel()
+
+	jpegMagic := []byte{
+		0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01,
+	}
+	pngMagic := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D,
+	}
+	jpegData := slices.Concat(jpegMagic, []byte("rest of jpeg data"))
+	pngData := slices.Concat(pngMagic, []byte("rest of png data"))
+
+	tests := []struct {
+		name         string
+		data         []byte
+		declaredType string
+		wantErr      bool
+		wantData     []byte
+	}{
+		{
+			name:         "valid JPEG",
+			data:         jpegData,
+			declaredType: testMIMEJPEG,
+			wantErr:      false,
+			wantData:     jpegData,
+		},
+		{
+			name:         "valid PNG",
+			data:         pngData,
+			declaredType: testMIMEPNG,
+			wantErr:      false,
+			wantData:     pngData,
+		},
+		{
+			name:         "mismatched type",
+			data:         jpegData,
+			declaredType: testMIMEPNG,
+			wantErr:      true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			r := bytes.NewReader(tt.data)
+
+			result, err := PeekAndValidate(r, tt.declaredType)
+			if tt.wantErr {
+				if err == nil {
+					t.Error("PeekAndValidate() expected error, got nil")
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Errorf("PeekAndValidate() unexpected error = %v", err)
+
+				return
+			}
+
+			// Read all data from result reader
+			got, err := io.ReadAll(result)
+			if err != nil {
+				t.Errorf("Failed to read result: %v", err)
+
+				return
+			}
+
+			if !bytes.Equal(got, tt.wantData) {
+				t.Errorf(
+					"PeekAndValidate() data mismatch: got %d bytes, want %d bytes",
+					len(got), len(tt.wantData),
+				)
+			}
+		})
+	}
+}
+
 func TestMIMEToImageFormat(t *testing.T) {
 	t.Parallel()
 
@@ -187,6 +303,35 @@ func TestMIMEToImageFormat(t *testing.T) {
 	}
 }
 
+func TestImageFormatToMIME(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		format   ImageFormat
+		wantMIME string
+	}{
+		{FormatJPEG, testMIMEJPEG},
+		{FormatPNG, testMIMEPNG},
+		{FormatWebP, testMIMEWebP},
+		{FormatGIF, testMIMEGIF},
+		{FormatAVIF, testMIMEAVIF},
+		{FormatOriginal, mimeOctetStream},
+		{"unknown", mimeOctetStream},
+	}
+
+	for _, tt := range tests {
+		t.Run(string(tt.format), func(t *testing.T) {
+			t.Parallel()
+
+			got := ImageFormatToMIME(tt.format)
+
+			if got != tt.wantMIME {
+				t.Errorf("ImageFormatToMIME(%q) = %v, want %v", tt.format, got, tt.wantMIME)
+			}
+		})
+	}
+}
+
 func TestNormalizeMIMEType(t *testing.T) {
 	t.Parallel()
 
@@ -348,3 +493,34 @@ func TestDetectFormatFtypNotAVIF(t *testing.T) {
 		t.Errorf("DetectFormat(MP4) error = %v, want %v", err, ErrUnknownFormat)
 	}
 }
+
+func TestPeekAndValidatePreservesReader(t *testing.T) {
+	t.Parallel()
+
+	// Ensure that after PeekAndValidate, we can read the complete
+	// original content
+	originalContent := append(
+		[]byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D},
+		[]byte(strings.Repeat("PNG IDAT chunk data here ", 100))...,
+	)
+
+	r := bytes.NewReader(originalContent)
+
+	validated, err := PeekAndValidate(r, testMIMEPNG)
+	if err != nil {
+		t.Fatalf("PeekAndValidate() error = %v", err)
+	}
+
+	// Read everything from the validated reader
+	got, err := io.ReadAll(validated)
+	if err != nil {
+		t.Fatalf("io.ReadAll() error = %v", err)
+	}
+
+	if !bytes.Equal(got, originalContent) {
+		t.Errorf(
+			"Content mismatch: got %d bytes, want %d bytes",
+			len(got), len(originalContent),
+		)
+	}
+}

internal/server/image_proxy_internal_test.go

@@ -3,7 +3,9 @@ package server
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
 	"database/sql"
+	"encoding/hex"
 	"image"
 	"image/color"
 	"image/jpeg"
@@ -19,7 +21,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx"
 	"go.uber.org/fx/fxtest"
 
@@ -29,7 +30,6 @@ import (
 	"sneak.berlin/go/pixa/internal/handlers"
 	"sneak.berlin/go/pixa/internal/healthcheck"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
-	"sneak.berlin/go/pixa/internal/imagerequest"
 	"sneak.berlin/go/pixa/internal/logger"
 	"sneak.berlin/go/pixa/internal/middleware"
 )
@@ -114,7 +114,7 @@ func TestImageProxyFlow(t *testing.T) {
 			}
 
 			checkSourceCached(t, db, stateDir, source)
-			checkVariantCached(t, db, stateDir, first.Body.Bytes())
+			checkVariantCached(t, db, stateDir, first.Body.Bytes(), tt.contentType)
 		})
 	}
 }
@@ -171,7 +171,6 @@ func startImageProxy(
 			handlers.New,
 			middleware.New,
 			func() httpfetcher.Fetcher { return fetcher },
-			func() prometheus.Registerer { return prometheus.NewRegistry() },
 		),
 		fx.Populate(&h, &mw, &db),
 	)
@@ -225,7 +224,6 @@ func startImageProxyWithBlockedNetworks(
 			healthcheck.New,
 			handlers.New,
 			middleware.New,
-			func() prometheus.Registerer { return prometheus.NewRegistry() },
 		),
 		fx.Populate(&h, &mw),
 	)
@@ -256,42 +254,63 @@ func getImage(t *testing.T, s *Server, target string) *httptest.ResponseRecorder
 	return rec
 }
 
-// checkSourceCached checks that source is stored in cache/sources under the
+// checkSourceCached checks that source is stored under its SHA-256 in
-// source key of upstreamHost and /photo.png, and recorded under that key in
+// cache/sources, recorded in source_content, and that the source URL's row in
-// source_content.
+// source_metadata points at it.
 func checkSourceCached(t *testing.T, db *sql.DB, stateDir string, source []byte) {
 	t.Helper()
 
-	key := string(imagerequest.Source{Host: upstreamHost, Path: "/photo.png"}.Key())
+	sum := sha256.Sum256(source)
+	hash := hex.EncodeToString(sum[:])
 
-	checkFile(t, filepath.Join(stateDir, "cache", "sources", key[0:2], key[2:4], key),
+	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 source_key = ?", key,
+		"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, and stored under its cache key in cache/variants.
+// variant_content with contentType, and stored under its cache key in
-func checkVariantCached(t *testing.T, db *sql.DB, stateDir string, served []byte) {
+// cache/variants.
+func checkVariantCached(
+	t *testing.T, db *sql.DB, stateDir string, served []byte, contentType string,
+) {
 	t.Helper()
 
-	var cacheKey string
+	var cacheKey, storedType string
 
 	err := db.QueryRowContext(t.Context(),
-		"SELECT cache_key FROM variant_content",
+		"SELECT cache_key, content_type FROM variant_content",
-	).Scan(&cacheKey)
+	).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)
 }

internal/server/login_rate_limit_internal_test.go

@@ -12,7 +12,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx/fxtest"
 
 	"sneak.berlin/go/pixa/internal/config"
@@ -82,7 +81,6 @@ func newTestServer(t *testing.T) *Server {
 
 	h, err := handlers.New(lc, handlers.Params{
 		Logger: log, Healthcheck: hc, Database: db, Config: cfg,
-		MetricsRegistry: prometheus.NewRegistry(),
 	})
 	if err != nil {
 		t.Fatalf("handlers.New() error = %v", err)

internal/server/logout_internal_test.go

@@ -9,7 +9,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/prometheus/client_golang/prometheus"
 	"go.uber.org/fx"
 	"go.uber.org/fx/fxtest"
 
@@ -47,7 +46,6 @@ func startPixa(t *testing.T, cfg *config.Config) *Server {
 			healthcheck.New,
 			handlers.New,
 			middleware.New,
-			func() prometheus.Registerer { return prometheus.NewRegistry() },
 		),
 		fx.Populate(&h, &mw),
 	)

internal/server/source_url_internal_test.go

@@ -513,8 +513,8 @@ func TestImageRoutesFetchIPv6SourceHostWithOrWithoutPort(t *testing.T) {
 func signedImageURL(t *testing.T, sourceHost string) string {
 	t.Helper()
 
-	expires := time.Now().Add(time.Hour)
+	path, sig, exp := signature.New(testSigningKey).GenerateSignedURL(
-	sig := signature.New(testSigningKey).Sign(&imagerequest.Request{
+		&imagerequest.Request{
 			Source: imagerequest.Source{
 				Host: sourceHost,
 				Path: ipv6SourcePath,
@@ -524,16 +524,9 @@ func signedImageURL(t *testing.T, sourceHost string) string {
 				Quality: 85,
 				FitMode: imagerequest.FitCover,
 			},
-		Expires: expires,
+		}, time.Hour)
-	})
 
-	// Go's percent-encoding of a URL path writes the brackets of the IPv6
+	return path + "?sig=" + sig + "&exp=" + strconv.FormatInt(exp, 10)
-	// host as %5B and %5D.
-	path := (&url.URL{
-		Path: "/v1/image/" + sourceHost + ipv6SourcePath + "/orig.png",
-	}).EscapedPath()
-
-	return path + "?sig=" + sig + "&exp=" + strconv.FormatInt(expires.Unix(), 10)
 }
 
 // encryptedImageURL returns the encrypted URL of ipv6SourcePath on sourceHost

internal/signature/golden_test.go

@@ -22,6 +22,11 @@ type goldenVector struct {
 	// padded) HMAC-SHA256 signature for the request with Expires
 	// set to goldenExpiresUnix.
 	wantSignature string
+	// wantSignedPath is the exact path returned by
+	// GenerateSignedURL for the request. The signature and
+	// expiration are returned separately by GenerateSignedURL and
+	// are not embedded in the path.
+	wantSignedPath string
 }
 
 // goldenVectors returns the known-answer vectors. The expected values
@@ -46,6 +51,7 @@ func goldenVectors() []goldenVector {
 			// Signed data:
 			// "cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200:85:cover"
 			wantSignature:  "kdqeGoW2SX7qnaYtoB970wEnLydn0UnIgQYQLfAnjXQ=",
+			wantSignedPath: testSignedPath,
 		},
 		{
 			name: "resized with query string",
@@ -65,6 +71,8 @@ func goldenVectors() []goldenVector {
 			// Signed data:
 			// "cdn.example.com:/photos/cat.jpg:token=abc&v=2:800:600:webp:1704067200:85:cover"
 			wantSignature: "pKgVBOTd_Q_EikI7MNQLC9Q8Hurdxzyv3EIYvVhqc2I=",
+			wantSignedPath: "/v1/image/cdn.example.com/photos/cat.jpg" +
+				"%3Ftoken=abc&v=2/800x600.webp",
 		},
 		{
 			name: "original size without query",
@@ -84,6 +92,7 @@ func goldenVectors() []goldenVector {
 			// Signed data:
 			// "cdn.example.com:/photos/cat.jpg::0:0:png:1704067200:85:cover"
 			wantSignature:  "6_rZ0yyVbGZRs8kG7n7HLgLi5Jt8vjiWQljIEL1jbIs=",
+			wantSignedPath: "/v1/image/cdn.example.com/photos/cat.jpg/orig.png",
 		},
 		{
 			name: "non-default quality and fit",
@@ -103,17 +112,22 @@ func goldenVectors() []goldenVector {
 			// Signed data:
 			// "cdn.example.com:/photos/cat.jpg::800:600:webp:1704067200:40:contain"
 			wantSignature: "pGaXpPUbI3A7nMx-4T9bfq9bYWBNL0kY4bxlcv3g1F8=",
+			// The path is the same as for the default quality and fit:
+			// q=40&fit=contain go in the query string next to sig and
+			// exp (imgcache.Service.GenerateSignedURL adds all four).
+			wantSignedPath: testSignedPath,
 		},
 	}
 }
 
-// TestSigner_GoldenVectors pins the exact HMAC-SHA256 signature output for
+// TestSigner_GoldenVectors pins the exact HMAC-SHA256 signature output and
-// fully-specified requests with a hardcoded signing key.
+// the exact generated signed URL path for fully-specified requests with a
+// hardcoded signing key.
 //
 // If any of these assertions fail, the signed byte format
-// ("host:path:query:width:height:format:expiration:quality:fit") or the
+// ("host:path:query:width:height:format:expiration:quality:fit"), the
-// base64url encoding has changed. Update these constants only when that
+// base64url encoding, or the signed URL layout has changed. Update these
-// change is intended.
+// constants only when that change is intended.
 func TestSigner_GoldenVectors(t *testing.T) {
 	t.Parallel()
 
@@ -131,6 +145,14 @@ func TestSigner_GoldenVectors(t *testing.T) {
 				t.Errorf("Sign() = %q, want %q (signed byte format changed?)",
 					gotSignature, tt.wantSignature)
 			}
+
+			urlReq := tt.req
+
+			gotPath, _, _ := signer.GenerateSignedURL(&urlReq, time.Hour)
+			if gotPath != tt.wantSignedPath {
+				t.Errorf("GenerateSignedURL() path = %q, want %q (signed URL layout changed?)",
+					gotPath, tt.wantSignedPath)
+			}
 		})
 	}
 }

internal/signature/signature.go

@@ -8,6 +8,8 @@ import (
 	"encoding/base64"
 	"errors"
 	"fmt"
+	"net/url"
+	"strconv"
 	"strings"
 	"time"
 
@@ -77,6 +79,44 @@ func (s *Signer) Verify(req *imagerequest.Request) error {
 	return nil
 }
 
+// GenerateSignedURL creates a complete URL with signature and expiration.
+// Returns the path portion that should be appended to the base URL.
+func (s *Signer) GenerateSignedURL(
+	req *imagerequest.Request, ttl time.Duration,
+) (string, string, int64) {
+	// Set expiration
+	req.Expires = time.Now().Add(ttl)
+	exp := req.Expires.Unix()
+
+	// Generate signature
+	sig := s.Sign(req)
+	req.Signature = sig
+
+	// Build the size component
+	var sizeStr string
+	if req.Transform.Size.Width == 0 && req.Transform.Size.Height == 0 {
+		sizeStr = "orig"
+	} else {
+		sizeStr = fmt.Sprintf("%dx%d",
+			req.Transform.Size.Width, req.Transform.Size.Height)
+	}
+
+	// Build the path. A source query follows the source path after a "?".
+	// The image route reads the path decoded once, so the whole path is
+	// written in Go's own percent-encoding of a URL path, which writes "?"
+	// as %3F and "%" as %25, and leaves "/", ";", ",", "=" and "&" as they
+	// are.
+	sourcePathAndQuery := req.Source.Path
+	if req.Source.Query != "" {
+		sourcePathAndQuery += "?" + req.Source.Query
+	}
+
+	unescapedPath := fmt.Sprintf("/v1/image/%s%s/%s.%s",
+		req.Source.Host, sourcePathAndQuery, sizeStr, req.Transform.Format)
+
+	return (&url.URL{Path: unescapedPath}).EscapedPath(), sig, exp
+}
+
 // buildSignatureData creates the string to be signed.
 // Format: "host:path:query:width:height:format:expiration:quality:fit"
 // The path and query go through escapePercentAndColon, so that a ":" in
@@ -106,3 +146,17 @@ func escapePercentAndColon(s string) string {
 
 	return strings.ReplaceAll(s, ":", "%3A")
 }
+
+// ParseParams extracts signature and expiration from query parameters.
+func ParseParams(sig, expStr string) (string, time.Time, error) {
+	if expStr == "" {
+		return sig, time.Time{}, nil
+	}
+
+	expUnix, err := strconv.ParseInt(expStr, 10, 64)
+	if err != nil {
+		return "", time.Time{}, fmt.Errorf("invalid expiration: %w", err)
+	}
+
+	return sig, time.Unix(expUnix, 0), nil
+}

internal/signature/signature_test.go

@@ -2,6 +2,7 @@ package signature_test
 
 import (
 	"errors"
+	"strings"
 	"testing"
 	"time"
 
@@ -17,6 +18,8 @@ const (
 	testFormatPNG  = "png"
 	testFitCover   = "cover"
 	testFitContain = "contain"
+	testSignedPath = "/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp"
+	testSig        = "abc123"
 )
 
 func TestSigner_Sign(t *testing.T) {
@@ -375,10 +378,140 @@ func TestSigner_DifferentKeys(t *testing.T) {
 	}
 }
 
-// TestSign_ReadmeQueryExample checks the signature, with the README's key, of
+func TestGenerateSignedURL(t *testing.T) {
-// the README's example of a source URL with a query, the image at
+	t.Parallel()
-// https://cdn.example.com/img?url=https://origin.example.com/my%20cat.jpg.
+
-func TestSign_ReadmeQueryExample(t *testing.T) {
+	signer := signature.New("test-secret-key")
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host:  testHost,
+			Path:  testPath,
+			Query: "",
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 800, Height: 600},
+			Format: testFormatWebP,
+		},
+	}
+
+	ttl := 1 * time.Hour
+	path, sig, exp := signer.GenerateSignedURL(req, ttl)
+
+	// Path should be correct format
+	if path != testSignedPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, testSignedPath)
+	}
+
+	// Signature should be non-empty
+	if sig == "" {
+		t.Error("GenerateSignedURL() produced empty signature")
+	}
+
+	// Expiration should be approximately now + TTL
+	expTime := time.Unix(exp, 0)
+
+	expectedExp := time.Now().Add(ttl)
+	if expTime.Sub(expectedExp) > time.Second {
+		t.Errorf("GenerateSignedURL() exp time off by too much")
+	}
+
+	// Request should have been updated with signature and expiration
+	if req.Signature != sig {
+		t.Errorf("GenerateSignedURL() didn't update request signature")
+	}
+}
+
+func TestGenerateSignedURL_OrigSize(t *testing.T) {
+	t.Parallel()
+
+	signer := signature.New("test-secret-key")
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHost,
+			Path: testPath,
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 0, Height: 0}, // Original size
+			Format: testFormatPNG,
+		},
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	expectedPath := "/v1/image/cdn.example.com/photos/cat.jpg/orig.png"
+	if path != expectedPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, expectedPath)
+	}
+}
+
+func TestGenerateSignedURL_WithQueryString(t *testing.T) {
+	t.Parallel()
+
+	signer := signature.New("test-secret-key-for-testing!")
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host:  testHost,
+			Path:  testPath,
+			Query: "token=abc&v=2",
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 800, Height: 600},
+			Format: testFormatWebP,
+		},
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	// The path must NOT contain a bare "?" that would be interpreted as
+	// a query string delimiter. The size segment must appear as the last
+	// path component.
+	if strings.Contains(path, "?token=abc") {
+		t.Errorf("GenerateSignedURL() produced bare query string in path: %q", path)
+	}
+
+	// The size segment must be present in the path
+	if !strings.Contains(path, "/800x600.webp") {
+		t.Errorf("GenerateSignedURL() missing size segment in path: %q", path)
+	}
+
+	// Path should end with the size.format, not with query params
+	if !strings.HasSuffix(path, "/800x600.webp") {
+		t.Errorf("GenerateSignedURL() path should end with size.format: %q", path)
+	}
+}
+
+func TestGenerateSignedURL_WithoutQueryString(t *testing.T) {
+	t.Parallel()
+
+	signer := signature.New("test-secret-key-for-testing!")
+
+	req := &imagerequest.Request{
+		Source: imagerequest.Source{
+			Host: testHost,
+			Path: testPath,
+		},
+		Transform: imagerequest.Transform{
+			Size:   imagerequest.Size{Width: 800, Height: 600},
+			Format: testFormatWebP,
+		},
+	}
+
+	path, _, _ := signer.GenerateSignedURL(req, time.Hour)
+
+	if path != testSignedPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", path, testSignedPath)
+	}
+}
+
+// TestGenerateSignedURL_ReadmeQueryExample checks the README's example of a
+// source URL with a query, the image at
+// https://cdn.example.com/img?url=https://origin.example.com/my%20cat.jpg: its
+// signature with the README's key, and the path GenerateSignedURL writes for
+// it, with the "?" written as %3F and the "%" as %25.
+func TestGenerateSignedURL_ReadmeQueryExample(t *testing.T) {
 	t.Parallel()
 
 	signer := signature.New("example-signing-key-for-documentation")
@@ -404,4 +537,76 @@ func TestSign_ReadmeQueryExample(t *testing.T) {
 	if gotSig != wantSig {
 		t.Errorf("Sign() = %q, want %q", gotSig, wantSig)
 	}
+
+	const wantPath = "/v1/image/cdn.example.com" +
+		"/img%3Furl=https://origin.example.com/my%2520cat.jpg/800x600.webp"
+
+	gotPath, _, _ := signer.GenerateSignedURL(&req, time.Hour)
+	if gotPath != wantPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", gotPath, wantPath)
+	}
+}
+
+func TestParseParams(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		sig       string
+		expStr    string
+		wantSig   string
+		wantErr   bool
+		checkTime bool
+	}{
+		{
+			name:    "valid params",
+			sig:     testSig,
+			expStr:  "1704067200",
+			wantSig: testSig,
+			wantErr: false,
+		},
+		{
+			name:    "empty expiration",
+			sig:     testSig,
+			expStr:  "",
+			wantSig: testSig,
+			wantErr: false,
+		},
+		{
+			name:    "invalid expiration",
+			sig:     testSig,
+			expStr:  "not-a-number",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			sig, exp, err := signature.ParseParams(tt.sig, tt.expStr)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Error("ParseParams() expected error, got nil")
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Errorf("ParseParams() unexpected error = %v", err)
+
+				return
+			}
+
+			if sig != tt.wantSig {
+				t.Errorf("sig = %q, want %q", sig, tt.wantSig)
+			}
+
+			if tt.expStr != "" && exp.IsZero() {
+				t.Error("exp should not be zero when expStr is provided")
+			}
+		})
+	}
 }

script/bench

@@ -1,19 +0,0 @@
-#!/bin/sh
-# script/bench: run the Go benchmarks of internal/handlers, which serve
-# cache hits in parallel through the image handler and report the hits
-# served per second. A benchmark, not a check: script/check does not run
-# it. It runs Go on the host, as script/loadtest does, and compiles pixa
-# there with CGO, so it needs the C compiler and libraries that
-# `script/bootstrap --cgo` installs. -run '^$' runs no test, only the
-# benchmarks.
-set -eu
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
-ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
-
-main() {
-    cd "$ROOT"
-    CGO_ENABLED=1 go test -run '^$' -bench . ./internal/handlers
-}
-
-main "$@"