async-service 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dc20befccfdbe1d36db11898e11a469ff64f2338a7b88942d59cb58e0e8c92f
-  data.tar.gz: c2a09fad50e09a6188e30b213d921f832ac14706c8f23d721269e4e48cffe028
+  metadata.gz: 6e9258424ee834d70b309984ba6f2d0c89f87ed9b2a16ec38fb298dfafb33fcd
+  data.tar.gz: e91b2129702c7c8ad7f3203063d3dd526b8e6e91d322bb84388afe873cf638f0
 SHA512:
-  metadata.gz: ef436a78425bfab299e187e37e81f6d442dd00ffbff6c3e526c94d5753395e03158219d3b92d7e3edec4a68babf277fc97448d2a18991b6ab1d79cfdd6cafb74
-  data.tar.gz: 59468d0b53c26be506a8c4195cae58c91627352ebf09555bdcbf539d166c66d97f4c6a9ad3969fd0e8251f857cc058e4ad69e322ece8cd585b0579c0fbc44d69
+  metadata.gz: edc78ce3ff189ef951f19b206d02bbef4f2c121b10e24f074b6a7eab702c6ffeceb5e47c7c29d330363c7389c721b371c4584f33b9145cde42b798ec08e47237
+  data.tar.gz: be8a666be488d9d428339edea966834c0a7d5e935bcf330b8669f914b58661ed11deff0782b4202327951b108063992e5ac6f4fb9427beca5d6c1daaf09f440a

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/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/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,32 @@ 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
-
+			
+			# 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 start_time [Async::Clock] The monotonic start time from {Async::Clock.start}.
 			def emit_prepared(instance, start_time)
+				# Override in subclasses as needed.
 			end
-
+			
+			# 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 start_time [Async::Clock] The monotonic start time from {Async::Clock.start}.
 			def emit_running(instance, start_time)
+				# Override in subclasses as needed.
 			end
 			
 			# Set up the container with health checking and process title formatting.
@@ -70,16 +84,16 @@ module Async
 				
 				container.run(**container_options) do |instance|
 					start_time = Async::Clock.start
-
+					
 					Async do
 						evaluator = self.environment.evaluator
 						
+						instance.status!("Preparing...")
 						evaluator.prepare!(instance)
-						
 						emit_prepared(instance, start_time)
-
-						server = run(instance, evaluator)
 						
+						instance.status!("Running...")
+						server = run(instance, evaluator)
 						emit_running(instance, start_time)
 						
 						health_checker(instance) do

data/lib/async/service/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Service
-		VERSION = "0.16.0"
+		VERSION = "0.17.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,11 @@ 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.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.
@@ -72,10 +77,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
   - 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,10 @@
 # Releases
 
+## 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.17.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.28'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.28'
 - !ruby/object:Gem::Dependency
   name: string-format
   requirement: !ruby/object:Gem::Requirement
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A service layer for Async.
 test_files: []