docs/generated/contracts.mdgenerated from code

Reference · 11 min read

api-host

Contracts: api-host.

Source: crates/lvcs-api/src/host.rs.

ruston main
1/// `hello`: must be the first request on a connection to the per-user2/// daemon (discussion:owner/272). `root` names the project every later request on3/// the connection acts on: an absolute path, which the daemon4/// canonicalizes, of a root it hosts. A root it doesn't host is refused5/// `NO_PEER` with `next` naming `lvcs project`; one whose opening6/// failed is refused with the reason it failed, and one still opening or7/// joining is refused `retry_after`. Without `root`, the connection is the8/// host's: it may call only `init`, `join`, `forget`, `project`, and9/// `status` (of every project), and `peer` must be absent.10///11/// With `root`, every later request acts as `peer` (a public key12/// in `ID_ENCODING`, an alias, or a prefix), whose key the project holds13/// under `KEYS_DIR`; without `peer`, as the project's default14/// peer (the owner after `init`, the joined peer after15/// `join`, or whom `lvcs project --as` named). Custody is per16/// OS user: a connection from any other user than the daemon's is refused17/// at accept, before `hello` (discussion:owner/272, revising 115 and 149). A key18/// with no live grant is accepted, and its signed requests are refused19/// `REJECTED` until a grant renders.20///21/// On a host node stream (discussion:owner/300) the daemon's first line is the22/// push `challenge`; `hello` names `root` and, for a device, its `device`23/// proof, and never `peer`. A device with a live device grant acts24/// as itself within it; one without may only `auth.pair`; with no25/// `device`, the connection reads what a `read` grant to `anyone` covers,26/// and is refused `NO_PEER` naming `lvcs auth login` when there is27/// none. A request past its scope is refused `REJECTED` `device_scope`.28/// A device's `hello` naming no root opens a host-level stream, which29/// reads only `project.summary`, `inbox`, and `resources`, over the30/// projects where the device holds a device grant.31#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]32pub struct HelloParams {33    #[serde(default, skip_serializing_if = "Option::is_none")]34    pub peer: Option<String>,35    /// The project root the connection acts on; absent for the host's.36    #[serde(default, skip_serializing_if = "Option::is_none")]37    pub root: Option<String>,38    /// On a host node stream with no `root`, the project's id in its39    /// place, as a public link names it (discussion:owner/337): the stream acts on40    /// the running project with that id. Ignored on the socket.41    #[serde(default, skip_serializing_if = "Option::is_none")]42    pub project: Option<String>,43    /// On a host node stream, the device's proof of its key (44    /// discussion:owner/300); absent for an anonymous reader. Never sent on the socket.45    #[serde(default, skip_serializing_if = "Option::is_none")]46    pub device: Option<DeviceProof>,47    /// On the socket, a harness session in `peer`'s place48    /// (discussion:owner/800): the connection acts as the peer the project49    /// binds that session to (`lvcs key new --session`), read at each50    /// `hello`, so a long-lived client follows a later binding by saying51    /// `hello` again. With `peer` too, refused `INVALID_PARAMS`; unbound,52    /// refused `NO_PEER` with `recover=wait`, never served as the default53    /// peer (discussion:owner/726).54    #[serde(default, skip_serializing_if = "Option::is_none")]55    pub session: Option<String>,56}5758/// `hello`'s result, on every connection (discussion:owner/325): the socket's and59/// a host node stream's, host-level and a project's. `version` is the60/// daemon's release, as `lvcs --version` prints it; absent, the daemon61/// predates discussion:owner/325, which answered `hello` with `{}`. `api` is62/// [`crate::API_VERSION`] as the daemon speaks it, 0 when absent. A client63/// that needs a newer daemon names `version` and `lvcs update` instead of64/// failing to decode a later reply. `unpaired` says, on a host node stream,65/// that the device proved its key but holds no device grant here (it never66/// paired, or its pairing ended): the stream serves it nothing but67/// `auth.pair`, so a client asks nothing else on it. Absent, false.68#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]69pub struct HelloResult {70    #[serde(default, skip_serializing_if = "Option::is_none")]71    pub version: Option<String>,72    #[serde(default)]73    pub api: u16,74    #[serde(default, skip_serializing_if = "core::ops::Not::not")]75    pub unpaired: bool,76}7778/// How a hosted project's transport runs (discussion:owner/272): its79/// own swarm in the per-user daemon, listening on `listen` (every IPv480/// interface, TCP and QUIC, on the port its project id derives, when81/// empty, discussion:owner/572),82/// dialing `bootstrap` at each opening, in seed mode when `seed`, and83/// with no mDNS when `no_mdns` (discussion:owner/307).84#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]85pub struct TransportParams {86    /// Multiaddrs to listen on.87    #[serde(default, skip_serializing_if = "Vec::is_empty")]88    pub listen: Vec<String>,89    /// Multiaddrs to dial at each opening, with their `/p2p/<node id>`.90    #[serde(default, skip_serializing_if = "Vec::is_empty")]91    pub bootstrap: Vec<String>,92    /// Seed mode: pin every document, serve as a circuit relay, and act93    /// as a bootstrap address, with no special authority.94    #[serde(default, skip_serializing_if = "core::ops::Not::not")]95    pub seed: bool,96    /// No mDNS: nodes find the project only through bootstrap addresses,97    /// Kademlia, and relays (discussion:owner/307).98    #[serde(default, skip_serializing_if = "core::ops::Not::not")]99    pub no_mdns: bool,100}101102/// The transport flags `project` changes (discussion:owner/572): each one103/// given replaces the registered one, and each one absent keeps it.104#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]105pub struct TransportPatch {106    #[serde(default, skip_serializing_if = "Option::is_none")]107    pub listen: Option<Vec<String>>,108    #[serde(default, skip_serializing_if = "Option::is_none")]109    pub bootstrap: Option<Vec<String>>,110    #[serde(default, skip_serializing_if = "Option::is_none")]111    pub seed: Option<bool>,112    /// Whether nodes are found on the local network (`false`: `--no-mdns`).113    #[serde(default, skip_serializing_if = "Option::is_none")]114    pub mdns: Option<bool>,115}116117impl TransportPatch {118    /// `base` with this patch's flags in place of its own.119    #[must_use]120    pub fn apply(&self, base: &TransportParams) -> TransportParams {121        TransportParams {122            listen: self.listen.clone().unwrap_or_else(|| base.listen.clone()),123            bootstrap: self124                .bootstrap125                .clone()126                .unwrap_or_else(|| base.bootstrap.clone()),127            seed: self.seed.unwrap_or(base.seed),128            no_mdns: self.mdns.map_or(base.no_mdns, |mdns| !mdns),129        }130    }131132    /// Whether it changes nothing.133    #[must_use]134    pub const fn is_empty(&self) -> bool {135        self.listen.is_none()136            && self.bootstrap.is_none()137            && self.seed.is_none()138            && self.mdns.is_none()139    }140}141142/// `init` (discussion:owner/272): create a project at `root` (absolute) and host143/// it, its default peer the owner. Refused when `root` holds144/// `.lvcs/` already: `lvcs project` registers an initialized project.145/// Answered once the project is open.146#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]147pub struct InitParams {148    pub root: String,149    #[serde(default)]150    pub transport: TransportParams,151    /// The name the owner is shown by (discussion:owner/682), which `lvcs152    /// init` takes from `--name` or the OS user; absent, or no owner name,153    /// shows the owner as `owner`.154    #[serde(default, skip_serializing_if = "Option::is_none")]155    pub name: Option<String>,156}157158/// `init` result: what `lvcs init` prints.159#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]160pub struct InitResult {161    /// The owner's peer id.162    pub owner: String,163    /// The project id.164    pub project: String,165    /// The project's node id in the daemon.166    pub node_id: String,167}168169/// `join` (discussion:owner/107, discussion:owner/215, and discussion:owner/272): create a peer170/// key and the device key at `root` (absolute, holding no `.lvcs/`), sync171/// project `project` from `transport.bootstrap`, and host it as the new172/// peer. Answered when the join ends. An incomplete join is173/// refused `retry_after` with what is unsettled; the project stays174/// registered and open, so its sync goes on.175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]176pub struct JoinParams {177    pub root: String,178    /// The project id (`ID_ENCODING`).179    pub project: String,180    #[serde(default)]181    pub transport: TransportParams,182}183184/// `join` result: what `lvcs join` prints.185#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]186pub struct JoinResult {187    /// The new peer's id.188    pub peer: String,189    /// The project id.190    pub project: String,191    /// The project's node id in the daemon.192    pub node_id: String,193    /// What a join that ended incomplete lacked (discussion:owner/575): it194    /// joined, its project is registered, and the daemon goes on syncing195    /// it; `lvcs status` shows how far.196    #[serde(default, skip_serializing_if = "Option::is_none")]197    pub incomplete: Option<String>,198}199200/// `forget` (discussion:owner/272): stop hosting the project at `root` and drop201/// it from the registry, leaving its files alone.202#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]203pub struct ForgetParams {204    pub root: String,205}206207/// `forget` result.208#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]209pub struct ForgetResult {210    /// The canonical root forgotten.211    pub root: String,212}213214/// `project` (discussion:owner/272): register the initialized project at `root`215/// (absolute) when the daemon doesn't host it, or change how it is216/// hosted, then open it again. `peer` is the default peer,217/// which authors changes made on disk in the project's tree (its id, an218/// alias, or a prefix; registering without one takes the owner);219/// `transport`, when given, replaces how its transport runs. A project220/// whose opening failed (for example on a format refusal, after `lvcs221/// migrate`) is opened again. Answered once it is open.222/// `title`, `description`, and `language`, when given, replace what the223/// project's directory listing says of it (discussion:owner/305: at most224/// `LISTING_TITLE_MAX_BYTES`, `LISTING_DESCRIPTION_MAX_BYTES`, and225/// `LISTING_LANGUAGE_MAX_BYTES`; empty clears one), kept in its226/// `.lvcs/listing.json`; lvcs.sh shows the title in place of the project227/// name, which its id is made of and never changes. While anyone may read the228/// project (`lvcs grant anyone read`), a daemon holding the owner's key229/// publishes the owner-signed listing to the tracker's directory, which230/// lvcs.sh's Explore and Trending list.231#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]232pub struct ProjectParams {233    pub root: String,234    #[serde(default, skip_serializing_if = "Option::is_none")]235    pub peer: Option<String>,236    #[serde(default, skip_serializing_if = "Option::is_none")]237    pub transport: Option<TransportParams>,238    /// The transport flags to change, each kept as registered when absent239    /// (discussion:owner/572); `transport`, when also given, is replaced240    /// first.241    #[serde(default, skip_serializing_if = "Option::is_none")]242    pub patch: Option<TransportPatch>,243    #[serde(default, skip_serializing_if = "Option::is_none")]244    pub title: Option<String>,245    #[serde(default, skip_serializing_if = "Option::is_none")]246    pub description: Option<String>,247    #[serde(default, skip_serializing_if = "Option::is_none")]248    pub language: Option<String>,249}250251/// `project` result.252#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]253pub struct ProjectResult {254    /// The canonical root.255    pub root: String,256    /// The default peer.257    pub peer: String,258    /// The project id.259    pub project: String,260    /// The project's node id in the daemon.261    pub node_id: String,262    /// The transport in force after the change (discussion:owner/572).263    #[serde(default, skip_serializing_if = "Option::is_none")]264    pub transport: Option<TransportParams>,265}266267/// `key.new` (discussion:owner/272): create a peer key in the268/// connection's project. With `alias` (discussion:owner/385), the agent named so:269/// when the project's key holder of `alias` is a peer whose key270/// this daemon holds, nothing is created and that peer answers271/// (`created` false); when another peer was ever granted it, the272/// request is refused `INVALID_PARAMS` with a free alias in `next`; else273/// a new key answers (`created` true), for the caller to grant under that274/// alias. An `alias` that isn't one (lowercase ASCII letters, digits, and275/// `-`, starting with a letter, at most `ALIAS_MAX_BYTES`) is refused276/// `INVALID_PARAMS`. With `session`, the harness session the caller binds277/// to the answer (discussion:owner/726): an `alias` whose peer another278/// session is bound to is refused `INVALID_PARAMS` with a free alias in279/// `next`, so a session's peer is never shared.280#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]281pub struct KeyNewParams {282    #[serde(default, skip_serializing_if = "Option::is_none")]283    pub alias: Option<String>,284    /// The harness session the caller binds to the answer285    /// (discussion:owner/726).286    #[serde(default, skip_serializing_if = "Option::is_none")]287    pub session: Option<String>,288}289290/// `key.new` result.291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]292pub struct KeyNewResult {293    /// The peer's id: the new one, or with `alias` the one that294    /// already holds it.295    pub peer: String,296    /// Whether a key was made (discussion:owner/385): false only when `alias`297    /// named a peer this daemon already holds.298    pub created: bool,299}300301/// `status` on the host's connection (discussion:owner/272): the socket and every302/// project the daemon hosts.303#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]304pub struct HostStatusResult {305    /// The socket (or pipe) the daemon serves.306    pub socket: String,307    /// Every hosted project, by root.308    #[serde(default)]309    pub projects: Vec<HostedProject>,310    /// The host node the app dials (discussion:owner/300), absent while it is off311    /// (until `lvcs auth login` turns it on) or when it couldn't start.312    #[serde(default, skip_serializing_if = "Option::is_none")]313    pub host_node: Option<HostNodeStatus>,314    /// Whether this daemon applies a signed release itself (discussion:owner/293):315    /// its own setting, under its own `LVCS_NO_AUTO_UPDATE`, not the316    /// caller's.317    #[serde(default)]318    pub auto_update: bool,319}320321/// `host.enable` and `host.disable` (discussion:owner/300): turn the host node on322/// or off, and keep it so across restarts. Answered with the host's323/// `status`. `lvcs auth login` enables it first.324#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]325pub struct HostToggleParams {}326327/// The per-user daemon's host node (discussion:owner/300): one libp2p identity328/// that reaches every hosted project over `/lvcs/rpc/1`.329#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]330pub struct HostNodeStatus {331    /// Its node id.332    pub node_id: String,333    /// Its WebRTC-direct addresses, each ending in `/certhash/<hash>/p2p/<node id>`.334    pub addrs: Vec<String>,335    /// The tracker it announces to and a browser signals it through336    /// (discussion:owner/301 and discussion:owner/327); none when `LVCS_TRACKER` is `off`.337    #[serde(default, skip_serializing_if = "Option::is_none")]338    pub tracker: Option<String>,339    /// The STUN servers a signaled session asks (discussion:owner/327).340    #[serde(default, skip_serializing_if = "Vec::is_empty")]341    pub stun: Vec<String>,342    /// Its relayed addresses (discussion:owner/639): each a relay's343    /// address, then `/p2p-circuit/p2p/<node id>`, once the relay344    /// accepted its reservation; a browser dials one when no direct path345    /// opens.346    #[serde(default, skip_serializing_if = "Vec::is_empty")]347    pub relayed: Vec<String>,348}349350/// One project the per-user daemon hosts.351#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]352pub struct HostedProject {353    /// Its canonical root.354    pub root: String,355    /// Where its lifecycle stands: `opening`, `joining`, `open`,356    /// `failed`, or `closing`.357    pub stage: String,358    /// The default peer.359    pub peer: String,360    /// Why its opening failed, when `stage` is `failed`.361    #[serde(default, skip_serializing_if = "Option::is_none")]362    pub reason: Option<String>,363    /// Its public link (discussion:owner/337), while a `read` grant to anyone364    /// holds and the host node is on: `APP_URL`, then `#` and its365    /// [`crate::auth::ReadLink`].366    #[serde(default, skip_serializing_if = "Option::is_none")]367    pub link: Option<String>,368    /// The counts its plugins keep for its card (discussion:owner/684),369    /// as its `status` gives them.370    #[serde(default, skip_serializing_if = "Vec::is_empty")]371    pub counts: Vec<crate::status::PluginCount>,372    /// Its listing's title (`.lvcs/listing.json`), when it has one.373    #[serde(default, skip_serializing_if = "Option::is_none")]374    pub title: Option<String>,375    /// Its listing's main language, when it has one (discussion:owner/684).376    #[serde(default, skip_serializing_if = "Option::is_none")]377    pub language: Option<String>,378}