- New /api/v1 endpoints: GET /soundtracks, /soundtracks/{uuid},
/songs/{uuid} and /songs/{uuid}/file (streams the song, Range support,
locked during sync)
- UUIDs added to every response with soundtracks or songs: queue info and
list (SoundtrackUuid, SongUuid) and statistics (soundtrack_uuid,
song_uuid). Existing fields stay for backward compatibility
- Play counts and broken-song removal use song UUIDs instead of
soundtrack ID + song name, so songs with the same name are counted
separately
- Statistics return an empty song list for soundtracks without songs
instead of a single empty entry
- The legacy .id file cleanup stays until Phase 4 (#31)
Closes#29
- Unit tests, integration tests and the Docker build check run in
parallel on branches and pull requests
- Integration tests run on every push instead of only manually
- Branch builds only build amd64 and check the arm64 cross-compile in the
test job; both platforms are built and pushed only for version tags,
after all tests pass
- Docker layers cached through the runner cache, Go module and build
caches mounted in the Dockerfile
- A newer push to the same branch cancels the running pipeline
- Build (main, develop): vet and unit tests, then a linux/amd64 and
linux/arm64 image build without pushing
- Publish (version branches): same tests, then build and push both
platforms
- Integration tests (manual): run the testcontainers suite
- Dockerfile cross-compiles Go for the target platform (amd64/arm64
without emulation), uses templ pinned in go.mod, runs as uid 1000 on
alpine and lets FRONTEND_IMAGE pin the frontend version
- justfile: tools via go tool, `test` (unit) and `test-integration`
(uses the active docker context), no hardcoded paths, no tailwind or
frontend recipes
- Removed app.yaml, init.sh, tailwind.config.js and the tracked .idea
folder
- Unit tests use an in-memory fake database (internal/testutil/fakedb),
temp folders and httptest; `go test ./...` needs no Docker or env vars
- Integration tests (build tag "integration") start PostgreSQL with
testcontainers: migrations step by step, SQL dumps (skipped if
missing) and a full sync against a real database
- Removed tests that only checked copies of the logic or had empty
bodies, the broken root integration_test.go, compose.test.yaml and
.env.test with hardcoded paths
- testMusic MP3s replaced with tiny placeholders (sync never decodes
audio), 194 MB -> 168 KB
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
- Add NOT NULL constraints to soundtrack.uuid, song.uuid, and song.soundtrack_uuid
- Add corresponding DROP NOT NULL in down migration
- Update header comments to reflect combined Phase 1 & 2
This eliminates the need for a separate migration 000007 while maintaining
proper rollback capability. The NOT NULL constraints are added AFTER
all UUID backfills are complete, ensuring data integrity.
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Add id serial4 PK to song table (was composite PK)
- Update queries to use soundtrack_id + path
- Add UUID columns to soundtrack and song (nullable)
- Add migration tracking table
TODO: Run sqlc generate, then create backfill migration (000008)
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Enhanced TODO comment to clearly mark Dbpool and Ctx as DEPRECATED
- Direct developers to use Database struct from database.go instead
- Migration test already includes manual data insertion (5 games, 8 songs)
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- TestStatisticsEndpoints: tests /api/v1/statistics/summary endpoint
- TestPartialMigrationThenSyncThenComplete: tests migration + sync workflow
- insertTestData: helper to insert 5 soundtracks with 8 songs
- getTestToken: helper to get auth token for tests
- Updated other test files to use FindAllSoundtracks instead of FindAllGames
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Update internal/db/test_helpers.go to use Database struct instead of globals
- Update internal/server/test_helpers.go to use TestDatabase.Pool
- Add TODO comment to old Dbpool/Ctx globals in dbHelper.go
- Remove db.Testf() usage from production code (kept for deprecated /dbtest endpoint)
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Create middleware/deprecation.go with DeprecationMiddleware
- Adds Warning and Deprecation headers to old endpoints
- Apply middleware to all non-/api/v1 routes:
/version, /dbtest, /health, /character*, /download*, /sync/*,
/music/*
- Message: 'Deprecated: This endpoint is deprecated. Use /api/v1/ endpoints instead.'
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Add Database struct in internal/db/database.go with Pool, Ctx, and RunMigrations()
- Update server.go to use Database struct with NewServerInstance()
- Add backend.go with InitBackend(), BackendRepo(), BackendCtx(), BackendPool()
- Update music.go and sync.go to use BackendRepo() and BackendCtx() instead of db.Dbpool/db.Ctx
- Update token_handler.go to accept pool parameter
- Update routes.go to use s.db.Pool for middleware
- Update cmd/main.go to use NewServerInstance() and HTTPServer()
- Update test_helpers.go to initialize backend with test database
- Update test files to use backend.BackendPool() and backend.BackendCtx()
Benefits:
- Easier to mock database for unit tests
- Follows Go best practices (dependency injection)
- Better architecture with explicit dependencies
- RunMigrations() replaces old Migrate_db() function
Note: Global db.Dbpool and db.Ctx still exist in dbHelper.go for backward compatibility
with test_helpers.go, but production code no longer uses them.
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Add Database struct in internal/db/database.go with Pool, Ctx, and RunMigrations()
- Update server.go to use Database struct with NewServerInstance()
- Add backend.go with InitBackend(), BackendRepo(), BackendCtx(), BackendPool()
- Update music.go and sync.go to use BackendRepo() and BackendCtx() instead of db.Dbpool/db.Ctx
- Update token_handler.go to accept pool parameter
- Update routes.go to use s.db.Pool for middleware
- Update cmd/main.go to use NewServerInstance() and HTTPServer()
- Update test_helpers.go to initialize backend with test database
- Update test files to use backend.BackendPool() and backend.BackendCtx()
Benefits:
- Easier to mock database for unit tests
- Follows Go best practices (dependency injection)
- Better architecture with explicit dependencies
- RunMigrations() replaces old Migrate_db() function
Note: Global db.Dbpool and db.Ctx still exist in dbHelper.go for backward compatibility
with test_helpers.go, but production code no longer uses them.
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
- Split IndexHandler into HealthHandler, VersionHandler, and CharacterHandler
- Rename index.go to version.go in backend
- Change VersionData.Changelog from string to []string
- Add changelog entries for issues #16-#23
- Remove TestDB function and related code
- Fix import ordering in several files
Closes#21, #22
References #16, #17, #18, #19, #20, #23
Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
Sansan
