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

noxu_rep/
lib.rs
