Restructure backend into services and fix security, crash and sync issues

Security
- Serve character images through os.Root so names like ../ can't escape
  the characters folder
- Sync start and /sync/reset are POST only (legacy and /api/v1)
- /api/v1/token/cleanup requires a token, password compared in constant
  time, tokens no longer logged
- Echo's rate limiter replaces the custom one; TRUSTED_PROXIES enables
  X-Forwarded-For for reverse proxies

Crashes and races
- Sync state lives in SyncService with atomics and a mutex instead of
  unsynchronised globals (fixes concurrent map writes during full sync)
- Only one sync can run; /api/v1 sync and music routes are locked during
  sync like the legacy ones
- No log.Fatal outside startup: errors become 4xx/5xx responses
- Search uses an in-order character match instead of unescaped regexes
- Empty queue / no songs return 404 instead of panicking or looping

Behaviour
- Sync result is computed once and stays the same between polls
- Swagger and /openapi serve the embedded spec
- Shutdown stops HTTP before closing the database
- Expired tokens are deleted with a context that outlives the request
- Files are served with Range support and correct content types; audio
  has no write deadline

Performance
- Migration 000006 adds soundtrack.fingerprint (names, sizes, mtimes) so
  unchanged folders are skipped without reading any files
- Songs are reconciled per soundtrack with one query plus needed writes;
  renames keep play counts
- Moved MUSIC_PATH updates soundtrack and song paths
- .id cleanup only runs for changed soundtracks or a full sync
- Classic random uses one SQL query; Gitea release lookups are cached
  with a timeout

Structure
- internal/config reads all environment variables once
- sqlc emits a Querier interface; backend globals become services
  injected into handlers
- One route registration shared by legacy and /api/v1
- Removed dead code (dbHelper.go, unused middleware, duplicate Gitea
  functions, embedded Swagger UI copy) and lib/pq
- templ and swag pinned as go tools

internal/server/server.go

@@ -1,125 +1,133 @@
 package server
 
 import (
+	"context"
+	"errors"
 	"fmt"
-	"os"
-	"strconv"
+	"net/http"
 	"time"
 
 	"music-server/internal/backend"
+	"music-server/internal/config"
 	"music-server/internal/db"
+	"music-server/internal/db/repository"
 	"music-server/internal/logging"
-	"net/http"
 
 	"go.uber.org/zap"
 )
 
