nomad_protocol/lib.rs
1//! # NOMAD Protocol
2//!
3//! **N**etwork-**O**ptimized **M**obile **A**pplication **D**atagram
4//!
5//! NOMAD is a secure, UDP-based state synchronization protocol designed for
6//! real-time applications over unreliable networks. It provides:
7//!
8//! - **Security**: End-to-end authenticated encryption with forward secrecy
9//! - **Mobility**: Seamless operation across IP address changes (roaming)
10//! - **Latency**: Sub-100ms reconnection, optional client-side prediction
11//! - **Simplicity**: Fixed cryptographic suite, no negotiation
12//! - **Generality**: State-agnostic synchronization framework
13//!
14//! ## Feature Flags
15//!
16//! - `transport` (default): Transport layer (frames, RTT, pacing, sockets)
17//!
18//! ## Modules
19//!
20//! - [`core`]: Core traits, constants, and error types (always included)
21//! - [`transport`]: Transport layer (requires `transport` feature)
22//!
23//! ## Example Usage
24//!
25//! ```rust
26//! use nomad_protocol::prelude::*;
27//!
28//! // Define your state type
29//! #[derive(Clone)]
30//! struct MyState {
31//! counter: u64,
32//! }
33//!
34//! #[derive(Clone)]
35//! struct MyDiff {
36//! delta: i64,
37//! }
38//!
39//! impl SyncState for MyState {
40//! type Diff = MyDiff;
41//! const STATE_TYPE_ID: &'static str = "example.counter.v1";
42//!
43//! fn diff_from(&self, old: &Self) -> Self::Diff {
44//! MyDiff {
45//! delta: self.counter as i64 - old.counter as i64,
46//! }
47//! }
48//!
49//! fn apply_diff(&mut self, diff: &Self::Diff) -> Result<(), ApplyError> {
50//! self.counter = (self.counter as i64 + diff.delta) as u64;
51//! Ok(())
52//! }
53//!
54//! fn encode_diff(diff: &Self::Diff) -> Vec<u8> {
55//! diff.delta.to_le_bytes().to_vec()
56//! }
57//!
58//! fn decode_diff(data: &[u8]) -> Result<Self::Diff, DecodeError> {
59//! if data.len() < 8 {
60//! return Err(DecodeError::UnexpectedEof);
61//! }
62//! let delta = i64::from_le_bytes(data[..8].try_into().unwrap());
63//! Ok(MyDiff { delta })
64//! }
65//! }
66//! ```
67
68#![forbid(unsafe_code)]
69#![warn(missing_docs)]
70#![cfg_attr(docsrs, feature(doc_cfg))]
71
72// Core module (always included)
73pub mod core;
74
75// Transport layer (feature-gated)
76#[cfg(feature = "transport")]
77#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
78pub mod transport;
79
80// Placeholder modules (not yet implemented)
81mod crypto;
82mod sync;
83mod extensions;
84mod client;
85mod server;
86
87/// Prelude module for convenient imports.
88pub mod prelude {
89 // Core traits and types
90 pub use crate::core::*;
91
92 // Transport types (when enabled)
93 #[cfg(feature = "transport")]
94 pub use crate::transport::*;
95}
96
97// Re-export commonly used items at crate root
98pub use core::{ApplyError, DecodeError, NomadError, SyncState};
99
100#[cfg(feature = "transport")]
101pub use transport::{
102 ConnectionPhase, ConnectionState, DataFrame, DataFrameHeader, FrameFlags, FramePacer,
103 FrameType, NomadSocket, PayloadHeader, RttEstimator, SessionId,
104};