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 commit_durability;
67pub mod consistency;
68pub mod error;
69pub mod node_type;
70pub mod protocol;
71pub mod quorum_policy;
72pub mod rep_config;
73pub mod rep_group;
74pub mod rep_node;
75
76// Election subsystem
77pub mod elections;
78
79// VLSN tracking subsystem
80pub mod vlsn;
81
82// Replication stream subsystem
83pub mod stream;
84
85// Node state management
86pub mod node_state;
87
88// Group membership
89pub mod group_service;
90
91// Acknowledgment tracking
92pub mod ack_tracker;
93
94// Statistics
95pub mod rep_stats;
96
97// Master transfer
98pub mod group_admin;
99pub mod master_transfer;
100
101// Network transport
102pub mod net;
103
104// TLS configuration
105pub mod tls;
106
107// Subscription API
108pub mod subscription;
109
110// Network restore
111pub mod network_restore;
112pub mod network_restore_server;
113
114// Main API
115pub mod replicated_environment;
116pub mod state_change_listener;
117
118// In-memory `RepTestBase` / `RepEnvInfo` harness for porting JE rep
119// tests and for production in-process clusters.  Available under
120// `cfg(any(test, feature = "test-harness"))` and as a first-class
121// production module via [`net::InMemoryTransport`].  The
122// `test-harness` feature flag is retained as a no-op for backward
123// compatibility with downstream Cargo.toml entries.
124pub mod test_harness;
125
126// Re-export primary types
127pub use commit_durability::{CommitDurability, ReplicaAckPolicy};
128pub use consistency::ConsistencyPolicy;
129pub use elections::phi_detector::PhiAccrualDetector;
130pub use error::{RepError, Result};
131pub use master_transfer::{
132    MasterTransfer, MasterTransferConfig, TransferState,
133};
134pub use net::{InMemoryEndpoint, InMemoryGroup, InMemoryTransport};
135#[cfg(feature = "quic")]
136pub use net::{
137    QuicChannel, QuicChannelListener, default_server_config,
138    insecure_client_config,
139};
140#[cfg(feature = "quic")]
141pub use net::{
142    QuicMultiplexedChannel, QuicMultiplexedChannelListener, ReconnectToken,
143    ReplicationChannel, mux_insecure_client_config, mux_server_config,
144};
145pub use network_restore::{NetworkRestore, NetworkRestoreConfig, RestoreState};
146pub use network_restore_server::{NetworkRestoreServer, RESTORE_SERVICE_NAME};
147pub use node_state::{NodeState, NodeStateMachine};
148pub use node_type::NodeType;
149pub use quorum_policy::QuorumPolicy;
150pub use rep_config::RepConfig;
151pub use rep_config::RepTransportKind;
152pub use rep_group::RepGroup;
153pub use rep_node::RepNode;
154pub use rep_stats::RepStats;
155pub use replicated_environment::ReplicatedEnvironment;
156pub use state_change_listener::{StateChangeEvent, StateChangeListener};
157pub use stream::reconnect::{
158    ReconnectConfig, ReconnectOutcome, catch_up_with_retry,
159};
160pub use subscription::{
161    Subscription, SubscriptionCallback, SubscriptionConfig, SubscriptionState,
162};
163#[cfg(any(feature = "tls-rustls", feature = "tls-native"))]
164pub use tls::TlsConfig;
noxu_rep/lib.rs

noxu_rep/
lib.rs
