docs/generated/contracts.mdgenerated from code
Reference · 7 min read
inbox
Contracts: inbox.
Read as
Source: crates/lvcs/src/daemon/mailbox.rs.
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}