dittolive-ditto 4.3.1

//! # Ditto needs an `Identity` to start syncing with other peers.
//!
//! The various identity configurations that you can use when initializing a `Ditto` instance.
//!
//! - [`OfflinePlayground`](crate::prelude::OfflinePlayground): Develop peer-to-peer apps with no
//! cloud connection. This mode offers no security and must only be used for development.
//! - [`OnlineWithAuthentication`](crate::prelude::OnlineWithAuthentication): Run Ditto in secure
//! production mode, logging on to Ditto Cloud or on on-premises authentication server. User
//! permissions are centrally managed.
//! - [`OnlinePlayground`](crate::prelude::OnlinePlayground): Test a Ditto Cloud app with weak
//! shared token authentication ("Playground mode"). This mode is not secure and must only be used
//! for development.
//! - [`SharedKey`](crate::prelude::SharedKey): A mode where any device is trusted provided they
//! know the secret key. This is a simplistic authentication model normally only suitable for
//! private apps where users and devices are both trusted.
//! - [`Manual`](crate::prelude::Manual): A Ditto peer identity that was created manually rather
//! than generated by an identity service. This is a text bundle beginning with the line `-----BEGIN
//! DITTO IDENTITY-----`. To learn how to create and use Manual Identities please refer to Ditto's
//! online documentation.

use std::sync::{Arc, Mutex};

use ffi_sdk::BoxedIdentityConfig;

use crate::{
    auth::login_provider::{DittoAuthenticationEventHandler, LoginProvider},
    ditto::AppId,
    error::{DittoError, ErrorKind},
};
use_prelude!();

pub(crate) type SharedIdentity = Arc<dyn Identity>;

// Identity is pub because it is part of the Builder's public interface
// It is therefore Sealed to prevent downstream implementations
#[doc(hidden)]
pub trait Identity: private::Sealed + Send + Sync {
    /// Consumes the identity's built IdentityConfig
    fn identity_config(&self) -> Option<BoxedIdentityConfig>;

    /// Returns the underlying `DittoAuthenticator` if specified
    fn authenticator(&self) -> Option<DittoAuthenticator> {
        None
    }

    /// REFACTOR(Ham): This is necessary for a couple of reasons:
    ///
    /// 1. we only want to pass down our login provider down into the Rust core once we've had a
    ///    chance to make the FFI `Ditto` object and store a reference to it in the
    ///    `DittoAuthenticator`
    /// 2. we pass around `DittoAuthenticator`s rather than `Arc<DittoAuthenticator>`s, and so we
    ///    have to explicitly set the authenticator on the `LoginProvider` instance that exists for
    ///    `OnlineWithAuthentication` identities rather than being able to set it on the
    ///    `DittoAuthenticator` we get from the initial creation of the identity
    fn set_login_provider(&self, _authenticator: Option<DittoAuthenticator>) {}

    /// Indicates if cloud sync should be enabled by default
    fn is_cloud_sync_enabled(&self) -> bool;

    /// Returns the configured URL for Auth
    fn auth_url(&self) -> Result<String, DittoError>;

    /// Returns the configured URL for WebSocket sync
    fn sync_url(&self) -> Result<String, DittoError>;

    /// Indicates whether the specific Identity type requires an offline only license token to be
    /// set.
    fn requires_offline_only_license_token(&self) -> bool;
}

/// Run Ditto in secure production mode, logging on to Ditto Cloud or an
/// on-premises authentication server. User permissions are centrally managed.
/// Sync will not work until a successful login has occurred.
///
/// The only required configuration is the application's UUID, which can be
/// found on the Ditto portal where the app is registered.
///
/// By default cloud sync is enabled. This means the SDK will sync to a Big Peer
/// in Ditto's cloud when an internet connection is available. This is
/// controlled by the `enable_cloud_sync` parameter. If `true` (default), a
/// suitable wss:// URL will be added to the
/// [`TransportConfig`](crate::prelude::TransportConfig).
///
/// To prevent cloud sync, or to specify your own URL later, pass `false`.
///
/// Authentication requests are handled by Ditto's cloud by default, configured
/// in the portal at `<https://portal.ditto.live>`.
///
/// To use a different or on-premises authentication service, pass a custom
/// HTTPS base URL as the * `auth_url` parameter.
pub struct OnlineWithAuthentication {
    app_id: AppId,
    enable_cloud_sync: bool,
    auth_url: String,
    identity_config: Mutex<Option<BoxedIdentityConfig>>,
    authenticator: DittoAuthenticator,
    auth_event_handler: Mutex<Option<Box<dyn DittoAuthenticationEventHandler + 'static>>>,
}

