photon_etcd_cluster/
lib.rs

1//! # photon-etcd-cluster
2//!
3//! A lightweight cluster coordination library providing leader election
4//! and node registry via etcd.
5//!
6//! ## Main Components
7//!
8//! - [`ClusterNode`]: Joins cluster, participates in elections
9//! - [`ServiceDiscovery`]: Watches cluster state with reactive event streams
10//! - [`ClusterEvent`]: Events emitted on cluster changes
11//! - [`Node`]: Node metadata (id, ip, last_seen)
12//!
13//! ## Usage Patterns
14//!
15//! ### Event-driven (recommended)
16//!
17//! React to cluster changes as they happen:
18//!
19//! ```ignore
20//! use photon_etcd_cluster::{ServiceDiscovery, ClusterEvent};
21//!
22//! let discovery = ServiceDiscovery::new(endpoints, "my-service".into());
23//! tokio::spawn(async move { discovery.run(None).await });
24//!
25//! let mut events = discovery.subscribe();
26//! while let Ok(event) = events.recv().await {
27//!     match event {
28//!         ClusterEvent::NodeJoined(n) => update_backends(),
29//!         ClusterEvent::LeaderElected(n) => route_writes_to(n),
30//!         _ => {}
31//!     }
32//! }
33//! ```
34//!
35//! ### Watch-based (for metrics/state observation)
36//!
37//! Efficiently observe state changes without polling:
38//!
39//! ```ignore
40//! let mut watch = discovery.watch_nodes();
41//! loop {
42//!     watch.changed().await?;
43//!     BACKEND_COUNT.set(watch.borrow().len() as i64);
44//! }
45//! ```
46//!
47//! ### Direct access (for one-off queries)
48//!
49//! ```ignore
50//! let nodes = discovery.nodes();
51//! let leader = discovery.leader();
52//! ```
53//!
54//! ## ClusterNode Example
55//!
56//! ```ignore
57//! use photon_etcd_cluster::ClusterNode;
58//! use tokio::sync::broadcast;
59//!
60//! let node = ClusterNode::new(
61//!     vec!["http://localhost:2379".into()],
62//!     "node-1".into(),
63//!     "127.0.0.1".parse().unwrap(),
64//!     "my-service".into(),
65//!     Some(5),
66//! );
67//!
68//! let (shutdown_tx, _) = broadcast::channel(1);
69//! let mut rx = shutdown_tx.subscribe();
70//! node.run(&mut rx).await?;
71//!
72//! if node.is_leader() {
73//!     // Perform leader-only tasks
74//! }
75//! ```
76
77pub(crate) mod connection;
78pub mod cluster_node;
79pub mod discovery;
80pub mod error;
81pub mod event;
82pub mod metrics;
83pub mod types;
84
85// Re-exports for convenience
86pub use cluster_node::{ClusterNode, ClusterNodeBuilder};
87pub use discovery::ServiceDiscovery;
88pub use error::ClusterError;
89pub use event::ClusterEvent;
90pub use metrics::{MetricsCollector, NoopMetricsCollector};
91#[cfg(feature = "system-metrics")]
92pub use metrics::SystemMetricsCollector;
93pub use types::{metadata_keys, HealthStatus, Node, NodeMetadata};
photon_etcd_cluster/lib.rs

photon_etcd_cluster/
lib.rs
