sui_protocol/lib.rs
1//! sui-protocol — wire-type substrate for every IPC link in sui.
2//!
3//! ## Scope
4//!
5//! Today this crate ships the **local** protocol that the future
6//! sui-daemon will speak with same-host CLIs and atticd: rkyv 0.8 over
7//! a length-prefixed multiplex frame, over `tokio::net::UnixStream`.
8//! It deliberately stops short of a daemon implementation — the goal is
9//! to anchor the wire types so subsequent PRs (the daemon, the client
10//! library, the CLI integration) all build on a single typed seam.
11//!
12//! ## Roadmap (queued for follow-up PRs)
13//!
14//! | Link | Wire format | Framing | Transport |
15//! |---|---|---|---|
16//! | daemon ↔ same-host CLI | rkyv 0.8 (this crate, today) | length-prefixed multiplex | `tokio::net::UnixStream` |
17//! | daemon ↔ same-host atticd | rkyv 0.8 metadata + raw chunks | same multiplex | `UnixStream` (or shm ring later) |
18//! | daemon ↔ remote-daemon | protobuf, REAPI-shaped | gRPC | `tonic` over HTTPS (Tailscale identity) |
19//! | daemon ↔ remote-atticd | protobuf, tvix-castore-shaped | gRPC streaming | `tonic` over HTTPS |
20//! | fleet events | JSON/CBOR | NATS subjects | `async-nats` (existing) |
21//!
22//! Each new wire surface lands as a new `mod` here and shares the
23//! [`WireFrame`] envelope discipline: every connection starts with a
24//! magic-bytes + version-negotiation handshake, the server downgrades
25//! to `min(my_max, their_max)`, and we commit to an N-version compat
26//! window in writing. Nix's worker-protocol pain (per Tweag's
27//! "Re-implementing the Nix protocol in Rust" post-mortem) was the
28//! *absence* of a self-describing schema — sui won't repeat it.
29//!
30//! ## Behavior contract
31//!
32//! This crate ships **wire types and the version-negotiation
33//! primitives only**. No I/O, no daemon, no client connection logic.
34//! Subsequent crates depend on this for the wire surface and supply
35//! the I/O loop themselves. That separation means a future "fuzz the
36//! wire protocol" tool, or a future "drive the daemon from a
37//! WebAssembly client", or a future "swap UnixStream for tcp", all
38//! reuse the same types unchanged.
39
40#![warn(clippy::pedantic)]
41#![allow(clippy::module_name_repetitions)]
42
43pub mod local;
44pub mod version;
45
46pub use local::{
47 ErrorCode, Heartbeat, LocalError, LocalRequest, LocalResponse, RequestId, StatsSnapshot,
48 WireFrame, FRAME_MAGIC,
49};
50pub use version::{NegotiatedVersion, VersionHandshake, MAX_LOCAL_PROTOCOL_VERSION, MIN_LOCAL_PROTOCOL_VERSION};