#[deprecated(note = "use OnlinePlayground instead")]
pub type OnlinePlaygroundV2 = OnlinePlayground;

/// Test a Ditto Cloud app with a simple shared token ("Playground mode"). This
/// mode offers no security and must only be used for development. Other
/// behavior mirrors the
/// [`OnlineWithAuthentication`](crate::prelude::OnlineWithAuthentication)
/// identity.
pub struct OnlinePlayground {
    app_id: AppId,
    enable_cloud_sync: bool,
    auth_url: String,
    identity_config: Mutex<Option<BoxedIdentityConfig>>,
    authenticator: DittoAuthenticator,
}

/// Develop peer-to-peer apps with no cloud connection. This mode offers no
/// security and must only be used for development. In this mode, any string can
/// be used as the name of the app.
pub struct OfflinePlayground {
    identity_config: Mutex<Option<BoxedIdentityConfig>>,
}

/// An identity where any device is trusted provided they know the secret key.
/// This is a simplistic authentication model normally only suitable for private
/// apps where users and devices are both trusted. In this mode, any string may
/// be used as the app id.
pub struct SharedKey {
    identity_config: Mutex<Option<BoxedIdentityConfig>>,
}

/// An identity where devices are manually configured with a x509 certificate
/// bundle
pub struct Manual {
    identity_config: Mutex<Option<BoxedIdentityConfig>>,
}

impl OnlineWithAuthentication {
    /// Construct an OnlineWithAuthentication Identity.
    ///
    /// - `ditto_root`: The directory containing ditto local storage
    /// - `app_id`: The unique identifier of the application, usually a UUIDv4 string
    /// - `auth_event_handler`: A user created type which implements the
    ///   `DittoAuthenticationEventHandler` trait
    /// - `enable_cloud_sync`: whether cloud sync should be started by default
    /// - `custom_auth_url`: an optional custom authentication URL; default is is `cloud.ditto.live`
    pub fn new(
        _ditto_root: Arc<dyn DittoRoot>, // TODO: Remove this in a future major release (v5)
        app_id: AppId,
        auth_event_handler: impl DittoAuthenticationEventHandler + 'static,
        enable_cloud_sync: bool,
        custom_auth_url: Option<&str>,
    ) -> Result<Self, DittoError> {
        let auth_url = match custom_auth_url {
            Some(url) => url.to_owned(),
            None => app_id.default_auth_url(),
        };
        let c_app_id = char_p::new(app_id.to_string());
        let c_auth_url = char_p::new(auth_url.as_str());

        let identity_config = Mutex::new(Some(
            ffi_sdk::ditto_identity_config_make_online_with_authentication(
                c_app_id.as_ref(),
                c_auth_url.as_ref(),
            )
            .ok_or(ErrorKind::Config)?,
        ));

        let authenticator = DittoAuthenticator::new();

        Ok(OnlineWithAuthentication {
            app_id,
            enable_cloud_sync,
            auth_url,
            identity_config,
            authenticator,
            auth_event_handler: Mutex::new(Some(Box::new(auth_event_handler))),
        })
    }
}

impl Identity for OnlineWithAuthentication {
    fn identity_config(&self) -> Option<BoxedIdentityConfig> {
        let mut config = self.identity_config.lock().unwrap();
        config.take()
    }

    fn authenticator(&self) -> Option<DittoAuthenticator> {
        Some(self.authenticator.retain())
    }

    fn set_login_provider(&self, authenticator: Option<DittoAuthenticator>) {
        let mut auth_event_handler = self.auth_event_handler.lock().unwrap();
        let auth_event_handler = auth_event_handler
            .take()
            .expect("auth event handler is some");

        let login_provider = LoginProvider::new(auth_event_handler);
        let LoginProvider {
            _provider: c_provider,
            ctx,
        } = login_provider;

        let authenticator = authenticator.expect("authenticator is some");
        let ditto = authenticator
            .ditto_fields
            .upgrade()
            .expect("ditto fields is alive")
            .ditto
            .retain();
        ctx.lock().unwrap().set_authenticator(authenticator);
        ffi_sdk::ditto_auth_set_login_provider(&ditto, c_provider);
    }

