docs/generated/contracts.mdgenerated from code
Reference · 11 min read
transport
Contracts: transport.
Read as
Source: crates/lvcs-net/src/transport/mod.rs.
1/// A node device as the net actors name it (discussion:owner/107).2///3/// It is its Ed25519 public key, from which its libp2p `PeerId` derives.4/// Every LVCS device key is Ed25519, so the transport refuses a connection5/// whose identity is another key type (chosen at the M3 freeze: a6/// fixed-size, journaled form, where a `PeerId` would need libp2p's serde7/// feature). Journaled as a byte string. Owner: `M3.transport`.8#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]9pub struct Node(#[serde(with = "crate::wire::cbor::fixed")] pub [u8; 32]);1011/// How the transport found a node (discussion:owner/13).12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]13pub enum Discovery {14 /// mDNS on the local network.15 Mdns,16 /// The Kademlia DHT.17 Kademlia,18 /// A `--bootstrap` address.19 Bootstrap,20}2122/// What `AutoNAT` concluded about this device's reachability (discussion:owner/400):23/// a `Private` device is reached through a circuit relay v2 reservation,24/// upgraded by `DCUtR` when hole punching succeeds.25#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]26pub enum NatStatus {27 /// Not concluded yet.28 Unknown,29 /// Publicly reachable.30 Public,31 /// Not publicly reachable.32 Private,33}3435/// How the transport runs, from `lvcs daemon`'s flags (discussion:owner/107).36///37/// It holds the multiaddrs to listen on (`--listen`) and to dial at start38/// (`--bootstrap`), the wire major it speaks, and seed mode (`--seed`): the same binary with no39/// special authority, which pins every document it learns of, serves as a40/// circuit relay v2 server, and is a bootstrap address for others. Owner:41/// `M3.transport`; the daemon (`M3.daemon`) builds it.42#[derive(Debug, Clone, PartialEq, Eq)]43pub struct TransportConfig {44 /// The multiaddrs to listen on (`--listen`).45 pub listen: Vec<String>,46 /// The multiaddrs to dial at start (`--bootstrap`).47 pub bootstrap: Vec<String>,48 /// Seed mode (`--seed`).49 pub seed: bool,50 /// Whether the swarm runs mDNS (off with `--no-mdns`, discussion:owner/307),51 /// which `build_swarm` composes.52 pub mdns: bool,53 /// The project id (`ID_ENCODING`), which names the sync protocol, so a54 /// node of another project is never synced with (discussion:owner/320).55 pub project: String,56 /// The wire major version this daemon speaks (production-readiness57 /// U4): `WIRE_MAJOR`, except where a debug build's58 /// `WIRE_MAJOR_TEST_ENV` sets another. It names the sync protocol id59 /// and is advertised in identify; a node that advertises another, or60 /// lists no sync protocol of this one, is incompatible.61 pub wire: u16,62 /// The public relays (discussion:owner/639) this swarm probes through63 /// and reserves on, each ending in `/p2p/<relay>`; empty for none.64 pub relays: Vec<String>,65 /// Whether this swarm listens on `/webrtc` and falls back to tracker-signaled66 /// WebRTC ICE when direct dials fail (discussion:owner/828).67 pub tracker_ice: bool,68}6970impl Default for TransportConfig {71 /// No listen or bootstrap address, no seed mode, mDNS on, no project,72 /// `WIRE_MAJOR`, no relays, and tracker ICE off.73 fn default() -> Self {74 Self {75 listen: Vec::new(),76 bootstrap: Vec::new(),77 seed: false,78 mdns: true,79 project: String::new(),80 wire: lvcs_vocab::ids::WIRE_MAJOR,81 relays: Vec::new(),82 tracker_ice: false,83 }84 }85}8687/// What the swarm reports (discussion:owner/261), in the order it saw it.88///89/// The daemon shell turns each into the events of the actors that need it:90/// nodes and the sync stream go to the sync actor (`SyncingEvents`), gossip91/// messages to the gossip actor (`GossipingEvents`). Addresses are multiaddrs92/// in text form. Owner: `M3.transport`.93#[derive(Debug, Clone, PartialEq, Eq)]94pub enum TransportEvent {95 /// The swarm is reachable at `addr` (discussion:owner/639): it listens96 /// there, through a relay's circuit (`/p2p-circuit`) among them, or97 /// `AutoNAT` confirmed it as an external address.98 Listening {99 /// The address.100 addr: String,101 },102 /// The swarm is no longer reachable at `addr`: it stopped listening103 /// there, or the external address expired.104 Unlistening {105 /// The address.106 addr: String,107 },108 /// One connection to `node` came up (`up`) or closed, through a relay's109 /// circuit (`relayed`) or not: what `node.list`'s link says110 /// (discussion:owner/400 and discussion:owner/639).111 Linked {112 /// The node.113 node: Node,114 /// Whether the connection goes through a relay.115 relayed: bool,116 /// Whether it came up, else closed.117 up: bool,118 },119 /// A connection to `node` is up (the first one, if there are several).120 Connected {121 /// The connected node.122 node: Node,123 },124 /// The swarm panicked and the transport restarted with a fresh one125 /// (discussion:owner/676): every connection, stream, and listen address the126 /// old swarm held is gone, unreported one by one. `panics` counts the127 /// panics within `TRANSPORT_PANIC_WINDOW_MS`, this one included.128 Restarted {129 /// The panics so far within the window.130 panics: u32,131 },132 /// The last connection to `node` closed.133 Gone {134 /// The node whose last connection closed.135 node: Node,136 },137 /// `node` was discovered at `addrs` through `via`.138 Discovered {139 /// The discovered node.140 node: Node,141 /// Its addresses.142 addrs: Vec<String>,143 /// How it was found.144 via: Discovery,145 },146 /// Every bootstrap address failed its dials and no node has connected147 /// (launch-qa/8).148 Unanswered {149 /// The bootstrap addresses, each with its node id.150 addrs: Vec<String>,151 },152 /// A listen address's port is taken; the transport listens on one the153 /// system picked and retries it (discussion:owner/683).154 PortWaiting {155 /// The address it wants.156 addr: String,157 },158 /// A listen address that waited is bound now.159 PortBound {160 /// The address.161 addr: String,162 },163 /// `AutoNAT`'s conclusion changed.164 Nat(NatStatus),165 /// The one sync stream with `node` is open (discussion:owner/68): whichever166 /// side's device key bytes are smaller opens it, and the transport167 /// closes a second one, so each node pair has exactly one.168 SyncOpened {169 /// The node the stream is with.170 node: Node,171 },172 /// One length-delimited frame read from the sync stream: an encoded173 /// envelope of kind `sync`, at most `WIRE_MAX_BYTES` (a longer frame174 /// closes the stream and is reported as [`TransportEvent::SyncClosed`]).175 SyncFrame {176 /// The node the stream is with.177 node: Node,178 /// The frame's bytes.179 frame: Vec<u8>,180 },181 /// The sync stream with `node` closed.182 SyncClosed {183 /// The node the stream was with.184 node: Node,185 },186 /// The sync stream with `node` has `room` bytes in its write queue, at187 /// least what was asked, after [`TransportCommand::AwaitRoom`]188 /// (session-29a3231b/2).189 SyncRoom {190 /// The node the stream is with.191 node: Node,192 /// The bytes its queue has room for.193 room: u64,194 },195 /// A gossipsub message waiting for validation (discussion:owner/111).196 ///197 /// `id` is gossipsub's message id, `propagation` the node that198 /// forwarded it (whose score a repeat offense lowers), and `data`199 /// the encoded envelope, which its peer signed. Gossipsub200 /// forwards it only after [`TransportCommand::Validate`] accepts it.201 /// The publishing device is not reported: nothing downstream needs it,202 /// since the envelope names its signer and the yield order reads only203 /// the payload (chosen at the M3 freeze).204 Gossip {205 /// Gossipsub's message id.206 id: Vec<u8>,207 /// The node that forwarded it.208 propagation: Node,209 /// The topic it came on.210 topic: String,211 /// The encoded envelope.212 data: Vec<u8>,213 },214 /// A compatible `node` identified with `agent`, its first identify on215 /// a connection or one naming another build than the last; [`Advertised::parse`]216 /// reads its release. Its last connection's [`TransportEvent::Gone`]217 /// ends it.218 Identified {219 /// The node.220 node: Node,221 /// Its identify agent version, printable ASCII, at most222 /// `AGENT_MAX_BYTES`.223 agent: String,224 },225 /// `node` runs a release this daemon can't sync with226 /// (production-readiness U4): its identify advertises another wire227 /// major, or no agent version this daemon parses, or lists no sync228 /// protocol of this daemon's major. Reported once per node and daemon229 /// run, until [`TransportEvent::Cleared`]; no sync stream opens with230 /// it meanwhile.231 Incompatible {232 /// The incompatible node.233 node: Node,234 /// Its identify agent version, printable ASCII, at most235 /// `AGENT_MAX_BYTES`.236 agent: String,237 /// The wire major it advertises, `None` when its agent version238 /// names none.239 wire: Option<u16>,240 /// The wire major this daemon speaks.241 here: u16,242 },243 /// This daemon refused `node`'s sync and disconnected it, though it244 /// speaks the same wire major: its build and this one disagree245 /// (discussion:owner/320). Reported on its first refusal; the transport then246 /// lets it connect only after a doubling backoff, until247 /// [`TransportEvent::Cleared`].248 BuildRefused {249 /// The refused node.250 node: Node,251 /// Its identify agent version, empty if none arrived.252 agent: String,253 },254 /// A node reported [`TransportEvent::Incompatible`] or255 /// [`TransportEvent::BuildRefused`] is no longer: it identified again256 /// as compatible (it upgraded, or downgraded), or the transport forgot257 /// it to remember a newer one past its bound.258 Cleared {259 /// The node.260 node: Node,261 },262 /// `node` told this side it joined `topic`: on their first connection,263 /// gossipsub's greeting lists every topic the node is subscribed to,264 /// and a later join is told on its own. A publish on `topic` reaches265 /// the node from now on.266 Subscribed {267 /// The subscribed node.268 node: Node,269 /// The topic it joined.270 topic: String,271 },272 /// `node` asked this daemon `query` on the query protocol (273 /// discussion:owner/400 and 422): answer it with [`TransportCommand::Answer`] under274 /// `id`, within `QUERY_TIMEOUT_MS`, after which its stream is closed275 /// unanswered. At most `QUERY_INBOUND_PER_NODE` of one node's wait at276 /// once, each at most `QUERY_MAX_BYTES`.277 Asked {278 /// The node that asked.279 node: Node,280 /// The query's id, this daemon's own.281 id: u64,282 /// The query, opaque here.283 query: Vec<u8>,284 },285 /// The answer to this daemon's [`TransportCommand::Ask`] `id`, or why286 /// none came.287 Answered {288 /// The query's id, as the ask named it.289 id: u64,290 /// The answer, opaque here, or why none came.291 answer: Result<Vec<u8>, QueryFailure>,292 },293}294295/// Why a query got no answer (discussion:owner/400 and discussion:owner/422).296#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]297pub enum QueryFailure {298 /// The node is not connected.299 UnknownNode,300 /// The node doesn't speak the query protocol.301 NotSupported,302 /// No answer came within `QUERY_TIMEOUT_MS`.303 TimedOut,304 /// The stream failed, or the answer was over `QUERY_MAX_BYTES`.305 Failed,306}307308/// Gossipsub's validation verdict for a received message (discussion:owner/111):309/// only an accepted message is forwarded; a rejected one also counts310/// against the propagating node's score; an ignored one does neither.311#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]312pub enum Acceptance {313 /// Forward the message.314 Accept,315 /// Drop it and count it against the propagating node's score.316 Reject,317 /// Drop it.318 Ignore,319}320321/// What the daemon shell asks the swarm to do, built from the net actors'322/// outputs. Owner: `M3.transport`.323#[derive(Debug, Clone, PartialEq, Eq)]324pub enum TransportCommand {325 /// Signed reopened-stream incarnation verdict for the restart detector.326 IncarnationVerdict { node: Node, same: Option<bool> },327 /// Abort one sync stream's reader, writer, and queued frames without a328 /// fault penalty; the connection stays up for a caps-only reopen.329 AbortSync { node: Node },330 /// Dial the multiaddr `addr`.331 Dial {332 /// The multiaddr to dial.333 addr: String,334 },335 /// Write one frame (an encoded envelope) to the sync stream with336 /// `node`, length-delimited.337 SyncFrame {338 /// The node the stream is with.339 node: Node,340 /// The frame's bytes.341 frame: Vec<u8>,342 /// Written ahead of the stream's other queued frames: a control343 /// document's (`.lvcs/caps`, the namespace `.lvcs/tree`, …) or an344 /// inventory, which a node needs before its files' frames mean345 /// anything (a joiner's files wait for their paths).346 urgent: bool,347 },348 /// Report [`TransportEvent::SyncRoom`] once the sync stream with349 /// `node` has `room` bytes of its queue free (session-29a3231b/2): the350 /// sync actor holds what it writes the node until then. A full queue351 /// never closes the stream. `room` is what the sync actor's next frame352 /// needs within its share (r3-memory/12).353 AwaitRoom {354 /// The node the stream is with.355 node: Node,356 /// The room wanted.357 room: u64,358 },359 /// Stop reading the sync stream with `node` between frames, until360 /// [`TransportCommand::ResumeSync`] or the stream ends: its frames wait361 /// in the stream, whose flow control pushes back to the node362 /// (session-29a3231b/2). A paused stream is never taken for silent,363 /// and still closes as any other.364 PauseSync {365 /// The node the stream is with.366 node: Node,367 },368 /// Read the sync stream with `node` again.369 ResumeSync {370 /// The node the stream is with.371 node: Node,372 },373 /// Close every connection to `node`.374 Disconnect {375 /// The node to disconnect.376 node: Node,377 },378 /// Join a gossipsub topic.379 Subscribe {380 /// The topic to join.381 topic: String,382 },383 /// Leave a gossipsub topic.384 Unsubscribe {385 /// The topic to leave.386 topic: String,387 },388 /// Publish `data` (an encoded envelope) on `topic`.389 Publish {390 /// The topic to publish on.391 topic: String,392 /// The encoded envelope.393 data: Vec<u8>,394 },395 /// Report the validation of the gossipsub message `id` received from396 /// `propagation`.397 Validate {398 /// Gossipsub's message id.399 id: Vec<u8>,400 /// The node that forwarded it.401 propagation: Node,402 /// The verdict.403 acceptance: Acceptance,404 },405 /// Lower `node`'s score for a protocol violation (discussion:owner/459 and discussion:owner/111).406 Penalize {407 /// The node to penalize.408 node: Node,409 /// The violation.410 reason: Rejection,411 },412 /// Reset `node`'s score to neutral: its penalty ended with its last413 /// connection (fleetroll/1).414 Pardon {415 /// The node to pardon.416 node: Node,417 },418 /// Whether sync admits `node` (discussion:owner/494 and 495), so gossip419 /// goes to it (discussion:owner/617): until it does, nothing leaves420 /// over gossipsub for it.421 GossipAdmission {422 /// The node.423 node: Node,424 /// Whether it is admitted.425 admitted: bool,426 },427 /// Ask `node`'s daemon `query` on the query protocol (discussion:owner/400428 /// and 422); its answer, or why none came, is429 /// [`TransportEvent::Answered`] under `id`.430 Ask {431 /// The node to ask.432 node: Node,433 /// The query's id, the asker's own.434 id: u64,435 /// The query, opaque here, at most `QUERY_MAX_BYTES`.436 query: Vec<u8>,437 },438 /// Answer the query [`TransportEvent::Asked`] `id` with `answer` and439 /// close its stream; an id no longer held (answered, or past440 /// `QUERY_TIMEOUT_MS`) is ignored.441 Answer {442 /// The query's id.443 id: u64,444 /// The answer, opaque here, at most `QUERY_MAX_BYTES`.445 answer: Vec<u8>,446 },447 /// Stop the transport, as its last command: every connection is closed448 /// before the swarm is dropped, so each node sees it end at once rather449 /// than when its pings fail, and a restarted daemon's next connection is450 /// its nodes' first again.451 Stop,452}