Initial kosync-rs port

2026-06-12 09:42:23 +00:00
commit 52cec7f8f4
20 changed files with 4827 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,120 @@
+# kosync-rs
+
+`kosync-rs` is a self-contained Rust replacement for
+`koreader/koreader-sync-server`. It keeps the KOReader sync API compatible while
+replacing the old Redis, OpenResty/nginx, Lua/Gin, and runit stack with one
+binary and one SQLite database.
+
+Compatibility target:
+
+- Upstream checkout: `../koreader-sync-server`
+- Upstream commit: `597e0648be0894c535a222f192d7bd583fb3b2dc`
+- Target platforms: Linux `amd64` and Linux `aarch64`
+
+## Quick start
+
+```sh
+docker compose up -d --build
+curl -k -H "Accept: application/vnd.koreader.v1+json" https://127.0.0.1:7200/healthcheck
+```
+
+The compose file stores data in `./data/kosync.sqlite3`, enables user
+registration, exposes HTTPS on `7200`, and exposes plain HTTP on `17200` for
+reverse proxies.
+
+## Binary usage
+
+```sh
+kosync-rs serve
+kosync-rs init-db --db ./data/kosync.sqlite3
+kosync-rs healthcheck --url https://127.0.0.1:7200/healthcheck --insecure
+```
+
+Useful environment variables:
+
+```text
+KOSYNC_DB=./data/kosync.sqlite3
+KOSYNC_HTTP_ADDR=0.0.0.0:17200
+KOSYNC_HTTPS_ADDR=0.0.0.0:7200
+KOSYNC_TLS=auto
+KOSYNC_TLS_CERT=/path/to/cert.pem
+KOSYNC_TLS_KEY=/path/to/key.pem
+ENABLE_USER_REGISTRATION=true
+RUST_LOG=info
+```
+
+`ENABLE_USER_REGISTRATION` matches the old server: registration is enabled only
+when the value is exactly `true` or `1`.
+
+## API
+
+Implemented routes:
+
+```text
+POST /users/create
+GET  /users/auth
+PUT  /syncs/progress
+GET  /syncs/progress/:document
+GET  /healthcheck
+```
+
+Authenticated routes use:
+
+```text
+x-auth-user: <username>
+x-auth-key: <client key>
+```
+
+The server stores and compares the auth key exactly as supplied, matching the
+original implementation.
+
+## Migrating from the old Docker container
+
+Keep the old container running while importing. The old Redis usually listens
+on `127.0.0.1:6379` inside that container, so the helper script joins the old
+container's network namespace.
+
+```sh
+scripts/import-from-old-redis.sh \
+  --old-container kosync \
+  --sqlite ./data/kosync.sqlite3 \
+  --image kosync-rs:latest
+```
+
+Then stop the old container and start the new compose stack:
+
+```sh
+docker stop kosync
+docker compose up -d
+```
+
+Export SQLite data back to the old Redis format:
+
+```sh
+scripts/export-to-old-redis.sh \
+  --old-container kosync \
+  --sqlite ./data/kosync.sqlite3 \
+  --image kosync-rs:latest
+```
+
+The export script will not flush Redis unless `--flush-target` is passed.
+
+## Backups
+
+SQLite backup:
+
+```sh
+sqlite3 ./data/kosync.sqlite3 ".backup './data/kosync-backup.sqlite3'"
+```
+
+Portable JSON backup:
+
+```sh
+kosync-rs export-json --db ./data/kosync.sqlite3 --output backup.json
+kosync-rs import-json --db ./data/kosync.sqlite3 --input backup.json
+```
+
+## License
+
+This project is intended to be compatible with the AGPL-3.0 upstream server and
+is licensed as AGPL-3.0-or-later.