taskchampion 3.0.1

Personal task-tracking
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

use crate::errors::Result;
use async_trait::async_trait;
use uuid::Uuid;

/// Versions are referred to with UUIDs.
pub type VersionId = Uuid;

/// The distinguished value for "no version"
pub const NIL_VERSION_ID: VersionId = Uuid::nil();

/// A segment in the history of this task database, in the form of a sequence of operations.  This
/// data is pre-encoded, and from the protocol level appears as a sequence of bytes.
pub type HistorySegment = Vec<u8>;

/// A snapshot of the state of the task database.  This is encoded by the taskdb implementation
/// and treated as a sequence of bytes by the server implementation.
pub type Snapshot = Vec<u8>;

/// AddVersionResult is the response type from [`crate::server::Server::add_version`].
#[derive(Debug, PartialEq, Eq)]
pub enum AddVersionResult {
    /// OK, version added with the given ID
    Ok(VersionId),
    /// Rejected; expected a version with the given parent version
    ExpectedParentVersion(VersionId),
}

/// SnapshotUrgency indicates how much the server would like this replica to send a snapshot.
#[derive(PartialEq, Debug, Clone, Copy, Eq, PartialOrd, Ord)]
pub enum SnapshotUrgency {
    /// Don't need a snapshot right now.
    None,
    /// A snapshot would be good, but can wait for other replicas to provide it.
    Low,
    /// A snapshot is needed right now.
    High,
}

/// A version as downloaded from the server
#[derive(Debug, PartialEq, Eq)]
pub enum GetVersionResult {
    /// No such version exists
    NoSuchVersion,

    /// The requested version
    Version {
        version_id: VersionId,
        parent_version_id: VersionId,
        history_segment: HistorySegment,
    },
}

/// A value implementing this trait can act as a server against which a replica can sync.
#[async_trait(?Send)]
pub trait Server {
    /// Add a new version.
    ///
    /// This must ensure that the new version is the only version with the given
    /// `parent_version_id`, and that all versions form a single parent-child chain. Inductively,
    /// this means that if there are any versions on the server, then `parent_version_id` must be
    /// the only version that does not already have a child.
    async fn add_version(
        &mut self,
        parent_version_id: VersionId,
        history_segment: HistorySegment,
    ) -> Result<(AddVersionResult, SnapshotUrgency)>;

    /// Get the version with the given parent VersionId
    async fn get_child_version(&mut self, parent_version_id: VersionId)
        -> Result<GetVersionResult>;

    /// Add a snapshot on the server
    async fn add_snapshot(&mut self, version_id: VersionId, snapshot: Snapshot) -> Result<()>;

    async fn get_snapshot(&mut self) -> Result<Option<(VersionId, Snapshot)>>;
}