    fn is_cloud_sync_enabled(&self) -> bool {
        self.enable_cloud_sync
    }

    fn auth_url(&self) -> Result<String, DittoError> {
        Ok(self.auth_url.to_owned())
    }

    fn sync_url(&self) -> Result<String, DittoError> {
        Ok(self.app_id.default_sync_url())
    }

    fn requires_offline_only_license_token(&self) -> bool {
        false
    }
}

impl OnlinePlayground {
    /// Construct a new `OnlinePlayground` identity.
    ///
    /// - `ditto_root`: Instance of DittoRoot indicating local storage directory
    /// - `app_id`: A unique AppId which must be a valid UUIDv4
    /// - `shared_token`: A shared token used to set up the `OnlinePlayground` session. This token
    ///   is provided by the portal when setting up the application.
    /// - `enable_cloud_sync`: Should WebSocket sync with `wss://<app_id>.cloud.ditto.live` be
    ///   enabled by default. Do not enable this if you want to provide a custom sync URL later
    /// - `custom_auth_url`: An optional alternative URL for authentication requests. Defaults to `https://<app_id>.cloud.ditto.live/`
    pub fn new(
        _ditto_root: Arc<dyn DittoRoot>, // TODO: Remove this in a future major release (v5)
        app_id: AppId,
        shared_token: String,
        enable_cloud_sync: bool,
        custom_auth_url: Option<&str>,
    ) -> Result<Self, DittoError> {
        let c_app_id = app_id.to_c_string();
        let c_shared_token = char_p::new(shared_token.as_str());
        let auth_url = match custom_auth_url {
            Some(url) => url.to_owned(),
            None => app_id.default_auth_url(),
        };
        let c_auth_url = char_p::new(auth_url.as_str());
        let identity_config = Mutex::new(Some(
            ffi_sdk::ditto_identity_config_make_online_playground(
                c_app_id.as_ref(),
                c_shared_token.as_ref(),
                c_auth_url.as_ref(),
            )
            .ok_or(ErrorKind::Config)?,
        ));
        let authenticator = DittoAuthenticator::new();
        Ok(Self {
            app_id,
            enable_cloud_sync,
            auth_url,
            identity_config,
            authenticator,
        })
    }
}

impl Identity for OnlinePlayground {
    fn identity_config(&self) -> Option<BoxedIdentityConfig> {
        let mut config = self.identity_config.lock().unwrap();
        config.take()
    }

    fn authenticator(&self) -> Option<DittoAuthenticator> {
        Some(self.authenticator.retain())
    }

    fn auth_url(&self) -> Result<String, DittoError> {
        Ok(self.auth_url.to_owned())
    }

    fn sync_url(&self) -> Result<String, DittoError> {
        Ok(self.app_id.default_sync_url())
    }

    fn is_cloud_sync_enabled(&self) -> bool {
        self.enable_cloud_sync
    }

    fn requires_offline_only_license_token(&self) -> bool {
        false
    }
}

impl OfflinePlayground {
    /// Construct an `OfflinePlayground` identity.
    ///
    /// - `ditto_root`: Location for the local database
    /// - `app_id`: A unique string identifying the App. For an `OfflinePlayground` identity this
    ///   does not need to be a UUIDv4.
    // TODO: Remove `ditto_root` in a future major release (v5)
    pub fn new(_ditto_root: Arc<dyn DittoRoot>, app_id: AppId) -> Result<Self, DittoError> {
        let c_app_id = app_id.to_c_string();
        let identity_config = Mutex::new(Some(
            ffi_sdk::ditto_identity_config_make_offline_playground(c_app_id.as_ref(), 0)
                .ok_or(ErrorKind::Config)?,
        ));
        Ok(Self { identity_config })
    }

    /// Generate an `OfflinePlayground` identity with a random AppId for testing
    pub fn random(ditto_root: Arc<dyn DittoRoot>) -> Result<Self, DittoError> {
        let app_id = AppId::generate();
        Self::new(ditto_root, app_id)
    }
}

impl Identity for OfflinePlayground {
    fn identity_config(&self) -> Option<BoxedIdentityConfig> {
        let mut config = self.identity_config.lock().unwrap();
        config.take()
    }

