dittolive_ditto/small_peer_info/
mod.rs

1//! Use [`ditto.small_peer_info()`] to interact with peer metadata.
2//!
3//! # Example
4//!
5//! ```
6//! use dittolive_ditto::prelude::*;
7//!
8//! # fn example(ditto: &Ditto) -> anyhow::Result<()> {
9//! let small_peer_info = ditto.small_peer_info();
10//!
11//! small_peer_info.set_metadata(&serde_json::json!({
12//!     "deviceType": "cashRegister"
13//! }))?;
14//!
15//! let metadata: serde_json::Value = small_peer_info.metadata()?;
16//! assert_eq!(metadata["deviceType"].as_str().unwrap(), "cashRegister");
17//! # Ok(())
18//! # }
19//! ```
20//!
21//! [`ditto.small_peer_info()`]: crate::Ditto::small_peer_info
22
23use_prelude!();
24use std::sync::Arc;
25
26/// Determines which "kind" of peers the small peer info will be
27/// replicate to, defaults to [`DittoSmallPeerInfoSyncScope::BigPeerOnly`].
28///
29/// # Deprecated
30///
31/// Use Sync Scopes instead. Will be removed in v5.
32/// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
33#[deprecated(
34    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"
35)]
36pub use ffi_sdk::DittoSmallPeerInfoSyncScope;
37
38/// The entrypoint for small peer user info collection. Small peer info consists of information
39/// gathered into a system collection on a regular interval and optionally synced to the Big Peer
40/// for device dashboard and debugging purposes.
41///
42/// You don't create this class directly, but can access it from a particular [`Ditto`]
43/// instance via its [`Ditto::small_peer_info`] method.
44pub struct SmallPeerInfo {
45    /// Handle to the live Ditto instance
46    ditto: Arc<ffi_sdk::BoxedDitto>,
47}
48
49impl SmallPeerInfo {
50    pub(crate) fn new(ditto: Arc<ffi_sdk::BoxedDitto>) -> Self {
51        Self { ditto }
52    }
53
54    /// Indicates whether small peer info collection is currently enabled, defaults
55    /// to `true`.
56    ///
57    /// Small peer info consists of information scraped into a system collection
58    /// at repeated intervals and synced to the Big Peer for device dashboard
59    /// and debugging purposes.
60    ///
61    /// Note: whether the background ingestion process is enabled or not is a
62    /// separate decision to whether this information is allowed to sync to other
63    /// peers (including the big peer). This is controlled by [`DittoSmallPeerInfoSyncScope`].
64    pub fn is_enabled(&self) -> bool {
65        ffi_sdk::ditto_small_peer_info_get_is_enabled(&self.ditto)
66    }
67
68    /// Sets whether small peer info collection is currently enabled.
69    pub fn set_enabled(&self, enabled: bool) {
70        ffi_sdk::ditto_small_peer_info_set_enabled(&self.ditto, enabled);
71    }
72
73    /// Determines which "kind" of peers the small peer info will be
74    /// replicate to, defaults to `DittoSmallPeerInfoSyncScope::BigPeerOnly`.
75    ///
76    /// # Deprecated
77    ///
78    /// Use Sync Scopes instead. Will be removed in v5.
79    /// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
80    #[deprecated(
81        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"
82    )]
83    pub fn sync_scope(&self) -> DittoSmallPeerInfoSyncScope {
84        ffi_sdk::ditto_small_peer_info_get_sync_scope(&self.ditto)
85    }
86
87    /// Sets which "kind" of peers the small peer info will be
88    /// replicated to.
89    ///
90    /// # Deprecated
91    ///
92    /// Use Sync Scopes instead. Will be removed in v5.
93    /// See: <https://docs.ditto.live/sdk/latest/sync/sync-scopes>
94    #[deprecated(
95        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"
96    )]
97    pub fn set_sync_scope(&self, sync_scope: DittoSmallPeerInfoSyncScope) {
98        ffi_sdk::ditto_small_peer_info_set_sync_scope(&self.ditto, sync_scope)
99    }
100
101    /// Returns the JSON metadata being associated with the small peer info.
102    pub fn metadata<T: serde::de::DeserializeOwned>(&self) -> Result<T, DittoError> {
103        let result = ffi_sdk::ditto_small_peer_info_get_metadata(&self.ditto);
104        serde_json::from_str(result.to_str()).map_err(Into::into)
105    }
106
107    /// Sets the JSON metadata to be associated with the small peer info.
108    ///
109    /// The metadata is a free-form, user-provided dictionary that is serialized into
110    /// JSON and is inserted into the small peer info system doc at each collection
111    /// interval. The dictionary has no schema except for the following constraints:
112    ///
113    /// 1. All contained values must be JSON serializable.
114    /// 1. The size of the dictionary serialized as JSON may not exceed 128 KB.
115    /// 2. The dictionary may only be nested up to 64 levels deep.
116    pub fn set_metadata<T: serde::Serialize>(&self, metadata: &T) -> Result<(), DittoError> {
117        let json_string = serde_json::to_string(metadata)?;
118        let result = ffi_sdk::ditto_small_peer_info_set_metadata(
119            &self.ditto,
120            char_p::new(json_string).as_ref(),
121        );
122        if result != 0 {
123            return Err(DittoError::from_small_peer_info_error_code(result));
124        }
125        Ok(())
126    }
127
128    /// Returns the JSON string of the metadata being associated with the small peer info.
129    pub fn metadata_json_string(&self) -> Result<String, DittoError> {
130        let result = ffi_sdk::ditto_small_peer_info_get_metadata(&self.ditto);
131        Ok(result.into_string())
132    }
133
134    /// Sets the JSON metadata to be associated with the small peer info.
135    ///
136    /// The metadata is free-form, user-provided string is serialized into
137    /// JSON and is inserted into the small peer info system doc at each collection
138    /// interval. The dictionary has no schema except for the following constraints:
139    ///
140    /// 1. All contained values must be JSON serializable.
141    /// 1. The size of the dictionary serialized as JSON may not exceed 128 KB.
142    /// 2. The dictionary may only be nested up to 64 levels deep.
143    pub fn set_metadata_json_string(&self, metadata: &str) -> Result<(), DittoError> {
144        let result = ffi_sdk::ditto_small_peer_info_set_metadata(
145            &self.ditto,
146            char_p::new(metadata).as_ref(),
147        );
148        if result != 0 {
149            return Err(DittoError::from_small_peer_info_error_code(result));
150        }
151        Ok(())
152    }
153}
dittolive_ditto/small_peer_info/mod.rs

dittolive_ditto/small_peer_info/
mod.rs
