Booklore Sync - KOReader Plugin

Version: 1.0.0-beta
Status: Ready for Testing
Last Updated: February 21, 2026

Automatically track your reading sessions in KOReader and sync them to your Booklore server silently in the background.

---

Features

📚 Automatic Session Tracking

• Smart Detection - Automatically starts tracking when you open a book
• Progress Tracking - Records reading progress (0-100%) with configurable precision
• Duration Tracking - Measures time spent reading in seconds
• Location Tracking - Tracks page numbers and positions
• Format Support - Works with EPUB, PDF, DJVU, CBZ, CBR files
• Suspend/Resume - Handles device sleep and wake events

📊 Session Validation

• Minimum Duration - Only save sessions longer than X seconds (default: 30)
• Minimum Pages - Only save sessions with Y+ pages read (default: 5)
• Detection Mode - Choose duration-based OR pages-based validation
• Skip Zero Progress - Automatically reject sessions with no progress

🔄 Two-Way Library Synchronization

• Auto-Download Missing Books - Automatically pulls down EPUBs from your designated Booklore shelf that aren't on your device yet.
• Bidirectional Deletions - Automatically deletes local copies of books that have been removed from your online Booklore shelf, keeping your device clean.
• Interactive Shelf Picker - No need to type UUIDs manually! Browse and select your Booklore shelves natively within the KOReader UI.

🔄 Offline Support & Recovery

• Queue When Offline - Sessions saved locally when server unavailable
• Auto-Sync - Syncs queued sessions when connection restored
• Retry Logic - Failed syncs automatically retried with counter
• Token Recovery - On-the-fly 401/403 token refresh preventing thread crashes
• Book ID Resolution - Offline sessions resolved by hash during sync
• Batch Upload - Historical sessions uploaded in batches (up to 100 per batch) for 10-20x faster syncing, with automatic fallback to individual uploads for older servers

🗄️ Smart Caching

• Book Hash Calculation - Fast MD5 fingerprinting using sample-based algorithm
• Book ID Mapping - Maps file hashes to Booklore book IDs
• SQLite Database - Robust local caching with migrations
• File Path Caching - Remembers books by file location

⚙️ Flexible Configuration

• Server URL - Connect to any Booklore server
• Authentication - Username/password with MD5 hashing
• Session Thresholds - Customize min duration and pages
• Progress Decimals - 0-5 decimal places for progress tracking
• Manual/Auto Sync - Choose when sessions are synced
• Silent Mode - Disable popup notifications

🔄 UI Progress

• Dynamic UI Tracking - Live progress for long-running sync and scans

---

Quick Start

Installation

1. Copy plugin to KOReader:

   cp -r bookloresync.koplugin ~/.config/koreader/plugins/

2. Restart KOReader completely (not just sleep mode)

3. Configure the plugin:

   • Open KOReader
   • Go to Tools → Booklore Sync → Settings
   • Enter your server URL, username, and password
   • Tap Test Connection to verify

4. Setup Library Sync (Optional):

   • Tap Shelf to interactively select your Booklore shelf
   • Set your Download Directory where books should be saved
   • Enable Auto-Sync from Shelf & Bidirectional Sync in Settings

First Session

1. Open any book - Hash calculated, book ID fetched
2. Read for 30+ seconds - Session tracked automatically
3. Close the book - Session validated and synced
4. Check your Booklore server - Session appears!

For detailed testing instructions, see QUICK_START.md.

How It Works

Session Lifecycle

┌─────────────┐
│ Open Book   │ → Calculate hash → Fetch book_id → Cache
└─────────────┘
       ↓
┌─────────────┐
│ Start       │ → Record: start time, progress, location
│ Session     │
└─────────────┘
       ↓
┌─────────────┐
│ Read Book   │ → User reads...
└─────────────┘
       ↓
┌─────────────┐
│ Close Book  │ → Calculate: duration, pages, progress delta
└─────────────┘
       ↓
┌─────────────┐
│ Validate    │ → Check: min duration, min pages
└─────────────┘
       ↓
    [Valid?]
       ↓ Yes
┌─────────────┐
│ Save to     │ → Queue in local database
│ Queue       │
└─────────────┘
       ↓
┌─────────────┐
│ Sync to     │ → Upload to Booklore server
│ Server      │
└─────────────┘

Offline Mode

When offline, sessions are saved with book_id = NULL:

Offline Open → Hash calculated → book_id = NULL → Cache
             ↓
