solti-model

Domain model for the solti task execution system.

Defines core resource types: Task, TaskSpec, TaskStatus, ObjectMeta, and all supporting domain primitives (phases, policies, selectors, identity newtypes).

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

Task lifecycle

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

Terminal phases: Succeeded, Failed, Timeout, Canceled, Exhausted.

Task kinds

Embedded tasks are submitted directly via SupervisorApi::submit_with_task. Routable variants go through RunnerRouter::pick().

Subprocess has two execution strategies (see SubprocessMode):

• Command: execve(command, args) directly.
• Script: interpreter + script body. The body is base64-encoded, UTF-8, capped at MAX_SCRIPT_BODY_BYTES (2 MiB after decode). Interpreters: Bash, Python, Node, Custom { command, flag }.

Policies

Runner selector

 TaskSpec.runner_selector
 ┌──────────────────────────────────────────────────────┐
 │  match_labels:      { "zone": "eu" }                 │
 │  match_expressions: [ {key:"gpu", op:Exists} ]       │
 └──────────────────────────┬───────────────────────────┘
                            │  ALL requirements ANDed
                            ▼
 RunnerRouter::pick()
 ┌──────────────────────────────────────────────────────┐
 │  Runner A  labels: {"zone":"us","gpu":"a100"}  ✗     │
 │  Runner B  labels: {"zone":"eu","gpu":"h100"}  ✓     │
 │  Runner C  labels: {"zone":"eu"}               ✗     │
 └──────────────────────────────────────────────────────┘

Operators: In, NotIn, Exists, DoesNotExist.

Key types

Size limits

Exposed as pub const so downstream layers (API, CP, UI) share one source of truth.

Identity rules

Slot, TaskId, AgentId allow [A-Za-z0-9._-] only, reject . and ... No whitespace, no path separators, no non-ASCII: these values reach cgroup paths, tempfile names, execve argv, and log fields, where anything else misbehaves. Validation runs at TaskSpec::validate / submit time.

Authentication

Token is the shared bearer secret used in both directions of agent ⇄ control-plane communication:

• agent → CP discovery: the agent presents it (solti-discover);
• CP → agent API: the agent verifies inbound calls against it (solti-api).

One secret per agent enables auth symmetrically from a single config value. It rides in the transport (Authorization: Bearer <token> / gRPC authorization metadata), never in a message body. Debug is redacted; verify() compares in constant time. Orthogonal to TLS - both can be enabled independently.

Construct via Token::new (literal), Token::from_env / Token::from_file (readers), or Token::generate() (fresh 256-bit OS-random, prefixed solti_agt_). generate() performs no persistence - the SDK is a library and does not decide where the secret lives; the agent binary owns that (file, vault, k8s secret). The zero-ops flow lives in the agent: "read from my store; if absent, generate() then persist".

Versioning

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

Construction

let spec = TaskSpec::builder("my-slot", kind, 5_000u64)
    .restart(RestartPolicy::OnFailure)
    .backoff(BackoffPolicy { jitter: JitterPolicy::Equal, first_ms: 1_000, max_ms: 30_000, factor: 2.0 })
    .build()?;

spec.validate()?;  // submit-boundary validation (rejects Embedded)

Error model

 Variant             When
 ───────             ────
 UnknownAdmission    unknown admission policy string
 UnknownRestart      unknown restart policy string
 UnknownJitter       unknown jitter policy string
 UnknownTaskPhase    unknown task phase string
 Invalid             structural validation failure (empty slot, bad backoff, etc.)

Notes

• TaskSpec fields are private — use TaskSpec::builder() for construction and serde for deserialization.
• Deserialization goes through #[serde(try_from = "TaskSpecRaw")] which validates on parse.
• BackoffPolicy is also validated on deserialize via its own try_from raw; zero first_ms, inverted max_ms, or non-finite/<1.0 factor are rejected at parse time.
• Identity newtypes (Slot, TaskId, AgentId) wrap Arc<str> via arc_str_newtype!; environment newtypes (TaskEnv, RunnerEnv) wrap Vec<KeyValue> via env_newtype!. Both macros keep parallel types in lockstep.
• BackoffPolicy implements Eq/Hash via f64::to_bits() for the factor field.
• TaskPhase, RestartPolicy, AdmissionPolicy, JitterPolicy all implement FromStr for CLI/config parsing.
• Labels is backed by BTreeMap<String, String> for deterministic iteration order.
• Most types derive Serialize/Deserialize with camelCase field renaming. The one exception is SelectorOperator, which serializes as PascalCase (In, NotIn, Exists, DoesNotExist) to match the Kubernetes LabelSelectorOperator convention.
• TaskKind, TaskPhase, RestartPolicy, AdmissionPolicy, JitterPolicy, SelectorOperator are #[non_exhaustive] — adding new variants is a non-breaking change.
• Pagination constants for list endpoints: DEFAULT_LIMIT = 100, MAX_LIMIT = 1000 (re-exported as pub const so downstream API layers share one source of truth).