Skip to main content

nodedb_cluster/
lib.rs

1// SPDX-License-Identifier: BUSL-1.1
2
3//! Distributed coordination for NodeDB: vShards, Multi-Raft, QUIC transport,
4//! routing, replication, rebalancing, and the Calvin sequencer for cross-shard
5//! atomicity.
6//!
7//! This crate is consumed by the `nodedb` server binary and by
8//! NodeDB-internal tooling. Items marked `#[doc(hidden)]` are operational
9//! plumbing whose API shape is not yet stable for v0.1.0 — they remain `pub`
10//! so internal tools (`nodedb-cli`, `nodedb-studio`) and server crates can
11//! reach them, but external consumers should not depend on those modules
12//! directly. They will be promoted, redesigned, or moved behind curated
13//! facades in a later release.
14
15pub mod applied_watcher;
16pub mod array_routing;
17pub mod auth;
18pub mod bootstrap;
19#[doc(hidden)]
20pub mod bootstrap_listener;
21#[doc(hidden)]
22pub mod calvin;
23pub mod catalog;
24#[doc(hidden)]
25pub mod circuit_breaker;
26pub mod closed_timestamp;
27pub mod cluster_epoch;
28pub mod cluster_info;
29pub mod conf_change;
30pub mod cross_shard_txn;
31pub mod decommission;
32pub mod distributed_array;
33pub mod distributed_document;
34pub mod distributed_graph;
35pub mod distributed_join;
36pub mod distributed_spatial;
37pub mod distributed_timeseries;
38pub mod distributed_vector;
39pub mod error;
40pub mod follower_read;
41pub mod forward;
42#[doc(hidden)]
43pub mod ghost;
44#[doc(hidden)]
45pub mod ghost_sweeper;
46pub mod health;
47pub mod install_snapshot;
48pub mod lifecycle;
49pub mod lifecycle_state;
50pub mod loop_metrics;
51pub mod metadata_group;
52pub mod migration;
53#[doc(hidden)]
54pub mod migration_executor;
55pub mod mirror;
56pub mod multi_raft;
57pub mod quic_transport;
58pub mod raft_loop;
59pub mod raft_storage;
60pub mod rdma_transport;
61pub mod reachability;
62pub mod readiness;
63pub mod rebalance;
64pub mod rebalance_scheduler;
65pub mod rebalancer;
66pub mod routing;
67pub mod routing_liveness;
68pub mod rpc_codec;
69pub mod shard_split;
70pub mod subsystem;
71pub mod swim;
72pub mod sync_frame_versioned;
73pub mod topology;
74pub mod transport;
75pub mod vshard_handler;
76pub mod wire;
77pub mod wire_version;
78
79pub use applied_watcher::{AppliedIndexWatcher, GroupAppliedWatchers, WaitOutcome};
80pub use bootstrap::{
81    ClusterConfig, ClusterState, JoinRetryPolicy, start_cluster, start_cluster_subsystems,
82};
83#[doc(hidden)]
84pub use calvin::{EngineKeySet, EpochBatch, ReadWriteSet, SequencedTxn, SortedVec, TxClass};
85pub use catalog::ClusterCatalog;
86#[doc(hidden)]
87pub use circuit_breaker::BreakerSnapshot;
88pub use closed_timestamp::ClosedTimestampTracker;
89pub use cluster_epoch::{
90    bump_local_cluster_epoch, current_local_cluster_epoch, init_local_cluster_epoch_from_catalog,
91    observe_peer_cluster_epoch, set_local_cluster_epoch,
92};
93pub use cluster_info::{
94    ClusterInfoSnapshot, ClusterObserver, GroupSnapshot, GroupStatusProvider, PeerSnapshot,
95};
96pub use conf_change::{ConfChange, ConfChangeType};
97pub use decommission::{
98    DecommissionCoordinator, DecommissionObserver, DecommissionPlan, DecommissionRunResult,
99    DecommissionSafetyError, MetadataProposer, check_can_decommission, plan_full_decommission,
100};
101pub use error::{
102    CalvinError, ClusterError, MigrationCheckpointError, MigrationRecoveryError, Result,
103};
104pub use follower_read::{FollowerReadGate, ReadLevel};
105pub use forward::{ChunkSink, NoopPlanExecutor, PlanExecutor};
106pub use ghost::{GhostStub, GhostTable};
107pub use health::{HealthConfig, HealthMonitor};
108pub use lifecycle_state::{ClusterLifecycleState, ClusterLifecycleTracker};
109pub use loop_metrics::{LoopMetrics, LoopMetricsRegistry};
110pub use migration::{MigrationPhase, MigrationState};
111pub use migration_executor::{
112    MigrationExecutor, MigrationRequest, MigrationResult, MigrationSnapshot, MigrationTracker,
113};
114pub use multi_raft::{GroupStatus, MultiRaft};
115pub use raft_loop::{
116    AssignRemoteSurrogate, CalvinSubmit, CalvinSubmitInbox, CommitApplier, RaftLoop,
117    ReleaseReservation, ReserveRead, ShuffleAggregator, ShuffleConsumer, ShuffleProducer,
118    ShuffleReceiver, SnapshotApplier, SnapshotBuilder, SnapshotQuarantineHook,
119    VShardEnvelopeHandler,
120};
121pub use reachability::{
122    NoopProber, ReachabilityDriver, ReachabilityDriverConfig, ReachabilityProber, TransportProber,
123};
124pub use rebalance::{RebalancePlan, compute_plan, plan_to_requests};
125pub use rebalancer::{
126    AlwaysReadyGate, ElectionGate, LoadMetrics, LoadMetricsProvider, LoadWeights,
127    MigrationDispatcher, RebalancerKickHook, RebalancerLoop, RebalancerLoopConfig,
128    RebalancerPlanConfig, compute_load_based_plan, normalized_score,
129};
130pub use routing::RoutingTable;
131pub use routing_liveness::{NodeIdResolver, RoutingLivenessHook};
132pub use rpc_codec::{
133    AssignSurrogateRequest, AssignSurrogateResponse, JoinKeyPair, MacKey, PartNodeEntry, RaftRpc,
134    ReleaseReservationRequest, ReleaseReservationResponse, ReserveReadRequest, ReserveReadResponse,
135    ShuffleAggregateConsumeRequest, ShuffleAggregateConsumeResponse, ShuffleConsumeRequest,
136    ShuffleConsumeResponse, ShuffleProduceRequest, ShuffleProduceResponse, ShufflePushChunk,
137    ShufflePushEnd, ShufflePushRequest, SortKey, SubmitCalvinInboxRequest,
138    SubmitCalvinInboxResponse, SubmitCalvinTxnRequest, SubmitCalvinTxnResponse, TypedClusterError,
139};
140pub use topology::{ClusterTopology, NodeInfo, NodeState};
141pub use transport::{
142    IDENTITY_MISMATCH_QUIC_ERROR, NexarTransport, NoopIdentityStore, PeerIdentityStore,
143    PinnedClientVerifier, PinnedServerVerifier, RaftRpcHandler, ShufflePushStream, TlsCredentials,
144    TransportCredentials, TransportPeerSnapshot, VerifyMethod, VerifyOutcome, ca_fingerprint,
145    ca_fingerprint_hex, generate_node_credentials, generate_node_credentials_multi_san,
146    insecure_transport_count, issue_leaf_for_sans, load_crls_from_pem,
147    make_raft_client_config_mtls, make_raft_server_config_mtls, spki_pin_from_cert_der,
148};
149pub use wire::VShardEnvelope;
150
151pub use cross_shard_txn::{
152    EdgeValidationRequest, EdgeValidationResult, GsiAction, GsiForwardEntry,
153};
154pub use metadata_group::entry::JoinTokenTransitionKind;
155pub use metadata_group::{
156    CacheApplier, Compensation, DescriptorHeader, DescriptorId, DescriptorKind, DescriptorLease,
157    DescriptorState, METADATA_GROUP_ID, MetadataApplier, MetadataCache, MetadataEntry,
158    MigrationCheckpointPayload, MigrationId, MigrationPhaseTag, NoopMetadataApplier,
159    PersistedMigrationCheckpoint, RoutingChange, SharedMigrationStateTable, TopologyChange,
160    apply_migration_abort, apply_migration_checkpoint, decode_entry, encode_entry, new_shared,
161};
162pub use migration_executor::recover_in_flight_migrations;
163pub use quic_transport::{QuicTransport, QuicTransportConfig};
164
165pub use array_routing::{tile_id_of_coord, vshard_for_array_coord, vshard_for_array_tile};
166pub use distributed_join::{BroadcastJoinRequest, JoinStrategy, ShufflePartition, select_strategy};
167pub use lifecycle::{
168    DecommissionResult, handle_learner_promotion, handle_node_join, plan_decommission,
169};
170pub use rdma_transport::{RdmaConfig, RdmaTransport};
171pub use rebalance_scheduler::{NodeMetrics, RebalanceScheduler, RebalanceTrigger, SchedulerConfig};
172pub use shard_split::{SplitPlan, SplitStrategy, plan_graph_split, plan_vector_split};
173pub use subsystem::{
174    BootstrapCtx, BootstrapError, ClusterHealth, ClusterSubsystem, RunningCluster, ShutdownError,
175    SubsystemHandle, SubsystemHealth, SubsystemRegistry, TopoError, topo_sort,
176};
177pub use swim::bootstrap::spawn_with_subscribers as spawn_swim_with_subscribers;
178pub use swim::{
179    Incarnation, Member, MemberState, MembershipList, MembershipSubscriber, SwimConfig, SwimError,
180    SwimHandle, UdpTransport, spawn as spawn_swim,
181};
182
183pub use auth::{
184    AuditEvent, AuditWriter, AuthenticatedJoinBundle, BundleError, InMemoryTokenStore, JoinOutcome,
185    JoinTokenLifecycle, JoinTokenState, NoopAuditWriter, RaftBackedTokenStore,
186    SharedTokenStateMirror, TokenError, TokenStateBackend, TokenStateError, VecAuditWriter,
187    apply_token_transition_to_mirror, derive_mac_key, issue_token, open_bundle, seal_bundle,
188    spawn_inflight_timeout, token_hash, verify_token,
189};
190
191pub use wire_version::handshake_io::{
192    perform_version_handshake_client, perform_version_handshake_server,
193};
194pub use wire_version::{
195    VersionHandshake, VersionHandshakeAck, VersionRange, Versioned, WireVersion, WireVersionError,
196    WireVersionMetrics, decode_versioned, encode_versioned, local_version_range, negotiate,
197    unwrap_bytes_versioned, wrap_bytes_versioned,
198};