Wire up service example, generate_supervisor binary, and manual updates for 006-6

- Add service_task example with lifecycle observation and supervisor tree patterns
- Add generate_supervisor bin to produce SupervisorSpec from YAML template
- Update child_declaration spec with resource_limits and command_permissions fields
- Update configurable.rs, control_loop, and runtime context for dynamic children
- Sync en/zh manuals: configuration, runtime-control, supervisor-tree, policies
- Fix dashboard error naming and Cargo dependency metadata

Author: developerworks

.gitignore

@@ -13,3 +13,4 @@ Thumbs.db
 *.swp
 .vscode/
 .idea/
+/config

Cargo.lock

@@ -33,11 +33,12 @@ name = "rust_supervisor"
 path = "src/lib.rs"
 
 [dependencies]
+clap = { version = "4.6.1", features = ["derive"] }
 confique = { version = "0.4.0", features = ["yaml"] }
 libc = "0.2"
 metrics = "0.24"
 rand = "0.10"
-rust-config-tree = "0.1.9"
+rust-config-tree = "0.2.0"
 schemars = { version = "1", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

Cargo.toml

@@ -1,42 +1,97 @@
+# Configuration file shape loaded from YAML.
+
+# Additional configuration files included by `rust-config-tree`.
+#
+# Default value: []
+#include: []
+
+# Optional target-side dashboard IPC configuration.
+#ipc:
+
+# Child declarations loaded from YAML children array.
+#
+# Default value: []
+#children: []
+
+# Root supervisor declaration values.
 supervisor:
-  strategy: OneForAll
+  # Restart scope strategy for child failures.
+  #
+  # Required! This value must be specified.
+  #strategy:
+
+# Runtime policy values.
 policy:
-  child_restart_limit: 10
-  child_restart_window_ms: 60000
-  supervisor_failure_limit: 30
-  supervisor_failure_window_ms: 60000
-  initial_backoff_ms: 100
-  max_backoff_ms: 5000
-  jitter_ratio: 0.10
-  heartbeat_interval_ms: 1000
-  stale_after_ms: 3000
-  # restart_budget:                          # 可选, 重启预算限流 (本切片新增)
-  #   window_secs: 60                        # 滑动窗口, 默认 60s
-  #   max_burst: 10                          # 窗口内最大突发故障次数, 默认 10
-  #   recovery_rate_per_sec: 0.5             # 每秒令牌恢复速率, 默认 0.5
-  # group_strategies:                        # 可选, 分组策略 (本切片新增)
-  #   - name: "group-a"
-  #     children: ["child-1", "child-2"]
-  #     budget:
-  #       window_secs: 120
-  #       max_burst: 20
-  #       recovery_rate_per_sec: 1.0
+  # Maximum child restarts within the child restart window.
+  #
+  # Required! This value must be specified.
+  #child_restart_limit:
+
+  # Child restart window in milliseconds.
+  #
+  # Required! This value must be specified.
+  #child_restart_window_ms:
+
+  # Maximum supervisor failures within the supervisor failure window.
+  #
+  # Required! This value must be specified.
+  #supervisor_failure_limit:
+
+  # Supervisor failure window in milliseconds.
+  #
+  # Required! This value must be specified.
+  #supervisor_failure_window_ms:
+
+  # Initial backoff in milliseconds.
+  #
+  # Required! This value must be specified.
+  #initial_backoff_ms:
+
+  # Maximum backoff in milliseconds.
+  #
+  # Required! This value must be specified.
+  #max_backoff_ms:
+
+  # Jitter ratio expressed as a fraction between zero and one.
+  #
+  # Required! This value must be specified.
+  #jitter_ratio:
+
+  # Heartbeat interval in milliseconds.
+  #
+  # Required! This value must be specified.
+  #heartbeat_interval_ms:
+
+  # Stale heartbeat threshold in milliseconds.
+  #
+  # Required! This value must be specified.
+  #stale_after_ms:
+
+# Shutdown budget values.
 shutdown:
-  graceful_timeout_ms: 5000
-  abort_wait_ms: 1000
+  # Graceful drain timeout in milliseconds.
+  #
+  # Required! This value must be specified.
+  #graceful_timeout_ms:
+
+  # Abort wait timeout in milliseconds.
+  #
+  # Required! This value must be specified.
+  #abort_wait_ms:
+
+# Observability switches and capacities.
 observability:
-  event_journal_capacity: 256
-  metrics_enabled: true
-  audit_enabled: true
-ipc:
-  enabled: false
-  target_id: example-target
-  path: /tmp/rust-supervisor-demo/example-target.sock
-  permissions: "0600"
-  bind_mode: replace_stale
-  registration:
-    enabled: false
-    relay_registration_path: /tmp/rust-supervisor-demo/dashboard-relay-registration.sock
-    display_name: "example target"
-    lease_seconds: 30
-    registration_heartbeat_interval_seconds: 15
+  # Event journal capacity.
+  #
+  # Required! This value must be specified.
+  #event_journal_capacity:
+
+  # Whether metrics recording is enabled.
+  #
+  # Required! This value must be specified.
+  #metrics_enabled:
+
+  # Whether command audit recording is enabled.
+  #
+  # Required! This value must be specified.
+  #audit_enabled:

examples/config/supervisor.template.yaml

@@ -13,9 +13,9 @@ use rust_supervisor::runtime::supervisor::Supervisor;
 type ExampleResult = Result<(), rust_supervisor::error::types::SupervisorError>;
 
 // Use the Tokio runtime for the asynchronous example.
-#[tokio::main]
 // Return typed supervisor errors from the example.
-/// Runs the runtime control story example.
+// Runs the runtime control story example.
+#[tokio::main]
 async fn main() -> ExampleResult {
     // Load centralized YAML configuration.
     let state = load_config_from_yaml_file("examples/config/supervisor.yaml")?;

examples/runtime_control_story.rs

@@ -0,0 +1,44 @@
+# Service Role Example
+
+[中文说明](README.zh.md)
+
+This example shows a supervised `WorkRole::Service` child. A service role is a long-running task that should stay online, report readiness, emit heartbeats, and stop cooperatively when the supervisor shuts down.
+
+Run it with:
+
+```bash
+cargo run --package rust-tokio-supervisor --example service
+```
+
+The process keeps running until you press `Ctrl+C`. The signal is treated as the operator stop request, then the example calls `shutdown_tree` and prints the graceful shutdown outcome.
+
+## What It Shows
+
+- Initialization: `service_task.rs` builds a `quote-service` child and marks it as ready.
+- Running: the service prints the current UNIX time once per second, then emits heartbeat and running tick facts.
+- Observation: `observation.rs` prints periodic `current_state`, runtime event text, and shutdown report data.
+- Stop: after `Ctrl+C`, `main.rs` calls `shutdown_tree`, cancellation reaches the service, and the service returns `TaskResult::Cancelled`.
+
+## File Layout
+
+- `main.rs`: wires the supervisor, event subscriptions, state snapshots, and shutdown command.
+- `service_task.rs`: declares the `WorkRole::Service` child and the async service body.
+- `observation.rs`: prints service facts, runtime events, current state records, and shutdown outcomes.
+
+## Expected Output Shape
+
+The output should include these stages:
+
+```text
+service initialization: initialized child=quote-service path=/quote-service
+state after-initialization: child_count=1 shutdown_completed=false
+service example: running until Ctrl+C
+service business: child=quote-service tick=... now_unix=...
+service while-running: running child=quote-service tick=...
+operator signal=ctrl_c
+service during-stop: stopping child=quote-service
+shutdown outcome: child=quote-service status=Graceful phase=GracefulDrain cancel_delivered=true
+state after-shutdown: child_count=1 shutdown_completed=true
+```
+
+The important behavior is that the service does not exit by itself. It stays active while running, reports readiness and heartbeat status through `current_state`, receives cancellation only after the operator signal, and finishes as a graceful child shutdown outcome.

examples/service/README.md

@@ -0,0 +1,44 @@
+# Service(常驻服务) 角色示例
+
+[English README](README.md)
+
+这个示例展示一个被 supervisor(监督器) 管理的 `WorkRole::Service`(工作角色: 常驻服务) 子任务. Service(常驻服务) 角色表示长期在线的任务, 它应该完成初始化, 报告 readiness(就绪状态), 发出 heartbeat(心跳), 并在 supervisor(监督器) 关闭时协作停止.
+
+运行命令:
+
+```bash
+cargo run --package rust-tokio-supervisor --example service
+```
+
+进程会一直运行, 直到你按下 `Ctrl+C`. 这个信号会被当成 operator stop request(操作员停止请求), 然后示例调用 `shutdown_tree`(关闭监督树), 并输出 graceful shutdown outcome(优雅关闭结果).
+
+## 示例展示内容
+
+- 初始化: `service_task.rs` 构建 `quote-service` 子任务, 并调用 `mark_ready()` 报告 readiness(就绪状态).
+- 运行: service(常驻服务) 每秒输出一次当前 UNIX time(UNIX 时间), 然后发出 heartbeat(心跳) 和 running tick(运行周期) 事实.
+- 观测: `observation.rs` 周期性输出 `current_state`(当前状态), runtime event text(运行时事件文本) 和 shutdown report(关闭报告).
+- 停止: 按下 `Ctrl+C` 后, `main.rs` 调用 `shutdown_tree`(关闭监督树), cancellation(取消信号) 到达 service(常驻服务), service(常驻服务) 返回 `TaskResult::Cancelled`(任务已取消).
+
+## 文件结构
+
+- `main.rs`: 组合 supervisor(监督器), event subscription(事件订阅), state snapshot(状态快照) 和 shutdown command(关闭命令).
+- `service_task.rs`: 声明 `WorkRole::Service`(工作角色: 常驻服务) 子任务, 并实现 async service body(异步服务主体).
+- `observation.rs`: 输出 service fact(服务事实), runtime event(运行时事件), current state record(当前状态记录) 和 shutdown outcome(关闭结果).
+
+## 预期输出形态
+
+输出应该包含这些阶段:
+
+```text
+service initialization: initialized child=quote-service path=/quote-service
+state after-initialization: child_count=1 shutdown_completed=false
+service example: running until Ctrl+C
+service business: child=quote-service tick=... now_unix=...
+service while-running: running child=quote-service tick=...
+operator signal=ctrl_c
+service during-stop: stopping child=quote-service
+shutdown outcome: child=quote-service status=Graceful phase=GracefulDrain cancel_delivered=true
+state after-shutdown: child_count=1 shutdown_completed=true
+```
+
+关键行为是: service(常驻服务) 不会自己退出. 它在运行期保持 active(活跃), 通过 `current_state`(当前状态) 暴露 readiness(就绪状态) 和 heartbeat(心跳) 状态, 只在收到 operator signal(操作员信号) 后进入关闭阶段并收到 cancellation(取消信号), 最后形成 graceful child shutdown outcome(优雅子任务关闭结果).

examples/service/README.zh.md

@@ -0,0 +1,99 @@
+//! Demonstrates a supervised service role with initialization, running,
+//! cooperative stop, and observation output.
+
+mod observation;
+mod service_task;
+
+// Import command result variants returned by the runtime handle.
+use rust_supervisor::control::command::CommandResult;
+// Import supervisor error values.
+use rust_supervisor::error::types::SupervisorError;
+// Import the supervisor runtime entry point.
+use rust_supervisor::runtime::supervisor::Supervisor;
+// Import supervisor specification values.
+use rust_supervisor::spec::supervisor::SupervisorSpec;
+// Import shutdown timing policy.
+use rust_supervisor::shutdown::stage::ShutdownPolicy;
+// Import duration values for the example timing budget.
+use std::time::Duration;
+// Import asynchronous channel helpers.
+use tokio::sync::mpsc;
+
+// Define the shared example result type.
+type ExampleResult = Result<(), rust_supervisor::error::types::SupervisorError>;
+
+// Use the Tokio runtime for the asynchronous example.
+#[tokio::main]
+// Return typed supervisor errors from the example.
+/// Runs the service role example.
+async fn main() -> ExampleResult {
+    // Build a channel that receives service lifecycle facts.
+    let (service_event_sender, mut service_events) = mpsc::unbounded_channel();
+    // Build one child declared as a service role.
+    let service_child = service_task::service_child(service_event_sender);
+    // Build a root supervisor with the service child.
+    let mut spec = SupervisorSpec::root(vec![service_child]);
+    // Keep enough event buffer for the full shutdown observation sequence.
+    spec.event_channel_capacity = 32;
+    // Use short shutdown windows so the example finishes quickly.
+    let shutdown_policy =
+        ShutdownPolicy::new(Duration::from_millis(250), Duration::from_millis(50), true);
+    // Start the runtime with the service child.
+    let handle = Supervisor::start_with_policy(spec, shutdown_policy).await?;
+    // Subscribe to lifecycle event text before commands are sent.
+    let mut runtime_events = handle.subscribe_events();
+    // Wait until the service reports initialization.
+    observation::wait_for_initialization(&mut service_events).await;
+    // Print the state after the service has initialized.
+    observation::print_current_state("after-initialization", handle.current_state().await?);
+    // Print the long-running operation hint.
+    println!("service example: running until Ctrl+C");
+    // Build periodic observation ticks for the long-running service.
+    let mut observation_interval = tokio::time::interval(Duration::from_secs(1));
+    // Keep the service running until the operator requests shutdown.
+    loop {
+        // Wait for either an operator signal or the next observation tick.
+        tokio::select! {
+            // Stop the example only when the operator sends Ctrl+C.
+            signal = tokio::signal::ctrl_c() => {
+                // Convert signal errors into the example error type.
+                signal.map_err(|error| {
+                    SupervisorError::fatal_config(format!(
+                        "failed to receive Ctrl+C signal: {error}"
+                    ))
+                })?;
+                // Print the operator stop signal.
+                println!("operator signal=ctrl_c");
+                // Leave the persistent running loop.
+                break;
+            }
+            // Print periodic service observation.
+            _ = observation_interval.tick() => {
+                // Print service facts emitted while the service is running.
+                observation::drain_service_events("while-running", &mut service_events);
+                // Print the current runtime state.
+                observation::print_current_state("while-running", handle.current_state().await?);
+                // Print relevant runtime events that arrived during the tick.
+                observation::drain_runtime_events(&mut runtime_events);
+            }
+        }
+    }
+    // Request cooperative shutdown for the whole supervisor tree.
+    let shutdown = handle
+        .shutdown_tree("operator", "service role example stopped by operator")
+        .await?;
+    // Print service facts emitted during cooperative stop.
+    observation::drain_service_events("during-stop", &mut service_events);
+    // Print runtime events that show command and shutdown observation.
+    observation::drain_runtime_events(&mut runtime_events);
+    // Print the shutdown result and per-child outcome.
+    if let CommandResult::Shutdown { result } = shutdown {
+        // Print the completed shutdown phase.
+        observation::print_shutdown_result(result);
+    }
+    // Print the state after shutdown has completed.
+    observation::print_current_state("after-shutdown", handle.current_state().await?);
+    // Finish the example successfully.
+    Ok(())
+    // End the service role example.
+}