docs/generated/contracts.mdgenerated from code
Reference · 11 min read
api-host
Contracts: api-host.
Read as
Source: crates/lvcs-api/src/host.rs.
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}