grafos_net/lib.rs
1//! grafos-net — Network-aware programming primitives for grafOS.
2//!
3//! This crate provides higher-level networking abstractions built on top of
4//! `grafos-std`'s [`grafos_std::net::NetLease`] and [`grafos_std::net::NetBuilder`]. Programs acquire leased
5//! network interfaces with bandwidth guarantees, then use familiar socket
6//! and listener APIs for communication.
7//!
8//! # Architecture
9//!
10//! ```text
11//! +-------------------------------+
12//! | Your program |
13//! | FabricSocket / FabricDns |
14//! +-------------------------------+
15//! | grafos-net |
16//! | socket | listener | dns |
17//! +-------------------------------+
18//! | grafos-std::net |
19//! | NetBuilder → NetLease |
20//! +-------------------------------+
21//! | Host: macvlan / SR-IOV / tc |
22//! +-------------------------------+
23//! ```
24//!
25//! `grafos-std::net` handles lease acquisition (requesting a NIC with a
26//! bandwidth guarantee from the host). `grafos-net` builds familiar
27//! socket and DNS APIs on top of those leases.
28//!
29//! # Types
30//!
31//! | Type | Purpose |
32//! |------|---------|
33//! | [`FabricSocket`] | UDP socket bound to a leased NIC with bandwidth guarantee |
34//! | [`FabricListener`] | TCP listener bound to a leased NIC |
35//! | [`FabricDns`] | In-memory name→address resolver with TTL cache |
36//!
37//! # Quick start
38//!
39//! ```rust
40//! use grafos_net::FabricSocket;
41//! use grafos_std::net::NetBuilder;
42//!
43//! # grafos_std::host::reset_mock();
44//! # grafos_std::host::mock_set_net_interface("eth-fab0", 1_000_000_000);
45//! let lease = NetBuilder::new().min_bandwidth(1_000_000_000).acquire()?;
46//! let sock = FabricSocket::new(lease)?;
47//! assert_eq!(sock.bandwidth(), 1_000_000_000);
48//! # Ok::<(), Box<dyn std::error::Error>>(())
49//! ```
50
51mod dns;
52mod listener;
53mod socket;
54
55pub use dns::FabricDns;
56pub use listener::FabricListener;
57pub use socket::FabricSocket;