Keep realtime progress synchronized while BookWave is foregrounded #40

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

Migrated from GitHub issue #133. Forgejo issue: #40. 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 realtime/library correctness follow-up discovered during physical acceptance. Not part of GitHub PR #93.

User observation

While BookWave is open, progress changed from another Audiobookshelf client does not always appear to update the corresponding BookWave book/shelf immediately. The Audiobookshelf web client does update live when BookWave seeks or syncs, so the expected experience is symmetric: while BookWave is foregrounded, accepted remote progress should appear through the local Room-backed UI without waiting for a full library refresh.

Current implementation

Most of this pipeline already exists:

  • AbsRealtimeConnection subscribes to user_item_progress_updated.
  • ObserveRealtimeUpdatesUseCase sends each ProgressChanged row through LibraryRepository.writeProgress(...).
  • DefaultLibraryRepository.writeProgress(...) writes accepted server progress into Room, preserving the existing conflict rules.
  • Home/library UI observes Room rather than receiving socket data directly.

The current socket collector is started by HomeViewModel.onVisible() and owned by that ViewModel. That may be narrower than the product expectation of one realtime connection for the active profile while BookWave is foregrounded. A second possible explanation is that the progress row reaches the conflict boundary but is correctly or incorrectly rejected there. The implementation should diagnose which case is occurring rather than bypassing the repository.

Audiobookshelf itself currently emits user_item_progress_updated after session progress changes, and its web client commits that pushed progress directly into its user-progress store. BookWave should obtain equivalent low-latency library projection while retaining its stronger local-unsynced conflict protection.

Desired contract

While the app is foregrounded and an authenticated profile is active:

  1. maintain exactly one realtime collector/socket for that active profile;
  2. pass progress pushes through the existing conflict-safe repository owner;
  3. accepted progress writes Room and therefore updates any observing shelf/detail screen without a REST library sweep;
  4. switching profiles cancels the previous profile's collector before the new one can become authoritative;
  5. backgrounding the app closes the socket — persistent background sockets remain out of scope;
  6. returning to foreground reconciles events missed while disconnected using the existing cheap account/progress sync or another already-owned reconciliation path;
  7. realtime progress remains library/resume evidence only and must never directly seek active playback.

Conflict-safety requirement

Do not weaken DefaultLibraryRepository.writeProgress to make the UI look live.

  • A locally unsynced position must still beat remote/socket state.
  • An older/equal server timestamp must still be rejected.
  • Progress for a book the profile cannot currently see must not be written.

Add redaction-safe diagnostics/tests that distinguish:

  • event not received / socket not owned;
  • event received and accepted;
  • event received but deliberately rejected by the conflict boundary.

Do not log title, server host, token, raw session id, or other private media metadata.

Acceptance criteria

  • With BookWave foregrounded on Home, changing a cached visible book's progress from another Audiobookshelf client updates Room/UI within realtime-event latency and does not run a full library refresh.
  • The same behavior holds while another BookWave screen is foregrounded; realtime ownership is not accidentally tied to Home composition lifetime.
  • Exactly one active realtime connection exists for the active profile.
  • Profile A -> B cancels A's collector; a late A event cannot write B state or reappear after the switch.
  • Backgrounding closes the realtime connection; returning foreground reconnects and reconciles any missed progress without assuming socket replay.
  • A newer remote progress push is accepted when the local row is eligible.
  • A local row with unsynced changes still rejects a conflicting remote push.
  • Active BookWave playback is never auto-seeked by a realtime push.
  • Unit/integration tests prove lifecycle ownership plus the accepted/rejected repository path, not only event parsing.
  • Device test: keep BookWave foregrounded, seek/play the same book from the Audiobookshelf web client several times, and confirm the BookWave shelf/detail progress follows without manual refresh.

Relationships

  • Issue #8 / the realtime progress work provides the event and persistence path.
  • GitHub PR #93 / issue #9 consumes accepted realtime evidence for resume freshness; this issue is about keeping the Room-backed library projection live and must not create a second playback-position owner.
  • PRODUCT_SPEC LIB-001 already states: Websocket events update Room; REST refresh is used when websocket is unavailable.

Do not merge or broaden GitHub #93 to fix this; implement as an independent follow-up on current main after GitHub #93 lands.

