nomad-protocol 0.2.0

NOMAD Protocol - Network-Optimized Mobile Application Datagram. A secure UDP-based state synchronization protocol.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! # NOMAD Protocol
//!
//! **N**etwork-**O**ptimized **M**obile **A**pplication **D**atagram
//!
//! NOMAD is a secure, UDP-based state synchronization protocol designed for
//! real-time applications over unreliable networks. It provides:
//!
//! - **Security**: End-to-end authenticated encryption with forward secrecy
//! - **Mobility**: Seamless operation across IP address changes (roaming)
//! - **Latency**: Sub-100ms reconnection, optional client-side prediction
//! - **Simplicity**: Fixed cryptographic suite, no negotiation
//! - **Generality**: State-agnostic synchronization framework
//!
//! ## Feature Flags
//!
//! - `transport` (default): Transport layer (frames, RTT, pacing, sockets)
//! - `crypto` (default): Security layer (Noise_IK, XChaCha20-Poly1305)
//!
//! ## Modules
//!
//! - [`core`]: Core traits, constants, and error types (always included)
//! - [`transport`]: Transport layer (requires `transport` feature)
//! - [`crypto`]: Security layer (requires `crypto` feature)
//!
//! ## Example Usage
//!
//! ```rust
//! use nomad_protocol::prelude::*;
//!
//! // Define your state type
//! #[derive(Clone)]
//! struct MyState {
//!     counter: u64,
//! }
//!
//! #[derive(Clone)]
//! struct MyDiff {
//!     delta: i64,
//! }
//!
//! impl SyncState for MyState {
//!     type Diff = MyDiff;
//!     const STATE_TYPE_ID: &'static str = "example.counter.v1";
//!
//!     fn diff_from(&self, old: &Self) -> Self::Diff {
//!         MyDiff {
//!             delta: self.counter as i64 - old.counter as i64,
//!         }
//!     }
//!
//!     fn apply_diff(&mut self, diff: &Self::Diff) -> Result<(), ApplyError> {
//!         self.counter = (self.counter as i64 + diff.delta) as u64;
//!         Ok(())
//!     }
//!
//!     fn encode_diff(diff: &Self::Diff) -> Vec<u8> {
//!         diff.delta.to_le_bytes().to_vec()
//!     }
//!
//!     fn decode_diff(data: &[u8]) -> Result<Self::Diff, DecodeError> {
//!         if data.len() < 8 {
//!             return Err(DecodeError::UnexpectedEof);
//!         }
//!         let delta = i64::from_le_bytes(data[..8].try_into().unwrap());
//!         Ok(MyDiff { delta })
//!     }
//! }
//! ```

#![forbid(unsafe_code)]
#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

// Core module (always included)
pub mod core;

// Transport layer (feature-gated)
#[cfg(feature = "transport")]
#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
pub mod transport;

// Crypto layer (feature-gated)
#[cfg(feature = "crypto")]
#[cfg_attr(docsrs, doc(cfg(feature = "crypto")))]
pub mod crypto;

// Sync layer (feature-gated)
#[cfg(feature = "sync")]
#[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
pub mod sync;

// Extensions (feature-gated)
#[cfg(feature = "extensions")]
#[cfg_attr(docsrs, doc(cfg(feature = "extensions")))]
pub mod extensions;

// Client API (feature-gated)
#[cfg(feature = "client")]
#[cfg_attr(docsrs, doc(cfg(feature = "client")))]
pub mod client;

// Server API (feature-gated)
#[cfg(feature = "server")]
#[cfg_attr(docsrs, doc(cfg(feature = "server")))]
pub mod server;

/// Prelude module for convenient imports.
pub mod prelude {
    // Core traits and types
    pub use crate::core::*;

    // Transport types (when enabled) - exclude SessionId to avoid conflict with crypto
    #[cfg(feature = "transport")]
    pub use crate::transport::{
        ConnectionPhase, ConnectionState, DataFrame, DataFrameHeader, FrameFlags, FramePacer,
        FrameType, MigrationState, NomadSocket, NomadSocketBuilder, PacerAction,
        PayloadHeader, RetransmitController, RttEstimator, SendReason, TimestampTracker,
        TransportError, TransportResult,
    };

    // Crypto types (when enabled) - SessionId comes from here
    #[cfg(feature = "crypto")]
    pub use crate::crypto::*;
}

// Re-export commonly used items at crate root
pub use core::{ApplyError, DecodeError, NomadError, SyncState};

#[cfg(feature = "transport")]
pub use transport::{
    ConnectionPhase, ConnectionState, DataFrame, DataFrameHeader, FrameFlags, FramePacer,
    FrameType, NomadSocket, PayloadHeader, RttEstimator, SessionId,
};