Repository navigation
README: link a written description of the sync protocol - #54
Merged
Merged
Conversation
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Frenzie
reviewed
Sep 21, 2026
| The protocol | ||
| ------------ | ||
|
|
||
| The API is described in [kosync-conformance](https://github.com/pid1/kosync-conformance), |
Member
There was a problem hiding this comment.
Let's make it something like this for clarity.
Suggested change
| The API is described in [kosync-conformance](https://github.com/pid1/kosync-conformance), | |
| The API is described in the third-party [kosync-conformance](https://github.com/pid1/kosync-conformance), |
Co-Authored-By: Claude Opus 5 (1M context) <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
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.
The API has never been written down. Issue #11 asked for a description in 2018 and was closed with "never mind, I found it", and someone asked again in 2020; in both cases the answer was to read the source.
api.jsonin the client plugin gives paths and parameters but no response bodies, no error codes, no hash algorithm and no conflict semantics, so every reimplementation has had to guess at the same set of details and they have guessed differently.This adds a short section to the README linking a written description of the protocol, together with a verifier that checks an implementation against it in one command.
The specification is descriptive rather than normative: it documents what this server does, and where it and the client disagree it says so. It was validated by running the verifier against this server, not only against my own, and two of the assertions are recorded as SHOULD rather than MUST because this implementation does not satisfy them. One of those is the routing defect I filed separately.
The document hash is settled there against KOReader's own fixtures rather than by argument:
util.partialMD5takes twelve samples and the first offset is 0 rather than 256, because LuaJIT masks the shift count to five bits.leaves.epubandtall.pdfreproduce the digests pinned inspec/unit/util_spec.luaunder the first reading and not the second. Two implementations in the wild currently take eleven samples.The spec text is CC0, so anything in it can be copied into this repository or any other without attribution obligations, including into the README directly if you would rather have it here than linked.
One thing I noticed while checking the document against this server, not included in this change because it is a separate fix: the storage layout at the end of the README describes flat suffixed keys (
user:chrox:document:<hash>:percentage), whileapp/controllers/1/syncs_controller.lua:5buildsuser:%s:document:%sand reads it withhmget, so a document is one hash rather than three keys. Happy to correct that here or in its own pull request, whichever you prefer.This change is