feat(kosync): bridge Tome positions to KOSync clients, hash auto-link, manual link UI - #159
Merged
Conversation
…, manual link UI (#156) The KOSync-compat endpoint was an island: GET only ever served what a KOSync client had pushed, so web-reader progress never reached stock KOReader sync or Readest, and document maps only formed via the OPDS pending-download guess. - GET /syncs/progress/{document} now serves the newer of the last KOSync push and Tome's own position (web/plugin), percentage-precision, with the stored locator passed through as-is. Read-only by design: KOSync pushes never write TomeSyncPosition or PositionHistory, so plugin devices are unaffected (pinned by regression test). - Documents auto-link deterministically via ko_hashes (the KOSync document id IS KOReader's partial-MD5, which Readest also computes - confirmed in #156) on both push and pull; visibility-gated; the OPDS heuristic stays as fallback only. - Book page grows a "Link KOReader sync" picker for unlinked synced documents (endpoint existed, had no UI). - KOSync status writes route through the shared sticky-completion rule (0.99 finish, sticky read, finished_at) instead of two inline 0.95 non-sticky copies. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
#156) New Integrations page documenting sync for clients that don't run the Tome plugin (Readest, stock KOReader Progress sync): setup, the percentage-precision position bridge, hash auto-linking, the manual link picker, and troubleshooting. Marked unreleased until the next tag. Screenshot captured on the showcase in all three themes via a new self-healing kosync-link shot definition (seeds an unlinked Readest push over the API, links it away to an un-shot book afterwards so reruns and other shots stay clean). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #156.
Problem
The KOSync-compat endpoint (stock KOReader sync, Readest) was an island:
GET /syncs/progress/{document}only ever served what a KOSync client itself had pushed, so progress from the web reader (or a TomeSync device) never reached those apps. Document maps only formed via the OPDS pending-download heuristic, which requires downloading via OPDS immediately before the first sync - otherwisekosync_document_mapstays empty.Changes
TomeSyncPositionorPositionHistory- third-party clients cannot move positions on devices running the TomeSync plugin. That guarantee is pinned by a regression test.documentid is KOReader's partial-MD5, which Tome records for every artifact it scans or serves (ko_hashes) and which Readest also computes (confirmed by the reporter against their own DB). Documents now auto-link by hash on both push and pull, visibility-gated; the OPDS heuristic is demoted to fallback for files Tome has never seen.finished_atrecorded) replacing two inline non-sticky 0.95 copies inkosync.pyandlink-kosync.Testing
test_kosync_bridge.py(13 tests): hash auto-link on push and pull, OPDS fallback, hash-beats-guess precedence, visibility gate, LWW in both directions, first-pull bridge with no prior push, unlinked-account isolation, sticky/0.99 status semantics, manual-link endpoint, and the no-write guarantee toward plugin state.TomeSyncPositionstill holds the web position untouched.No plugin update, no migration.