diff --git a/README.md b/README.md index 1fdde7c..81dd740 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,11 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr - **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). - **Similar artists.** With Last.fm switched on, `GET /artists/{id}/similar` lists artists similar to an artist, and says which of them you already have. See [External providers](#external-providers). Without it, Sonda makes no outbound network requests at all. -- **Friends (federation).** Two Sonda servers can become friends, and the listeners of one can read what the other chose to share. `PUT /federation` (admin) turns federation on, which is off by default, and gives this server a name and a public address (`https`; plain `http` only on a network of your own); the server then makes its own Ed25519 key, kept in the database and never returned. `POST /federation/invites` makes an invite that works once and expires in 24 hours (only a hash of its code is kept). The other admin uses it with `POST /federation/friends`: that server is asked to accept this one, the key it answers with must be the one named in the invite, and the friend waits as `outgoing` until the first admin approves it with `POST /federation/friends/{id}/approve` (`POST /federation/friends/{id}/check` lets the waiting side find out). Either side can remove a friend with `DELETE /federation/friends/{id}`. Nothing is shared until an admin turns on `shared` for a library (`PATCH /libraries/{id}`). A friend's server then reads, with requests signed by its key (the method, the path and query, a date, a nonce and the hash of the body), the routes under `/peer`: the artists, albums and tracks that have a file in a shared library, their covers once they are built, and the audio itself with `Range`. A friend never sees a path, a library id, a listen, a taste or a user, never makes this server build a cover or ask a provider, and has a few streams at a time and a number of KiB a second to share (`max_streams`, `max_kib_per_sec`); the admin sees the last requests it made (`GET /federation/requests`, the route and the size, never what was searched for). Sharing a library lets friends play it and, in practice, copy its files. A listener browses the music of a friend with `GET /friends` (the names of the friends whose friendship both admins agreed to, never an address or a key) and `GET /friends/{friend}/artists`, `albums` and `tracks` with `q`, `limit` and `offset`, and one item at a time: this server asks the friend with a signed request, checks the shape of the answer and passes it on, and nothing is kept; the ids are the friend's own. A friend that cannot be reached or no longer takes this server for a friend is told in words. The web app has a Friends section for it, shown only when there is a friend to browse. Playing a friend's music and showing its covers is not there yet. The admin area has a Federation section for all of it. +- **Friends (federation).** Two Sonda servers can become friends, and the listeners of one can read what the other chose to share. `PUT /federation` (admin) turns federation on, which is off by default, and gives this server a name and a public address (`https`; plain `http` only on a network of your own); the server then makes its own Ed25519 key, kept in the database and never returned. `POST /federation/invites` makes an invite that works once and expires in 24 hours (only a hash of its code is kept). The other admin uses it with `POST /federation/friends`: that server is asked to accept this one, the key it answers with must be the one named in the invite, and the friend waits as `outgoing` until the first admin approves it with `POST /federation/friends/{id}/approve` (`POST /federation/friends/{id}/check` lets the waiting side find out). Either side can remove a friend with `DELETE /federation/friends/{id}`. Nothing is shared until an admin turns on `shared` for a library (`PATCH /libraries/{id}`). A friend's server then reads, with requests signed by its key (the method, the path and query, a date, a nonce and the hash of the body), the routes under `/peer`: the artists, albums and tracks that have a file in a shared library, their covers once they are built, and the audio itself with `Range`. A friend never sees a path, a library id, a listen, a taste or a user, never makes this server build a cover or ask a provider, and has a few streams at a time and a number of KiB a second to share (`max_streams`, `max_kib_per_sec`); the admin sees the last requests it made (`GET /federation/requests`, the route and the size, never what was searched for). Sharing a library lets friends play it and, in practice, copy its files. A listener browses the music of a friend with `GET /friends` (the names of the friends whose friendship both admins agreed to, never an address or a key) and `GET /friends/{friend}/artists`, `albums` and `tracks` with `q`, `limit` and `offset`, and one item at a time: this server asks the friend with a signed request, checks the shape of the answer and passes it on, and nothing is kept; the ids are the friend's own. A friend that cannot be reached or no longer takes this server for a friend is told in words. The web app has a Friends section for it, shown only when there is a friend to browse. A listener plays it with `GET /friends/{friend}/tracks/{id}/stream` and sees its covers with `GET /friends/{friend}/albums/{id}/cover`, which accept the access token in the query like the local ones: this server asks the friend with a signed request, forwards `Range` and the conditional headers, and passes on only audio (or a JPEG for a cover) with `Content-Type`, `Content-Length`, `Content-Range`, `Accept-Ranges`, `Last-Modified` and `ETag`, so the friend sees this server and never the listener, and a friend cannot make this server serve anything else. A friend's track plays in the same player as the others but is never reported as a listen and does not feed taste. The admin area has a Federation section for all of it. ## What is not there yet -Playing a friend's music and showing its covers (federation), radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client is built into the binary (see [Web app](#web-app)), and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs. +Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client is built into the binary (see [Web app](#web-app)), and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs. ## Requirements diff --git a/internal/api/http/contract_test.go b/internal/api/http/contract_test.go index e094313..a693c5e 100644 --- a/internal/api/http/contract_test.go +++ b/internal/api/http/contract_test.go @@ -245,8 +245,8 @@ func (c *contract) validate(req *http.Request, payload []byte, rec *httptest.Res // The library skips HEAD and redirects, and cannot read audio or YAML. // Those are checked by hand: the status above, and the content type here. skipBody := req.Method == http.MethodHead || route.Path == "/openapi.yaml" || - (rec.Code >= 300 && rec.Code < 400) || ((route.Path == "/tracks/{id}/stream" || route.Path == "/peer/tracks/{id}/stream") && rec.Code/100 == 2) - if skipBody && documented != nil && documented.Value != nil && rec.Code/100 == 2 && req.Method != http.MethodHead && (route.Path == "/tracks/{id}/stream" || route.Path == "/peer/tracks/{id}/stream") { + (rec.Code >= 300 && rec.Code < 400) || ((route.Path == "/tracks/{id}/stream" || route.Path == "/peer/tracks/{id}/stream" || route.Path == "/friends/{friend}/tracks/{id}/stream") && rec.Code/100 == 2) + if skipBody && documented != nil && documented.Value != nil && rec.Code/100 == 2 && req.Method != http.MethodHead && (route.Path == "/tracks/{id}/stream" || route.Path == "/peer/tracks/{id}/stream" || route.Path == "/friends/{friend}/tracks/{id}/stream") { mediaType, _, err := mime.ParseMediaType(rec.Header().Get("Content-Type")) if err != nil || documented.Value.Content.Get(mediaType) == nil { c.t.Errorf("%s -> %d: Content-Type %q is not one the spec lists", where, rec.Code, rec.Header().Get("Content-Type")) @@ -1328,6 +1328,28 @@ func (c *contract) friends(t *testing.T, token string) { c.expect(c.call("GET", "/friends/999999/tracks", token, nil), 404, "a friend that is not there", "friend_not_found") c.expect(c.call("GET", base+"/tracks?limit=abc", token, nil), 400, "a limit that is no number", "invalid_input") + // Playing it and seeing its cover, through this server. + stream := base + "/tracks/" + trackID + "/stream" + c.expect(c.call("GET", stream, "", nil), 401, "a friend's stream without a login", "unauthorized") + if rec := c.call("GET", stream, token, nil); rec.Code != 200 { + t.Fatalf("a friend's stream: %d %s", rec.Code, rec.Body.String()) + } + if rec := c.call("GET", stream, token, nil, "Range", "bytes=0-9"); rec.Code != 206 { + t.Fatalf("a friend's stream, a range: %d", rec.Code) + } + c.expect(c.call("GET", base+"/tracks/999999/stream", token, nil), 404, "the stream of a track the friend does not have", "track_not_found") + cover := base + "/albums/" + albumID + "/cover" + c.expect(c.call("GET", cover, token, nil), 404, "a cover that is not built there yet", "cover_not_found") + var theirAlbum int64 + _ = p.db.QueryRow("SELECT id FROM albums WHERE title = 'Shared Album'").Scan(&theirAlbum) + if rec := p.serveAs(t, "GET", "/api/v1/albums/"+strconv.FormatInt(theirAlbum, 10)+"/cover"); rec.Code != 200 { + t.Fatalf("the cover on the friend's server: %d", rec.Code) + } + if rec := c.call("GET", cover, token, nil); rec.Code != 200 || rec.Header().Get("Content-Type") != "image/jpeg" { + t.Fatalf("a friend's cover: %d %q", rec.Code, rec.Header().Get("Content-Type")) + } + c.expect(c.call("GET", cover+"?size=huge", token, nil), 400, "a cover of a size that does not exist", "invalid_input") + // The friend removes this server: the listener is told, and nothing is kept. p.admin1(t, "DELETE", "/federation/friends/"+idOf(theirs[0].(map[string]any)), nil) c.expect(c.call("GET", base+"/tracks", token, nil), 409, "a friend that removed this server", "friend_gone") diff --git a/internal/api/http/friends_test.go b/internal/api/http/friends_test.go index 85c8aed..a44a10c 100644 --- a/internal/api/http/friends_test.go +++ b/internal/api/http/friends_test.go @@ -1,6 +1,7 @@ package httpapi import ( + "bytes" "context" "net/http" "net/http/httptest" @@ -8,6 +9,7 @@ import ( "strconv" "strings" "testing" + "time" "github.com/uptrace/bun" @@ -265,3 +267,174 @@ func TestAnAnswerThatIsNotACataloguePageIsNotPassedOn(t *testing.T) { } } } + +// listen asks this server (C) for something as its listener would: with a header, or with the token in the +// query, as an