feat: fail initialization when a configured sync-init readiness timeout expires

check_init_health now returns Result; a set AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS
that expires during synchronous cold-start init fails init (refuses to serve)
instead of admitting traffic to a never-ready app. Unset stays unbounded/non-fatal;
async_init keeps its own non-fatal ~9.8s bound.

Author: bnusunny

CHANGELOG.md

@@ -20,10 +20,13 @@
 - Add `AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS` to bound the readiness check
   (fractional seconds allowed, e.g. `0.5`), applied to both the initial cold-start
   readiness wait and the
-  post-SnapStart-restore readiness check. When unset (the default) the wait is
+  post-SnapStart-restore readiness check. When set and the app does not become
+  ready within it, the adapter **refuses to serve**: cold-start init fails (the
+  runtime never starts) and a restore fails, rather than admitting traffic to an
+  app that never reported ready. When unset (the default) the wait is
   **unbounded**, matching the previous behavior, so existing slow-cold-start apps
   are unaffected unless they opt in. The `async_init` initial-readiness path keeps
-  its own fixed ~9.8s bound and is not affected by this variable.
+  its own fixed ~9.8s bound (non-fatal) and is not affected by this variable.
 
 ### Bug Fixes
 

src/lib.rs

@@ -33,7 +33,7 @@
 //!         let mut adapter = Adapter::new(&options)?;
 //!         
 //!         adapter.register_default_extension();
-//!         adapter.check_init_health().await;
+//!         adapter.check_init_health().await?;
 //!         adapter.run().await
 //!     })
 //! }
@@ -714,7 +714,7 @@ fn matches_hook_path(configured: &Option<String>, request_path: &str) -> bool {
 /// let mut adapter = Adapter::new(&options)?;
 ///
 /// adapter.register_default_extension();
-/// adapter.check_init_health().await;
+/// adapter.check_init_health().await?;
 /// adapter.run().await
 /// # }
 /// ```
@@ -969,7 +969,17 @@ impl Adapter<HttpConnector, Body> {
     /// - Allow the application to continue booting in the background
     ///
     /// The first request will re-check readiness if the application wasn't ready
-    /// during initialization.
+    /// during initialization. The async path always returns `Ok`.
+    ///
+    /// # Synchronous Initialization
+    ///
+    /// Without `async_init`, this waits for the app to report ready before the
+    /// Lambda runtime starts serving. If `readiness_check_timeout`
+    /// (`AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS`) is set and the app does not
+    /// become ready within it, this returns `Err`: init fails and no traffic is
+    /// served against an app that never came up. When the timeout is unset the
+    /// wait is unbounded and this returns `Ok` once the check completes
+    /// (historical behavior).
     ///
     /// # Examples
     ///
@@ -979,25 +989,38 @@ impl Adapter<HttpConnector, Body> {
     /// # async fn example() -> Result<(), lambda_web_adapter::Error> {
     /// let options = AdapterOptions::default();
     /// let mut adapter = Adapter::new(&options)?;
-    /// adapter.check_init_health().await;
+    /// adapter.check_init_health().await?;
     /// # Ok(())
     /// # }
     /// ```
-    pub async fn check_init_health(&mut self) {
+    pub async fn check_init_health(&mut self) -> Result<(), Error> {
         let ready_at_init = if self.async_init {
             // async_init keeps its own fixed bound, independent of
             // readiness_check_timeout (see AdapterOptions::readiness_check_timeout).
+            // A timeout here is non-fatal: the app keeps booting and the first
+            // request re-checks readiness.
             timeout(Duration::from_secs_f32(9.8), self.check_readiness())
                 .await
                 .unwrap_or_default()
         } else if let Some(t) = self.readiness_check_timeout {
-            // Bound the sync-init readiness wait when configured; unset = unbounded
-            // (historical behavior), so an unset value never fails a slow cold start.
-            timeout(t, self.check_readiness()).await.unwrap_or_default()
+            // Bound the sync-init readiness wait when configured. On expiry, refuse
+            // to serve: fail init rather than admit traffic to an app that never
+            // reported ready — this is the point of configuring the bound.
+            match timeout(t, self.check_readiness()).await {
+                Ok(ready) => ready,
+                Err(_) => {
+                    return Err(Error::from(format!(
+                        "web application did not become ready within {t:?} \
+                         (AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS); failing initialization"
+                    )));
+                }
+            }
         } else {
+            // Unset: unbounded wait, non-fatal result (historical behavior).
             self.check_readiness().await
         };
         self.ready_at_init.store(ready_at_init, Ordering::SeqCst);
+        Ok(())
     }
 
     /// Performs a single readiness check against the configured endpoint.
@@ -1512,6 +1535,36 @@ mod tests {
         healthcheck.assert();
     }
 
+    #[tokio::test]
+    async fn test_check_init_health_fails_when_sync_init_readiness_timeout_expires() {
+        // App server that never reports ready (always 500) so the readiness
+        // retry loop runs until the configured timeout fires.
+        let app_server = MockServer::start();
+        app_server.mock(|when, then| {
+            when.method(GET).path("/healthcheck");
+            then.status(500).body("nope");
+        });
+
+        // Sync init (async_init defaults to false) with a short configured bound.
+        let options = AdapterOptions {
+            host: app_server.host(),
+            port: app_server.port().to_string(),
+            readiness_check_port: app_server.port().to_string(),
+            readiness_check_path: "/healthcheck".to_string(),
+            readiness_check_timeout: Some(Duration::from_millis(100)),
+            ..Default::default()
+        };
+
+        let mut adapter = Adapter::new(&options).expect("Failed to create adapter");
+
+        // Refuse to serve: a configured timeout that expires fails initialization.
+        let result = adapter.check_init_health().await;
+        assert!(
+            result.is_err(),
+            "sync-init readiness timeout should fail init, got {result:?}"
+        );
+    }
+
     #[tokio::test]
     async fn test_status_403_is_bad_when_configured() {
         // Start app server

src/main.rs

@@ -30,7 +30,7 @@ async fn async_main() -> Result<(), Error> {
     // register the adapter as an extension
     adapter.register_default_extension();
     // check if the web application is ready
-    adapter.check_init_health().await;
+    adapter.check_init_health().await?;
     // start lambda runtime after the web application is ready
     adapter.run().await?;
 

tests/integ_tests/main.rs

@@ -135,7 +135,10 @@ async fn test_http_readiness_check() {
 
     // Initialize adapter and do readiness check
     let mut adapter = Adapter::new(&options).expect("Failed to create adapter");
-    adapter.check_init_health().await;
+    adapter
+        .check_init_health()
+        .await
+        .expect("init health check should succeed");
 
     // Assert app server's healthcheck endpoint got called
     healthcheck.assert();
@@ -1109,7 +1112,10 @@ async fn test_http_async_init_ready_at_init() {
     .expect("Failed to create adapter");
 
     // Perform init health check — app is already running so it should succeed
-    adapter.check_init_health().await;
+    adapter
+        .check_init_health()
+        .await
+        .expect("init health check should succeed");
 
     healthcheck.assert();
 
@@ -1142,7 +1148,10 @@ async fn test_http_tcp_readiness_check() {
     .expect("Failed to create adapter");
 
     // TCP readiness check should succeed since MockServer is listening
-    adapter.check_init_health().await;
+    adapter
+        .check_init_health()
+        .await
+        .expect("init health check should succeed");
 
     // Now verify the adapter can still forward requests
     let hello = app_server.mock(|when, then| {