docs/generated/contracts.mdgenerated from code
Reference · 12 min read
plugins
Contracts: plugins.
Read as
Source: crates/lvcs-api/src/plugins.rs.
1/// `peer.resolve` (discussion:owner/514): the peer each of `names` is, an alias,2/// an id, or an id's start, as `grant` resolves one; refused3/// `INVALID_PARAMS` naming the first that is no peer this project knows or4/// names several (the candidates in `next`).5#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]6pub struct PeerResolveParams {7 pub names: Vec<String>,8}910/// `peer.resolve` result: each name's peer id (`ID_ENCODING`), in order,11/// the calling peer's own, and the name the project's directory gives each12/// id resolved (its alias, else its short id), so an id passed in comes13/// back with the alias to show.14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]15pub struct PeerResolveResult {16 pub ids: Vec<String>,17 pub me: String,18 #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]19 pub names: std::collections::BTreeMap<String, String>,20}2122/// `plugin.install` (discussion:owner/768 points 10, 12, and 18): put a23/// plugin into this project's store, or with `global` into the node's for24/// every project its daemon hosts, on the host's own connection only.25/// `source` is the plugin's directory (an absolute path on the daemon's26/// host, holding its `plugin.toml`) or an install source: a release index27/// URL (`https://...[@x.y.z]#key=<key>`) or `github:<owner>/<repo>[@x.y.z]#key=<key>`,28/// whose signed release entry is checked before anything is kept. With29/// `enable` it is then enabled in this project as `plugin.enable` enables30/// it; `binary` (an absolute path, a directory source only) is the31/// plugin's built binary in place of the manifest's `binary` inside it,32/// and `allow_remote` names the manifest's remote roles the installer33/// allows at that enable. Refused `INVALID_PARAMS` for a source that is34/// neither, a manifest that doesn't parse, a plugin this project already35/// has (`plugin.upgrade` replaces it), or what enable refuses.36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]37pub struct PluginInstallParams {38 pub source: String,39 #[serde(default, skip_serializing_if = "core::ops::Not::not")]40 pub global: bool,41 #[serde(default, skip_serializing_if = "core::ops::Not::not")]42 pub enable: bool,43 #[serde(default, skip_serializing_if = "Option::is_none")]44 pub binary: Option<String>,45 #[serde(default, skip_serializing_if = "Vec::is_empty")]46 pub allow_remote: Vec<String>,47}4849/// `plugin.upgrade` (discussion:owner/768 point 5): replace plugin `name`,50/// which this project has, with the one `source` gives (as51/// `plugin.install` reads a source), in the store it resolves from, or with52/// `global` in the node's; it runs again under its key, with what the new53/// manifest declares. Refused `INVALID_PARAMS` with no source, for a source54/// holding another plugin, or a plugin this project doesn't have.55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]56pub struct PluginUpgradeParams {57 pub name: String,58 #[serde(default, skip_serializing_if = "Option::is_none")]59 pub source: Option<String>,60 #[serde(default, skip_serializing_if = "core::ops::Not::not")]61 pub global: bool,62}6364/// `plugin.install` and `plugin.upgrade` result: the plugin and version65/// kept, the store that holds it (`project` or `node`), its tree digest66/// (64 lowercase hex), what enabling it gave when it was enabled, and the67/// step left when one is.68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]69pub struct PluginInstallResult {70 pub name: String,71 pub version: String,72 pub scope: String,73 pub digest: String,74 #[serde(default, skip_serializing_if = "Option::is_none")]75 pub enabled: Option<PluginEnableResult>,76 #[serde(default, skip_serializing_if = "Option::is_none")]77 pub next: Option<String>,78}7980/// One installed plugin as `plugin.list` answers it: its name, version,81/// the command it adds (or its parent's, for a sub-plugin), its directory82/// and binary, its key, its locality, the remote roles allowed at83/// install, its `serve` command when it has one, and its config path when84/// `lvcs.toml` names one.85#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]86pub struct PluginInfo {87 pub name: String,88 pub version: String,89 #[serde(default, skip_serializing_if = "Option::is_none")]90 pub command: Option<String>,91 #[serde(default, skip_serializing_if = "Option::is_none")]92 pub parent: Option<String>,93 pub dir: String,94 pub binary: String,95 pub key: String,96 pub locality: String,97 #[serde(default, skip_serializing_if = "Vec::is_empty")]98 pub allow_remote: Vec<String>,99 #[serde(default, skip_serializing_if = "Option::is_none")]100 pub serve: Option<Vec<String>>,101 #[serde(default, skip_serializing_if = "Option::is_none")]102 pub config: Option<String>,103 /// Why its `serve` stopped and isn't restarted: the last line it wrote104 /// to stderr before it exited `EX_CONFIG` (78), until an install or105 /// an upgrade runs it again.106 #[serde(default, skip_serializing_if = "Option::is_none")]107 pub halted: Option<String>,108 /// The store it runs from in this project: `project`, `node`, or109 /// `daemon` (discussion:owner/768 point 13).110 #[serde(default)]111 pub scope: String,112 /// Whether this project enables it.113 #[serde(default)]114 pub enabled: bool,115 /// Its tree digest in that store, 64 lowercase hex; empty for a plugin116 /// no store holds (one 0.2.x installed by path).117 #[serde(default, skip_serializing_if = "String::is_empty")]118 pub digest: String,119 /// Why it is held, not running, when it is.120 #[serde(default, skip_serializing_if = "Option::is_none")]121 pub held: Option<String>,122 /// Its `serve` ended itself idle (`plugin.dormant`) and starts again on123 /// its wake filters, at its wake time, or with an install or upgrade124 /// (discussion:owner/790).125 #[serde(default, skip_serializing_if = "core::ops::Not::not")]126 pub dormant: bool,127}128129/// `plugin.list` result, sorted by name.130#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]131pub struct PluginListResult {132 pub plugins: Vec<PluginInfo>,133}134135/// `plugin.remove` (discussion:owner/514): revoke every grant the plugin holds,136/// delete its record from `.lvcs/caps`, and unregister its command; its137/// ledgers stay. Refused `INVALID_PARAMS` for a plugin not installed, or138/// one another installed plugin depends on (named in the reason).139#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]140pub struct PluginRemoveParams {141 pub name: String,142}143144/// `plugin.remove` result: the plugin and the grants revoked. If the145/// selected local directory changed during signing, the signed removal still146/// completes; `local_conflict` names the remaining local cleanup work.147#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]148pub struct PluginRemoveResult {149 pub name: String,150 pub revoked: Vec<String>,151 #[serde(default, skip_serializing_if = "core::ops::Not::not")]152 pub local_conflict: bool,153 #[serde(default, skip_serializing_if = "Option::is_none")]154 pub next: Option<String>,155}156/// `plugin.enable` (discussion:owner/768): enable in this project a plugin157/// the node's store holds, by name: its key, exactly the grants its158/// manifest declares, and its record. Refused `INVALID_PARAMS` for a name159/// no store holds.160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]161pub struct PluginEnableParams {162 pub name: String,163}164165/// `plugin.enable` result: the plugin, its key in `ID_ENCODING`, the grants166/// it holds (ids), the store it runs from (`project`, `node`, or167/// `daemon`), the optional dependencies it found missing, and the step168/// left when one is.169#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]170pub struct PluginEnableResult {171 pub name: String,172 pub key: String,173 pub grants: Vec<String>,174 pub scope: String,175 /// The alias the owner's first enable gave the key: the plugin's name,176 /// or its first free `-<n>` variant when another peer holds the name177 /// (session-9468d544/29).178 #[serde(default, skip_serializing_if = "Option::is_none")]179 pub alias: Option<String>,180 #[serde(default, skip_serializing_if = "Vec::is_empty")]181 pub missing_optional: Vec<String>,182 /// A person enabled a held plugin with a newly minted key: the prior183 /// key's grants were not carried to it.184 #[serde(default, skip_serializing_if = "core::ops::Not::not")]185 pub prior_grants_not_carried: bool,186 /// A runner's enable (discussion:owner/518): the grant the owner issues187 /// this node's key, as the `lvcs` command that issues it.188 #[serde(default, skip_serializing_if = "Option::is_none")]189 pub next: Option<String>,190}191192/// `plugin.disable` (discussion:owner/768): revoke the plugin's grants in193/// this project and stop it; its key, record, and documents stay.194#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]195pub struct PluginDisableParams {196 pub name: String,197}198199/// `plugin.disable` result: the grants revoked, and those that could not200/// be with the step that revokes them.201#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]202pub struct PluginDisableResult {203 pub name: String,204 pub revoked: Vec<String>,205 #[serde(default, skip_serializing_if = "Vec::is_empty")]206 pub not_revoked: Vec<String>,207 #[serde(default, skip_serializing_if = "Option::is_none")]208 pub next: Option<String>,209}210211/// `plugin.surfaces` (discussion:owner/520): every installed plugin with the UI212/// surfaces it ships, for the app, on any session that may read the213/// project, a paired device's too. It names no host path, binary, or key.214#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]215pub struct PluginSurfacesParams {}216217/// `plugin.surfaces` result, by name.218#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]219pub struct PluginSurfacesResult {220 pub plugins: Vec<PluginSurfaces>,221}222223/// One installed plugin as the app shows it: its name, its public peer id224/// (`ID_ENCODING`, the author of what it publishes), version, author (as225/// its manifest says, never checked), command or parent, the plugins it226/// depends on (whose ledgers its surfaces may read, read-only, within the227/// user's own read grants), each capability it was granted with its228/// paths, and its surfaces.229#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]230pub struct PluginSurfaces {231 pub name: String,232 pub plugin_key: String,233 pub version: String,234 #[serde(default, skip_serializing_if = "Option::is_none")]235 pub author: Option<String>,236 /// What it does, as its manifest says.237 #[serde(default, skip_serializing_if = "Option::is_none")]238 pub description: Option<String>,239 #[serde(default, skip_serializing_if = "Option::is_none")]240 pub command: Option<String>,241 #[serde(default, skip_serializing_if = "Option::is_none")]242 pub parent: Option<String>,243 #[serde(default, skip_serializing_if = "Vec::is_empty")]244 pub dependencies: Vec<String>,245 pub permissions: std::collections::BTreeMap<String, Vec<String>>,246 pub surfaces: Vec<SurfaceInfo>,247}248249/// One UI surface: a sandboxed web component of `kind` at the surface API250/// `version`, whose module is `entry`, a path under the plugin's `ui/`,251/// loading the other files `assets` names there.252#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]253pub struct SurfaceInfo {254 pub kind: String,255 pub version: String,256 pub entry: String,257 #[serde(default, skip_serializing_if = "Vec::is_empty")]258 pub assets: Vec<String>,259 /// A card's places (discussion:owner/689): `home`, `public`, `overview`;260 /// none is the project Overview alone.261 #[serde(default, skip_serializing_if = "Vec::is_empty")]262 pub places: Vec<String>,263 /// A card's size, `wide` or `narrow`; none is narrow.264 #[serde(default, skip_serializing_if = "Option::is_none")]265 pub size: Option<String>,266 /// A tab's label; none is the plugin's name.267 #[serde(default, skip_serializing_if = "Option::is_none")]268 pub label: Option<String>,269 /// The link names a tab answers.270 #[serde(default, skip_serializing_if = "Vec::is_empty")]271 pub routes: Vec<String>,272}273274/// `plugin.asset` (discussion:owner/520): the bytes of `path`, a file the plugin275/// `plugin`'s surfaces declare (an entry or an asset) under its `ui/`, at276/// most `PLUGIN_ASSET_MAX_BYTES`, on any session `plugin.surfaces`277/// answers. Refused `invalid_params` for an undeclared path, one outside278/// `ui/`, a plugin not installed, or one hosted at a URL, whose surfaces279/// its host serves.280#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]281pub struct PluginAssetParams {282 pub plugin: String,283 pub path: String,284}285286/// `plugin.asset` result: the file's bytes (standard base64) and its media287/// type, from its extension (`application/octet-stream` when unknown).288#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]289pub struct PluginAssetResult {290 pub bytes_base64: String,291 pub content_type: String,292}293/// `plugin.configure` (discussion:owner/521): set the keys `values` names of the294/// plugin `plugin`'s settings, each checked against its manifest's295/// `[settings]`: a key it declares, of its default's type (an integer296/// where the default is one, a number where it is a float, an array of the297/// default's element type, a table of its keys). It saves `lvcs.toml`'s298/// `[plugins.<plugin>]`, and only those keys of it, or the plugin's own299/// toml when the section names a path, as the caller (a paired device's300/// issuer): a protected change, pending until an `Approve` holder301/// approves it. Callable from a device paired with `write`.302#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]303pub struct PluginConfigureParams {304 pub plugin: String,305 pub values: serde_json::Map<String, serde_json::Value>,306}307308/// `plugin.configure` result: the file saved, its heads after the save,309/// and whether it waits for approval or applied at once.310#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]311pub struct PluginConfigureResult {312 /// The save waits for an `Approve` holder's approval.313 pub pending: bool,314 /// The saver holds `Approve` on the file, so its save is its own315 /// approval (discussion:owner/479) and applies without waiting.316 #[serde(default, skip_serializing_if = "std::ops::Not::not")]317 pub applied: bool,318 pub path: String,319 pub heads: Vec<String>,320}321/// `plugin.config` (discussion:owner/521): plugin `plugin`'s settings as a322/// settings surface reads them: `values`, its `[plugins.<plugin>]` (or its323/// own toml) at the file's approved heads; `defaults`, its manifest's324/// `[settings]`; and `pending`, the values main holds beyond the approved325/// heads, while a change waits for approval. Callable from any device326/// whose read grants cover `lvcs.toml`.327#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]328pub struct PluginConfigParams {329 pub plugin: String,330}331332/// `plugin.config` result.333#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]334pub struct PluginConfigResult {335 pub values: serde_json::Map<String, serde_json::Value>,336 pub defaults: serde_json::Map<String, serde_json::Value>,337 #[serde(default, skip_serializing_if = "Option::is_none")]338 pub pending: Option<PendingConfig>,339}340341/// The settings a change not yet approved holds, in the file at `path`.342#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]343pub struct PendingConfig {344 pub path: String,345 pub values: serde_json::Map<String, serde_json::Value>,346}347348/// `plugin.dormant` (discussion:owner/790): a plugin's `serve`, said from its349/// own process as the plugin's key, is about to exit idle. Its keeper notes350/// it and watches `wake` from now on: once that serve exits 0 it stays351/// down, costing no memory, and is started again by the first event one of352/// `wake` matches (at most once per `PLUGIN_DORMANT_MIN_MS`), at353/// `wake_at_ms` (Unix ms) when given, or by an install or upgrade. An event354/// matched before it exits makes its exit restart it as any exit does. At355/// most `PLUGIN_WAKE_FILTERS_MAX` filters. Refused `rejected`356/// (`not_authorized`) from any other process or key, and `INVALID_PARAMS`357/// for a filter `event.subscribe` would refuse, too many, or neither a358/// filter nor a wake time.359#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]360pub struct PluginDormantParams {361 #[serde(default)]362 pub wake: Vec<WakeFilter>,363 /// Document patterns, as `subscribe` takes them (a document address,364 /// a path prefix ending in `/**`, or `**`), a change to any of which365 /// wakes it too, a plain file write included (discussion:owner/797).366 /// They count toward `PLUGIN_WAKE_FILTERS_MAX` with `wake`.367 #[serde(default, skip_serializing_if = "Vec::is_empty")]368 pub docs: Vec<String>,369 #[serde(default, skip_serializing_if = "Option::is_none")]370 pub wake_at_ms: Option<i64>,371}372373/// One event filter that wakes a dormant serve, as `event.subscribe` takes374/// one: a ledger's address, a prefix ending in `/`, or `""` for every375/// ledger, and the event kinds (every kind when empty).376#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]377pub struct WakeFilter {378 pub prefix: String,379 #[serde(default, skip_serializing_if = "Vec::is_empty")]380 pub kinds: Vec<String>,381}382383/// `plugin.dormant` result: the keeper noted it, and its wake filters are384/// watched.385#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]386pub struct PluginDormantResult {}387388/// `plugin.busy` (discussion:owner/790 item 3): a plugin's `serve`, said389/// from its own process as the plugin's key, answers a `plugin.rest` push:390/// it is busy (runs under way, claims held) and serves on. Its keeper391/// tells the plugin admitter, which asks the next-quietest serve instead392/// and asks this one again only once it is sampled quiet. Refused393/// `rejected` (`not_authorized`) from any other process or key, or when394/// no rest was asked of it. No params.395#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]396pub struct PluginBusyParams {}397398/// `plugin.busy` result: the keeper noted it.399#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]400pub struct PluginBusyResult {}401402/// `plugin.admit` (discussion:owner/790 item 3): room in the plugins'403/// memory share (`PLUGINS_RSS_BYTES`) for plugin `plugin`'s command, asked404/// by the CLI before it runs the command as its own process. Answered once405/// there is room; the process's room is held until it exits. Never406/// refused for want of room (ruling lnhoqmrf (a)): when no room came407/// within `PLUGIN_ADMIT_WAIT_MS` it is answered with `waiting`, keeping the408/// command's place for the same process to ask again. Local only: a409/// caller whose process the platform doesn't name runs unadmitted.410#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]411pub struct PluginAdmitParams {412 /// The plugin whose command runs: its last command's peak is what it413 /// is charged.414 #[serde(default, skip_serializing_if = "String::is_empty")]415 pub plugin: String,416}417418/// `plugin.admit` result: the command has room, or, with `waiting`, it419/// still waits and its process asks again.420#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]421pub struct PluginAdmitResult {422 /// Set when the command still waits for room.423 #[serde(default, skip_serializing_if = "Option::is_none")]424 pub waiting: Option<PluginAdmitWaiting>,425}426427/// A plugin command still waiting for room in the plugins' share.428#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]429pub struct PluginAdmitWaiting {430 /// Commands asked before it, still waiting.431 #[serde(default)]432 pub ahead: u32,433 /// Bytes the plugins hold now.434 #[serde(default)]435 pub held_bytes: u64,436 /// The plugins' share, in bytes.437 #[serde(default)]438 pub share_bytes: u64,439}