dittolive-ditto 4.12.5

Ditto is a peer to peer cross-platform database that allows mobile, web, IoT and server apps to sync with or without an internet connection.
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

use std::path::PathBuf;

use serde::{Deserialize, Serialize};
use serde_with::{base64::Base64, serde_as};
use url::Url;

/// Configuration options required to initialize a [`Ditto`] instance.
///
/// # Example
///
/// ```
/// # use dittolive_ditto::prelude::*;
/// # fn example(database_id: &str) {
/// let connect = DittoConfigConnect::Server {
///     url: "REPLACE_ME_WITH_YOUR_SERVER_URL".parse().unwrap(),
/// };
/// let connect = DittoConfigConnect::SmallPeersOnly {
///     private_key: Some("REPLACE_ME_WITH_YOUR_PRIVATE_KEY".as_bytes().to_vec()),
/// };
/// let connect = DittoConfigConnect::SmallPeersOnly { private_key: None };
/// let config = DittoConfig::new(database_id, connect);
/// # }
/// ```
///
/// [`Ditto`]: crate::Ditto
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DittoConfig {
    /// An ID used to distinguish between Ditto database instantations.
    ///
    /// **Note**: This was formerly known as `appId`.
    pub database_id: String,
    /// The connection configuration this device uses to connect to a Ditto mesh.
    pub connect: DittoConfigConnect,
    /// The directory where Ditto will store its data.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub persistence_directory: Option<PathBuf>,
    #[doc(hidden)]
    pub experimental: DittoConfigExperimental,
}

impl DittoConfig {
    /// Create a new [`DittoConfig`] instance from a database ID and connection configuration.
    pub fn new<S: Into<String>>(database_id: S, connect: DittoConfigConnect) -> Self {
        DittoConfig {
            database_id: database_id.into(),
            connect,
            persistence_directory: None,
            experimental: Default::default(),
        }
    }

    /// Optionally specify a custom persistence directory.
    pub fn with_persistence_directory<P: Into<PathBuf>>(mut self, path: P) -> Self {
        self.persistence_directory = Some(path.into());
        self
    }
}

/// Specifies the connection mechanism to be used by the [`Ditto`] instance.
///
/// # Example
///
/// ```
/// use dittolive_ditto::prelude::*;
/// let connect_config = DittoConfigConnect::Server {
///     url: "https://example.com/your-server-url".parse().unwrap(),
/// };
/// let connect_config = DittoConfigConnect::SmallPeersOnly {
///     private_key: Some("REPLACE_ME_WITH_YOUR_PRIVATE_KEY".bytes().collect()),
/// };
/// let connect_config = DittoConfigConnect::SmallPeersOnly { private_key: None };
/// ```
///
/// [`Ditto`]: crate::Ditto
#[serde_as]
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum DittoConfigConnect {
    /// Connect to a Ditto "Big Peer" using the provided URL.
    ///
    /// When using `Server` mode, you _must_ provide an authentication expiration
    /// handler using [`ditto.auth()?.set_expiration_handler(...)`][0].
    ///
    /// [0]: crate::prelude::DittoAuthenticator::set_expiration_handler
    Server {
        /// The "Auth URL" from the Ditto Portal, if using a Ditto-hosted Big Peer.
        ///
        /// If using a self-hosted Big Peer, provide your custom authentication URL.
        ///
        /// # Example
        ///
        /// ```text
        /// // Where this subdomain is your Ditto `databaseId` (formerly `AppId`)
        /// https://00000000-0000-0000-0000-000000000000.cloud.ditto.live
        /// ```
        url: Url,
    },
    /// Connect only to other Ditto small peers, using the provided private key.
    ///
    /// If no private key is provided, sync traffic will be UNENCRYPTED. This
    /// mode should NOT be used in production, only for development and testing
    /// purposes.
    SmallPeersOnly {
        #[serde_as(as = "Option<Base64>")]
        #[serde(skip_serializing_if = "Option::is_none")]
        private_key: Option<Vec<u8>>,
    },
}

#[doc(hidden)]
#[non_exhaustive]
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
pub struct DittoConfigExperimental {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub passphrase: Option<String>,
}