noxu_rep/
lib.rs

1// Copyright (C) 2024-2025 Greg Burd.  Licensed under either of the
2// Apache License, Version 2.0 or the MIT license, at your option.
3// See LICENSE-APACHE and LICENSE-MIT at the root of this repository.
4// SPDX-License-Identifier: Apache-2.0 OR MIT
5
6#![allow(dead_code, clippy::type_complexity, clippy::too_many_arguments)]
7//! > **Internal component of the [`noxu`](https://crates.io/crates/noxu) database.**
8//! >
9//! > This crate is published only so the `noxu` umbrella crate can depend on it.
10//! > Use `noxu` (`noxu = "3"`) in applications; depend on this crate directly only
11//! > if you are extending the engine internals. Its API may change without a major
12//! > version bump.
13//!
14//! Replication and high availability for Noxu DB.
15//!
16//! master-replica replication with
17//! automatic elections, VLSN tracking, network restore, and subscription.
18//!
19//! # Architecture
20//!
21//! The replication layer consists of:
22//!
23//! - **ReplicatedEnvironment** -- Entry point that wraps a standard Environment
24//!   and adds replication capabilities.
25//!   Rep.ReplicatedEnvironment`.
26//! - **Elections** -- Automatic master election using majority voting.
27//!   Rep.elections`.
28//! - **VLSN Index** -- Maps version sequence numbers to log file positions.
29//! - **Feeder/Replica Stream** -- Master-to-replica log entry streaming. Port
30//! - **Network Transport** -- Pluggable channel-based communication.
31//!   Rep.net`.
32//! - **Group Service** -- Replication group membership management.
33//! - **Consistency Policies** -- Configurable replica consistency guarantees.
34//! - **Master Transfer** -- Controlled transfer of master role.
35//! - **Network Restore** -- Full node restore from another replica.
36//! - **Subscription** -- External subscription to the replication stream.
37//!
38//! # Node States
39//!
40//! A replication node transitions through the following states:
41//!
42//! - **Detached** -- Not associated with the group (handle closed).
43//! - **Unknown** -- Not in contact with the master, actively trying to
44//!   establish contact or decide upon a master.
45//! - **Master** -- The unique master of the group; can read and write.
46//! - **Replica** -- Being updated by the master; read-only.
47//!
48//! The state transitions visible to the application follow:
49//! ```text
50//! [ MASTER | REPLICA | UNKNOWN ]+ DETACHED
51//! ```
52//!
53//! # Example
54//!
55//! ```ignore
56//! use noxu_rep::{ReplicatedEnvironment, RepConfig, NodeType};
57//!
58//! let config = RepConfig::builder("my_group", "node1", "localhost")
59//!     .node_port(14_001)
60//!     .node_type(NodeType::Electable)
61//!     .build();
62//! let rep_env = ReplicatedEnvironment::new(config).unwrap();
63//! ```
64
65// Foundation modules
66pub mod auth;
67pub mod commit_durability;
68pub mod consistency;
69pub mod error;
70pub mod node_type;
71pub mod protocol;
72pub mod quorum_policy;
73pub mod rep_config;
74pub mod rep_group;
75pub mod rep_node;
76
77// Election subsystem
78pub mod elections;
79
80// VLSN tracking subsystem
81pub mod vlsn;
82
83// Replication stream subsystem
84pub mod stream;
85
86// Node state management
87pub mod node_state;
88
89// Group membership
90pub mod group_service;
91
92// Acknowledgment tracking
93pub mod ack_tracker;
94
95// Statistics
96pub mod rep_stats;
97
98// Master transfer
99pub mod group_admin;
100pub mod master_transfer;
101
102// Network transport
103pub mod net;
104
105// TLS configuration
106pub mod tls;
107
108// Subscription API
109pub mod subscription;
110
111// Network restore
112pub mod network_restore;
113pub mod network_restore_server;
114
115// Main API
116pub mod replicated_environment;
117pub mod state_change_listener;
118
119// In-memory `RepTestBase` / `RepEnvInfo` harness for porting JE rep
120// tests and for production in-process clusters.  Available under
121// `cfg(any(test, feature = "test-harness"))` and as a first-class
122// production module via [`net::InMemoryTransport`].  The
123// `test-harness` feature flag is retained as a no-op for backward
124// compatibility with downstream Cargo.toml entries.
125pub mod test_harness;
126
127// Re-export primary types
128#[cfg(any(feature = "tls-rustls", feature = "tls-native"))]
129pub use auth::PeerAllowlist;
130pub use commit_durability::{CommitDurability, ReplicaAckPolicy};
131pub use consistency::ConsistencyPolicy;
132pub use elections::phi_detector::PhiAccrualDetector;
133pub use error::{RepError, Result};
134pub use master_transfer::{
135    MasterTransfer, MasterTransferConfig, TransferState,
136};
137pub use net::{InMemoryEndpoint, InMemoryGroup, InMemoryTransport};
138#[cfg(feature = "quic")]
139pub use net::{
140    QuicChannel, QuicChannelListener, default_server_config,
141    insecure_client_config,
142};
143#[cfg(feature = "quic")]
144pub use net::{
145    QuicMultiplexedChannel, QuicMultiplexedChannelListener, ReconnectToken,
146    ReplicationChannel, mux_insecure_client_config, mux_server_config,
147};
148pub use network_restore::{NetworkRestore, NetworkRestoreConfig, RestoreState};
149pub use network_restore_server::{NetworkRestoreServer, RESTORE_SERVICE_NAME};
150pub use node_state::{NodeState, NodeStateMachine};
151pub use node_type::NodeType;
152pub use quorum_policy::QuorumPolicy;
153pub use rep_config::RepConfig;
154pub use rep_config::RepTransportKind;
155pub use rep_group::RepGroup;
156pub use rep_node::RepNode;
157pub use rep_stats::RepStats;
158pub use replicated_environment::ReplicatedEnvironment;
159pub use state_change_listener::{StateChangeEvent, StateChangeListener};
160pub use stream::reconnect::{
161    ReconnectConfig, ReconnectOutcome, catch_up_with_retry,
162};
163pub use subscription::{
164    Subscription, SubscriptionCallback, SubscriptionConfig, SubscriptionState,
165};
166pub use tls::{TlsConfig, TlsIdentity, TrustedCerts};
noxu_rep/lib.rs

noxu_rep/
lib.rs