    fn is_cloud_sync_enabled(&self) -> bool {
        false
    }

    fn auth_url(&self) -> Result<String, DittoError> {
        Err(DittoError::new(
            ErrorKind::InvalidInput,
            "Cloud Auth is not enabled for OfflinePlayground Identities".to_string(),
        ))
    }
    fn sync_url(&self) -> Result<String, DittoError> {
        Err(DittoError::new(
            ErrorKind::InvalidInput,
            "Cloud sync is not enabled for OfflinePlayground Identities".to_string(),
        ))
    }

    fn requires_offline_only_license_token(&self) -> bool {
        true
    }
}

impl SharedKey {
    /// Construct a `SharedKey` identity.
    ///
    /// - `ditto_root`: An instance of `DittoRoot` for local storage
    /// - `app_id`: The unique UUIDv4 identifying this app; must be shared across all instances
    /// - `key_der_b64`: A pre-shared key for securing peer-to-peer communication encoded as a
    ///   Base64 string
    pub fn new(
        _ditto_root: Arc<dyn DittoRoot>, // TODO: Remove this in a future major release (v5)
        app_id: AppId,
        key_der_b64: &str,
    ) -> Result<Self, DittoError> {
        let c_app_id = app_id.to_c_string();
        let c_key_der = char_p::new(key_der_b64);
        let identity_config = Mutex::new(Some(
            ffi_sdk::ditto_identity_config_make_shared_key(
                c_app_id.as_ref(),
                c_key_der.as_ref(),
                0,
            )
            .ok_or(ErrorKind::Config)?,
        ));
        Ok(Self { identity_config })
    }
}

impl Identity for SharedKey {
    fn identity_config(&self) -> Option<BoxedIdentityConfig> {
        let mut config = self.identity_config.lock().unwrap();
        config.take()
    }

    fn auth_url(&self) -> Result<String, DittoError> {
        let msg = "SharedKey Identities don't support auth urls".to_owned();
        Err(DittoError::new(ErrorKind::Config, msg))
    }

    fn sync_url(&self) -> Result<String, DittoError> {
        let msg = "SharedKey Identities to support cloud sync".to_owned();
        Err(DittoError::new(ErrorKind::Config, msg))
    }

    fn is_cloud_sync_enabled(&self) -> bool {
        false
    }

    fn requires_offline_only_license_token(&self) -> bool {
        true
    }
}

impl Manual {
    /// Construct a `Manual` identity.
    ///
    /// A Ditto peer identity that was created manually rather than generated by an identity
    /// service. This is a text bundle beginning with the line "-----BEGIN DITTO IDENTITY-----".
    /// To learn how to create and use Manual Identities please refer to Ditto's online
    /// documentation.
    ///
    /// - `manual_identity`: a multiline string containing a Manual Identity bundle
    pub fn new(manual_identity: impl Into<String>) -> Result<Self, DittoError> {
        let manual_identity_str = char_p::new(manual_identity.into());
        let identity_config = Mutex::new(Some(
            ffi_sdk::ditto_identity_config_make_manual(manual_identity_str.as_ref())
                .ok_or(ErrorKind::Config)?,
        ));
        Ok(Self { identity_config })
    }
}

impl Identity for Manual {
    fn identity_config(&self) -> Option<BoxedIdentityConfig> {
        let mut config = self.identity_config.lock().unwrap();
        config.take()
    }

    fn auth_url(&self) -> Result<String, DittoError> {
        let msg = "Manual Identities don't support auth urls".to_owned();
        Err(DittoError::new(ErrorKind::Config, msg))
    }

    fn sync_url(&self) -> Result<String, DittoError> {
        let msg = "Manual Identities to support cloud sync".to_owned();
        Err(DittoError::new(ErrorKind::Config, msg))
    }

    fn is_cloud_sync_enabled(&self) -> bool {
        false
    }

    fn requires_offline_only_license_token(&self) -> bool {
        true
    }
}

mod private {
    use super::*;
    pub trait Sealed {}
    impl Sealed for OnlineWithAuthentication {}
    impl Sealed for OnlinePlayground {}
    impl Sealed for OfflinePlayground {}
    impl Sealed for SharedKey {}
    impl Sealed for Manual {}
}