docs/generated/contracts.mdgenerated from code

Reference · 11 min read

transport

Contracts: transport.

Source: crates/lvcs-net/src/transport/mod.rs.

ruston main
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}