Add support for startup_timeout.

Author: samuel-williams-shopify

async-service.gemspec

@@ -27,6 +27,6 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = ">= 3.2"
 
 	spec.add_dependency "async"
-	spec.add_dependency "async-container", "~> 0.16"
+	spec.add_dependency "async-container", "~> 0.28"
 	spec.add_dependency "string-format", "~> 0.2"
 end

guides/best-practices/readme.md

@@ -208,6 +208,7 @@ class WebService < Async::Service::ManagedService
 	# Managed::Service automatically handles:
 	# - Container setup with proper options.
 	# - Health checking with process title updates.
+	# - Status messages during startup to prevent premature timeouts.
 	# - Preloading of scripts before startup.
 
 	private def format_title(evaluator, server)
@@ -222,6 +223,28 @@ class WebService < Async::Service::ManagedService
 end
 ```
 
+### Configure Timeouts for Slow-Starting Services
+
+If your service takes a long time to start up (e.g., loading large datasets, connecting to external services), configure appropriate timeouts:
+
+```ruby
+module WebEnvironment
+	include Async::Service::ManagedEnvironment
+	
+	# Allow 2 minutes for startup.
+	def startup_timeout
+		120
+	end
+	
+	# Require health checks every 30 seconds.
+	def health_check_timeout
+		30
+	end
+end
+```
+
+The `startup_timeout` ensures processes that hang during startup are detected, while `health_check_timeout` monitors processes after they've become ready. `ManagedService` automatically sends `status!` messages during startup to keep the health check clock resetting until the service is ready.
+
 ### Implement Meaningful Process Titles
 
 Use the `format_title` method to provide dynamic process information:

guides/service-architecture/readme.md

@@ -262,20 +262,25 @@ end
 
 ### Health Checking
 
-For services using `Async::Service::ManagedService`, health checking is handled automatically. For services extending `GenericService`, you can set up health checking manually:
+For services using `Async::Service::ManagedService`, health checking is handled automatically. The service sends `status!` messages during startup to prevent premature health check timeouts, then transitions to sending `ready!` messages once the service is actually ready.
+
+For services extending `GenericService`, you can set up health checking manually:
 
 ```ruby
 def setup(container)
 	container_options = @evaluator.container_options
 	health_check_timeout = container_options[:health_check_timeout]
 
 	container.run(**container_options) do |instance|
+		# Send status updates during startup:
+		instance.status!("Preparing...")
 		# Prepare your service.
 
 		Async do
 			# Start your service.
+			instance.status!("Starting...")
 
-			# Set up health checking, if a timeout was specified:
+			# Once ready, set up health checking:
 			health_checker(instance, health_check_timeout) do
 				instance.name = "#{self.name}: #{current_status}"
 			end
@@ -284,6 +289,30 @@ def setup(container)
 end
 ```
 
+#### Startup Timeout vs Health Check Timeout
+
+The container supports two separate timeout mechanisms:
+
+- **`startup_timeout`**: Maximum time a process can take to become ready (call `ready!`) before being terminated. This detects processes that hang during startup and never become ready.
+- **`health_check_timeout`**: Maximum time between health check messages after the process has become ready. This detects processes that stop responding after they've started.
+
+Both timeouts use a single clock that starts when the process starts. The clock resets when the process becomes ready, transitioning from startup timeout monitoring to health check timeout monitoring.
+
+You can configure these timeouts via `container_options`:
+
+```ruby
+module WebEnvironment
+	include Async::Service::ManagedEnvironment
+	
+	def container_options
+		super.merge(
+			startup_timeout: 60,      # Allow up to 60 seconds for startup.
+			health_check_timeout: 30  # Require health checks every 30 seconds after ready.
+		)
+	end
+end
+```
+
 Note: `Async::Service::ManagedService` automatically handles health checking, container options, and process title formatting, so you typically don't need to set this up manually.
 
 ## How They Work Together

lib/async/service/managed_environment.rb

@@ -16,6 +16,13 @@ def count
 				nil
 			end
 
+			# The timeout duration for the startup. Set to `nil` to disable the startup timeout.
+			#
+			# @returns [Numeric | nil] The startup timeout in seconds.
+			def startup_timeout
+				nil
+			end
+
 			# The timeout duration for the health check. Set to `nil` to disable the health check.
 			#
 			# @returns [Numeric | nil] The health check timeout in seconds.
@@ -30,6 +37,7 @@ def container_options
 				{
 					restart: true,
 					count: self.count,
+					startup_timeout: self.startup_timeout,
 					health_check_timeout: self.health_check_timeout,
 				}.compact
 			end

lib/async/service/managed_service.rb

@@ -74,12 +74,12 @@ def setup(container)
 					Async do
 						evaluator = self.environment.evaluator
 
+						instance.status!("Preparing...")
 						evaluator.prepare!(instance)
-						
 						emit_prepared(instance, start_time)
 
+						instance.status!("Running...")
 						server = run(instance, evaluator)
-						
 						emit_running(instance, start_time)
 
 						health_checker(instance) do

releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## Unreleased
+
+- `ManagedService` now sends `status!` messages during startup to prevent premature health check timeouts for slow-starting services.
+- Support for `startup_timeout` option via `container_options` to detect processes that hang during startup and never become ready.
+
 ## v0.16.0
 
   - Renamed `Async::Service::Generic` -\> `Async::Service::GenericService`, added compatibilty alias.

test/async/service/managed_service.rb

@@ -77,6 +77,10 @@ def mock_instance.ready!
 				@ready_called = true
 			end
 
+			def mock_instance.status!(text)
+				# status! is called during startup but doesn't need to be tracked
+			end
+			
 			def mock_instance.ready_called?
 				@ready_called || false
 			end