fix(listening): report a deleted account first and document one event per play

- fix: a listen from a deleted account is answered 401 before the track or the
  duration is looked at, so a client that signs out on 401 does it whatever
  else is wrong with the request (UserExists on the store)
- docs: one event per play, sent when the play ends or is abandoned, with one
  idempotency key per play. An event cannot be upgraded afterwards: a key that
  was already used is ignored even if the type or duration differ, and a new
  key would count the same play twice. The README no longer says to report at
  20 seconds, which led straight into that trap, and no longer hard-codes the
  minimum
- test: the SQL filter at exactly the threshold and just under it, the order of
  events within the same second, the order of checks for a deleted account
This commit is contained in:
tgiachi 2026-11-11 15:02:28 +01:00
commit 32068f7cf6
7 changed files with 126 additions and 9 deletions

View file

@ -141,7 +141,7 @@ 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; 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`:
**7. Report a listen.** Streaming never counts as a listen. The player reports one event per play, when the play ends or is abandoned, with the time actually played. Use one idempotency key per play: a retry with the same key is harmless, but a key that was already used is ignored even if the event differs, so an event cannot be upgraded later. An event counts as a listen when it is `complete` or lasted at least the configured minimum (20 seconds by default); a shorter play is stored too, but does not count:
```bash
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"play\",\"duration_played_ms\":25000,\"idempotency_key\":\"demo-1\"}"

View file