Read & Close → Session saved to queue
             ↓
[Network available]
             ↓
Sync → Resolve book_id by hash → Upload session → Delete from queue

See SESSION_TRACKING.md for detailed architecture.

---

Architecture

Module Structure

bookloresync.koplugin/
├── main.lua                    - Main plugin, session logic, event handlers
├── booklore_settings.lua       - Settings UI and configuration
├── booklore_api_client.lua     - HTTP client for Booklore API
├── booklore_database.lua       - SQLite database operations
├── plugin_version.lua          - Auto-generated version info
└── _meta.lua                   - Plugin metadata

Database Schema

book_cache - Caches book information

• file_path (unique) - Full path to book file
• file_hash (indexed) - MD5 hash of book content
• book_id - Booklore server book ID (nullable)
• title, author, book_type - Book metadata
• created_at, updated_at - Timestamps

pending_sessions - Queued sessions waiting to sync

• book_id - Booklore book ID (nullable if offline)
• book_hash - MD5 hash for resolution
• start_time, end_time - ISO 8601 timestamps
• duration_seconds - Reading time in seconds
• start_progress, end_progress, progress_delta - Progress tracking
• start_location, end_location - Page/position
• retry_count - Failed sync attempts
• created_at - Queue timestamp

See SYNC_IMPLEMENTATION.md for sync workflow details.

---

API Endpoints

The plugin communicates with these Booklore API endpoints:

• GET /api/koreader/users/auth - Authenticate user
• GET /api/koreader/books/by-hash/:hash - Get book by file hash
• POST /api/v1/reading-sessions - Submit reading session
• GET /api/health - Check server health

Authentication uses MD5-hashed password for compatibility with Booklore server.

---

Configuration Options

Setup & Connection

