async-service 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dc20befccfdbe1d36db11898e11a469ff64f2338a7b88942d59cb58e0e8c92f
-  data.tar.gz: c2a09fad50e09a6188e30b213d921f832ac14706c8f23d721269e4e48cffe028
+  metadata.gz: a7fd9e53ca4f30c0166fb518aa104d292d67543377a6c93fa5df01b85148330d
+  data.tar.gz: ba8d1d6f6c994a40a7e7ff7536a81444faa9ebf01f087933a94ee1a3f590f6c0
 SHA512:
-  metadata.gz: ef436a78425bfab299e187e37e81f6d442dd00ffbff6c3e526c94d5753395e03158219d3b92d7e3edec4a68babf277fc97448d2a18991b6ab1d79cfdd6cafb74
-  data.tar.gz: 59468d0b53c26be506a8c4195cae58c91627352ebf09555bdcbf539d166c66d97f4c6a9ad3969fd0e8251f857cc058e4ad69e322ece8cd585b0579c0fbc44d69
+  metadata.gz: 74126e6fff458ce042d8233f148f8dd8042d8d26fce12bfea98a6d3622310bd5f8b3216344486391cdb9a60ee38416f6c3b2061228dc0fd2384c9034fddf53e1
+  data.tar.gz: 32572d45278190114e722909e14cd1d3bf3abcb66c17e5a70d97e4a0ed85ab0f323959e93a5b1bb46955897f9fc34ea6a2de66728b96ab43ed02321a2f94245c

data/context/best-practices.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:

data/context/service-architecture.md

@@ -262,7 +262,9 @@ 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)
@@ -270,12 +272,15 @@ def setup(container)
 	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

data/lib/async/service/configuration.rb

@@ -21,7 +21,12 @@ module Async
 				configuration = self.new
 				
 				loader = Loader.new(configuration, root)
-				loader.instance_eval(&block)
+				
+				if block.arity == 0
+					loader.instance_eval(&block)
+				else
+					yield loader
+				end
 				
 				return configuration
 			end

data/lib/async/service/generic_service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	module Service

data/lib/async/service/health_checker.rb

@@ -28,10 +28,10 @@ module Async
 							# We deliberately create a fiber here, to confirm that fiber creation is working.
 							# If something has gone wrong with fiber allocation, we will crash here, and that's okay.
 							Fiber.new do
-								instance.ready!
+								instance.healthy!
 							end.resume
 							
-							sleep(timeout / 2)
+							sleep(timeout / 2.0)
 						end
 					end
 				else
@@ -39,7 +39,7 @@ module Async
 						yield(instance)
 					end
 					
-					instance.ready!
+					instance.healthy!
 				end
 			end
 		end

data/lib/async/service/managed_environment.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	module Service
@@ -16,6 +16,13 @@ module Async
 				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 @@ module Async
 				{
 					restart: true,
 					count: self.count,
+					startup_timeout: self.startup_timeout,
 					health_check_timeout: self.health_check_timeout,
 				}.compact
 			end

data/lib/async/service/managed_service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "generic_service"
 require_relative "health_checker"
@@ -46,18 +46,34 @@ module Async
 			rescue StandardError, LoadError => error
 				Console.warn(self, "Service preload failed!", error)
 			end
-		
+			
 			# Start the service, including preloading resources.
 			def start
 				preload!
 				
 				super
 			end
-
-			def emit_prepared(instance, start_time)
+			
+			# Called after the service has been prepared but before it starts running.
+			#
+			# Override this method to emit metrics, logs, or perform other actions when the service preparation is complete.
+			#
+			# @parameter instance [Async::Container::Instance] The container instance.
+			# @parameter clock [Async::Clock] The monotonic start time from {Async::Clock.start}.
+			def emit_prepared(instance, clock)
+				# Override in subclasses as needed.
+				Console.info(self, "Prepared...", duration: clock.total)
 			end
-
-			def emit_running(instance, start_time)
+			
+			# Called after the service has started running.
+			#
+			# Override this method to emit metrics, logs, or perform other actions when the service begins running.
+			#
+			# @parameter instance [Async::Container::Instance] The container instance.
+			# @parameter clock [Async::Clock] The monotonic start time from {Async::Clock.start}.
+			def emit_running(instance, clock)
+				# Override in subclasses as needed.
+				Console.info(self, "Running...", duration: clock.total)
 			end
 			
 			# Set up the container with health checking and process title formatting.
@@ -69,22 +85,27 @@ module Async
 				health_check_timeout = container_options[:health_check_timeout]
 				
 				container.run(**container_options) do |instance|
-					start_time = Async::Clock.start
-
+					clock = Async::Clock.start
+					
 					Async do
 						evaluator = self.environment.evaluator
+						server = nil
+						
+						health_checker(instance, health_check_timeout) do
+							if server
+								instance.name = format_title(evaluator, server)
+							end
+						end
 						
+						instance.status!("Preparing...")
 						evaluator.prepare!(instance)
+						emit_prepared(instance, clock)
 						
-						emit_prepared(instance, start_time)
-
+						instance.status!("Running...")
 						server = run(instance, evaluator)
+						emit_running(instance, clock)
 						
-						emit_running(instance, start_time)
-						
-						health_checker(instance) do
-							instance.name = format_title(evaluator, server)
-						end
+						instance.ready!
 					end
 				end
 			end

data/lib/async/service/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Service
-		VERSION = "0.16.0"
+		VERSION = "0.18.0"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2024-2025, by Samuel Williams.  
+Copyright, 2024-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -29,6 +29,17 @@ Please see the [project documentation](https://socketry.github.io/async-service/
 
 Please see the [project releases](https://socketry.github.io/async-service/releases/index) for all releases.
 
+### v0.18.0
+
+  - Start health checker earlier in the process. Use `#healthy!` message instead of `#ready!`.
+  - Emit prepared and running log messages with durations (e.g. how long it took to transition to prepared and running states).
+  - `Async::Service::Configuration.build{|loader|...}` can now take an argument for more flexible configuration construction.
+
+### v0.17.0
+
+  - `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.
@@ -67,15 +78,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
 
   - Allow builder with argument for more flexible configuration construction.
 
-### v0.10.0
-
-  - Add `Environment::Evaluator#as_json` for JSON serialization support.
-  - Allow constructing a configuration with existing environments.
-
-### v0.9.0
-
-  - Allow providing a list of modules to include in environments.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,16 @@
 # Releases
 
+## v0.18.0
+
+  - Start health checker earlier in the process. Use `#healthy!` message instead of `#ready!`.
+  - Emit prepared and running log messages with durations (e.g. how long it took to transition to prepared and running states).
+  - `Async::Service::Configuration.build{|loader|...}` can now take an argument for more flexible configuration construction.
+
+## v0.17.0
+
+  - `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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.29'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.29'
 - !ruby/object:Gem::Dependency
   name: string-format
   requirement: !ruby/object:Gem::Requirement