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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
45pub struct NamedPort {
46 pub name: String,
47 pub port: Port,
48}
49
50fn 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#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
82pub struct ProcessEnvVar {
83 pub name: String,
84 #[serde(flatten)]
85 pub value: EnvValue,
86}
87
88#[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#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
126#[serde(rename_all = "lowercase")]
127pub enum EnvValue {
128 Value(String),
130 Secret { name: String, key: String },
133}
134
135impl ProcessEnvVar {
136 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#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
173pub struct ReadyCheck {
174 #[serde(flatten)]
175 pub target: ReadyTarget,
176 #[serde(default = "one", skip_serializing_if = "is_one")]
178 pub interval: u32,
179}
180
181#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "lowercase")]
184pub enum ReadyTarget {
185 Tcp(String),
187 Http { port: String, path: String },
189}
190
191impl ReadyTarget {
192 pub fn port_name(&self) -> &str {
194 match self {
195 Self::Tcp(port) | Self::Http { port, .. } => port,
196 }
197 }
198
199 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 pub fn tcp(port: impl Into<String>) -> Self {
219 Self {
220 target: ReadyTarget::Tcp(port.into()),
221 interval: 1,
222 }
223 }
224
225 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 pub fn port_name(&self) -> &str {
243 self.target.port_name()
244 }
245}
246
247#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
249#[serde(rename_all = "snake_case")]
250pub enum DependencyCondition {
251 ServiceStarted,
253 ServiceHealthy,
255 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#[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 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
332pub const MAX_TIMEOUT_SECS: u32 = 7 * 24 * 60 * 60;
334
335#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
340pub struct CustomProcess {
341 name: String,
343 #[serde(skip_serializing_if = "Option::is_none")]
345 image: Option<Image>,
346 command: Command,
348 #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
350 args: Vec<Arg>,
351 #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
353 env: Vec<ProcessEnvVar>,
354 #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
356 injected_files: Vec<TransferedFile>,
357 #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
359 ports: Vec<NamedPort>,
360 #[serde(skip_serializing_if = "Option::is_none")]
362 resources: Option<Resources>,
363 #[serde(skip_serializing_if = "Option::is_none")]
365 ready_check: Option<ReadyCheck>,
366 #[serde(skip_serializing_if = "std::vec::Vec::is_empty", default)]
368 depends_on: Vec<Dependency>,
369 #[serde(skip_serializing_if = "is_false", default)]
371 one_shot: bool,
372 #[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(), 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 pub fn name(&self) -> &str {
399 &self.name
400 }
401
402 pub fn image(&self) -> Option<&Image> {
404 self.image.as_ref()
405 }
406
407 pub fn command(&self) -> &Command {
409 &self.command
410 }
411
412 pub fn args(&self) -> Vec<&Arg> {
414 self.args.iter().collect()
415 }
416
417 pub fn env(&self) -> &[ProcessEnvVar] {
419 &self.env
420 }
421
422 pub fn injected_files(&self) -> &[TransferedFile] {
424 &self.injected_files
425 }
426
427 pub fn ports(&self) -> &[NamedPort] {
429 &self.ports
430 }
431
432 pub fn resources(&self) -> Option<&Resources> {
434 self.resources.as_ref()
435 }
436
437 pub fn ready_check(&self) -> Option<&ReadyCheck> {
441 self.ready_check.as_ref()
442 }
443
444 pub fn depends_on(&self) -> &[Dependency] {
446 &self.depends_on
447 }
448
449 pub fn one_shot(&self) -> bool {
452 self.one_shot
453 }
454
455 pub fn timeout(&self) -> Option<u32> {
459 self.timeout
460 }
461
462 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 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 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 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 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
689pub(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 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
765pub 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 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 name,
821 ..self.config
822 },
823 merge_errors(self.errors, FieldError::Name(e).into()),
824 ),
825 }
826 }
827}
828
829impl CustomProcessBuilder<WithName, WithOutCmd> {
830 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 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 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 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 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 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 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 pub fn with_dependency(self, name: impl Into<String>) -> Self {
939 self.with_dependency_on(name, None)
940 }
941
942 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 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 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 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 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 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 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 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 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 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}