ranvier_core/
cluster.rs

1use async_trait::async_trait;
2use thiserror::Error;
3
4/// Error type for distributed cluster operations
5#[derive(Debug, Error)]
6pub enum ClusterError {
7    #[error("Failed to acquire lock: {0}")]
8    LockAcquisitionFailed(String),
9    #[error("Lock is already held by another node: {0}")]
10    LockHeld(String),
11    #[error("Failed to release lock: {0}")]
12    LockReleaseFailed(String),
13    #[error("Cluster bus error: {0}")]
14    BusError(String),
15    #[error("Connection error: {0}")]
16    ConnectionError(String),
17    #[error("Internal cluster error: {0}")]
18    Internal(String),
19}
20
21/// Interface for distributed locking mechanisms.
22/// Ensures that scheduled tasks or singleton operations run exactly once across the cluster.
23#[async_trait]
24pub trait DistributedLock: Send + Sync {
25    /// Attempts to acquire a distributed lock.
26    ///
27    /// # Arguments
28    /// * `key` - The unique identifier for the lock.
29    /// * `ttl_ms` - Time-to-live in milliseconds before the lock automatically expires.
30    ///
31    /// # Returns
32    /// * `Ok(true)` if the lock was successfully acquired.
33    /// * `Ok(false)` if the lock is currently held by another node.
34    /// * `Err` if a cluster or connection error occurred.
35    async fn try_acquire(&self, key: &str, ttl_ms: u64) -> Result<bool, ClusterError>;
36
37    /// Releases a previously acquired distributed lock.
38    ///
39    /// # Arguments
40    /// * `key` - The unique identifier for the lock.
41    async fn release(&self, key: &str) -> Result<(), ClusterError>;
42
43    /// Extends the expiration time of an actively held lock.
44    ///
45    /// # Arguments
46    /// * `key` - The unique identifier for the lock.
47    /// * `extra_ttl_ms` - Additional time-to-live to add to the lock.
48    async fn extend(&self, key: &str, extra_ttl_ms: u64) -> Result<(), ClusterError>;
49}
50
51/// Interface for distributed key-value storage.
52/// Supports basic get/put/delete operations with optional TTL.
53#[async_trait]
54pub trait DistributedStore: Send + Sync {
55    /// Retrieves a value by key.
56    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>, ClusterError>;
57
58    /// Stores a value with an optional TTL in milliseconds.
59    async fn put(&self, key: &str, value: &[u8], ttl_ms: Option<u64>) -> Result<(), ClusterError>;
60
61    /// Deletes a key from the store.
62    async fn delete(&self, key: &str) -> Result<(), ClusterError>;
63}
64
65/// Interface for a distributed message bus.
66/// Facilitates inter-node coordination, such as state synchronization or cluster-wide events.
67#[async_trait]
68pub trait ClusterBus: Send + Sync {
69    /// Publishes a message to a specific cluster topic.
70    async fn publish(&self, topic: &str, payload: &[u8]) -> Result<(), ClusterError>;
71
72    /// Subscribes to a specific cluster topic, returning a stream or receiver of messages.
73    /// The exact return type is abstracted or wrapped depending on implementation.
74    /// For this trait definition, we represent the registration of intent.
75    async fn subscribe(&self, topic: &str) -> Result<(), ClusterError>;
76}
ranvier_core/cluster.rs

ranvier_core/
cluster.rs
