dittolive_ditto/ditto/init/
config.rs

1use std::path::PathBuf;
2
3use serde::{Deserialize, Serialize};
4use serde_with::{base64::Base64, serde_as};
5use url::Url;
6
7/// Configuration options required to initialize a [`Ditto`] instance.
8///
9/// # Example
10///
11/// ```
12/// # use dittolive_ditto::prelude::*;
13/// # fn example(database_id: &str) {
14/// let connect = DittoConfigConnect::Server {
15///     url: "REPLACE_ME_WITH_YOUR_SERVER_URL".parse().unwrap(),
16/// };
17/// let connect = DittoConfigConnect::SmallPeersOnly {
18///     private_key: Some("REPLACE_ME_WITH_YOUR_PRIVATE_KEY".as_bytes().to_vec()),
19/// };
20/// let connect = DittoConfigConnect::SmallPeersOnly { private_key: None };
21/// let config = DittoConfig::new(database_id, connect);
22/// # }
23/// ```
24///
25/// [`Ditto`]: crate::Ditto
26#[non_exhaustive]
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct DittoConfig {
29    /// An ID used to distinguish between Ditto database instantations.
30    ///
31    /// **Note**: This was formerly known as `appId`.
32    pub database_id: String,
33    /// The connection configuration this device uses to connect to a Ditto mesh.
34    pub connect: DittoConfigConnect,
35    /// The directory where Ditto will store its data.
36    #[serde(skip_serializing_if = "Option::is_none")]
37    pub persistence_directory: Option<PathBuf>,
38    #[doc(hidden)]
39    pub experimental: DittoConfigExperimental,
40}
41
42impl DittoConfig {
43    /// Create a new [`DittoConfig`] instance from a database ID and connection configuration.
44    pub fn new<S: Into<String>>(database_id: S, connect: DittoConfigConnect) -> Self {
45        DittoConfig {
46            database_id: database_id.into(),
47            connect,
48            persistence_directory: None,
49            experimental: Default::default(),
50        }
51    }
52
53    /// Optionally specify a custom persistence directory.
54    pub fn with_persistence_directory<P: Into<PathBuf>>(mut self, path: P) -> Self {
55        self.persistence_directory = Some(path.into());
56        self
57    }
58}
59
60/// Specifies the connection mechanism to be used by the [`Ditto`] instance.
61///
62/// # Example
63///
64/// ```
65/// use dittolive_ditto::prelude::*;
66/// let connect_config = DittoConfigConnect::Server {
67///     url: "https://example.com/your-server-url".parse().unwrap(),
68/// };
69/// let connect_config = DittoConfigConnect::SmallPeersOnly {
70///     private_key: Some("REPLACE_ME_WITH_YOUR_PRIVATE_KEY".bytes().collect()),
71/// };
72/// let connect_config = DittoConfigConnect::SmallPeersOnly { private_key: None };
73/// ```
74///
75/// [`Ditto`]: crate::Ditto
76#[serde_as]
77#[non_exhaustive]
78#[derive(Debug, Clone, Serialize, Deserialize)]
79#[serde(tag = "type", rename_all = "snake_case")]
80pub enum DittoConfigConnect {
81    /// Connect to a Ditto "Big Peer" using the provided URL.
82    ///
83    /// When using `Server` mode, you _must_ provide an authentication expiration
84    /// handler using [`ditto.auth()?.set_expiration_handler(...)`][0].
85    ///
86    /// [0]: crate::prelude::DittoAuthenticator::set_expiration_handler
87    Server {
88        /// The "Auth URL" from the Ditto Portal, if using a Ditto-hosted Big Peer.
89        ///
90        /// If using a self-hosted Big Peer, provide your custom authentication URL.
91        ///
92        /// # Example
93        ///
94        /// ```text
95        /// // Where this subdomain is your Ditto `databaseId` (formerly `AppId`)
96        /// https://00000000-0000-0000-0000-000000000000.cloud.ditto.live
97        /// ```
98        url: Url,
99    },
100    /// Connect only to other Ditto small peers, using the provided private key.
101    ///
102    /// If no private key is provided, sync traffic will be UNENCRYPTED. This
103    /// mode should NOT be used in production, only for development and testing
104    /// purposes.
105    SmallPeersOnly {
106        #[serde_as(as = "Option<Base64>")]
107        #[serde(skip_serializing_if = "Option::is_none")]
108        private_key: Option<Vec<u8>>,
109    },
110}
111
112#[doc(hidden)]
113#[non_exhaustive]
114#[derive(Debug, Default, Clone, Serialize, Deserialize)]
115pub struct DittoConfigExperimental {
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub passphrase: Option<String>,
118}
dittolive_ditto/ditto/init/config.rs

dittolive_ditto/ditto/init/
config.rs
