korrosync 0.4.0

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

//! 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
    ///
    /// # 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.
    ///
    /// # 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>;
}