From 7047e079069a21e7f2950d9b25f9be983675a69b Mon Sep 17 00:00:00 2001 From: tgiachi Date: Wed, 11 Nov 2026 14:58:47 +0100 Subject: [PATCH 1/2] 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 --- README.md | 22 ++- cmd/sondad/main.go | 2 +- internal/api/http/api_test.go | 2 +- internal/api/http/contract_test.go | 19 ++- internal/api/http/handlers_listen.go | 62 +++++++- internal/api/http/listens_test.go | 155 +++++++++++++++++++ internal/api/http/router.go | 4 +- internal/api/openapi/openapi.yaml | 77 +++++++++- internal/config/config.go | 27 +++- internal/config/config_test.go | 17 +++ internal/listening/listening.go | 150 ++++++++++++++++-- internal/listening/listening_test.go | 219 +++++++++++++++++++++++++-- internal/storage/listening.go | 60 ++++++++ internal/storage/repos_test.go | 100 ++++++++++++ sonda.example.toml | 3 + 15 files changed, 866 insertions(+), 53 deletions(-) create mode 100644 internal/api/http/listens_test.go diff --git a/README.md b/README.md index 45169e1..9bfe5bb 100644 --- a/README.md +++ b/README.md @@ -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 `