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

use crate::{errors::Result, server::cloud::iter::AsyncObjectIterator};
use async_trait::async_trait;

/// Information about an object as returned from `Service::list`
pub(in crate::server) struct ObjectInfo {
    /// Name of the object.
    pub(in crate::server) name: String,
    /// Creation time of the object, in seconds since the UNIX epoch.
    pub(in crate::server) creation: u64,
}

/// An abstraction of a cloud-storage service.
///
/// The underlying cloud storage is assumed to be a map from object names to object values,
/// similar to a HashMap, with the addition of a compare-and-swap operation. Object names
/// are always simple strings from the character set `[a-zA-Z0-9-]`, no more than 100 characters
/// in length.
#[async_trait]
pub(in crate::server) trait Service {
    /// Put an object into cloud storage. If the object exists, it is overwritten.
    async fn put(&mut self, name: &str, value: &[u8]) -> Result<()>;

    /// Get an object from cloud storage, or None if the object does not exist.
    async fn get(&mut self, name: &str) -> Result<Option<Vec<u8>>>;

    /// Delete an object. Does nothing if the object does not exist.
    async fn del(&mut self, name: &str) -> Result<()>;

    /// Enumerate objects with the given prefix.
    async fn list<'a>(&'a mut self, prefix: &'a str) -> Box<dyn AsyncObjectIterator + Send + 'a>;

    /// Compare the existing object's value with `existing_value`, and replace with `new_value`
    /// only if the values match. Returns true if the replacement occurred.
    async fn compare_and_swap(
        &mut self,
        name: &str,
        existing_value: Option<Vec<u8>>,
        new_value: Vec<u8>,
    ) -> Result<bool>;
}

/// Enforce the limits on `name` described for [`Service`].
///
/// Names are generated by `server.rs` in a way that is not affected by user input, so this only
/// asserts in debug builds.
pub(in crate::server) fn validate_object_name(name: &str) {
    debug_assert!(name.is_ascii());
    debug_assert!(name.len() <= 100);
    debug_assert!(name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-'));
}