docs/generated/contracts.mdgenerated from code

Reference · 7 min read

inbox

Contracts: inbox.

Source: crates/lvcs/src/daemon/mailbox.rs.

ruston main
1/// One notification as the shell offers it: its metadata and its content.2#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]3pub(crate) struct Received {4    /// What `notifications` lists of it.5    pub(crate) notification: Notification,6    /// What `notifications.read` returns of it.7    pub(crate) content: NotificationContent,8}910/// A candidate notification for one peer.11///12/// Kept only when it names `peer` directly or its address matches13/// the peer's interest, and when its signed `at_ms` lies in14/// [`now_ms` − `BULLETIN_SECS`, `now_ms` + `INBOX_SKEW_MS`].15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]16pub(crate) struct Item {17    /// The local peer it is offered to.18    pub(crate) peer: PeerKey,19    /// The notification.20    pub(crate) received: Received,21    /// Its arrival time, which orders listing.22    pub(crate) now_ms: i64,23}2425/// Whom a `List` or `Read` answers: a request the shell serves26/// (`status`), or a question asked without the shell (owner/18), which27/// the machine's close completes.28#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]29pub(crate) enum Answer {30    /// The shell's request.31    Shell(RequestId),32    /// The question.33    Ask(ReplyTo),34}3536/// List a peer's unread notifications, as the module docs order them.37#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]38pub(crate) struct List {39    /// Whom it answers.40    pub(crate) answer: Answer,41    /// The peer.42    pub(crate) peer: PeerKey,43    /// Only unread notifications sent at or after this time (every one44    /// when `None`).45    pub(crate) since: Option<i64>,46    /// The most bytes of their JSON listed (no bound when `None`).47    pub(crate) max_bytes: Option<u32>,48    /// Whether it is a hook's hint (discussion:owner/242): after it, every49    /// notification the peer holds counts as shown.50    pub(crate) hint: bool,51    /// The shell's clock when the request came.52    pub(crate) now_ms: i64,53}5455/// Read the content of `peer`'s notifications `ids` for a56/// `notifications.read`, marking them read unless `peek`.57#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]58pub(crate) struct Read {59    /// Whom it answers.60    pub(crate) answer: Answer,61    /// The peer.62    pub(crate) peer: PeerKey,63    /// The notification ids to read.64    pub(crate) ids: Vec<String>,65    /// Answer their content and leave them unread.66    #[serde(default)]67    pub(crate) peek: bool,68    /// The shell's clock when the request came.69    pub(crate) now_ms: i64,70}7172/// A runner's check notice for `peer` (discussion:owner/193): a73/// `action_failed` when `failed`, else an `action_succeeded`, on check `check`.74/// A plugin event's streak rides on its `Item` instead (discussion:owner/532,75/// session-8faca4ed/5).76#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]77pub(crate) struct Check {78    /// The local peer it names.79    pub(crate) peer: PeerKey,80    /// The check's id, in `ID_ENCODING`.81    pub(crate) id: String,82    /// Whether it is an `action_failed`.83    pub(crate) failed: bool,84    /// Its notification, as the `Item` that follows offers it.85    pub(crate) notification: Notification,86    /// The shell's clock when it came.87    pub(crate) now_ms: i64,88}8990/// What one plugin event kind does to its recipient's check streaks91/// (discussion:owner/532): `kind` of `plugin` opens (`opens_streak`) or closes92/// the streak named by its opening kind `opens`.93#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]94pub(crate) struct StreakRule {95    /// The plugin.96    pub(crate) plugin: String,97    /// The event kind.98    pub(crate) kind: String,99    /// The opening kind's name, which names the streak.100    pub(crate) opens: String,101    /// Whether it opens the streak, else closes it.102    pub(crate) opens_streak: bool,103}104105/// The installed plugins' streak kinds (discussion:owner/532), as the mailbox106/// keeps them.107pub(crate) type StreakKinds = Vec<StreakRule>;108109/// The installed plugins' streak kinds are now `kinds`: sent to each110/// mailbox as it is made and again whenever a plugin is installed,111/// upgraded, or removed (session-8faca4ed/5).112#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]113pub(crate) struct Kinds {114    /// The peer.115    pub(crate) peer: PeerKey,116    /// The streak kinds.117    pub(crate) kinds: StreakKinds,118}119120/// How this incarnation of `peer`'s mailbox began (discussion:owner/679),121/// its first event: `continued` when it was rebuilt from the journal122/// entries of the incarnations before it, else it began empty. The123/// previous process's `notifications.wait`s end here: nobody waits on124/// them any more.125#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]126pub(crate) struct Resumed {127    /// The peer.128    pub(crate) peer: PeerKey,129    /// Whether it resumes the incarnations before it.130    pub(crate) continued: bool,131}132133/// Whether `event`, an incarnation's first, resumes the incarnations134/// before it (discussion:owner/679): only a `Resumed` that says so. Every135/// other first event, one from before `Resumed` too, began empty, so the136/// open's rebuild and `lvcs replay` both start that peer's lineage over137/// at it.138pub(crate) const fn continues(event: &DeliveringEvents) -> bool {139    matches!(140        event,141        DeliveringEvents::Resumed(Resumed {142            continued: true,143            ..144        })145    )146}147148/// `peer`'s key is held here (discussion:owner/439): its inbox takes149/// notifications that name it or whose address matches `patterns`, its150/// interest, which a later `Local` replaces.151#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]152pub(crate) struct Local {153    /// The local peer.154    pub(crate) peer: PeerKey,155    /// Its interest.156    pub(crate) patterns: Vec<String>,157}158159/// `peer`'s key is no longer held here: its inbox takes no more.160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]161pub(crate) struct Gone {162    /// The peer.163    pub(crate) peer: PeerKey,164}165166/// A `notifications.wait` (discussion:owner/424): answered by the first167/// notification of one of `kinds` offered to `peer` ([`InboxOutput::Woke`]).168#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]169pub(crate) struct Wait {170    /// Whom it answers.171    pub(crate) answer: Answer,172    /// The waiting peer.173    pub(crate) peer: PeerKey,174    /// The `notification_kind`s it waits for.175    #[serde(with = "kinds")]176    pub(crate) kinds: Vec<NotificationKind>,177    /// The event kinds it waits for (`<plugin>.<name>`, discussion:owner/515).178    #[serde(default)]179    pub(crate) event_kinds: Vec<String>,180}181182/// A `Vec<NotificationKind>` as its wire strings: lvcs-vocab has no serde.183mod kinds {184    use lvcs_vocab::notification::NotificationKind;185    use serde::{Deserialize as _, Deserializer, Serializer};186187    /// Each kind as its wire string.188    ///189    /// # Errors190    ///191    /// The serializer's.192    pub(super) fn serialize<S: Serializer>(193        kinds: &[NotificationKind],194        serializer: S,195    ) -> Result<S::Ok, S::Error> {196        serializer.collect_seq(197            kinds198                .iter()199                .map(|kind| lvcs_vocab::Vocabulary::as_str(*kind)),200        )201    }202203    /// The kinds the wire strings name.204    ///205    /// # Errors206    ///207    /// The deserializer's, or a custom one for a string no kind has.208    pub(super) fn deserialize<'de, D: Deserializer<'de>>(209        deserializer: D,210    ) -> Result<Vec<NotificationKind>, D::Error> {211        Vec::<String>::deserialize(deserializer)?212            .iter()213            .map(|name| {214                <NotificationKind as lvcs_vocab::Vocabulary>::ALL215                    .iter()216                    .copied()217                    .find(|kind| lvcs_vocab::Vocabulary::as_str(*kind) == name)218                    .ok_or_else(|| {219                        serde::de::Error::custom(format!("no notification_kind is named {name}"))220                    })221            })222            .collect()223    }224}225226/// Whether `peer` has a `notifications.wait` running (discussion:owner/424), for227/// stop_gate's hint: answered by [`InboxOutput::IsWaiting`].228#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]229pub(crate) struct Waiting {230    /// Whom it answers.231    pub(crate) answer: Answer,232    /// The peer.233    pub(crate) peer: PeerKey,234}235236/// The wait `answer` timed out or its caller left: it is answered no237/// more.238#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]239pub(crate) struct Unwait {240    /// Whom the wait answers.241    pub(crate) answer: Answer,242    /// The waiting peer, whose mailbox holds the wait.243    pub(crate) peer: PeerKey,244}245246/// List `peer`'s open check streaks for the request `req`.247#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]248pub(crate) struct Checks {249    /// The request it answers.250    pub(crate) req: RequestId,251    /// The peer.252    pub(crate) peer: PeerKey,253}254255/// What the inbox actor asks the shell to do.256#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]257pub(crate) enum InboxOutput {258    /// The answer to a `List`: the unread `notifications` that fit, and259    /// how many didn't (`omitted`).260    Listed {261        /// Whom it answers.262        answer: Answer,263        /// The unread notifications that fit.264        notifications: Vec<Notification>,265        /// How many unread notifications didn't fit.266        omitted: u32,267        /// The peer's open check streaks, newest first.268        checks: Vec<Notification>,269        /// The ids listed that arrived after the peer's last hinting270        /// `List` (discussion:owner/242).271        fresh: Vec<String>,272    },273    /// The answer to `Checks` `req`: the peer's open check streaks,274    /// newest first.275    Checked {276        /// The request.277        req: RequestId,278        /// The peer.279        peer: PeerKey,280        /// The open streaks.281        checks: Vec<Notification>,282    },283    /// An `action_failed` opened or replaced `peer`'s streak on a284    /// check.285    StreakOpened {286        /// The peer.287        peer: PeerKey,288    },289    /// The answer to a `Waiting`.290    IsWaiting {291        /// Whom it answers.292        answer: Answer,293        /// Whether the peer has a wait running.294        waiting: bool,295    },296    /// A `Wait` is answered by `notification`, offered to its peer.297    Woke {298        /// Whom it answers.299        answer: Answer,300        /// The notification.301        notification: Box<Notification>,302    },303    /// A `Wait` ends unanswered: its peer's key is no longer held here304    /// (secfix/37), so no notification will wake it.305    Unwoken {306        /// Whom it answers.307        answer: Answer,308    },309    /// The answer to a `Read`: the content of each named notification310    /// held, and the ids not held.311    Contents {312        /// Whom it answers.313        answer: Answer,314        /// The content of each named notification held, in order.315        contents: Vec<NotificationContent>,316        /// The ids not held.317        missing: Vec<String>,318    },319    /// The peer's first `Local` came: `events`, held for it, go back on320    /// this mailbox's own queue, in order (discussion:owner/653, rule 2).321    Released {322        /// What was held, oldest first.323        events: Vec<DeliveringEvents>,324    },325    /// `MAILBOX_HELD_MAX` notifications wait for the peer's first `Local`,326    /// so one more was dropped.327    HeldOver,328}