Tighten control command audit validation

- Reject empty audit fields in public control entrypoints and runtime loops

- Add control command audit tests and update manual guidance

Author: developerworks

README.zh.md

@@ -30,6 +30,7 @@
 - 使用 `OneForOne`(一对一), `OneForAll`(一对全部) 和 `RestForOne`(后续一组) supervision strategy(监督策略).
 - 从 typed failure(类型化失败), backoff(退避), jitter(抖动), fuse rule(熔断规则) 和 policy engine(策略引擎) 生成 `RestartDecision`(重启决策).
 - 通过 `SupervisorHandle`(监督器句柄) 控制运行中的树, 包括 `add_child`, `remove_child`, `restart_child`, `pause_child`, `resume_child`, `quarantine_child`, `shutdown_tree`, `current_state` 和 `subscribe_events`.
+- 控制命令必须携带非空 `requested_by`(请求者) 和 `reason`(原因), 公共控制入口和 runtime control loop(运行时控制循环) 都会在执行前校验审计字段.
 - 从 `examples/config/supervisor.yaml` 加载主 YAML(数据序列化格式) 配置.
 - 复用 `rust_supervisor::config::configurable::SupervisorConfig` 完成 YAML(数据序列化格式) 加载, template generation(模板生成) 和 JSON Schema(JSON 结构模式) 生成.
 - 发出 structured log(结构化日志), tracing span(追踪跨度), metrics(指标), audit event(审计事件), event journal entry(事件日志条目) 和 `RunSummary`(运行摘要) diagnostics(诊断信息).

manual/en/dashboard.md

@@ -10,7 +10,7 @@ The screenshot below shows the dashboard client view for target lists, topology,
 
 ## Three-End Responsibilities
 
-- `rust-supervisor`: The target process reads `SupervisorConfig`, opens a Unix domain socket when `ipc.enabled=true`, and produces snapshots, event records, log records, command results, and registration heartbeats.
+- `rust-supervisor`: The target process reads `SupervisorConfig`, opens a Unix domain socket when `ipc.enabled=true`, and produces state, event records, log records, command results, and registration heartbeats.
 - `rust-supervisor-relay`: The relay listens on the registration socket, stores the target registry, exposes external `wss://` dashboard sessions, validates mTLS and allowed IPC path prefixes, and forwards session commands to the target process.
 - `rust-supervisor-ui`: The dashboard client connects to the relay through `wss://` and displays the target list, topology, state, event stream, log tail, and command audit.
 

manual/zh/dashboard.md

@@ -10,7 +10,7 @@ dashboard(看板) 功能由三个仓库共同完成. `rust-supervisor` 只负责
 
 ## 三端职责
 
-- `rust-supervisor`: target process(目标进程) 读取 `SupervisorConfig`(监督器配置), 在 `ipc.enabled=true` 时打开 Unix domain socket(Unix 域套接字), 并生成 snapshot(快照), event record(事件记录), log record(日志记录), command result(命令结果) 和 registration heartbeat(注册心跳).
+- `rust-supervisor`: target process(目标进程) 读取 `SupervisorConfig`(监督器配置), 在 `ipc.enabled=true` 时打开 Unix domain socket(Unix 域套接字), 并生成 state(状态), event record(事件记录), log record(日志记录), command result(命令结果) 和 registration heartbeat(注册心跳).
 - `rust-supervisor-relay`: relay(中继) 监听 registration socket(注册套接字), 保存 target registry(目标注册表), 对外提供 `wss://` dashboard session(看板会话), 校验 mTLS(双向传输层安全协议认证) 和 allowed IPC path prefix(允许的进程间通信路径前缀), 并把会话命令转发到 target process(目标进程).
 - `rust-supervisor-ui`: dashboard client(看板客户端) 通过 `wss://` 连接 relay(中继), 显示 target list(目标列表), topology(拓扑), state(状态), event stream(事件流), log tail(日志尾部) 和 command audit(命令审计).
 

manual/zh/runtime-control.md

@@ -29,3 +29,5 @@
 ## 审计数据
 
 每个控制命令都带有 `requested_by`(请求者), `reason`(原因), `target_path`(目标路径), `accepted_at`(接受时间)和 `command_id`(命令标识). 这些字段用于 audit event(审计事件)和问题追踪.
+
+`requested_by`(请求者) 和 `reason`(原因) 必须提供非空文本. `SupervisorHandle`(监督器句柄) 会在命令进入 channel(通道) 前拒绝空值, runtime control loop(运行时控制循环) 也会在执行命令前再次校验. 这样做可以保证人工操作, dashboard IPC(看板进程间通信) 转发和内部控制调用都留下可追踪的审计来源.

