docs/generated/contracts.mdgenerated from code

Reference · 8 min read

api-notifications

Contracts: api-notifications.

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

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