feat: implement depends_on conditions (service_started, service_healthy)

Add ServiceDependency and DependencyCondition types to support Docker
Compose v3 depends_on semantics. The default condition service_started
means a running dependency is sufficient regardless of health check
status, while service_healthy requires health checks to pass first.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lightsofapollo

crates/vz-stack/src/compose.rs

@@ -12,8 +12,8 @@ use serde_yml::Value;
 
 use crate::error::StackError;
 use crate::spec::{
-    HealthCheckSpec, MountSpec, PortSpec, ResourcesSpec, RestartPolicy, SecretDef,
-    ServiceSecretRef, ServiceSpec, StackSpec, VolumeSpec,
+    DependencyCondition, HealthCheckSpec, MountSpec, PortSpec, ResourcesSpec, RestartPolicy,
+    SecretDef, ServiceDependency, ServiceSecretRef, ServiceSpec, StackSpec, VolumeSpec,
 };
 
 // ── Accepted key sets ──────────────────────────────────────────────
@@ -213,10 +213,10 @@ fn parse_compose_inner(
     let service_names: Vec<&str> = services.iter().map(|s| s.name.as_str()).collect();
     for svc in &services {
         for dep in &svc.depends_on {
-            if !service_names.contains(&dep.as_str()) {
+            if !service_names.contains(&dep.service.as_str()) {
                 return Err(StackError::ComposeValidation(format!(
                     "service `{}` depends on `{}` which is not defined",
-                    svc.name, dep,
+                    svc.name, dep.service,
                 )));
             }
         }
@@ -775,7 +775,10 @@ fn parse_mount_long(svc_name: &str, obj: &serde_yml::Mapping) -> Result<MountSpe
 }
 
 /// Parse `depends_on` which can be a list of strings or a mapping with conditions.
-fn parse_depends_on(svc_name: &str, map: &serde_yml::Mapping) -> Result<Vec<String>, StackError> {
+fn parse_depends_on(
+    svc_name: &str,
+    map: &serde_yml::Mapping,
+) -> Result<Vec<ServiceDependency>, StackError> {
     let Some(value) = map.get(val("depends_on")) else {
         return Ok(vec![]);
     };
@@ -784,22 +787,28 @@ fn parse_depends_on(svc_name: &str, map: &serde_yml::Mapping) -> Result<Vec<Stri
         // Simple list: depends_on: [db, cache]
         seq.iter()
             .map(|v| {
-                v.as_str().map(String::from).ok_or_else(|| {
-                    StackError::ComposeParse(format!(
-                        "service `{svc_name}`: `depends_on` items must be strings"
-                    ))
-                })
+                v.as_str()
+                    .map(ServiceDependency::started)
+                    .ok_or_else(|| {
+                        StackError::ComposeParse(format!(
+                            "service `{svc_name}`: `depends_on` items must be strings"
+                        ))
+                    })
             })
             .collect()
     } else if let Some(obj) = value.as_mapping() {
         // Conditional form: depends_on: { db: { condition: service_healthy } }
-        // We accept both forms but treat all conditions as service_started.
-        obj.keys()
-            .map(|k| {
-                k.as_str().map(String::from).ok_or_else(|| {
+        obj.iter()
+            .map(|(k, v)| {
+                let dep_name = k.as_str().ok_or_else(|| {
                     StackError::ComposeParse(format!(
                         "service `{svc_name}`: `depends_on` keys must be strings"
                     ))
+                })?;
+                let condition = parse_dependency_condition(svc_name, dep_name, v)?;
+                Ok(ServiceDependency {
+                    service: dep_name.to_string(),
+                    condition,
                 })
             })
             .collect()
@@ -810,6 +819,40 @@ fn parse_depends_on(svc_name: &str, map: &serde_yml::Mapping) -> Result<Vec<Stri
     }
 }
 
+/// Extract the condition from a depends_on mapping value.
+///
+/// The value can be a mapping like `{ condition: service_healthy }` or
+/// omitted/empty (defaults to `service_started`).
+fn parse_dependency_condition(
+    svc_name: &str,
+    dep_name: &str,
+    value: &serde_yml::Value,
+) -> Result<DependencyCondition, StackError> {
+    let Some(obj) = value.as_mapping() else {
+        // No condition specified → default.
+        return Ok(DependencyCondition::ServiceStarted);
+    };
+
+    let Some(cond_val) = obj.get(val("condition")) else {
+        return Ok(DependencyCondition::ServiceStarted);
+    };
+
+    let cond_str = cond_val.as_str().ok_or_else(|| {
+        StackError::ComposeParse(format!(
+            "service `{svc_name}`: depends_on `{dep_name}` condition must be a string"
+        ))
+    })?;
+
+    match cond_str {
+        "service_started" => Ok(DependencyCondition::ServiceStarted),
+        "service_healthy" => Ok(DependencyCondition::ServiceHealthy),
+        "service_completed_successfully" => Ok(DependencyCondition::ServiceCompletedSuccessfully),
+        other => Err(StackError::ComposeParse(format!(
+            "service `{svc_name}`: depends_on `{dep_name}` unknown condition `{other}`"
+        ))),
+    }
+}
+
 /// Parse healthcheck configuration.
 fn parse_healthcheck(
     svc_name: &str,
@@ -1925,11 +1968,11 @@ services:
 "#;
         let spec = parse_compose(yaml, "myapp").unwrap();
         let web = spec.services.iter().find(|s| s.name == "web").unwrap();
-        assert_eq!(web.depends_on, vec!["db".to_string()]);
+        assert_eq!(web.depends_on, vec![ServiceDependency::started("db")]);
     }
 
     #[test]
-    fn depends_on_mapping_form() {
+    fn depends_on_mapping_form_service_healthy() {
         let yaml = r#"
 services:
   db:
@@ -1942,7 +1985,40 @@ services:
 "#;
         let spec = parse_compose(yaml, "myapp").unwrap();
         let web = spec.services.iter().find(|s| s.name == "web").unwrap();
-        assert_eq!(web.depends_on, vec!["db".to_string()]);
+        assert_eq!(web.depends_on, vec![ServiceDependency::healthy("db")]);
+    }
+
+    #[test]
+    fn depends_on_mapping_form_service_started() {
+        let yaml = r#"
+services:
+  db:
+    image: postgres:15
+  web:
+    image: nginx:latest
+    depends_on:
+      db:
+        condition: service_started
+"#;
+        let spec = parse_compose(yaml, "myapp").unwrap();
+        let web = spec.services.iter().find(|s| s.name == "web").unwrap();
+        assert_eq!(web.depends_on, vec![ServiceDependency::started("db")]);
+    }
+
+    #[test]
+    fn depends_on_mapping_form_no_condition() {
+        let yaml = r#"
+services:
+  db:
+    image: postgres:15
+  web:
+    image: nginx:latest
+    depends_on:
+      db: {}
+"#;
+        let spec = parse_compose(yaml, "myapp").unwrap();
+        let web = spec.services.iter().find(|s| s.name == "web").unwrap();
+        assert_eq!(web.depends_on, vec![ServiceDependency::started("db")]);
     }
 
     // ── Healthcheck parsing ───────────────────────────────────────
@@ -2555,7 +2631,7 @@ volumes:
 
         // Web service.
         let web = &spec.services[1];
-        assert_eq!(web.depends_on, vec!["redis".to_string()]);
+        assert_eq!(web.depends_on, vec![ServiceDependency::started("redis")]);
         assert_eq!(
             web.environment.get("REDIS_URL").unwrap(),
             "redis://redis:6379"

crates/vz-stack/src/convert.rs

@@ -207,7 +207,9 @@ mod tests {
     #![allow(clippy::unwrap_used)]
 
     use super::*;
-    use crate::spec::{HealthCheckSpec, MountSpec as StackMountSpec, RestartPolicy};
+    use crate::spec::{
+        HealthCheckSpec, MountSpec as StackMountSpec, RestartPolicy, ServiceDependency,
+    };
     use crate::volume::{ResolvedMount, ResolvedMountKind};
     use std::collections::HashMap;
 
@@ -513,7 +515,7 @@ mod tests {
                     host_port: None,
                 },
             ],
-            depends_on: vec!["db".to_string()],
+            depends_on: vec![ServiceDependency::started("db")],
             healthcheck: Some(HealthCheckSpec {
                 test: vec![
                     "CMD".to_string(),

crates/vz-stack/src/health.rs

@@ -16,7 +16,7 @@ use tracing::{debug, info, warn};
 use crate::error::StackError;
 use crate::events::StackEvent;
 use crate::executor::ContainerRuntime;
-use crate::spec::{HealthCheckSpec, ServiceSpec, StackSpec};
+use crate::spec::{DependencyCondition, HealthCheckSpec, ServiceSpec, StackSpec};
 use crate::state_store::{ServiceObservedState, ServicePhase, StateStore};
 
 /// Result of checking whether a service's dependencies are satisfied.
@@ -103,11 +103,14 @@ pub fn is_service_ready(
 /// only blocks when:
 ///
 /// - It is in a terminal state (`Failed` / `Stopped`).
-/// - It is `Running` with a health check that has not yet passed.
+/// - The condition is `service_healthy` and the health check has
+///   not yet passed.
+/// - The condition is `service_completed_successfully` and the
+///   service has not exited with code 0.
 ///
-/// This means a fresh deployment creates all services in one
-/// topo-sorted pass, while health-checked dependencies gate their
-/// dependents across apply cycles.
+/// With the default `service_started` condition, a running service
+/// is considered ready regardless of health check status — matching
+/// Docker Compose semantics.
 pub fn check_dependencies(
     service: &ServiceSpec,
     observed: &[ServiceObservedState],
@@ -128,10 +131,10 @@ pub fn check_dependencies(
 
     let mut waiting_on = Vec::new();
 
-    for dep_name in &service.depends_on {
-        let dep_obs = observed_map.get(dep_name.as_str());
-        let dep_spec = spec_map.get(dep_name.as_str());
-        let dep_health = health_statuses.get(dep_name);
+    for dep in &service.depends_on {
+        let dep_obs = observed_map.get(dep.service.as_str());
+        let dep_spec = spec_map.get(dep.service.as_str());
+        let dep_health = health_statuses.get(&dep.service);
 
         let blocked = match dep_obs {
             None => {
@@ -141,21 +144,32 @@ pub fn check_dependencies(
             Some(obs) => match obs.phase {
                 // Terminal states block dependent creation.
                 ServicePhase::Failed | ServicePhase::Stopped => true,
-                // Running: block only if there's a health check that hasn't passed.
-                ServicePhase::Running => {
-                    let healthcheck = dep_spec.and_then(|s| s.healthcheck.as_ref());
-                    match healthcheck {
-                        None => false, // Running + no health check = ready.
-                        Some(hc) => !is_service_ready(obs, Some(hc), dep_health),
+                // Running: behaviour depends on the condition.
+                ServicePhase::Running => match dep.condition {
+                    DependencyCondition::ServiceStarted => {
+                        // Running is sufficient — don't check health.
+                        false
                     }
-                }
+                    DependencyCondition::ServiceHealthy => {
+                        // Must have a passing health check.
+                        let healthcheck = dep_spec.and_then(|s| s.healthcheck.as_ref());
+                        match healthcheck {
+                            None => false, // No health check defined = ready.
+                            Some(hc) => !is_service_ready(obs, Some(hc), dep_health),
+                        }
+                    }
+                    DependencyCondition::ServiceCompletedSuccessfully => {
+                        // Running means not completed yet → blocked.
+                        true
+                    }
+                },
                 // Pending/Creating/Stopping — in progress, don't block.
                 _ => false,
             },
         };
 
         if blocked {
-            waiting_on.push(dep_name.clone());
+            waiting_on.push(dep.service.clone());
         }
     }
 
@@ -433,6 +447,7 @@ mod tests {
     #![allow(clippy::unwrap_used)]
 
     use super::*;
+    use crate::spec::ServiceDependency;
     use std::collections::HashMap;
 
     fn svc(name: &str) -> ServiceSpec {
@@ -457,7 +472,14 @@ mod tests {
 
     fn svc_with_deps(name: &str, deps: Vec<&str>) -> ServiceSpec {
         ServiceSpec {
-            depends_on: deps.into_iter().map(String::from).collect(),
+            depends_on: deps.into_iter().map(ServiceDependency::started).collect(),
+            ..svc(name)
+        }
+    }
+
+    fn svc_with_healthy_deps(name: &str, deps: Vec<&str>) -> ServiceSpec {
+        ServiceSpec {
+            depends_on: deps.into_iter().map(ServiceDependency::healthy).collect(),
             ..svc(name)
         }
     }
@@ -644,12 +666,25 @@ mod tests {
     }
 
     #[test]
-    fn dep_running_with_healthcheck_failing_is_blocked() {
+    fn dep_running_with_healthcheck_service_started_is_ready() {
+        // service_started condition: running is sufficient, healthcheck irrelevant.
         let service = svc_with_deps("web", vec!["db"]);
         let all_services = vec![svc_with_healthcheck("db"), service.clone()];
         let observed = vec![obs("db", ServicePhase::Running)];
 
-        // No health status means health check hasn't passed yet.
+        // No health status — but condition is service_started, so not blocked.
+        let result = check_dependencies(&service, &observed, &all_services, &HashMap::new());
+        assert_eq!(result, DependencyCheck::Ready);
+    }
+
+    #[test]
+    fn dep_running_with_healthcheck_service_healthy_blocks() {
+        // service_healthy condition: must wait for health check to pass.
+        let service = svc_with_healthy_deps("web", vec!["db"]);
+        let all_services = vec![svc_with_healthcheck("db"), service.clone()];
+        let observed = vec![obs("db", ServicePhase::Running)];
+
+        // No health status means health check hasn't passed yet → blocked.
         let result = check_dependencies(&service, &observed, &all_services, &HashMap::new());
         assert_eq!(
             result,
@@ -660,8 +695,9 @@ mod tests {
     }
 
     #[test]
-    fn dep_running_with_healthcheck_passing_is_ready() {
-        let service = svc_with_deps("web", vec!["db"]);
+    fn dep_running_with_healthcheck_passing_service_healthy_is_ready() {
+        // service_healthy condition + health check passed → ready.
+        let service = svc_with_healthy_deps("web", vec!["db"]);
         let all_services = vec![svc_with_healthcheck("db"), service.clone()];
         let observed = vec![obs("db", ServicePhase::Running)];
 

crates/vz-stack/src/lib.rs

@@ -39,8 +39,9 @@ pub use orchestrator::{OrchestrationConfig, OrchestrationResult, RoundReport, St
 pub use reconcile::{Action, ApplyResult, DeferredService, apply};
 pub use restart::{RestartTracker, compute_restarts};
 pub use spec::{
-    HealthCheckSpec, MountSpec, NetworkSpec, PortSpec, ResourcesSpec, RestartPolicy, SecretDef,
-    ServiceSecretRef, ServiceSpec, StackSpec, VolumeSpec,
+    DependencyCondition, HealthCheckSpec, MountSpec, NetworkSpec, PortSpec, ResourcesSpec,
+    RestartPolicy, SecretDef, ServiceDependency, ServiceSecretRef, ServiceSpec, StackSpec,
+    VolumeSpec,
 };
 pub use state_store::{ServiceObservedState, ServicePhase, StateStore};
 pub use volume::{

crates/vz-stack/src/orchestrator.rs

@@ -280,7 +280,7 @@ mod tests {
 
     use super::*;
     use crate::executor::tests_support::MockContainerRuntime;
-    use crate::spec::{HealthCheckSpec, ServiceSpec, StackSpec};
+    use crate::spec::{HealthCheckSpec, ServiceDependency, ServiceSpec, StackSpec};
 
     fn svc(name: &str) -> ServiceSpec {
         ServiceSpec {
@@ -304,7 +304,7 @@ mod tests {
 
     fn svc_with_deps(name: &str, deps: Vec<&str>) -> ServiceSpec {
         ServiceSpec {
-            depends_on: deps.into_iter().map(String::from).collect(),
+            depends_on: deps.into_iter().map(ServiceDependency::started).collect(),
             ..svc(name)
         }
     }