Struct Ditto

pub struct Ditto { /* private fields */ }

The entrypoint for accessing all Ditto functionality.

Use the Ditto object to access all other Ditto APIs, such as:

• ditto.store() to access the Store API and read and write data on this peer
• ditto.sync() to access the Sync API and sync data with other peers
• ditto.presence() to access the Presence API and inspect connected peers
• ditto.small_peer_info() to access the SmallPeerInfo API and manage peer metadata
• ditto.disk_usage() to access the DiskUsage API and inspect disk usage

Implementations

impl Ditto

pub async fn open(config: DittoConfig) -> Result<Ditto, DittoError>

Open a new Ditto instance using a DittoConfig

Example

// Load your database ID somehow, ENV is a good option
let database_id = std::env::var("DITTO_DATABASE_ID")?;

// Choose one of the following types of connection config
let connect = DittoConfigConnect::Server {
    url: "https://example.com/your-server-url".parse().unwrap(),
};
let connect = DittoConfigConnect::SmallPeersOnly {
    private_key: Some("https://example.com/your-server-url".bytes().collect()),
};
let connect = DittoConfigConnect::SmallPeersOnly { private_key: None };

let config = DittoConfig::new(database_id, connect);
let ditto = Ditto::open(config).await?;

pub fn open_sync(config: DittoConfig) -> Result<Ditto, DittoError>

Open a new Ditto instance using a DittoConfig

This is a synchronous blocking variant of Ditto::open() that will wait until initialization is complete.

Example

// Load your database ID somehow, ENV is a good option
let database_id = std::env::var("DITTO_DATABASE_ID")?;

// Choose one of the following types of connection config
let connect = DittoConfigConnect::Server {
    url: "https://example.com/your-server-url".parse().unwrap(),
};
let connect = DittoConfigConnect::SmallPeersOnly {
    private_key: Some("https://example.com/your-server-url".bytes().collect()),
};
let connect = DittoConfigConnect::SmallPeersOnly { private_key: None };

let config = DittoConfig::new(database_id, connect);
let ditto = Ditto::open_sync(config)?;

impl Ditto

pub fn close(self)

Clean shutdown of the Ditto instance

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

Starts the network transports. Ditto will connect to other devices.

By default, Ditto will enable all peer-to-peer transport types. The network configuration can be customized using set_transport_config.

Performance of initial sync when bootstrapping a new peer can be improved by calling disable_sync_with_v3 before calling start_sync. Only do this when all peers in the mesh are known to be running Ditto v4 or higher.

pub fn stop_sync(&self)

Stop syncing on all transports.

You may continue to use the Ditto store locally but no data will sync to or from other devices.

pub fn is_sync_active(&self) -> bool

Returns true if sync is currently active, otherwise returns false.

Use Ditto::start_sync to activate and Ditto::stop_sync to deactivate sync.

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 update_transport_config(&self, update: impl FnOnce(&mut TransportConfig))

Convenience method to update the current transport config of the receiver.

Invokes the block with a copy of the current transport config which you can alter to your liking. The updated transport config is then set on the receiver.

You may use this method to alter the configuration at any time. Sync will not begin until ditto.start_sync() is invoked.

Example

Edit the config by simply mutating the &mut TransportConfig passed to your callback:

use dittolive_ditto::prelude::*;

// Enable the TCP listener on port 4000
ditto.update_transport_config(|config| {
    config.listen.tcp.enabled = true;
    config.listen.tcp.interface_ip = "0.0.0.0".to_string();
    config.listen.tcp.port = 4000;
});

pub fn transport_config(&self) -> TransportConfig

Returns a snapshot of the currently configured transports.

Example

let transport_config = ditto.transport_config();
println!("Current transport config: {transport_config:#?}");

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_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.

impl Ditto

pub fn store(&self) -> &Store

Returns a reference to the underlying local data store.

pub fn sync(&self) -> &Sync

Entrypoint to Ditto’s Sync API for syncing documents between peers.

