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/middleware/rate_limit.go

@@ -2,98 +2,30 @@ package middleware
 
 import (
 	"net/http"
-	"sync"
 	"time"
 
 	"music-server/internal/logging"
 
 	"github.com/labstack/echo/v5"
+	echoMiddleware "github.com/labstack/echo/v5/middleware"
 	"go.uber.org/zap"
 )
 
-// RateLimiter implements a simple IP-based rate limiter
-type RateLimiter struct {
-	visits map[string]*Visit
-	mu     sync.Mutex
-	limit  int           // requests per window
-	window time.Duration // time window
-}
-
-type Visit struct {
-	count     int
-	firstSeen time.Time
-}
-
-// NewRateLimiter creates a new rate limiter
-func NewRateLimiter(limit int, window time.Duration) *RateLimiter {
-	rl := &RateLimiter{
-		visits: make(map[string]*Visit),
-		limit:  limit,
-		window: window,
+// RateLimit allows each client IP limit requests per window, with bursts up to limit.
+func RateLimit(limit int, window time.Duration) echo.MiddlewareFunc {
+	config := echoMiddleware.DefaultRateLimiterConfig
+	config.Store = echoMiddleware.NewRateLimiterMemoryStoreWithConfig(echoMiddleware.RateLimiterMemoryStoreConfig{
+		Rate:      float64(limit) / window.Seconds(),
+		Burst:     limit,
+		ExpiresIn: window,
+	})
+	config.DenyHandler = func(c *echo.Context, identifier string, err error) error {
+		logging.GetLogger().Warn("Rate limit exceeded",
+			zap.String("ip", identifier),
+			zap.String("path", c.Request().URL.Path))
+		return c.JSON(http.StatusTooManyRequests, map[string]string{
+			"error": "Rate limit exceeded. Please try again later.",
+		})
 	}
-
-	// Start cleanup goroutine
-	go rl.cleanup()
-	return rl
+	return echoMiddleware.RateLimiterWithConfig(config)
 }
-
-// cleanup periodically removes old entries
-func (rl *RateLimiter) cleanup() {
-	for {
-		time.Sleep(rl.window)
-		rl.mu.Lock()
-		now := time.Now()
-		for ip, visit := range rl.visits {
-			if now.Sub(visit.firstSeen) > rl.window {
-				delete(rl.visits, ip)
-			}
-		}
-		rl.mu.Unlock()
-	}
-}
-
-// RateLimitMiddleware returns an Echo middleware for rate limiting
-func RateLimitMiddleware(rl *RateLimiter) echo.MiddlewareFunc {
-	return func(next echo.HandlerFunc) echo.HandlerFunc {
-		return func(c *echo.Context) error {
-			ip := c.RealIP()
-
-			rl.mu.Lock()
-			defer rl.mu.Unlock()
-
-			visit, exists := rl.visits[ip]
-			now := time.Now()
-
-			if !exists {
-				// First visit from this IP
-				rl.visits[ip] = &Visit{
-					count:     1,
-					firstSeen: now,
-				}
-				return next(c)
-			}
-
-			// Check if window has expired
-			if now.Sub(visit.firstSeen) > rl.window {
-				// Reset for new window
-				visit.count = 1
-				visit.firstSeen = now
-				return next(c)
-			}
-
-			// Check if limit exceeded
-			if visit.count >= rl.limit {
-				logging.GetLogger().Warn("Rate limit exceeded",
-					zap.String("ip", ip),
-					zap.String("path", c.Request().URL.Path))
-				return c.JSON(http.StatusTooManyRequests, map[string]string{
-					"error": "Rate limit exceeded. Please try again later.",
-				})
-			}
-
-			// Increment count
-			visit.count++
-			return next(c)
-		}
-	}
-}

internal/server/middleware/sync_check.go

@@ -1,22 +1,22 @@
 package middleware
 
 import (
-	"music-server/internal/backend"
-	"music-server/internal/logging"
 	"net/http"
 
+	"music-server/internal/logging"
+
 	"github.com/labstack/echo/v5"
 )
 
-// SyncCheckMiddleware blocks requests when syncing is in progress.
-// It returns HTTP 423 Locked with a standard message.
-// This middleware should be applied to handlers that cannot execute during sync.
-func SyncCheckMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
-	return func(c *echo.Context) error {
-		if backend.Syncing {
-			logging.GetLogger().Info("Syncing is in progress - request blocked")
-			return c.JSON(http.StatusLocked, "Syncing is in progress")
+// SyncCheck blocks requests with HTTP 423 Locked while a sync is in progress.
+func SyncCheck(isSyncing func() bool) echo.MiddlewareFunc {
+	return func(next echo.HandlerFunc) echo.HandlerFunc {
+		return func(c *echo.Context) error {
+			if isSyncing() {
+				logging.GetLogger().Info("Syncing is in progress - request blocked")
+				return c.JSON(http.StatusLocked, "Syncing is in progress")
+			}
+			return next(c)
 		}
-		return next(c)
 	}
 }

internal/server/middleware/token_auth.go

@@ -1,87 +1,62 @@
 package middleware
 
 import (
+	"context"
 	"net/http"
-	"os"
 	"strings"
 	"time"
 
 	"music-server/internal/db/repository"
 	"music-server/internal/logging"
 
-	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/labstack/echo/v5"
 	"go.uber.org/zap"
 )
 
-// TokenAuthMiddleware returns an Echo middleware that validates session tokens
-func TokenAuthMiddleware(pool *pgxpool.Pool) echo.MiddlewareFunc {
+// BearerToken extracts the token from an "Authorization: Bearer <token>" header.
+func BearerToken(c *echo.Context) (string, bool) {
+	token, ok := strings.CutPrefix(c.Request().Header.Get("Authorization"), "Bearer ")
+	return token, ok && token != "" && !strings.Contains(token, " ")
+}
+
+// TokenAuth validates session tokens. When disabled is true all requests are let through.
+func TokenAuth(q repository.Querier, disabled bool) echo.MiddlewareFunc {
 	return func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c *echo.Context) error {
-			// Session auth disable bypass - allow all requests through without token validation
-			disableSessionAuth := os.Getenv("DISABLE_SESSION_AUTH") == "true"
-			if disableSessionAuth {
-				logging.GetLogger().Debug("Session auth disabled - bypassing token authentication",
-					zap.String("path", c.Request().URL.Path),
-					zap.String("ip", c.RealIP()))
+			if disabled {
 				return next(c)
 			}
 
-			// Extract token from Authorization header
-			authHeader := c.Request().Header.Get("Authorization")
-			if authHeader == "" {
+			if c.Request().Header.Get("Authorization") == "" {
 				return c.JSON(http.StatusUnauthorized, map[string]string{"error": "Authorization header required"})
 			}
-
-			// Bearer token format
-			parts := strings.Split(authHeader, " ")
-			if len(parts) != 2 || parts[0] != "Bearer" {
+			token, ok := BearerToken(c)
+			if !ok {
 				return c.JSON(http.StatusUnauthorized, map[string]string{"error": "Invalid authorization format. Use: Bearer <token>"})
 			}
 
-			token := parts[1]
-			queries := repository.New(pool)
-			session, err := queries.GetSession(c.Request().Context(), token)
+			ctx := c.Request().Context()
+			session, err := q.GetSession(ctx, token)
 			if err != nil {
 				logging.GetLogger().Warn("Invalid token attempt",
-					zap.String("token", token),
 					zap.String("ip", c.RealIP()),
 					zap.String("error", err.Error()),
 				)
 				return c.JSON(http.StatusUnauthorized, map[string]string{"error": "Invalid or expired token"})
 			}
 
-			// Check if token is expired
 			if time.Now().After(session.ExpiresAt.Time) {
-				// Clean up expired session in background
-				go func() {
-					queries.DeleteSession(c.Request().Context(), token)
-				}()
+				// Clean up in the background with a context that outlives the request.
+				go func(ctx context.Context) {
+					if err := q.DeleteSession(ctx, token); err != nil {
+						logging.GetLogger().Error("Failed to delete expired session", zap.Error(err))
+					}
+				}(context.WithoutCancel(ctx))
 				return c.JSON(http.StatusUnauthorized, map[string]string{"error": "Token expired"})
 			}
 
-			// Add session to request context for potential use by handlers
 			c.Set("session", session)
-
 			return next(c)
 		}
 	}
 }
-
-// TokenIPCheckMiddleware checks if the request IP matches the session IP
-func TokenIPCheckMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
-	return func(c *echo.Context) error {
-		sessionVal := c.Get("session")
-		if sessionVal == nil {
-			return c.JSON(http.StatusUnauthorized, map[string]string{"error": "No session in context"})
-		}
-		session := sessionVal.(repository.Session)
-		if session.IpAddress != c.RealIP() {
-			logging.GetLogger().Warn("Token IP mismatch",
-				zap.String("token_ip", session.IpAddress),
-				zap.String("request_ip", c.RealIP()),
-			)
-		}
-		return next(c)
-	}
-}