Hydrate recently active books before the full library refresh #41
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Classification
Post-GitHub #93 library-refresh latency improvement. Independent of GitHub PR #93 and distinct from BW-PLAY-01 / issue #24.
User observation
The common reason to open BookWave is to continue listening, but a book played recently on another Audiobookshelf client may not become the useful/top Continue item until the broader library refresh has progressed far enough. On a large library, that makes the user wait for unrelated catalogue/expansion work before the book they are most likely to press Play on is current.
Current implementation
BookWave already has several good latency optimizations:
HomeViewModel.onVisible()starts a cheap account/progress sync before/alongside the full library refresh.The remaining hole is server-recent activity that the local cache cannot use as a priority hint. In particular, a remotely played book can be absent/incomplete locally, and
LibraryRepository.writeProgress()correctly refuses progress for a book that is not currently visible in the local profile catalogue.cachedLibrary(...).isInProgress()can only prioritize IDs Room already knows about.BookWave already has a captured and implemented
GET /api/me/listening-sessionscontract, newest first, and itsListeningSessiondomain model includesbookId.LibraryApi.fetchBook(profileId, bookId)already performs a targeted expanded item fetch with profile authorization and progress. Those seams make a bounded recent-book hot set possible without changing the authoritative full refresh.Current Audiobookshelf source also exposes
GET /api/me/items-in-progress, which may eventually be a more direct source for this hot set. BookWave has not captured that response contract, so it must not be adopted without a real supported-server fixture and contract test.Desired behavior
Before, or concurrently ahead of, the expensive bulk item-expansion phase:
A safe initial implementation can use the already-captured first page of listening sessions as priority hints only. Session
reachedAtmust not be promoted into a second progress source; progress/item state must continue through the existing authoritative repository/API paths.If
/api/me/items-in-progressproves a better fit, first capture it against a supported Audiobookshelf version and add fixture/contract coverage. Preserve a compatible fallback rather than silently raising BookWave's minimum server contract.Permission / admission clarification
BookWave's account grant has two separate visibility dimensions: library access and item/tag filtering. A profile can be allowed to a library while Audiobookshelf filters individual items inside it.
fetchBook(profileId, bookId)re-checks the returnedlibraryId, but that library-level check alone is not proof that an arbitrary session-derived item ID is visible through the profile's filtered catalogue.Therefore a pre-catalogue hot-set write must not assume that a recent-session ID is permission evidence.
Before hydrating a listening-session candidate ahead of catalogue visibility, implementation must either:
If the first option cannot be proven from a real supported server, use the second. Do not weaken BookWave's item/tag privacy boundary for refresh latency.
Important boundaries
Not a second refresh architecture
The hot-set stage only changes which useful books arrive first. The existing full library refresh still owns:
Hot-set failure must not be interpreted as deletion and must not make a healthy cached shelf disappear.
Not BW-PLAY-01
Issue #24 owns which audiobook this physical device remembers as its locally last-played book. Remote activity must not rewrite that local ownership fact.
This issue instead improves the server-derived Room/library projection: if another device recently played B, B can become fresh and prominent in the server-derived Continue shelf quickly, while a future
Continue this device's remembered bookaction may still point to locally remembered A according to #24.Preserve conflict safety
Acceptance criteria
API investigation gate
Compare these options before implementation:
GET /api/me/listening-sessions-> deduplicatedbookIdhints -> existingfetchBook, subject to the admission rule above.GET /api/me/items-in-progressfrom current Audiobookshelf source. Capture a real supported-server response and contract-test it before use.Choose the smallest path that measurably improves time-to-useful-Continue without inventing or duplicating progress ownership.
Do not create a separate
/items-in-progressimplementation merely because upstream source exposes the route. A separate API-contract investigation is justified only if the already-captured listening-session path cannot meet the measured latency goal or if supported-version/permission evidence is needed before choosing the implementation.Relationships
Do not merge or broaden GitHub #93 to implement this. Sequence it through
docs/roadmap.md, which remains the canonical work-order authority.