refactor: extract whitelist package from internal/imgcache (#41)

Extract `HostWhitelist`, `NewHostWhitelist`, `IsWhitelisted`, `IsEmpty`, and `Count` from `internal/imgcache/` into the new `internal/whitelist/` package.

The whitelist package is completely self-contained, depending only on `net/url` and `strings` from the standard library. No circular imports introduced.

**Changes:**
- Moved `whitelist.go` → `internal/whitelist/whitelist.go` (added package comment)
- Moved `whitelist_test.go` → `internal/whitelist/whitelist_test.go` (adapted to external test style)
- Updated `internal/imgcache/service.go` to import from `sneak.berlin/go/pixa/internal/whitelist`

`docker build .` passes (lint, tests, build).

Part of [issue #39](#39)

Co-authored-by: clawbot <clawbot@noreply.git.eeqj.de>
Co-authored-by: user <user@Mac.lan guest wan>
Reviewed-on: #41
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/allowlist/allowlist.go

@@ -1,26 +1,26 @@
-// Package whitelist provides host-based URL whitelisting for the image proxy.
-package whitelist
+// Package allowlist provides host-based URL allow-listing for the image proxy.
+package allowlist
 
 import (
 	"net/url"
 	"strings"
 )
 
-// HostWhitelist implements the Whitelist interface for checking allowed source hosts.
-type HostWhitelist struct {
+// HostAllowList checks whether source hosts are permitted.
+type HostAllowList struct {
 	// exactHosts contains hosts that must match exactly (e.g., "cdn.example.com")
 	exactHosts map[string]struct{}
 	// suffixHosts contains domain suffixes to match (e.g., ".example.com" matches "cdn.example.com")
 	suffixHosts []string
 }
 
-// NewHostWhitelist creates a whitelist from a list of host patterns.
+// New creates a HostAllowList from a list of host patterns.
 // Patterns starting with "." are treated as suffix matches.
 // Examples:
 //   - "cdn.example.com" - exact match only
 //   - ".example.com" - matches cdn.example.com, images.example.com, etc.
-func NewHostWhitelist(patterns []string) *HostWhitelist {
-	w := &HostWhitelist{
+func New(patterns []string) *HostAllowList {
+	w := &HostAllowList{
 		exactHosts:  make(map[string]struct{}),
 		suffixHosts: make([]string, 0),
 	}
@@ -41,8 +41,8 @@ func NewHostWhitelist(patterns []string) *HostWhitelist {
 	return w
 }
 
-// IsWhitelisted checks if a URL's host is in the whitelist.
-func (w *HostWhitelist) IsWhitelisted(u *url.URL) bool {
+// IsAllowed checks if a URL's host is in the allow list.
+func (w *HostAllowList) IsAllowed(u *url.URL) bool {
 	if u == nil {
 		return false
 	}
@@ -72,12 +72,12 @@ func (w *HostWhitelist) IsWhitelisted(u *url.URL) bool {
 	return false
 }
 
-// IsEmpty returns true if the whitelist has no entries.
-func (w *HostWhitelist) IsEmpty() bool {
+// 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 whitelist entries.
-func (w *HostWhitelist) Count() int {
+// 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

@@ -1,13 +1,13 @@
-package whitelist_test
+package allowlist_test
 
 import (
 	"net/url"
 	"testing"
 
-	"sneak.berlin/go/pixa/internal/whitelist"
+	"sneak.berlin/go/pixa/internal/allowlist"
 )
 
-func TestHostWhitelist_IsWhitelisted(t *testing.T) {
+func TestHostAllowList_IsAllowed(t *testing.T) {
 	tests := []struct {
 		name     string
 		patterns []string
@@ -69,7 +69,7 @@ func TestHostWhitelist_IsWhitelisted(t *testing.T) {
 			want:     true,
 		},
 		{
-			name:     "empty whitelist",
+			name:     "empty allow list",
 			patterns: []string{},
 			testURL:  "https://cdn.example.com/image.jpg",
 			want:     false,
@@ -96,7 +96,7 @@ func TestHostWhitelist_IsWhitelisted(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			w := whitelist.NewHostWhitelist(tt.patterns)
+			w := allowlist.New(tt.patterns)
 
 			var u *url.URL
 			if tt.testURL != "" {
@@ -107,15 +107,15 @@ func TestHostWhitelist_IsWhitelisted(t *testing.T) {
 				}
 			}
 
-			got := w.IsWhitelisted(u)
+			got := w.IsAllowed(u)
 			if got != tt.want {
-				t.Errorf("IsWhitelisted() = %v, want %v", got, tt.want)
+				t.Errorf("IsAllowed() = %v, want %v", got, tt.want)
 			}
 		})
 	}
 }
 
-func TestHostWhitelist_IsEmpty(t *testing.T) {
+func TestHostAllowList_IsEmpty(t *testing.T) {
 	tests := []struct {
 		name     string
 		patterns []string
@@ -145,7 +145,7 @@ func TestHostWhitelist_IsEmpty(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			w := whitelist.NewHostWhitelist(tt.patterns)
+			w := allowlist.New(tt.patterns)
 			if got := w.IsEmpty(); got != tt.want {
 				t.Errorf("IsEmpty() = %v, want %v", got, tt.want)
 			}
@@ -153,7 +153,7 @@ func TestHostWhitelist_IsEmpty(t *testing.T) {
 	}
 }
 
-func TestHostWhitelist_Count(t *testing.T) {
+func TestHostAllowList_Count(t *testing.T) {
 	tests := []struct {
 		name     string
 		patterns []string
@@ -183,7 +183,7 @@ func TestHostWhitelist_Count(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			w := whitelist.NewHostWhitelist(tt.patterns)
+			w := allowlist.New(tt.patterns)
 			if got := w.Count(); got != tt.want {
 				t.Errorf("Count() = %v, want %v", got, tt.want)
 			}

internal/database/database.go

@@ -9,6 +9,7 @@ import (
 	"log/slog"
 	"path/filepath"
 	"sort"
+	"strconv"
 	"strings"
 
 	"go.uber.org/fx"
@@ -21,6 +22,10 @@ import (
 //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
+
 // Params defines dependencies for Database.
 type Params struct {
 	fx.In
@@ -38,35 +43,40 @@ type Database struct {
 // ParseMigrationVersion extracts the numeric version prefix from a migration
 // filename. Filenames must follow the pattern "<version>.sql" or
 // "<version>_<description>.sql", where version is a zero-padded numeric
-// string (e.g. "001", "002"). Returns the version string and an error if
-// the filename does not match the expected pattern.
-func ParseMigrationVersion(filename string) (string, error) {
+// string (e.g. "001", "002"). Returns the version as an integer and an
+// error if the filename does not match the expected pattern.
+func ParseMigrationVersion(filename string) (int, error) {
 	name := strings.TrimSuffix(filename, filepath.Ext(filename))
 	if name == "" {
-		return "", fmt.Errorf("invalid migration filename %q: empty name", filename)
+		return 0, fmt.Errorf("invalid migration filename %q: empty name", filename)
 	}
 
 	// Split on underscore to separate version from description.
 	// If there's no underscore, the entire stem is the version.
-	version := name
+	versionStr := name
 	if idx := strings.IndexByte(name, '_'); idx >= 0 {
-		version = name[:idx]
+		versionStr = name[:idx]
 	}
 
-	if version == "" {
-		return "", fmt.Errorf("invalid migration filename %q: empty version prefix", filename)
+	if versionStr == "" {
+		return 0, fmt.Errorf("invalid migration filename %q: empty version prefix", filename)
 	}
 
 	// Validate the version is purely numeric.
-	for _, ch := range version {
+	for _, ch := range versionStr {
 		if ch < '0' || ch > '9' {
-			return "", fmt.Errorf(
+			return 0, fmt.Errorf(
 				"invalid migration filename %q: version %q contains non-numeric character %q",
-				filename, version, string(ch),
+				filename, versionStr, string(ch),
 			)
 		}
 	}
 
+	version, err := strconv.Atoi(versionStr)
+	if err != nil {
+		return 0, fmt.Errorf("invalid migration filename %q: %w", filename, err)
+	}
+
 	return version, nil
 }
 
@@ -143,17 +153,34 @@ func collectMigrations() ([]string, error) {
 	return migrations, nil
 }
 
-// ensureMigrationsTable creates the schema_migrations tracking table if
-// it does not already exist.
-func ensureMigrationsTable(ctx context.Context, db *sql.DB) error {
-	_, err := db.ExecContext(ctx, `
-		CREATE TABLE IF NOT EXISTS schema_migrations (
-			version TEXT PRIMARY KEY,
-			applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
-		)
-	`)
+// bootstrapMigrationsTable ensures the schema_migrations table exists
+// by applying 000.sql if the table is missing.
+func bootstrapMigrationsTable(ctx context.Context, db *sql.DB, log *slog.Logger) error {
+	var tableExists int
+
+	err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='schema_migrations'",
+	).Scan(&tableExists)
 	if err != nil {
-		return fmt.Errorf("failed to create migrations table: %w", err)
+		return fmt.Errorf("failed to check for migrations table: %w", err)
+	}
+
+	if tableExists > 0 {
+		return nil
+	}
+
+	content, err := schemaFS.ReadFile("schema/000.sql")
+	if err != nil {
+		return fmt.Errorf("failed to read bootstrap migration 000.sql: %w", err)
+	}
+
+	if log != nil {
+		log.Info("applying bootstrap migration", "version", bootstrapVersion)
+	}
+
+	_, err = db.ExecContext(ctx, string(content))
+	if err != nil {
+		return fmt.Errorf("failed to apply bootstrap migration: %w", err)
 	}
 
 	return nil
@@ -164,7 +191,7 @@ func ensureMigrationsTable(ctx context.Context, db *sql.DB) error {
 // This is exported so tests can apply the real schema without the full fx
 // lifecycle.
 func ApplyMigrations(ctx context.Context, db *sql.DB, log *slog.Logger) error {
-	if err := ensureMigrationsTable(ctx, db); err != nil {
+	if err := bootstrapMigrationsTable(ctx, db, log); err != nil {
 		return err
 	}
 

internal/database/database_test.go

@@ -8,37 +8,51 @@ import (
 	_ "modernc.org/sqlite" // SQLite driver registration
 )
 
+// openTestDB returns a fresh in-memory SQLite database.
+func openTestDB(t *testing.T) *sql.DB {
+	t.Helper()
+
+	db, err := sql.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("failed to open test db: %v", err)
+	}
+
+	t.Cleanup(func() { db.Close() })
+
+	return db
+}
+
 func TestParseMigrationVersion(t *testing.T) {
 	tests := []struct {
 		name     string
 		filename string
-		want     string
+		want     int
 		wantErr  bool
 	}{
 		{
 			name:     "version only",
 			filename: "001.sql",
-			want:     "001",
+			want:     1,
 		},
 		{
 			name:     "version with description",
 			filename: "001_initial_schema.sql",
-			want:     "001",
+			want:     1,
 		},
 		{
 			name:     "multi-digit version",
 			filename: "042_add_indexes.sql",
-			want:     "042",
+			want:     42,
 		},
 		{
 			name:     "long version number",
 			filename: "00001_long_prefix.sql",
-			want:     "00001",
+			want:     1,
 		},
 		{
 			name:     "description with multiple underscores",
 			filename: "003_add_user_auth_tables.sql",
-			want:     "003",
+			want:     3,
 		},
 		{
 			name:     "empty filename",
@@ -67,7 +81,7 @@ func TestParseMigrationVersion(t *testing.T) {
 			got, err := ParseMigrationVersion(tt.filename)
 			if tt.wantErr {
 				if err == nil {
-					t.Errorf("ParseMigrationVersion(%q) expected error, got %q", tt.filename, got)
+					t.Errorf("ParseMigrationVersion(%q) expected error, got %d", tt.filename, got)
 				}
 
 				return
@@ -80,76 +94,131 @@ func TestParseMigrationVersion(t *testing.T) {
 			}
 
 			if got != tt.want {
-				t.Errorf("ParseMigrationVersion(%q) = %q, want %q", tt.filename, got, tt.want)
+				t.Errorf("ParseMigrationVersion(%q) = %d, want %d", tt.filename, got, tt.want)
 			}
 		})
 	}
 }
 
-func TestApplyMigrations(t *testing.T) {
-	db, err := sql.Open("sqlite", ":memory:")
-	if err != nil {
-		t.Fatalf("failed to open in-memory database: %v", err)
-	}
-	defer db.Close()
+func TestApplyMigrations_CreatesSchemaAndTables(t *testing.T) {
+	db := openTestDB(t)
+	ctx := context.Background()
 
-	// Apply migrations should succeed.
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
+	if err := ApplyMigrations(ctx, db, nil); err != nil {
 		t.Fatalf("ApplyMigrations failed: %v", err)
 	}
 
-	// Verify the schema_migrations table recorded the version.
-	var version string
-
-	err = db.QueryRowContext(context.Background(),
-		"SELECT version FROM schema_migrations LIMIT 1",
-	).Scan(&version)
+	// The schema_migrations table must exist and contain at least
+	// version 0 (the bootstrap) and 1 (the initial schema).
+	rows, err := db.Query("SELECT version FROM schema_migrations ORDER BY version")
 	if err != nil {
 		t.Fatalf("failed to query schema_migrations: %v", err)
 	}
+	defer rows.Close()
 
-	if version != "001" {
-		t.Errorf("expected version %q, got %q", "001", version)
+	var versions []int
+	for rows.Next() {
+		var v int
+		if err := rows.Scan(&v); err != nil {
+			t.Fatalf("failed to scan version: %v", err)
 		}
 
-	// Verify a table from the migration exists (source_content).
-	var tableName string
-
-	err = db.QueryRowContext(context.Background(),
-		"SELECT name FROM sqlite_master WHERE type='table' AND name='source_content'",
-	).Scan(&tableName)
-	if err != nil {
-		t.Fatalf("expected source_content table to exist: %v", err)
-	}
+		versions = append(versions, v)
 	}
 
-func TestApplyMigrationsIdempotent(t *testing.T) {
-	db, err := sql.Open("sqlite", ":memory:")
-	if err != nil {
-		t.Fatalf("failed to open in-memory database: %v", err)
-	}
-	defer db.Close()
-
-	// Apply twice should succeed (idempotent).
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
-		t.Fatalf("first ApplyMigrations failed: %v", err)
+	if err := rows.Err(); err != nil {
+		t.Fatalf("row iteration error: %v", err)
 	}
 
-	if err := ApplyMigrations(context.Background(), db, nil); err != nil {
-		t.Fatalf("second ApplyMigrations failed: %v", err)
+	if len(versions) < 2 {
+		t.Fatalf("expected at least 2 migrations recorded, got %d: %v", len(versions), versions)
 	}
 
-	// Should still have exactly one migration recorded.
+	if versions[0] != 0 {
+		t.Errorf("first recorded migration = %d, want %d", versions[0], 0)
+	}
+
+	if versions[1] != 1 {
+		t.Errorf("second recorded migration = %d, want %d", versions[1], 1)
+	}
+
+	// Verify that the application tables created by 001.sql exist.
+	for _, table := range []string{"source_content", "source_metadata", "output_content", "request_cache", "negative_cache", "cache_stats"} {
 		var count int
 
-	err = db.QueryRowContext(context.Background(),
-		"SELECT COUNT(*) FROM schema_migrations",
+		err := db.QueryRow(
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?",
+			table,
 		).Scan(&count)
 		if err != nil {
-		t.Fatalf("failed to count schema_migrations: %v", err)
+			t.Fatalf("failed to check for table %s: %v", table, err)
 		}
 
 		if count != 1 {
-		t.Errorf("expected 1 migration record, got %d", count)
+			t.Errorf("table %s does not exist after migrations", table)
+		}
+	}
+}
+
+func TestApplyMigrations_Idempotent(t *testing.T) {
+	db := openTestDB(t)
+	ctx := context.Background()
+
+	if err := ApplyMigrations(ctx, db, nil); err != nil {
+		t.Fatalf("first ApplyMigrations failed: %v", err)
+	}
+
+	// Running a second time must succeed without errors.
+	if err := ApplyMigrations(ctx, db, nil); err != nil {
+		t.Fatalf("second ApplyMigrations failed: %v", err)
+	}
+
+	// Verify no duplicate rows in schema_migrations.
+	var count int
+
+	err := db.QueryRow("SELECT COUNT(*) FROM schema_migrations WHERE version = 0").Scan(&count)
+	if err != nil {
+		t.Fatalf("failed to count version 0 rows: %v", err)
+	}
+
+	if count != 1 {
+		t.Errorf("expected exactly 1 row for version 0, got %d", count)
+	}
+}
+
+func TestBootstrapMigrationsTable_FreshDatabase(t *testing.T) {
+	db := openTestDB(t)
+	ctx := context.Background()
+
+	if err := bootstrapMigrationsTable(ctx, db, nil); err != nil {
+		t.Fatalf("bootstrapMigrationsTable failed: %v", err)
+	}
+
+	// schema_migrations table must exist.
+	var tableCount int
+
+	err := db.QueryRow(
+		"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='schema_migrations'",
+	).Scan(&tableCount)
+	if err != nil {
+		t.Fatalf("failed to check for table: %v", err)
+	}
+
+	if tableCount != 1 {
+		t.Fatalf("schema_migrations table not created")
+	}
+
+	// Version 0 must be recorded.
+	var recorded int
+
+	err = db.QueryRow(
+		"SELECT COUNT(*) FROM schema_migrations WHERE version = 0",
+	).Scan(&recorded)
+	if err != nil {
+		t.Fatalf("failed to check version: %v", err)
+	}
+
+	if recorded != 1 {
+		t.Errorf("expected version 0 to be recorded, got count %d", recorded)
 	}
 }

internal/database/schema/000.sql

@@ -0,0 +1,9 @@
+-- Migration 000: Schema migrations tracking table
+-- Applied as a bootstrap step before the normal migration loop.
+
+CREATE TABLE IF NOT EXISTS schema_migrations (
+    version INTEGER PRIMARY KEY,
+    applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+INSERT OR IGNORE INTO schema_migrations (version) VALUES (0);

internal/imgcache/service.go

@@ -11,8 +11,8 @@ import (
 	"time"
 
 	"github.com/dustin/go-humanize"
+	"sneak.berlin/go/pixa/internal/allowlist"
 	"sneak.berlin/go/pixa/internal/imageprocessor"
-	"sneak.berlin/go/pixa/internal/whitelist"
 )
 
 // Service implements the ImageCache interface, orchestrating cache, fetcher, and processor.
@@ -21,7 +21,7 @@ type Service struct {
 	fetcher         Fetcher
 	processor       *imageprocessor.ImageProcessor
 	signer          *Signer
-	whitelist       *whitelist.HostWhitelist
+	allowlist       *allowlist.HostAllowList
 	log             *slog.Logger
 	allowHTTP       bool
 	maxResponseSize int64
@@ -86,7 +86,7 @@ func NewService(cfg *ServiceConfig) (*Service, error) {
 		fetcher:         fetcher,
 		processor:       imageprocessor.New(imageprocessor.Params{MaxInputBytes: maxResponseSize}),
 		signer:          signer,
-		whitelist:       whitelist.NewHostWhitelist(cfg.Whitelist),
+		allowlist:       allowlist.New(cfg.Whitelist),
 		log:             log,
 		allowHTTP:       allowHTTP,
 		maxResponseSize: maxResponseSize,
@@ -382,7 +382,7 @@ func (s *Service) Stats(ctx context.Context) (*CacheStats, error) {
 
 // ValidateRequest validates the request signature if required.
 func (s *Service) ValidateRequest(req *ImageRequest) error {
-	// Check if host is whitelisted (no signature required)
+	// Check if host is allowed (no signature required)
 	sourceURL := req.SourceURL()
 
 	parsedURL, err := url.Parse(sourceURL)
@@ -390,11 +390,11 @@ func (s *Service) ValidateRequest(req *ImageRequest) error {
 		return fmt.Errorf("invalid source URL: %w", err)
 	}
 
-	if s.whitelist.IsWhitelisted(parsedURL) {
+	if s.allowlist.IsAllowed(parsedURL) {
 		return nil
 	}
 
-	// Signature required for non-whitelisted hosts
+	// Signature required for non-allowed hosts
 	return s.signer.Verify(req)
 }