• Server URL - Booklore server address (e.g., http://192.168.1.100:6060)
• Username - Your Booklore username
• Password - Your Booklore password
• Shelf - Interactive picker to choose which Booklore shelf to sync with
• Shelf ID - Manual alternative to the interactive picker
• Download Directory - Directory for fetching EPUBs
• Test Connection - Verify settings immediately

Preferences

• Enable Sync - Toggle plugin behavior entirely
• Manual Sync Only - Disable background auto-syncs
• Silent Messages - Hide low-priority popup notifications
• Debug Logging - Write advanced diagnostics to a file handler
• Secure Logs - Redact sensitive URLs and headers in output log
• Auto-Sync from Shelf - Download missing books automatically
• Bidirectional Sync - Remove local files if removed remotely

Validation Thresholds

• Min Duration - Minimum seconds to save session (default: 30)
• Min Pages - Minimum pages to save session (default: 5)
• Detection Mode - Validate by "duration" or "pages"
• Progress Decimals - 0-5 decimal places (default: 2)

---

Feature Completion

Category	Status
Session Tracking	✅ 100%
Session Validation	✅ 100%
Offline Support	✅ 100%
Cache Management	✅ 100%
Settings & UI	✅ 100%
API Communication	✅ 100%
Database (SQLite)	✅ 100%
Dispatcher Integration	✅ 100%
Logging & Diagnostics	✅ 100%

Overall: 100% Complete

See features.md for detailed granular feature tracking.

---

Troubleshooting

Plugin Not Appearing in Menu

• Ensure files are in ~/.config/koreader/plugins/bookloresync.koplugin/
• Restart KOReader completely (not just sleep mode)
• Check KOReader log for Lua errors

Connection Test Fails

# Verify server is running
curl http://localhost:6060/api/health

# Should return: {"status":"ok"}

• Check server URL is correct
• Verify server is running and accessible
• Check username/password are correct

Sessions Not Syncing

• Check Tools → Booklore Sync → View Statistics for pending count
• Verify Manual Sync Only is disabled (if you want auto-sync)
• Check KOReader log: tail -f /tmp/koreader.log | grep BookloreSync
• Try manual sync: Tools → Booklore Sync → Sync Now

"bad argument #1 to 'floor'" Error

• Cause: KOReader didn't reload updated plugin code
• Fix: Restart KOReader completely

Database Errors

# Reset database (WARNING: deletes all cached data)
rm ~/.config/koreader/settings/booklore-sync.sqlite
# Restart KOReader

For more help, see DEBUG_REFERENCE.md.

---

Testing

Quick Test (5 minutes)

See QUICK_START.md for a simple 5-step test.

Comprehensive Test

See TESTING_GUIDE.md for full test plan covering:

• Fresh installation
• Book hash calculation
• Session tracking (valid/invalid)
• Sync (online/offline)
• Edge cases
• Settings persistence
• Performance benchmarks

---

Development

Requirements

• Lua 5.1 / LuaJIT
• KOReader 2023.10+ (or compatible version)
• SQLite 3 (via lua-ljsqlite3)
• Booklore server running

File Structure

booklore-koreader-plugin/
├── bookloresync.koplugin/     - Plugin code
│   ├── main.lua
│   ├── booklore_settings.lua
│   ├── booklore_api_client.lua
│   ├── booklore_database.lua
│   ├── plugin_version.lua
│   └── _meta.lua
├── old/                        - Reference old plugin
├── docs/
│   ├── QUICK_START.md         - Quick test guide
│   ├── TESTING_GUIDE.md       - Comprehensive tests
│   ├── DEBUG_REFERENCE.md     - Debug commands
│   ├── STATUS.md              - Project status
│   ├── BOOK_HASH.md           - Hash algorithm
│   ├── SESSION_TRACKING.md    - Session architecture
│   ├── SYNC_IMPLEMENTATION.md - Sync workflow
│   ├── TYPE_SAFETY_FIX.md     - Type conversions
│   └── VERSIONING.md          - Version strategy
├── features.md                 - Feature tracking
└── README.md                   - This file

Syntax Check

cd bookloresync.koplugin
luac -p *.lua

Database Inspection

sqlite3 ~/.config/koreader/settings/booklore-sync.sqlite

# View schema
.schema

# View cached books
SELECT * FROM book_cache;

# View pending sessions
SELECT * FROM pending_sessions;

---

Changes from Old Plugin

Major Improvements

• ✅ Two-Way Library Sync - The plugin isn't just for reading progress anymore; it keeps your physical EPUB files perfectly mirrored with your remote Booklore shelf. Includes automatic downloads, bidirectional deletions, and an interactive native shelf picker.
• ✅ Silent Background Sync - Sync operations run fully in the background without UI interruption when reading.
• ✅ Safe UI & Token Recovery - Safe dispatch for connection errors and automatic 401/403 retry handling.
• ✅ SQLite Database - Replaced LuaSettings with proper database and Schema Versioning.
• ✅ Offline Book ID Resolution - Sessions with NULL book_id resolved during sync.
• ✅ Optimized Sync Speed - Bypasses hashing for books already in local cache.
• ✅ Atomic Sync & Scan - Bulk database operations wrapped in SQLite transactions.
• ✅ Flash-Safe Logging - Persistent file handle and lifecycle-aware closure.

New Features

• Session Detection Mode - Choose duration OR pages validation
• Minimum Pages Read - Additional validation option
• Version Display - Dedicated button showing version info
• Formatted Duration - Human-readable format (e.g., "1h 5m 9s")
• Auto-Detect Book Type - Supports EPUB, PDF, DJVU, CBZ, CBR
• Auto-Sync on Resume - Background sync on device wake
• Update Book ID by Hash - Cache updates when resolved
• Dynamic UI Progress Tracking - Live progress updates for long-running sync and library scans

Bug Fixes

All SQLite binding errors and cdata type conversion issues resolved. See TYPE_SAFETY_FIX.md for details.

---

Version History

1.0.0-beta (February 21, 2026) - Current

• Advanced background and silent sync.
• SQLite database implementation.
• Intelligent token recovery and safe dispatch.
• Refined caching, offline recovery, and file logging optimizations.

See VERSIONING.md for version strategy.

---

Contributing

Bug Reports

When reporting bugs, please include:

• KOReader version
• Plugin version
• Steps to reproduce
• KOReader log output (grep BookloreSync /tmp/koreader.log)
• Database state (SELECT * FROM pending_sessions;)

Feature Requests

Feature requests welcome! Check features.md to see what's planned.

---

License

[Add your license here]

---

Links

• Booklore Server: [Add Booklore repo link]
• KOReader: https://github.com/koreader/koreader
• Documentation: See docs/ folder

---

Support

For help:

1. Check QUICK_START.md for testing guide
2. Check DEBUG_REFERENCE.md for debug commands
3. Check TESTING_GUIDE.md for comprehensive tests
4. Review KOReader logs for errors
5. Inspect database for pending sessions

---

Status: Ready! Follow QUICK_START.md to get started.

Last Updated: February 21, 2026