xds_cache/lib.rs
1//! # xds-cache
2//!
3//! High-performance snapshot cache for xDS resources.
4//!
5//! This crate provides the caching layer for xDS control plane implementations:
6//!
7//! - [`ShardedCache`] - DashMap-based concurrent cache for snapshots
8//! - [`Snapshot`] - Immutable collection of resources for a node
9//! - [`Watch`] - Subscription system for cache updates
10//!
11//! ## Key Design Decisions
12//!
13//! - Uses `DashMap` for lock-free concurrent access
14//! - All `DashMap` references are dropped before any `.await` to prevent deadlocks
15//! - Snapshots are immutable and atomically replaced
16//! - Watch notifications are async and non-blocking
17//!
18//! ## Example
19//!
20//! ```rust
21//! use xds_cache::{Cache, ShardedCache, Snapshot};
22//! use xds_core::NodeHash;
23//!
24//! // Create a cache
25//! let cache = ShardedCache::new();
26//!
27//! // Build a snapshot
28//! let snapshot = Snapshot::builder()
29//! .version("v1")
30//! .build();
31//!
32//! // Set snapshot for a node (sync; watch notifications are async internally)
33//! cache.set_snapshot(NodeHash::from_id("node-1"), snapshot);
34//! ```
35
36#![cfg_attr(docsrs, feature(doc_cfg))]
37#![deny(unsafe_code)]
38#![warn(missing_docs)]
39// Tests are allowed to use .unwrap() / .expect() / panic! freely; the
40// production-only warnings still apply.
41#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
42
43mod cache;
44mod snapshot;
45mod stats;
46mod watch;
47
48pub use cache::{Cache, ShardedCache};
49pub use snapshot::{Snapshot, SnapshotBuilder, SnapshotResources};
50pub use stats::CacheStats;
51pub use watch::{Watch, WatchId, WatchManager};