Skip to main content

bombay_entity/
lib.rs

1//! Local, in-memory activation and stable routing for entities.
2//!
3//! An entity is addressed by a stable [`EntityId`], while its actor incarnation
4//! may be activated, drained, passivated, and later replaced. This crate owns
5//! that lifecycle. Actor execution, business behavior, persistence, discovery,
6//! and distributed consensus remain separate concerns.
7//!
8//! The runtime implements this state machine:
9//!
10//! ```text
11//! Inactive
12//!   -> Activating(generation)
13//!   -> Active(generation, actor reference)
14//!   -> Draining(generation)
15//!   -> Retiring(generation)
16//!   -> Inactive
17//! ```
18//!
19//! Generation checks prevent late activation or termination events from an old
20//! incarnation from changing the binding for a newer incarnation.
21
22#![deny(missing_docs)]
23
24use core::fmt;
25use core::hash::Hash;
26
27mod directory;
28mod lifecycle;
29#[cfg(feature = "protocol")]
30mod protocol;
31mod runtime;
32
33pub use bombay_transition::{Decision, Reducer};
34pub use directory::{
35    DirectoryConfig, DirectoryError, DirectoryOutput, DispatchOutput, EffectInterpreter,
36    LocalDirectory,
37};
38pub use lifecycle::{
39    ActivatingSlot, ActivationId, ActiveSlot, DispatchId, DrainFailure, DrainStage, DrainingSlot,
40    EntitySlot, LIFECYCLE_TOPOLOGY, LifecycleEdge, LifecycleMachine, LifecycleOutput,
41    LifecyclePhase, LifecycleTopologyError, LifecycleTrigger, Refusal, RetirementMode,
42    SlotDecision, SlotEffect, SlotEffectBatch, SlotEvent, SlotReducer, TransitionEvidence,
43    lifecycle_machine, validate_lifecycle_topology,
44};
45#[cfg(feature = "protocol")]
46pub use protocol::{DrainFenceAcknowledged, EntityBehavior, EntityEvent, EntityProtocol};
47pub use runtime::{
48    Activated, DispatchFailure, EntityRuntime, FenceFailure, LocalEntityRuntime, Passivation,
49};
50
51/// A stable, typed identifier for an entity.
52///
53/// The identifier names the logical entity rather than any particular actor
54/// incarnation. The inner value determines equality, ordering, and hashing.
55#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
56pub struct EntityId<T>(T);
57
58impl<T> EntityId<T> {
59    /// Wrap a domain identifier as an entity identifier.
60    pub const fn new(value: T) -> Self {
61        Self(value)
62    }
63
64    /// Borrow the domain identifier.
65    pub const fn get(&self) -> &T {
66        &self.0
67    }
68
69    /// Return the wrapped domain identifier.
70    pub fn into_inner(self) -> T {
71        self.0
72    }
73}
74
75impl<T: fmt::Debug> fmt::Debug for EntityId<T> {
76    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
77        formatter.debug_tuple("EntityId").field(&self.0).finish()
78    }
79}
80
81impl<T: fmt::Display> fmt::Display for EntityId<T> {
82    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
83        self.0.fmt(formatter)
84    }
85}
86
87#[cfg(test)]
88mod tests {
89    use super::EntityId;
90
91    #[test]
92    fn entity_id_preserves_domain_identity() {
93        let id = EntityId::new(42_u64);
94
95        assert_eq!(id.get(), &42);
96        assert_eq!(id.to_string(), "42");
97        assert_eq!(id.into_inner(), 42);
98    }
99}