nidus-core 1.0.0

Core Nidus dependency injection, modules, provider lifetimes, and application lifecycle.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Application bootstrap primitives.

use crate::{Container, LifecycleRunner, Module, ModuleDefinition, ModuleGraph, Result};

/// Bootstrapped Nidus application.
pub struct Application {
    container: Container,
    modules: ModuleGraph,
    lifecycle: LifecycleRunner,
}

impl Application {
    /// Creates an application from an already validated container and graph.
    pub fn new(container: Container, modules: ModuleGraph) -> Self {
        Self {
            container,
            modules,
            lifecycle: LifecycleRunner::empty(),
        }
    }

    /// Creates an application from an already validated container, graph, and lifecycle runner.
    pub fn with_lifecycle(
        container: Container,
        modules: ModuleGraph,
        lifecycle: LifecycleRunner,
    ) -> Self {
        Self {
            container,
            modules,
            lifecycle,
        }
    }

    /// Returns the application dependency container.
    pub fn container(&self) -> &Container {
        &self.container
    }

    /// Returns the validated module graph.
    pub fn modules(&self) -> &ModuleGraph {
        &self.modules
    }

    /// Runs application shutdown hooks.
    pub async fn shutdown(&self) -> Result<()> {
        self.lifecycle.shutdown().await
    }
}

/// Framework bootstrap entrypoint.
pub struct Nidus;

impl Nidus {
    /// Bootstraps a Nidus application from a root module definition.
    ///
    /// The module graph is validated and the container is populated with the root
    /// module graph's typed providers. Synchronous providers are registered here;
    /// providers that require async initialization are not run by this synchronous
    /// entrypoint and need [`Nidus::bootstrap_with_lifecycle`] (or the facade
    /// builder) to construct.
    pub fn bootstrap<M: Module>() -> Result<Application> {
        let graph = ModuleGraph::from_root::<M>()?;
        let mut container = Container::new();
        register_module_providers(&mut container, &graph)?;
        Ok(Application::new(container, graph))
    }

    /// Bootstraps a Nidus application from a root module and explicit graph definitions.
    ///
    /// Like [`Nidus::bootstrap`], this validates the graph and registers synchronous
    /// typed providers. Async provider initializers are not run by this synchronous
    /// entrypoint.
    pub fn bootstrap_with_modules<M, I>(modules: I) -> Result<Application>
    where
        M: Module,
        I: IntoIterator<Item = ModuleDefinition>,
    {
        let graph = ModuleGraph::from_root_and_modules::<M, I>(modules)?;
        let mut container = Container::new();
        register_module_providers(&mut container, &graph)?;
        Ok(Application::new(container, graph))
    }

    /// Bootstraps a Nidus application and runs startup lifecycle hooks.
    ///
    /// Typed providers are registered and async provider initializers run before
    /// startup hooks, so hooks can resolve fully initialized providers.
    pub async fn bootstrap_with_lifecycle<M: Module>(
        lifecycle: LifecycleRunner,
    ) -> Result<Application> {
        let graph = ModuleGraph::from_root::<M>()?;
        let mut container = Container::new();
        register_module_providers(&mut container, &graph)?;
        initialize_module_providers(&mut container, &graph).await?;
        lifecycle.startup().await?;
        Ok(Application::with_lifecycle(container, graph, lifecycle))
    }

    /// Bootstraps a Nidus application from an explicit module graph and runs startup hooks.
    ///
    /// Typed providers are registered and async provider initializers run before
    /// startup hooks, so hooks can resolve fully initialized providers.
    pub async fn bootstrap_with_modules_and_lifecycle<M, I>(
        modules: I,
        lifecycle: LifecycleRunner,
    ) -> Result<Application>
    where
        M: Module,
        I: IntoIterator<Item = ModuleDefinition>,
    {
        let graph = ModuleGraph::from_root_and_modules::<M, I>(modules)?;
        let mut container = Container::new();
        register_module_providers(&mut container, &graph)?;
        initialize_module_providers(&mut container, &graph).await?;
        lifecycle.startup().await?;
        Ok(Application::with_lifecycle(container, graph, lifecycle))
    }
}

fn register_module_providers(container: &mut Container, graph: &ModuleGraph) -> Result<()> {
    for module in graph.modules() {
        for registrar in module.provider_registrars() {
            registrar(container)?;
        }
    }
    Ok(())
}

async fn initialize_module_providers(container: &mut Container, graph: &ModuleGraph) -> Result<()> {
    for module in graph.modules() {
        for initializer in module.async_initializers() {
            initializer(container).await?;
        }
    }
    Ok(())
}