feat(listening): count a listen after a minimum play time and expose the history

- feat: an event counts as a listen when it is `complete`, or when it was
  played for at least listening.min_listen_seconds (default 20, 1 to 3600).
  The rule is applied when the history is read, not when an event is stored,
  so changing the setting re-reads the past; streaming never counts
- feat(api): POST /listens answers with `counted`, also for a duplicate
- feat(api): GET /listens returns the signed-in user's own history, newest
  first, with `counted` per event, paging and ?counted=true; nobody sees
  anybody else's events
- feat: a reported play time more than twice the track length plus ten seconds
  is rejected as implausible; looping and seeking back stay allowed, and a
  track of unknown length is not checked
- feat(storage): TrackDurationMs and ListEvents on SQLite and PostgreSQL
- docs: OpenAPI operations and schemas, README rule, setting, API table and a
  demo that reports a 25 s and a 3 s play and reads the history; the demo tones
  now last 30 s so a 25 s play is plausible
- test: the rule at its boundaries, the plausibility bound, history order,
  paging and isolation on both databases, and the contract test for the new
  operation

Closes #17
This commit is contained in:
tgiachi 2026-11-11 14:58:47 +01:00
commit 7047e07906
15 changed files with 866 additions and 53 deletions

View file

@ -14,7 +14,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr
- **Catalog.** Browse and search artists, albums and tracks, with paging, by library, artist or album. Only tracks you can actually play are listed.
- **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen.
- **API documentation.** The full API is described in OpenAPI and browsable with Swagger UI, served by Sonda itself. The UI is embedded in the binary, so opening it contacts no other server.
- **Listening history.** Clients report explicit `play`, `complete` and `skip` events. They stay in your database; nothing is sent anywhere. Sonda makes no outbound network requests at all.
- **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; nothing is sent anywhere. Sonda makes no outbound network requests at all.
## What is not there yet
@ -57,6 +57,7 @@ Precedence is: built-in defaults, then the file, then environment variables. An
| `auth.jwt_secret` | `SONDA_JWT_SECRET` | *(required)* | Signs access tokens. At least 32 characters. |
| `auth.access_ttl_minutes` | | `15` | Lifetime of an access token. |
| `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`. |
| `providers.lastfm.api_key` | `SONDA_LASTFM_API_KEY` | | Reserved, not used yet. |
Libraries are not in the config: you add them through the API (see the demo).
@ -75,13 +76,13 @@ Sonda creates and migrates its tables on start. The storage tests run against bo
This takes you from an empty database to streaming a track. Run the server in one terminal and the commands in another.
**1. Get some music.** Point `MUSIC` at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two test tones:
**1. Get some music.** Point `MUSIC` at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two 30-second test tones:
```bash
export MUSIC="$HOME/Music"
mkdir -p "$MUSIC/demo"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=5" -metadata title="Tone A" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=1 "$MUSIC/demo/a.mp3"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=660:duration=5" -metadata title="Tone B" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=2 "$MUSIC/demo/b.flac"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=30" -metadata title="Tone A" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=1 "$MUSIC/demo/a.mp3"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=660:duration=30" -metadata title="Tone B" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=2 "$MUSIC/demo/b.flac"
```
**2. Start the server** (after the Build and Configure steps above):
@ -140,12 +141,18 @@ curl -s -o track.audio -H "$AUTH" $BASE/tracks/$TRACK/stream
A browser `<audio>` element cannot send headers, so the stream URL also accepts the access token in the query string: `$BASE/tracks/$TRACK/stream?access_token=$TOKEN`. That is the only route that does, and the query string is never logged.
**7. Report a listen.** Streaming never counts as a listen; clients say what happened. The idempotency key makes a retry harmless:
**7. Report a listen.** Streaming never counts as a listen; the player reports one event when a play passes 20 seconds or ends. The idempotency key makes a retry harmless. A play shorter than 20 seconds is stored too, but does not count unless it is `complete`:
```bash
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"complete\",\"duration_played_ms\":5000,\"idempotency_key\":\"demo-1\"}"
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"play\",\"duration_played_ms\":25000,\"idempotency_key\":\"demo-1\"}"
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"play\",\"duration_played_ms\":3000,\"idempotency_key\":\"demo-2\"}"
# Your history, newest first. Add ?counted=true to see only what counts.
curl -s "$BASE/listens" -H "$AUTH" | jq '.items[] | {track: .track.title, event_type, duration_played_ms, counted}'
```
The answer to each report says whether it counts. A reported play time far beyond the length of the track (more than twice its length plus 10 seconds) is rejected.
**8. Refresh the session and log out:**
```bash
@ -181,7 +188,8 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er
| signed in | `GET /auth/me`, `POST /auth/password` | Your account; change your password (signs you out everywhere). |
| signed in | `GET /artists`, `/albums`, `/tracks` and `/…/{id}` | Browse and search. Query: `q`, `limit` (default 50, max 200), `offset`, `library_id`, `artist_id`, `album_id`. |
| signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. |
| signed in | `POST /listens` | Record a `play`, `complete` or `skip`. |
| 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 /library/scan` | Scan status and the last result. |
| admin | `GET`, `POST /libraries`; `PATCH`, `DELETE /libraries/{id}` | Manage libraries. Deleting one removes its index entries, never your files. |
| admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. |

View file

