Merge branch 'main' into consolidate-appname-to-globals

Closes #28

Migration filenames now follow the pattern `<version>_<description>.sql` (e.g. `001_initial_schema.sql`). The version stored in `schema_migrations` is the numeric prefix only, not the full filename stem.

## Changes

- **`ParseMigrationVersion()`** — new exported function that extracts the numeric prefix from migration filenames. Validates that the prefix is purely numeric and rejects malformed filenames (empty prefix, non-numeric characters, leading underscore).
- **Renamed `001.sql` → `001_initial_schema.sql`** — migration files can now have descriptive names while the tracked version remains `001`. This is safe pre-1.0.0 (no installed base).
- **Deduplicated migration logic** — `runMigrations()` and `ApplyMigrations()` now share a single `applyMigrations()` implementation, plus extracted `collectMigrations()` and `ensureMigrationsTable()` helpers.
- **Unit tests** — `TestParseMigrationVersion` covers valid patterns (version-only, with description, multi-digit, multiple underscores) and error cases (empty, leading underscore, non-numeric, mixed alphanumeric). `TestApplyMigrations` and `TestApplyMigrationsIdempotent` verify end-to-end migration application against an in-memory SQLite database.

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

README.md

@@ -96,10 +96,11 @@ expiration 1704067200:
 4. URL:
    `/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp?sig=<base64url>&exp=1704067200`
 
-**Whitelist entries** are exact host matches only (e.g.
-`cdn.example.com`). Suffix/wildcard matching is not supported —
-signatures are per-URL, so each allowed host must be listed
-explicitly.
+**Whitelist patterns:**
+
+- **Exact match**: `cdn.example.com` — matches only that host
+- **Suffix match**: `.example.com` — matches `cdn.example.com`,
+  `images.example.com`, and `example.com`
 
 ### Configuration
 

cmd/pixad/main.go

@@ -17,10 +17,7 @@ import (
 	"sneak.berlin/go/pixa/internal/server"
 )
 
-var (
-	Appname = "pixad" //nolint:gochecknoglobals // set by ldflags
-	Version string    //nolint:gochecknoglobals // set by ldflags
-)
+var Version string //nolint:gochecknoglobals // set by ldflags
 
 var configPath string //nolint:gochecknoglobals // cobra flag
 
