docs/generated/contracts.mdgenerated from code

Reference · 12 min read

plugins

Contracts: plugins.

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

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