Skip to main content

delta_stream/
lib.rs

1//! DeltaStream is a state-aware synchronization library for realtime Rust applications.
2//!
3//! It sends an initial snapshot and then compact state deltas when doing so is cheaper,
4//! while validating sequence/base-state relationships on the receiver. When the chain
5//! breaks, the receiver reports that recovery is required instead of applying an unsafe
6//! delta.
7//!
8//! # Quick start
9//!
10//! ```
11//! use delta_stream::{DeltaState, Publisher, Subscriber};
12//! use serde::{Deserialize, Serialize};
13//!
14//! #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, DeltaState)]
15//! struct GameState {
16//!     x: i32,
17//!     hp: u16,
18//! }
19//!
20//! # fn main() -> Result<(), delta_stream::DeltaError> {
21//! let mut publisher = Publisher::<GameState>::new();
22//! let mut subscriber = Subscriber::<GameState>::new();
23//!
24//! let bytes = publisher.encode(&GameState { x: 10, hp: 100 })?;
25//! subscriber.receive(&bytes)?;
26//!
27//! assert_eq!(subscriber.state().map(|state| state.hp), Some(100));
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! # Synchronization flow
33//!
34//! ```text
35//! Application state
36//!     -> Publisher
37//!     -> snapshot or delta packet
38//!     -> serialized bytes
39//!     -> any byte-capable transport
40//!     -> received bytes
41//!     -> Subscriber
42//!     -> validated synchronized state
43//! ```
44//!
45//! # Transport model
46//!
47//! DeltaStream produces and consumes [`Packet`] values. A transport is responsible for
48//! moving the serialized packet bytes between peers. Optional adapters are available for
49//! PubNub, WebSocket, MQTT, and NATS behind Cargo features.
50
51extern crate self as delta_stream;
52
53pub mod api;
54#[cfg(feature = "crdt")]
55pub mod crdt;
56pub mod error;
57pub mod packet;
58pub mod partial_repair;
59pub mod recovery_history;
60pub mod reorder;
61pub mod runtime;
62pub mod schema;
63#[cfg(feature = "async-runtime")]
64pub mod session;
65#[cfg(feature = "async-runtime")]
66pub mod transport;
67
68// Compatibility and advanced building blocks remain public in v0.30.0 so existing users
69// are not broken, but they are hidden from the primary rustdoc surface.
70#[doc(hidden)]
71pub mod adaptive;
72#[doc(hidden)]
73pub mod app;
74#[doc(hidden)]
75pub mod binary;
76#[doc(hidden)]
77pub mod byte_sync;
78#[doc(hidden)]
79pub mod chaos;
80#[doc(hidden)]
81pub mod compat;
82#[doc(hidden)]
83pub mod control;
84#[doc(hidden)]
85pub mod demo_server;
86#[doc(hidden)]
87pub mod edge_cases;
88#[doc(hidden)]
89pub mod fast_selector;
90#[doc(hidden)]
91pub mod metrics;
92#[doc(hidden)]
93pub mod migration;
94#[doc(hidden)]
95pub mod multi_client;
96#[doc(hidden)]
97pub mod recovery_v30;
98#[doc(hidden)]
99pub mod replay;
100#[doc(hidden)]
101pub mod smart_delta;
102#[doc(hidden)]
103pub mod state;
104#[doc(hidden)]
105pub mod sync;
106#[doc(hidden)]
107pub mod torture;
108#[doc(hidden)]
109pub mod v25_bench;
110#[doc(hidden)]
111pub mod v25_validation;
112#[doc(hidden)]
113pub mod v30_bench;
114#[doc(hidden)]
115pub mod v30_sync;
116#[doc(hidden)]
117pub mod v30_torture;
118#[doc(hidden)]
119pub mod v30_validation;
120#[doc(hidden)]
121pub mod validation;
122#[cfg(feature = "websocket-transport")]
123#[doc(hidden)]
124pub mod ws_broker;
125
126pub use api::{Publisher, PublisherBuilder, StatePublisher, StateSubscriber, Subscriber};
127pub use error::DeltaError;
128pub use packet::{
129    DecodeConfig, Packet, PacketKind, MAX_LOGICAL_PAYLOAD, MAX_WIRE_PAYLOAD, WIRE_VERSION,
130};
131pub use partial_repair::{ChunkManifest, ChunkPatch, PartialRepair};
132pub use runtime::{backpressure_decision, BackpressureDecision, RuntimeLimits, RuntimeMetrics};
133pub use schema::DeltaState;
134pub use sync::GenericApplyResult as Apply;
135
136#[cfg(feature = "derive")]
137pub use delta_stream_derive::DeltaState;
138
139/// Common imports for application code.
140pub mod prelude {
141    pub use crate::{Apply, DeltaError, DeltaState, Packet, PacketKind, Publisher, Subscriber};
142}
143
144/// Lower-level protocol and tuning types for advanced integrations.
145pub mod advanced {
146    pub use crate::adaptive::{AdaptivePolicy, EncodeDecision, EncodeMode};
147    pub use crate::byte_sync::{
148        ByteApplyResult, ByteEncodeDecision, ByteEncodeMode, ByteStateDecoder, ByteStateEncoder,
149        V25Policy,
150    };
151    pub use crate::compat::Capabilities;
152    pub use crate::fast_selector::{ChangeProfile, SelectorPolicy, StrategyAdvisor};
153    pub use crate::migration::MigrationRegistry;
154    pub use crate::recovery_history::{RecoveryHistory, RecoveryPlan};
155    pub use crate::recovery_v30::{plan_recovery, V30RecoveryPlan};
156    pub use crate::reorder::{ReorderApplyResult, ReorderDecoder};
157    pub use crate::smart_delta::{AdaptiveTuner, SmartDeltaKind, SmartDeltaPolicy};
158    pub use crate::state::AgentState;
159    pub use crate::sync::{
160        ApplyResult, Decoder, Encoder, GenericApplyResult, GenericDecoder, GenericEncoder,
161    };
162    pub use crate::v30_sync::{FastByteStateEncoder, V30Decision, V30EncodeMode, V30Policy};
163}
164
165// Backward-compatible root re-exports retained for v0.30.0.
166#[doc(hidden)]
167pub use adaptive::{AdaptivePolicy, EncodeDecision, EncodeMode};
168#[doc(hidden)]
169pub use byte_sync::{
170    ByteApplyResult, ByteEncodeDecision, ByteEncodeMode, ByteStateDecoder, ByteStateEncoder,
171    V25Policy,
172};
173#[doc(hidden)]
174pub use compat::Capabilities;
175#[doc(hidden)]
176pub use fast_selector::{ChangeProfile, SelectorPolicy, StrategyAdvisor};
177#[doc(hidden)]
178pub use migration::MigrationRegistry;
179#[doc(hidden)]
180pub use multi_client::MultiClientReport;
181#[doc(hidden)]
182pub use recovery_history::{RecoveryHistory, RecoveryPlan};
183#[doc(hidden)]
184pub use recovery_v30::{plan_recovery, V30RecoveryPlan};
185#[doc(hidden)]
186pub use smart_delta::{AdaptiveTuner, SmartDeltaKind, SmartDeltaPolicy};
187#[doc(hidden)]
188pub use state::AgentState;
189#[doc(hidden)]
190pub use sync::{ApplyResult, Decoder, Encoder, GenericApplyResult, GenericDecoder, GenericEncoder};
191#[doc(hidden)]
192pub use torture::TortureReport;
193#[doc(hidden)]
194pub use v30_sync::{FastByteStateEncoder, V30Decision, V30EncodeMode, V30Policy};
195#[doc(hidden)]
196pub use v30_torture::V30TortureReport;
197
198/// Runs the bundled CLI/demo application.
199#[doc(hidden)]
200pub use app::run;