fix: use blue_green for rolling deployments

Author: ra0x3

README.md

@@ -155,7 +155,7 @@ If `database` fails to come up, `web` will remain stopped and log the dependency
 
 #### Rolling Deployments
 
-Services can opt into rolling restarts so existing instances keep serving traffic until replacements are healthy. Add a `deployment` block to configure the behavior:
+Services can opt into rolling restarts. For single-host web services that bind a fixed port, use the `blue_green` block so the replacement starts on an alternate slot and traffic is switched after health checks.
 
 ```yaml
 version: "1"
@@ -167,18 +167,31 @@ services:
       strategy: "rolling"          # default is "immediate"
       pre_start: "cargo build --release"
       health_check:
-        url: "http://localhost:8080/health"
+        url: "http://localhost:8000/health"
         timeout: "60s"
         retries: 5
       grace_period: "5s"
+      blue_green:
+        env_var: "PORT"
+        slots: ["8000", "8001"]
+        candidate_health_check_url: "http://127.0.0.1:{slot}/health"
+        switch_command: "/usr/local/bin/switch-upstream {candidate_slot}"
+        switch_verify_url: "http://localhost:8000/health"
+        state_path: ".state/api-slot.json"
 ```
 
-- `strategy` — set to `rolling` to enable the zero-downtime workflow, or omit to keep the traditional stop/start cycle.
+- `strategy` — set to `rolling` to enable restart-time rollout workflow, or omit to keep the traditional stop/start cycle.
 - `pre_start` — optional shell command executed before the new instance launches (perfect for build or migrate steps).
-- `health_check` — optional HTTP probe the replacement must pass before traffic flips; configure timeout and retry budget per service.
+- `health_check` — optional HTTP probe settings reused by rolling checks.
 - `grace_period` — optional delay to keep the old instance alive after the new one passes health checks, giving load balancers time to rebalance.
-
-If any rolling step fails, systemg restores the original instance and surfaces the error so unhealthy builds never replace running services.
+- `blue_green.env_var` — env var injected into the candidate instance (`PORT` by default).
+- `blue_green.slots` — exactly two alternating slot values (typically port numbers).
+- `blue_green.switch_command` — command run after candidate is healthy; supports `{candidate_slot}`, `{active_slot}`, `{service_name}` placeholders.
+- `blue_green.candidate_health_check_url` — optional candidate probe URL template with `{slot}`.
+- `blue_green.switch_verify_url` — optional post-switch verify URL.
+- `blue_green.state_path` — optional path for persisted active-slot state.
+
+If any rolling step fails, systemg restores the original instance and surfaces the error so unhealthy builds never replace running services. For deployment scripts, use `sysg restart --daemonize` so supervisor state is restored even if detection fails.
 
 #### Cron Scheduling
 

docs/docs/examples/crud.md

@@ -25,7 +25,13 @@ env:
 services:
   node__web_server:
     command: "node server.js"
-    deployment_strategy: "rolling_start"
+    deployment:
+      strategy: "rolling"
+      blue_green:
+        env_var: "PORT"
+        slots: ["3000", "3001"]
+        candidate_health_check_url: "http://127.0.0.1:{slot}/health"
+        switch_command: "sudo /usr/local/bin/switch-crud-upstream {candidate_slot}"
     env:
       vars:
         NODE_ENV: "${NODE_ENV}"
@@ -148,7 +154,7 @@ $ git pull
 $ npm install
 
 # Rolling restart - zero downtime
-$ sysg restart node__web_server
+$ sysg restart --service node__web_server --daemonize
 ```
 
 ### View logs

docs/docs/how-it-works/commands/restart.md

@@ -90,12 +90,21 @@ Services configured with `deployment.strategy: rolling` get zero-downtime restar
 
 1. New instance starts
 2. Health checks pass
-3. Old instance receives `SIGTERM`
-4. Grace period allows requests to complete
-5. Old instance stops
+3. (Optional) blue/green `switch_command` shifts traffic to candidate slot
+4. Old instance receives `SIGTERM`
+5. Grace period allows requests to complete
+6. Old instance stops
 
 Services without rolling deployment stop then start.
 
+For deployment scripts, prefer:
+
+```sh
+sysg restart --config <config> --daemonize
+```
+
+This keeps restart behavior explicit when supervisor detection is unavailable.
+
 ## See also
 
 - [`start`](start) - Launch services

docs/docs/how-it-works/configuration.md

@@ -214,14 +214,23 @@ services:
         url: "http://localhost:8000/health"
         timeout: "30s"
       grace_period: "5s"
+      blue_green:
+        env_var: "PORT"
+        slots: ["8000", "8001"]
+        candidate_health_check_url: "http://127.0.0.1:{slot}/health"
+        switch_command: "/usr/local/bin/switch-upstream {candidate_slot}"
+        switch_verify_url: "http://localhost:8000/health"
+        state_path: ".state/api-slot.json"
 ```
 