src/control/command.rs

@@ -3,6 +3,7 @@
 //! This module owns auditable command inputs and command results. Runtime code
 //! executes these commands and records state changes.
 
+use crate::error::types::SupervisorError;
 use crate::id::types::{ChildId, SupervisorPath};
 use crate::shutdown::coordinator::ShutdownResult;
 use serde::{Deserialize, Serialize};
@@ -75,6 +76,20 @@ impl CommandMeta {
             reason: reason.into(),
         }
     }
+
+    /// Validates audit metadata before command dispatch.
+    ///
+    /// # Arguments
+    ///
+    /// This function has no arguments.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` when actor and reason fields are non-empty.
+    pub(crate) fn validate(&self) -> Result<(), SupervisorError> {
+        validate_required_text(&self.requested_by, "requested_by")?;
+        validate_required_text(&self.reason, "reason")
+    }
 }
 
 /// Runtime command sent to the control loop.
@@ -158,6 +173,38 @@ impl ControlCommand {
             | Self::CurrentState { meta } => meta,
         }
     }
+
+    /// Validates audit metadata attached to this command.
+    ///
+    /// # Arguments
+    ///
+    /// This function has no arguments.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` when the command carries auditable metadata.
+    pub(crate) fn validate_audit_metadata(&self) -> Result<(), SupervisorError> {
+        self.meta().validate()
+    }
+}
+
+/// Validates one required text field.
+///
+/// # Arguments
+///
+/// - `value`: Text value supplied by the command caller.
+/// - `field`: Field name used in the diagnostic message.
+///
+/// # Returns
+///
+/// Returns `Ok(())` when the value is not blank.
+fn validate_required_text(value: &str, field: &str) -> Result<(), SupervisorError> {
+    if value.trim().is_empty() {
+        return Err(SupervisorError::InvalidTransition {
+            message: format!("control command {field} must not be empty"),
+        });
+    }
+    Ok(())
 }
 
 /// State assigned to a managed child by the control loop.

src/control/handle.rs

@@ -263,6 +263,7 @@ impl SupervisorHandle {
     ///
     /// Returns a command result or a supervisor error when the runtime is gone.
     async fn send(&self, command: ControlCommand) -> Result<CommandResult, SupervisorError> {
+        command.validate_audit_metadata()?;
         let (reply_sender, reply_receiver) = oneshot::channel();
         self.command_sender
             .send(RuntimeCommand::Control {

src/runtime/control_loop.rs

@@ -133,6 +133,7 @@ impl RuntimeControlState {
         &mut self,
         command: ControlCommand,
     ) -> Result<CommandResult, SupervisorError> {
+        command.validate_audit_metadata()?;
         match command {
             ControlCommand::AddChild { child_manifest, .. } => {
                 self.ensure_dynamic_child_allowed()?;

src/tests/supervisor_control_test.rs

@@ -3,6 +3,7 @@
 //! These tests verify idempotent command handling through the public handle.
 
 use rust_supervisor::control::command::{CommandResult, ManagedChildState};
+use rust_supervisor::error::types::SupervisorError;
 use rust_supervisor::id::types::{ChildId, SupervisorPath};
 use rust_supervisor::runtime::supervisor::Supervisor;
 use rust_supervisor::spec::supervisor::SupervisorSpec;
@@ -50,3 +51,30 @@ async fn control_commands_update_child_state() {
         }
     ));
 }
+
+/// Verifies that control commands require auditable metadata.
+#[tokio::test]
+async fn control_commands_reject_empty_audit_metadata() {
+    let handle = Supervisor::start(SupervisorSpec::root(Vec::new()))
+        .await
+        .expect("start supervisor");
+    let child_id = ChildId::new("worker");
+
+    let missing_actor = handle
+        .pause_child(child_id, " ", "maintenance window")
+        .await;
+    assert_invalid_transition(missing_actor, "requested_by");
+
+    let missing_reason = handle.shutdown_tree("operator", "\t").await;
+    assert_invalid_transition(missing_reason, "reason");
+}
+
+/// Asserts that a command returned the expected invalid transition field.
+fn assert_invalid_transition(result: Result<CommandResult, SupervisorError>, expected_field: &str) {
+    match result {
+        Err(SupervisorError::InvalidTransition { message }) => {
+            assert!(message.contains(expected_field), "{message}");
+        }
+        other => panic!("unexpected command result: {other:?}"),
+    }
+}