-type Server struct {
-	port              int
-	db                *db.Database
-	tokenHandler      *TokenHandler
-	statisticsHandler *StatisticsHandler
-	httpServer        *http.Server
+// Database is the database connection used by the server.
+type Database interface {
+	HealthChecker
+	Close()
 }
 
-var (
-	musicPath      = os.Getenv("MUSIC_PATH")
-	charactersPath = os.Getenv("CHARACTERS_PATH")
-	logLevel       = os.Getenv("LOG_LEVEL")
-	logJSON        = os.Getenv("LOG_JSON") == "true"
-)
+type Server struct {
+	cfg        config.Config
+	db         Database
+	q          repository.Querier
+	music      *backend.MusicService
+	sync       *backend.SyncService
+	characters *backend.CharacterService
+	releases   *backend.ReleaseService
+	stats      *backend.StatisticsService
+	search     *backend.SearchCache
+	httpServer *http.Server
+}
 
-// NewServerInstance creates a new Server instance with all dependencies initialized.
-// Use this for dependency injection and proper lifecycle management.
-func NewServerInstance() *Server {
-	// Re-read environment variables at server creation time (not at package import time)
-	// This allows tests to override environment variables
-	host := os.Getenv("DB_HOST")
-	dbPort := os.Getenv("DB_PORT")
-	dbName := os.Getenv("DB_NAME")
-	username := os.Getenv("DB_USERNAME")
-	password := os.Getenv("DB_PASSWORD")
-
-	// Initialize logger
-	currentLogLevel := logLevel
-	if currentLogLevel == "" {
-		currentLogLevel = "info"
-	}
-	logging.Init(currentLogLevel, logJSON)
-
-	logger := logging.GetLogger()
-
-	port, _ := strconv.Atoi(os.Getenv("PORT"))
-
-	// Validate required environment variables
-	if host == "" || dbPort == "" || username == "" || password == "" || dbName == "" || musicPath == "" || charactersPath == "" {
-		logging.GetLogger().Fatal("Invalid settings - missing required environment variables")
-	}
-
-	// Create database instance
-	database, err := db.NewDatabase(host, dbPort, username, password, dbName)
+// New creates a Server with all services wired up.
+func New(cfg config.Config, q repository.Querier, database Database) (*Server, error) {
+	characters, err := backend.NewCharacterService(cfg.CharactersPath)
 	if err != nil {
-		logging.GetLogger().Fatal("Failed to initialize database", zap.String("error", err.Error()))
+		return nil, fmt.Errorf("characters path: %w", err)
 	}
 
-	// Run migrations using the new method
-	if err := database.RunMigrations(); err != nil {
-		logging.GetLogger().Fatal("Migration failed", zap.String("error", err.Error()))
+	s := &Server{
+		cfg:        cfg,
+		db:         database,
+		q:          q,
+		music:      backend.NewMusicService(q, cfg.SoundCheckPath),
+		characters: characters,
+		releases:   backend.NewReleaseService(cfg.ReleasesURL),
+		stats:      backend.NewStatisticsService(q),
 	}
+	s.search = backend.NewSearchCache(s.music.SoundtrackNames)
+	s.sync = backend.NewSyncService(q, cfg.MusicPath, s.afterSync)
 
-	// Initialize backend package with database pool
-	backend.InitBackend(database.Pool)
-
-	// Initialize token handler with database pool
-	tokenHandler := NewTokenHandler(database.Pool)
-
-	// Initialize statistics handler
-	statisticsHandler := NewStatisticsHandler()
-
-	// Create the server instance
-	appServer := &Server{
-		port:              port,
-		db:                database,
-		tokenHandler:      tokenHandler,
-		statisticsHandler: statisticsHandler,
-	}
-
-	// Create the HTTP server
-	appServer.httpServer = &http.Server{
-		Addr:         fmt.Sprintf(":%d", port),
-		Handler:      appServer.RegisterRoutes(),
+	s.httpServer = &http.Server{
+		Addr:         fmt.Sprintf(":%d", cfg.Port),
+		Handler:      s.RegisterRoutes(),
 		IdleTimeout:  time.Minute,
 		ReadTimeout:  10 * time.Second,
 		WriteTimeout: 30 * time.Second,
 	}
-
-	logger.Info("Starting server",
-		zap.String("host", host),
-		zap.String("dbPort", dbPort),
-		zap.String("username", username),
-		zap.String("dbName", dbName),
-	)
-
-	logger.Info("Paths",
-		zap.String("musicPath", musicPath),
-		zap.String("charactersPath", charactersPath),
-	)
-
-	return appServer
+	return s, nil
 }
 
-// HTTPServer returns the underlying http.Server for serving HTTP requests.
+// afterSync refreshes cached data once a sync has finished.
+func (s *Server) afterSync(ctx context.Context) {
+	if err := s.music.Reset(ctx); err != nil {
+		logging.GetLogger().Error("Failed to reset music after sync", zap.Error(err))
+	}
+	if err := s.search.Reload(ctx); err != nil {
+		logging.GetLogger().Error("Failed to reload search cache after sync", zap.Error(err))
+	}
+}
+
+// NewServerInstance loads the configuration, connects to and migrates the database and creates the Server.
+// It exits the process if any of these steps fail.
+func NewServerInstance() *Server {
+	cfg, err := config.Load()
+	logging.Init(cfg.LogLevel, cfg.LogJSON)
+	logger := logging.GetLogger()
+	if err != nil {
+		logger.Fatal("Invalid settings", zap.Error(err))
+	}
+
+	logger.Info("Starting server",
+		zap.String("host", cfg.DBHost),
+		zap.String("dbPort", cfg.DBPort),
+		zap.String("username", cfg.DBUser),
+		zap.String("dbName", cfg.DBName),
+		zap.String("musicPath", cfg.MusicPath),
+		zap.String("charactersPath", cfg.CharactersPath),
+	)
+
+	ctx := context.Background()
+	database, err := db.NewDatabase(ctx, db.ConnString(cfg.DBHost, cfg.DBPort, cfg.DBUser, cfg.DBPassword, cfg.DBName))
+	if err != nil {
+		logger.Fatal("Failed to initialize database", zap.Error(err))
+	}
+	if err := database.RunMigrations(); err != nil {
+		logger.Fatal("Migration failed", zap.Error(err))
+	}
+
+	s, err := New(cfg, repository.New(database.Pool), database)
+	if err != nil {
+		logger.Fatal("Failed to create server", zap.Error(err))
+	}
+	return s
+}
+
+// ListenAndServe starts the HTTP server. It returns nil after a graceful shutdown.
+func (s *Server) ListenAndServe() error {
+	logging.GetLogger().Info("Server starting", zap.String("address", s.httpServer.Addr))
+	if err := s.httpServer.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
+		return err
+	}
+	return nil
+}
+
+// Shutdown stops accepting requests, waits for running requests and then closes the database.
+func (s *Server) Shutdown(ctx context.Context) error {
+	err := s.httpServer.Shutdown(ctx)
+	s.sync.Wait()
+	s.characters.Close()
+	s.db.Close()
+	return err
+}
+
+// HTTPServer returns the underlying http.Server.
 func (s *Server) HTTPServer() *http.Server {
 	return s.httpServer
 }
-
-// DB returns the database instance for dependency injection.
-func (s *Server) DB() *db.Database {
-	return s.db
-}
-
-// NewServer creates a new HTTP server (deprecated, use NewServerInstance instead).
-// This function is kept for backward compatibility.
-func NewServer() *http.Server {
-	return NewServerInstance().HTTPServer()
-}