Hydrate recently active books before the full library refresh #41

Closed
opened 2026-09-18 08:48:07 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #134. Forgejo issue: #41. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

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:

  • Home renders cached Room content immediately.
  • HomeViewModel.onVisible() starts a cheap account/progress sync before/alongside the full library refresh.
  • the library catalogue is written before per-item expansion;
  • expanded item fetching prioritizes books that are already locally known as in progress;
  • unchanged expanded items may be skipped by server revision.

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-sessions contract, newest first, and its ListeningSession domain model includes bookId. 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:

  1. obtain a bounded set of recently relevant server book IDs;
  2. deduplicate the IDs while preserving useful recency;
  3. admit only candidates whose visibility to the active profile is proven;
  4. for admitted candidate books that are missing or insufficiently hydrated locally, use the existing targeted book-fetch boundary to hydrate them into Room;
  5. let Room observers immediately update Continue/recently-played shelf state;
  6. then continue the existing catalogue/full expansion/reconciliation as the authoritative library refresh.

A safe initial implementation can use the already-captured first page of listening sessions as priority hints only. Session reachedAt must 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-progress proves 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 returned libraryId, 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:

  • capture and contract-test supported-server behavior proving the targeted item route itself enforces the same active-profile item/tag visibility boundary for the relevant BookWave-supported server versions; or
  • use the active profile's actual catalogue as the admission fact, intersecting/prioritizing recent candidate IDs as catalogue pages arrive and hydrating them before the ordinary bulk expansion.

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:

  • complete catalogue visibility;
  • additions/removals;
  • permission-scoped reconciliation;
  • authors/series/chapters/tracks and all normal expansion work;
  • final sync outcome.

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 book action may still point to locally remembered A according to #24.

Preserve conflict safety

  • local unsynced progress must not be overwritten;
  • inaccessible/revoked/tag-hidden books must not be hydrated into the profile;
  • server timestamps/revisions remain authoritative for deciding whether existing content can be skipped;
  • candidate session IDs/order are hints, not permission or deletion evidence.

Acceptance criteria

  • Opening Home does not wait for full-library expansion before a remotely recent cached book's progress/reordering can update; the existing cheap progress sync remains on the fast path.
  • A remotely recent book that is missing or insufficiently hydrated locally can be fetched through a bounded targeted hot-set stage and becomes usable in Room/Continue before the bulk expansion finishes.
  • Candidate admission is proven against the active profile's item/tag visibility boundary; a session-derived ID alone is never treated as permission evidence.
  • The hot-set does not page listening history to exhaustion. Its request count is bounded independently of account history size.
  • Multiple recent sessions for the same book cause at most one targeted hydration fetch in the stage.
  • A candidate that is already fully current is not redundantly expanded.
  • A book hydrated by the hot-set is not needlessly fetched again in the later sweep when its stored remote revision proves it current.
  • A candidate the active profile cannot access is not written.
  • Local unsynced progress survives hot-set and full-refresh writes.
  • Hot-set network failure leaves cached content usable and the normal full refresh/retry semantics intact.
  • Full refresh still completes catalogue reconciliation and remains the sole authority for deletions/visibility reconciliation.
  • Automated tests prove ordering/request counts, deduplication, authorization/tag filtering, unsynced-progress protection, hot-set failure isolation, and no redundant later expansion.
  • Device test on a realistically large library: play/seek a different book on the Audiobookshelf web client, foreground BookWave, and confirm the likely Continue book is current/usable materially before the full refresh completes.

API investigation gate

Compare these options before implementation:

  1. Already captured: bounded newest-first GET /api/me/listening-sessions -> deduplicated bookId hints -> existing fetchBook, subject to the admission rule above.
  2. Potentially better but currently unverified in BookWave: GET /api/me/items-in-progress from 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-progress implementation 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

  • Issue #40 should make accepted realtime progress keep already-known books current while BookWave is foregrounded.
  • Issue #24 / BW-PLAY-01 owns device-local remembered-book identity and must remain independent.
  • GitHub PR #93 / issue #9 owns resume position freshness once Play is requested, not library hydration or refresh ordering.

Do not merge or broaden GitHub #93 to implement this. Sequence it through docs/roadmap.md, which remains the canonical work-order authority.

