solti-exec 0.0.2

Solti SDK jobs execution crate.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

//! # Task: resolved subprocess configuration.
//!
//! [`SubprocessTaskConfig`] is the **fully resolved** config passed to the subprocess spawn loop.
//! It is produced by [`SubprocessRunner::build_task_config`] from a [`TaskSpec`](solti_model::TaskSpec) + [`BuildContext`](solti_runner::BuildContext).
//!
//! ## How it fits
//! ```text
//! TaskSpec (model)
//!     │
//!     ├──► SubprocessRunner::build_task_config()
//!     │     ├──► resolve SubprocessMode → (command, args)
//!     │     ├──► merge_env(task_env, runner_env)
//!     │     └──► generate run_id
//!     │
//!     └──► SubprocessTaskConfig (this struct)
//!           ├──► validate(): command not empty
//!           └──► passed to run_subprocess() for execution
//! ```
//!
//! ## Fields
//!
//! | Field              | Source                    | Description                          |
//! |--------------------|---------------------------|--------------------------------------|
//! | `run_id`           | generated by runner       | unique execution identifier          |
//! | `command`          | `SubprocessMode`          | OS command to exec                   |
//! | `args`             | `SubprocessMode`          | command-line arguments               |
//! | `env`              | `merge_env(task, runner)` | merged environment variables         |
//! | `cwd`              | `SubprocessSpec`          | working directory (`None` = inherit) |
//! | `fail_on_non_zero` | `SubprocessSpec`          | treat non-zero exit as failure       |

use std::{collections::BTreeMap, fmt, path::PathBuf, sync::Arc};

use solti_model::Flag;

use crate::ExecError;

/// Subprocess configuration - fully resolved per-task parameters.
///
/// ## Also
///
/// - [`SubprocessRunner`](super::SubprocessRunner) produces this config in `build_task`.
/// - [`SubprocessBackendConfig`](super::SubprocessBackendConfig) runner-level settings applied at spawn.
#[derive(Debug, Clone)]
pub struct SubprocessTaskConfig {
    /// End-to-End log identifier.
    pub(crate) run_id: Arc<str>,
    /// Raw sequence number from run id generation (used for cgroup naming).
    pub(crate) seq: u64,
    /// Command to execute (e.g. `"ls"`, `"/usr/bin/python"`).
    pub(crate) command: String,
    /// Command-line arguments passed to the command.
    pub(crate) args: Vec<String>,
    /// Merged environment (runner overrides task). Ready for `Command::envs()`.
    pub(crate) env: BTreeMap<String, String>,
    /// Working directory for the subprocess.
    ///
    /// If `None`, the subprocess inherits the parent process working directory.
    pub(crate) cwd: Option<PathBuf>,
    /// Whether non-zero exit codes should be treated as task failures.
    pub(crate) fail_on_non_zero: Flag,
}

impl SubprocessTaskConfig {
    /// Validate the configuration before spawning a subprocess.
    ///
    /// Rules:
    /// - `command` is not empty or whitespace-only.
    pub fn validate(&self) -> Result<(), ExecError> {
        if self.command.trim().is_empty() {
            return Err(ExecError::InvalidSpec("Subprocess command is empty".into()));
        }
        Ok(())
    }
}

impl fmt::Display for SubprocessTaskConfig {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "SubprocessTaskConfig(cmd='{}', args={}, env={}, cwd={:?}, fail_on_non_zero={})",
            self.command,
            self.args.len(),
            self.env.len(),
            self.cwd,
            self.fail_on_non_zero.is_enabled(),
        )
    }
}