@ -376,9 +376,16 @@ func TestListenWithADeletedAccountsTokenIsUnauthorized(t *testing.T) {
if r := do(t, h, "DELETE", userPath(bobID), admin, nil); r.Code != http.StatusNoContent {
t.Fatalf("delete: %d", r.Code)
}
body := map[string]any{"track_id": 1, "event_type": "play", "idempotency_key": "k"}
r := do(t, h, "POST", "/api/v1/listens", bob, body)
if r.Code != http.StatusUnauthorized || errCode(r) != "unauthorized" {
t.Fatalf("listen after the account was deleted: %d %v", r.Code, r.Body)
// Whatever else is wrong with the request, the deleted account is told
// "unauthorized" first.
for name, body := range map[string]map[string]any{
"a valid event": {"track_id": 1, "event_type": "play", "idempotency_key": "k"},
"an unknown track": {"track_id": 999, "event_type": "play", "idempotency_key": "k"},
"an absurd length": {"track_id": 1, "event_type": "play", "duration_played_ms": 1, "idempotency_key": "k2"},
} {
r := do(t, h, "POST", "/api/v1/listens", bob, body)
if r.Code != http.StatusUnauthorized || errCode(r) != "unauthorized" {
t.Errorf("%s after the account was deleted: %d %v", name, r.Code, r.Body)
}
}
}

View file

@ -780,9 +780,14 @@ paths:
operationId: recordListen
summary: Record a listen
description: |
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`.
Clients report what the listener did: **one event per play**, when the play ends or is
abandoned, with the time actually played (`complete` if it finished, `skip` if the listener
moved on, `play` if it simply stopped).
Use **one `idempotency_key` per play**. A retry with the same key from the same user is
recorded once and answered with `duplicate`. An event cannot be upgraded afterwards: a later
event with a key that was already used is ignored, even if its type or duration differ, and
sending it with a new key would count the same play twice.
**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).
@ -1161,7 +1166,7 @@ components:
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).}
idempotency_key: {type: string, description: "One per play, 1 to 128 bytes (UTF-8). A key that was already used is ignored."}
ListenResult:
type: object

View file

@ -109,6 +109,8 @@ type Store interface {
// (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)
// UserExists reports whether the account is still there.
UserExists(ctx context.Context, userID int64) (bool, 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)
@ -155,6 +157,16 @@ func (s *Service) Record(ctx context.Context, e Event) (Result, error) {
return Result{}, fmt.Errorf("%w: duration_played_ms cannot be negative", ErrInvalidEvent)
}
// An access token outlives a deleted account for a few minutes: say so
// before looking at anything else about the request.
exists, err := s.store.UserExists(ctx, e.UserID)
if err != nil {
return Result{}, err
}
if !exists {
return Result{}, ErrUserNotFound
}
length, err := s.store.TrackDurationMs(ctx, e.TrackID)
if err != nil {
return Result{}, err

View file

@ -17,6 +17,8 @@ type fakeStore struct {
durErr error
durCalls int
userGone bool
records []Record
total int
lastQ ListQuery
@ -27,6 +29,8 @@ func (f *fakeStore) Record(_ context.Context, e Event) (bool, error) {
return f.created, f.err
}
func (f *fakeStore) UserExists(context.Context, int64) (bool, error) { return !f.userGone, nil }
func (f *fakeStore) TrackDurationMs(context.Context, int64) (int64, error) {
f.durCalls++
return f.durationMs, f.durErr
@ -277,3 +281,24 @@ func TestListPropagatesStoreErrors(t *testing.T) {
t.Fatalf("err = %v", err)
}
}
// A token outlives a deleted account for a few minutes. Whoever presents one
// must be told "unauthorized" first, whatever else is wrong with the request.
func TestADeletedAccountIsReportedBeforeAnythingElse(t *testing.T) {
store := &fakeStore{userGone: true, durErr: ErrTrackNotFound}
_, err := newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: Play, DurationPlayedMs: 1000, IdempotencyKey: "k"})
if !errors.Is(err, ErrUserNotFound) {
t.Fatalf("err = %v, want ErrUserNotFound before the track is looked at", err)
}
if store.durCalls != 0 || len(store.got) != 0 {
t.Error("the track was looked up or an event stored for a deleted account")
}
store = &fakeStore{userGone: true, durationMs: 100_000}
_, err = newSvc(store).Record(context.Background(),
Event{UserID: 1, TrackID: 2, Type: Play, DurationPlayedMs: 9_999_999, IdempotencyKey: "k"})
if !errors.Is(err, ErrUserNotFound) {
t.Fatalf("an implausible duration from a deleted account: err = %v, want ErrUserNotFound", err)
}
}

View file

@ -134,3 +134,12 @@ func (r *ListeningRepo) ListEvents(ctx context.Context, q listening.ListQuery) (
}
return records, total, rows.Err()
}
// UserExists reports whether the account is still there.
func (r *ListeningRepo) UserExists(ctx context.Context, userID int64) (bool, error) {
ok, err := r.db.NewSelect().Model((*userRow)(nil)).Where("id = ?", userID).Exists(ctx)
if err != nil {
return false, fmt.Errorf("check user: %w", err)
}
return ok, nil
}

View file

@ -251,3 +251,62 @@ func TestListeningRepoListEvents(t *testing.T) {
}
})
}
func TestListeningRepoUserExists(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
users, repo := NewUserRepo(db), NewListeningRepo(db)
u, _ := users.CreateUser(ctx, "here", "h", false)
if ok, err := repo.UserExists(ctx, u.ID); err != nil || !ok {
t.Errorf("existing user: %v, %v", ok, err)
}
if ok, err := repo.UserExists(ctx, 99999); err != nil || ok {
t.Errorf("unknown user: %v, %v", ok, err)
}
_ = users.DeleteUser(ctx, u.ID)
if ok, _ := repo.UserExists(ctx, u.ID); ok {
t.Error("a deleted user still exists")
}
})
}
// The SQL filter must agree with the Go rule exactly at the threshold, and
// events of the same second must come out in a fixed order.
func TestListeningRepoThresholdBoundaryAndTies(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
u, _ := NewUserRepo(db).CreateUser(ctx, "alice", "h", false)
repo := NewListeningRepo(db)
var track int64
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('T') RETURNING id").Scan(&track); err != nil {
t.Fatal(err)
}
add := func(typ listening.EventType, ms int64, key string) {
t.Helper()
if _, err := repo.Record(ctx, listening.Event{
UserID: u.ID, TrackID: track, Type: typ,
OccurredAt: time.Unix(1_700_000_000, 0), // the same second for all
DurationPlayedMs: ms, IdempotencyKey: key,
}); err != nil {
t.Fatal(err)
}
}
add(listening.Play, 19_999, "under")
add(listening.Play, 20_000, "exactly")
add(listening.Play, 20_001, "over")
counted, total, err := repo.ListEvents(ctx, listening.ListQuery{UserID: u.ID, Limit: 50, OnlyCounted: true, MinPlayedMs: 20_000})
if err != nil || total != 2 {
t.Fatalf("counted total = %d err=%v, want the event at exactly 20 s included and 19.999 s left out", total, err)
}
if counted[0].DurationPlayedMs != 20_001 || counted[1].DurationPlayedMs != 20_000 {
t.Errorf("same-second events came out as %d, %d; want the later insert first (id DESC)",
counted[0].DurationPlayedMs, counted[1].DurationPlayedMs)
}
all, _, _ := repo.ListEvents(ctx, listening.ListQuery{UserID: u.ID, Limit: 50})
if len(all) != 3 || all[0].DurationPlayedMs != 20_001 || all[2].DurationPlayedMs != 19_999 {
t.Errorf("order of all three = %+v", all)
}
})
}