> Migrated from [GitHub issue #134](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/134). Forgejo issue: #41. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Post-[GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) library-refresh latency improvement. Independent of [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/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: - Home renders cached Room content immediately. - `HomeViewModel.onVisible()` starts a cheap account/progress sync before/alongside the full library refresh. - the library catalogue is written before per-item expansion; - expanded item fetching prioritizes books that are **already locally known** as in progress; - unchanged expanded items may be skipped by server revision. 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-sessions` contract, newest first, and its `ListeningSession` domain model includes `bookId`. `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: 1. obtain a **bounded** set of recently relevant server book IDs; 2. deduplicate the IDs while preserving useful recency; 3. admit only candidates whose visibility to the active profile is proven; 4. for admitted candidate books that are missing or insufficiently hydrated locally, use the existing targeted book-fetch boundary to hydrate them into Room; 5. let Room observers immediately update Continue/recently-played shelf state; 6. then continue the existing catalogue/full expansion/reconciliation as the authoritative library refresh. A safe initial implementation can use the already-captured first page of listening sessions as **priority hints only**. Session `reachedAt` must 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-progress` proves 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 returned `libraryId`, 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: - capture and contract-test supported-server behavior proving the targeted item route itself enforces the same active-profile item/tag visibility boundary for the relevant BookWave-supported server versions; or - use the active profile's actual catalogue as the admission fact, intersecting/prioritizing recent candidate IDs as catalogue pages arrive and hydrating them before the ordinary bulk expansion. 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: - complete catalogue visibility; - additions/removals; - permission-scoped reconciliation; - authors/series/chapters/tracks and all normal expansion work; - final sync outcome. 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 book` action may still point to locally remembered A according to #24. ### Preserve conflict safety - local unsynced progress must not be overwritten; - inaccessible/revoked/tag-hidden books must not be hydrated into the profile; - server timestamps/revisions remain authoritative for deciding whether existing content can be skipped; - candidate session IDs/order are hints, not permission or deletion evidence. ## Acceptance criteria - Opening Home does not wait for full-library expansion before a remotely recent **cached** book's progress/reordering can update; the existing cheap progress sync remains on the fast path. - A remotely recent book that is missing or insufficiently hydrated locally can be fetched through a bounded targeted hot-set stage and becomes usable in Room/Continue before the bulk expansion finishes. - Candidate admission is proven against the active profile's item/tag visibility boundary; a session-derived ID alone is never treated as permission evidence. - The hot-set does not page listening history to exhaustion. Its request count is bounded independently of account history size. - Multiple recent sessions for the same book cause at most one targeted hydration fetch in the stage. - A candidate that is already fully current is not redundantly expanded. - A book hydrated by the hot-set is not needlessly fetched again in the later sweep when its stored remote revision proves it current. - A candidate the active profile cannot access is not written. - Local unsynced progress survives hot-set and full-refresh writes. - Hot-set network failure leaves cached content usable and the normal full refresh/retry semantics intact. - Full refresh still completes catalogue reconciliation and remains the sole authority for deletions/visibility reconciliation. - Automated tests prove ordering/request counts, deduplication, authorization/tag filtering, unsynced-progress protection, hot-set failure isolation, and no redundant later expansion. - Device test on a realistically large library: play/seek a different book on the Audiobookshelf web client, foreground BookWave, and confirm the likely Continue book is current/usable materially before the full refresh completes. ## API investigation gate Compare these options before implementation: 1. **Already captured:** bounded newest-first `GET /api/me/listening-sessions` -> deduplicated `bookId` hints -> existing `fetchBook`, subject to the admission rule above. 2. **Potentially better but currently unverified in BookWave:** `GET /api/me/items-in-progress` from 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-progress` implementation 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 - Issue #40 should make accepted realtime progress keep already-known books current while BookWave is foregrounded. - Issue #24 / BW-PLAY-01 owns device-local remembered-book identity and must remain independent. - [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) / issue #9 owns resume **position freshness once Play is requested**, not library hydration or refresh ordering. Do not merge or broaden [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) to implement this. Sequence it through `docs/roadmap.md`, which remains the canonical work-order authority.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#41
No description provided.