-Rolling deployments start the new instance, wait for health checks, then stop the old instance. The `grace_period` allows in-flight requests to complete.
+Rolling deployments start the new instance, wait for health checks, then stop the old instance. For single-host zero-downtime with fixed ports, use `blue_green` so traffic can be switched between two slots.
 
 ## Field reference
 
 ### Service fields
 
+Primary keys available on each service definition.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `command` | string | Command to execute (required) |
@@ -237,13 +246,17 @@ Rolling deployments start the new instance, wait for health checks, then stop th
 
 ### Environment object
 
+Environment sources and inline overrides merged into the service process environment.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `vars` | object | Key-value environment variables |
 | `file` | string | Path to env file |
 
 ### Hooks object
 
+Lifecycle callbacks you can trigger on service start/stop/restart outcomes.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `on_start` | object | Commands for start events |
@@ -256,6 +269,8 @@ Each hook has `success` and `error` handlers with:
 
 ### Health check object
 
+Probe configuration used to determine readiness/health during deployment workflows.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `command` | string | Check command |
@@ -266,9 +281,25 @@ Each hook has `success` and `error` handlers with:
 
 ### Deployment object
 
+Controls how restarts are performed and what validation happens before cutover.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `strategy` | string | `rolling` or `immediate` |
 | `pre_start` | string | Command to run before starting |
 | `health_check` | object | Health check configuration |
 | `grace_period` | string | Time before stopping old instance |
+| `blue_green` | object | Single-host blue/green rollout settings |
+
+### Blue/green deployment object
+
+Single-host zero-downtime options for alternating between two rollout slots (typically ports).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `env_var` | string | Env var injected with slot value (`PORT` default) |
+| `slots` | array | Exactly two slot values to alternate between |
+| `switch_command` | string | Command to switch traffic to candidate slot |
+| `candidate_health_check_url` | string | Candidate health probe URL template (`{slot}` supported) |
+| `switch_verify_url` | string | Optional post-switch verify URL |
+| `state_path` | string | Optional persisted active-slot state file path |

src/bin/main.rs

@@ -2447,6 +2447,7 @@ struct InspectProcessContext<'a> {
     total_memory: f64,
 }
 
