Crate korrosync 

Korrosync - KOReader synchronization server

A Rust implementation of a synchronization server compatible with KOReader’s sync functionality. This server provides a self-hosted alternative for synchronizing reading progress across multiple KOReader devices.

Architecture

The crate is organized into three main layers:

Model Layer (model)

Domain models representing the core business entities:

• model::User - User authentication and profile management
• model::Progress - Reading progress tracking for documents
• model::Error - Model-specific errors

Service Layer (service)

Business logic and data persistence:

• service::db - Database abstraction with trait-based design
• service::db::KorrosyncServiceRedb - Default redb implementation
• service::error - Service-level error types

API Layer (api)

HTTP API compatible with KOReader sync protocol:

• RESTful endpoints for user registration and authentication
• Progress synchronization endpoints
• Rate limiting and authentication middleware

Quick Start

use korrosync::{config::Config, run_server};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from environment or defaults
    let config = Config::from_env();

    // Start the server
    run_server(config).await?;

    Ok(())
}

Configuration

The server can be configured via environment variables:

• KORROSYNC_SERVER_ADDRESS - Server bind address (default: 0.0.0.0:3000)
• KORROSYNC_DB_PATH - Database file path (default: data/db.redb)

When the tls feature is enabled:

• KORROSYNC_USE_TLS - Enable TLS/HTTPS (default: false, accepts: true/1/yes/on or false/0/no/off)
• KORROSYNC_CERT_PATH - Path to TLS certificate file in PEM format (default: tls/cert.pem)
• KORROSYNC_KEY_PATH - Path to TLS private key file in PEM format (default: tls/key.pem)

Features

This crate supports the following optional cargo features:

tls

Enables native TLS/HTTPS support using rustls via axum-server. When enabled, the server can accept HTTPS connections directly without requiring a reverse proxy.

Compile-time enablement:

cargo build --release --features tls

What it provides:

• Direct HTTPS support using the rustls TLS implementation
• TLS configuration fields in config::Server
• Runtime TLS enable/disable via KORROSYNC_USE_TLS environment variable
• Certificate and private key file handling

Note: Without this feature, the server only supports HTTP. You can still use HTTPS by deploying behind a reverse proxy like Nginx or Caddy.

KOReader Compatibility

This server implements the KOReader synchronization API, allowing you to:

• Register user accounts
• Authenticate devices
• Synchronize reading progress across devices

Configure your KOReader device to point to your server URL to start syncing.

Modules

api

HTTP API layer compatible with KOReader sync protocol.

cli

config

Configuration management for Korrosync

logging

model

Domain models for KOReader synchronization.

service

Service layer for business logic and data persistence.

Functions

run_server