feat(sync): server-side position authority — verify/heal progress anchors

Progress submissions now carry (percentage, context_text, epubcfi) and
the server becomes the position authority:

- VerifyProgressAnchor resolves the submitted standard CFI against the
  book's own XHTML, extracts the text at the anchor, and cross-checks it
  with the submitted context_text. A mismatch heals the anchor by text
  search (percentage disambiguates repeats) instead of storing a bad
  position.
- The anchor's block element is derived as a cssSelector plus a block-
  relative character offset, and served on progress GET alongside the
  anchor document's href — readium-native handles that let clients
  re-open a book without parsing CFIs themselves.
- context_text-only submissions (no CFI — the dumb-client tier) are
  anchored structurally from the context text.

Motivation: cross-client progress sync (web foliate CFIs, KOReader CRE
xpointers, readium-native apps) previously trusted each client's own
locator math; the app's EPUB restore drifted ±pages because readium's
paginator does not lay out far-from-viewport columns and the foliate-
ported CFI walk ran against readium's mutated WebView DOM. Server-side
verification heals both classes at ingest.
This commit is contained in:
John O'Keefe
2026-09-26 14:43:34 -04:00
parent 1c1f5cf1bb
commit aec226af1a
6 changed files with 572 additions and 0 deletions
+3
View File
@@ -121,6 +121,9 @@ func main() {
// Create library service
libraryService := services.NewLibraryService(queries)
// The progress service verifies submitted anchors against the book
// itself — it needs to resolve library-relative file paths.
progressService.SetMediaPathResolver(libraryService)
// Sync Go AllowedExtensions into DB so API clients see correct extensions
libraryService.SyncAllowedExtensions(context.Background())