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

dittolive_ditto/small_peer_info/
mod.rs
