net_sdk/
lib.rs

1//! # Net SDK
2//!
3//! Ergonomic Rust SDK for the Net mesh network.
4//!
5//! The core `net` crate is the engine. This SDK is what developers actually import.
6//!
7//! # Example
8//!
9//! ```rust,no_run
10//! use net_sdk::{Net, Backpressure};
11//! use futures::StreamExt;
12//!
13//! # async fn example() -> net_sdk::error::Result<()> {
14//! let node = Net::builder()
15//!     .shards(4)
16//!     .backpressure(Backpressure::DropOldest)
17//!     .memory()
18//!     .build()
19//!     .await?;
20//!
21//! // Emit events
22//! node.emit(&serde_json::json!({"token": "hello"}))?;
23//! node.emit_raw(b"{\"token\": \"world\"}" as &[u8])?;
24//!
25//! // Subscribe to a stream
26//! let mut stream = node.subscribe(Default::default());
27//! while let Some(event) = stream.next().await {
28//!     let event = event?;
29//!     println!("{}", event.raw_str().unwrap_or("<non-utf8>"));
30//! }
31//!
32//! node.shutdown().await?;
33//! # Ok(())
34//! # }
35//! ```
36
37/// Crate version, sourced from `Cargo.toml` at build time. Re-
38/// exported so downstream binaries (the `net` CLI in particular)
39/// can report the embedded SDK version without hardcoding a
40/// literal that silently drifts on every workspace bump.
41pub const VERSION: &str = env!("CARGO_PKG_VERSION");
42
43#[cfg(feature = "compute")]
44pub mod compute;
45pub mod config;
46#[cfg(feature = "cortex")]
47pub mod cortex;
48#[cfg(feature = "dataforts")]
49pub mod dataforts;
50#[cfg(feature = "deck")]
51pub mod deck;
52pub mod error;
53#[cfg(feature = "groups")]
54pub mod groups;
55#[cfg(feature = "net")]
56pub mod mesh;
57#[cfg(all(feature = "net", feature = "cortex"))]
58pub mod mesh_rpc;
59#[cfg(all(feature = "net", feature = "cortex"))]
60pub mod mesh_rpc_resilience;
61#[cfg(feature = "meshdb")]
62pub mod meshdb;
63#[cfg(feature = "meshos")]
64pub mod meshos;
65mod net;
66#[cfg(feature = "redis")]
67pub mod redis_dedup;
68pub mod stream;
69#[cfg(feature = "testing")]
70pub mod testing;
71
72#[cfg(feature = "redis")]
73pub use redis_dedup::RedisStreamDedup;
74
75// Security surface — identity (keypairs + tokens), capabilities
76// (declare + query), and subnets (visibility partitioning). All
77// three ride the `net` feature because they share a subprotocol
78// dispatch and operate as a single unit at runtime.
79#[cfg(feature = "net")]
80pub mod capabilities;
81#[cfg(feature = "net")]
82pub mod identity;
83#[cfg(feature = "net")]
84pub mod subnets;
85
86// Re-export the main handle.
87pub use crate::net::{Net, PollRequest, PollResponse, Receipt, Stats};
88
89// Re-export config types.
90pub use crate::config::{Backpressure, NetBuilder};
91
92// Re-export stream types.
93pub use crate::stream::{EventStream, SubscribeOpts, TypedEventStream};
94
95// Re-export core types that users will need.
96pub use ::net::config::{BatchConfig, ScalingPolicy};
97pub use ::net::consumer::Ordering;
98pub use ::net::event::{Event, RawEvent, StoredEvent};
99pub use ::net::Filter;
100
101// Feature-gated re-exports.
102#[cfg(feature = "redis")]
103pub use ::net::config::RedisAdapterConfig;
104
105#[cfg(feature = "jetstream")]
106pub use ::net::config::JetStreamAdapterConfig;
107
108#[cfg(feature = "net")]
109pub use ::net::adapter::net::NetAdapterConfig;
110
111#[cfg(feature = "net")]
112pub use ::net::adapter::net::{
113    CloseBehavior, Reliability, Stream as MeshStream, StreamConfig, StreamStats,
114};
115
116// Channel (distributed pub/sub) types. Ship alongside `net` because
117// they live on the mesh transport — subscribing / publishing require
118// a live `Mesh`.
119#[cfg(feature = "net")]
120pub use ::net::adapter::net::{
121    AckReason, ChannelConfig, ChannelId, ChannelName, OnFailure, PublishConfig, PublishReport,
122    Visibility,
123};
124
125#[cfg(feature = "net")]
126pub use crate::mesh::{Mesh, MeshBuilder, SubscribeOptions};
127
128// Compute surface — `MeshDaemon` trait + runtime. Gated by the
129// `compute` feature (which depends on `net`).
130#[cfg(feature = "compute")]
131pub use crate::compute::{
132    CausalEvent, CausalLink, DaemonError as ComputeDaemonError, DaemonHandle, DaemonHostConfig,
133    DaemonRuntime, DaemonStats, MeshDaemon, MigrationError, MigrationHandle, MigrationOpts,
134    MigrationPhase, StateSnapshot,
135};
136
137// Convenience re-exports for the common security types, so users can
138// `use net_sdk::{Identity, TokenScope};` without reaching for a
139// sub-module path.
140#[cfg(feature = "net")]
141pub use crate::capabilities::{CapabilityFilter, CapabilitySet};
142#[cfg(feature = "net")]
143pub use crate::identity::{Identity, PermissionToken, TokenError, TokenScope};
144#[cfg(feature = "net")]
145pub use crate::subnets::{SubnetId, SubnetPolicy};
146
147impl NetBuilder {
148    /// Build and start the node.
149    pub async fn build(self) -> error::Result<Net> {
150        Net::from_builder(self).await
151    }
152}
net_sdk/lib.rs

net_sdk/
lib.rs
