korrosync 0.4.2

A KOReader Sync Server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

//! Database service layer for KoReader synchronization.
//!
//! This module defines the [`KorrosyncService`] trait which provides an abstract interface
//! for managing persistent storage of user authentication and reading progress synchronization.
//!
//! # Implementations
//!
//! Currently available implementations:
//!
//! - [`KorrosyncServiceRedb`] - Embedded redb database implementation (default)
//!

use crate::{
    model::{Progress, User},
    service::error::ServiceError,
};

pub mod redb;
pub use self::redb::KorrosyncServiceRedb;

/// Trait defining the core database operations for KoReader synchronization.
///
/// This trait provides a database-agnostic interface for managing users and reading progress.
/// Implementations can use any storage backend (embedded databases, SQL databases, etc.)
/// as long as they provide these operations.
///
/// # Design
///
/// The trait uses owned `String` parameters for flexibility and to avoid lifetime issues
/// when used with trait objects (`Arc<dyn KorrosyncService>`).
///
/// # Thread Safety
///
/// Implementations must be thread-safe when wrapped in `Arc`. All methods take `&self`
/// to allow concurrent access from multiple threads.
pub trait KorrosyncService {
    /// Retrieves a user by username.
    ///
    /// # Arguments
    ///
    /// * `name` - The username to look up
    ///
    /// # Returns
    ///
    /// - `Ok(Some(user))` - User found with the given username
    /// - `Ok(None)` - No user exists with the given username
    /// - `Err(...)` - Unexpected database error occurred
    fn get_user(&self, name: String) -> Result<Option<User>, ServiceError>;

    /// Creates a new user or updates an existing one.
    ///
    /// If a user with the same username already exists, they will be overwritten.
    ///
    /// # Arguments
    ///
    /// * `user` - The user to add or update
    ///
    /// # Returns
    ///
    /// - `Ok(User)` - User was successfully created or updated
    /// - `Err(...)` - unexpected database error occurred
    fn create_or_update_user(&self, user: User) -> Result<User, ServiceError>;

    /// Updates or creates reading progress for a user's document.
    ///
    /// If progress already exists for this user/document combination, it will be overwritten.
    ///
    /// # Arguments
    ///
    /// * `user` - The username of the user
    /// * `document` - The document identifier
    /// * `progress` - The progress information to store
    ///
    /// # Returns
    ///
    /// Returns a tuple containing:
    /// - The document identifier (echoed back)
    /// - The timestamp from the progress record, echoed back as given
    ///
    /// Unlike [`KorrosyncService::get_progress`] this does not normalise the timestamp:
    /// the caller owns the unit of what it writes, and laundering an out-of-contract
    /// value here would hide the bug that produced it.
    ///
    /// # Errors
    ///
    /// Returns an error if an unexpected database error occurs.
    fn update_progress(
        &self,
        user: String,
        document: String,
        progress: Progress,
    ) -> Result<(String, u64), ServiceError>;

    /// Retrieves reading progress for a specific user and document.
    ///
    /// `Progress::timestamp` must come back in seconds since the Unix epoch, which is what
    /// KOReader compares against its own `os.time()`. Implementations whose storage may
    /// still hold rows written before korrosync switched units are expected to rescale them
    /// on read, so this can return a different timestamp from the one `update_progress`
    /// stored.
    ///
    /// # Arguments
    ///
    /// * `user` - The username of the user
    /// * `document` - The document identifier to look up
    ///
    /// # Returns
    ///
    /// - `Ok(Some(progress))` - Progress found for the user/document combination
    /// - `Ok(None)` - No progress exists for this combination
    /// - `Err(...)` - Unexpected error occurred
    fn get_progress(
        &self,
        user: String,
        document: String,
    ) -> Result<Option<Progress>, ServiceError>;

    /// Lists all users in the database.
    ///
    /// # Returns
    ///
    /// - `Ok(Vec<User>)` - All users currently stored
    /// - `Err(...)` - Unexpected database error occurred
    fn list_users(&self) -> Result<Vec<User>, ServiceError>;

    /// Deletes a user by username.
    ///
    /// # Arguments
    ///
    /// * `name` - The username to delete
    ///
    /// # Returns
    ///
    /// - `Ok(true)` - User existed and was deleted
    /// - `Ok(false)` - No user with that username existed
    /// - `Err(...)` - Unexpected database error occurred
    fn delete_user(&self, name: String) -> Result<bool, ServiceError>;
}