squib_net/
lib.rs

1//! squib-net — host-side networking for virtio-net.
2//!
3//! Per [30-networking.md](../../../specs/30-networking.md), squib offers four host-side
4//! attachment modes:
5//!
6//! | Mode | Backend | Entitlement |
7//! |------|---------|-------------|
8//! | [`VmnetMode::Shared`] (default) | `vmnet.framework` `VMNET_SHARED_MODE` (NAT) | none beyond `com.apple.security.hypervisor` |
9//! | [`VmnetMode::Host`] | `vmnet.framework` `VMNET_HOST_MODE` (host-only) | none beyond `com.apple.security.hypervisor` |
10//! | `VmnetMode::Bridged` (cargo feature) | `vmnet.framework` `VMNET_BRIDGED_MODE` | `com.apple.vm.networking` (restricted) — gated by the `bridged` cargo feature |
11//! | [`NetMode::Userspace`] | bundled `gvproxy` over a `socketpair(2)` carrying length-prefixed L2 frames | none |
12//!
13//! ## Layout
14//!
15//! - [`sys`] — the second of two `unsafe` boundaries in the workspace (the first is `squib-hv`).
16//!   Hand-rolled FFI to `vmnet.framework`, libdispatch, and XPC. Per [99-key-decisions.md §
17//!   D13](../../../specs/99-key-decisions.md#d13-vmnet-via-hand-rolled-ffi).
18//! - [`iface`] — safe `VmnetIface` wrapper.
19//! - [`backend`] — `NetBackend` impls feeding the virtio-net frontend.
20//! - [`gvproxy`] — gvproxy child-process management for `--network=userspace`.
21//!
22//! Outside the [`sys`] module, `#![forbid(unsafe_code)]` holds for the rest of the
23//! crate (I-NET-1). I-NET-4 (pre-allocated [`bytes::BytesMut`] pool, no per-packet
24//! `Vec<u8>` alloc in the hot path) lands with the Phase 7 perf-tuning sweep — see
25//! `specs/93-improvements-review.md` for the deferred backlog entry.
26
27#![warn(missing_docs)]
28// virtio-net descriptor lengths are u32; we cast to usize for slice indexing. Same
29// pattern as `squib-virtio` — wire shapes pin the widths.
30#![allow(
31    clippy::cast_possible_truncation,
32    clippy::cast_lossless,
33    clippy::cast_sign_loss,
34    clippy::similar_names,
35    // Module-name repetition (`vmnet::vmnet_*`) is the spec's naming, not noise.
36    clippy::module_name_repetitions
37)]
38
39pub mod backend;
40pub mod gvproxy;
41pub mod iface;
42pub mod mode;
43pub mod sys;
44
45pub use backend::{LoopbackHostBackend, NetHostBackend, VmnetHostBackend};
46pub use gvproxy::{GvproxyBackend, GvproxyError, GvproxyParams};
47pub use iface::{IfaceError, IfaceStats, InterfaceParams, VmnetIface};
48pub use mode::{NetMode, VmnetMode};
squib_net/lib.rs

squib_net/
lib.rs
