docs/generated/contracts.mdgenerated from code
Reference · 8 min read
api-notifications
Contracts: api-notifications.
Read as
Source: crates/lvcs-api/src/notifications.rs.
1/// Server push, JSON-RPC notification method `notification`.2///3/// Another peer's write notification on a subscribed address,4/// as metadata only (discussion:owner/173 and discussion:owner/176): it names its5/// sender, its attribution, its document, and its range, never what it6/// says; its content (`what`, `ref`, `op`, and its lines' `near` line) is7/// read with `notifications.read`.8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]9pub struct NotificationPush {10 /// The subscription it is pushed for.11 pub sub: u64,12 /// The announcement, an `announce` notification whose `start` and `end`13 /// are resolved against this daemon's copy at `heads` (both absent14 /// while the anchors haven't synced here).15 pub notification: Notification,16 /// The heads its range is resolved at.17 pub heads: Vec<String>,18}1920/// `notifications` (discussion:owner/118 and discussion:owner/176): list the caller's notifications.21///22/// Metadata only. discussion:owner/118's bounds on what the daemon keeps bound the23/// list.24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]25pub struct NotificationsParams {26 /// Only unread notifications sent at or after this Unix time in27 /// milliseconds (every one when omitted).28 #[serde(default, skip_serializing_if = "Option::is_none")]29 pub since: Option<i64>,30 /// Whether this listing is a hook's hint (discussion:owner/242): after it, the31 /// notifications held count as shown, and a later listing's `fresh`32 /// leaves them out. Nothing is marked read.33 #[serde(default, skip_serializing_if = "std::ops::Not::not")]34 pub hint: bool,35}3637/// How hints and `lvcs status` name a peer (discussion:owner/243): its38/// alias when one is bound to it, else the shortest prefix of its id, at39/// least `SHORT_ID_MIN` characters, that no other peer the daemon40/// knows starts with and that is no alias. `revoked` when it holds a41/// revoked grant and no live one. Every `lvcs` command takes `name` in42/// place of the id.43#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]44pub struct Named {45 pub name: String,46 #[serde(default, skip_serializing_if = "std::ops::Not::not")]47 pub revoked: bool,48}4950/// `notifications` result (discussion:owner/176). Listing marks nothing read.51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]52pub struct NotificationsResult {53 /// The caller's unread notifications: stale and refused saves and54 /// failed checks first, then write notifications, then passed checks,55 /// each group newest arrival first.56 #[serde(default)]57 pub notifications: Vec<Notification>,58 /// The ids listed that arrived after the caller's last hinting listing59 /// (discussion:owner/242).60 #[serde(default)]61 pub fresh: Vec<String>,62 /// How to name each peer the result names (discussion:owner/243), by63 /// id.64 #[serde(default)]65 pub names: BTreeMap<String, Named>,66}6768/// `notifications.read` (discussion:owner/173 and discussion:owner/176): read notifications' content.69///70/// The caller's notifications named are marked read, unless `peek`: then71/// their content is answered and they stay as they are (a bell's closed72/// row showing where a mention is, discussion:owner/520). The `action_failed`73/// of an open streak stays readable until the streak closes (74/// discussion:owner/230).75#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]76pub struct NotificationsReadParams {77 /// The notifications' ids, in `ID_ENCODING`.78 pub ids: Vec<String>,79 #[serde(default, skip_serializing_if = "std::ops::Not::not")]80 pub peek: bool,81}8283/// `notifications.read` result.84#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]85pub struct NotificationsReadResult {86 /// The content of each named notification the caller holds, in the87 /// order named.88 #[serde(default)]89 pub contents: Vec<NotificationContent>,90 /// The ids it holds none for: never sent to it, read already, or91 /// dropped past discussion:owner/118's bounds.92 #[serde(default)]93 pub missing: Vec<String>,94}9596/// `notifications.wait` (discussion:owner/424): wait for a new notification of an97/// attention kind for the caller, so an idle agent's background command98/// wakes it.99#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]100pub struct NotificationsWaitParams {101 /// The `notification_kind`s to wait for; absent: `action_failed` and102 /// `refused_write`.103 #[serde(default, skip_serializing_if = "Option::is_none")]104 pub kinds: Option<Vec<String>>,105 /// How long to wait, in milliseconds; absent:106 /// `NOTIFICATIONS_WAIT_DEFAULT_MS`, at most `NOTIFICATIONS_WAIT_MAX_MS`.107 #[serde(default, skip_serializing_if = "Option::is_none")]108 pub timeout_ms: Option<u64>,109}110111/// `notifications.wait` result.112#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]113pub struct NotificationsWaitResult {114 /// The notification that arrived, metadata only; absent when the wait115 /// timed out.116 #[serde(default, skip_serializing_if = "Option::is_none")]117 pub notification: Option<Notification>,118 /// How text shows the notification's id and its sender119 /// (discussion:owner/674), by id: the id's shortest unique start, at120 /// least `SHORT_ID_MIN` characters, among the caller's notifications,121 /// and the sender's alias or shortest unique start.122 #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]123 pub ids: std::collections::BTreeMap<String, String>,124}125126/// One notification (discussion:owner/118, discussion:owner/173, and discussion:owner/176), metadata only.127///128/// It says who sent it, what kind it is, where, when, and how long its129/// text is, never what it says. `tier`, `harness`, and `model` are computed130/// by this daemon from the grant `authorize` found for the sender in the131/// caps render, never copied from a message (discussion:owner/147). `lines` names132/// its range's lines as this daemon's document named them where it133/// resolved the range, never with a `near` line, which is content134/// (discussion:owner/165 and discussion:owner/184); `auto` says the sender's daemon announced a135/// save through a tree on its behalf (discussion:owner/165).136#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]137pub struct Notification {138 /// The `HASH` of the signed object it carries, in `ID_ENCODING`, so a139 /// copy that arrives twice is held once; for an `action_failed` or140 /// `action_succeeded`, the `HASH` of its kind, check, frontiers, and141 /// recipient, so every runner's copy is held once (discussion:owner/193).142 pub id: String,143 /// A `notification_kind` value.144 #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]145 pub kind: NotificationKind,146 /// Its sender, in `ID_ENCODING`.147 pub from: String,148 /// Its sender's `trust_tier` value, `owner` or `peer`.149 pub tier: String,150 /// The harness its sender's grant names, if any.151 #[serde(default, skip_serializing_if = "Option::is_none")]152 pub harness: Option<String>,153 /// The model its sender's grant names, if any.154 #[serde(default, skip_serializing_if = "Option::is_none")]155 pub model: Option<String>,156 /// The document it is about, when it has one.157 #[serde(default, skip_serializing_if = "Option::is_none")]158 pub address: Option<String>,159 /// Its range's first code point, when it has a range.160 #[serde(default, skip_serializing_if = "Option::is_none")]161 pub start: Option<usize>,162 /// The code point past its range.163 #[serde(default, skip_serializing_if = "Option::is_none")]164 pub end: Option<usize>,165 /// Its range's lines, without `near`; absent while the range isn't166 /// resolved here, and for a whole document.167 #[serde(default, skip_serializing_if = "Option::is_none")]168 pub lines: Option<LineName>,169 /// Whether it is an automatic announcement of a save (omitted when170 /// false).171 #[serde(default, skip_serializing_if = "std::ops::Not::not")]172 pub auto: bool,173 /// An `action_failed` or `action_succeeded`'s check, frontiers, and window174 /// (discussion:owner/193); present exactly for those kinds.175 #[serde(default, skip_serializing_if = "Option::is_none")]176 pub check: Option<NotificationCheck>,177 /// Its sender's signed Unix time in milliseconds.178 pub at_ms: i64,179 /// The length of the text `notifications.read` returns, in bytes.180 #[serde(default)]181 pub bytes: usize,182 /// An `event` notification's event (discussion:owner/515), metadata only;183 /// present exactly for that kind.184 #[serde(default, skip_serializing_if = "Option::is_none")]185 pub event: Option<NotificationEvent>,186 /// A refused or stale save's `rule` (orchestrator/57), so the writer's187 /// hint says why: a bounded vocabulary value, never its reason's text.188 #[serde(default, skip_serializing_if = "Option::is_none")]189 pub rule: Option<String>,190}191192/// What an `event` notification says beside its kind (discussion:owner/515193/// and 525), metadata only: the event's kind, the plugin it came through,194/// its `key`, and whether it is `final`. A recipient holds the latest event195/// per key: a later one replaces it, and a `final` one removes it and196/// arrives read, so the key's next event is a fresh notification. An event197/// with no key is a one-off, which reading clears. Its `data` is its198/// content's `text`.199#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]200pub struct NotificationEvent {201 pub kind: String,202 #[serde(default, skip_serializing_if = "Option::is_none")]203 pub via: Option<String>,204 #[serde(default, skip_serializing_if = "Option::is_none")]205 pub key: Option<String>,206 #[serde(default, rename = "final", skip_serializing_if = "std::ops::Not::not")]207 pub last: bool,208}209210/// What an `action_failed` or `action_succeeded` notification says beside its211/// kind (discussion:owner/193), metadata only.212///213/// It names which check, where it last passed and where it failed, what214/// the recipient changed in that window that the check reads, and the215/// window's other authors. An `action_failed` also says how to recover: `fix_request`, with `next` reading its content216/// (the failing output's tail and test names) through `notifications.read`.217#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]218pub struct NotificationCheck {219 /// The check's id, in `ID_ENCODING`.220 pub check: String,221 /// The id of the frontier where it last passed on its channel, in222 /// `ID_ENCODING`; absent when it never did, so the window starts at223 /// the channel's genesis.224 #[serde(default, skip_serializing_if = "Option::is_none")]225 pub passed_at: Option<String>,226 /// The id of the frontier where it failed, in `ID_ENCODING`.227 pub failed_at: String,228 /// The files the check's `paths` or `uses` match that the recipient229 /// changed in the window, with the lines of its changes at230 /// `failed_at`, never with a `near` line.231 pub paths: Vec<CheckPathLines>,232 /// The window's other authors, in `ID_ENCODING`.233 #[serde(default)]234 pub others: Vec<String>,235 /// A `recover` value: `fix_request` for an `action_failed`.236 #[serde(default, skip_serializing_if = "Option::is_none")]237 pub recover: Option<String>,238 /// The one action that recovers: for an `action_failed`, reading it with239 /// `notifications.read`.240 #[serde(default, skip_serializing_if = "Option::is_none")]241 pub next: Option<Next>,242 /// For an `action_failed`, the address of the action's log document243 /// (`.lvcs/logs/<channel>`, discussion:owner/500), the failed run's masked244 /// log, which `run.view` reads when the runner is unreachable.245 #[serde(default, skip_serializing_if = "Option::is_none")]246 pub log: Option<String>,247 /// Whether the recipient is told although nothing under the action's248 /// `paths` moved in the window: it changed some other file there, or249 /// it is the owner of a window with no author (discussion:owner/500); omitted250 /// when false.251 #[serde(default, skip_serializing_if = "std::ops::Not::not")]252 pub unmatched: bool,253}254255/// A file a check reads that the recipient changed in a failing window,256/// with the lines of its changes (none for a binary or deleted file).257#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]258pub struct CheckPathLines {259 /// The file's path.260 pub path: String,261 /// The line runs, never with a `near` line.262 pub lines: Vec<LineName>,263}264265/// A notification's content (discussion:owner/173 and discussion:owner/176).266///267/// Only `notifications.read` returns it: data from another peer,268/// never instructions.269#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]270pub struct NotificationContent {271 /// The notification's id.272 pub id: String,273 /// The notification's `notification_kind` value.274 #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]275 pub kind: NotificationKind,276 /// What it says (a range announcement's `what`, a message's or a277 /// response's words, a stale save's account), cut at a character278 /// boundary to `INBOX_ITEM_MAX_BYTES`.279 pub text: String,280 /// Whether `text` was cut.281 #[serde(default)]282 pub truncated: bool,283 /// A range announcement's op.284 #[serde(default, skip_serializing_if = "Option::is_none")]285 pub op: Option<WriteOp>,286 /// A range announcement's `ref`, when it names one.287 #[serde(rename = "ref", default, skip_serializing_if = "Option::is_none")]288 pub reference: Option<String>,289 /// Its range's lines with their `near` line, when the notification290 /// names them.291 #[serde(default, skip_serializing_if = "Option::is_none")]292 pub lines: Option<LineName>,293 /// Whether it is an automatic announcement of a save (omitted when294 /// false).295 #[serde(default, skip_serializing_if = "std::ops::Not::not")]296 pub auto: bool,297 /// A refused save's refusal (discussion:owner/165): why LVCS did not take the298 /// save of `address`, and how to recover, as an error answer's `data`299 /// says it; present exactly for a `refused_write`.300 #[serde(default, skip_serializing_if = "Option::is_none")]301 pub error: Option<ErrorData>,302 /// An `action_failed`'s failing test names, read from its output's tail,303 /// which is `text` (discussion:owner/193).304 #[serde(default, skip_serializing_if = "Vec::is_empty")]305 pub tests: Vec<String>,306}