From 0e121ead8e5209ee262f532dd1510166b00e46a6 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 20:52:36 +0100 Subject: [PATCH 1/2] feat(images): album covers from my own files - GET and HEAD /albums/{id}/cover serve a JPEG made from the picture embedded in the album's files, or else a cover, folder, front, album or albumart image (jpg, jpeg, png) in the album's folder. ?size=small (300 px) or large (1000 px). The token can be in the query, so an element can use it. - Built the first time it is asked for, scaled, and kept in storage.data_dir (SONDA_DATA_DIR, default "data"); an album with no cover is remembered for a day. A new or changed file of the album, or a full rescan, clears the record. - Nothing is sent anywhere. Pictures are untrusted: files are opened inside the library only (links are not followed), over 20 MB or 16 million pixels are ignored, and what is served is always a JPEG made here. Stored files are 0600. - images table (migration 0013, SQLite and PostgreSQL). - Spec, contract test, README and example config updated. Closes #37 --- .gitignore | 1 + README.md | 4 + cmd/sondad/main.go | 6 + internal/api/http/api_test.go | 3 + internal/api/http/contract_test.go | 32 +++ internal/api/http/covers_test.go | 229 +++++++++++++++ internal/api/http/handlers_covers.go | 65 +++++ internal/api/http/router.go | 10 + internal/api/openapi/openapi.yaml | 103 ++++++- internal/config/config.go | 15 + internal/config/config_test.go | 15 + internal/images/nonblock_other.go | 5 + internal/images/nonblock_unix.go | 8 + internal/images/process.go | 120 ++++++++ internal/images/process_test.go | 162 +++++++++++ internal/images/service.go | 342 ++++++++++++++++++++++ internal/images/service_test.go | 408 +++++++++++++++++++++++++++ internal/storage/images.go | 99 +++++++ internal/storage/images_test.go | 166 +++++++++++ internal/storage/library.go | 11 + internal/storage/storage_test.go | 6 +- migrations/postgres/0013_images.sql | 19 ++ migrations/sqlite/0013_images.sql | 19 ++ sonda.example.toml | 3 + 24 files changed, 1847 insertions(+), 4 deletions(-) create mode 100644 internal/api/http/covers_test.go create mode 100644 internal/api/http/handlers_covers.go create mode 100644 internal/images/nonblock_other.go create mode 100644 internal/images/nonblock_unix.go create mode 100644 internal/images/process.go create mode 100644 internal/images/process_test.go create mode 100644 internal/images/service.go create mode 100644 internal/images/service_test.go create mode 100644 internal/storage/images.go create mode 100644 internal/storage/images_test.go create mode 100644 migrations/postgres/0013_images.sql create mode 100644 migrations/sqlite/0013_images.sql diff --git a/.gitignore b/.gitignore index 4af4b6b..04bae5e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ sonda.toml *.db *.db-wal *.db-shm +/data/ # AI agent instruction files: never published (Codeberg EULA) agent.md diff --git a/README.md b/README.md index ebc5070..d9e4a7a 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr - **Listening history.** Clients report explicit `play`, `complete` and `skip` events. An event counts as a listen when it is `complete`, or when it was played for at least 20 seconds (`listening.min_listen_seconds`); the rule is applied when the history is read, so changing it re-reads the past. You can read your own history, with a `counted` flag on every event. It stays in your database and is never sent anywhere. - **Your taste.** `GET /me/taste` shows what Sonda has learned from your own listening: the artists you like and the kinds of music (tags) they have in common. A complete listen counts for more than a short one, a skip counts against the artist, and older listens weigh less (they halve every 90 days, `taste.half_life_days`; only the last ten half-lives are read). It is worked out on every request from data already in your database; nothing is sent to any provider. - **Discover.** `GET /discover` suggests artists you may like, in your library or not, each with a score from 0 to 1 and the parts it is made of: how close it is to the artists you like (affinity), how close its tags are to yours (genre), what your listening says about it (preference) and a bonus for what you have not played (discovery). The weights are in `[scoring]` in the config. A part with no data is left out and the rest rescaled, and every answer says which seeds led to each suggestion. It starts from the artists you name with `?seed=`, or, only if you turned on `discover_from_listening`, from the artists you play most. It needs Last.fm to be switched on to ask for anything new: when Last.fm is off and a seed's similar artists are not stored yet, the answer says `disabled` (what was stored earlier is still used). See [External providers](#external-providers). +- **Album covers.** `GET /albums/{id}/cover` serves the cover of an album from your own files: the picture embedded in them, or else a `cover`, `folder`, `front`, `album` or `albumart` image in the album's folder. It is built the first time it is asked for, scaled (`?size=small` is 300 pixels, `large` 1000) and kept in the data folder (`storage.data_dir`, you can delete it: covers are built again). Nothing is sent anywhere. It also takes `?access_token=`, so an `` element can use it. - **Wishlist and "not interested".** `PUT /wishlist/{artist}` puts an artist on your wishlist (`GET /wishlist` lists it, `DELETE` takes it off), and `POST /discover/{artist}/dismiss` hides an artist from your Discover for good (`DELETE` brings it back, `GET /discover/dismissed` lists them). An artist is wished or dismissed, never both, and both lists are yours alone. Discover marks the wished artists it shows (`wishlisted`) and never suggests a dismissed one. Nothing is downloaded or sent anywhere: the wishlist is a list for you, and for a download client you may set up later. An artist that only Last.fm named is kept while you have it marked (your lists still show it, but other users cannot see that it exists), and goes with the rest of Last.fm's data if an admin removes Last.fm's data. Removing MusicBrainz's data does not touch it. - **Your own settings.** `GET` and `PATCH /me/settings` hold choices that belong to you, not to the server. Everyone starts private: `discover_from_listening` is off, so this setting never sends your listening to a provider. When you turn it on, Discover may start from the artists you listen to most, and their names are sent to Last.fm (only if an admin switched it on). What Last.fm answers is kept in the shared database like any other lookup, so another local user can see, from `retrieved_at` of `GET /artists/{id}/similar`, that someone looked up an artist, but not who. - **Tags.** `GET /artists/{id}/tags` shows what Last.fm and MusicBrainz say kind of music an artist plays, each with its own weights, and the genres of the artist's own files, read offline. See [External providers](#external-providers). @@ -65,6 +66,7 @@ Precedence is: built-in defaults, then the file, then environment variables. An | `auth.refresh_ttl_hours` | | `720` | Lifetime of a refresh token (30 days). | | `listening.min_listen_seconds` | | `20` | A play counts as a listen after this long (1 to 3600), or when it is `complete`. | | `taste.half_life_days` | | `90` | After this many days a listen weighs half as much when learning your taste (1 to 3650). | +| `storage.data_dir` | `SONDA_DATA_DIR` | `data` | Where Sonda keeps the files it makes (covers). They are built from your music, so they need no backup. | | `scoring.weight_affinity`, `weight_genre`, `weight_preference`, `weight_discovery` | | `0.40`, `0.25`, `0.25`, `0.10` | The weights of the parts of a Discover score (0 to 10 each, not all zero). Only their proportions matter. | Libraries and the external providers are not in the config: you set them up through the API (see the demo and [External providers](#external-providers)). @@ -233,6 +235,7 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er | signed in | `POST /listens` | Record a `play`, `complete` or `skip`; the answer says whether it counts as a listen. | | signed in | `GET /listens` | Your own history, newest first, with `counted` per event. Query: `limit`, `offset`, `counted=true`. | | signed in | `GET /discover` | Artists you may like, with a score and its parts. Query: `seed` (an artist id, up to 5 times), `limit` (default 20, max 30), `in_library=true\|false`. | +| signed in | `GET`, `HEAD /albums/{id}/cover` | The cover of an album, a JPEG made from your own files. Query: `size=small\|large`. Also accepts `?access_token=`. | | signed in | `GET /wishlist`, `PUT /wishlist/{id}`, `DELETE /wishlist/{id}` | Your wishlist: list it (query `limit`, `offset`), add an artist, take one off. | | signed in | `GET /discover/dismissed`, `POST /discover/{id}/dismiss`, `DELETE /discover/{id}/dismiss` | The artists you are not interested in: list them, dismiss one, bring it back. | | signed in | `GET /me/taste` | The artists and tags Sonda learned you like, from your own listening. Query: `limit` (default 20, max 50). | @@ -293,6 +296,7 @@ internal/listening/ listen events internal/taste/ what the listener likes, learned from the listening history internal/discover/ the score of an artist you may like, and the suggestions internal/feedback/ the wishlist and the artists a user is not interested in +internal/images/ covers made from the pictures in the user's own files internal/usersettings/ the settings that belong to one user internal/storage/ SQLite and PostgreSQL through bun, the repositories internal/streaming/ opening a track's file safely diff --git a/cmd/sondad/main.go b/cmd/sondad/main.go index e9bc48f..cdf6af1 100644 --- a/cmd/sondad/main.go +++ b/cmd/sondad/main.go @@ -21,6 +21,7 @@ import ( "codeberg.org/squidd/sonda/internal/discover" "codeberg.org/squidd/sonda/internal/discovery" "codeberg.org/squidd/sonda/internal/feedback" + "codeberg.org/squidd/sonda/internal/images" "codeberg.org/squidd/sonda/internal/library" "codeberg.org/squidd/sonda/internal/listening" "codeberg.org/squidd/sonda/internal/providers" @@ -145,6 +146,10 @@ func run() error { tasteService := taste.NewService(tasteRepo, taste.Options{MinListen: cfg.Listening.MinListen(), HalfLife: cfg.Taste.HalfLife()}) userSettings := usersettings.NewService(storage.NewUserSettingsRepo(db)) feedbacks := feedback.NewService(storage.NewFeedbackRepo(db)) + if err := os.MkdirAll(cfg.Storage.DataDir, 0o700); err != nil { + return fmt.Errorf("create the data folder: %w", err) + } + imageRepo := storage.NewImageRepo(db) weights := discover.Weights{ Affinity: cfg.Scoring.WeightAffinity, Genre: cfg.Scoring.WeightGenre, Preference: cfg.Scoring.WeightPreference, Discovery: cfg.Scoring.WeightDiscovery, @@ -164,6 +169,7 @@ func run() error { Taste: tasteService, Discover: discover.NewService(tasteService, discoveries, tags, tasteRepo, userSettings, feedbacks, weights), Feedback: feedbacks, + Images: images.NewService(cfg.Storage.DataDir, imageRepo, imageRepo), Settings: userSettings, Streams: streaming.NewService(libraryRepo), }) diff --git a/internal/api/http/api_test.go b/internal/api/http/api_test.go index 1cafac1..8a45935 100644 --- a/internal/api/http/api_test.go +++ b/internal/api/http/api_test.go @@ -19,6 +19,7 @@ import ( "codeberg.org/squidd/sonda/internal/discover" "codeberg.org/squidd/sonda/internal/discovery" "codeberg.org/squidd/sonda/internal/feedback" + "codeberg.org/squidd/sonda/internal/images" "codeberg.org/squidd/sonda/internal/library" "codeberg.org/squidd/sonda/internal/listening" "codeberg.org/squidd/sonda/internal/providers" @@ -96,6 +97,8 @@ func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun } feedbackSvc := feedback.NewService(storage.NewFeedbackRepo(db)) deps.Feedback = feedbackSvc + imageRepo := storage.NewImageRepo(db) + deps.Images = images.NewService(filepath.Join(t.TempDir(), "data"), imageRepo, imageRepo) mutate(&deps, db) // Built from the final services, so a test that swaps one gets a Discover that uses it. if deps.Discover == nil { diff --git a/internal/api/http/contract_test.go b/internal/api/http/contract_test.go index 316ad3f..805b27e 100644 --- a/internal/api/http/contract_test.go +++ b/internal/api/http/contract_test.go @@ -4,6 +4,8 @@ import ( "bytes" "context" "encoding/json" + "image" + "image/png" "io" "mime" "net/http" @@ -143,6 +145,14 @@ func newContract(t *testing.T) *contract { t.Fatal(err) } } + // A picture in the folder of the music, for the cover of its album. + var pic bytes.Buffer + if err := png.Encode(&pic, image.NewRGBA(image.Rect(0, 0, 40, 30))); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(music, "cover.png"), pic.Bytes(), 0o644); err != nil { + t.Fatal(err) + } return &contract{lastfm: lf, t: t, h: h, db: db, reader: reader, router: router, seen: map[string]bool{}, music: music} } @@ -526,6 +536,28 @@ func TestResponsesMatchTheSpec(t *testing.T) { c.expect(c.call("GET", "/me/taste?limit=-1", token, nil), 400, "taste with a bad limit", "invalid_input") c.expect(c.call("GET", "/me/taste?limit=abc", token, nil), 400, "taste with a limit that is not a number", "invalid_input") + // ---- covers ---- + cover := "/albums/" + albumID + "/cover" + big := c.call("GET", cover, token, nil) + if big.Code != 200 || big.Header().Get("Content-Type") != "image/jpeg" { + t.Fatalf("cover: %d %s", big.Code, big.Header().Get("Content-Type")) + } + if sm := c.call("GET", cover+"?size=small", token, nil); sm.Code != 200 { + t.Fatalf("small cover: %d", sm.Code) + } + c.expect(c.call("GET", cover+"?size=huge", token, nil), 400, "a cover of a size that does not exist", "invalid_input") + c.expect(c.call("GET", "/albums/999/cover", token, nil), 404, "the cover of an unknown album", "album_not_found") + c.expect(c.call("GET", cover, "", nil), 401, "a cover without a token", "unauthorized") + if rec := c.call("GET", cover+"?access_token="+token, "", nil); rec.Code != 200 { + t.Fatalf("cover with the token in the query: %d", rec.Code) + } + if rec := c.call("GET", cover, token, nil, "If-None-Match", big.Header().Get("ETag")); rec.Code != 304 { + t.Fatalf("cover If-None-Match: %d", rec.Code) + } + if rec := c.call("HEAD", cover, token, nil); rec.Code != 200 { + t.Fatalf("cover HEAD: %d", rec.Code) + } + // ---- discover ---- c.expect(c.call("GET", "/discover", token, nil), 400, "discover with no seed and no permission", "seed_required") found := c.expect(c.call("GET", "/discover?seed="+artistID+"&limit=5", token, nil), 200, "discover from a named seed") diff --git a/internal/api/http/covers_test.go b/internal/api/http/covers_test.go new file mode 100644 index 0000000..f23af58 --- /dev/null +++ b/internal/api/http/covers_test.go @@ -0,0 +1,229 @@ +package httpapi + +import ( + "bytes" + "encoding/json" + "image" + "image/color" + "image/jpeg" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "testing" + + "github.com/uptrace/bun" + + "codeberg.org/squidd/sonda/internal/images" + "codeberg.org/squidd/sonda/internal/library" + "codeberg.org/squidd/sonda/internal/storage" +) + +type coversEnv struct { + h http.Handler + db *bun.DB + token string + root string + data string + withArt int64 // an album with a cover.jpg in its folder + without int64 // an album with no picture at all +} + +func testJPEG(t *testing.T, w, h int, c color.Color) []byte { + t.Helper() + img := image.NewRGBA(image.Rect(0, 0, w, h)) + for y := 0; y < h; y++ { + for x := 0; x < w; x++ { + img.Set(x, y, c) + } + } + var b bytes.Buffer + if err := jpeg.Encode(&b, img, nil); err != nil { + t.Fatal(err) + } + return b.Bytes() +} + +func newCoversEnv(t *testing.T) *coversEnv { + t.Helper() + e := &coversEnv{root: t.TempDir(), data: filepath.Join(t.TempDir(), "data")} + for _, dir := range []string{"With Art", "Without"} { + if err := os.MkdirAll(filepath.Join(e.root, dir), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(e.root, dir, "01.mp3"), []byte("not audio"), 0o644); err != nil { + t.Fatal(err) + } + } + if err := os.WriteFile(filepath.Join(e.root, "With Art", "cover.jpg"), testJPEG(t, 1500, 1200, color.RGBA{200, 30, 30, 255}), 0o644); err != nil { + t.Fatal(err) + } + e.h, e.db = newTestEnvDB(t, func(d *Deps, db *bun.DB) { + repo := storage.NewImageRepo(db) + d.Images = images.NewService(e.data, repo, repo) + }) + e.token = registerAndLogin(t, e.h) + + lib := storage.NewLibraryRepo(e.db) + l, err := lib.CreateLibrary(t.Context(), "music", e.root) + if err != nil { + t.Fatal(err) + } + for _, name := range []string{"With Art", "Without"} { + f := library.ParsedFile{ + FileInfo: library.FileInfo{RelPath: name + "/01.mp3", Size: 9, MTimeUnix: 1}, + Metadata: library.Metadata{ + Tags: library.Tags{Title: name + " song", Album: name, AlbumArtist: "Band", Artists: []string{"Band"}}, + Properties: library.Properties{Format: "mpeg", DurationMs: 1000}, + }, + } + if _, err := lib.SaveFile(t.Context(), l.ID, f, 0); err != nil { + t.Fatal(err) + } + } + e.withArt, e.without = e.album(t, "With Art"), e.album(t, "Without") + return e +} + +func (e *coversEnv) album(t *testing.T, title string) int64 { + t.Helper() + var id int64 + if err := e.db.QueryRow("SELECT id FROM albums WHERE title = ?", title).Scan(&id); err != nil { + t.Fatal(err) + } + return id +} + +func (e *coversEnv) get(method, path, token string, header ...string) *httptest.ResponseRecorder { + req := httptest.NewRequest(method, "/api/v1"+path, nil) + if token != "" { + req.Header.Set("Authorization", "Bearer "+token) + } + for i := 0; i+1 < len(header); i += 2 { + req.Header.Set(header[i], header[i+1]) + } + rec := httptest.NewRecorder() + e.h.ServeHTTP(rec, req) + return rec +} + +func TestCoverNeedsASignedInUserAndAcceptsTheTokenInTheQuery(t *testing.T) { + e := newCoversEnv(t) + path := "/albums/" + id(e.withArt) + "/cover" + if rec := e.get("GET", path, ""); rec.Code != http.StatusUnauthorized { + t.Errorf("no token: %d", rec.Code) + } + // An element cannot send a header. + if rec := e.get("GET", path+"?access_token="+e.token, ""); rec.Code != http.StatusOK { + t.Errorf("token in the query: %d %s", rec.Code, rec.Body.String()) + } + if rec := e.get("GET", path+"?access_token=wrong", ""); rec.Code != http.StatusUnauthorized { + t.Errorf("a bad token in the query: %d", rec.Code) + } +} + +func TestCoverIsAJPEGInTheSizeAsked(t *testing.T) { + e := newCoversEnv(t) + path := "/albums/" + id(e.withArt) + "/cover" + for query, width := range map[string]int{"": 1000, "?size=large": 1000, "?size=small": 300} { + rec := e.get("GET", path+query, e.token) + if rec.Code != http.StatusOK { + t.Fatalf("%q: %d %s", query, rec.Code, rec.Body.String()) + } + if ct := rec.Header().Get("Content-Type"); ct != "image/jpeg" { + t.Errorf("%q: content type %q", query, ct) + } + cfg, format, err := image.DecodeConfig(bytes.NewReader(rec.Body.Bytes())) + if err != nil || format != "jpeg" || cfg.Width != width || cfg.Height != width*1200/1500 { + t.Errorf("%q: %v %s %v, want a jpeg %d wide, same shape as the original", query, cfg, format, err, width) + } + if rec.Header().Get("X-Content-Type-Options") != "nosniff" { + t.Errorf("%q: no nosniff", query) + } + if cc := rec.Header().Get("Cache-Control"); cc != "private, max-age=3600" { + t.Errorf("%q: cache-control %q, want it private", query, cc) + } + } +} + +func TestCoverIsCachedWithAnETag(t *testing.T) { + e := newCoversEnv(t) + path := "/albums/" + id(e.withArt) + "/cover" + first := e.get("GET", path, e.token) + etag := first.Header().Get("ETag") + if etag == "" || etag[0] != '"' || first.Header().Get("Last-Modified") == "" { + t.Fatalf("etag %q, last-modified %q", etag, first.Header().Get("Last-Modified")) + } + if rec := e.get("GET", path, e.token, "If-None-Match", etag); rec.Code != http.StatusNotModified || rec.Body.Len() != 0 { + t.Errorf("If-None-Match: %d with %d bytes", rec.Code, rec.Body.Len()) + } + if small := e.get("GET", path+"?size=small", e.token); small.Header().Get("ETag") == etag { + t.Error("the small and the large picture have the same etag") + } + if rec := e.get("HEAD", path, e.token); rec.Code != http.StatusOK || rec.Body.Len() != 0 || rec.Header().Get("Content-Length") == "" { + t.Errorf("HEAD: %d, %d bytes, length %q", rec.Code, rec.Body.Len(), rec.Header().Get("Content-Length")) + } + if rec := e.get("GET", path, e.token, "Range", "bytes=0-9"); rec.Code != http.StatusPartialContent || rec.Body.Len() != 10 { + t.Errorf("Range: %d, %d bytes", rec.Code, rec.Body.Len()) + } +} + +func TestCoverErrors(t *testing.T) { + e := newCoversEnv(t) + for name, tt := range map[string]struct { + path string + code int + err string + }{ + "no picture": {"/albums/" + id(e.without) + "/cover", 404, "cover_not_found"}, + "unknown album": {"/albums/99999/cover", 404, "album_not_found"}, + "bad id": {"/albums/abc/cover", 400, "invalid_input"}, + "zero id": {"/albums/0/cover", 400, "invalid_input"}, + "bad size": {"/albums/" + id(e.withArt) + "/cover?size=huge", 400, "invalid_input"}, + "size twice": {"/albums/" + id(e.withArt) + "/cover?size=small&size=large", 400, "invalid_input"}, + "size in capital": {"/albums/" + id(e.withArt) + "/cover?size=Small", 400, "invalid_input"}, + } { + rec := e.get("GET", tt.path, e.token) + var body struct { + Error struct{ Code string } `json:"error"` + } + _ = json.Unmarshal(rec.Body.Bytes(), &body) + if rec.Code != tt.code || body.Error.Code != tt.err { + t.Errorf("%s: %d %s, want %d %s", name, rec.Code, rec.Body.String(), tt.code, tt.err) + } + } +} + +// A picture is looked for again when a file of the album changes. +func TestCoverIsBuiltAgainAfterTheFilesChange(t *testing.T) { + e := newCoversEnv(t) + path := "/albums/" + id(e.without) + "/cover" + if rec := e.get("GET", path, e.token); rec.Code != http.StatusNotFound { + t.Fatalf("before: %d", rec.Code) + } + if err := os.WriteFile(filepath.Join(e.root, "Without", "folder.jpg"), testJPEG(t, 500, 500, color.White), 0o644); err != nil { + t.Fatal(err) + } + if rec := e.get("GET", path, e.token); rec.Code != http.StatusNotFound { + t.Fatalf("the absence is remembered for a day: %d", rec.Code) + } + // What the scanner does when a file of the album changes. + lib := storage.NewLibraryRepo(e.db) + var libID, fileID int64 + if err := e.db.QueryRow("SELECT library_id, id FROM audio_files WHERE rel_path = 'Without/01.mp3'").Scan(&libID, &fileID); err != nil { + t.Fatal(err) + } + f := library.ParsedFile{ + FileInfo: library.FileInfo{RelPath: "Without/01.mp3", Size: 9, MTimeUnix: 2}, + Metadata: library.Metadata{ + Tags: library.Tags{Title: "Without song", Album: "Without", AlbumArtist: "Band", Artists: []string{"Band"}}, + Properties: library.Properties{Format: "mpeg", DurationMs: 1000}, + }, + } + if _, err := lib.SaveFile(t.Context(), libID, f, fileID); err != nil { + t.Fatal(err) + } + if rec := e.get("GET", path, e.token); rec.Code != http.StatusOK { + t.Errorf("after the file changed: %d %s", rec.Code, rec.Body.String()) + } +} diff --git a/internal/api/http/handlers_covers.go b/internal/api/http/handlers_covers.go new file mode 100644 index 0000000..3e0556a --- /dev/null +++ b/internal/api/http/handlers_covers.go @@ -0,0 +1,65 @@ +package httpapi + +import ( + "context" + "errors" + "net/http" + + "github.com/gin-gonic/gin" + + "codeberg.org/squidd/sonda/internal/images" +) + +type coverHandlers struct{ svc coverService } + +// sizeParam reads ?size=: absent means large, otherwise exactly "small" or "large" once. +func sizeParam(c *gin.Context) (images.Size, bool) { + values := c.QueryArray("size") + switch { + case len(values) == 0: + return images.Large, true + case len(values) == 1 && values[0] == string(images.Small): + return images.Small, true + case len(values) == 1 && values[0] == string(images.Large): + return images.Large, true + } + writeError(c, http.StatusBadRequest, "invalid_input", "size must be small or large") + return "", false +} + +// album serves the cover of an album: a JPEG made from the picture in the album's own +// files, built on the first request. It never contacts anybody. +func (h *coverHandlers) album(c *gin.Context) { + id, ok := pathID(c) + if !ok { + return + } + size, ok := sizeParam(c) + if !ok { + return + } + cover, err := h.svc.AlbumCover(c.Request.Context(), id, size) + switch { + case errors.Is(err, images.ErrAlbumNotFound): + writeError(c, http.StatusNotFound, "album_not_found", "no such album") + return + case errors.Is(err, images.ErrNoCover): + writeError(c, http.StatusNotFound, "cover_not_found", "this album has no cover") + return + case errors.Is(err, context.Canceled): + c.AbortWithStatus(statusClientClosed) // the client left; nobody is waiting + return + case err != nil: + _ = c.Error(err) + writeError(c, http.StatusInternalServerError, "internal", "internal error") + return + } + defer cover.File.Close() + + hdr := c.Writer.Header() + hdr.Set("Content-Type", "image/jpeg") + hdr.Set("ETag", `"`+cover.ETag+`"`) + hdr.Set("Cache-Control", "private, max-age=3600") // it is the listener's own library + hdr.Set("X-Content-Type-Options", "nosniff") + http.ServeContent(c.Writer, c.Request, "cover.jpg", cover.ModTime, cover.File) +} diff --git a/internal/api/http/router.go b/internal/api/http/router.go index 6ddf5ae..ac0b47f 100644 --- a/internal/api/http/router.go +++ b/internal/api/http/router.go @@ -15,6 +15,7 @@ import ( "codeberg.org/squidd/sonda/internal/discover" "codeberg.org/squidd/sonda/internal/discovery" "codeberg.org/squidd/sonda/internal/feedback" + "codeberg.org/squidd/sonda/internal/images" "codeberg.org/squidd/sonda/internal/library" "codeberg.org/squidd/sonda/internal/listening" "codeberg.org/squidd/sonda/internal/providers" @@ -84,6 +85,10 @@ type feedbackService interface { List(ctx context.Context, userID int64, kind feedback.Kind, p feedback.Page) (feedback.Listing, error) } +type coverService interface { + AlbumCover(ctx context.Context, albumID int64, size images.Size) (*images.Cover, error) +} + type tasteService interface { Taste(ctx context.Context, userID int64, limit int) (taste.Profile, error) } @@ -124,6 +129,7 @@ type Deps struct { Taste tasteService Discover discoverService Feedback feedbackService + Images coverService Settings userSettingsService Streams streamService } @@ -189,6 +195,10 @@ func NewRouter(d Deps) *gin.Engine { audio := v1.Group("", requireAuth(d.Tokens, d.Auth, true)) audio.GET("/tracks/:id/stream", st.stream) audio.HEAD("/tracks/:id/stream", st.stream) + // An element cannot send headers either, so covers take the token the same way. + cv := &coverHandlers{svc: d.Images} + audio.GET("/albums/:id/cover", cv.album) + audio.HEAD("/albums/:id/cover", cv.album) // Admins only. admin := protected.Group("", requireAdmin(d.Auth)) diff --git a/internal/api/openapi/openapi.yaml b/internal/api/openapi/openapi.yaml index ba2a036..1734f58 100644 --- a/internal/api/openapi/openapi.yaml +++ b/internal/api/openapi/openapi.yaml @@ -974,6 +974,101 @@ paths: application/json: schema: {$ref: '#/components/schemas/Error'} + /albums/{id}/cover: + parameters: + - {$ref: '#/components/parameters/Id'} + get: + tags: [Catalog] + operationId: getAlbumCover + summary: The cover of an album + description: | + A JPEG made from the picture in the album's own files: the picture embedded in one of + its first files, or else a `cover`, `folder`, `front`, `album` or `albumart` image + (`.jpg`, `.jpeg` or `.png`, any case) in the album's folder, in that order of names. It + is built the first time it is asked for (that request can take a moment), scaled to fit + and saved in the server's data folder, and served from there afterwards. It never + contacts anybody. Pictures that are too big (over 20 MB or 16 million pixels) or are not + pictures are ignored, and only files inside the library are read. + + An album with no picture answers `cover_not_found`, and the server does not look again + for a day; a new or changed file of the album, or a full rescan, makes it look again. + The picture is `private` for an hour in caches and has an `ETag`: send it back as + `If-None-Match`. + + An `` element cannot send headers, so, like the stream, this also accepts the access + token as the `access_token` query parameter. A header, when present, always wins. + security: + - bearerAuth: [] + - streamQueryToken: [] + parameters: + - name: size + in: query + description: "`small` (300 pixels at most on the longest side) or `large` (1000). Large when absent. Never enlarged: a small picture stays as it is." + schema: {type: string, enum: [small, large], default: large} + - name: If-None-Match + in: header + required: false + schema: {type: string} + - name: Range + in: header + required: false + schema: {type: string} + responses: + '200': + description: The cover. + headers: + ETag: {$ref: '#/components/headers/ETag'} + Cache-Control: {$ref: '#/components/headers/CacheControl'} + Content-Length: {$ref: '#/components/headers/ContentLength'} + Last-Modified: {$ref: '#/components/headers/LastModified'} + content: + image/jpeg: + schema: {type: string, format: binary} + '206': + description: The requested byte range of the cover. + headers: + Content-Range: + schema: {type: string} + content: + image/jpeg: + schema: {type: string, format: binary} + '304': {description: Not modified since the `ETag` sent.} + '400': {$ref: '#/components/responses/InvalidInput'} + '401': {$ref: '#/components/responses/Unauthorized'} + '404': + description: No such album (`album_not_found`), or it has no cover (`cover_not_found`). + content: + application/json: + schema: {$ref: '#/components/schemas/Error'} + head: + tags: [Catalog] + operationId: headAlbumCover + summary: Headers of a cover + description: Same as `GET`, without the body. + security: + - bearerAuth: [] + - streamQueryToken: [] + parameters: + - name: size + in: query + schema: {type: string, enum: [small, large], default: large} + - name: If-None-Match + in: header + required: false + schema: {type: string} + responses: + '200': + description: Headers of the cover. + headers: + ETag: {$ref: '#/components/headers/ETag'} + Cache-Control: {$ref: '#/components/headers/CacheControl'} + Content-Length: {$ref: '#/components/headers/ContentLength'} + Last-Modified: {$ref: '#/components/headers/LastModified'} + '304': {description: Not modified since the `ETag` sent.} + '400': {$ref: '#/components/responses/InvalidInput'} + '401': {$ref: '#/components/responses/Unauthorized'} + '404': {description: "No such album, or it has no cover."} + /tracks: get: tags: [Catalog] @@ -1348,7 +1443,7 @@ components: type: apiKey in: query name: access_token - description: The same access token, for stream URLs used by an `