pub fn small_peer_info(&self) -> &SmallPeerInfo

Return a reference to the SmallPeerInfo object.

pub fn absolute_persistence_directory(&self) -> PathBuf

The absolute path to the persistence directory used by Ditto to persist data.

This returns the final, resolved absolute file path where Ditto stores its data. The value depends on what was provided in DittoConfig::persistence_directory.

• If an absolute path was provided, it returns that path unchanged.
• If a relative path was provided, it returns the path resolved relative to [ditto.default_root_directory()].
• If no path was provided, it returns the default path using the pattern {default_root}/ditto-{database-id} where {default_root} corresponds to [ditto.default_root_directory()] and {database-id} is the Ditto database ID in lowercase.

This property always returns a consistent value throughout the lifetime of the Ditto instance and represents the actual directory being used for persistence.

• Note: “Database ID” was previously referred to as “App ID” in older versions of the SDK.

• Note: It is not recommended to directly read or write to this directory as its structure and contents are managed by Ditto and may change in future versions.

• Note: When DittoLogger is enabled, logs may be written to this directory even after a Ditto instance has been deallocated. Please refer to the documentation of DittoLogger for more information.

• See also: DittoConfig::persistence_directory

pub fn config(&self) -> DittoConfig

Returns an owned snapshot of the effective DittoConfig as used by the core library.

• Modifying this DittoConfig have no effect on the active Ditto configuration.
• The returned DittoConfig may be different than the one passed to [Ditto::open{,_sync}] because it will have resolved details such as the absolute path to the persistence directory.

pub fn app_id(&self) -> AppId

Returns the AppId 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 presence(&self) -> &Arc<Presence>

Return a handle to the Presence API to monitor peers’ activity in the Ditto mesh.

Example

Use ditto.presence().graph() to request a current PresenceGraph of connected peers:

use dittolive_ditto::prelude::*;

let presence_graph: PresenceGraph = ditto.presence().graph();
println!("Ditto mesh right now: {presence_graph:#?}");

Example

Use ditto.presence().observe(...) to subscribe to changes in mesh presence:

use dittolive_ditto::prelude::*;

let _observer = ditto.presence().observe(|graph| {
    println!("Ditto mesh update! {graph:#?}");
});

// The observer is cancelled when dropped.
// In a real application, hold onto it for as long as you need it alive.
drop(_observer);

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 auth(&self) -> Option<DittoAuthenticator>

Returns the current DittoAuthenticator, if it exists.

The DittoAuthenticator is available when using the OnlinePlayground and OnlineWithAuthentication identities.

pub fn is_activated(&self) -> bool

Returns true if this Ditto instance has been activated with a valid license token.

impl Ditto

pub fn builder() -> DittoBuilder

Entrypoint to constructing Ditto with the builder pattern.

Example

use dittolive_ditto::prelude::*;

fn main() -> anyhow::Result<()> {
    let app_id = AppId::from_env("DITTO_APP_ID")?;
    let playground_token = std::env::var("DITTO_PLAYGROUND_TOKEN")?;
    let cloud_sync = true;
    let custom_auth_url = None;

    // Initialize Ditto
    let ditto = Ditto::builder()
        .with_root(Arc::new(PersistentRoot::from_current_exe()?))
        .with_identity(|ditto_root| {
            identity::OnlinePlayground::new(
                ditto_root,
                app_id,
                playground_token,
                cloud_sync,
                custom_auth_url,
            )
        })?
        .build()?;

    Ok(())
}

See the crate docs for examples of what to do next using Ditto.

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>

Disable sync with peers running version 3 or lower of the Ditto SDK.

Required for the execution of mutating DQL statements.

This setting spreads to other peers on connection. Those peers will in turn spread it further until all peers in the mesh take on the same setting. This is irreversible and will persist across restarts of the Ditto instance.

Calling this method before calling start_sync is recommended whenever possible. This improves performance of initial sync when this peer has never before connected to a Ditto mesh for which sync with v3 peers is disabled.

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.