pharos_runtime_database/

backend_registry.rs

#![forbid(unsafe_code)]

use std::collections::BTreeMap;
use std::sync::Arc;

use crate::backend::{BackendError, BackendKind, PrimaryBackend};
use crate::operations::{DatabaseError, DatabaseOperations, valid_identifier};

#[derive(Default)]
/// Immutable registry of primary backends available to the runtime.
///
/// # Fields
///
/// - This type stores module-owned state for [`crate::backend_registry::BackendRegistry`].
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_integrations::backend_registry::BackendRegistry>();
/// ```
///
/// # Related
///
/// - [`crate::backend_registry`] for constructors, helpers, and neighboring runtime types.
pub struct BackendRegistry {
    backends: BTreeMap<&'static str, Arc<dyn PrimaryBackend>>,
    operations: BTreeMap<&'static str, Arc<dyn DatabaseOperations>>,
}

impl BackendRegistry {
    /// Creates one empty backend registry.
    ///
    /// # Returns
    ///
    /// Returns the computed value produced by [`crate::backend_registry::new`].
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::new();
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn new() -> Self {
        Self::default()
    }

    /// Registers one primary backend under its stable backend name.
    ///
    /// # Parameters
    ///
    /// - `backend`: Input consumed by [`crate::backend_registry::register`].
    ///
    /// # Returns
    ///
    /// Returns the successful value produced by [`crate::backend_registry::register`] or an error when the operation fails.
    ///
    /// # Errors
    ///
    /// Returns an error value when [`crate::backend_registry::register`] cannot complete successfully.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::register(todo!());
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn register(&mut self, backend: Arc<dyn PrimaryBackend>) -> Result<(), BackendError> {
        let name = backend.name();
        if self.backends.contains_key(name) {
            return Err(BackendError::DuplicateBackend(name.to_owned()));
        }
        self.backends.insert(name, backend);
        Ok(())
    }

    /// Registers the executable operations for one backend in this same registry.
    pub fn register_operations(
        &mut self,
        name: &'static str,
        adapter: Arc<dyn DatabaseOperations>,
    ) -> Result<(), DatabaseError> {
        if !valid_identifier(name)
            || adapter.backend_name() != name
            || self.operations.contains_key(name)
        {
            return Err(DatabaseError::InvalidContract);
        }
        // The required operation trait is the execution contract. Metadata
        // cannot restrict future adapters to the shipped BackendKind enum.
        if let Some(backend) = self.backends.get(name) {
            let capabilities = backend.capabilities();
            if !capabilities.readiness
                || !capabilities.migrations
                || !capabilities.transactions
                || !capabilities.export
                || !capabilities.import
            {
                return Err(DatabaseError::InvalidContract);
            }
        }
        self.operations.insert(name, adapter);
        Ok(())
    }

    /// Resolves an executable adapter; metadata registration alone cannot satisfy it.
    /// Invalid names are input errors; a valid but unregistered name is unavailable.
    pub fn resolve_operations(
        &self,
        name: &str,
    ) -> Result<Arc<dyn DatabaseOperations>, DatabaseError> {
        if !valid_identifier(name) {
            return Err(DatabaseError::InvalidInput);
        }
        self.operations
            .get(name)
            .cloned()
            .ok_or(DatabaseError::Unavailable)
    }

    /// Resolves one backend by its stable config name.
    ///
    /// # Parameters
    ///
    /// - `name`: Input consumed by [`crate::backend_registry::resolve`].
    ///
    /// # Returns
    ///
    /// Returns the successful value produced by [`crate::backend_registry::resolve`] or an error when the operation fails.
    ///
    /// # Errors
    ///
    /// Returns an error value when [`crate::backend_registry::resolve`] cannot complete successfully.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::resolve("name");
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn resolve(&self, name: &str) -> Result<Arc<dyn PrimaryBackend>, BackendError> {
        self.backends
            .get(name)
            .cloned()
            .ok_or_else(|| BackendError::UnknownBackend(name.to_owned()))
    }

    /// Resolves one backend by typed backend kind.
    ///
    /// # Parameters
    ///
    /// - `kind`: Input consumed by [`crate::backend_registry::resolve_kind`].
    ///
    /// # Returns
    ///
    /// Returns the successful value produced by [`crate::backend_registry::resolve_kind`] or an error when the operation fails.
    ///
    /// # Errors
    ///
    /// Returns an error value when [`crate::backend_registry::resolve_kind`] cannot complete successfully.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::resolve_kind(todo!());
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn resolve_kind(&self, kind: BackendKind) -> Result<Arc<dyn PrimaryBackend>, BackendError> {
        self.resolve(kind.as_str())
    }

    /// Returns whether the registry contains the named backend.
    ///
    /// # Parameters
    ///
    /// - `name`: Input consumed by [`crate::backend_registry::contains`].
    ///
    /// # Returns
    ///
    /// Returns `true` when the condition checked by [`crate::backend_registry::contains`] holds and `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::contains("name");
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn contains(&self, name: &str) -> bool {
        self.backends.contains_key(name)
    }

