docs/generated/contracts.mdgenerated from code

Reference · 6 min read

events

Contracts: events.

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

ruston main
1/// A range of lines, 1-based and inclusive.2#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]3pub struct EventRange {4    pub first: u32,5    pub last: u32,6}78/// One event (discussion:owner/515 and discussion:owner/525). `kind` is core's (`write`,9/// `session.ended`) or a plugin's `<plugin>.<name>`, which only that10/// plugin's keys, or a user through it, publish. `address` is what it is11/// about: a path, `path#pointer`, or a plugin ledger12/// `.lvcs/x/<plugin>/<path>`. `to` are the peers (`ID_ENCODING`) it is a13/// notification for. `data` is its JSON object, whose keys core reads only14/// where the plugin's manifest rules name them, and for the core kinds it15/// defines (a `write`'s `WriteBody`). `key` keeps one notification per16/// (recipient, key): a later event with the same key replaces it.17/// `final` settles the key: the event removes the open one and arrives18/// read, and the key's next event starts a fresh notification. An event19/// with no key is a one-off. `durable` events are appended to the ledger20/// at `address` (a plugin ledger) and sync; ephemeral ones travel by gossip21/// only and are never stored.22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]23pub struct Event {24    pub kind: String,25    pub address: String,26    #[serde(default, skip_serializing_if = "Vec::is_empty")]27    pub to: Vec<String>,28    #[serde(default, skip_serializing_if = "Option::is_none")]29    pub data: Option<Value>,30    #[serde(default, skip_serializing_if = "Option::is_none")]31    pub key: Option<String>,32    #[serde(default, rename = "final", skip_serializing_if = "std::ops::Not::not")]33    pub last: bool,34    #[serde(default)]35    pub durable: bool,36}3738/// `event.publish`: publish `event`, signed by the caller, or with39/// `on_behalf_of` (a peer's id, alias, or id start) by the calling40/// plugin's key under that user's delegated grant to it, which the daemon41/// issues the first time, attributed `<user> via <plugin>`. A durable42/// event is admitted under `write` on its ledger and the plugin's manifest43/// rules, as every node's verifier requires: a rule's field is a key of44/// `data`, or `address` (the event's address) or `to` (its recipients).45/// Refused `REJECTED` `out_of_scope` past them, and `INVALID_PARAMS` for a46/// kind the caller may not publish, a durable event whose address is no47/// plugin ledger, or `data` that isn't an object within `ENTRY_MAX_BYTES`.48#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]49pub struct EventPublishParams {50    pub event: Event,51    #[serde(default, skip_serializing_if = "Option::is_none")]52    pub on_behalf_of: Option<String>,53}5455/// `event.publish`'s params as the daemon reads them: [`EventPublishParams`]56/// and, optionally, `via`. With `via`, the caller publishes through that57/// plugin (discussion:owner/520: a surface's frame on a paired device): an event58/// of a `<via>.*` kind, a durable one about a ledger under its prefix,59/// signed by the plugin's key under the caller's delegated grant to it,60/// so it reads `<caller> via <via>`. Never with `on_behalf_of`.61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]62pub struct EventPublishThrough {63    #[serde(flatten)]64    pub publish: EventPublishParams,65    #[serde(default, skip_serializing_if = "Option::is_none")]66    pub via: Option<String>,67}6869/// `event.publish` result: its record's id (the `EventRecord` `id` it70/// reads back as), and for a durable event its ledger's heads after the71/// append.72#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]73pub struct EventPublishResult {74    pub id: String,75    #[serde(default, skip_serializing_if = "Vec::is_empty")]76    pub heads: Vec<String>,77}7879/// One event as it is read, pushed, or listed as a notification: its id,80/// the `HASH` in `ID_ENCODING` of the record's canonical CBOR (author,81/// plugin, device, time, and event; net-join/2), so it names this record,82/// not its event body: one body published by two authors, devices, or83/// times reads as two ids; its author (`ID_ENCODING`; the user a plugin published it for), the84/// plugin it came through when it did, the device that signed it85/// (`ID_ENCODING`; a durable event's, as its change's record names it,86/// discussion:owner/518; none for an ephemeral one), its signed time in Unix87/// milliseconds, and the event.88#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]89pub struct EventRecord {90    pub id: String,91    pub author: String,92    #[serde(default, skip_serializing_if = "Option::is_none")]93    pub via: Option<String>,94    #[serde(default, skip_serializing_if = "Option::is_none")]95    pub device: Option<String>,96    pub at_ms: i64,97    pub event: Event,98}99100/// `event.read`: one page of the events of the ledger at `address`,101/// oldest first (discussion:owner/562): the last `limit` when given, else102/// up to `count` from position `from` (0 when omitted), each at most103/// `EVENT_READ_PAGE_MAX`. When `kinds` names some, only events of those104/// kinds count, chosen before the page is cut (orchestrator/56): `limit`105/// and `count` are matching events, and `next` and `before` say where the106/// scan stopped. None for a ledger that holds none.107#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]108pub struct EventReadParams {109    pub address: String,110    #[serde(default, skip_serializing_if = "Vec::is_empty")]111    pub kinds: Vec<String>,112    #[serde(default, skip_serializing_if = "Option::is_none")]113    pub limit: Option<usize>,114    #[serde(default, skip_serializing_if = "Option::is_none")]115    pub from: Option<u64>,116    #[serde(default, skip_serializing_if = "Option::is_none")]117    pub count: Option<usize>,118    /// With `limit`: the last `limit` events before this position, an119    /// answer's `before` (discussion:owner/638), so a reader pages back a120    /// page at a time.121    #[serde(default, skip_serializing_if = "Option::is_none")]122    pub before: Option<u64>,123}124125/// `event.read` result: the ledger's heads, the page's events, and `next`,126/// the position the next page starts at (`from`), absent once the page127/// reached the ledger's end (discussion:owner/562).128#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]129pub struct EventReadResult {130    pub heads: Vec<String>,131    pub events: Vec<EventRecord>,132    #[serde(default, skip_serializing_if = "Option::is_none")]133    pub next: Option<u64>,134    /// The position of a `limit` page's first event, which a read with135    /// `before` set to it pages back from; absent once the page reaches the136    /// ledger's start (discussion:owner/638).137    #[serde(default, skip_serializing_if = "Option::is_none")]138    pub before: Option<u64>,139}140141/// `event.list`: the ledgers this daemon holds whose address starts with142/// `prefix` (`.lvcs/x/<plugin>/...`).143#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]144pub struct EventListParams {145    pub prefix: String,146}147148/// One ledger `event.list` names: its newest segment's `heads`, and149/// every segment of it the daemon holds (discussion:owner/820; none from150/// a daemon older than that).151#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]152pub struct EventLedger {153    pub address: String,154    pub heads: Vec<String>,155    #[serde(default, skip_serializing_if = "Vec::is_empty")]156    pub segments: Vec<EventSegment>,157}158159/// One segment of a ledger (discussion:owner/820): its `number` (the160/// unsegmented ledger itself is 0), its `heads`, and the `digest` of those161/// heads with the digest of the history each ends. Two answers naming a162/// segment with equal `heads` and `digest` name equal histories, so a163/// reader that kept what it read of a segment reads it again only when164/// they differ. Answered without starting the segment's document.165#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]166pub struct EventSegment {167    pub number: u32,168    pub heads: Vec<String>,169    pub digest: String,170}171172/// `event.list` result, sorted by address.173#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]174pub struct EventListResult {175    pub ledgers: Vec<EventLedger>,176}177178/// `event.subscribe`: deliver, as `event` pushes on this connection, each179/// event from now on whose `address` is `prefix` or under it (`""`180/// for every address), of `kinds` when it names some, durable or181/// ephemeral, that the caller may read.182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]183pub struct EventSubscribeParams {184    pub prefix: String,185    #[serde(default, skip_serializing_if = "Vec::is_empty")]186    pub kinds: Vec<String>,187}188189/// `event.subscribe` result: the subscription's id, which its pushes name.190#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]191pub struct EventSubscribeResult {192    pub sub: u64,193}194195/// `event.unsubscribe`: end the caller connection's `event.subscribe`196/// `sub`; another connection's, or one already ended, is left as it is.197#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]198pub struct EventUnsubscribeParams {199    pub sub: u64,200}201202/// `event.unsubscribe` result: an empty object.203#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]204pub struct EventUnsubscribeResult {}205206/// Server push, JSON-RPC notification method `event`: one event a207/// subscription matched.208#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]209pub struct EventPush {210    pub sub: u64,211    pub event: EventRecord,212}