nucleus-container 0.2.0

Extremely lightweight Docker alternative for agents and production services — isolated execution using cgroups, namespaces, seccomp, Landlock, and gVisor
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

use crate::error::StateTransition;

/// Cgroup lifecycle state machine matching Nucleus_Resources_CgroupLifecycle.tla
///
/// State transitions:
/// nonexistent -> created -> configured -> attached -> monitoring -> removed
///
/// Properties verified by TLA+ model:
/// - resource_limits_enforced: Once configured, can only move to attached, monitoring, or removed
/// - cleanup_guaranteed: Eventually reaches removed state
/// - no_resource_leak: Removed state is terminal and stable
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CgroupState {
    /// Initial state - cgroup doesn't exist
    Nonexistent,
    /// Cgroup created in filesystem
    Created,
    /// Resource limits configured
    Configured,
    /// Process attached to cgroup
    Attached,
    /// Monitoring resource usage
    Monitoring,
    /// Cgroup removed - terminal state
    Removed,
}

impl StateTransition for CgroupState {
    fn can_transition_to(&self, next: &CgroupState) -> bool {
        use CgroupState::*;

        matches!(
            (self, next),
            (Nonexistent, Created)
                | (Created, Configured)
                | (Configured, Attached)
                | (Attached, Monitoring)
                | (Monitoring, Removed)
                // Cleanup paths
                | (Created, Removed)
                | (Configured, Removed)
                | (Attached, Removed)
                // Stuttering
                | (Nonexistent, Nonexistent)
                | (Created, Created)
                | (Configured, Configured)
                | (Attached, Attached)
                | (Monitoring, Monitoring)
                | (Removed, Removed)
        )
    }

    fn is_terminal(&self) -> bool {
        matches!(self, CgroupState::Removed)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_valid_transitions() {
        assert!(CgroupState::Nonexistent.can_transition_to(&CgroupState::Created));
        assert!(CgroupState::Created.can_transition_to(&CgroupState::Configured));
        assert!(CgroupState::Configured.can_transition_to(&CgroupState::Attached));
        assert!(CgroupState::Attached.can_transition_to(&CgroupState::Monitoring));
        assert!(CgroupState::Monitoring.can_transition_to(&CgroupState::Removed));
    }

    #[test]
    fn test_error_paths() {
        // Can cleanup from Created or Configured on error
        assert!(CgroupState::Created.can_transition_to(&CgroupState::Removed));
        assert!(CgroupState::Configured.can_transition_to(&CgroupState::Removed));
    }

    #[test]
    fn test_invalid_transitions() {
        // Cannot skip states
        assert!(!CgroupState::Nonexistent.can_transition_to(&CgroupState::Configured));
        assert!(!CgroupState::Created.can_transition_to(&CgroupState::Attached));

        // Cannot go backwards
        assert!(!CgroupState::Configured.can_transition_to(&CgroupState::Created));
        assert!(!CgroupState::Removed.can_transition_to(&CgroupState::Monitoring));
    }

    #[test]
    fn test_terminal_state() {
        assert!(!CgroupState::Nonexistent.is_terminal());
        assert!(!CgroupState::Created.is_terminal());
        assert!(!CgroupState::Configured.is_terminal());
        assert!(!CgroupState::Attached.is_terminal());
        assert!(!CgroupState::Monitoring.is_terminal());
        assert!(CgroupState::Removed.is_terminal());
    }
}