Keep variant content types in memory for cache hits (closes #70)

Cache.metaCache was declared and never used, so every hit read and
parsed the variant's .meta file. It is now an LRU of up to 10,000
content types (hashicorp/golang-lru/v2), filled by StoreVariant and by
GetVariant after it reads a .meta file. For a variant it holds, Lookup
skips the disk check and GetVariant skips the .meta read; the variant
file is still opened and its size taken from it. Eviction removes the
entry before deleting the files, and GetVariant removes it when the
file will not open, so a missing variant is never served. The cap is a
constant, not a setting. README.md describes it.

Model: opus-5-5

README.md

@@ -86,7 +86,10 @@ prevent abuse, and allowlisted source hosts for open access.
 
 Multiple source paths may reference the same content blob; the
 database tracks references rather than using filesystem refcounting.
-In-process caching of request-to-output mappings targets 1-5k r/s.
+Toward a target of 1-5k r/s, pixa keeps in memory the content types of
+the 10,000 transformed images most recently cached or served, so a
+cache hit on one of them reads only the image file from disk and not
+the metadata file stored beside it.
 
 ### Routes
 
@@ -239,7 +242,7 @@ variables set by the file's `env:` section are checked the same way.
 | `PIXA_METRICS_PASSWORD`              | `metrics.password`              | Password for `/metrics`; set together with the username                      |
 | `PIXA_SENTRY_DSN`                    | `sentry_dsn`                    | Sentry DSN for error reporting; empty disables it                            |
 | `PIXA_DEBUG`                         | `debug`                         | Debug logging and plain-HTTP local development; default `false`              |
-| `PIXA_MAINTENANCE_MODE`              | `maintenance_mode`              | Answer image requests with 503; the health check stays 200; default `false`  |
+| `PIXA_MAINTENANCE_MODE`              | `maintenance_mode`              | Maintenance flag reported by the health check; default `false`               |
 
 Key settings in more detail:
 
@@ -276,13 +279,6 @@ Key settings in more detail:
 - `cache_max_bytes` — disk cache size limit in bytes; `0` disables the
   disk cache entirely; omitted defaults to 75% of the free space on
   the filesystem containing `<state_dir>/cache/` (minimum 500 MiB)
-- `maintenance_mode` — while `true`, the image routes (`/v1/image/` and
-  `/v1/e/`) answer every request with 503, a `Retry-After` header and a JSON
-  error body. The health check (`/.well-known/healthcheck.json`) still answers
-  200 and reports `"maintenance_mode": true`. It stays 200 because the image's
-  Docker `HEALTHCHECK` requests it: a 503 there would make the container
-  unhealthy, and upaas marks a deploy failed when its container is unhealthy.
-  The login and URL generator pages and `/metrics` keep working
 
 See `config.example.yml` for all options with defaults.
 

TODO.md

@@ -30,14 +30,22 @@ exhaustion
 
 # Completed Steps
 
-- 2026-09-29 maintenance mode refuses image requests (closes #71): while
-  `maintenance_mode` is on, `/v1/image/` and `/v1/e/` answer 503 with a
-  `Retry-After` header and the JSON error body, from one middleware in
-  `internal/server/routes.go`; the health check stays 200 and reports
-  `maintenance_mode`, as the image's Docker `HEALTHCHECK` requests it and upaas
-  marks a deploy failed when its container is unhealthy; the login and URL
-  generator pages and `/metrics` keep working; documented in `README.md` and
-  `config.example.yml`.
+- 2026-09-29 variant content types kept in memory (closes #70):
+  `Cache.metaCache` holds the content types of up to 10,000 variants in an LRU
+  (`github.com/hashicorp/golang-lru/v2`), filled by `StoreVariant` and by
+  `GetVariant` after it reads a `.meta` file; for a variant it holds, `Lookup`
+  skips the check of the disk and `GetVariant` skips the `.meta` read, still
+  opening the variant file and taking the size from it; eviction removes the
+  entry before deleting the files, and `GetVariant` removes it when the file
+  will not open; the cap is a constant, not a setting; the unused `variantMeta`
+  type is gone; `README.md` describes it.
+- 2026-09-29 migrations at the path `REPO_POLICIES.md` sets (closes #96): the
+  migration files moved, contents unchanged, from `internal/database/schema/`
+  to `internal/db/migrations/` as `000_migration.sql` and `001_schema.sql`; the
+  `internal/db/migrations` package embeds them and `internal/database` reads
+  them through its `FS()`; the `internal/database` package itself stays; the
+  version still comes from the filename prefix, so a database that has recorded
+  versions 0 and 1 runs neither again.
 - 2026-09-29 `trusted_proxies` advice and signature padding in `README.md`
   (closes #150): the login-limit paragraph, the `trusted_proxies` entry and
   `config.example.yml` say to set `trusted_proxies` to the address pixa sees for

config.example.yml

@@ -12,12 +12,6 @@
 # Server settings
 port: 8080
 debug: false
-
-# While true, the image routes (/v1/image/ and /v1/e/) answer every request
-# with 503 and a Retry-After header. The health check keeps answering 200 and
-# reports maintenance_mode as true. It stays 200 because the image's Docker
-# HEALTHCHECK requests it: a 503 there would make the container unhealthy, and
-# upaas marks a deploy failed when its container is unhealthy.
 maintenance_mode: false
 
 # Data directory for SQLite database and cache files

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

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

internal/database/migrations_internal_test.go

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

internal/db/migrations/migrations.go

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

internal/imgcache/cache.go

@@ -14,6 +14,7 @@ import (
 	"sync"
 	"time"
 
+	lru "github.com/hashicorp/golang-lru/v2"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 )
 
@@ -26,6 +27,10 @@ var (
 // HTTP status code for successful fetch.
 const httpStatusOK = 200
 
+// metaCacheSize is how many variants' content types metaCache holds. A
+// variant not among them is served as before, reading its .meta file.
+const metaCacheSize = 10000
+
 // CacheConfig holds cache configuration.
 type CacheConfig struct {
 	StateDir    string
@@ -49,12 +54,6 @@ type CacheConfig struct {
 	Logger *slog.Logger
 }
 
-// variantMeta stores content type for fast cache hits without reading .meta file.
-type variantMeta struct {
-	ContentType string
-	Size        int64
-}
-
 // Cache implements the caching layer for the image proxy.
 type Cache struct {
 	db          *sql.DB
@@ -76,9 +75,10 @@ type Cache struct {
 	evictionStarted  bool
 	evictionStopOnce sync.Once
 
-	// In-memory cache of variant metadata (content type, size) to avoid
-	// reading .meta files
-	metaCache map[VariantKey]variantMeta
+	// metaCache holds the content types of the variants most recently
+	// stored or served, so a hit does not read the variant's .meta file.
+	// It never stands in for the variant file, which is always opened.
+	metaCache *lru.Cache[VariantKey, string]
 
 	// contentLocks serializes StoreSource and evictSourceBlob per
 	// content hash, closing the race window between an eviction's row
@@ -101,6 +101,11 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 		log = slog.Default()
 	}
 
+	metaCache, err := lru.New[VariantKey, string](metaCacheSize)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create variant content type cache: %w", err)
+	}
+
 	c := &Cache{
 		db:               db,
 		config:           config,
@@ -109,7 +114,7 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 		evictionPressure: make(chan struct{}, 1),
 		evictionStop:     make(chan struct{}),
 		evictionDone:     make(chan struct{}),
-		metaCache:        make(map[VariantKey]variantMeta),
+		metaCache:        metaCache,
 		contentLocks:     newContentLock(),
 	}
 
@@ -154,13 +159,15 @@ type LookupResult struct {
 	CacheStatus CacheStatus
 }
 
-// Lookup checks if a processed variant exists on disk. Hits touch the
-// variant's LRU timestamp; a disabled cache always misses.
+// Lookup checks if a processed variant exists on disk: a variant held
+// in metaCache counts as present without a check of the disk. Hits
+// touch the variant's LRU timestamp; a disabled cache always misses.
 func (c *Cache) Lookup(ctx context.Context, req *ImageRequest) (*LookupResult, error) {
 	cacheKey := CacheKey(req)
 
-	// Check variant storage directly - no DB needed for cache hits
-	if !c.disabled && c.variants.Exists(cacheKey) {
+	// Check memory, then variant storage - no DB needed for cache hits
+	if !c.disabled &&
+		(c.metaCache.Contains(cacheKey) || c.variants.Exists(cacheKey)) {
 		c.touchVariant(ctx, cacheKey)
 
 		return &LookupResult{
@@ -177,13 +184,35 @@ func (c *Cache) Lookup(ctx context.Context, req *ImageRequest) (*LookupResult, e
 	}, nil
 }
 
-// GetVariant returns a reader, size, and content type for a cached variant.
+// GetVariant returns a reader, size, and content type for a cached
+// variant. The content type comes from metaCache, or else from the
+// variant's .meta file and is then kept in metaCache.
 func (c *Cache) GetVariant(cacheKey VariantKey) (io.ReadCloser, int64, string, error) {
 	if c.disabled {
 		return nil, 0, "", ErrNotFound
 	}
 
-	return c.variants.LoadWithMeta(cacheKey)
+	contentType, known := c.metaCache.Get(cacheKey)
+	if known {
+		reader, size, err := c.variants.LoadWithSize(cacheKey)
+		if err != nil {
+			// The file is gone, e.g. deleted outside pixa
+			c.metaCache.Remove(cacheKey)
+
+			return nil, 0, "", err
+		}
+
+		return reader, size, contentType, nil
+	}
+
+	reader, size, contentType, err := c.variants.LoadWithMeta(cacheKey)
+	if err != nil {
+		return nil, 0, "", err
+	}
+
+	c.metaCache.Add(cacheKey, contentType)
+
+	return reader, size, contentType, nil
 }
 
 // StoreSource stores fetched source content and metadata. On a
@@ -286,6 +315,8 @@ func (c *Cache) StoreVariant(
 		return err
 	}
 
+	c.metaCache.Add(cacheKey, contentType)
+
 	_, err = c.db.ExecContext(ctx, `
 		INSERT INTO variant_content (cache_key, size_bytes, content_type)
 		VALUES (?, ?, ?)

internal/imgcache/eviction.go

@@ -271,7 +271,9 @@ func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, erro
 
 // evictVariant removes one variant: accounting row first, then the
 // content and .meta files, so the database never references a deleted
-// file.
+// file. The metaCache entry goes before the files; a GetVariant that
+// read them just before may put it back, and the next GetVariant then
+// fails to open the file and removes it again.
 func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 	_, err := c.db.ExecContext(ctx,
 		`DELETE FROM variant_content WHERE cache_key = ?`, string(cacheKey))
@@ -279,6 +281,8 @@ func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 		return fmt.Errorf("failed to delete variant accounting row: %w", err)
 	}
 
+	c.metaCache.Remove(cacheKey)
+
 	err = c.variants.DeleteWithMeta(cacheKey)
 	if err != nil {
 		return err

internal/imgcache/metacache_internal_test.go

@@ -0,0 +1,222 @@
+package imgcache
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"sync"
+	"testing"
+	"time"
+)
+
+// webpRequest returns a request for a 100x100 WebP variant of path.
+func webpRequest(path string) *ImageRequest {
+	return &ImageRequest{
+		SourceHost: testHostCDN,
+		SourcePath: path,
+		Size:       Size{Width: 100, Height: 100},
+		Format:     FormatWebP,
+		Quality:    85,
+		FitMode:    FitCover,
+	}
+}
+
+// assertVariantServed checks that GetVariant serves key with the given
+// content and the image/webp content type storeEvictionTestVariant stores.
+func assertVariantServed(t *testing.T, cache *Cache, key VariantKey, content []byte) {
+	t.Helper()
+
+	reader, size, contentType, err := cache.GetVariant(key)
+	if err != nil {
+		t.Fatalf("GetVariant(%s) error = %v", key, err)
+	}
+
+	defer func() { _ = reader.Close() }()
+
+	got, err := io.ReadAll(reader)
+	if err != nil {
+		t.Fatalf("reading variant %s: %v", key, err)
+	}
+
+	if !bytes.Equal(got, content) {
+		t.Errorf("GetVariant(%s) content = %q, want %q", key, got, content)
+	}
+
+	if size != int64(len(content)) {
+		t.Errorf("GetVariant(%s) size = %d, want %d", key, size, len(content))
+	}
+
+	if contentType != testContentTypeWebP {
+		t.Errorf("GetVariant(%s) content type = %q, want %q",
+			key, contentType, testContentTypeWebP)
+	}
+}
+
+// assertVariantNotFound checks that GetVariant refuses key with
+// ErrNotFound.
+func assertVariantNotFound(t *testing.T, cache *Cache, key VariantKey) {
+	t.Helper()
+
+	reader, _, _, err := cache.GetVariant(key)
+	if err == nil {
+		_ = reader.Close()
+	}
+
+	if !errors.Is(err, ErrNotFound) {
+		t.Errorf("GetVariant(%s) error = %v, want ErrNotFound", key, err)
+	}
+}
+
+// assertLookupMisses checks that Lookup reports request as a miss.
+func assertLookupMisses(t *testing.T, cache *Cache, request *ImageRequest) {
+	t.Helper()
+
+	lookup, err := cache.Lookup(t.Context(), request)
+	if err != nil {
+		t.Fatalf("Lookup(%s) error = %v", request.SourcePath, err)
+	}
+
+	if lookup.Hit {
+		t.Errorf("Lookup(%s) is a hit, want a miss", request.SourcePath)
+	}
+}
+
+// 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)
+}
+
+// TestEvictedVariantIsNotServed checks that a variant the evictor
+// removed is a miss and cannot be read, although it had been stored
+// and served before.
+func TestEvictedVariantIsNotServed(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1500)
+
+	oldRequest := webpRequest("/old.jpg")
+	newRequest := webpRequest("/new.jpg")
+	oldKey := CacheKey(oldRequest)
+	newKey := CacheKey(newRequest)
+	oldContent := bytes.Repeat([]byte{0x01}, 1000)
+	newContent := bytes.Repeat([]byte{0x02}, 1000)
+
+	storeEvictionTestVariant(t, cache, oldKey, oldContent)
+	storeEvictionTestVariant(t, cache, newKey, newContent)
+	assertVariantServed(t, cache, oldKey, oldContent)
+	setVariantLastAccessed(t, cache, oldKey, time.Now().Add(-time.Hour))
+
+	err := cache.EvictToLimit(t.Context())
+	if err != nil {
+		t.Fatalf("EvictToLimit() error = %v", err)
+	}
+
+	assertLookupMisses(t, cache, oldRequest)
+	assertVariantNotFound(t, cache, oldKey)
+	assertVariantServed(t, cache, newKey, newContent)
+}
+
+// TestVariantDeletedFromDiskIsNotServed checks that a variant whose
+// file was deleted by something other than the evictor cannot be read,
+// and is a miss afterwards.
+func TestVariantDeletedFromDiskIsNotServed(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+
+	request := webpRequest("/deleted.jpg")
+	key := CacheKey(request)
+	content := []byte("webp variant bytes")
+
+	storeEvictionTestVariant(t, cache, key, content)
+	assertVariantServed(t, cache, key, content)
+
+	err := os.Remove(cache.variants.keyToPath(key))
+	if err != nil {
+		t.Fatalf("removing variant file: %v", err)
+	}
+
+	assertVariantNotFound(t, cache, key)
+	assertLookupMisses(t, cache, request)
+}
+
+// TestConcurrentVariantStoreReadAndEvict stores, reads and evicts
+// variants from several goroutines at once, for the race detector.
+func TestConcurrentVariantStoreReadAndEvict(t *testing.T) {
+	t.Parallel()
+
+	cache, _ := newEvictionTestCache(t, 1<<20)
+	ctx := t.Context()
+
+	var wg sync.WaitGroup
+
+	for goroutine := range 8 {
+		wg.Go(func() {
+			key := VariantKey(fmt.Sprintf("aabbccdd01%02d", goroutine))
+			content := []byte(key)
+
+			for range 20 {
+				err := cache.StoreVariant(
+					ctx, key, bytes.NewReader(content), testContentTypeWebP)
+				if err != nil {
+					t.Errorf("StoreVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				reader, _, contentType, err := cache.GetVariant(key)
+				if err != nil {
+					t.Errorf("GetVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				_ = reader.Close()
+
+				if contentType != testContentTypeWebP {
+					t.Errorf("GetVariant(%s) content type = %q, want %q",
+						key, contentType, testContentTypeWebP)
+				}
+
+				err = cache.evictVariant(ctx, key)
+				if err != nil {
+					t.Errorf("evictVariant(%s) error = %v", key, err)
+
+					return
+				}
+
+				assertVariantNotFound(t, cache, key)
+			}
+		})
+	}
+
+	wg.Wait()
+}

internal/imgcache/storage.go

@@ -506,32 +506,43 @@ func (s *VariantStorage) Load(key VariantKey) (io.ReadCloser, error) {
 	return f, nil
 }
 
-// LoadWithMeta returns a reader, size, and content type for the content at
-// the given key.
-func (s *VariantStorage) LoadWithMeta(
-	key VariantKey,
-) (io.ReadCloser, int64, string, error) {
+// LoadWithSize returns a reader and file size for the content at the
+// given key.
+func (s *VariantStorage) LoadWithSize(key VariantKey) (io.ReadCloser, int64, error) {
 	path := s.keyToPath(key)
-	metaPath := path + ".meta"
 
 	f, err := os.Open(path) //nolint:gosec // path derived from cache key
 	if err != nil {
 		if os.IsNotExist(err) {
-			return nil, 0, "", ErrNotFound
+			return nil, 0, ErrNotFound
 		}
 
-		return nil, 0, "", fmt.Errorf("failed to open content: %w", err)
+		return nil, 0, fmt.Errorf("failed to open content: %w", err)
 	}
 
 	stat, err := f.Stat()
 	if err != nil {
 		_ = f.Close()
 
-		return nil, 0, "", fmt.Errorf("failed to stat content: %w", err)
+		return nil, 0, fmt.Errorf("failed to stat content: %w", err)
+	}
+
+	return f, stat.Size(), nil
+}
+
+// LoadWithMeta returns a reader, size, and content type for the content at
+// the given key.
+func (s *VariantStorage) LoadWithMeta(
+	key VariantKey,
+) (io.ReadCloser, int64, string, error) {
+	f, size, err := s.LoadWithSize(key)
+	if err != nil {
+		return nil, 0, "", err
 	}
 
 	// Load metadata for content type
 	contentType := "application/octet-stream" // fallback
+	metaPath := s.keyToPath(key) + ".meta"
 
 	metaData, err := os.ReadFile(metaPath) //nolint:gosec // path derived from cache key
 	if err == nil {
@@ -541,7 +552,7 @@ func (s *VariantStorage) LoadWithMeta(
 		}
 	}
 
-	return f, stat.Size(), contentType, nil
+	return f, size, contentType, nil
 }
 
 // Exists checks if content exists at the given key.

internal/imgcache/testutil_internal_test.go

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

internal/server/login_rate_limit_internal_test.go

@@ -18,7 +18,6 @@ import (
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/globals"
 	"sneak.berlin/go/pixa/internal/handlers"
-	"sneak.berlin/go/pixa/internal/healthcheck"
 	"sneak.berlin/go/pixa/internal/logger"
 	"sneak.berlin/go/pixa/internal/middleware"
 )
@@ -71,15 +70,8 @@ func newTestServer(t *testing.T) *Server {
 		t.Fatalf("database.New() error = %v", err)
 	}
 
-	hc, err := healthcheck.New(lc, healthcheck.Params{
-		Globals: &globals.Globals{}, Config: cfg, Logger: log, Database: db,
-	})
-	if err != nil {
-		t.Fatalf("healthcheck.New() error = %v", err)
-	}
-
 	h, err := handlers.New(lc, handlers.Params{
-		Logger: log, Healthcheck: hc, Database: db, Config: cfg,
+		Logger: log, Database: db, Config: cfg,
 	})
 	if err != nil {
 		t.Fatalf("handlers.New() error = %v", err)

internal/server/maintenance_internal_test.go

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

internal/server/routes.go

@@ -1,9 +1,7 @@
 package server
 
 import (
-	"encoding/json"
 	"net/http"
-	"strconv"
 	"time"
 
 	sentryhttp "github.com/getsentry/sentry-go/http"
@@ -19,10 +17,6 @@ import (
 // make per minute; the next is refused with 429 Too Many Requests.
 const LoginAttemptsPerMinute = 5
 
-// MaintenanceRetryAfterSeconds is the Retry-After, in seconds, sent with
-// the 503 that the image routes answer while maintenance mode is on.
-const MaintenanceRetryAfterSeconds = 300
-
 // SetupRoutes configures all HTTP routes.
 func (s *Server) SetupRoutes() {
 	s.router = chi.NewRouter()
@@ -74,23 +68,15 @@ func (s *Server) SetupRoutes() {
 
 	s.router.Get("/logout", s.h.HandleLogout())
 
-	// Image routes, refused while maintenance mode is on. Only these: the
-	// image's Docker HEALTHCHECK requests the health check, a 503 there
-	// would make the container unhealthy, and upaas marks a deploy failed
-	// when its container is unhealthy.
-	s.router.Group(func(r chi.Router) {
-		r.Use(s.refuseDuringMaintenance)
+	// Main image proxy route
+	// /v1/image/<host>/<path>/<width>x<height>.<format>
+	s.router.Get("/v1/image/*", s.h.HandleImage())
+	s.router.Head("/v1/image/*", s.h.HandleImage())
 
-		// Main image proxy route
-		// /v1/image/<host>/<path>/<width>x<height>.<format>
-		r.Get("/v1/image/*", s.h.HandleImage())
-		r.Head("/v1/image/*", s.h.HandleImage())
-
-		// Encrypted image URL route
-		// The trailing filename (e.g., /img.jpg) is ignored but helps
-		// browsers with content type
-		r.Get("/v1/e/{token}/*", s.h.HandleImageEnc())
-	})
+	// Encrypted image URL route
+	// The trailing filename (e.g., /img.jpg) is ignored but helps
+	// browsers with content type
+	s.router.Get("/v1/e/{token}/*", s.h.HandleImageEnc())
 
 	// Metrics endpoint with auth
 	if s.config.MetricsUsername != "" {
@@ -100,30 +86,3 @@ func (s *Server) SetupRoutes() {
 		})
 	}
 }
-
-// refuseDuringMaintenance answers a request with 503 Service Unavailable,
-// a Retry-After header and a JSON error body while maintenance mode is on,
-// and passes it on otherwise. The body has the fields of the JSON errors
-// the image handlers send.
-func (s *Server) refuseDuringMaintenance(next http.Handler) http.Handler {
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if !s.MaintenanceMode() {
-			next.ServeHTTP(w, r)
-
-			return
-		}
-
-		w.Header().Set("Retry-After", strconv.Itoa(MaintenanceRetryAfterSeconds))
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusServiceUnavailable)
-
-		err := json.NewEncoder(w).Encode(map[string]any{
-			"error":     "down for maintenance, try again later",
-			"status":    http.StatusServiceUnavailable,
-			"timestamp": time.Now().UTC().Format(time.RFC3339),
-		})
-		if err != nil {
-			s.log.Error("json encode error", "error", err)
-		}
-	})
-}