@ -101,7 +101,7 @@ func run() error {
Logger: logger,
Auth: auth.NewService(storage.NewUserRepo(db), storage.NewRefreshRepo(db), tokens, cfg.Auth.RefreshTTL()),
Tokens: tokens,
Listening: listening.NewService(storage.NewListeningRepo(db)),
Listening: listening.NewService(storage.NewListeningRepo(db), cfg.Listening.MinListen()),
Scan: scanControl{ctx: ctx, m: scans},
Libraries: libraries,
Catalog: catalog.NewService(storage.NewCatalogRepo(db)),

View file

@ -77,7 +77,7 @@ func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun
Logger: zap.NewNop(),
Auth: auth.NewService(storage.NewUserRepo(db), storage.NewRefreshRepo(db), tokens, 24*time.Hour),
Tokens: tokens,
Listening: listening.NewService(storage.NewListeningRepo(db)),
Listening: listening.NewService(storage.NewListeningRepo(db), 20*time.Second),
Scan: &fakeScan{},
Libraries: library.NewLibraries(storage.NewLibraryRepo(db)),
Streams: streaming.NewService(noFiles{}),

View file

@ -412,8 +412,25 @@ func TestResponsesMatchTheSpec(t *testing.T) {
tid, _ := strconv.Atoi(trackID)
listen := map[string]any{"track_id": tid, "event_type": "complete", "duration_played_ms": 1000, "idempotency_key": "k1", "occurred_at": "2026-01-02T03:04:05Z"}
c.expect(c.call("POST", "/listens", token, listen), 201, "listen")
if got := c.expect(c.call("POST", "/listens", token, listen), 201, "listen"); got["counted"] != true {
t.Fatalf("a complete event must count: %v", got)
}
c.expect(c.call("POST", "/listens", token, listen), 200, "listen again")
short := map[string]any{"track_id": tid, "event_type": "play", "duration_played_ms": 3000, "idempotency_key": "k4"}
if got := c.expect(c.call("POST", "/listens", token, short), 201, "a short play"); got["counted"] != false {
t.Fatalf("a 3 s play must not count: %v", got)
}
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": tid, "event_type": "play", "duration_played_ms": 99999999, "idempotency_key": "k5"}), 400, "an implausible duration", "invalid_input")
history := c.expect(c.call("GET", "/listens", token, nil), 200, "history")
if history["total"] != float64(2) {
t.Fatalf("history = %v, want the two stored events", history)
}
onlyCounted := c.expect(c.call("GET", "/listens?counted=true&limit=5", token, nil), 200, "counted history")
if onlyCounted["total"] != float64(1) {
t.Fatalf("counted history = %v, want one", onlyCounted)
}
c.expect(c.call("GET", "/listens", "", nil), 401, "history without token", "unauthorized")
c.expect(c.call("GET", "/listens?counted=maybe", token, nil), 400, "history bad filter", "invalid_input")
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": 999, "event_type": "play", "idempotency_key": "k2"}), 404, "listen unknown track", "track_not_found")
c.expect(c.call("POST", "/listens", token, map[string]any{"track_id": tid, "event_type": "dance", "idempotency_key": "k3"}), 400, "listen invalid", "invalid_input")

View file

@ -41,7 +41,7 @@ func (h *listenHandlers) record(c *gin.Context) {
userID, _ := c.Get(ctxUserID)
uid, _ := userID.(int64)
created, err := h.svc.Record(c.Request.Context(), listening.Event{
res, err := h.svc.Record(c.Request.Context(), listening.Event{
UserID: uid,
TrackID: req.TrackID,
Type: listening.EventType(req.EventType),
@ -59,9 +59,63 @@ func (h *listenHandlers) record(c *gin.Context) {
case err != nil:
_ = c.Error(err)
writeError(c, http.StatusInternalServerError, "internal", "internal error")
case created:
c.JSON(http.StatusCreated, gin.H{"status": "recorded"})
case res.Created:
c.JSON(http.StatusCreated, gin.H{"status": "recorded", "counted": res.Counted})
default:
c.JSON(http.StatusOK, gin.H{"status": "duplicate"})
c.JSON(http.StatusOK, gin.H{"status": "duplicate", "counted": res.Counted})
}
}
type listenItemJSON struct {
ID int64 `json:"id"`
Track albumRefJSON `json:"track"`
EventType string `json:"event_type"`
OccurredAt string `json:"occurred_at"`
DurationPlayedMs int64 `json:"duration_played_ms"`
Counted bool `json:"counted"`
}
// list returns the signed-in user's own listening history, newest first.
func (h *listenHandlers) list(c *gin.Context) {
limit, ok := queryInt(c, "limit")
if !ok {
return
}
offset, ok := queryInt(c, "offset")
if !ok {
return
}
f := listening.Filter{Limit: clampInt(limit), Offset: clampInt(offset)}
switch c.Query("counted") {
case "":
case "true":
f.OnlyCounted = true
default:
writeError(c, http.StatusBadRequest, "invalid_input", "counted can only be true")
return
}
page, err := h.svc.List(c.Request.Context(), currentUserID(c), f)
switch {
case errors.Is(err, listening.ErrInvalidQuery):
writeError(c, http.StatusBadRequest, "invalid_input", err.Error())
return
case err != nil:
_ = c.Error(err)
writeError(c, http.StatusInternalServerError, "internal", "internal error")
return
}
items := make([]listenItemJSON, len(page.Items))
for i, it := range page.Items {
items[i] = listenItemJSON{
ID: it.ID,
Track: albumRefJSON{ID: it.TrackID, Title: it.TrackTitle},
EventType: string(it.Type),
OccurredAt: it.OccurredAt.UTC().Format(time.RFC3339),
DurationPlayedMs: it.DurationPlayedMs,
Counted: it.Counted,
}
}
c.JSON(http.StatusOK, gin.H{"items": items, "total": page.Total, "limit": page.Limit, "offset": page.Offset})
}

View file

@ -0,0 +1,155 @@
package httpapi
import (
"net/http"
"testing"
)
// listenFixture has a track of known length (100 s, id 2) next to the track of
// unknown length (id 1) every test environment starts with.
type listenFixture struct {
h http.Handler
admin string
bob string
}
func newListenFixture(t *testing.T) listenFixture {
t.Helper()
h, db := newTestEnv(t, func(*Deps) {})
if _, err := db.Exec("INSERT INTO tracks (title, duration_ms) VALUES ('Hundred seconds', 100000)"); err != nil {
t.Fatal(err)
}
admin := registerAndLogin(t, h)
_, bob := addUser(t, h, admin, "bob", false)
return listenFixture{h: h, admin: admin, bob: bob}
}
func (f listenFixture) listen(t *testing.T, token string, body map[string]any) resp {
t.Helper()
return do(t, f.h, "POST", "/api/v1/listens", token, body)
}
func ev(track int, typ string, ms int, key string, at string) map[string]any {
m := map[string]any{"track_id": track, "event_type": typ, "duration_played_ms": ms, "idempotency_key": key}
if at != "" {
m["occurred_at"] = at
}
return m
}
func TestListenSaysWhetherItCounts(t *testing.T) {
f := newListenFixture(t)
for name, tt := range map[string]struct {
body map[string]any
counted bool
}{
"a short play": {ev(1, "play", 5_000, "a", ""), false},
"a play past 20 s": {ev(1, "play", 25_000, "b", ""), true},
"exactly 20 s": {ev(1, "play", 20_000, "c", ""), true},
"just under": {ev(1, "play", 19_999, "d", ""), false},
"complete, however short": {ev(1, "complete", 1_000, "e", ""), true},
"a quick skip": {ev(1, "skip", 2_000, "f", ""), false},
"a late skip": {ev(1, "skip", 40_000, "g", ""), true},
} {
r := f.listen(t, f.admin, tt.body)
if r.Code != http.StatusCreated || r.Body["status"] != "recorded" || r.Body["counted"] != tt.counted {
t.Errorf("%s: %d %v, want 201 recorded counted=%v", name, r.Code, r.Body, tt.counted)
}
}
// A retry is accepted, not stored twice, and says what the event is worth.
r := f.listen(t, f.admin, ev(1, "play", 25_000, "b", ""))
if r.Code != http.StatusOK || r.Body["status"] != "duplicate" || r.Body["counted"] != true {
t.Errorf("duplicate: %d %v", r.Code, r.Body)
}
}
func TestListenRejectsAnImplausibleDuration(t *testing.T) {
f := newListenFixture(t)
// Track 2 lasts 100 s: up to twice that plus ten seconds is accepted.
if r := f.listen(t, f.admin, ev(2, "play", 210_000, "ok", "")); r.Code != http.StatusCreated {
t.Fatalf("210 s on a 100 s track: %d %v", r.Code, r.Body)
}
r := f.listen(t, f.admin, ev(2, "play", 210_001, "too-long", ""))
if r.Code != http.StatusBadRequest || errCode(r) != "invalid_input" {
t.Fatalf("210.001 s on a 100 s track: %d %v", r.Code, r.Body)
}
// Track 1 has no known length, so there is nothing to compare with.
if r := f.listen(t, f.admin, ev(1, "play", 9_000_000, "unknown-length", "")); r.Code != http.StatusCreated {
t.Fatalf("unknown length: %d %v", r.Code, r.Body)
}
}
func TestListeningHistoryRequiresAuth(t *testing.T) {
f := newListenFixture(t)
if r := do(t, f.h, "GET", "/api/v1/listens", "", nil); r.Code != http.StatusUnauthorized {
t.Errorf("without a token: %d", r.Code)
}
}
func TestListeningHistory(t *testing.T) {
f := newListenFixture(t)
f.listen(t, f.admin, ev(1, "play", 5_000, "e1", "2026-01-01T10:00:00Z"))
f.listen(t, f.admin, ev(1, "play", 25_000, "e2", "2026-01-01T11:00:00Z"))
f.listen(t, f.admin, ev(2, "complete", 1_000, "e3", "2026-01-01T12:00:00Z"))
f.listen(t, f.bob, ev(2, "play", 60_000, "b1", "2026-01-01T13:00:00Z"))
r := do(t, f.h, "GET", "/api/v1/listens", f.admin, nil)
if r.Code != http.StatusOK || r.Body["total"] != float64(3) || r.Body["limit"] != float64(50) || r.Body["offset"] != float64(0) {
t.Fatalf("history: %d %v", r.Code, r.Body)
}
sameKeys(t, "history", r.Body, "items", "total", "limit", "offset")
items := r.Body["items"].([]any)
first := items[0].(map[string]any)
sameKeys(t, "item", first, "id", "track", "event_type", "occurred_at", "duration_played_ms", "counted")
sameKeys(t, "item.track", first["track"].(map[string]any), "id", "title")
if first["event_type"] != "complete" || first["occurred_at"] != "2026-01-01T12:00:00Z" ||
first["counted"] != true || first["track"].(map[string]any)["title"] != "Hundred seconds" {
t.Errorf("newest event = %v", first)
}
// Newest first, and the 5 s play is in the list but not counted.
if items[2].(map[string]any)["counted"] != false || items[2].(map[string]any)["occurred_at"] != "2026-01-01T10:00:00Z" {
t.Errorf("oldest event = %v", items[2])
}
// Only what counts.
r = do(t, f.h, "GET", "/api/v1/listens?counted=true", f.admin, nil)
if r.Body["total"] != float64(2) {
t.Errorf("counted=true: total %v, want 2", r.Body["total"])
}
for _, it := range r.Body["items"].([]any) {
if it.(map[string]any)["counted"] != true {
t.Errorf("an uncounted event in the counted list: %v", it)
}
}
// Paging.
r = do(t, f.h, "GET", "/api/v1/listens?limit=1&offset=1", f.admin, nil)
page := r.Body["items"].([]any)
if len(page) != 1 || r.Body["total"] != float64(3) || page[0].(map[string]any)["occurred_at"] != "2026-01-01T11:00:00Z" {
t.Errorf("page: %v", r.Body)
}
// Nobody sees anybody else's history.
r = do(t, f.h, "GET", "/api/v1/listens", f.bob, nil)
if r.Body["total"] != float64(1) {
t.Errorf("bob's total = %v, want only his own event", r.Body["total"])
}
}
func TestListeningHistoryRejectsBadParameters(t *testing.T) {
f := newListenFixture(t)
for _, qs := range []string{"limit=abc", "offset=x", "limit=-1", "offset=-1", "counted=maybe", "counted=1", "counted=false"} {
r := do(t, f.h, "GET", "/api/v1/listens?"+qs, f.admin, nil)
if r.Code != http.StatusBadRequest || errCode(r) != "invalid_input" {
t.Errorf("?%s: %d %v", qs, r.Code, r.Body)
}
}
// limit=0 means the default, like everywhere else.
if r := do(t, f.h, "GET", "/api/v1/listens?limit=0", f.admin, nil); r.Code != http.StatusOK || r.Body["limit"] != float64(50) {
t.Errorf("limit=0: %d %v", r.Code, r.Body)
}
if r := do(t, f.h, "GET", "/api/v1/listens?limit=9999", f.admin, nil); r.Body["limit"] != float64(200) {
t.Errorf("limit=9999: %v, want it lowered to 200", r.Body["limit"])
}
}

View file

@ -39,7 +39,8 @@ type tokenParser interface {
}
type listenService interface {
Record(ctx context.Context, e listening.Event) (bool, error)
Record(ctx context.Context, e listening.Event) (listening.Result, error)
List(ctx context.Context, userID int64, f listening.Filter) (listening.Page, error)
}
type streamService interface {
@ -103,6 +104,7 @@ func NewRouter(d Deps) *gin.Engine {
protected.POST("/auth/password", a.changePassword)
l := &listenHandlers{svc: d.Listening}
protected.POST("/listens", l.record)
protected.GET("/listens", l.list)
lib := &libraryHandlers{scan: d.Scan}
protected.GET("/library/scan", lib.scanStatus)

View file

@ -752,13 +752,47 @@ paths:
'416': {description: The range cannot be satisfied.}
/listens:
get:
tags: [Playback]
operationId: listListens
summary: Your listening history
description: |
The events you reported, newest first, each with `counted`: whether it counts as a listen
under the current rule (see `POST /listens`). Nobody else's history is visible.
security: [{bearerAuth: []}]
parameters:
- {$ref: '#/components/parameters/Limit'}
- {$ref: '#/components/parameters/Offset'}
- name: counted
in: query
description: Send `true` to list only the events that count as a listen.
schema: {type: boolean, enum: [true]}
responses:
'200':
description: A page of events.
content:
application/json:
schema: {$ref: '#/components/schemas/ListenPage'}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
post:
tags: [Playback]
operationId: recordListen
summary: Record a listen
description: |
Clients report what the listener did. The `idempotency_key` makes a retry harmless: the
same key from the same user is recorded once and answered with `duplicate`.
Clients report what the listener did, once per play, when the play passes the minimum
time or ends. The `idempotency_key` makes a retry harmless: the same key from the same user
is recorded once and answered with `duplicate`.
**What counts as a listen.** An event counts when its type is `complete`, or when
`duration_played_ms` is at least `listening.min_listen_seconds` (20 seconds by default).
A `play` or `skip` shorter than that is stored but does not count. The rule is applied when
the history is read, so changing the setting re-reads the past. The answer says whether this
event counts; for a `duplicate` it describes the event you sent.
**Plausibility.** When the length of the track is known, `duration_played_ms` may not exceed
twice that length plus 10 seconds (a listener can seek back and loop). Streaming a file never
records anything on its own.
security: [{bearerAuth: []}]
requestBody:
required: true
@ -1122,12 +1156,47 @@ components:
track_id: {type: integer, format: int64, minimum: 1}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time, description: Defaults to now.}
duration_played_ms: {type: integer, format: int64, minimum: 0}
duration_played_ms:
type: integer
format: int64
minimum: 0
description: Milliseconds actually played. Up to twice the track length plus 10 seconds when that length is known.
idempotency_key: {type: string, description: 1 to 128 bytes (UTF-8).}
ListenResult:
type: object
additionalProperties: false
required: [status]
required: [status, counted]
properties:
status: {type: string, enum: [recorded, duplicate]}
counted: {type: boolean, description: Whether the event counts as a listen.}
ListenItem:
type: object
additionalProperties: false
required: [id, track, event_type, occurred_at, duration_played_ms, counted]
properties:
id: {type: integer, format: int64}
track:
type: object
additionalProperties: false
required: [id, title]
properties:
id: {type: integer, format: int64}
title: {type: string}
event_type: {type: string, enum: [play, complete, skip]}
occurred_at: {type: string, format: date-time}
duration_played_ms: {type: integer, format: int64}
counted: {type: boolean, description: Whether the event counts as a listen under the current rule.}
ListenPage:
type: object
additionalProperties: false
required: [items, total, limit, offset]
properties:
items:
type: array
items: {$ref: '#/components/schemas/ListenItem'}
total: {type: integer, description: "Size of the whole result, not of this page."}
limit: {type: integer}
offset: {type: integer}

View file

@ -22,6 +22,7 @@ type Config struct {
Database Database `toml:"database"`
Log Log `toml:"log"`
Auth Auth `toml:"auth"`
Listening Listening `toml:"listening"`
Providers Providers `toml:"providers"`
}
@ -68,6 +69,18 @@ func (a Auth) RefreshTTL() time.Duration {
return time.Duration(a.RefreshTTLHours) * time.Hour
}
// Listening holds the rule for what counts as a listen.
type Listening struct {
// MinListenSeconds is how long a play must last to count as a listen when it
// is not reported as complete.
MinListenSeconds int `toml:"min_listen_seconds"`
}
// MinListen returns the minimum play time of a counted listen.
func (l Listening) MinListen() time.Duration {
return time.Duration(l.MinListenSeconds) * time.Second
}
// Providers holds external provider settings.
type Providers struct {
LastFM LastFM `toml:"lastfm"`
@ -81,11 +94,12 @@ type LastFM struct {
// Default returns the configuration used when nothing else is set.
func Default() Config {
return Config{
Server: Server{Listen: "127.0.0.1:8080"},
Library: Library{ScanWorkers: 4},
Database: Database{Driver: "sqlite", Path: "sonda.db"},
Log: Log{Env: "production"},
Auth: Auth{AccessTTLMinutes: 15, RefreshTTLHours: 720}, // 15 minutes, 30 days
Server: Server{Listen: "127.0.0.1:8080"},
Library: Library{ScanWorkers: 4},
Database: Database{Driver: "sqlite", Path: "sonda.db"},
Log: Log{Env: "production"},
Auth: Auth{AccessTTLMinutes: 15, RefreshTTLHours: 720}, // 15 minutes, 30 days
Listening: Listening{MinListenSeconds: 20},
}
}
@ -165,6 +179,9 @@ func (c Config) Validate() error {
if c.Auth.RefreshTTLHours <= 0 {
errs = append(errs, errors.New("auth.refresh_ttl_hours must be greater than 0"))
}
if c.Listening.MinListenSeconds < 1 || c.Listening.MinListenSeconds > 3600 {
errs = append(errs, errors.New("listening.min_listen_seconds must be between 1 and 3600"))
}
if c.Library.ScanWorkers < 1 {
errs = append(errs, errors.New("library.scan_workers must be at least 1"))
}

View file

@ -37,6 +37,9 @@ func TestLoadEmptyPathReturnsDefaults(t *testing.T) {
if cfg.Library.ScanWorkers != 4 {
t.Errorf("scan workers = %d", cfg.Library.ScanWorkers)
}
if cfg.Listening.MinListen() != 20*time.Second {
t.Errorf("min listen = %v, want 20s", cfg.Listening.MinListen())
}
if cfg.Auth.AccessTTL() != 15*time.Minute {
t.Errorf("access ttl = %v", cfg.Auth.AccessTTL())
}
@ -131,6 +134,9 @@ func TestValidate(t *testing.T) {
}, ""},
{"no secret", func(c *Config) { c.Auth.JWTSecret = "" }, "auth.jwt_secret"},
{"short secret", func(c *Config) { c.Auth.JWTSecret = "short" }, "auth.jwt_secret"},
{"zero min listen", func(c *Config) { c.Listening.MinListenSeconds = 0 }, "listening.min_listen_seconds"},
{"negative min listen", func(c *Config) { c.Listening.MinListenSeconds = -5 }, "listening.min_listen_seconds"},
{"absurd min listen", func(c *Config) { c.Listening.MinListenSeconds = 3601 }, "listening.min_listen_seconds"},
{"bad workers", func(c *Config) { c.Library.ScanWorkers = 0 }, "library.scan_workers"},
{"bad access ttl", func(c *Config) { c.Auth.AccessTTLMinutes = 0 }, "auth.access_ttl_minutes"},
{"bad refresh ttl", func(c *Config) { c.Auth.RefreshTTLHours = 0 }, "auth.refresh_ttl_hours"},
@ -169,3 +175,14 @@ func TestLoadExplainsRemovedLibraryRoots(t *testing.T) {
t.Errorf("error = %v, want a pointer to the libraries API", err)
}
}
func TestListeningSettingIsReadFromTheFile(t *testing.T) {
p := writeFile(t, t.TempDir(), "[listening]\nmin_listen_seconds = 30\n")
cfg, err := Load(p)
if err != nil {
t.Fatal(err)
}
if cfg.Listening.MinListen() != 30*time.Second {
t.Errorf("min listen = %v", cfg.Listening.MinListen())
}
}

View file

@ -1,7 +1,13 @@
// Package listening records explicit listen events (play, complete, skip).
// Package listening records what listeners did (play, complete, skip) and reads
// the history back.
//
// These events feed the recommendation engine. Merely opening or prefetching
// an audio URL must never create one.
// an audio URL must never create one: the player reports an event itself.
//
// An event counts as a listen when it is `complete`, or when it was played for
// at least a minimum time (20 seconds by default). The rule is applied when the
// history is read, not when an event is stored, so changing the minimum
// re-reads the whole past with the new rule.
package listening
import (
@ -14,6 +20,7 @@ import (
// Errors returned by the service.
var (
ErrInvalidEvent = errors.New("invalid listening event")
ErrInvalidQuery = errors.New("invalid query")
ErrTrackNotFound = errors.New("track not found")
ErrUserNotFound = errors.New("user not found") // the account was deleted
)
@ -28,7 +35,17 @@ const (
Skip EventType = "skip"
)
const maxKeyLen = 128
// Limits.
const (
maxKeyLen = 128
DefaultLimit = 50
MaxLimit = 200
// A reported play time may exceed the track length (the listener can seek
// back and loop), but not by more than twice its length plus ten seconds.
maxOverrunFactor = 2
maxOverrunSlack = 10_000 // ms
)
// Event is one listen reported by a client.
type Event struct {
@ -40,43 +57,144 @@ type Event struct {
IdempotencyKey string // client generated; retries with the same key are no-ops
}
// Store persists events.
// Result says what happened to a reported event.
type Result struct {
Created bool // false when the idempotency key was already recorded
Counted bool // whether the event counts as a listen
}
// Record is a stored event, as read back for the history.
type Record struct {
ID int64
TrackID int64
TrackTitle string
Type EventType
OccurredAt time.Time
DurationPlayedMs int64
}
// Item is a stored event together with the verdict of the current rule.
type Item struct {
Record
Counted bool
}
// Filter pages the history. Zero Limit means the default.
type Filter struct {
Limit int
Offset int
OnlyCounted bool
}
// Page is one page of the history and the size of the whole result.
type Page struct {
Items []Item
Total int
Limit int
Offset int
}
// ListQuery is what the service asks the store for.
type ListQuery struct {
UserID int64
Limit int
Offset int
OnlyCounted bool
MinPlayedMs int64 // threshold for OnlyCounted
}
// Store persists and reads events.
type Store interface {
// Record saves e. It returns created=false when an event with the same
// (user, idempotency key) already exists, ErrTrackNotFound for an unknown
// track and ErrUserNotFound for an account that no longer exists.
Record(ctx context.Context, e Event) (created bool, err error)
// TrackDurationMs returns the length of a track, 0 when it is not known,
// and ErrTrackNotFound for an unknown track.
TrackDurationMs(ctx context.Context, trackID int64) (int64, error)
// ListEvents returns one page of a user's events, newest first, and the
// total. With OnlyCounted it keeps `complete` events and those played for
// at least MinPlayedMs.
ListEvents(ctx context.Context, q ListQuery) ([]Record, int, error)
}
// Service validates and records events.
// Service validates and records events and reads the history.
type Service struct {
store Store
now func() time.Time
store Store
minListen time.Duration
now func() time.Time
}
// NewService builds a Service.
func NewService(store Store) *Service {
return &Service{store: store, now: time.Now}
// NewService builds a Service. minListen is how long a play must last to count
// as a listen when it is not `complete`.
func NewService(store Store, minListen time.Duration) *Service {
return &Service{store: store, minListen: minListen, now: time.Now}
}
// Counted applies the rule: a `complete` event counts, anything else counts when
// it was played for at least the minimum. A skip after the minimum was listened
// to; later code may weigh it differently, but it was a listen.
func (s *Service) Counted(t EventType, playedMs int64) bool {
return t == Complete || playedMs >= s.minListen.Milliseconds()
}
// Record validates e and stores it.
func (s *Service) Record(ctx context.Context, e Event) (bool, error) {
func (s *Service) Record(ctx context.Context, e Event) (Result, error) {
switch e.Type {
case Play, Complete, Skip:
default:
return false, fmt.Errorf("%w: event_type must be play, complete or skip", ErrInvalidEvent)
return Result{}, fmt.Errorf("%w: event_type must be play, complete or skip", ErrInvalidEvent)
}
if e.UserID <= 0 || e.TrackID <= 0 {
return false, fmt.Errorf("%w: user and track are required", ErrInvalidEvent)
return Result{}, fmt.Errorf("%w: user and track are required", ErrInvalidEvent)
}
if e.IdempotencyKey == "" || len(e.IdempotencyKey) > maxKeyLen {
return false, fmt.Errorf("%w: idempotency_key must be 1-%d characters", ErrInvalidEvent, maxKeyLen)
return Result{}, fmt.Errorf("%w: idempotency_key must be 1-%d bytes", ErrInvalidEvent, maxKeyLen)
}
if e.DurationPlayedMs < 0 {
return false, fmt.Errorf("%w: duration_played_ms cannot be negative", ErrInvalidEvent)
return Result{}, fmt.Errorf("%w: duration_played_ms cannot be negative", ErrInvalidEvent)
}
length, err := s.store.TrackDurationMs(ctx, e.TrackID)
if err != nil {
return Result{}, err
}
if length > 0 && e.DurationPlayedMs > maxOverrunFactor*length+maxOverrunSlack {
return Result{}, fmt.Errorf("%w: duration_played_ms is far longer than the track", ErrInvalidEvent)
}
if e.OccurredAt.IsZero() {
e.OccurredAt = s.now()
}
return s.store.Record(ctx, e)
created, err := s.store.Record(ctx, e)
if err != nil {
return Result{}, err
}
return Result{Created: created, Counted: s.Counted(e.Type, e.DurationPlayedMs)}, nil
}
// List returns one page of the history of a user, newest first.
func (s *Service) List(ctx context.Context, userID int64, f Filter) (Page, error) {
if f.Limit < 0 || f.Offset < 0 {
return Page{}, fmt.Errorf("%w: limit and offset cannot be negative", ErrInvalidQuery)
}
switch {
case f.Limit == 0:
f.Limit = DefaultLimit
case f.Limit > MaxLimit:
f.Limit = MaxLimit
}
records, total, err := s.store.ListEvents(ctx, ListQuery{
UserID: userID, Limit: f.Limit, Offset: f.Offset,
OnlyCounted: f.OnlyCounted, MinPlayedMs: s.minListen.Milliseconds(),
})
if err != nil {
return Page{}, err
}
page := Page{Items: make([]Item, len(records)), Total: total, Limit: f.Limit, Offset: f.Offset}
for i, r := range records {
page.Items[i] = Item{Record: r, Counted: s.Counted(r.Type, r.DurationPlayedMs)}
}
return page, nil
}

View file

@ -8,10 +8,18 @@ import (
"time"
)
// fakeStore records what it is asked and returns canned answers.
type fakeStore struct {
got []Event
created bool
err error
got []Event
created bool
err error
durationMs int64
durErr error
durCalls int
records []Record
total int
lastQ ListQuery
}
func (f *fakeStore) Record(_ context.Context, e Event) (bool, error) {
@ -19,6 +27,20 @@ func (f *fakeStore) Record(_ context.Context, e Event) (bool, error) {
return f.created, f.err
}
func (f *fakeStore) TrackDurationMs(context.Context, int64) (int64, error) {
f.durCalls++
return f.durationMs, f.durErr
}
func (f *fakeStore) ListEvents(_ context.Context, q ListQuery) ([]Record, int, error) {
f.lastQ = q
return f.records, f.total, f.err
}
const minListen = 20 * time.Second
func newSvc(store *fakeStore) *Service { return NewService(store, minListen) }
func TestRecordValidation(t *testing.T) {
valid := Event{UserID: 1, TrackID: 2, Type: Play, IdempotencyKey: "k1"}
tests := []struct {
@ -38,7 +60,7 @@ func TestRecordValidation(t *testing.T) {
store := &fakeStore{}
e := valid
tt.mutate(&e)
if _, err := NewService(store).Record(context.Background(), e); !errors.Is(err, ErrInvalidEvent) {
if _, err := newSvc(store).Record(context.Background(), e); !errors.Is(err, ErrInvalidEvent) {
t.Fatalf("err = %v, want ErrInvalidEvent", err)
}
if len(store.got) != 0 {
@ -51,12 +73,12 @@ func TestRecordValidation(t *testing.T) {
func TestRecordDefaultsTimestamp(t *testing.T) {
store := &fakeStore{created: true}
now := time.Unix(1_700_000_000, 0)
s := NewService(store)
s := newSvc(store)
s.now = func() time.Time { return now }
created, err := s.Record(context.Background(), Event{UserID: 1, TrackID: 2, Type: Complete, IdempotencyKey: "k"})
if err != nil || !created {
t.Fatalf("created=%v err=%v", created, err)
res, err := s.Record(context.Background(), Event{UserID: 1, TrackID: 2, Type: Complete, IdempotencyKey: "k"})
if err != nil || !res.Created {
t.Fatalf("result=%+v err=%v", res, err)
}
if !store.got[0].OccurredAt.Equal(now) {
t.Errorf("OccurredAt = %v, want %v", store.got[0].OccurredAt, now)
@ -66,7 +88,7 @@ func TestRecordDefaultsTimestamp(t *testing.T) {
func TestRecordKeepsClientTimestamp(t *testing.T) {
store := &fakeStore{created: true}
ts := time.Unix(1_600_000_000, 0)
_, err := NewService(store).Record(context.Background(),
_, err := newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: Skip, IdempotencyKey: "k", OccurredAt: ts})
if err != nil {
t.Fatal(err)
@ -77,10 +99,181 @@ func TestRecordKeepsClientTimestamp(t *testing.T) {
}
func TestRecordPropagatesStoreError(t *testing.T) {
store := &fakeStore{err: ErrTrackNotFound}
_, err := NewService(store).Record(context.Background(),
store := &fakeStore{err: ErrUserNotFound}
_, err := newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: Play, IdempotencyKey: "k"})
if !errors.Is(err, ErrTrackNotFound) {
t.Fatalf("err = %v, want ErrTrackNotFound", err)
if !errors.Is(err, ErrUserNotFound) {
t.Fatalf("err = %v, want ErrUserNotFound", err)
}
}
// ---- what counts as a listen ----
func TestWhatCountsAsAListen(t *testing.T) {
tests := []struct {
name string
typ EventType
ms int64
min time.Duration
want bool
}{
{"complete counts however short", Complete, 0, minListen, true},
{"complete counts with a long duration too", Complete, 300_000, minListen, true},
{"play just under the threshold", Play, 19_999, minListen, false},
{"play exactly at the threshold", Play, 20_000, minListen, true},
{"play well over", Play, 90_000, minListen, true},
{"a skip after the threshold was listened to", Skip, 25_000, minListen, true},
{"a quick skip", Skip, 1_000, minListen, false},
{"a play that never started", Play, 0, minListen, false},
{"a different threshold", Play, 6_000, 5 * time.Second, true},
{"a different threshold, under", Play, 4_999, 5 * time.Second, false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := NewService(&fakeStore{}, tt.min).Counted(tt.typ, tt.ms); got != tt.want {
t.Errorf("Counted(%s, %d ms, min %v) = %v, want %v", tt.typ, tt.ms, tt.min, got, tt.want)
}
})
}
}
func TestRecordTellsWhetherTheEventCounts(t *testing.T) {
for name, tt := range map[string]struct {
typ EventType
ms int64
want bool
}{
"short play": {Play, 5_000, false},
"long play": {Play, 25_000, true},
"complete": {Complete, 3_000, true},
} {
t.Run(name, func(t *testing.T) {
store := &fakeStore{created: true}
res, err := newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: tt.typ, DurationPlayedMs: tt.ms, IdempotencyKey: "k"})
if err != nil || res.Counted != tt.want || !res.Created {
t.Fatalf("result = %+v err=%v, want counted=%v", res, err, tt.want)
}
})
}
}
// A duplicate is not stored again, but the answer still says what the event
// you sent is worth.
func TestDuplicateStillReportsCounted(t *testing.T) {
store := &fakeStore{created: false}
res, err := newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: Play, DurationPlayedMs: 30_000, IdempotencyKey: "k"})
if err != nil || res.Created || !res.Counted {
t.Fatalf("result = %+v err=%v", res, err)
}
}
// ---- a reported duration must be believable ----
func TestRecordRejectsADurationFarBeyondTheTrack(t *testing.T) {
ctx := context.Background()
ev := func(ms int64) Event {
return Event{UserID: 1, TrackID: 2, Type: Play, DurationPlayedMs: ms, IdempotencyKey: "k"}
}
// A 100 s track: up to twice its length plus ten seconds is fine, so that
// seeking back and looping does not lose real listens.
store := &fakeStore{created: true, durationMs: 100_000}
if _, err := newSvc(store).Record(ctx, ev(210_000)); err != nil {
t.Errorf("210 s on a 100 s track: %v", err)
}
store = &fakeStore{created: true, durationMs: 100_000}
if _, err := newSvc(store).Record(ctx, ev(210_001)); !errors.Is(err, ErrInvalidEvent) {
t.Errorf("210.001 s on a 100 s track: err = %v, want ErrInvalidEvent", err)
}
if len(store.got) != 0 {
t.Error("an implausible event reached the store")
}
// A track of unknown length cannot be checked.
store = &fakeStore{created: true, durationMs: 0}
if _, err := newSvc(store).Record(ctx, ev(10_000_000)); err != nil {
t.Errorf("unknown track length: %v", err)
}
// An unknown track is reported as such, before anything is stored.
store = &fakeStore{durErr: ErrTrackNotFound}
if _, err := newSvc(store).Record(ctx, ev(1000)); !errors.Is(err, ErrTrackNotFound) {
t.Errorf("unknown track: err = %v", err)
}
if len(store.got) != 0 {
t.Error("an event for an unknown track reached the store")
}
}
// ---- the history ----
func TestListPagingAndBounds(t *testing.T) {
tests := []struct {
name string
in Filter
wantLimit int
wantOffset int
wantInvalid bool
}{
{"defaults", Filter{}, DefaultLimit, 0, false},
{"explicit", Filter{Limit: 10, Offset: 20}, 10, 20, false},
{"above the maximum is lowered", Filter{Limit: MaxLimit + 1}, MaxLimit, 0, false},
{"negative limit", Filter{Limit: -1}, 0, 0, true},
{"negative offset", Filter{Offset: -1}, 0, 0, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
store := &fakeStore{}
page, err := newSvc(store).List(context.Background(), 7, tt.in)
if tt.wantInvalid {
if !errors.Is(err, ErrInvalidQuery) {
t.Fatalf("err = %v, want ErrInvalidQuery", err)
}
return
}
if err != nil {
t.Fatal(err)
}
if store.lastQ.Limit != tt.wantLimit || store.lastQ.Offset != tt.wantOffset || store.lastQ.UserID != 7 {
t.Errorf("store saw %+v, want limit %d offset %d user 7", store.lastQ, tt.wantLimit, tt.wantOffset)
}
if page.Limit != tt.wantLimit || page.Offset != tt.wantOffset {
t.Errorf("page = %+v", page)
}
})
}
}
func TestListMarksCountedAndPassesTheThreshold(t *testing.T) {
store := &fakeStore{
total: 3,
records: []Record{
{ID: 3, TrackID: 1, TrackTitle: "A", Type: Complete, DurationPlayedMs: 1000},
{ID: 2, TrackID: 1, TrackTitle: "A", Type: Play, DurationPlayedMs: 25_000},
{ID: 1, TrackID: 2, TrackTitle: "B", Type: Play, DurationPlayedMs: 3_000},
},
}
page, err := newSvc(store).List(context.Background(), 1, Filter{OnlyCounted: true})
if err != nil {
t.Fatal(err)
}
if !store.lastQ.OnlyCounted || store.lastQ.MinPlayedMs != 20_000 {
t.Errorf("store query = %+v, want OnlyCounted with the 20 s threshold", store.lastQ)
}
counted := []bool{page.Items[0].Counted, page.Items[1].Counted, page.Items[2].Counted}
if !(counted[0] && counted[1] && !counted[2]) {
t.Errorf("counted = %v, want [true true false]", counted)
}
if page.Total != 3 {
t.Errorf("total = %d", page.Total)
}
}
func TestListPropagatesStoreErrors(t *testing.T) {
boom := errors.New("db down")
if _, err := newSvc(&fakeStore{err: boom}).List(context.Background(), 1, Filter{}); !errors.Is(err, boom) {
t.Fatalf("err = %v", err)
}
}

View file

@ -2,7 +2,10 @@ package storage
import (
"context"
"database/sql"
"errors"
"fmt"
"time"
"github.com/uptrace/bun"
@ -74,3 +77,60 @@ func (r *ListeningRepo) Record(ctx context.Context, e listening.Event) (bool, er
}
return n > 0, nil
}
// TrackDurationMs returns the length of a track in milliseconds, 0 when it is
// not known, or listening.ErrTrackNotFound.
func (r *ListeningRepo) TrackDurationMs(ctx context.Context, trackID int64) (int64, error) {
var d sql.NullInt64
err := r.db.QueryRowContext(ctx, "SELECT duration_ms FROM tracks WHERE id = ?", trackID).Scan(&d)
if errors.Is(err, sql.ErrNoRows) {
return 0, listening.ErrTrackNotFound
}
if err != nil {
return 0, fmt.Errorf("select track duration: %w", err)
}
return d.Int64, nil
}
// ListEvents returns one page of a user's events, newest first, and the total.
// With OnlyCounted it keeps `complete` events and plays of at least MinPlayedMs.
func (r *ListeningRepo) ListEvents(ctx context.Context, q listening.ListQuery) ([]listening.Record, int, error) {
where := "e.user_id = ?"
args := []any{q.UserID}
if q.OnlyCounted {
where += " AND (e.event_type = 'complete' OR e.duration_played_ms >= ?)"
args = append(args, q.MinPlayedMs)
}
var total int
if err := r.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM listening_events e WHERE "+where, args...).Scan(&total); err != nil {
return nil, 0, fmt.Errorf("count listening events: %w", err)
}
records := []listening.Record{}
if q.Offset >= total {
return records, total, nil
}
rows, err := r.db.QueryContext(ctx,
`SELECT e.id, e.track_id, t.title, e.event_type, e.occurred_at, e.duration_played_ms
FROM listening_events e JOIN tracks t ON t.id = e.track_id
WHERE `+where+` ORDER BY e.occurred_at DESC, e.id DESC LIMIT ? OFFSET ?`,
append(append([]any{}, args...), q.Limit, q.Offset)...)
if err != nil {
return nil, 0, fmt.Errorf("list listening events: %w", err)
}
defer rows.Close()
for rows.Next() {
var (
rec listening.Record
typ string
at int64
)
if err := rows.Scan(&rec.ID, &rec.TrackID, &rec.TrackTitle, &typ, &at, &rec.DurationPlayedMs); err != nil {
return nil, 0, err
}
rec.Type, rec.OccurredAt = listening.EventType(typ), time.Unix(at, 0)
records = append(records, rec)
}
return records, total, rows.Err()
}

View file

@ -151,3 +151,103 @@ func TestListeningRepoRefusesADeletedUser(t *testing.T) {
}
})
}
func TestListeningRepoTrackDuration(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
repo := NewListeningRepo(db)
var withLen, withoutLen int64
if err := db.QueryRow("INSERT INTO tracks (title, duration_ms) VALUES ('long', 90000) RETURNING id").Scan(&withLen); err != nil {
t.Fatal(err)
}
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('unknown length') RETURNING id").Scan(&withoutLen); err != nil {
t.Fatal(err)
}
if got, err := repo.TrackDurationMs(ctx, withLen); err != nil || got != 90000 {
t.Errorf("known length: %d, %v", got, err)
}
if got, err := repo.TrackDurationMs(ctx, withoutLen); err != nil || got != 0 {
t.Errorf("unknown length: %d, %v (want 0, nil)", got, err)
}
if _, err := repo.TrackDurationMs(ctx, 99999); !errors.Is(err, listening.ErrTrackNotFound) {
t.Errorf("unknown track: %v", err)
}
})
}
func TestListeningRepoListEvents(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
users, repo := NewUserRepo(db), NewListeningRepo(db)
alice, _ := users.CreateUser(ctx, "alice", "h", false)
bob, _ := users.CreateUser(ctx, "bob", "h", false)
var a, b int64
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('Track A') RETURNING id").Scan(&a); err != nil {
t.Fatal(err)
}
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('Track B') RETURNING id").Scan(&b); err != nil {
t.Fatal(err)
}
record := func(user, track int64, typ listening.EventType, at int64, ms int64, key string) {
t.Helper()
_, err := repo.Record(ctx, listening.Event{
UserID: user, TrackID: track, Type: typ,
OccurredAt: time.Unix(at, 0), DurationPlayedMs: ms, IdempotencyKey: key,
})
if err != nil {
t.Fatal(err)
}
}
record(alice.ID, a, listening.Play, 100, 5_000, "e1")
record(alice.ID, a, listening.Play, 200, 25_000, "e2")
record(alice.ID, b, listening.Complete, 300, 1_000, "e3")
record(alice.ID, b, listening.Skip, 400, 30_000, "e4")
record(bob.ID, a, listening.Play, 250, 40_000, "b1")
titles := func(recs []listening.Record) []string {
var out []string
for _, r := range recs {
out = append(out, r.TrackTitle+"/"+string(r.Type))
}
return out
}
all, total, err := repo.ListEvents(ctx, listening.ListQuery{UserID: alice.ID, Limit: 50})
if err != nil || total != 4 {
t.Fatalf("total = %d err=%v", total, err)
}
if !equal(titles(all), []string{"Track B/skip", "Track B/complete", "Track A/play", "Track A/play"}) {
t.Errorf("order = %v, want newest first", titles(all))
}
if all[0].DurationPlayedMs != 30_000 || !all[0].OccurredAt.Equal(time.Unix(400, 0)) || all[0].TrackID != b || all[0].ID == 0 {
t.Errorf("first record = %+v", all[0])
}
page, total, _ := repo.ListEvents(ctx, listening.ListQuery{UserID: alice.ID, Limit: 2, Offset: 1})
if total != 4 || !equal(titles(page), []string{"Track B/complete", "Track A/play"}) {
t.Errorf("page 2 = %v (total %d)", titles(page), total)
}
past, total, err := repo.ListEvents(ctx, listening.ListQuery{UserID: alice.ID, Limit: 2, Offset: 50})
if err != nil || total != 4 || len(past) != 0 {
t.Errorf("past the end: %v, total %d, err %v", titles(past), total, err)
}
// OnlyCounted keeps `complete` and plays of at least the minimum.
counted, total, _ := repo.ListEvents(ctx, listening.ListQuery{UserID: alice.ID, Limit: 50, OnlyCounted: true, MinPlayedMs: 20_000})
if total != 3 || !equal(titles(counted), []string{"Track B/skip", "Track B/complete", "Track A/play"}) {
t.Errorf("counted = %v (total %d), want the 5 s play left out", titles(counted), total)
}
strict, total, _ := repo.ListEvents(ctx, listening.ListQuery{UserID: alice.ID, Limit: 50, OnlyCounted: true, MinPlayedMs: 60_000})
if total != 1 || !equal(titles(strict), []string{"Track B/complete"}) {
t.Errorf("with a 60 s minimum = %v, want only the complete", titles(strict))
}
// Nobody sees anybody else's history.
mine, total, _ := repo.ListEvents(ctx, listening.ListQuery{UserID: bob.ID, Limit: 50})
if total != 1 || !equal(titles(mine), []string{"Track A/play"}) {
t.Errorf("bob's history = %v (total %d)", titles(mine), total)
}
})
}

View file

@ -23,5 +23,8 @@ jwt_secret = "" # required, 32+ chars: openssl rand -hex 32
access_ttl_minutes = 15 # lifetime of an access token
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, or when it completes
[providers.lastfm]
api_key = ""