Struct dittolive_ditto::ditto::Ditto

pub struct Ditto { /* private fields */ }

The entry point for accessing Ditto-related functionality.

This struct is generally a handle and interface to ditto-functionality which operates in background threads.

Implementations

impl Ditto

pub fn close(self)

Clean shutdown of the Ditto instance

pub fn start_sync(&self) -> Result<(), DittoError>

Start syncing on all configured transports

pub fn stop_sync(&self)

Stop syncing on all transports.

pub fn set_transport_config(&self, config: TransportConfig)

Set a new TransportConfig and begin syncing over these transports. Any change to start or stop a specific transport should proceed via providing a modified configuration to this method.

pub fn current_transport_config(&self) -> Result<TransportConfig, DittoError>

Returns a snapshot of the currently configured transports.

impl Ditto

pub fn with_sdk_version<R>(ret: impl FnOnce(&str) -> R) -> R

Return the version of the SDK.

impl Ditto

pub fn set_logging_enabled(enabled: bool)

Enable of disable logging.

pub fn get_logging_enabled() -> bool

Return true if logging is enabled.

pub fn get_emoji_log_level_headings_enabled() -> bool

Represent whether or not emojis should be used as the log level indicator in the logs.

pub fn set_emoji_log_level_headings_enabled(enabled: bool)

Set whether or not emojis should be used as the log level indicator in the logs.

pub fn get_minimum_log_level() -> LogLevel

Get the current minimum log level.

pub fn set_minimum_log_level(log_level: LogLevel)

Set the current minimum log level.

impl Ditto

pub fn set_offline_only_license_token(
    &self,
    license_token: &str
) -> Result<(), DittoError>

Activate an offline Ditto instance by setting a license token.

You cannot initiate sync on an offline (OfflinePlayground, Manual, or SharedKey) Ditto instance before you have activated it.

pub fn set_license_from_env(&self, var_name: &str) -> Result<(), DittoError>

Look for a license token from a given environment variable.

pub fn set_peer_signed_info<S: Serialize>(
    &self,
    peer_info: HashMap<String, S>
) -> Result<(), DittoError>

Set a dictionary of arbitrary data about this device to be shared with peers in the mesh.

This data is gossiped in the presence collection across the mesh. This can be useful to include extra metadata like app versions,capabilities, etc., to help peers decide who to interact with.

This peer information is persisted in the SDK, and thus needn’t be set at every start of Ditto.

Security (and caveats)

This peer info will be signed by your peer key to prevent forgery of this info by other peers.

However, for compatibility, there is no attestation of the lack of peer info – that is, participants in the mesh could maliciously remove peer info. If this is a concern for your application, a workaround for this is to have your application require that peers have a signed peer info dictionary present.

Similarly, as there is no monotonic version counter or timestamp/expiration of the signed peer info, replay attacks (replacing the current info with previously, possibly outdated, signed info) are possible without counter-measures. If this is a concern for your application, you might consider including a counter or creation timestamp to prevent replays, depending on your use-case.

Performance caveats

Because this information is included in the presence data that is gossiped among peers, the size of this peer info and the frequency it is updated can drastically affect performance if it is too large.

Errors

Because of the performance implications, the serialized info dictionary is currently limited to 4KiB.

Examples

let mut peer_info = HashMap::new();
peer_info.insert("app_version".into(), "1.0.0".to_string());
ditto.set_peer_signed_info(peer_info)?;

pub fn register_on_connecting_callback(
    &self,
    callback: impl Fn(ConnectingPeer, Box<dyn FnOnce(bool)>) + Send + Sync + 'static
)

Add a callback that can decide based on the known peer information at the time whether Ditto should complete the handshake or reject the connection.

This is an asynchronous API, so your callback will receive information about the connecting peer, and you must then call the provided callback function with your decision.

Decisions

Responding with true will allow the peer to connect. Responding with false will reject the peer. Not responding will lead to a handshake timeout, effectively rejecting the peer.

Examples

ditto.register_on_connecting_callback(|peer, respond| {
    match peer.peer_info.unwrap_or_default().get("app_version") {
        // Reject peers reporting a known buggy version.
        Some(InfoValue::Text(v)) if v == "1.2.3" => respond(false),
        _ => respond(true),
    }
});

