Sync drift: no recovery when Kobo loses books server thinks are delivered #11

New issue

Open

opened 2026-04-13 10:57:10 +02:00 by arne · 0 comments

arne commented

2026-04-13 10:57:10 +02:00

Owner

Symptoms

Books are shelved on the server and marked delivered=1 in the latest sync session, but absent from the Kobo's library. Reproduced today: 2/12 shelved books missing on device.

Root cause

internal/kobo/sync.go (line ~173) marks books delivered without emitting any envelope when their meta_rev and file_hash match the previous session — the "already there, nothing to do" fast path.

If the Kobo's local DB lost a book (manual delete on device, factory reset, sync interruption, swap to new device), the server has no signal of the drift and never re-sends. The book is stuck in a "server thinks delivered, device doesn't have it" state with no recovery path.

Workaround (confirmed working)

On the shelf page: unshelve the missing book → sync from Kobo → reshelve → sync again. Forces removed→added envelopes.

Possible fixes

Reset-sync action per device — single button on /shelf next to "Regenerate". Deletes all sync sessions for the device; next sync rebuilds from scratch (every shelved book goes through added → NewEntitlement). Low risk, fixes drift in one shot.
Per-book "Re-send to Kobo" action — more granular, but more UI weight.
Inferred-library debug view — log what the Kobo touches (covers, downloads, StateGet/StatePut) and surface "last seen by Kobo" per book. Half-picture (unopened books after initial sync are invisible), but useful telemetry. Would fit naturally on the errata page as another diagnostic.

Out of scope (Kobo protocol limit)

The storefront API has no way to query what books the Kobo currently holds. Only the device's local KoboReader.sqlite (USB-only) is authoritative.

Why not now

Workaround is acceptable. Errata page is the natural home if/when we build a diagnostic view.

## Symptoms Books are shelved on the server and marked `delivered=1` in the latest sync session, but absent from the Kobo's library. Reproduced today: 2/12 shelved books missing on device. ## Root cause `internal/kobo/sync.go` (line ~173) marks books delivered without emitting any envelope when their `meta_rev` and `file_hash` match the previous session — the "already there, nothing to do" fast path. If the Kobo's local DB lost a book (manual delete on device, factory reset, sync interruption, swap to new device), the server has no signal of the drift and never re-sends. The book is stuck in a "server thinks delivered, device doesn't have it" state with no recovery path. ## Workaround (confirmed working) On the shelf page: unshelve the missing book → sync from Kobo → reshelve → sync again. Forces removed→added envelopes. ## Possible fixes - **Reset-sync action per device** — single button on /shelf next to "Regenerate". Deletes all sync sessions for the device; next sync rebuilds from scratch (every shelved book goes through `added` → `NewEntitlement`). Low risk, fixes drift in one shot. - **Per-book "Re-send to Kobo" action** — more granular, but more UI weight. - **Inferred-library debug view** — log what the Kobo touches (covers, downloads, StateGet/StatePut) and surface "last seen by Kobo" per book. Half-picture (unopened books after initial sync are invisible), but useful telemetry. Would fit naturally on the errata page as another diagnostic. ## Out of scope (Kobo protocol limit) The storefront API has no way to query what books the Kobo currently holds. Only the device's local KoboReader.sqlite (USB-only) is authoritative. ## Why not now Workaround is acceptable. Errata page is the natural home if/when we build a diagnostic view.

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

arne/books#11

No description provided.

Rows
Columns