Merge pull request 'feat(streaming): stream tracks with HTTP Range support' (#8) from feat/track-streaming into main

This commit is contained in:
squidd 2026-11-11 13:01:31 +01:00
commit 99de521130
16 changed files with 948 additions and 11 deletions

View file

@ -20,6 +20,7 @@ import (
"codeberg.org/squidd/sonda/internal/library"
"codeberg.org/squidd/sonda/internal/listening"
"codeberg.org/squidd/sonda/internal/storage"
"codeberg.org/squidd/sonda/internal/streaming"
"codeberg.org/squidd/sonda/migrations"
)
@ -97,6 +98,7 @@ func run() error {
Tokens: tokens,
Listening: listening.NewService(storage.NewListeningRepo(db)),
Scan: scanControl{ctx: ctx, m: scans},
Streams: streaming.NewService(libraryRepo, cfg.Library.Roots),
})
// No WriteTimeout: audio streaming (later) needs long responses.

View file

@ -17,6 +17,7 @@ import (
"codeberg.org/squidd/sonda/internal/auth"
"codeberg.org/squidd/sonda/internal/listening"
"codeberg.org/squidd/sonda/internal/storage"
"codeberg.org/squidd/sonda/internal/streaming"
"codeberg.org/squidd/sonda/migrations"
)
@ -31,6 +32,12 @@ func newTestAPI(t *testing.T) http.Handler {
}
func newTestAPIWithScan(t *testing.T, scan scanService) http.Handler {
t.Helper()
return newTestAPIWith(t, func(d *Deps) { d.Scan = scan })
}
// newTestAPIWith wires real services and lets a test replace parts of Deps.
func newTestAPIWith(t *testing.T, mutate func(*Deps)) http.Handler {
t.Helper()
db, err := storage.Open(storage.DriverSQLite, filepath.Join(t.TempDir(), "api.db"))
if err != nil {
@ -49,13 +56,23 @@ func newTestAPIWithScan(t *testing.T, scan scanService) http.Handler {
}
tokens := auth.NewTokenIssuer(secret, time.Hour)
return NewRouter(Deps{
deps := Deps{
Logger: zap.NewNop(),
Auth: auth.NewService(storage.NewUserRepo(db), storage.NewRefreshRepo(db), tokens, 24*time.Hour),
Tokens: tokens,
Listening: listening.NewService(storage.NewListeningRepo(db)),
Scan: scan,
})
Scan: &fakeScan{},
Streams: streaming.NewService(noFiles{}, nil),
}
mutate(&deps)
return NewRouter(deps)
}
// noFiles is a streaming source with nothing to play.
type noFiles struct{}
func (noFiles) PlayableFile(context.Context, int64) (streaming.File, error) {
return streaming.File{}, streaming.ErrNotFound
}
type resp struct {

View file

@ -2,6 +2,7 @@ package httpapi
import (
"net/http"
"net/http/httptest"
"strconv"
"testing"
)
@ -320,3 +321,34 @@ func TestAdminCanStartScan(t *testing.T) {
t.Errorf("starts = %d", scan.starts)
}
}
// Only "Authorization: Bearer <token>" is accepted. A bare token must not pass.
func TestAuthorizationHeaderMustUseTheBearerScheme(t *testing.T) {
h := newTestAPI(t)
tok := registerAndLogin(t, h)
for name, header := range map[string]string{
"bare token": tok,
"basic scheme": "Basic " + tok,
"lowercase": "bearer " + tok,
"token scheme": "Token " + tok,
"empty bearer": "Bearer ",
"bearer no gap": "Bearer" + tok,
} {
req := httptest.NewRequest("GET", "/api/v1/auth/me", nil)
req.Header.Set("Authorization", header)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
if rec.Code != http.StatusUnauthorized {
t.Errorf("%s: status %d, want 401", name, rec.Code)
}
}
req := httptest.NewRequest("GET", "/api/v1/auth/me", nil)
req.Header.Set("Authorization", "Bearer "+tok)
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
if rec.Code != http.StatusOK {
t.Errorf("proper Bearer header: %d", rec.Code)
}
}

View file

@ -0,0 +1,51 @@
package httpapi
import (
"errors"
"net/http"
"github.com/gin-gonic/gin"
"codeberg.org/squidd/sonda/internal/streaming"
)
type streamHandlers struct{ svc streamService }
// stream serves a track's original file. http.ServeContent does the protocol
// work: Range (206, 416), HEAD, Content-Length, conditional requests, and it
// stops copying when the client goes away.
func (h *streamHandlers) stream(c *gin.Context) {
id, ok := pathID(c)
if !ok {
return
}
st, err := h.svc.Open(c.Request.Context(), id)
switch {
case errors.Is(err, streaming.ErrNotFound):
writeError(c, http.StatusNotFound, "track_not_found", "no playable file for this track")
return
case errors.Is(err, streaming.ErrFileMissing):
writeError(c, http.StatusNotFound, "file_missing", "the audio file is not available")
return
case errors.Is(err, streaming.ErrUnsafePath):
// A stored path that leaves the library is a data problem, not the
// client's: log it, but say no more than "not available".
_ = c.Error(err)
writeError(c, http.StatusNotFound, "file_missing", "the audio file is not available")
return
case err != nil:
_ = c.Error(err)
writeError(c, http.StatusInternalServerError, "internal", "internal error")
return
}
defer st.Close()
hdr := c.Writer.Header()
hdr.Set("Content-Type", st.ContentType)
hdr.Set("X-Content-Type-Options", "nosniff")
// The URL may carry the access token: never leak it through Referer.
hdr.Set("Referrer-Policy", "no-referrer")
hdr.Set("Cache-Control", "private, no-cache")
http.ServeContent(c.Writer, c.Request, st.Name, st.ModTime, st.File)
}

View file

@ -32,12 +32,17 @@ func requestLog(logger *zap.Logger) gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
c.Next()
logger.Info("http request",
fields := []zap.Field{
zap.String("method", c.Request.Method),
zap.String("path", c.Request.URL.Path),
zap.Int("status", c.Writer.Status()),
zap.Duration("latency", time.Since(start)),
)
}
if last := c.Errors.Last(); last != nil {
// Internal errors are hidden from the client; keep them in the log.
fields = append(fields, zap.String("error", last.Error()))
}
logger.Info("http request", fields...)
}
}
@ -73,12 +78,25 @@ func requireAdmin(users userLookup) gin.HandlerFunc {
}
}
// requireAuth accepts only "Authorization: Bearer <jwt>".
func requireAuth(tokens tokenParser) gin.HandlerFunc {
// requireAuth checks the access token. It reads "Authorization: Bearer <jwt>";
// when allowQuery is true and the header is absent it also accepts the
// access_token query parameter. That is for routes loaded by an <audio> element,
// which cannot send headers. A header that is present always wins, so a bad
// header is never rescued by a query token.
func requireAuth(tokens tokenParser, allowQuery bool) gin.HandlerFunc {
return func(c *gin.Context) {
header := c.GetHeader("Authorization")
token, ok := strings.CutPrefix(header, "Bearer ")
if !ok || token == "" {
token := ""
if header := c.GetHeader("Authorization"); header != "" {
var ok bool
if token, ok = strings.CutPrefix(header, "Bearer "); !ok {
// Any other scheme, or a bare token, is not accepted.
writeError(c, http.StatusUnauthorized, "unauthorized", "missing bearer token")
return
}
} else if allowQuery {
token = c.Query("access_token")
}
if token == "" {
writeError(c, http.StatusUnauthorized, "unauthorized", "missing bearer token")
return
}

View file

@ -13,6 +13,7 @@ import (
"codeberg.org/squidd/sonda/internal/auth"
"codeberg.org/squidd/sonda/internal/library"
"codeberg.org/squidd/sonda/internal/listening"
"codeberg.org/squidd/sonda/internal/streaming"
)
// maxBodyBytes bounds every request body.
@ -40,6 +41,10 @@ type listenService interface {
Record(ctx context.Context, e listening.Event) (bool, error)
}
type streamService interface {
Open(ctx context.Context, trackID int64) (*streaming.Stream, error)
}
type scanService interface {
Start() error
Status() library.Status
@ -52,6 +57,7 @@ type Deps struct {
Tokens tokenParser
Listening listenService
Scan scanService
Streams streamService
}
// NewRouter builds the gin engine with all routes.
@ -71,7 +77,7 @@ func NewRouter(d Deps) *gin.Engine {
v1.POST("/auth/logout", a.logout)
// Any signed-in user.
protected := v1.Group("", requireAuth(d.Tokens))
protected := v1.Group("", requireAuth(d.Tokens, false))
protected.GET("/auth/me", a.me)
protected.POST("/auth/password", a.changePassword)
l := &listenHandlers{svc: d.Listening}
@ -80,6 +86,13 @@ func NewRouter(d Deps) *gin.Engine {
lib := &libraryHandlers{scan: d.Scan}
protected.GET("/library/scan", lib.scanStatus)
// Audio loaded by an <audio> element cannot send headers, so this route also
// takes the access token as a query parameter. It never records a listen.
st := &streamHandlers{svc: d.Streams}
audio := v1.Group("", requireAuth(d.Tokens, true))
audio.GET("/tracks/:id/stream", st.stream)
audio.HEAD("/tracks/:id/stream", st.stream)
// Admins only.
admin := protected.Group("", requireAdmin(d.Auth))
admin.POST("/library/scan", lib.startScan)

View file

@ -0,0 +1,256 @@
package httpapi
import (
"bytes"
"context"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strconv"
"testing"
"time"
"codeberg.org/squidd/sonda/internal/streaming"
)
type mapSource map[int64]streaming.File
func (m mapSource) PlayableFile(_ context.Context, id int64) (streaming.File, error) {
f, ok := m[id]
if !ok {
return streaming.File{}, streaming.ErrNotFound
}
return f, nil
}
// streamFixture serves track 1 (a 1000-byte mp3), track 2 (file gone from
// disk) and track 3 (a path that escapes the root).
type streamFixture struct {
h http.Handler
token string
data []byte
}
func newStreamFixture(t *testing.T) streamFixture {
t.Helper()
root := t.TempDir()
data := make([]byte, 1000)
for i := range data {
data[i] = byte(i % 251)
}
if err := os.WriteFile(filepath.Join(root, "song.mp3"), data, 0o644); err != nil {
t.Fatal(err)
}
src := mapSource{
1: {Root: root, RelPath: "song.mp3"},
2: {Root: root, RelPath: "gone.mp3"},
3: {Root: root, RelPath: "../escape.mp3"},
}
h := newTestAPIWith(t, func(d *Deps) { d.Streams = streaming.NewService(src, []string{root}) })
return streamFixture{h: h, token: registerAndLogin(t, h), data: data}
}
func (f streamFixture) get(t *testing.T, method, path string, headers map[string]string) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequest(method, path, nil)
for k, v := range headers {
req.Header.Set(k, v)
}
rec := httptest.NewRecorder()
f.h.ServeHTTP(rec, req)
return rec
}
func (f streamFixture) auth() map[string]string {
return map[string]string{"Authorization": "Bearer " + f.token}
}
func TestStreamRequiresAuth(t *testing.T) {
f := newStreamFixture(t)
for _, method := range []string{"GET", "HEAD"} {
if rec := f.get(t, method, "/api/v1/tracks/1/stream", nil); rec.Code != http.StatusUnauthorized {
t.Errorf("%s without token: %d", method, rec.Code)
}
}
if rec := f.get(t, "GET", "/api/v1/tracks/1/stream?access_token=garbage", nil); rec.Code != http.StatusUnauthorized {
t.Errorf("garbage query token: %d", rec.Code)
}
// The header wins: a bad header is not rescued by a good query token.
rec := f.get(t, "GET", "/api/v1/tracks/1/stream?access_token="+f.token, map[string]string{"Authorization": "Bearer garbage"})
if rec.Code != http.StatusUnauthorized {
t.Errorf("bad header with good query token: %d", rec.Code)
}
}
// A header that is present but not a Bearer token is not rescued by the query.
func TestStreamIgnoresQueryTokenWhenAnyAuthorizationHeaderIsPresent(t *testing.T) {
f := newStreamFixture(t)
for _, header := range []string{f.token, "Basic " + f.token, "Token x"} {
rec := f.get(t, "GET", "/api/v1/tracks/1/stream?access_token="+f.token, map[string]string{"Authorization": header})
if rec.Code != http.StatusUnauthorized {
t.Errorf("Authorization %.12q... with a valid query token: %d, want 401", header, rec.Code)
}
}
}
func TestStreamAcceptsHeaderAndQueryToken(t *testing.T) {
f := newStreamFixture(t)
if rec := f.get(t, "GET", "/api/v1/tracks/1/stream", f.auth()); rec.Code != http.StatusOK {
t.Errorf("header token: %d", rec.Code)
}
if rec := f.get(t, "GET", "/api/v1/tracks/1/stream?access_token="+f.token, nil); rec.Code != http.StatusOK {
t.Errorf("query token: %d", rec.Code)
}
}
func TestQueryTokenIsAcceptedOnlyForStreaming(t *testing.T) {
f := newStreamFixture(t)
for _, path := range []string{"/api/v1/auth/me", "/api/v1/users", "/api/v1/library/scan"} {
if rec := f.get(t, "GET", path+"?access_token="+f.token, nil); rec.Code != http.StatusUnauthorized {
t.Errorf("%s accepted a token in the URL: %d", path, rec.Code)
}
}
}
func TestStreamFullFile(t *testing.T) {
f := newStreamFixture(t)
rec := f.get(t, "GET", "/api/v1/tracks/1/stream", f.auth())
if rec.Code != http.StatusOK || !bytes.Equal(rec.Body.Bytes(), f.data) {
t.Fatalf("status %d, %d bytes", rec.Code, rec.Body.Len())
}
want := map[string]string{
"Content-Type": "audio/mpeg",
"Content-Length": "1000",
"Accept-Ranges": "bytes",
"X-Content-Type-Options": "nosniff",
"Referrer-Policy": "no-referrer",
"Cache-Control": "private, no-cache",
}
for k, v := range want {
if got := rec.Header().Get(k); got != v {
t.Errorf("%s = %q, want %q", k, got, v)
}
}
if rec.Header().Get("Last-Modified") == "" {
t.Error("Last-Modified missing")
}
}
func TestStreamHead(t *testing.T) {
f := newStreamFixture(t)
rec := f.get(t, "HEAD", "/api/v1/tracks/1/stream", f.auth())
if rec.Code != http.StatusOK || rec.Body.Len() != 0 {
t.Fatalf("HEAD: %d with a %d byte body", rec.Code, rec.Body.Len())
}
if rec.Header().Get("Content-Length") != "1000" || rec.Header().Get("Content-Type") != "audio/mpeg" ||
rec.Header().Get("Accept-Ranges") != "bytes" {
t.Errorf("HEAD headers = %v", rec.Header())
}
}
func TestStreamRanges(t *testing.T) {
f := newStreamFixture(t)
tests := []struct {
name, header string
first, last int
}{
{"first bytes", "bytes=0-99", 0, 99},
{"middle", "bytes=100-199", 100, 199},
{"open ended", "bytes=900-", 900, 999},
{"suffix", "bytes=-50", 950, 999},
{"single byte", "bytes=5-5", 5, 5},
{"end beyond the file is clamped", "bytes=990-5000", 990, 999},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
h := f.auth()
h["Range"] = tt.header
rec := f.get(t, "GET", "/api/v1/tracks/1/stream", h)
if rec.Code != http.StatusPartialContent {
t.Fatalf("status = %d, want 206", rec.Code)
}
wantRange := "bytes " + strconv.Itoa(tt.first) + "-" + strconv.Itoa(tt.last) + "/1000"
if got := rec.Header().Get("Content-Range"); got != wantRange {
t.Errorf("Content-Range = %q, want %q", got, wantRange)
}
if got := rec.Header().Get("Content-Length"); got != strconv.Itoa(tt.last-tt.first+1) {
t.Errorf("Content-Length = %q", got)
}
if !bytes.Equal(rec.Body.Bytes(), f.data[tt.first:tt.last+1]) {
t.Error("body does not match the requested bytes")
}
})
}
}
func TestStreamRangeOnHeadHasNoBody(t *testing.T) {
f := newStreamFixture(t)
h := f.auth()
h["Range"] = "bytes=0-9"
rec := f.get(t, "HEAD", "/api/v1/tracks/1/stream", h)
if rec.Code != http.StatusPartialContent || rec.Body.Len() != 0 || rec.Header().Get("Content-Length") != "10" {
t.Fatalf("HEAD with Range: %d, body %d, length %q", rec.Code, rec.Body.Len(), rec.Header().Get("Content-Length"))
}
}
func TestStreamUnsatisfiableRange(t *testing.T) {
f := newStreamFixture(t)
// Well-formed but outside the file: 416 and the real size in Content-Range.
for _, rng := range []string{"bytes=2000-3000", "bytes=1000-"} {
h := f.auth()
h["Range"] = rng
rec := f.get(t, "GET", "/api/v1/tracks/1/stream", h)
if rec.Code != http.StatusRequestedRangeNotSatisfiable {
t.Errorf("Range %q: status %d, want 416", rng, rec.Code)
continue
}
if got := rec.Header().Get("Content-Range"); got != "bytes */1000" {
t.Errorf("Range %q: Content-Range = %q, want %q", rng, got, "bytes */1000")
}
}
// Malformed: also refused with 416, and no audio is sent.
for _, rng := range []string{"bytes=abc", "bytes=9-1"} {
h := f.auth()
h["Range"] = rng
rec := f.get(t, "GET", "/api/v1/tracks/1/stream", h)
if rec.Code != http.StatusRequestedRangeNotSatisfiable || bytes.Contains(rec.Body.Bytes(), f.data[:50]) {
t.Errorf("Range %q: status %d", rng, rec.Code)
}
}
}
func TestStreamConditionalRequest(t *testing.T) {
f := newStreamFixture(t)
h := f.auth()
h["If-Modified-Since"] = time.Now().Add(time.Hour).UTC().Format(http.TimeFormat)
rec := f.get(t, "GET", "/api/v1/tracks/1/stream", h)
if rec.Code != http.StatusNotModified || rec.Body.Len() != 0 {
t.Fatalf("If-Modified-Since in the future: %d with %d bytes", rec.Code, rec.Body.Len())
}
}
func TestStreamErrors(t *testing.T) {
f := newStreamFixture(t)
tests := []struct {
name, path string
status int
code string
}{
{"unknown track", "/api/v1/tracks/99/stream", http.StatusNotFound, "track_not_found"},
{"file gone from disk", "/api/v1/tracks/2/stream", http.StatusNotFound, "file_missing"},
{"path escaping the root", "/api/v1/tracks/3/stream", http.StatusNotFound, "file_missing"},
{"id is not a number", "/api/v1/tracks/abc/stream", http.StatusBadRequest, "invalid_input"},
{"id is zero", "/api/v1/tracks/0/stream", http.StatusBadRequest, "invalid_input"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
r := do(t, f.h, "GET", tt.path, f.token, nil)
if r.Code != tt.status || errCode(r) != tt.code {
t.Fatalf("%d %v, want %d %s", r.Code, r.Body, tt.status, tt.code)
}
})
}
}

View file

@ -8,6 +8,7 @@ import (
"errors"
"fmt"
"os"
"path/filepath"
"time"
"github.com/pelletier/go-toml/v2"
@ -172,6 +173,12 @@ func (c Config) Validate() error {
errs = append(errs, errors.New("library.roots needs at least one directory"))
}
for _, root := range c.Library.Roots {
if !filepath.IsAbs(root) {
// Roots are stored with every indexed file and used to serve it:
// a relative one would depend on the directory sondad starts in.
errs = append(errs, fmt.Errorf("library.roots: %q must be an absolute path", root))
continue
}
info, err := os.Stat(root)
switch {
case err != nil:

View file

@ -127,6 +127,7 @@ func TestValidate(t *testing.T) {
{"ok", func(c *Config) {}, ""},
{"no roots", func(c *Config) { c.Library.Roots = nil }, "library.roots"},
{"root missing", func(c *Config) { c.Library.Roots = []string{filepath.Join(good, "nope")} }, "library.roots"},
{"relative root", func(c *Config) { c.Library.Roots = []string{"music"} }, "absolute"},
{"root is file", func(c *Config) { c.Library.Roots = []string{file} }, "not a directory"},
{"bad env", func(c *Config) { c.Log.Env = "staging" }, "log.env"},
{"empty listen", func(c *Config) { c.Server.Listen = "" }, "server.listen"},

View file

@ -11,6 +11,7 @@ import (
"github.com/uptrace/bun"
"codeberg.org/squidd/sonda/internal/library"
"codeberg.org/squidd/sonda/internal/streaming"
)
type artistModel struct {
@ -205,6 +206,24 @@ func (r *LibraryRepo) Restore(ctx context.Context, ids []int64) error {
return nil
}
// PlayableFile returns the file to play for a track: the oldest one that was
// not flagged missing. It returns streaming.ErrNotFound when the track does not
// exist or has no such file. It implements streaming.Source.
func (r *LibraryRepo) PlayableFile(ctx context.Context, trackID int64) (streaming.File, error) {
var row audioFileModel
err := r.db.NewSelect().Model(&row).
Where("track_id = ?", trackID).
Where("missing_at IS NULL").
OrderExpr("id").Limit(1).Scan(ctx)
if errors.Is(err, sql.ErrNoRows) {
return streaming.File{}, streaming.ErrNotFound
}
if err != nil {
return streaming.File{}, fmt.Errorf("select playable file: %w", err)
}
return streaming.File{Root: row.Root, RelPath: row.RelPath}, nil
}
// RefreshMatchKeys recomputes name_key and title_key for every artist and album
// whose stored key differs from the current rule. It is idempotent and cheap
// when nothing changed, so it can run at every start: rows created before

View file

@ -2,6 +2,7 @@ package storage
import (
"context"
"errors"
"os"
"path/filepath"
"testing"
@ -10,6 +11,7 @@ import (
"github.com/uptrace/bun"
"codeberg.org/squidd/sonda/internal/library"
"codeberg.org/squidd/sonda/internal/streaming"
)
func parsed(rel, title, album string, artists ...string) library.ParsedFile {
@ -254,6 +256,52 @@ func TestLibraryRepoMissingRestoreRename(t *testing.T) {
})
}
func TestLibraryRepoPlayableFile(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
repo := NewLibraryRepo(db)
if _, err := repo.PlayableFile(ctx, 999); !errors.Is(err, streaming.ErrNotFound) {
t.Fatalf("unknown track: err = %v, want ErrNotFound", err)
}
if _, err := repo.SaveFile(ctx, "/music", parsed("a/1.flac", "Song", "", "X"), 0); err != nil {
t.Fatal(err)
}
var trackID, fileID int64
if err := db.QueryRow("SELECT track_id, id FROM audio_files").Scan(&trackID, &fileID); err != nil {
t.Fatal(err)
}
f, err := repo.PlayableFile(ctx, trackID)
if err != nil || f.Root != "/music" || f.RelPath != "a/1.flac" {
t.Fatalf("PlayableFile = %+v err=%v", f, err)
}
// A second encoding of the same track.
if _, err := db.Exec(`INSERT INTO audio_files (track_id, root, rel_path, format, size_bytes, mtime_unix)
VALUES (?, '/music', 'a/1.mp3', 'mp3', 1, 1)`, trackID); err != nil {
t.Fatal(err)
}
// The first file goes missing: the other one is served.
if err := repo.MarkMissing(ctx, []int64{fileID}, time.Now()); err != nil {
t.Fatal(err)
}
f, err = repo.PlayableFile(ctx, trackID)
if err != nil || f.RelPath != "a/1.mp3" {
t.Fatalf("with one file missing: %+v err=%v", f, err)
}
// Every file missing: nothing to play, but the track still exists.
if _, err := db.Exec("UPDATE audio_files SET missing_at = 1"); err != nil {
t.Fatal(err)
}
if _, err := repo.PlayableFile(ctx, trackID); !errors.Is(err, streaming.ErrNotFound) {
t.Fatalf("all files missing: err = %v, want ErrNotFound", err)
}
})
}
// stubReader lets the end-to-end test run without real audio.
type stubReader struct{}

View file

@ -0,0 +1,52 @@
//go:build unix
package streaming
import (
"context"
"errors"
"os"
"path/filepath"
"syscall"
"testing"
"time"
)
// Opening a named pipe blocks forever until a writer shows up, so a FIFO must
// be refused without ever blocking the request.
func TestOpenRefusesFIFOsWithoutHanging(t *testing.T) {
root := t.TempDir()
if err := syscall.Mkfifo(filepath.Join(root, "pipe.mp3"), 0o644); err != nil {
t.Skip("cannot create a FIFO:", err)
}
if err := os.Symlink("pipe.mp3", filepath.Join(root, "pipelink.mp3")); err != nil {
t.Skip("symlinks not supported:", err)
}
for _, rel := range []string{"pipe.mp3", "pipelink.mp3"} {
s := service(root, map[int64]File{1: {Root: root, RelPath: rel}})
type result struct {
st *Stream
err error
}
done := make(chan result, 1)
go func() {
st, err := s.Open(context.Background(), 1)
done <- result{st, err}
}()
select {
case r := <-done:
if r.err == nil {
r.st.Close()
t.Fatalf("%s: a FIFO was opened as a stream", rel)
}
if !errors.Is(r.err, ErrUnsafePath) {
t.Errorf("%s: err = %v, want ErrUnsafePath", rel, r.err)
}
case <-time.After(3 * time.Second):
t.Fatalf("%s: Open blocked on a FIFO", rel)
}
}
}

View file

@ -0,0 +1,5 @@
//go:build !unix
package streaming
const nonBlock = 0

View file

@ -0,0 +1,9 @@
//go:build unix
package streaming
import "syscall"
// nonBlock makes open(2) on a FIFO return immediately instead of waiting for a
// writer. It changes nothing for regular files.
const nonBlock = syscall.O_NONBLOCK

View file

@ -0,0 +1,161 @@
// Package streaming opens audio files for playback.
//
// The only job here is to turn a track id into an open, verified file. The
// stored path is treated as untrusted: it must belong to a configured library
// root, and the file is opened through os.Root so that nothing, not even a
// symlink swapped in at the last moment, can lead outside that root.
package streaming
import (
"context"
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
"strings"
"time"
)
// Errors returned by Open. Handlers map them to HTTP statuses.
var (
ErrNotFound = errors.New("no playable file for this track")
ErrFileMissing = errors.New("audio file is missing on disk")
ErrUnsafePath = errors.New("audio path is outside the library")
)
// File is where a track's audio lives: a configured library root plus a path
// relative to it, exactly as the scanner stored them.
type File struct {
Root string
RelPath string // slash-separated
}
// Source finds the file to play for a track.
type Source interface {
// PlayableFile returns ErrNotFound when the track does not exist or every
// file of it is flagged missing.
PlayableFile(ctx context.Context, trackID int64) (File, error)
}
// Stream is an open audio file ready to be served. The caller must Close it.
type Stream struct {
File *os.File
Name string
ModTime time.Time
ContentType string
}
// Close releases the file.
func (s *Stream) Close() error { return s.File.Close() }
// Service opens tracks for playback.
type Service struct {
source Source
roots []string // cleaned; config validation requires them to be absolute
}
// NewService builds a Service. Only files under the given roots can be opened.
func NewService(source Source, roots []string) *Service {
cleaned := make([]string, len(roots))
for i, r := range roots {
cleaned[i] = filepath.Clean(r)
}
return &Service{source: source, roots: cleaned}
}
// Open returns the audio file of a track, after verifying that it is a regular
// file inside one of the configured roots.
//
// The file is opened through an os.Root, which refuses to leave the root at
// open time: a symlink swapped in after any earlier check cannot escape, and
// there is no gap between "check the path" and "open the file".
func (s *Service) Open(ctx context.Context, trackID int64) (*Stream, error) {
f, err := s.source.PlayableFile(ctx, trackID)
if err != nil {
return nil, err
}
rel, err := s.validate(f)
if err != nil {
return nil, err
}
root, err := os.OpenRoot(filepath.Clean(f.Root))
if errors.Is(err, fs.ErrNotExist) {
return nil, ErrFileMissing // volume not mounted
}
if err != nil {
return nil, fmt.Errorf("open library root: %w", err)
}
defer root.Close() // files already opened stay valid
// O_NONBLOCK so that a FIFO cannot hang the request: opening one would
// otherwise block until a writer appears.
file, err := root.OpenFile(rel, os.O_RDONLY|nonBlock, 0)
switch {
case errors.Is(err, fs.ErrNotExist):
return nil, ErrFileMissing
case err != nil && strings.Contains(err.Error(), "path escapes from parent"):
// os.Root has no exported error for this case.
return nil, fmt.Errorf("%w: symlink leaves the library", ErrUnsafePath)
case err != nil:
return nil, fmt.Errorf("open audio file: %w", err)
}
// Check what was actually opened, not what the path looked like earlier.
info, err := file.Stat()
if err != nil {
_ = file.Close()
return nil, fmt.Errorf("stat audio file: %w", err)
}
if !info.Mode().IsRegular() {
_ = file.Close()
return nil, fmt.Errorf("%w: not a regular file", ErrUnsafePath)
}
return &Stream{
File: file,
Name: filepath.Base(rel),
ModTime: info.ModTime(),
ContentType: contentType(rel),
}, nil
}
// validate checks the stored root and relative path and returns the cleaned
// relative path to open under the root.
func (s *Service) validate(f File) (string, error) {
root := filepath.Clean(f.Root)
if !filepath.IsAbs(root) || !s.allowed(root) {
return "", fmt.Errorf("%w: root is not a configured library root", ErrUnsafePath)
}
rel := filepath.FromSlash(f.RelPath)
if rel == "" || filepath.IsAbs(rel) {
return "", fmt.Errorf("%w: bad relative path", ErrUnsafePath)
}
rel = filepath.Clean(rel)
if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
return "", fmt.Errorf("%w: path escapes the root", ErrUnsafePath)
}
return rel, nil
}
func (s *Service) allowed(root string) bool {
for _, r := range s.roots {
if r == root {
return true
}
}
return false
}
func contentType(path string) string {
switch strings.ToLower(filepath.Ext(path)) {
case ".mp3":
return "audio/mpeg"
case ".flac":
return "audio/flac"
default:
return "application/octet-stream"
}
}

View file

@ -0,0 +1,246 @@
package streaming
import (
"context"
"errors"
"io"
"os"
"path/filepath"
"testing"
)
type fakeSource struct {
files map[int64]File
err error
}
func (f fakeSource) PlayableFile(_ context.Context, trackID int64) (File, error) {
if f.err != nil {
return File{}, f.err
}
file, ok := f.files[trackID]
if !ok {
return File{}, ErrNotFound
}
return file, nil
}
func write(t *testing.T, path, content string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
t.Fatal(err)
}
}
// service builds a Service whose only allowed root is root.
func service(root string, files map[int64]File) *Service {
return NewService(fakeSource{files: files}, []string{root})
}
func TestOpenServesTheFile(t *testing.T) {
root := t.TempDir()
write(t, filepath.Join(root, "Artist/song.mp3"), "audio-bytes")
s := service(root, map[int64]File{1: {Root: root, RelPath: "Artist/song.mp3"}})
st, err := s.Open(context.Background(), 1)
if err != nil {
t.Fatal(err)
}
defer st.Close()
data, _ := io.ReadAll(st.File)
if string(data) != "audio-bytes" {
t.Errorf("content = %q", data)
}
if st.ContentType != "audio/mpeg" || st.Name != "song.mp3" || st.ModTime.IsZero() {
t.Errorf("stream = %+v", st)
}
}
func TestContentTypeFollowsTheExtension(t *testing.T) {
root := t.TempDir()
write(t, filepath.Join(root, "a.FLAC"), "x")
write(t, filepath.Join(root, "b.mp3"), "x")
write(t, filepath.Join(root, "c.xyz"), "x")
s := service(root, map[int64]File{
1: {Root: root, RelPath: "a.FLAC"},
2: {Root: root, RelPath: "b.mp3"},
3: {Root: root, RelPath: "c.xyz"},
})
want := map[int64]string{1: "audio/flac", 2: "audio/mpeg", 3: "application/octet-stream"}
for id, ct := range want {
st, err := s.Open(context.Background(), id)
if err != nil {
t.Fatal(err)
}
if st.ContentType != ct {
t.Errorf("track %d: content type = %q, want %q", id, st.ContentType, ct)
}
st.Close()
}
}
func TestOpenUnknownTrack(t *testing.T) {
s := service(t.TempDir(), nil)
if _, err := s.Open(context.Background(), 42); !errors.Is(err, ErrNotFound) {
t.Fatalf("err = %v, want ErrNotFound", err)
}
}
func TestOpenPropagatesSourceErrors(t *testing.T) {
boom := errors.New("db down")
s := NewService(fakeSource{err: boom}, []string{t.TempDir()})
if _, err := s.Open(context.Background(), 1); !errors.Is(err, boom) {
t.Fatalf("err = %v, want the source error", err)
}
}
func TestOpenMissingFileOnDisk(t *testing.T) {
root := t.TempDir()
s := service(root, map[int64]File{1: {Root: root, RelPath: "gone.mp3"}})
if _, err := s.Open(context.Background(), 1); !errors.Is(err, ErrFileMissing) {
t.Fatalf("err = %v, want ErrFileMissing", err)
}
}
func TestOpenRejectsUnsafePaths(t *testing.T) {
root := t.TempDir()
outside := t.TempDir()
write(t, filepath.Join(outside, "secret.mp3"), "secret")
write(t, filepath.Join(root, "ok.mp3"), "ok")
tests := []struct {
name string
file File
}{
{"dot dot", File{Root: root, RelPath: "../" + filepath.Base(outside) + "/secret.mp3"}},
{"deep dot dot", File{Root: root, RelPath: "a/../../x.mp3"}},
{"absolute path", File{Root: root, RelPath: filepath.Join(outside, "secret.mp3")}},
{"empty path", File{Root: root, RelPath: ""}},
{"the root itself", File{Root: root, RelPath: "."}},
{"root not configured", File{Root: outside, RelPath: "secret.mp3"}},
{"relative root", File{Root: "relative/dir", RelPath: "ok.mp3"}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
s := service(root, map[int64]File{1: tt.file})
st, err := s.Open(context.Background(), 1)
if err == nil {
st.Close()
t.Fatal("unsafe path was opened")
}
if !errors.Is(err, ErrUnsafePath) && !errors.Is(err, ErrFileMissing) {
t.Fatalf("err = %v, want ErrUnsafePath", err)
}
if errors.Is(err, ErrNotFound) {
t.Fatal("must not look like a plain not-found")
}
})
}
}
func TestOpenRejectsSymlinkEscapingTheRoot(t *testing.T) {
root := t.TempDir()
outside := t.TempDir()
write(t, filepath.Join(outside, "secret.mp3"), "secret")
if err := os.Symlink(filepath.Join(outside, "secret.mp3"), filepath.Join(root, "link.mp3")); err != nil {
t.Skip("symlinks not supported:", err)
}
if err := os.Symlink(outside, filepath.Join(root, "dirlink")); err != nil {
t.Skip("symlinks not supported:", err)
}
for _, rel := range []string{"link.mp3", "dirlink/secret.mp3"} {
s := service(root, map[int64]File{1: {Root: root, RelPath: rel}})
st, err := s.Open(context.Background(), 1)
if err == nil {
data, _ := io.ReadAll(st.File)
st.Close()
t.Fatalf("%s: symlink escaped the root and served %q", rel, data)
}
if !errors.Is(err, ErrUnsafePath) {
t.Errorf("%s: err = %v, want ErrUnsafePath", rel, err)
}
}
}
func TestOpenAllowsRelativeSymlinkThatStaysInsideTheRoot(t *testing.T) {
root := t.TempDir()
write(t, filepath.Join(root, "real/song.mp3"), "ok")
if err := os.Symlink("real", filepath.Join(root, "alias")); err != nil {
t.Skip("symlinks not supported:", err)
}
s := service(root, map[int64]File{1: {Root: root, RelPath: "alias/song.mp3"}})
st, err := s.Open(context.Background(), 1)
if err != nil {
t.Fatalf("relative symlink inside the root rejected: %v", err)
}
st.Close()
}
// os.Root refuses absolute symlink targets even when they point back inside the
// root. The scanner never indexes through a symlink, so this only costs files
// that were linked in after the scan, and it keeps the rule simple and safe.
func TestOpenRefusesAbsoluteSymlinksEvenInsideTheRoot(t *testing.T) {
root := t.TempDir()
write(t, filepath.Join(root, "real/song.mp3"), "ok")
if err := os.Symlink(filepath.Join(root, "real"), filepath.Join(root, "alias")); err != nil {
t.Skip("symlinks not supported:", err)
}
s := service(root, map[int64]File{1: {Root: root, RelPath: "alias/song.mp3"}})
st, err := s.Open(context.Background(), 1)
if err == nil {
st.Close()
t.Fatal("an absolute symlink was followed")
}
if !errors.Is(err, ErrUnsafePath) {
t.Errorf("err = %v, want ErrUnsafePath", err)
}
}
func TestOpenAcceptsASymlinkedRoot(t *testing.T) {
real := t.TempDir()
write(t, filepath.Join(real, "song.mp3"), "ok")
link := filepath.Join(t.TempDir(), "music")
if err := os.Symlink(real, link); err != nil {
t.Skip("symlinks not supported:", err)
}
s := service(link, map[int64]File{1: {Root: link, RelPath: "song.mp3"}})
st, err := s.Open(context.Background(), 1)
if err != nil {
t.Fatalf("a symlinked root is a normal setup: %v", err)
}
st.Close()
}
func TestOpenRejectsDirectories(t *testing.T) {
root := t.TempDir()
if err := os.MkdirAll(filepath.Join(root, "album.mp3"), 0o755); err != nil {
t.Fatal(err)
}
s := service(root, map[int64]File{1: {Root: root, RelPath: "album.mp3"}})
st, err := s.Open(context.Background(), 1)
if err == nil {
st.Close()
t.Fatal("a directory was opened as a stream")
}
if !errors.Is(err, ErrUnsafePath) {
t.Errorf("err = %v, want ErrUnsafePath", err)
}
}
func TestRootsAreComparedAfterCleaning(t *testing.T) {
root := t.TempDir()
write(t, filepath.Join(root, "song.mp3"), "ok")
// The configured root has no trailing slash, the stored one does.
s := service(root, map[int64]File{1: {Root: root + "/", RelPath: "song.mp3"}})
st, err := s.Open(context.Background(), 1)
if err != nil {
t.Fatalf("trailing slash on the stored root: %v", err)
}
st.Close()
}