pub fn store(&self) -> &Store

Returns a reference to the underlying local data store.

pub fn sync(&self) -> &Sync

Returns a reference to the synchronization controller.

pub fn small_peer_info(&self) -> &SmallPeerInfo

Return a reference to the SmallPeerInfo object.

pub fn site_id(&self) -> u64

Returns the site ID that the instance of Ditto is using as part of its identity.

pub fn persistence_directory(&self) -> &Path

Returns the Ditto persistence directory path.

pub fn application_id(&self) -> AppId

Returns the application Id being used by this Ditto instance.

pub fn set_device_name(&self, name: &str)

Set a custom identifier for the current device.

When using observe_peers, each remote peer is represented by a short UTF-8 “device name”. By default this will be a truncated version of the device’s hostname. It does not need to be unique among peers. Configure the device name before calling start_sync. If it is too long it will be truncated.

pub fn observe_peers<H>(&self, handler: H) -> PeersObserverwhere
    H: Fn(V2Presence) + Send + Sync + 'static,

👎Deprecated: Use presence().observe() instead

Request information about Ditto peers in range of this device.

This method returns an observer which should be held as long as updates are required. A newly registered observer will have a peers update delivered to it immediately. Then it will be invoked repeatedly when Ditto devices come and go, or the active connections to them change.

pub fn presence(&self) -> &Arc<Presence>

Return a handle to Presence to monitor the peers’ activity in the Ditto mesh. It can be used to retrieve an immediate representation of known peers :

let presence_graph = ditto.presence().exec();

Or to bind a callback to the changes :

let handle = ditto.presence().observe(|graph| {
    // do something with the graph
});
// The handle must be kept to keep receiving updates on the other peers.
// To stop receiving update, drop the handle.

pub fn disk_usage(&self) -> &DiskUsage

Return a DiskUsage to monitor the disk usage of the Ditto instance. It can be used to retrieve an immediate representation of the Ditto file system:

let fs_tree = ditto.disk_usage().exec();

Or to bind a callback to the changes :

let handle = ditto.disk_usage().observe(|fs_tree| {
    // do something with the graph
});
// The handle must be kept to keep receiving updates on the file system.
// To stop receiving update, drop the handle.

pub fn root_dir(&self) -> &Path

👎Deprecated: Use persistence_directory instead

Returns the DittoRoot path.

pub fn data_dir(&self) -> &Path

👎Deprecated: Use persistence_directory instead

Returns the ditto persistence data directory path.

pub fn authenticator(&self) -> Option<DittoAuthenticator>

Returns the current DittoAuthenticator, if it exists.

pub fn is_activated(&self) -> bool

Has this Ditto instance been activated yet with a valid license token.

impl Ditto

pub fn builder() -> DittoBuilder

Returns a builder for Ditto following the builder pattern.

Start constructing a new Ditto instance.

pub fn new(app_id: AppId) -> Ditto

Construct a Ditto instance with sensible defaults.

This instance will still need to have a license set (if necessary) and sync functionality manually started.

impl Ditto

pub fn run_garbage_collection(&self)

Removes all sync metadata for any remote peers which aren’t currently connected. This method shouldn’t usually be called. Manually running garbage collection often will result in slower sync times. Ditto automatically runs a garbage a collection process in the background at optimal times.

Manually running garbage collection is typically only useful during testing if large amounts of data are being generated. Alternatively, if an entire data set is to be evicted and it’s clear that maintaining this metadata isn’t necessary, then garbage collection could be run after evicting the old data.

pub fn disable_sync_with_v3(&self) -> Result<(), DittoError>

Explicitly opt-in to disabling the ability to sync with Ditto peers running any version of the SDK in the v3 (or lower) series of releases.

Assuming this succeeds then this peer will only be able to sync with other peers using SDKs in the v4 (or higher) series of releases. Note that this disabling of sync spreads to peers that sync with a peer that has disabled, or has (transitively) had disabled, syncing with v3 SDK peers.

Trait Implementations

impl Deref for Ditto

type Target = DittoFields

The resulting type after dereferencing.

fn deref(&self) -> &DittoFields

Dereferences the value.

impl Drop for Ditto

fn drop(&mut self)

Executes the destructor for this type.