+/// Renders an htop-style process table for the inspected unit and all discovered descendants.
 fn render_inspect_process_table(unit: &UnitStatus, no_color: bool) {
     let Some(root_runtime) = unit.process.as_ref() else {
         println!("Process Table: unit is not currently running.");
@@ -2625,6 +2626,7 @@ fn render_inspect_process_table(unit: &UnitStatus, no_color: bool) {
     println!("{}", make_bottom_border(&columns));
 }
 
+/// Walks the process tree rooted at `pid` and appends formatted table rows in tree order.
 fn append_inspect_process_rows(
     context: &InspectProcessContext<'_>,
     pid: u32,
@@ -2703,6 +2705,7 @@ fn append_inspect_process_rows(
     }
 }
 
+/// Formats a generic table row using dynamic columns with control-character sanitization.
 fn format_row_cells(values: &[String], columns: &[Column], _no_color: bool) -> String {
     let mut row = String::from('│');
     for (value, column) in values.iter().zip(columns.iter()) {
@@ -2715,6 +2718,7 @@ fn format_row_cells(values: &[String], columns: &[Column], _no_color: bool) -> S
     row
 }
 
+/// Normalizes cell text to a single printable line while preserving ANSI color escape sequences.
 fn sanitize_table_cell(value: &str) -> String {
     let mut collapsed = String::new();
     let mut chars = value.chars().peekable();
@@ -2746,10 +2750,12 @@ fn sanitize_table_cell(value: &str) -> String {
     collapsed.split_whitespace().collect::<Vec<_>>().join(" ")
 }
 
+/// Returns a display-friendly process name from sysinfo process metadata.
 fn process_display_name(process: &sysinfo::Process) -> String {
     process.name().to_string_lossy().into_owned()
 }
 
+/// Returns the full command line when available, otherwise falls back to process display name.
 fn process_command_line(process: &sysinfo::Process) -> String {
     if process.cmd().is_empty() {
         process_display_name(process)
@@ -2763,6 +2769,7 @@ fn process_command_line(process: &sysinfo::Process) -> String {
     }
 }
 
+/// Converts sysinfo's status enum into a compact single-letter process state marker.
 fn process_status_code(status: sysinfo::ProcessStatus) -> String {
     format!("{status:?}")
         .chars()
@@ -2772,6 +2779,7 @@ fn process_status_code(status: sysinfo::ProcessStatus) -> String {
 }
 
 #[cfg(target_os = "linux")]
+/// Reads Linux `/proc` process stats used by inspect table columns (PPID, PRI/NI, CPU ticks, SHR).
 fn read_linux_proc_stats(pid: u32) -> LinuxProcStats {
     let stat_path = format!("/proc/{pid}/stat");
     let statm_path = format!("/proc/{pid}/statm");
@@ -2807,11 +2815,13 @@ fn read_linux_proc_stats(pid: u32) -> LinuxProcStats {
 }
 
 #[cfg(not(target_os = "linux"))]
+/// Non-Linux stub returning empty Linux-specific process stats.
 fn read_linux_proc_stats(_pid: u32) -> LinuxProcStats {
     LinuxProcStats::default()
 }
 
 #[cfg(target_os = "linux")]
+/// Parses a `/proc/<pid>/stat` line into selected fields needed for inspect table rendering.
 fn parse_proc_stat_line(contents: &str) -> Option<LinuxProcStats> {
     let closing_paren = contents.rfind(')')?;
     let remainder = contents.get((closing_paren + 1)..)?.trim();
@@ -2838,6 +2848,7 @@ fn parse_proc_stat_line(contents: &str) -> Option<LinuxProcStats> {
     })
 }
 
+/// Formats CPU clock ticks as `MM:SS.CC`, matching htop-style time display.
 fn format_cpu_time_from_ticks(ticks: u64) -> String {
     #[cfg(target_os = "linux")]
     let hz = {

src/config.rs

@@ -414,6 +414,25 @@ pub struct DeploymentConfig {
     pub health_check: Option<HealthCheckConfig>,
     /// Grace period before stopping the old service instance.
     pub grace_period: Option<String>,
+    /// Optional blue/green rollout settings for single-host zero-downtime deployments.
+    pub blue_green: Option<BlueGreenDeploymentConfig>,
+}
+
+/// Blue/green rollout configuration used by rolling deployments on a single host.
+#[derive(Debug, Deserialize, Clone, serde::Serialize)]
+pub struct BlueGreenDeploymentConfig {
+    /// Environment variable used to inject the selected slot value (defaults to "PORT").
+    pub env_var: Option<String>,
+    /// Two slot values (commonly two port numbers) used as alternating targets.
+    pub slots: Vec<String>,
+    /// Command executed to switch traffic to the candidate slot once healthy.
+    pub switch_command: Option<String>,
+    /// Optional URL template for candidate health checks (supports `{slot}` substitution).
+    pub candidate_health_check_url: Option<String>,
+    /// Optional URL to verify after switch command completes.
+    pub switch_verify_url: Option<String>,
+    /// Optional path for persisting the active slot state.
+    pub state_path: Option<String>,
 }
 
 /// Health check configuration used during rolling deployments.
@@ -1144,6 +1163,55 @@ services:
         assert!(vars2.get("SERVICE_ONLY").is_none());
     }
 
+    #[test]
+    fn load_config_parses_blue_green_deployment_block() {
+        let dir = tempdir().expect("tempdir");
+        let yaml_path = dir.path().join("systemg.yaml");
+        let mut yaml_file = File::create(&yaml_path).expect("create yaml");
+        writeln!(
+            yaml_file,
+            r#"
+version: "1"
+services:
+  web:
+    command: "python app.py"
+    deployment:
+      strategy: "rolling"
+      blue_green:
+        env_var: "PORT"
+        slots: ["8000", "8001"]
+        switch_command: "echo switch"
+        candidate_health_check_url: "http://127.0.0.1:{{slot}}/health"
+        switch_verify_url: "http://127.0.0.1/health"
+        state_path: ".state/web-slot.json"
+"#
+        )
+        .expect("write yaml");
+
+        let config = load_config(Some(yaml_path.to_str().expect("yaml path")))
+            .expect("load config");
+        let deployment = config
+            .services
+            .get("web")
+            .expect("web service")
+            .deployment
+            .as_ref()
+            .expect("deployment");
+        let blue_green = deployment.blue_green.as_ref().expect("blue_green");
+
+        assert_eq!(deployment.strategy.as_deref(), Some("rolling"));
+        assert_eq!(blue_green.env_var.as_deref(), Some("PORT"));
+        assert_eq!(blue_green.slots, vec!["8000", "8001"]);
+        assert_eq!(
+            blue_green.candidate_health_check_url.as_deref(),
+            Some("http://127.0.0.1:{slot}/health")
+        );
+        assert_eq!(
+            blue_green.switch_verify_url.as_deref(),
+            Some("http://127.0.0.1/health")
+        );
+    }
+
     #[test]
     fn hash_computation_is_stable() {
         // Same config should always produce the same hash