Skip to content

README: link a written description of the sync protocol - #54

Merged
Frenzie merged 2 commits into
koreader:masterfrom
pid1:readme-protocol-link
Sep 21, 2026
Merged

Frenzie merged 2 commits into
koreader:masterfrom
pid1:readme-protocol-link

Conversation

@pid1

@pid1 pid1 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

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.json in 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.partialMD5 takes twelve samples and the first offset is 0 rather than 256, because LuaJIT masks the shift count to five bits. leaves.epub and tall.pdf reproduce the digests pinned in spec/unit/util_spec.lua under 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), while app/controllers/1/syncs_controller.lua:5 builds user:%s:document:%s and reads it with hmget, 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 Reviewable

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread README.md Outdated
The protocol
------------

The API is described in [kosync-conformance](https://github.com/pid1/kosync-conformance),

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@Frenzie
Frenzie merged commit 6d0da72 into koreader:master Sep 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants