docs: add ROADMAP.md with health check hardening items

fix: address PR #71 review comments

- Add 'validate' to available help topics hint message
- Use EXIT_USAGE (1) instead of EXIT_RUNTIME (5) for config parse
failures in execute_validate
- Add transformCapacity check to /health/ready endpoint
- Skip memoryUsage check in /health/ready when RSS is unavailable
(non-Linux)
- Add 'validate' command to README Commands table
- Add platform-specific note to OpenAPI /health/ready description

fix: resolve fmt failure and cross-platform test failure

- Run cargo fmt to fix formatting in cli.rs and mod.rs
- Fix health_ready_memory_check_includes_details test to expect
  memoryUsage check absent on non-Linux (RSS unavailable)

Author: nao1215

README.md

@@ -203,6 +203,7 @@ See the [Docker](#docker) section for running with Docker instead.
 | `convert` | Convert and transform an image file (can be omitted; see above) |
 | `inspect` | Show metadata (format, dimensions, alpha) of an image |
 | `serve` | Start the HTTP image-transform server (implied when server flags are used at the top level) |
+| `validate` | Validate server configuration without starting the server (useful in CI/CD) |
 | `sign` | Generate a signed public URL for the server |
 | `completions` | Generate shell completion scripts |
 | `version` | Print version information |

ROADMAP.md

@@ -0,0 +1,9 @@
+# Roadmap
+
+Items planned for future releases, roughly in priority order.
+
+## Health Check Hardening
+
+- [#72 — Add hysteresis to readiness probe resource checks to prevent flapping](https://github.com/nao1215/truss/issues/72)
+- [#73 — Consider authentication for /health diagnostic endpoint](https://github.com/nao1215/truss/issues/73)
+- [#74 — Cache syscall results in health check endpoints](https://github.com/nao1215/truss/issues/74)

doc/openapi.yaml

@@ -394,8 +394,15 @@ paths:
         verifying the storage root is accessible, the cache root (if configured)
         is accessible, the object-storage backend (if configured) is
         network-reachable, cache disk free space is above the configured
-        threshold (`TRUSS_HEALTH_CACHE_MIN_FREE_BYTES`), and process memory
-        usage is below the configured limit (`TRUSS_HEALTH_MAX_MEMORY_BYTES`).
+        threshold (`TRUSS_HEALTH_CACHE_MIN_FREE_BYTES`), process memory
+        usage is below the configured limit (`TRUSS_HEALTH_MAX_MEMORY_BYTES`),
+        and transform capacity is not exhausted.
+
+        **Platform note:** RSS memory and cache disk free space are read on
+        Linux only. On other platforms `TRUSS_HEALTH_MAX_MEMORY_BYTES` and
+        `TRUSS_HEALTH_CACHE_MIN_FREE_BYTES` are effectively no-ops — those
+        checks are omitted from the response and the remaining checks
+        (object-storage reachability, transform capacity, etc.) still apply.
 
         The object-storage reachability check (S3, GCS, or Azure) confirms
         that the configured bucket/container exists and the service responds to

src/adapters/cli.rs

@@ -1059,7 +1059,8 @@ fn parse_help_topic(topic: Option<String>) -> Result<Command, CliError> {
             message: format!("unknown help topic '{other}'"),
             usage: None,
             hint: Some(
-                "available topics: convert, inspect, serve, sign, completions, version".to_string(),
+                "available topics: convert, inspect, serve, validate, sign, completions, version"
+                    .to_string(),
             ),
         }),
     }
@@ -1499,7 +1500,7 @@ fn execute_validate<W: Write>(stdout: &mut W) -> Result<(), CliError> {
             Ok(())
         }
         Err(error) => Err(runtime_error(
-            EXIT_RUNTIME,
+            EXIT_USAGE,
             &format!("invalid configuration: {error}"),
         )),
     }

src/adapters/server/mod.rs

@@ -1069,8 +1069,7 @@ fn handle_stream(mut stream: TcpStream, config: &ServerConfig) -> io::Result<()>
         }
 
         requests_served += 1;
-        let close_after =
-            client_wants_close || requests_served >= config.keep_alive_max_requests;
+        let close_after = client_wants_close || requests_served >= config.keep_alive_max_requests;
 
         write_response(&mut stream, response, close_after)?;
         record_http_request_duration(route, start);
@@ -1431,19 +1430,33 @@ fn handle_health_ready(config: &ServerConfig) -> HttpResponse {
         }
     }
 
-    if let Some(max_mem) = config.health_max_memory_bytes {
-        let rss = process_rss_bytes();
-        let ok = rss.is_none_or(|r| r <= max_mem);
+    // Concurrency utilization
+    let in_flight = config.transforms_in_flight.load(Ordering::Relaxed);
+    let overloaded = in_flight >= config.max_concurrent_transforms;
+    checks.push(json!({
+        "name": "transformCapacity",
+        "status": if overloaded { "fail" } else { "ok" },
+        "current": in_flight,
+        "max": config.max_concurrent_transforms,
+    }));
+    if overloaded {
+        all_ok = false;
+    }
+
+    // Memory usage (Linux only) — skip entirely when RSS is unavailable
+    if let Some(rss_bytes) = process_rss_bytes() {
+        let threshold = config.health_max_memory_bytes;
+        let mem_ok = threshold.is_none_or(|max| rss_bytes <= max);
         let mut check = json!({
             "name": "memoryUsage",
-            "status": if ok { "ok" } else { "fail" },
+            "status": if mem_ok { "ok" } else { "fail" },
+            "rssBytes": rss_bytes,
         });
-        if let Some(r) = rss {
-            check["rssBytes"] = json!(r);
+        if let Some(max) = threshold {
+            check["thresholdBytes"] = json!(max);
         }
-        check["thresholdBytes"] = json!(max_mem);
         checks.push(check);
-        if !ok {
+        if !mem_ok {
             all_ok = false;
         }
     }
@@ -5530,8 +5543,7 @@ mod tests {
             &config,
         );
         assert_eq!(response.status, "503 Service Unavailable");
-        let body: serde_json::Value =
-            serde_json::from_slice(&response.body).expect("parse body");
+        let body: serde_json::Value = serde_json::from_slice(&response.body).expect("parse body");
         assert_eq!(body["status"], "fail");
         let checks = body["checks"].as_array().expect("checks array");
         let storage_check = checks
@@ -5557,8 +5569,7 @@ mod tests {
             },
             &config,
         );
-        let body: serde_json::Value =
-            serde_json::from_slice(&response.body).expect("parse body");
+        let body: serde_json::Value = serde_json::from_slice(&response.body).expect("parse body");
         let checks = body["checks"].as_array().expect("checks array");
         let disk_check = checks
             .iter()
@@ -5585,8 +5596,7 @@ mod tests {
             },
             &config,
         );
-        let body: serde_json::Value =
-            serde_json::from_slice(&response.body).expect("parse body");
+        let body: serde_json::Value = serde_json::from_slice(&response.body).expect("parse body");
         let checks = body["checks"].as_array().expect("checks array");
         assert!(
             checks.iter().all(|c| c["name"] != "cacheDiskFree"),
@@ -5609,17 +5619,16 @@ mod tests {
             },
             &config,
         );
-        let body: serde_json::Value =
-            serde_json::from_slice(&response.body).expect("parse body");
+        let body: serde_json::Value = serde_json::from_slice(&response.body).expect("parse body");
         let checks = body["checks"].as_array().expect("checks array");
-        let mem = checks
-            .iter()
-            .find(|c| c["name"] == "memoryUsage")
-            .expect("memoryUsage check");
-        assert_eq!(mem["status"], "ok");
-        assert_eq!(mem["thresholdBytes"], u64::MAX);
+        let mem = checks.iter().find(|c| c["name"] == "memoryUsage");
         if cfg!(target_os = "linux") {
+            let mem = mem.expect("memoryUsage check present on Linux");
+            assert_eq!(mem["status"], "ok");
+            assert_eq!(mem["thresholdBytes"], u64::MAX);
             assert!(mem["rssBytes"].as_u64().is_some());
+        } else {
+            assert!(mem.is_none(), "memoryUsage should be absent on non-Linux");
         }
     }
 }