> Migrated from [GitHub issue #133](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/133). Forgejo issue: #40. 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) realtime/library correctness follow-up discovered during physical acceptance. **Not part of [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93).** ## User observation While BookWave is open, progress changed from another Audiobookshelf client does not always appear to update the corresponding BookWave book/shelf immediately. The Audiobookshelf web client does update live when BookWave seeks or syncs, so the expected experience is symmetric: while BookWave is foregrounded, accepted remote progress should appear through the local Room-backed UI without waiting for a full library refresh. ## Current implementation Most of this pipeline already exists: - `AbsRealtimeConnection` subscribes to `user_item_progress_updated`. - `ObserveRealtimeUpdatesUseCase` sends each `ProgressChanged` row through `LibraryRepository.writeProgress(...)`. - `DefaultLibraryRepository.writeProgress(...)` writes accepted server progress into Room, preserving the existing conflict rules. - Home/library UI observes Room rather than receiving socket data directly. The current socket collector is started by `HomeViewModel.onVisible()` and owned by that ViewModel. That may be narrower than the product expectation of **one realtime connection for the active profile while BookWave is foregrounded**. A second possible explanation is that the progress row reaches the conflict boundary but is correctly or incorrectly rejected there. The implementation should diagnose which case is occurring rather than bypassing the repository. Audiobookshelf itself currently emits `user_item_progress_updated` after session progress changes, and its web client commits that pushed progress directly into its user-progress store. BookWave should obtain equivalent low-latency library projection while retaining its stronger local-unsynced conflict protection. ## Desired contract While the app is foregrounded and an authenticated profile is active: 1. maintain exactly one realtime collector/socket for that active profile; 2. pass progress pushes through the existing conflict-safe repository owner; 3. accepted progress writes Room and therefore updates any observing shelf/detail screen without a REST library sweep; 4. switching profiles cancels the previous profile's collector before the new one can become authoritative; 5. backgrounding the app closes the socket — persistent background sockets remain out of scope; 6. returning to foreground reconciles events missed while disconnected using the existing cheap account/progress sync or another already-owned reconciliation path; 7. realtime progress remains library/resume evidence only and **must never directly seek active playback**. ## Conflict-safety requirement Do **not** weaken `DefaultLibraryRepository.writeProgress` to make the UI look live. - A locally unsynced position must still beat remote/socket state. - An older/equal server timestamp must still be rejected. - Progress for a book the profile cannot currently see must not be written. Add redaction-safe diagnostics/tests that distinguish: - event not received / socket not owned; - event received and accepted; - event received but deliberately rejected by the conflict boundary. Do not log title, server host, token, raw session id, or other private media metadata. ## Acceptance criteria - With BookWave foregrounded on Home, changing a cached visible book's progress from another Audiobookshelf client updates Room/UI within realtime-event latency and **does not run a full library refresh**. - The same behavior holds while another BookWave screen is foregrounded; realtime ownership is not accidentally tied to Home composition lifetime. - Exactly one active realtime connection exists for the active profile. - Profile A -> B cancels A's collector; a late A event cannot write B state or reappear after the switch. - Backgrounding closes the realtime connection; returning foreground reconnects and reconciles any missed progress without assuming socket replay. - A newer remote progress push is accepted when the local row is eligible. - A local row with unsynced changes still rejects a conflicting remote push. - Active BookWave playback is never auto-seeked by a realtime push. - Unit/integration tests prove lifecycle ownership plus the accepted/rejected repository path, not only event parsing. - Device test: keep BookWave foregrounded, seek/play the same book from the Audiobookshelf web client several times, and confirm the BookWave shelf/detail progress follows without manual refresh. ## Relationships - Issue #8 / the realtime progress work provides the event and persistence path. - [GitHub PR #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/93) / issue #9 consumes accepted realtime evidence for **resume freshness**; this issue is about keeping the Room-backed library projection live and must not create a second playback-position owner. - `PRODUCT_SPEC` LIB-001 already states: **Websocket events update Room; REST refresh is used when websocket is unavailable.** Do not merge or broaden [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) to fix this; implement as an independent follow-up on current `main` after [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) lands.
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#40
No description provided.