dittolive_ditto/small_peer_info/
mod.rs

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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! Use [`ditto.small_peer_info()`] to interact with peer metadata.
//!
//! # Example
//!
//! ```
//! use dittolive_ditto::prelude::*;
//!
//! # fn example(ditto: &Ditto) -> anyhow::Result<()> {
//! let small_peer_info = ditto.small_peer_info();
//!
//! small_peer_info.set_metadata(&serde_json::json!({
//!     "deviceType": "cashRegister"
//! }))?;
//!
//! let metadata: serde_json::Value = small_peer_info.metadata()?;
//! assert_eq!(metadata["deviceType"].as_str().unwrap(), "cashRegister");
//! # Ok(())
//! # }
//! ```
//!
//! [`ditto.small_peer_info()`]: crate::Ditto::small_peer_info

use_prelude!();
use std::sync::Arc;

/// Determines which "kind" of peers the small peer info will be
/// replicate to, defaults to [`DittoSmallPeerInfoSyncScope::BigPeerOnly`].
///
/// # Deprecated
///
/// Use Sync Scopes instead. Will be removed in v5.
/// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
#[deprecated(
    note = "Use Sync Scopes instead, settable via DQL ALTER SYSTEM. Will be removed in v5. See: https://docs.ditto.live/sdk/latest/sync/sync-scopes"
)]
pub use ffi_sdk::DittoSmallPeerInfoSyncScope;

/// The entrypoint for small peer user info collection. Small peer info consists of information
/// gathered into a system collection on a regular interval and optionally synced to the Big Peer
/// for device dashboard and debugging purposes.
///
/// You don't create this class directly, but can access it from a particular [`Ditto`]
/// instance via its [`Ditto::small_peer_info`] method.
pub struct SmallPeerInfo {
    /// Handle to the live Ditto instance
    ditto: Arc<ffi_sdk::BoxedDitto>,
}

impl SmallPeerInfo {
    pub(crate) fn new(ditto: Arc<ffi_sdk::BoxedDitto>) -> Self {
        Self { ditto }
    }

    /// Indicates whether small peer info collection is currently enabled, defaults
    /// to `true`.
    ///
    /// Small peer info consists of information scraped into a system collection
    /// at repeated intervals and synced to the Big Peer for device dashboard
    /// and debugging purposes.
    ///
    /// Note: whether the background ingestion process is enabled or not is a
    /// separate decision to whether this information is allowed to sync to other
    /// peers (including the big peer). This is controlled by [`DittoSmallPeerInfoSyncScope`].
    pub fn is_enabled(&self) -> bool {
        ffi_sdk::ditto_small_peer_info_get_is_enabled(&self.ditto)
    }

    /// Sets whether small peer info collection is currently enabled.
    pub fn set_enabled(&self, enabled: bool) {
        ffi_sdk::ditto_small_peer_info_set_enabled(&self.ditto, enabled);
    }

    /// Determines which "kind" of peers the small peer info will be
    /// replicate to, defaults to `DittoSmallPeerInfoSyncScope::BigPeerOnly`.
    ///
    /// # Deprecated
    ///
    /// Use Sync Scopes instead. Will be removed in v5.
    /// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
    #[deprecated(
        note = "Use Sync Scopes instead, settable via DQL ALTER SYSTEM. Will be removed in v5. See: https://docs.ditto.live/sdk/latest/sync/sync-scopes"
    )]
    pub fn sync_scope(&self) -> DittoSmallPeerInfoSyncScope {
        ffi_sdk::ditto_small_peer_info_get_sync_scope(&self.ditto)
    }

    /// Sets which "kind" of peers the small peer info will be
    /// replicated to.
    ///
    /// # Deprecated
    ///
    /// Use Sync Scopes instead. Will be removed in v5.
    /// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
    #[deprecated(
        note = "Use Sync Scopes instead, settable via DQL ALTER SYSTEM. Will be removed in v5. See: https://docs.ditto.live/sdk/latest/sync/sync-scopes"
    )]
    pub fn set_sync_scope(&self, sync_scope: DittoSmallPeerInfoSyncScope) {
        ffi_sdk::ditto_small_peer_info_set_sync_scope(&self.ditto, sync_scope)
    }

    /// Returns the JSON metadata being associated with the small peer info.
    pub fn metadata<T: serde::de::DeserializeOwned>(&self) -> Result<T, DittoError> {
        let result = ffi_sdk::ditto_small_peer_info_get_metadata(&self.ditto);
        serde_json::from_str(result.to_str()).map_err(Into::into)
    }

    /// Sets the JSON metadata to be associated with the small peer info.
    ///
    /// The metadata is a free-form, user-provided dictionary that is serialized into
    /// JSON and is inserted into the small peer info system doc at each collection
    /// interval. The dictionary has no schema except for the following constraints:
    ///
    /// 1. All contained values must be JSON serializable.
    /// 1. The size of the dictionary serialized as JSON may not exceed 128 KB.
    /// 2. The dictionary may only be nested up to 64 levels deep.
    pub fn set_metadata<T: serde::Serialize>(&self, metadata: &T) -> Result<(), DittoError> {
        let json_string = serde_json::to_string(metadata)?;
        let result = ffi_sdk::ditto_small_peer_info_set_metadata(
            &self.ditto,
            char_p::new(json_string).as_ref(),
        );
        if result != 0 {
            return Err(DittoError::from_small_peer_info_error_code(result));
        }
        Ok(())
    }

    /// Returns the JSON string of the metadata being associated with the small peer info.
    pub fn metadata_json_string(&self) -> Result<String, DittoError> {
        let result = ffi_sdk::ditto_small_peer_info_get_metadata(&self.ditto);
        Ok(result.into_string())
    }

    /// Sets the JSON metadata to be associated with the small peer info.
    ///
    /// The metadata is free-form, user-provided string is serialized into
    /// JSON and is inserted into the small peer info system doc at each collection
    /// interval. The dictionary has no schema except for the following constraints:
    ///
    /// 1. All contained values must be JSON serializable.
    /// 1. The size of the dictionary serialized as JSON may not exceed 128 KB.
    /// 2. The dictionary may only be nested up to 64 levels deep.
    pub fn set_metadata_json_string(&self, metadata: &str) -> Result<(), DittoError> {
        let result = ffi_sdk::ditto_small_peer_info_set_metadata(
            &self.ditto,
            char_p::new(metadata).as_ref(),
        );
        if result != 0 {
            return Err(DittoError::from_small_peer_info_error_code(result));
        }
        Ok(())
    }
}