rust_supervisor/runtime/
message.rs

1//! Runtime loop mailbox messages.
2//!
3//! This module separates externally requested control commands from internal
4//! child-child_start_count and control-plane messages that share the same runtime loop
5//! mailbox.
6
7use crate::child_runner::runner::{ChildRunHandle, ChildRunReport};
8use crate::control::command::{CommandMeta, CommandResult, ControlCommand};
9use crate::error::types::SupervisorError;
10use crate::id::types::{ChildId, ChildStartCount, Generation, SupervisorPath};
11use crate::runtime::lifecycle::RuntimeExitReport;
12use tokio::sync::oneshot;
13
14/// Message consumed by the runtime control loop mailbox.
15#[derive(Debug)]
16pub enum RuntimeLoopMessage {
17    /// Control command sent from [`crate::control::handle::SupervisorHandle`].
18    Control {
19        /// Command to execute.
20        command: ControlCommand,
21        /// Reply channel used to return the command result.
22        reply_sender: oneshot::Sender<Result<CommandResult, SupervisorError>>,
23    },
24    /// Message emitted by a child child_start_count task.
25    ChildStart(ChildStartMessage),
26    /// Message that controls the runtime control plane itself.
27    ControlPlane(ControlPlaneMessage),
28}
29
30/// Message emitted after a child child_start_count changes runtime state.
31#[derive(Debug)]
32pub enum ChildStartMessage {
33    /// Child child_start_count finished and must be evaluated by runtime policy.
34    Exited {
35        /// Report returned by the child runner.
36        report: Box<ChildRunReport>,
37    },
38    /// Delayed backoff spawn succeeded; control loop must activate runtime bookkeeping before awaiting completion.
39    DelayedSpawnAttached {
40        /// Stable child identifier for the spawned attempt.
41        child_id: ChildId,
42        /// Supervisor path segment ordering for observability correlation.
43        path: SupervisorPath,
44        /// Generation identity pinned by [`crate::registry::entry::ChildRuntime`] before `spawn_once`.
45        generation: Generation,
46        /// Attempt counter pinned by [`crate::registry::entry::ChildRuntime`] before `spawn_once`.
47        attempt: ChildStartCount,
48        /// Runner handle carrying cancellation and completion endpoints for the active attempt.
49        handle: ChildRunHandle,
50    },
51    /// Child child_start_count could not start.
52    StartFailed {
53        /// Child identifier whose child_start_count failed before execution.
54        child_id: ChildId,
55        /// Diagnostic message for the failed child_start_count.
56        message: String,
57    },
58}
59
60/// Message that controls the runtime control plane task.
61#[derive(Debug)]
62pub enum ControlPlaneMessage {
63    /// Request to stop the runtime control plane itself.
64    Shutdown {
65        /// Audit metadata for the shutdown request.
66        meta: CommandMeta,
67        /// Reply channel used to confirm shutdown acceptance.
68        reply_sender: oneshot::Sender<Result<RuntimeExitReport, SupervisorError>>,
69    },
70    /// Replays a synthetic exit report for integration tests exercising stale completions.
71    ReplayChildExitForTest {
72        /// Exit payload synthesized by tests.
73        report: Box<ChildRunReport>,
74    },
75}
rust_supervisor/runtime/message.rs

rust_supervisor/runtime/
message.rs
