nebucloud_xds/
lib.rs

1//! # nebucloud-xds
2//!
3//! Production-ready xDS control plane library for Rust.
4//!
5//! This crate provides a complete implementation of the xDS protocol
6//! for building Envoy control planes. It supports:
7//!
8//! - State-of-the-World (SotW) xDS protocol
9//! - Delta xDS protocol (incremental updates)
10//! - Aggregated Discovery Service (ADS)
11//! - Individual xDS services (CDS, LDS, RDS, EDS, SDS)
12//!
13//! ## Quick Start
14//!
15//! ```rust,no_run
16//! use nebucloud_xds::prelude::*;
17//! use std::sync::Arc;
18//!
19//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
20//! // Create a cache
21//! let cache = Arc::new(ShardedCache::new());
22//!
23//! // Build a snapshot for a node
24//! let snapshot = Snapshot::builder()
25//!     .version("v1")
26//!     .build();
27//!
28//! // Set snapshot
29//! cache.set_snapshot(NodeHash::from_id("node-1"), snapshot);
30//!
31//! // Create server
32//! let _server = XdsServer::builder()
33//!     .cache(cache)
34//!     .enable_sotw()
35//!     .build()?;
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! ## Architecture
41//!
42//! This library is organized into several crates:
43//!
44//! - `xds-core` - Core types, traits, and error handling
45//! - `xds-cache` - Snapshot cache with watch notifications
46//! - `xds-server` - gRPC server implementation
47//! - `xds-types` - Generated protobuf types
48//!
49//! This crate (`nebucloud-xds`) re-exports all public APIs for convenience.
50//!
51//! ## Design Principles
52//!
53//! 1. **No panics in library code** - All errors are returned as `Result`
54//! 2. **No locks held across await points** - Uses DashMap and careful design
55//! 3. **Type-safe resources** - Generic `Resource` trait with registry
56//! 4. **Observable** - Built-in metrics and tracing support
57//!
58//! ## Features
59//!
60//! - `full` - Enable all features (default)
61//! - `sotw` - State-of-the-World protocol
62//! - `delta` - Delta xDS protocol
63//! - `compression` - Response compression
64
65#![cfg_attr(docsrs, feature(doc_cfg))]
66#![deny(unsafe_code)]
67#![warn(missing_docs)]
68// Tests are allowed to use .unwrap() / .expect() / panic! freely; the
69// production-only warnings still apply.
70#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
71
72// Re-export all sub-crates
73pub use xds_cache as cache;
74pub use xds_core as core;
75pub use xds_server as server;
76pub use xds_types as types;
77
78/// Prelude module for convenient imports.
79///
80/// ```rust
81/// use nebucloud_xds::prelude::*;
82/// ```
83pub mod prelude {
84    // Core types
85    pub use xds_core::{
86        BoxResource, NodeHash, Resource, ResourceRegistry, ResourceTypeInfo, ResourceVersion,
87        SharedResourceRegistry, TypeUrl, XdsError, XdsResult,
88    };
89
90    // Cache types
91    pub use xds_cache::{
92        Cache, CacheStats, ShardedCache, Snapshot, SnapshotBuilder, Watch, WatchId,
93    };
94
95    // Server types
96    pub use xds_server::{ServerConfig, StreamContext, StreamId, XdsServer, XdsServerBuilder};
97
98    // TLS re-exports (only when the `tls` feature is enabled)
99    #[cfg(feature = "tls")]
100    #[cfg_attr(docsrs, doc(cfg(feature = "tls")))]
101    pub use xds_server::{ServerTlsConfig, TlsIdentity};
102}
103
104/// Version information for this crate.
105pub mod version {
106    /// Crate version.
107    pub const VERSION: &str = env!("CARGO_PKG_VERSION");
108
109    /// Minimum supported Rust version.
110    pub const MSRV: &str = "1.75";
111
112    /// Get version info as a string.
113    pub fn version_string() -> String {
114        format!("nebucloud-xds {} (MSRV {})", VERSION, MSRV)
115    }
116}
117
118#[cfg(test)]
119mod tests {
120    use super::prelude::*;
121    use std::sync::Arc;
122
123    #[test]
124    fn prelude_imports_work() {
125        let cache = ShardedCache::new();
126        let node = NodeHash::from_id("test-node");
127
128        let snapshot = Snapshot::builder().version("v1").build();
129
130        cache.set_snapshot(node, snapshot);
131
132        let retrieved = cache.get_snapshot(node).unwrap();
133        assert_eq!(retrieved.version(), "v1");
134    }
135
136    #[test]
137    fn server_builder_works() {
138        let cache = Arc::new(ShardedCache::new());
139
140        let result = XdsServer::builder()
141            .cache(cache)
142            .enable_sotw()
143            .enable_delta()
144            .build();
145
146        assert!(result.is_ok());
147    }
148
149    #[test]
150    fn version_info() {
151        let version = super::version::version_string();
152        assert!(version.contains("nebucloud-xds"));
153    }
154}
nebucloud_xds/lib.rs

nebucloud_xds/
lib.rs
