rust_supervisor/role/result/
supervisor.rs

1//! Supervisor role result and error values.
2//!
3//! Supervisor role errors preserve the child identifier and lifecycle phase
4//! before the adapter maps them into task failures.
5
6use crate::error::types::{SupervisorError, TaskFailure, TaskFailureKind};
7use crate::id::types::ChildId;
8use crate::policy::task_role_defaults::TaskRole;
9use crate::role::lifecycle::RoleLifecyclePhase;
10use thiserror::Error;
11
12/// Result returned by supervisor role lifecycle methods.
13pub type SupervisorResult<T = ()> = Result<T, SupervisorRoleError>;
14
15/// Structured error returned by a supervisor role.
16#[derive(Debug, Clone, PartialEq, Eq, Error)]
17#[error("supervisor role failed during {phase:?}: {message}")]
18pub struct SupervisorRoleError {
19    /// Stable child identifier for the failed supervisor role.
20    pub child_id: ChildId,
21    /// Lifecycle phase where the supervisor role failed.
22    pub phase: RoleLifecyclePhase,
23    /// Human-readable diagnostic message.
24    pub message: String,
25}
26
27impl SupervisorRoleError {
28    /// Creates a supervisor role error.
29    ///
30    /// # Arguments
31    ///
32    /// - `child_id`: Stable child identifier for the failed supervisor role.
33    /// - `phase`: Lifecycle phase where the supervisor role failed.
34    /// - `message`: Diagnostic message for operators.
35    ///
36    /// # Returns
37    ///
38    /// Returns a structured [`SupervisorRoleError`] value.
39    ///
40    /// # Examples
41    ///
42    /// ```
43    /// let error = rust_supervisor::role::result::supervisor::SupervisorRoleError::new(
44    ///     rust_supervisor::id::types::ChildId::new("nested-supervisor"),
45    ///     rust_supervisor::role::lifecycle::RoleLifecyclePhase::BuildTree,
46    ///     "nested tree could not be built",
47    /// );
48    /// assert_eq!(error.phase.as_str(), "build_tree");
49    /// ```
50    pub fn new(child_id: ChildId, phase: RoleLifecyclePhase, message: impl Into<String>) -> Self {
51        Self {
52            child_id,
53            phase,
54            message: message.into(),
55        }
56    }
57
58    /// Creates a supervisor role error from a runtime supervisor error.
59    ///
60    /// # Arguments
61    ///
62    /// - `child_id`: Stable child identifier for the failed supervisor role.
63    /// - `phase`: Lifecycle phase that observed the runtime error.
64    /// - `error`: Runtime supervisor error returned by the nested supervisor.
65    ///
66    /// # Returns
67    ///
68    /// Returns a structured [`SupervisorRoleError`] value with the runtime
69    /// error rendered into its diagnostic message.
70    pub fn from_supervisor_error(
71        child_id: ChildId,
72        phase: RoleLifecyclePhase,
73        error: SupervisorError,
74    ) -> Self {
75        Self::new(child_id, phase, error.to_string())
76    }
77
78    /// Converts this supervisor role error into a runtime task failure.
79    ///
80    /// # Arguments
81    ///
82    /// This function has no arguments.
83    ///
84    /// # Returns
85    ///
86    /// Returns a [`TaskFailure`] value consumed by the runtime policy pipeline.
87    pub fn into_task_failure(self) -> TaskFailure {
88        TaskFailure::new(
89            TaskFailureKind::Error,
90            format!("{}_{}", TaskRole::Supervisor.as_str(), self.phase.as_str()),
91            format!(
92                "supervisor role child={} phase={} failed: {}",
93                self.child_id,
94                self.phase.as_str(),
95                self.message
96            ),
97        )
98    }
99}
rust_supervisor/role/result/supervisor.rs

rust_supervisor/role/result/
supervisor.rs
