ChildSpecBuilder

Language: 中文

One-sentence summary

ChildSpecBuilder is the fluent API for constructing ChildSpec values in Rust code. Configuration and RPC should still use ChildDeclaration. The build exit is build() -> Result<ChildSpec, SupervisorError>, which calls ChildSpec::validate() internally.

Relationship to child-spec.md: that page explains how declarations and specs divide responsibility. This page focuses on builder entry points, setters, and common usage patterns.

Module path

#![allow(unused)]
fn main() {
use rust_supervisor::spec::child_builder::ChildSpecBuilder;
}

The module is defined in src/spec/child_builder.rs. Per project module-boundary rules, there is no pub use re-export.

When to use the builder

Legacy code may still mutate fields after construction. New code should prefer the builder.

Entry methods

Build exit

All entry methods and setters return ChildSpecBuilder, which means construction is still in progress. Only build() consumes the builder and returns the final ChildSpec.

There is no build_validated(). Validation is always performed inside build().

ChildSpec::worker(...) also returns Result<ChildSpec, SupervisorError> via ChildSpecBuilder::worker(...).build().

Basic usage

#![allow(unused)]
fn main() {
use rust_supervisor::error::types::SupervisorError;
use rust_supervisor::id::types::ChildId;
use rust_supervisor::policy::task_role_defaults::TaskRole;
use rust_supervisor::spec::child::TaskKind;
use rust_supervisor::spec::child_builder::ChildSpecBuilder;
use rust_supervisor::task::factory::{TaskResult, service_fn};
use std::sync::Arc;

fn build_worker() -> Result<ChildSpec, SupervisorError> {
    let factory = Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded }));
    ChildSpecBuilder::worker(
        ChildId::new("invoice-worker"),
        "Invoice Worker",
        TaskKind::AsyncWorker,
        factory,
    )
    .task_role(TaskRole::Worker)
    .tag("invoice")
    .build()
}
}

Propagate errors with ?, or use build().expect("...") in tests.

Fluent setter coverage

Each setter consumes self and returns Self. You can chain them in any order that remains semantically valid.

Policy fields: isolation, restart_policy, shutdown_policy, health_policy, readiness_policy, backoff_policy

Topology and classification: dependencies, dependency, tags, tag, criticality, task_role, without_task_role, sidecar_config, without_sidecar_config, severity, without_severity, group, without_group

Config blocks: health_check, without_health_check, readiness, without_readiness, resource_limits, without_resource_limits, command_permissions, environment, env_var, secrets, secret, cleanup_paths, cleanup_path

Runtime: kind, factory, without_factory (for new() or supervisor paths)

Naming convention: plural fields use dependencies(...), tags(...); singular helpers use dependency(...), tag(...). The same pattern applies to environment / env_var, secrets / secret, and cleanup_paths / cleanup_path.

Common combinations

Service

Long-running services should prefer service(...); callers do not need to set TaskRole::Service by hand:

#![allow(unused)]
fn main() {
ChildSpecBuilder::service(id, "API Service", TaskKind::AsyncWorker, factory)
    .tag("service")
    .build()?;
}

Job

Finite work should prefer job(...). You can still override restart_policy for one-shot behavior:

#![allow(unused)]
fn main() {
ChildSpecBuilder::job(id, "Nightly Export", TaskKind::AsyncWorker, factory)
    .restart_policy(RestartPolicy::Temporary)
    .build()?;
}

Sidecar

Sidecars attached to a primary child should prefer sidecar(...). This entry writes sidecar_config and automatically adds the primary child dependency:

#![allow(unused)]
fn main() {
use rust_supervisor::policy::task_role_defaults::SidecarConfig;

ChildSpecBuilder::sidecar(
    id,
    "Metrics Sidecar",
    TaskKind::AsyncWorker,
    factory,
    SidecarConfig::new(primary_id.clone(), false),
)
.build()?;
}

If you still configure task_role = Sidecar manually with setters, you must also set sidecar_config, or build() validation fails.

Worker from new()

#![allow(unused)]
fn main() {
ChildSpecBuilder::new(ChildId::new("custom"), "custom")
    .kind(TaskKind::AsyncWorker)
    .factory(factory)
    .build()?;
}

Data flow (short)

ChildSpecBuilder::worker / service / job / sidecar / supervisor / new
        |
        v
   fluent setters (policy, role, deps, env, ...)
        |
        v
   build()  -->  ChildSpec::validate()
        |
        +-- Ok(ChildSpec)  -->  Supervisor::start / register topology
        +-- Err(SupervisorError)

Example program

Runnable demo:

cargo run --example child_spec_builder

Source: examples/child_spec_builder.rs. Covers worker, service, job, sidecar, supervisor, the new() path, and an intentionally invalid sidecar combination.

Tests and regression

External tests: src/spec/tests/child_builder_test.rs

Run:

cargo test --test child_builder_test

Known boundaries

• Default policy bundles for TryFrom<ChildDeclaration> are not fully shared with the builder yet. The two paths may evolve independently; review both when changing defaults.
• The builder does not handle serde. Dynamic child adds still flow through ChildDeclaration.
• Legacy examples and tests were not bulk-migrated from ChildSpec::worker. Both styles are runtime-equivalent when callers handle Result.

Further reading

• child-spec.md — how ChildDeclaration and ChildSpec relate, plus a short builder introduction
• docs/architecture.md — module boundaries and the no re-export rule