daniel/deepdrft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity

docs: close §2.5 open question — add GET api/track/random endpoint

Browse Source
This commit is contained in:
daniel-c-harvey
2026-06-07 17:21:50 -04:00
parent ea535e0c7e
commit 4b1a68aa29
1 changed files with 6 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLAN.md
+6 -2
View File
@@ -169,9 +169,13 @@ So the launch logic is **not** duplicated from `TracksView` — both call into t
- Audio actually plays on the first click after a cold load on Chrome and Safari (the user-gesture/AudioContext constraint is satisfied). If Safari needs the context warmed inside the gesture, that hook is added to the player service, not worked around in the menu.
- While selection is in flight, the button is disabled to prevent double-launch.
#### Open question
#### Decision: server-side endpoint
- **Server-side `GET api/track/random` now, or defer?** The client-side count-then-fetch strategy is correct and ships without touching the API. A server endpoint is cleaner and is the natural home for "exclude current track" and "shuffle within filter," but those don't exist yet. Recommendation: **ship client-side now; revisit the endpoint when 2.2/2.3 land server-side filtering**, at which point "shuffle within this genre/search" makes the endpoint clearly worth it. Decision is Daniel's if he wants the endpoint up front.
- **Decided (2026-06-07):** Add `GET api/track/random` to `DeepDrftAPI` as part of this feature. The client's `GetRandomTrack()` calls this endpoint directly rather than building the selection strategy client-side. Rationale (Daniel): "you don't build a skyscraper from the top down" — the endpoint is the right foundation, and it is the natural home for "exclude current track" and "shuffle within filter" when 2.2/2.3 land server-side filtering.
- **New API surface:** `GET api/track/random` (unauthenticated, mirroring `GET api/track/page`) returning a single `TrackDto` via `ORDER BY RANDOM() LIMIT 1` (or the EF-Core equivalent) server-side. New `TrackService` method + `TrackClient` method to reach it.
- **Spec sections superseded by this decision** (the two-request client strategy was written before the endpoint was chosen — read them as historical context, not as the build target):
- *Random selection strategy* (above): the count-then-fetch math no longer applies. `GetRandomTrack()` is now a single call to `GET api/track/random`; the two-request strategy and its "at most two round-trips" property are obsolete.
- *Acceptance criteria*: "Selection issues **at most two** HTTP requests, and exactly one when the library fits in a single page" → selection issues **exactly one** request (`GET api/track/random`). "selects a track uniformly at random across the *entire* library" still holds; it is now satisfied server-side. The `ITrackDataService.GetRandomTrack()` seam is unchanged — only its implementation moves from client math to a single endpoint call.
### 2.3 Search and filter on the gallery