oxedyne/fe2o3/fe2o3_o3db_sync/src/dist/mod.rs
3.0 KiB, 17 runs
created by r1870400018:11498, which is this file's identity for as long as the history lasts, whatever it is later renamed to
download · who wrote it · its history
| 1 | //! Distributed Ozone -- the peer-to-peer replicated mode of Hematite's Ozone |
| 2 | //! key/value database. |
| 3 | //! |
| 4 | //! Every peer runs a local Ozone (the rest of this crate); this module layers |
| 5 | //! *replication* on top. It composes the pure primitives from the |
| 6 | //! primitive modules into one cohesive engine behind a small application |
| 7 | //! API: |
| 8 | //! |
| 9 | //! - [`crate::kademlia`] -- peer identifiers and XOR distance. |
| 10 | //! - [`crate::oam`] -- threshold-XOR placement. |
| 11 | //! - [`oxedyne_fe2o3_data::hll`] -- network-size estimation. |
| 12 | //! - [`oxedyne_fe2o3_data::iblt`] -- state-reconciliation sketches. |
| 13 | //! - [`hotstuff`] -- Byzantine-fault-tolerant consensus (kept local to this |
| 14 | //! module because it is consumed nowhere else in the ecosystem today). |
| 15 | //! |
| 16 | //! # Architectural layering |
| 17 | //! |
| 18 | //! Distributed Ozone depends on transport (Shield) and storage (local Ozone) |
| 19 | //! through *traits*, not concrete types. The intent is that the two heavy |
| 20 | //! integrations -- Shield's UDP wire and this crate's local engine -- plug |
| 21 | //! in as adapters; a pure in-memory mock works just as well for tests and |
| 22 | //! two-node loopback demos. The traits are small on purpose: |
| 23 | //! [`transport::Transport`] sends and receives envelopes, [`storage::Storage`] |
| 24 | //! reads, writes and enumerates records. Neither carries policy. |
| 25 | //! |
| 26 | //! # What this module owns |
| 27 | //! |
| 28 | //! - [`config::DistOzoneConfig`] and the related table-configuration types |
| 29 | //! that shape distributed mode at start-up. |
| 30 | //! - [`peer_set::PeerSet`] -- the rolling view of known peers. Updated by |
| 31 | //! Kademlia lookups (not modelled here) and consulted on every placement |
| 32 | //! decision. |
| 33 | //! - [`placement::Placement`] -- the service that answers "who holds this |
| 34 | //! record?" by combining `OamConfig` with the current peer set. |
| 35 | //! - [`engine::DistOzone`] -- the top-level engine. Callers construct one |
| 36 | //! per process, hand it a [`transport::Transport`] and a |
| 37 | //! [`storage::Storage`], then invoke [`engine::DistOzone::put`] and |
| 38 | //! [`engine::DistOzone::get`]. |
| 39 | //! |
| 40 | //! # What this module does not own |
| 41 | //! |
| 42 | //! - Any transport implementation. Shield is an external adapter. |
| 43 | //! - Any on-disk storage. The rest of this crate is an external adapter. |
| 44 | //! - The reference peer application. That is downstream and consumes the |
| 45 | //! [`engine::DistOzone`] API for persistence across its identity, |
| 46 | //! escrow, name, revocation, peer-set, treasury and epoch tables. |
| 47 | //! |
| 48 | //! # Feature gate |
| 49 | //! |
| 50 | //! This module is compiled only when the crate is built with the `dist` |
| 51 | //! feature. Local-only callers pay no compile cost for the distributed |
| 52 | //! primitive graph. |
| 53 | //! |
| 54 | //! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\ |
| 55 | //! Anthropic Claude |
| 56 | |
| 57 | pub mod cohort; |
| 58 | pub mod config; |
| 59 | pub mod consensus; |
| 60 | pub mod engine; |
| 61 | pub mod hotstuff; |
| 62 | pub mod o3db_storage; |
| 63 | pub mod peer_set; |
| 64 | pub mod placement; |
| 65 | pub mod record; |
| 66 | pub mod storage; |
| 67 | pub mod transport; |
| 68 | |
| 69 | pub use self::{ |
| 70 | config::{ |
| 71 | Consistency, |
| 72 | DistOzoneConfig, |
| 73 | TableConfig, |
| 74 | }, |
| 75 | engine::DistOzone, |
| 76 | peer_set::PeerSet, |
| 77 | placement::Placement, |
| 78 | record::{ |
| 79 | Record, |
| 80 | RecordId, |
| 81 | }, |
| 82 | }; |