geesawra.industries/hydraulophone
An unofficial YouTube Music app for iPhone, iPad, and Mac.
Catalog cache boundary
CachedMusicService is an in-memory decorator around MusicService. It
belongs between the app's feature state and the protocol worker; the worker
still owns request construction, response parsing, sessions, and playback.
What is cached
Only parsed domain values from first catalog pages are stored:
| Resource | TTL |
|---|---|
| Search | 60 seconds |
| Home | 120 seconds |
| Playlists, playlist tracks, and album tracks | 300 seconds |
The cache is bounded to 64 entries and evicts the least recently used entry. Pagination tokens and continuation results are kept only as part of the in-memory request/page flow. They are never persisted. Errors are never cached.
The old array methods (search, playlists, and tracks(in:)) use the
corresponding cached first page. An array-only fake therefore remains
compatible and produces a page with no continuation. Home and album tracks
have no old array capability; an array-only base reports
CachedMusicServiceError.unsupported instead of fabricating content.
Session and concurrency rules
The actor assigns a session generation to catalog work. setSession(_:) first
clears pages and invalidates all catalog tasks, then installs its successor
transition before waiting for an earlier transition; the successor forwards
the session only after that predecessor completes. Catalog requests are
rejected while the full transition chain is in progress. A late completion
from an older generation or a replaced resource task is rejected and cannot
publish or evict newer data. The same rules apply to clearCatalogCache() and
.reload.
Identical requests share one in-flight catalog task. Each in-flight task tracks its waiters. A waiter uses a cancellation handler of its own: cancelling one caller detaches only that waiter and does not cancel the shared task or another caller's wait. When the last waiter detaches, the task is cancelled and removed before a late result can publish; a later caller starts a fresh request. Playback, stream resolution, refresh, proof-related work, credentials, visitor data, and expiring media URLs bypass the cache entirely.
The clock is injectable through CachedMusicService(base:clock:) (or
base:now:) so expiry and race tests do not sleep for a TTL.