    /// Returns the number of registered backends.
    ///
    /// # Returns
    ///
    /// Returns the computed value produced by [`crate::backend_registry::len`].
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::len();
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn len(&self) -> usize {
        self.backends.len()
    }

    /// Returns whether no backends are registered.
    ///
    /// # Returns
    ///
    /// Returns `true` when the condition checked by [`crate::backend_registry::is_empty`] holds and `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust,ignore
    /// let _result = pharos_runtime_integrations::backend_registry::is_empty();
    /// ```
    ///
    /// # Related
    ///
    /// - [`crate::backend_registry`] for adjacent helpers that share the same runtime surface.
    pub fn is_empty(&self) -> bool {
        self.backends.is_empty()
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::BackendRegistry;
    use crate::backend::{BackendCapabilities, BackendError, BackendKind, PrimaryBackend};

    /// Keeps unavailable configuration distinct from malformed user input.
    #[test]
    fn executable_resolution_preserves_error_category() {
        let registry = BackendRegistry::new();
        assert!(matches!(
            registry.resolve_operations("missing_adapter"),
            Err(crate::operations::DatabaseError::Unavailable)
        ));
        assert!(matches!(
            registry.resolve_operations("../adapter"),
            Err(crate::operations::DatabaseError::InvalidInput)
        ));
    }

    struct StubBackend {
        kind: BackendKind,
        capabilities: BackendCapabilities,
    }

    impl PrimaryBackend for StubBackend {
        /// Performs kind.
        fn kind(&self) -> BackendKind {
            self.kind
        }

        /// Performs capabilities.
        fn capabilities(&self) -> BackendCapabilities {
            self.capabilities
        }
    }

    #[test]
    /// Performs registers and resolves backend by name.
    fn registers_and_resolves_backend_by_name() {
        let mut registry = BackendRegistry::new();
        let backend = Arc::new(StubBackend {
            kind: BackendKind::Sqlite,
            capabilities: BackendCapabilities {
                readiness: true,
                ..BackendCapabilities::default()
            },
        });
        registry
            .register(backend.clone())
            .expect("register backend");

        let resolved = registry.resolve("sqlite").expect("resolve backend");
        assert_eq!(resolved.kind(), BackendKind::Sqlite);
        assert!(resolved.capabilities().readiness);
    }

    #[test]
    /// Performs rejects duplicate backend registration.
    fn rejects_duplicate_backend_registration() {
        let mut registry = BackendRegistry::new();
        registry
            .register(Arc::new(StubBackend {
                kind: BackendKind::Sqlite,
                capabilities: BackendCapabilities::default(),
            }))
            .expect("first register");

        let duplicate = registry.register(Arc::new(StubBackend {
            kind: BackendKind::Sqlite,
            capabilities: BackendCapabilities::default(),
        }));

        assert_eq!(
            duplicate,
            Err(BackendError::DuplicateBackend("sqlite".to_owned()))
        );
    }

    #[test]
    /// Performs rejects unknown backend name.
    fn rejects_unknown_backend_name() {
        let registry = BackendRegistry::new();
        let result = registry.resolve("oracle");
        assert!(matches!(
            result,
            Err(BackendError::UnknownBackend(name)) if name == "oracle"
        ));
    }

    #[test]
    /// Performs resolves registered MySQL backend.
    fn resolves_registered_mysql_backend() {
        let mut registry = BackendRegistry::new();
        registry
            .register(Arc::new(StubBackend {
                kind: BackendKind::Mysql,
                capabilities: BackendCapabilities {
                    transactions: true,
                    ..BackendCapabilities::default()
                },
            }))
            .expect("register mysql backend");

        let resolved = registry.resolve("mysql").expect("resolve mysql backend");
        assert_eq!(resolved.kind(), BackendKind::Mysql);
        assert!(resolved.capabilities().transactions);
    }

    #[test]
    /// Performs resolves registered MongoDB backend.
    fn resolves_registered_mongodb_backend() {
        let mut registry = BackendRegistry::new();
        registry
            .register(Arc::new(StubBackend {
                kind: BackendKind::Mongodb,
                capabilities: BackendCapabilities {
                    export: true,
                    import: true,
                    ..BackendCapabilities::default()
                },
            }))
            .expect("register mongodb backend");

        let resolved = registry
            .resolve("mongodb")
            .expect("resolve mongodb backend");
        assert_eq!(resolved.kind(), BackendKind::Mongodb);
        assert!(resolved.capabilities().export);
        assert!(resolved.capabilities().import);
    }

    #[test]
    /// Performs resolves backend by kind.
    fn resolves_backend_by_kind() {
        let mut registry = BackendRegistry::new();
        registry
            .register(Arc::new(StubBackend {
                kind: BackendKind::Postgresql,
                capabilities: BackendCapabilities {
                    transactions: true,
                    ..BackendCapabilities::default()
                },
            }))
            .expect("register backend");

        let resolved = registry
            .resolve_kind(BackendKind::Postgresql)
            .expect("resolve by kind");
        assert_eq!(resolved.kind(), BackendKind::Postgresql);
        assert!(resolved.capabilities().transactions);
    }
}