Crate solti_model

Expand description

§solti-model

Domain model for the solti task execution system.

This crate defines the core resource types.

§Architecture

 ┌──────────────────────────────────────────────────────────┐
 │                      Task                                │
 │                                                          │
 │  ObjectMeta            TaskSpec            TaskStatus    │
 │  ├─ id: TaskId         ├─ slot: Slot       ├─ phase      │
 │  ├─ resource_version   ├─ kind: TaskKind   ├─ attempt    │
 │  ├─ created_at         ├─ timeout          ├─ exit_code  │
 │  └─ updated_at         ├─ restart          └─ error      │
 │                        ├─ backoff                        │
 │                        ├─ admission                      │
 │                        ├─ runner_selector                │
 │                        └─ labels                         │
 └──────────────────────────────────────────────────────────┘

§Resource model

Section	Type	Responsibility
metadata	`ObjectMeta`	Identity, versioning, timestamps
status	`TaskStatus`	Observed state: phase, attempt count, exit code, last error
spec	`TaskSpec`	Desired state (private fields; build via `TaskSpec::builder`)

Slot and labels live in spec as the single source of truth. Task provides convenience accessors (Task::slot, Task::labels) that delegate to spec.

§Versioning

ObjectMeta::resource_version is a monotonic counter bumped on every change (spec or status) for optimistic concurrency.

§Task lifecycle

 Pending ──► Running ──► Succeeded
               │
               ├──► Failed ──► (restart) ──► Running
               ├──► Timeout
               ├──► Canceled
               └──► Exhausted (max retries reached)

Terminal phases: Succeeded, Failed, Timeout, Canceled, Exhausted. See TaskPhase::is_terminal.

§Task kinds

TaskKind defines what a task actually runs:

Variant	Description
`Subprocess`	External process (`command`, `args`, `env`, `cwd`)
`Wasm`	WebAssembly module
`Container`	OCI container image
`Embedded`	Code-defined task (in-process `TaskRef`)

Subprocess tasks go through solti_runner::RunnerRouter; Embedded tasks are submitted directly via SupervisorApi::submit_with_task.

§Policies

Policy	Controls
`RestartPolicy`	When to restart: `Never`, `OnFailure`, `Always`
`BackoffPolicy`	Delay between retries: initial, max, factor, jitter
`JitterPolicy`	Jitter strategy: `None`, `Full`, `Equal`, `Decorrelated`
`AdmissionPolicy`	Duplicate handling: `DropIfRunning`, `Replace`, `Queue`

§Construction

TaskSpec fields are private; construct via TaskSpec::builder:

let spec = TaskSpec::builder("my-slot", kind, 5_000u64)
    .restart(RestartPolicy::OnFailure)
    .build()?;

See TaskSpecBuilder for the full API.

§Also

solti-runner consumes TaskSpec and TaskKind to build executable tasks.
solti-core manages Task lifecycle and state transitions.
solti-api serializes/deserializes model types over gRPC and HTTP.

§Domain types

Type	Description
`Slot`	Logical execution lane (newtype over `Arc<str>`)
`TaskId`	Unique task identifier (newtype over `Arc<str>`)
`Timeout`	Per-attempt timeout in milliseconds
`Labels`	Key-value metadata for routing and filtering
`TaskEnv`	Ordered environment variables for task execution
`Flag`	Boolean toggle with `enabled()`/`disabled()` constructors
`TaskQuery`	Builder for filtered, paginated task listing
`TaskPage`	Paginated query result
`TaskSpecBuilder`	Validated builder for `TaskSpec`

§Example

use solti_model::{
    BackoffPolicy, JitterPolicy,
    RestartPolicy, SubprocessMode, SubprocessSpec, Task, TaskKind, TaskPhase, TaskSpec,
};

// 1) Build a task spec via the builder
let spec = TaskSpec::builder(
    "my-worker",
    TaskKind::Subprocess(SubprocessSpec {
        mode: SubprocessMode::Command {
            command: "echo".into(),
            args: vec!["hello".into()],
        },
        env: Default::default(),
        cwd: None,
        fail_on_non_zero: Default::default(),
    }),
    5_000u64,
)
.restart(RestartPolicy::OnFailure)
.backoff(BackoffPolicy {
    jitter: JitterPolicy::Equal,
    first_ms: 1_000,
    max_ms: 30_000,
    factor: 2.0,
})
.build()
.expect("spec should be valid");

// 2) Validate at submit boundary (checks business rules like no Embedded)
spec.validate().expect("spec should pass submit validation");

// 3) Create a task resource (normally done by the supervisor)
let task = Task::new("task-001".into(), spec);
assert_eq!(task.slot(), "my-worker");
assert_eq!(*task.phase(), TaskPhase::Pending);
assert_eq!(task.metadata().resource_version, 1);

Structs§

AgentId: Unique identifier for a solti agent instance.
BackoffPolicy: Exponential backoff configuration for task restart delays.
ContainerSpec: Specification for OCI-compatible container execution.
Flag: Universal boolean flag with explicit enable/disable semantics.
KeyValue: Key–value pair used for environment variables or generic metadata.
Labels: Structured key–value metadata based on BTreeMap.
LabelsIter: Iterator over Labels yielding (&str, &str) pairs.
ObjectMeta: Resource metadata.
RunnerEnv: Environment variables injected by the runner.
RunnerSelector: Label selector for runner routing.
SelectorRequirement: Single set-based requirement for label matching.
Slot: Logical identifier for a controller slot.
SubprocessSpec: Specification for subprocess execution on the host.
Task: Unified task resource.
TaskEnv: Environment variables passed to a task at submission time.
TaskId: Unique identifier for a task instance.
TaskPage: Result of a paginated task query.
TaskQuery: Query parameters for listing tasks with filtering and pagination.
TaskRun: Record of a single task execution attempt.
TaskSpec: Desired state specification.
TaskSpecBuilder: Builder for TaskSpec that validates structural invariants on build.
TaskStatus: Observed runtime state of a task.
Timeout: Timeout value in milliseconds.
WasmSpec: Specification for WebAssembly module execution via a WASI-compatible runtime.

Enums§

AdmissionPolicy: Defines how the controller admits a new task into a slot.
JitterPolicy: Controls how random jitter is applied to backoff delays.
ModelError: Errors produced by domain model validation and construction.
RestartPolicy: Determines whether a task should be automatically restarted after completion or failure.
Runtime: Script interpreter for subprocess script execution.
SelectorOperator: Set-based operator for super::SelectorRequirement.
SubprocessMode: Execution strategy for a subprocess task.
TaskKind: Execution backend for a task.
TaskPhase: Current execution phase of a single task attempt.

Constants§

AGENT_ID_MAX_LEN: Maximum length of an AgentId.
DEFAULT_LIMIT: Default page size when the caller does not specify one.
MAX_LIMIT: Hard cap on page size.
MAX_SCRIPT_BODY_BYTES: Maximum script body size (after base64 decode) accepted by the model.
SLOT_MAX_LEN: Maximum length of a Slot identifier.
TASK_ID_MAX_LEN: Maximum length of a TaskId.

Functions§

merge_env: Merge task and runner environments.

Type Aliases§

ModelResult