@@ -40,7 +37,6 @@ func main() {
 }
 
 func run(_ *cobra.Command, _ []string) {
-	globals.Appname = Appname
 	globals.Version = Version
 
 	// Set config path in environment if specified via flag

config.example.yml

@@ -13,7 +13,8 @@ state_dir: ./data
 # Generate with: openssl rand -base64 32
 signing_key: "CHANGE_ME_generate_with_openssl_rand_base64_32"
 
-# Hosts that don't require signatures (exact match only)
+# Hosts that don't require signatures
+# Use "." prefix for wildcard subdomain matching (e.g., ".example.com" matches "cdn.example.com")
 whitelist_hosts:
   - s3.sneak.cloud
   - static.sneak.cloud

internal/database/database.go

@@ -35,6 +35,41 @@ type Database struct {
 	config *config.Config
 }
 
+// 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) {
+	name := strings.TrimSuffix(filename, filepath.Ext(filename))
+	if name == "" {
+		return "", 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
+	if idx := strings.IndexByte(name, '_'); idx >= 0 {
+		version = name[:idx]
+	}
+
+	if version == "" {
+		return "", fmt.Errorf("invalid migration filename %q: empty version prefix", filename)
+	}
+
+	// Validate the version is purely numeric.
+	for _, ch := range version {
+		if ch < '0' || ch > '9' {
+			return "", fmt.Errorf(
+				"invalid migration filename %q: version %q contains non-numeric character %q",
+				filename, version, string(ch),
+			)
+		}
+	}
+
+	return version, nil
+}
+
 // New creates a new Database instance.
 func New(lc fx.Lifecycle, params Params) (*Database, error) {
 	s := &Database{
@@ -84,96 +119,33 @@ func (s *Database) connect(ctx context.Context) error {
 	s.db = db
 	s.log.Info("database connected")
 
-	return s.runMigrations(ctx)
+	return ApplyMigrations(ctx, s.db, s.log)
 }
 
-func (s *Database) runMigrations(ctx context.Context) error {
-	// Create migrations tracking table
-	_, err := s.db.ExecContext(ctx, `
-		CREATE TABLE IF NOT EXISTS schema_migrations (
-			version TEXT PRIMARY KEY,
-			applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
-		)
-	`)
-	if err != nil {
-		return fmt.Errorf("failed to create migrations table: %w", err)
-	}
-
-	// Get list of migration files
+// collectMigrations reads the embedded schema directory and returns
+// migration filenames sorted lexicographically.
+func collectMigrations() ([]string, error) {
 	entries, err := schemaFS.ReadDir("schema")
 	if err != nil {
-		return fmt.Errorf("failed to read schema directory: %w", err)
+		return nil, fmt.Errorf("failed to read schema directory: %w", err)
 	}
 
-	// Sort migration files by name (001.sql, 002.sql, etc.)
 	var migrations []string
+
 	for _, entry := range entries {
 		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
 			migrations = append(migrations, entry.Name())
 		}
 	}
+
 	sort.Strings(migrations)
 
-	// Apply each migration that hasn't been applied yet
-	for _, migration := range migrations {
-		version := strings.TrimSuffix(migration, filepath.Ext(migration))
-
-		// Check if already applied
-		var count int
-		err := s.db.QueryRowContext(ctx,
-			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
-			version,
-		).Scan(&count)
-		if err != nil {
-			return fmt.Errorf("failed to check migration status: %w", err)
-		}
-
-		if count > 0 {
-			s.log.Debug("migration already applied", "version", version)
-
-			continue
-		}
-
-		// Read and apply migration
-		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
-		if err != nil {
-			return fmt.Errorf("failed to read migration %s: %w", migration, err)
-		}
-
-		s.log.Info("applying migration", "version", version)
-
-		_, err = s.db.ExecContext(ctx, string(content))
-		if err != nil {
-			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
-		}
-
-		// Record migration as applied
-		_, err = s.db.ExecContext(ctx,
-			"INSERT INTO schema_migrations (version) VALUES (?)",
-			version,
-		)
-		if err != nil {
-			return fmt.Errorf("failed to record migration %s: %w", migration, err)
-		}
-
-		s.log.Info("migration applied successfully", "version", version)
-	}
-
-	return nil
+	return migrations, nil
 }
 
-// DB returns the underlying sql.DB.
-func (s *Database) DB() *sql.DB {
-	return s.db
-}
-
-// ApplyMigrations applies all migrations to the given database.
-// This is useful for testing where you want to use the real schema
-// without the full fx lifecycle.
-func ApplyMigrations(db *sql.DB) error {
-	ctx := context.Background()
-
-	// Create migrations tracking table
+// 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,
@@ -184,27 +156,32 @@ func ApplyMigrations(db *sql.DB) error {
 		return fmt.Errorf("failed to create migrations table: %w", err)
 	}
 
-	// Get list of migration files
-	entries, err := schemaFS.ReadDir("schema")
+	return nil
+}
+
+// ApplyMigrations applies all pending migrations to db. An optional logger
+// may be provided for informational output; pass nil for silent operation.
+// 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 {
+		return err
+	}
+
+	migrations, err := collectMigrations()
 	if err != nil {
-		return fmt.Errorf("failed to read schema directory: %w", err)
+		return err
 	}
 
-	// Sort migration files by name (001.sql, 002.sql, etc.)
-	var migrations []string
-	for _, entry := range entries {
-		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".sql") {
-			migrations = append(migrations, entry.Name())
-		}
-	}
-	sort.Strings(migrations)
-
-	// Apply each migration that hasn't been applied yet
 	for _, migration := range migrations {
-		version := strings.TrimSuffix(migration, filepath.Ext(migration))
+		version, parseErr := ParseMigrationVersion(migration)
+		if parseErr != nil {
+			return parseErr
+		}
 
-		// Check if already applied
+		// Check if already applied.
 		var count int
+
 		err := db.QueryRowContext(ctx,
 			"SELECT COUNT(*) FROM schema_migrations WHERE version = ?",
 			version,
@@ -214,29 +191,46 @@ func ApplyMigrations(db *sql.DB) error {
 		}
 
 		if count > 0 {
+			if log != nil {
+				log.Debug("migration already applied", "version", version)
+			}
+
 			continue
 		}
 
-		// Read and apply migration
-		content, err := schemaFS.ReadFile(filepath.Join("schema", migration))
-		if err != nil {
-			return fmt.Errorf("failed to read migration %s: %w", migration, err)
+		// Read and apply migration.
+		content, readErr := schemaFS.ReadFile(filepath.Join("schema", migration))
+		if readErr != nil {
+			return fmt.Errorf("failed to read migration %s: %w", migration, readErr)
 		}
 
-		_, err = db.ExecContext(ctx, string(content))
-		if err != nil {
-			return fmt.Errorf("failed to apply migration %s: %w", migration, err)
+		if log != nil {
+			log.Info("applying migration", "version", version)
 		}
 
-		// Record migration as applied
-		_, err = db.ExecContext(ctx,
+		_, execErr := db.ExecContext(ctx, string(content))
+		if execErr != nil {
+			return fmt.Errorf("failed to apply migration %s: %w", migration, execErr)
+		}
+
+		// Record migration as applied.
+		_, recErr := db.ExecContext(ctx,
 			"INSERT INTO schema_migrations (version) VALUES (?)",
 			version,
 		)
-		if err != nil {
-			return fmt.Errorf("failed to record migration %s: %w", migration, err)
+		if recErr != nil {
+			return fmt.Errorf("failed to record migration %s: %w", migration, recErr)
+		}
+
+		if log != nil {
+			log.Info("migration applied successfully", "version", version)
 		}
 	}
 
 	return nil
 }
+
+// DB returns the underlying sql.DB.
+func (s *Database) DB() *sql.DB {
+	return s.db
+}

internal/database/database_test.go

@@ -0,0 +1,155 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"testing"
+
+	_ "modernc.org/sqlite" // SQLite driver registration
+)
+
+func TestParseMigrationVersion(t *testing.T) {
+	tests := []struct {
+		name     string
+		filename string
+		want     string
+		wantErr  bool
+	}{
+		{
+			name:     "version only",
+			filename: "001.sql",
+			want:     "001",
+		},
+		{
+			name:     "version with description",
+			filename: "001_initial_schema.sql",
+			want:     "001",
+		},
+		{
+			name:     "multi-digit version",
+			filename: "042_add_indexes.sql",
+			want:     "042",
+		},
+		{
+			name:     "long version number",
+			filename: "00001_long_prefix.sql",
+			want:     "00001",
+		},
+		{
+			name:     "description with multiple underscores",
+			filename: "003_add_user_auth_tables.sql",
+			want:     "003",
+		},
+		{
+			name:     "empty filename",
+			filename: ".sql",
+			wantErr:  true,
+		},
+		{
+			name:     "leading underscore",
+			filename: "_description.sql",
+			wantErr:  true,
+		},
+		{
+			name:     "non-numeric version",
+			filename: "abc_migration.sql",
+			wantErr:  true,
+		},
+		{
+			name:     "mixed alphanumeric version",
+			filename: "001a_migration.sql",
+			wantErr:  true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(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)
+				}
+
+				return
+			}
+
+			if err != nil {
+				t.Errorf("ParseMigrationVersion(%q) unexpected error: %v", tt.filename, err)
+
+				return
+			}
+
+			if got != tt.want {
+				t.Errorf("ParseMigrationVersion(%q) = %q, want %q", 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()
+
+	// Apply migrations should succeed.
+	if err := ApplyMigrations(context.Background(), 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)
+	if err != nil {
+		t.Fatalf("failed to query schema_migrations: %v", err)
+	}
+
+	if version != "001" {
+		t.Errorf("expected version %q, got %q", "001", version)
+	}
+
+	// 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)
+	}
+}
+
+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 := ApplyMigrations(context.Background(), db, nil); err != nil {
+		t.Fatalf("second ApplyMigrations failed: %v", err)
+	}
+
+	// Should still have exactly one migration recorded.
+	var count int
+
+	err = db.QueryRowContext(context.Background(),
+		"SELECT COUNT(*) FROM schema_migrations",
+	).Scan(&count)
+	if err != nil {
+		t.Fatalf("failed to count schema_migrations: %v", err)
+	}
+
+	if count != 1 {
+		t.Errorf("expected 1 migration record, got %d", count)
+	}
+}

internal/globals/globals.go

@@ -5,11 +5,10 @@ import (
 	"go.uber.org/fx"
 )
 
-// Build-time variables populated from main() via ldflags.
-var (
-	Appname string //nolint:gochecknoglobals // set from main
-	Version string //nolint:gochecknoglobals // set from main
-)
+const appname = "pixad"
+
+// Version is populated from main() via ldflags.
+var Version string //nolint:gochecknoglobals // set from main
 
 // Globals holds application-wide constants.
 type Globals struct {
@@ -20,7 +19,7 @@ type Globals struct {
 // New creates a new Globals instance from build-time variables.
 func New(_ fx.Lifecycle) (*Globals, error) {
 	return &Globals{
-		Appname: Appname,
+		Appname: appname,
 		Version: Version,
 	}, nil
 }

internal/handlers/handlers_test.go

@@ -82,7 +82,7 @@ func setupTestDB(t *testing.T) *sql.DB {
 		t.Fatalf("failed to open test db: %v", err)
 	}
 
-	if err := database.ApplyMigrations(db); err != nil {
+	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
 		t.Fatalf("failed to apply migrations: %v", err)
 	}
 

internal/imgcache/stats_test.go

@@ -16,7 +16,7 @@ func setupStatsTestDB(t *testing.T) *sql.DB {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if err := database.ApplyMigrations(db); err != nil {
+	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
 		t.Fatal(err)
 	}
 	t.Cleanup(func() { db.Close() })

internal/imgcache/testutil_test.go

@@ -2,6 +2,7 @@ package imgcache
 
 import (
 	"bytes"
+	"context"
 	"database/sql"
 	"image"
 	"image/color"
@@ -193,7 +194,7 @@ func setupServiceTestDB(t *testing.T) *sql.DB {
 	}
 
 	// Use the real production schema via migrations
-	if err := database.ApplyMigrations(db); err != nil {
+	if err := database.ApplyMigrations(context.Background(), db, nil); err != nil {
 		t.Fatalf("failed to apply migrations: %v", err)
 	}
 

internal/imgcache/whitelist.go

@@ -5,20 +5,23 @@ import (
 	"strings"
 )
 
-// HostWhitelist checks whether a source host is allowed without a signature.
-// Only exact host matches are supported. Signatures are per-URL, so
-// wildcard/suffix matching is intentionally not provided.
+// HostWhitelist implements the Whitelist interface for checking allowed source hosts.
 type HostWhitelist 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 hostnames.
-// Each entry is treated as an exact host match. Leading dots are
-// stripped so that legacy ".example.com" entries become "example.com".
+// NewHostWhitelist creates a whitelist 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{
-		exactHosts: make(map[string]struct{}),
+		exactHosts:  make(map[string]struct{}),
+		suffixHosts: make([]string, 0),
 	}
 
 	for _, pattern := range patterns {
@@ -27,11 +30,9 @@ func NewHostWhitelist(patterns []string) *HostWhitelist {
 			continue
 		}
 
-		// Strip leading dot — suffix matching is no longer supported;
-		// ".example.com" is normalised to "example.com" as an exact entry.
-		pattern = strings.TrimPrefix(pattern, ".")
-
-		if pattern != "" {
+		if strings.HasPrefix(pattern, ".") {
+			w.suffixHosts = append(w.suffixHosts, pattern)
+		} else {
 			w.exactHosts[pattern] = struct{}{}
 		}
 	}
@@ -39,7 +40,7 @@ func NewHostWhitelist(patterns []string) *HostWhitelist {
 	return w
 }
 
-// IsWhitelisted checks if a URL's host is in the whitelist (exact match only).
+// IsWhitelisted checks if a URL's host is in the whitelist.
 func (w *HostWhitelist) IsWhitelisted(u *url.URL) bool {
 	if u == nil {
 		return false
@@ -50,17 +51,32 @@ func (w *HostWhitelist) IsWhitelisted(u *url.URL) bool {
 		return false
 	}
 
-	_, ok := w.exactHosts[host]
+	// Check exact match
+	if _, ok := w.exactHosts[host]; ok {
+		return true
+	}
 
-	return ok
+	// Check suffix match
+	for _, suffix := range w.suffixHosts {
+		if strings.HasSuffix(host, suffix) {
+			return true
+		}
+		// Also match if host equals the suffix without the leading dot
+		// e.g., pattern ".example.com" should match "example.com"
+		if host == strings.TrimPrefix(suffix, ".") {
+			return true
+		}
+	}
+
+	return false
 }
 
 // IsEmpty returns true if the whitelist has no entries.
 func (w *HostWhitelist) IsEmpty() bool {
-	return len(w.exactHosts) == 0
+	return len(w.exactHosts) == 0 && len(w.suffixHosts) == 0
 }
 
 // Count returns the total number of whitelist entries.
 func (w *HostWhitelist) Count() int {
-	return len(w.exactHosts)
+	return len(w.exactHosts) + len(w.suffixHosts)
 }

internal/imgcache/whitelist_test.go

@@ -31,41 +31,41 @@ func TestHostWhitelist_IsWhitelisted(t *testing.T) {
 			want:     false,
 		},
 		{
-			name:     "no suffix matching for subdomains",
-			patterns: []string{"example.com"},
+			name:     "suffix match",
+			patterns: []string{".example.com"},
 			testURL:  "https://cdn.example.com/image.jpg",
-			want:     false,
+			want:     true,
 		},
 		{
-			name:     "leading dot stripped to exact match",
+			name:     "suffix match deep subdomain",
+			patterns: []string{".example.com"},
+			testURL:  "https://cdn.images.example.com/image.jpg",
+			want:     true,
+		},
+		{
+			name:     "suffix match apex domain",
 			patterns: []string{".example.com"},
 			testURL:  "https://example.com/image.jpg",
 			want:     true,
 		},
 		{
-			name:     "leading dot does not enable suffix matching",
+			name:     "suffix match not found",
 			patterns: []string{".example.com"},
-			testURL:  "https://cdn.example.com/image.jpg",
+			testURL:  "https://notexample.com/image.jpg",
 			want:     false,
 		},
 		{
-			name:     "leading dot does not match deep subdomain",
+			name:     "suffix match partial not allowed",
 			patterns: []string{".example.com"},
-			testURL:  "https://cdn.images.example.com/image.jpg",
+			testURL:  "https://fakeexample.com/image.jpg",
 			want:     false,
 		},
 		{
-			name:     "multiple patterns exact only",
-			patterns: []string{"cdn.example.com", "photos.images.org", "static.test.net"},
+			name:     "multiple patterns",
+			patterns: []string{"cdn.example.com", ".images.org", "static.test.net"},
 			testURL:  "https://photos.images.org/image.jpg",
 			want:     true,
 		},
-		{
-			name:     "multiple patterns no suffix leak",
-			patterns: []string{"cdn.example.com", "images.org"},
-			testURL:  "https://photos.images.org/image.jpg",
-			want:     false,
-		},
 		{
 			name:     "empty whitelist",
 			patterns: []string{},
@@ -86,7 +86,7 @@ func TestHostWhitelist_IsWhitelisted(t *testing.T) {
 		},
 		{
 			name:     "whitespace in patterns",
-			patterns: []string{"  cdn.example.com  ", "  other.com  "},
+			patterns: []string{"  cdn.example.com  ", "  .other.com  "},
 			testURL:  "https://cdn.example.com/image.jpg",
 			want:     true,
 		},
@@ -139,11 +139,6 @@ func TestHostWhitelist_IsEmpty(t *testing.T) {
 			patterns: []string{"example.com"},
 			want:     false,
 		},
-		{
-			name:     "leading dot normalised to entry",
-			patterns: []string{".example.com"},
-			want:     false,
-		},
 	}
 
 	for _, tt := range tests {
@@ -173,14 +168,14 @@ func TestHostWhitelist_Count(t *testing.T) {
 			want:     3,
 		},
 		{
-			name:     "leading dots normalised to exact",
+			name:     "suffix hosts only",
 			patterns: []string{".a.com", ".b.com"},
 			want:     2,
 		},
 		{
-			name:     "mixed deduplication",
-			patterns: []string{"example.com", ".example.com"},
-			want:     1,
+			name:     "mixed",
+			patterns: []string{"exact.com", ".suffix.com"},
+			want:     2,
 		},
 	}