Skip to main content

muse_code_sdk/
host_death.rs

1//! Host-exit attribution helpers.
2
3use crate::msp::{InitializeResult, SessionDurability};
4
5/// Conservative reading of the host's session durability profile.
6#[derive(Debug, Clone, PartialEq, Eq)]
7#[non_exhaustive]
8pub enum SessionDurabilityProfile {
9    /// Absent and declared `durable` both mean sessions survive host death.
10    Durable,
11    /// The host declared that sessions exist only in process memory.
12    Ephemeral,
13    /// A newer host declared a value this SDK predates.
14    Unrecognized(String),
15}
16
17/// Read `sessionDurability` from the generated handshake result.
18#[must_use]
19pub fn read_session_durability(result: &InitializeResult) -> SessionDurabilityProfile {
20    durability_profile(result.session_durability.as_ref())
21}
22
23pub(crate) fn durability_profile(declared: Option<&SessionDurability>) -> SessionDurabilityProfile {
24    match declared {
25        None | Some(SessionDurability::Durable) => SessionDurabilityProfile::Durable,
26        Some(SessionDurability::Ephemeral) => SessionDurabilityProfile::Ephemeral,
27        Some(SessionDurability::Unknown(value)) => {
28            SessionDurabilityProfile::Unrecognized(value.clone())
29        }
30    }
31}
32
33/// Only a durable profile promises that sessions survive an abnormal host death.
34#[must_use]
35pub const fn survives_host_death(profile: &SessionDurabilityProfile) -> bool {
36    matches!(profile, SessionDurabilityProfile::Durable)
37}
38
39/// The client-side observation that the host stopped serving the session.
40#[derive(Debug, Clone, PartialEq, Eq)]
41#[non_exhaustive]
42pub enum HostDeathNotification {
43    /// Orderly shutdown: the host had the chance to write session-end records.
44    CleanShutdown,
45    /// The transport reached EOF after the caller ruled out a client-owned close.
46    ///
47    /// Raw EOF must first pass through [`attribute_transport_eof`]; constructing
48    /// this variant for an own-close EOF would contradict that attribution.
49    TransportEof,
50    /// Any process exit other than clean shutdown.
51    AbnormalExit,
52}
53
54/// Whether this already-attributed observation means no orderly session end was written.
55#[must_use]
56pub fn is_abnormal_host_death(notification: &HostDeathNotification) -> bool {
57    !matches!(notification, HostDeathNotification::CleanShutdown)
58}
59
60/// Whether a close was ours, harmless, reattachable, or destructive.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62#[non_exhaustive]
63pub enum HostCloseAttribution {
64    /// EOF followed a close initiated by this client.
65    Ours,
66    /// The host process exited cleanly after completing its drain.
67    CleanHostExit,
68    /// A durable host died; live waits fail, but the session may be reattached.
69    DurableHostDeath,
70    /// A non-durable or unknown-profile host died; the session is discarded.
71    DiscardedHostDeath,
72}
73
74impl HostCloseAttribution {
75    /// Whether this is a durable host death, after which the session may be
76    /// reattached on a new transport.
77    #[must_use]
78    pub const fn may_reattach(self) -> bool {
79        matches!(self, Self::DurableHostDeath)
80    }
81
82    /// Whether the host died, durable or not.
83    #[must_use]
84    pub const fn is_host_death(self) -> bool {
85        matches!(self, Self::DurableHostDeath | Self::DiscardedHostDeath)
86    }
87}
88
89/// Attribute transport EOF at the layer that knows whether `close()` was ours.
90#[must_use]
91pub fn attribute_transport_eof(
92    profile: &SessionDurabilityProfile,
93    client_closing: bool,
94) -> HostCloseAttribution {
95    if client_closing {
96        HostCloseAttribution::Ours
97    } else {
98        death_for(profile)
99    }
100}
101
102/// Attribute a classified process exit.
103///
104/// A client-requested close does not suppress an abnormal process exit: a
105/// close escalation can still kill or crash the host. The caller therefore
106/// supplies only the spawn layer's `cleanShutdown` classification here.
107#[must_use]
108pub fn attribute_process_exit(
109    profile: &SessionDurabilityProfile,
110    clean_shutdown: bool,
111) -> HostCloseAttribution {
112    if clean_shutdown {
113        HostCloseAttribution::CleanHostExit
114    } else {
115        death_for(profile)
116    }
117}
118
119const fn death_for(profile: &SessionDurabilityProfile) -> HostCloseAttribution {
120    if survives_host_death(profile) {
121        HostCloseAttribution::DurableHostDeath
122    } else {
123        HostCloseAttribution::DiscardedHostDeath
124    }
125}