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

noxu_rep/
lib.rs
