Skip to main content

arachne_runtime/
workspace_activity.rs

1use serde::{Deserialize, Serialize};
2use serde_json::{json, Value};
3
4/// Durable lifecycle phases projected to every adapter.
5#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
6#[serde(rename_all = "snake_case")]
7pub enum Phase {
8    Empty,
9    Creating,
10    Joining,
11    Synchronizing,
12    Active,
13    Recovering,
14    Leaving,
15    Resetting,
16    Removed,
17    Failed,
18}
19
20/// The one restart-safe workspace lifecycle value. Membership and delivery
21/// details remain separate projections; this value only answers where the
22/// workspace operation is and why it stopped.
23#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
24pub struct Activity {
25    pub phase: Phase,
26    pub reason: Option<String>,
27}
28
29impl Default for Activity {
30    fn default() -> Self {
31        Self {
32            phase: Phase::Empty,
33            reason: None,
34        }
35    }
36}
37
38impl Activity {
39    pub(super) fn transition(&mut self, next: Phase, reason: Option<&str>) -> Result<(), String> {
40        if self.phase != next && !legal(self.phase, next) {
41            return Err(format!(
42                "invalid workspace activity transition: {:?} -> {:?}",
43                self.phase, next
44            ));
45        }
46        let reason = reason.map(str::to_owned);
47        if let Some(value) = &reason
48            && (value.is_empty()
49                || value.len() > 64
50                || !value
51                    .bytes()
52                    .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_'))
53        {
54            return Err("workspace activity reason is not a stable code".into());
55        }
56        self.reason = reason;
57        self.phase = next;
58        Ok(())
59    }
60
61    pub(super) fn projection(&self) -> Value {
62        json!({"state": self.phase, "reason": self.reason})
63    }
64}
65
66fn legal(from: Phase, to: Phase) -> bool {
67    matches!(
68        (from, to),
69        (
70            Phase::Empty,
71            Phase::Creating | Phase::Joining | Phase::Active | Phase::Resetting | Phase::Failed
72        ) | (
73            Phase::Creating,
74            Phase::Active | Phase::Failed | Phase::Resetting
75        ) | (
76            Phase::Joining,
77            Phase::Synchronizing | Phase::Failed | Phase::Resetting
78        ) | (
79            Phase::Synchronizing,
80            Phase::Active | Phase::Recovering | Phase::Failed | Phase::Resetting
81        ) | (
82            Phase::Active,
83            Phase::Recovering | Phase::Leaving | Phase::Resetting | Phase::Failed
84        ) | (
85            Phase::Recovering,
86            Phase::Active | Phase::Failed | Phase::Resetting
87        ) | (
88            Phase::Leaving,
89            Phase::Removed | Phase::Failed | Phase::Resetting
90        ) | (Phase::Removed, Phase::Empty | Phase::Resetting)
91            | (
92                Phase::Failed,
93                Phase::Empty
94                    | Phase::Creating
95                    | Phase::Joining
96                    | Phase::Recovering
97                    | Phase::Resetting
98                    | Phase::Failed
99            )
100            | (Phase::Resetting, Phase::Empty | Phase::Failed)
101    )
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn legal_transitions_are_strict_and_idempotent() {
110        let mut activity = Activity::default();
111        activity.transition(Phase::Creating, None).unwrap();
112        assert!(activity.transition(Phase::Active, None).is_ok());
113        let snapshot = activity.clone();
114        assert!(activity.transition(Phase::Joining, None).is_err());
115        assert_eq!(activity, snapshot);
116        activity
117            .transition(Phase::Failed, Some("join_timeout"))
118            .unwrap();
119        activity
120            .transition(Phase::Failed, Some("join_timeout"))
121            .unwrap();
122        assert_eq!(activity.projection()["state"], json!("failed"));
123        assert_eq!(activity.projection()["reason"], json!("join_timeout"));
124    }
125}