Skip to main content

zombienet_configuration/
custom_process.rs

1use std::{
2    collections::HashSet,
3    error::Error,
4    marker::PhantomData,
5    path::{Component, Path, PathBuf},
6};
7
8use serde::{Deserialize, Serialize};
9
10use crate::{
11    shared::{
12        errors::FieldError,
13        helpers::{ensure_value_is_not_empty, merge_errors, sanitize_node_name},
14        macros::states,
15        node::EnvVar,
16        resources::{Resources, ResourcesBuilder},
17    },
18    types::{Arg, Command, Image, Port, TransferedFile},
19    utils::is_false,
20};
21
22states! {
23    WithName,
24    WithOutName
25}
26
27states! {
28    WithCmd,
29    WithOutCmd
30}
31
32pub trait Cmd {}
33impl Cmd for WithOutCmd {}
34impl Cmd for WithCmd {}
35
36/// A port a custom process listens on, by name.
37///
38/// The name is what the port is exposed under (a k8s `Service` port, the key
39/// the running process reports its addresses by), so it has to be a valid
40/// service name: 1 to 15 lowercase letters, digits or `-`, with a letter in
41/// it. `port` is the number the process listens on; `0` lets zombienet pick a
42/// free one at spawn time, handed to the process through
43/// `{{ZOMBIE:<process>:port_<name>}}` in its args or env.
44#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
45pub struct NamedPort {
46    pub name: String,
47    pub port: Port,
48}
49
50/// k8s' rule for a named port (IANA_SVC_NAME), which is the strictest of the
51/// places a port name ends up.
52fn validate_port_name(name: &str) -> Result<(), anyhow::Error> {
53    if name.is_empty() || name.len() > 15 {
54        return Err(anyhow::anyhow!(
55            "port name '{name}' must be 1 to 15 characters long"
56        ));
57    }
58    if !name
59        .chars()
60        .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-')
61    {
62        return Err(anyhow::anyhow!(
63            "port name '{name}' may only contain lowercase letters, digits and '-'"
64        ));
65    }
66    if !name.chars().any(|c| c.is_ascii_lowercase()) {
67        return Err(anyhow::anyhow!(
68            "port name '{name}' must contain at least one letter"
69        ));
70    }
71    if name.starts_with('-') || name.ends_with('-') || name.contains("--") {
72        return Err(anyhow::anyhow!(
73            "port name '{name}' may not start or end with '-' or contain '--'"
74        ));
75    }
76    Ok(())
77}
78
79/// An environment variable of a custom process: a literal `value`, or on
80/// kubernetes a key of a `Secret` in the namespace, read by the pod itself.
81#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
82pub struct ProcessEnvVar {
83    pub name: String,
84    #[serde(flatten)]
85    pub value: EnvValue,
86}
87
88/// The written shape of a [`ProcessEnvVar`], `{ name, value }` or
89/// `{ name, secret = { name, key } }`, read loosely so that the check for
90/// exactly one of the two can name the variable.
91#[derive(Deserialize)]
92struct RawProcessEnvVar {
93    name: String,
94    value: Option<String>,
95    secret: Option<SecretRef>,
96}
97
98#[derive(Deserialize)]
99struct SecretRef {
100    name: String,
101    key: String,
102}
103
104impl<'de> Deserialize<'de> for ProcessEnvVar {
105    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
106        let raw = RawProcessEnvVar::deserialize(deserializer)?;
107        let value = match (raw.value, raw.secret) {
108            (Some(value), None) => EnvValue::Value(value),
109            (None, Some(SecretRef { name, key })) => EnvValue::Secret { name, key },
110            _ => {
111                return Err(serde::de::Error::custom(format!(
112                    "env '{}' needs exactly one of `value` or `secret`",
113                    raw.name
114                )))
115            },
116        };
117        Ok(Self {
118            name: raw.name,
119            value,
120        })
121    }
122}
123
124/// Where a [`ProcessEnvVar`] gets its value.
125#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
126#[serde(rename_all = "lowercase")]
127pub enum EnvValue {
128    /// The text as given, `{{ZOMBIE:..}}` placeholders resolved.
129    Value(String),
130    /// The `key` of the kubernetes `Secret` named `name`, as a pod's
131    /// `valueFrom.secretKeyRef`; rejected on the other providers.
132    Secret { name: String, key: String },
133}
134
135impl ProcessEnvVar {
136    /// A variable set to the `key` of the kubernetes `Secret` named `secret`.
137    pub fn from_secret(
138        name: impl Into<String>,
139        secret: impl Into<String>,
140        key: impl Into<String>,
141    ) -> Self {
142        Self {
143            name: name.into(),
144            value: EnvValue::Secret {
145                name: secret.into(),
146                key: key.into(),
147            },
148        }
149    }
150}
151
152impl From<(&str, &str)> for ProcessEnvVar {
153    fn from(pair: (&str, &str)) -> Self {
154        EnvVar::from(pair).into()
155    }
156}
157
158impl From<EnvVar> for ProcessEnvVar {
159    fn from(var: EnvVar) -> Self {
160        Self {
161            name: var.name,
162            value: EnvValue::Value(var.value),
163        }
164    }
165}
166
167/// How a custom process is known to be ready. `tcp` is a declared port name
168/// that must accept a connection; `http` is a declared port name and a path
169/// that must answer 2xx. On kubernetes the check is the pod's readiness
170/// probe; elsewhere zombienet probes the port from where it runs. How long
171/// to wait is the process's `timeout`.
172#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
173pub struct ReadyCheck {
174    #[serde(flatten)]
175    pub target: ReadyTarget,
176    /// Seconds between two attempts.
177    #[serde(default = "one", skip_serializing_if = "is_one")]
178    pub interval: u32,
179}
180
181/// What a [`ReadyCheck`] probes, by declared port name.
182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "lowercase")]
184pub enum ReadyTarget {
185    /// The named port accepts a TCP connection.
186    Tcp(String),
187    /// `GET <path>` on the named port answers 2xx.
188    Http { port: String, path: String },
189}
190
191impl ReadyTarget {
192    /// The name of the port the check probes.
193    pub fn port_name(&self) -> &str {
194        match self {
195            Self::Tcp(port) | Self::Http { port, .. } => port,
196        }
197    }
198
199    /// The path a `GET` must answer 2xx on; `None` for a TCP connect.
200    pub fn http_path(&self) -> Option<&str> {
201        match self {
202            Self::Tcp(_) => None,
203            Self::Http { path, .. } => Some(path),
204        }
205    }
206}
207
208fn one() -> u32 {
209    1
210}
211
212fn is_one(value: &u32) -> bool {
213    *value == 1
214}
215
216impl ReadyCheck {
217    /// A check that passes once the port named `port` accepts a connection.
218    pub fn tcp(port: impl Into<String>) -> Self {
219        Self {
220            target: ReadyTarget::Tcp(port.into()),
221            interval: 1,
222        }
223    }
224
225    /// A check that passes once `GET <path>` on the port named `port` answers 2xx.
226    pub fn http(port: impl Into<String>, path: impl Into<String>) -> Self {
227        Self {
228            target: ReadyTarget::Http {
229                port: port.into(),
230                path: path.into(),
231            },
232            interval: 1,
233        }
234    }
235
236    pub fn with_interval(mut self, secs: u32) -> Self {
237        self.interval = secs;
238        self
239    }
240
241    /// The name of the port the check probes.
242    pub fn port_name(&self) -> &str {
243        self.target.port_name()
244    }
245}
246
247/// When a dependency counts as met, as docker-compose names them.
248#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
249#[serde(rename_all = "snake_case")]
250pub enum DependencyCondition {
251    /// The process started.
252    ServiceStarted,
253    /// The process passed its ready check.
254    ServiceHealthy,
255    /// The one-shot process exited 0.
256    ServiceCompletedSuccessfully,
257}
258
259impl DependencyCondition {
260    pub fn as_str(&self) -> &'static str {
261        match self {
262            Self::ServiceStarted => "service_started",
263            Self::ServiceHealthy => "service_healthy",
264            Self::ServiceCompletedSuccessfully => "service_completed_successfully",
265        }
266    }
267}
268
269/// Another custom process this one starts after. Written as a bare name
270/// (`"postgres"`) or as `{ name = "init", condition = "..." }`; without a
271/// condition the target's natural one applies, see
272/// [`CustomProcess::natural_condition`].
273#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
274#[serde(from = "DependencyRepr", into = "DependencyRepr")]
275pub struct Dependency {
276    pub name: String,
277    pub condition: Option<DependencyCondition>,
278}
279
280#[derive(Serialize, Deserialize)]
281#[serde(untagged)]
282enum DependencyRepr {
283    Name(String),
284    Full {
285        name: String,
286        #[serde(default, skip_serializing_if = "Option::is_none")]
287        condition: Option<DependencyCondition>,
288    },
289}
290
291impl From<DependencyRepr> for Dependency {
292    fn from(repr: DependencyRepr) -> Self {
293        match repr {
294            DependencyRepr::Name(name) => Self {
295                name,
296                condition: None,
297            },
298            DependencyRepr::Full { name, condition } => Self { name, condition },
299        }
300    }
301}
302
303impl From<Dependency> for DependencyRepr {
304    fn from(dep: Dependency) -> Self {
305        match dep.condition {
306            None => Self::Name(dep.name),
307            Some(condition) => Self::Full {
308                name: dep.name,
309                condition: Some(condition),
310            },
311        }
312    }
313}
314
315impl Dependency {
316    /// The condition this dependency means on `target`: the one named, or
317    /// the target's natural one.
318    pub fn condition_on(&self, target: &CustomProcess) -> DependencyCondition {
319        self.condition.unwrap_or_else(|| target.natural_condition())
320    }
321}
322
323impl From<&str> for Dependency {
324    fn from(name: &str) -> Self {
325        Self {
326            name: name.into(),
327            condition: None,
328        }
329    }
330}
331
332/// The longest `timeout` accepted: a week, in seconds.
333pub const MAX_TIMEOUT_SECS: u32 = 7 * 24 * 60 * 60;
334
335/// A custom process to spawn next to the nodes: its `command`, `args`, `env`,
336/// `injected_files`, `image` (provider specific), named `ports`, `resources`
337/// (provider specific), and its lifecycle: `ready_check`, `depends_on`,
338/// `one_shot` and `timeout`.
339#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
340pub struct CustomProcess {
341    // Name of the process
342    name: String,
343    // Image to use
344    #[serde(skip_serializing_if = "Option::is_none")]
345    image: Option<Image>,
346    // Command to execute
347    command: Command,
348    // Arguments to pass
349    #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
350    args: Vec<Arg>,
351    // Environment to set
352    #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
353    env: Vec<ProcessEnvVar>,
354    // Files put in place before the process starts
355    #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
356    injected_files: Vec<TransferedFile>,
357    // Named ports the process listens on
358    #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
359    ports: Vec<NamedPort>,
360    // Resources to apply (only k8s)
361    #[serde(skip_serializing_if = "Option::is_none")]
362    resources: Option<Resources>,
363    // How the process is known to be ready
364    #[serde(skip_serializing_if = "Option::is_none")]
365    ready_check: Option<ReadyCheck>,
366    // Processes this one starts after
367    #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
368    depends_on: Vec<Dependency>,
369    // Runs to completion instead of staying up
370    #[serde(skip_serializing_if = "is_false", default)]
371    one_shot: bool,
372    // Seconds to wait for the condition: the ready check, or a one-shot's exit
373    #[serde(skip_serializing_if = "Option::is_none")]
374    timeout: Option<u32>,
375}
376
377impl Default for CustomProcess {
378    fn default() -> Self {
379        Self {
380            name: "".into(),
381            image: None,
382            command: Command::default(), // should be changed.
383            args: vec![],
384            env: vec![],
385            injected_files: vec![],
386            ports: vec![],
387            resources: None,
388            ready_check: None,
389            depends_on: vec![],
390            one_shot: false,
391            timeout: None,
392        }
393    }
394}
395
396impl CustomProcess {
397    /// Node name.
398    pub fn name(&self) -> &str {
399        &self.name
400    }
401
402    /// Image to run (only podman/k8s).
403    pub fn image(&self) -> Option<&Image> {
404        self.image.as_ref()
405    }
406
407    /// Command to run the node.
408    pub fn command(&self) -> &Command {
409        &self.command
410    }
411
412    /// Arguments to use for node.
413    pub fn args(&self) -> Vec<&Arg> {
414        self.args.iter().collect()
415    }
416
417    /// Environment variables to set (inside pod for podman/k8s, inside shell for native).
418    pub fn env(&self) -> &[ProcessEnvVar] {
419        &self.env
420    }
421
422    /// Files put in place before the process starts.
423    pub fn injected_files(&self) -> &[TransferedFile] {
424        &self.injected_files
425    }
426
427    /// Named ports the process listens on.
428    pub fn ports(&self) -> &[NamedPort] {
429        &self.ports
430    }
431
432    /// Resources to apply to the process (only k8s).
433    pub fn resources(&self) -> Option<&Resources> {
434        self.resources.as_ref()
435    }
436
437    /// How the process is known to be ready, if declared. Without one, a
438    /// process with ports is ready when its first port accepts a connection,
439    /// and a process without ports is ready once started.
440    pub fn ready_check(&self) -> Option<&ReadyCheck> {
441        self.ready_check.as_ref()
442    }
443
444    /// The processes this one starts after.
445    pub fn depends_on(&self) -> &[Dependency] {
446        &self.depends_on
447    }
448
449    /// Whether the process runs to completion (exit 0 is success) instead of
450    /// staying up.
451    pub fn one_shot(&self) -> bool {
452        self.one_shot
453    }
454
455    /// Seconds to wait for the process to meet its condition (the ready check
456    /// to pass, or a one-shot to exit); the global `node_spawn_timeout` when
457    /// absent.
458    pub fn timeout(&self) -> Option<u32> {
459        self.timeout
460    }
461
462    /// What the process is waited on: the `ready_check`, or a TCP connect on
463    /// the first declared port when there is none. `None` for a one-shot
464    /// (waited on to exit) and for a process with nothing to check (ready
465    /// once started).
466    pub fn effective_check(&self) -> Option<ReadyTarget> {
467        if self.one_shot {
468            return None;
469        }
470        match &self.ready_check {
471            Some(check) => Some(check.target.clone()),
472            None => self.ports.first().map(|p| ReadyTarget::Tcp(p.name.clone())),
473        }
474    }
475
476    /// The condition a dependency on this process means when it names none:
477    /// completed for a one-shot, healthy when there is something to check,
478    /// started otherwise.
479    pub fn natural_condition(&self) -> DependencyCondition {
480        if self.one_shot {
481            DependencyCondition::ServiceCompletedSuccessfully
482        } else if self.effective_check().is_some() {
483            DependencyCondition::ServiceHealthy
484        } else {
485            DependencyCondition::ServiceStarted
486        }
487    }
488
489    fn validate_env(&self, errors: &mut Vec<anyhow::Error>) {
490        let mut env_names = HashSet::new();
491        for var in &self.env {
492            if var.name.is_empty() {
493                errors.push(FieldError::Env(anyhow::anyhow!("a variable has no name")).into());
494            } else if !env_names.insert(&var.name) {
495                errors
496                    .push(FieldError::Env(anyhow::anyhow!("'{}' is given twice", var.name)).into());
497            }
498            if let EnvValue::Secret { name, key } = &var.value {
499                if name.is_empty() || key.is_empty() {
500                    errors.push(
501                        FieldError::Env(anyhow::anyhow!(
502                            "'{}' needs the secret's name and key",
503                            var.name
504                        ))
505                        .into(),
506                    );
507                }
508            }
509        }
510    }
511
512    fn validate_injected_files(&self, errors: &mut Vec<anyhow::Error>) {
513        let mut remote_paths: Vec<&Path> = vec![];
514        for file in &self.injected_files {
515            if file.local_path.as_os_str().is_empty() {
516                errors.push(
517                    FieldError::InjectedFiles(anyhow::anyhow!("a file has no local_path")).into(),
518                );
519            }
520            // The text is what every provider gets, so it has to be the one
521            // spelling of the path: a trailing slash, `.` and `//` fold away
522            // in the components, `..` would leave the process's directory and
523            // `:` splits a docker mount.
524            let remote = file.remote_path.to_string_lossy();
525            let plain: PathBuf = file.remote_path.components().collect();
526            if !file.remote_path.is_absolute()
527                || remote.contains(':')
528                || plain.file_name().is_none()
529                || plain.as_os_str() != file.remote_path.as_os_str()
530                || file
531                    .remote_path
532                    .components()
533                    .any(|c| c == Component::ParentDir)
534            {
535                errors.push(
536                    FieldError::InjectedFiles(anyhow::anyhow!(
537                        "remote_path '{remote}' must be an absolute path to a file, without '.', '..', '//' or ':'"
538                    ))
539                    .into(),
540                );
541            } else if let Some(other) = remote_paths
542                .iter()
543                .find(|p| p.starts_with(&file.remote_path) || file.remote_path.starts_with(p))
544            {
545                let error = if *other == file.remote_path {
546                    anyhow::anyhow!("remote_path '{remote}' is given twice")
547                } else {
548                    anyhow::anyhow!(
549                        "remote_paths '{}' and '{remote}' cannot both be files",
550                        other.display()
551                    )
552                };
553                errors.push(FieldError::InjectedFiles(error).into());
554            } else {
555                remote_paths.push(&file.remote_path);
556            }
557            let mode = &file.mode;
558            let octal =
559                (3..=4).contains(&mode.len()) && mode.chars().all(|c| ('0'..='7').contains(&c));
560            // a volume takes no more than the permission bits
561            if !octal || u32::from_str_radix(mode, 8).is_ok_and(|mode| mode > 0o777) {
562                errors.push(
563                    FieldError::InjectedFiles(anyhow::anyhow!(
564                        "mode '{mode}' must be 3 or 4 octal digits up to 0777, e.g. '0755'"
565                    ))
566                    .into(),
567                );
568            }
569        }
570    }
571
572    /// The field rules shared by the builder and the TOML loader. What is
573    /// checked at spawn follows from them, see [`Self::effective_check`].
574    pub fn validate(&self) -> Result<(), Vec<anyhow::Error>> {
575        let mut errors = vec![];
576        let valid_name = sanitize_node_name(&self.name);
577        if self.name.is_empty() {
578            errors.push(FieldError::Name(anyhow::anyhow!("can't be empty")).into());
579        } else if valid_name != self.name {
580            errors.push(
581                FieldError::Name(anyhow::anyhow!(
582                    "'{}' must be lowercase letters, digits and '-', starting with a letter and at most 63 characters (e.g. '{valid_name}')",
583                    self.name
584                ))
585                .into(),
586            );
587        }
588        let mut names: Vec<&str> = vec![];
589        let mut numbers: Vec<Port> = vec![];
590        for port in &self.ports {
591            if let Err(e) = validate_port_name(&port.name) {
592                errors.push(FieldError::Ports(e).into());
593            }
594            if names.contains(&port.name.as_str()) {
595                errors.push(
596                    FieldError::Ports(anyhow::anyhow!(
597                        "port name '{}' is declared twice",
598                        port.name
599                    ))
600                    .into(),
601                );
602            }
603            if port.port != 0 && numbers.contains(&port.port) {
604                errors.push(
605                    FieldError::Ports(anyhow::anyhow!(
606                        "port {} is declared twice (as '{}')",
607                        port.port,
608                        port.name
609                    ))
610                    .into(),
611                );
612            }
613            names.push(&port.name);
614            numbers.push(port.port);
615        }
616
617        if let Some(check) = &self.ready_check {
618            if !names.contains(&check.port_name()) {
619                errors.push(
620                    FieldError::ReadyCheck(anyhow::anyhow!(
621                        "port '{}' is not declared in ports",
622                        check.port_name()
623                    ))
624                    .into(),
625                );
626            }
627            if self.one_shot {
628                errors.push(
629                    FieldError::ReadyCheck(anyhow::anyhow!(
630                        "a one-shot process runs to completion, it has no readiness"
631                    ))
632                    .into(),
633                );
634            }
635            if let Some(path) = check.target.http_path() {
636                if !path.starts_with('/') {
637                    errors.push(
638                        FieldError::ReadyCheck(anyhow::anyhow!(
639                            "http path '{path}' must start with '/'"
640                        ))
641                        .into(),
642                    );
643                }
644            }
645        }
646        self.validate_env(&mut errors);
647        self.validate_injected_files(&mut errors);
648        if self.ready_check.as_ref().is_some_and(|c| c.interval == 0) {
649            errors.push(
650                FieldError::ReadyCheck(anyhow::anyhow!("interval must be at least 1 second"))
651                    .into(),
652            );
653        }
654        match self.timeout {
655            Some(0) => errors
656                .push(FieldError::Timeout(anyhow::anyhow!("must be at least 1 second")).into()),
657            Some(secs) if secs > MAX_TIMEOUT_SECS => errors.push(
658                FieldError::Timeout(anyhow::anyhow!(
659                    "{secs} is more than the {MAX_TIMEOUT_SECS} seconds (a week) allowed"
660                ))
661                .into(),
662            ),
663            _ => {},
664        }
665        let mut seen: Vec<&str> = vec![];
666        for dep in &self.depends_on {
667            if dep.name == self.name {
668                errors.push(
669                    FieldError::DependsOn(anyhow::anyhow!("'{}' depends on itself", dep.name))
670                        .into(),
671                );
672            }
673            if seen.contains(&dep.name.as_str()) {
674                errors.push(
675                    FieldError::DependsOn(anyhow::anyhow!("'{}' is listed twice", dep.name)).into(),
676                );
677            }
678            seen.push(&dep.name);
679        }
680
681        if errors.is_empty() {
682            Ok(())
683        } else {
684            Err(errors)
685        }
686    }
687}
688
689/// The rules between processes, applied once the whole set is known: every
690/// dependency names a custom process, its condition fits the target (only a
691/// one-shot completes, only a process with something to check is healthy),
692/// and there is no cycle. Errors are prefixed with the process they are on.
693pub(crate) fn validate_custom_processes(processes: &[CustomProcess]) -> Result<(), Vec<String>> {
694    let by_name: std::collections::HashMap<&str, &CustomProcess> =
695        processes.iter().map(|p| (p.name(), p)).collect();
696    let mut errors = vec![];
697
698    for process in processes {
699        for dep in &process.depends_on {
700            let Some(target) = by_name.get(dep.name.as_str()) else {
701                errors.push(format!(
702                    "custom_processes['{}'].depends_on: '{}' is not a custom process",
703                    process.name(),
704                    dep.name
705                ));
706                continue;
707            };
708            let condition = dep.condition_on(target);
709            let fits = match condition {
710                DependencyCondition::ServiceStarted => true,
711                DependencyCondition::ServiceHealthy => target.effective_check().is_some(),
712                DependencyCondition::ServiceCompletedSuccessfully => target.one_shot,
713            };
714            if !fits {
715                errors.push(format!(
716                    "custom_processes['{}'].depends_on: '{}' cannot be {} ({})",
717                    process.name(),
718                    dep.name,
719                    condition.as_str(),
720                    if target.one_shot {
721                        "it is a one-shot, which completes"
722                    } else if condition == DependencyCondition::ServiceHealthy {
723                        "it has no ready_check and no port"
724                    } else {
725                        "it is not a one-shot"
726                    }
727                ));
728            }
729        }
730    }
731
732    // A cycle: some process never becomes startable. Peel off the ones whose
733    // dependencies are all peeled; what is left is on a cycle.
734    let mut remaining: Vec<&CustomProcess> = processes.iter().collect();
735    let mut peeled: Vec<&str> = vec![];
736    loop {
737        let (free, blocked): (Vec<&CustomProcess>, Vec<&CustomProcess>) =
738            remaining.iter().partition(|p| {
739                p.depends_on.iter().all(|d| {
740                    peeled.contains(&d.name.as_str()) || !by_name.contains_key(d.name.as_str())
741                })
742            });
743        if free.is_empty() {
744            break;
745        }
746        peeled.extend(free.iter().map(|p| p.name()));
747        remaining = blocked;
748    }
749    if !remaining.is_empty() {
750        let mut names: Vec<&str> = remaining.iter().map(|p| p.name()).collect();
751        names.sort();
752        errors.push(format!(
753            "custom_processes: depends_on forms a cycle among {}",
754            names.join(", ")
755        ));
756    }
757
758    if errors.is_empty() {
759        Ok(())
760    } else {
761        Err(errors)
762    }
763}
764
765/// A custom process builder, used to build a [`CustomProcess`] declaratively with fields validation.
766pub struct CustomProcessBuilder<N, C> {
767    config: CustomProcess,
768    errors: Vec<anyhow::Error>,
769    _state_name: PhantomData<N>,
770    _state_cmd: PhantomData<C>,
771}
772
773impl Default for CustomProcessBuilder<WithOutName, WithOutCmd> {
774    fn default() -> Self {
775        Self {
776            config: CustomProcess::default(),
777            errors: vec![],
778            _state_name: PhantomData,
779            _state_cmd: PhantomData,
780        }
781    }
782}
783
784impl<A, B> CustomProcessBuilder<A, B> {
785    fn transition<C, D>(
786        config: CustomProcess,
787        errors: Vec<anyhow::Error>,
788    ) -> CustomProcessBuilder<C, D> {
789        CustomProcessBuilder {
790            config,
791            errors,
792            _state_name: PhantomData,
793            _state_cmd: PhantomData,
794        }
795    }
796}
797
798impl CustomProcessBuilder<WithOutName, WithOutCmd> {
799    pub fn new() -> CustomProcessBuilder<WithOutName, WithOutCmd> {
800        CustomProcessBuilder::default()
801    }
802}
803
804impl<C: Cmd> CustomProcessBuilder<WithOutName, C> {
805    /// set the name of the process.
806    pub fn with_name<T: Into<String> + Copy>(self, name: T) -> CustomProcessBuilder<WithName, C> {
807        let name: String = name.into();
808
809        match ensure_value_is_not_empty(&name) {
810            Ok(_) => Self::transition(
811                CustomProcess {
812                    name,
813                    ..self.config
814                },
815                self.errors,
816            ),
817            Err(e) => Self::transition(
818                CustomProcess {
819                    // we still set the name in error case to display error path
820                    name,
821                    ..self.config
822                },
823                merge_errors(self.errors, FieldError::Name(e).into()),
824            ),
825        }
826    }
827}
828
829impl CustomProcessBuilder<WithName, WithOutCmd> {
830    /// Set the command that will be executed to spawn the process.
831    pub fn with_command<T>(self, command: T) -> CustomProcessBuilder<WithName, WithCmd>
832    where
833        T: TryInto<Command>,
834        T::Error: Error + Send + Sync + 'static,
835    {
836        match command.try_into() {
837            Ok(command) => Self::transition(
838                CustomProcess {
839                    command,
840                    ..self.config
841                },
842                self.errors,
843            ),
844            Err(error) => Self::transition(
845                self.config,
846                merge_errors(self.errors, FieldError::Command(error.into()).into()),
847            ),
848        }
849    }
850}
851
852impl CustomProcessBuilder<WithName, WithCmd> {
853    /// Set the image that will be used for the node (only podman/k8s).
854    pub fn with_image<T>(self, image: T) -> Self
855    where
856        T: TryInto<Image>,
857        T::Error: Error + Send + Sync + 'static,
858    {
859        match image.try_into() {
860            Ok(image) => Self::transition(
861                CustomProcess {
862                    image: Some(image),
863                    ..self.config
864                },
865                self.errors,
866            ),
867            Err(error) => Self::transition(
868                self.config,
869                merge_errors(self.errors, FieldError::Image(error.into()).into()),
870            ),
871        }
872    }
873
874    /// Set the arguments that will be used when spawn the process.
875    pub fn with_args(self, args: Vec<Arg>) -> Self {
876        Self::transition(
877            CustomProcess {
878                args,
879                ..self.config
880            },
881            self.errors,
882        )
883    }
884
885    /// Set the environment variables of the process: `(name, value)` pairs,
886    /// or a [`ProcessEnvVar`] read from a kubernetes `Secret`.
887    pub fn with_env(self, env: Vec<impl Into<ProcessEnvVar>>) -> Self {
888        let env = env.into_iter().map(|var| var.into()).collect::<Vec<_>>();
889
890        Self::transition(CustomProcess { env, ..self.config }, self.errors)
891    }
892
893    /// Put a file in place before the process starts; see [`TransferedFile`].
894    pub fn with_injected_file(self, file: TransferedFile) -> Self {
895        let mut injected_files = self.config.injected_files;
896        injected_files.push(file);
897
898        Self::transition(
899            CustomProcess {
900                injected_files,
901                ..self.config
902            },
903            self.errors,
904        )
905    }
906
907    /// Declare a named port the process listens on; `0` lets zombienet pick a
908    /// free one at spawn time. Names and numbers are checked in [`Self::build`].
909    pub fn with_named_port(self, name: impl Into<String>, port: Port) -> Self {
910        let mut ports = self.config.ports;
911        ports.push(NamedPort {
912            name: name.into(),
913            port,
914        });
915
916        Self::transition(
917            CustomProcess {
918                ports,
919                ..self.config
920            },
921            self.errors,
922        )
923    }
924
925    /// Declare how the process is known to be ready; see [`ReadyCheck`].
926    pub fn with_ready_check(self, check: ReadyCheck) -> Self {
927        Self::transition(
928            CustomProcess {
929                ready_check: Some(check),
930                ..self.config
931            },
932            self.errors,
933        )
934    }
935
936    /// Start after `name` has met its natural condition (completed for a
937    /// one-shot, healthy when it has a check or a port, started otherwise).
938    pub fn with_dependency(self, name: impl Into<String>) -> Self {
939        self.with_dependency_on(name, None)
940    }
941
942    /// Start after `name` has met `condition`, or its natural one when `None`.
943    pub fn with_dependency_on(
944        self,
945        name: impl Into<String>,
946        condition: impl Into<Option<DependencyCondition>>,
947    ) -> Self {
948        let mut depends_on = self.config.depends_on;
949        depends_on.push(Dependency {
950            name: name.into(),
951            condition: condition.into(),
952        });
953        Self::transition(
954            CustomProcess {
955                depends_on,
956                ..self.config
957            },
958            self.errors,
959        )
960    }
961
962    /// Seconds to wait for the process to meet its condition (the ready check
963    /// to pass, or a one-shot to exit); the global `node_spawn_timeout`
964    /// otherwise.
965    pub fn with_timeout(self, secs: u32) -> Self {
966        Self::transition(
967            CustomProcess {
968                timeout: Some(secs),
969                ..self.config
970            },
971            self.errors,
972        )
973    }
974
975    /// The process runs to completion: exit 0 is success, anything else a
976    /// failure; others may depend on it with `service_completed_successfully`.
977    pub fn with_one_shot(self) -> Self {
978        Self::transition(
979            CustomProcess {
980                one_shot: true,
981                ..self.config
982            },
983            self.errors,
984        )
985    }
986
987    /// Set the resources to apply to the process (only k8s).
988    pub fn with_resources(self, f: impl FnOnce(ResourcesBuilder) -> ResourcesBuilder) -> Self {
989        match f(ResourcesBuilder::new()).build() {
990            Ok(resources) => Self::transition(
991                CustomProcess {
992                    resources: Some(resources),
993                    ..self.config
994                },
995                self.errors,
996            ),
997            Err(errors) => Self::transition(
998                self.config,
999                errors.into_iter().fold(self.errors, |acc, e| {
1000                    merge_errors(acc, FieldError::Resources(e).into())
1001                }),
1002            ),
1003        }
1004    }
1005
1006    /// Seals the builder and returns a [`CustomProcess`] if there are no validation errors, else returns errors.
1007    pub fn build(self) -> Result<CustomProcess, (String, Vec<anyhow::Error>)> {
1008        let mut errors = self.errors;
1009        if let Err(field_errors) = self.config.validate() {
1010            errors.extend(field_errors);
1011        }
1012
1013        if !errors.is_empty() {
1014            return Err((self.config.name.clone(), errors));
1015        }
1016
1017        Ok(self.config)
1018    }
1019}
1020
1021#[cfg(test)]
1022mod tests {
1023    use super::*;
1024
1025    #[test]
1026    fn custom_process_config_builder_should_succeeds_and_returns_a_custom_process_config() {
1027        let cpb = CustomProcessBuilder::new()
1028            .with_name("demo")
1029            .with_command("some")
1030            .with_args(vec![("--port", "100").into(), "--custom-flag".into()])
1031            .build()
1032            .unwrap();
1033
1034        assert_eq!(cpb.command().as_str(), "some");
1035        let args: Vec<Arg> = vec![("--port", "100").into(), "--custom-flag".into()];
1036        assert_eq!(cpb.args(), args.iter().collect::<Vec<&Arg>>());
1037        assert!(cpb.ports().is_empty());
1038        assert!(cpb.resources().is_none());
1039    }
1040
1041    #[test]
1042    fn ports_and_resources_are_carried_and_round_trip() {
1043        let cp = CustomProcessBuilder::new()
1044            .with_name("ipfs")
1045            .with_command("ipfs")
1046            .with_image("docker.io/ipfs/kubo:v0.39.0")
1047            .with_named_port("api", 5001)
1048            .with_named_port("gateway", 8080)
1049            .with_resources(|r| r.with_limit_cpu("500m").with_limit_memory("512Mi"))
1050            .build()
1051            .unwrap();
1052
1053        assert_eq!(
1054            cp.ports(),
1055            &[
1056                NamedPort {
1057                    name: "api".into(),
1058                    port: 5001
1059                },
1060                NamedPort {
1061                    name: "gateway".into(),
1062                    port: 8080
1063                }
1064            ]
1065        );
1066        assert_eq!(
1067            cp.resources().unwrap().limit_cpu().unwrap().as_str(),
1068            "500m"
1069        );
1070
1071        let json = serde_json::to_value(&cp).unwrap();
1072        assert_eq!(json["ports"][1]["name"], "gateway");
1073        assert_eq!(json["ports"][1]["port"], 8080);
1074        let back: CustomProcess = serde_json::from_value(json).unwrap();
1075        assert_eq!(back, cp);
1076    }
1077
1078    #[test]
1079    fn a_process_without_ports_serializes_as_before() {
1080        let cp = CustomProcessBuilder::new()
1081            .with_name("demo")
1082            .with_command("some")
1083            .build()
1084            .unwrap();
1085        let json = serde_json::to_value(&cp).unwrap();
1086        assert!(json.get("ports").is_none());
1087        assert!(json.get("resources").is_none());
1088    }
1089
1090    #[test]
1091    fn duplicate_port_names_and_numbers_are_rejected() {
1092        let err = CustomProcessBuilder::new()
1093            .with_name("demo")
1094            .with_command("some")
1095            .with_named_port("api", 5001)
1096            .with_named_port("api", 5002)
1097            .build()
1098            .unwrap_err();
1099        assert_eq!(err.0, "demo");
1100        assert!(err.1[0].to_string().contains("declared twice"));
1101
1102        let err = CustomProcessBuilder::new()
1103            .with_name("demo")
1104            .with_command("some")
1105            .with_named_port("api", 5001)
1106            .with_named_port("other", 5001)
1107            .build()
1108            .unwrap_err();
1109        assert!(err.1[0].to_string().contains("port 5001 is declared twice"));
1110
1111        // Two ports left for zombienet to pick never collide.
1112        CustomProcessBuilder::new()
1113            .with_name("demo")
1114            .with_command("some")
1115            .with_named_port("api", 0)
1116            .with_named_port("gateway", 0)
1117            .build()
1118            .unwrap();
1119    }
1120
1121    #[test]
1122    fn lifecycle_fields_round_trip_and_validate() {
1123        let init = CustomProcessBuilder::new()
1124            .with_name("init")
1125            .with_command("sh")
1126            .with_one_shot()
1127            .build()
1128            .unwrap();
1129        let api = CustomProcessBuilder::new()
1130            .with_name("api")
1131            .with_command("api")
1132            .with_named_port("http", 8080)
1133            .with_ready_check(ReadyCheck::http("http", "/health"))
1134            .with_timeout(30)
1135            .with_dependency("init")
1136            .with_dependency_on("db", DependencyCondition::ServiceStarted)
1137            .build()
1138            .unwrap();
1139        let db = CustomProcessBuilder::new()
1140            .with_name("db")
1141            .with_command("postgres")
1142            .with_named_port("pg", 5432)
1143            .build()
1144            .unwrap();
1145
1146        assert_eq!(
1147            init.natural_condition(),
1148            DependencyCondition::ServiceCompletedSuccessfully
1149        );
1150        assert_eq!(db.natural_condition(), DependencyCondition::ServiceHealthy);
1151        assert_eq!(api.ready_check().unwrap().port_name(), "http");
1152        assert_eq!(api.timeout(), Some(30));
1153        assert_eq!(
1154            api.effective_check(),
1155            Some(ReadyTarget::Http {
1156                port: "http".into(),
1157                path: "/health".into()
1158            })
1159        );
1160        assert_eq!(db.effective_check(), Some(ReadyTarget::Tcp("pg".into())));
1161        assert_eq!(init.effective_check(), None);
1162
1163        let toml_str = toml::to_string(&api).unwrap();
1164        assert!(
1165            toml_str.contains(
1166                "depends_on = [\"init\", { name = \"db\", condition = \"service_started\" }]"
1167            ),
1168            "{toml_str}"
1169        );
1170        assert!(toml_str.contains("[ready_check.http]"), "{toml_str}");
1171        let back: CustomProcess = toml::from_str(&toml_str).unwrap();
1172        assert_eq!(back, api);
1173
1174        validate_custom_processes(&[init.clone(), db.clone(), api.clone()]).unwrap();
1175    }
1176
1177    #[test]
1178    fn lifecycle_rules_are_enforced() {
1179        // ready_check on a port that is not declared, and on a one-shot
1180        let errors = CustomProcessBuilder::new()
1181            .with_name("bad")
1182            .with_command("sh")
1183            .with_one_shot()
1184            .with_ready_check(ReadyCheck::tcp("nope"))
1185            .build()
1186            .unwrap_err()
1187            .1;
1188        let text: Vec<String> = errors.iter().map(|e| e.to_string()).collect();
1189        assert!(
1190            text.iter()
1191                .any(|e| e.contains("port 'nope' is not declared")),
1192            "{text:?}"
1193        );
1194        assert!(
1195            text.iter()
1196                .any(|e| e.contains("one-shot process runs to completion")),
1197            "{text:?}"
1198        );
1199
1200        // zero and absurd durations
1201        let errors = CustomProcessBuilder::new()
1202            .with_name("slow")
1203            .with_command("sh")
1204            .with_named_port("p", 1)
1205            .with_ready_check(ReadyCheck::tcp("p").with_interval(0))
1206            .with_timeout(0)
1207            .build()
1208            .unwrap_err()
1209            .1;
1210        let text: Vec<String> = errors.iter().map(|e| e.to_string()).collect();
1211        assert!(
1212            text.iter()
1213                .any(|e| e.contains("interval must be at least 1")),
1214            "{text:?}"
1215        );
1216        assert!(
1217            text.iter()
1218                .any(|e| e.contains("timeout: must be at least 1")),
1219            "{text:?}"
1220        );
1221        let errors = CustomProcessBuilder::new()
1222            .with_name("forever")
1223            .with_command("sh")
1224            .with_timeout(u32::MAX)
1225            .build()
1226            .unwrap_err()
1227            .1;
1228        assert!(
1229            errors.iter().any(|e| e.to_string().contains("a week")),
1230            "{errors:?}"
1231        );
1232
1233        // self dependency and a duplicate
1234        let errors = CustomProcessBuilder::new()
1235            .with_name("me")
1236            .with_command("sh")
1237            .with_dependency("me")
1238            .with_dependency("other")
1239            .with_dependency("other")
1240            .build()
1241            .unwrap_err()
1242            .1;
1243        let text: Vec<String> = errors.iter().map(|e| e.to_string()).collect();
1244        assert!(
1245            text.iter().any(|e| e.contains("depends on itself")),
1246            "{text:?}"
1247        );
1248        assert!(text.iter().any(|e| e.contains("listed twice")), "{text:?}");
1249
1250        // across processes: unknown target, condition that does not fit, a cycle
1251        let mk = |name: &str, deps: Vec<Dependency>, one_shot: bool| {
1252            let mut b = CustomProcessBuilder::new()
1253                .with_name(name)
1254                .with_command("sh");
1255            for d in deps {
1256                b = b.with_dependency_on(d.name, d.condition);
1257            }
1258            if one_shot {
1259                b = b.with_one_shot();
1260            }
1261            b.build().unwrap()
1262        };
1263        let errors = validate_custom_processes(&[
1264            mk("a", vec!["ghost".into()], false),
1265            mk(
1266                "b",
1267                vec![Dependency {
1268                    name: "a".into(),
1269                    condition: Some(DependencyCondition::ServiceHealthy),
1270                }],
1271                false,
1272            ),
1273            mk(
1274                "c",
1275                vec![Dependency {
1276                    name: "a".into(),
1277                    condition: Some(DependencyCondition::ServiceCompletedSuccessfully),
1278                }],
1279                false,
1280            ),
1281            mk("x", vec!["y".into()], false),
1282            mk("y", vec!["x".into()], false),
1283        ])
1284        .unwrap_err();
1285        assert!(
1286            errors
1287                .iter()
1288                .any(|e| e.contains("'ghost' is not a custom process")),
1289            "{errors:?}"
1290        );
1291        assert!(
1292            errors
1293                .iter()
1294                .any(|e| e.contains("'a' cannot be service_healthy")),
1295            "{errors:?}"
1296        );
1297        assert!(
1298            errors
1299                .iter()
1300                .any(|e| e.contains("'a' cannot be service_completed_successfully")),
1301            "{errors:?}"
1302        );
1303        assert!(
1304            errors.iter().any(|e| e.contains("cycle among x, y")),
1305            "{errors:?}"
1306        );
1307    }
1308
1309    #[test]
1310    fn port_names_must_be_valid_service_names() {
1311        for bad in [
1312            "",
1313            "json_rpc",
1314            "Gateway",
1315            "a-name-that-is-too-long",
1316            "8080",
1317            "-api",
1318            "api--x",
1319        ] {
1320            let err = CustomProcessBuilder::new()
1321                .with_name("demo")
1322                .with_command("some")
1323                .with_named_port(bad, 5001)
1324                .build()
1325                .unwrap_err();
1326            assert!(
1327                err.1[0].to_string().starts_with("ports: port name"),
1328                "{bad:?} should be rejected, got {}",
1329                err.1[0]
1330            );
1331        }
1332        for good in ["api", "rpc-http", "p2p", "a", "x-15-chars-long"] {
1333            CustomProcessBuilder::new()
1334                .with_name("demo")
1335                .with_command("some")
1336                .with_named_port(good, 5001)
1337                .build()
1338                .unwrap_or_else(|e| panic!("{good:?} should be accepted, got {:?}", e.1));
1339        }
1340    }
1341
1342    #[test]
1343    fn files_and_secret_env_round_trip_and_validate() {
1344        let api = CustomProcessBuilder::new()
1345            .with_name("api")
1346            .with_command("api")
1347            .with_env(vec![
1348                ("RUST_LOG", "info").into(),
1349                ProcessEnvVar::from_secret("TURN_SECRET", "turn", "secret"),
1350            ])
1351            .with_injected_file(TransferedFile::new("./sql/init.sql", "/schema/init.sql"))
1352            .with_injected_file(TransferedFile::new("./run.sh", "/run.sh").mode("0755"))
1353            .build()
1354            .unwrap();
1355
1356        assert_eq!(
1357            api.env(),
1358            [
1359                ProcessEnvVar {
1360                    name: "RUST_LOG".into(),
1361                    value: EnvValue::Value("info".into()),
1362                },
1363                ProcessEnvVar {
1364                    name: "TURN_SECRET".into(),
1365                    value: EnvValue::Secret {
1366                        name: "turn".into(),
1367                        key: "secret".into(),
1368                    },
1369                },
1370            ]
1371        );
1372        assert_eq!(api.injected_files()[1].mode, "0755");
1373
1374        let json = serde_json::to_value(&api).unwrap();
1375        assert_eq!(
1376            json["env"],
1377            serde_json::json!([
1378                { "name": "RUST_LOG", "value": "info" },
1379                { "name": "TURN_SECRET", "secret": { "name": "turn", "key": "secret" } },
1380            ])
1381        );
1382        assert_eq!(
1383            json["injected_files"][0],
1384            serde_json::json!({ "local_path": "./sql/init.sql", "remote_path": "/schema/init.sql" })
1385        );
1386        let reloaded: CustomProcess = serde_json::from_value(json).unwrap();
1387        assert_eq!(reloaded, api);
1388
1389        let errors = CustomProcessBuilder::new()
1390            .with_name("bad")
1391            .with_command("bad")
1392            .with_env(vec![
1393                ProcessEnvVar::from_secret("TURN_SECRET", "", "secret"),
1394                ("TURN_SECRET", "plain").into(),
1395            ])
1396            .with_injected_file(TransferedFile::new("./a", "schema/init.sql"))
1397            .with_injected_file(TransferedFile::new("./b", "/etc/"))
1398            .with_injected_file(TransferedFile::new("./c", "/c").mode("rwx"))
1399            .with_injected_file(TransferedFile::new("./d", "/c"))
1400            .with_injected_file(TransferedFile::new("./e", "/x/../e"))
1401            .with_injected_file(TransferedFile::new("./f", "/f:g"))
1402            .with_injected_file(TransferedFile::new("./g", "/g").mode("4755"))
1403            .with_injected_file(TransferedFile::new("./h", "/c/."))
1404            .with_injected_file(TransferedFile::new("./i", "//c"))
1405            .with_injected_file(TransferedFile::new("./j", "/."))
1406            .with_injected_file(TransferedFile::new("./k", "/c/k"))
1407            .build()
1408            .unwrap_err()
1409            .1
1410            .iter()
1411            .map(ToString::to_string)
1412            .collect::<Vec<_>>();
1413        let expected = [
1414            "env: 'TURN_SECRET' needs the secret's name and key",
1415            "env: 'TURN_SECRET' is given twice",
1416            "injected_files: remote_path 'schema/init.sql' must be an absolute path to a file, without '.', '..', '//' or ':'",
1417            "remote_path '/etc/' must be an absolute path",
1418            "injected_files: mode 'rwx' must be 3 or 4 octal digits up to 0777, e.g. '0755'",
1419            "remote_path '/c' is given twice",
1420            "remote_path '/x/../e' must be an absolute path",
1421            "remote_path '/f:g' must be an absolute path",
1422            "mode '4755' must be 3 or 4 octal digits",
1423            "remote_path '/c/.' must be an absolute path",
1424            "remote_path '//c' must be an absolute path",
1425            "remote_path '/.' must be an absolute path",
1426            "remote_paths '/c' and '/c/k' cannot both be files",
1427        ];
1428        assert_eq!(errors.len(), expected.len(), "{errors:#?}");
1429        for (error, expected) in errors.iter().zip(expected) {
1430            assert!(
1431                error.contains(expected),
1432                "{error:?} should contain {expected:?}"
1433            );
1434        }
1435    }
1436
1437    #[test]
1438    fn an_env_entry_is_a_value_or_a_secret() {
1439        let parse = |json: serde_json::Value| {
1440            serde_json::from_value::<ProcessEnvVar>(json).map_err(|e| e.to_string())
1441        };
1442        assert_eq!(
1443            parse(serde_json::json!({ "name": "A", "value": "1" })).unwrap(),
1444            ProcessEnvVar::from(("A", "1"))
1445        );
1446        assert_eq!(
1447            parse(serde_json::json!({ "name": "A", "secret": { "name": "s", "key": "k" } }))
1448                .unwrap(),
1449            ProcessEnvVar::from_secret("A", "s", "k")
1450        );
1451        for json in [
1452            serde_json::json!({ "name": "A" }),
1453            serde_json::json!({ "name": "A", "valeu": "1" }),
1454            serde_json::json!({ "name": "A", "value": "1", "secret": { "name": "s", "key": "k" } }),
1455        ] {
1456            assert_eq!(
1457                parse(json).unwrap_err(),
1458                "env 'A' needs exactly one of `value` or `secret`"
1459            );
1460        }
1461    }
1462}