async-service 0.15.1 → 0.17.0

data/lib/async/service/generic.rb

@@ -3,63 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
 
+# Compatibility shim for Async::Service::Generic
+# Use Async::Service::GenericService instead
+require_relative "generic_service"
+
 module Async
 	module Service
-		# Captures the stateful behaviour of a specific service.
-		# Specifies the interfaces required by derived classes.
-		#
-		# Designed to be invoked within an {Async::Controller::Container}.
-		class Generic
-			# Convert the given environment into a service if possible.
-			# @parameter environment [Environment] The environment to use to construct the service.
-			# @returns [Generic | Nil] The constructed service if the environment specifies a service class.
-			def self.wrap(environment)
-				evaluator = environment.evaluator
-				
-				if evaluator.key?(:service_class)
-					if service_class = evaluator.service_class
-						return service_class.new(environment, evaluator)
-					end
-				end
-			end
-			
-			# Initialize the service from the given environment.
-			# @parameter environment [Environment]
-			def initialize(environment, evaluator = environment.evaluator)
-				@environment = environment
-				@evaluator = evaluator
-			end
-			
-			# @attribute [Environment] The environment which is used to configure the service.
-			attr :environment
-			
-			# Convert the service evaluator to a hash.
-			# @returns [Hash] A hash representation of the evaluator.
-			def to_h
-				@evaluator.to_h
-			end
-			
-			# The name of the service - used for informational purposes like logging.
-			# e.g. `myapp.com`.
-			def name
-				@evaluator.name
-			end
-			
-			# Start the service. Called before the container setup.
-			def start
-				Console.debug(self){"Starting service #{self.name}..."}
-			end
-			
-			# Setup the service into the specified container.
-			# @parameter container [Async::Container::Generic]
-			def setup(container)
-				Console.debug(self){"Setting up service #{self.name}..."}
-			end
-			
-			# Stop the service. Called after the container is stopped.
-			def stop(graceful = true)
-				Console.debug(self){"Stopping service #{self.name}..."}
-			end
-		end
+		# @deprecated Use {GenericService} instead.
+		Generic = GenericService
 	end
 end

data/lib/async/service/generic_service.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Async
+	module Service
+		# Captures the stateful behaviour of a specific service.
+		# Specifies the interfaces required by derived classes.
+		#
+		# Designed to be invoked within an {Async::Controller::Container}.
+		class GenericService
+			# Convert the given environment into a service if possible.
+			# @parameter environment [Environment] The environment to use to construct the service.
+			# @returns [GenericService | Nil] The constructed service if the environment specifies a service class.
+			def self.wrap(environment)
+				evaluator = environment.evaluator
+				
+				if evaluator.key?(:service_class)
+					if service_class = evaluator.service_class
+						return service_class.new(environment, evaluator)
+					end
+				end
+			end
+			
+			# Initialize the service from the given environment.
+			# @parameter environment [Environment]
+			def initialize(environment, evaluator = environment.evaluator)
+				@environment = environment
+				@evaluator = evaluator
+			end
+			
+			# @attribute [Environment] The environment which is used to configure the service.
+			attr :environment
+			
+			# Convert the service evaluator to a hash.
+			# @returns [Hash] A hash representation of the evaluator.
+			def to_h
+				@evaluator.to_h
+			end
+			
+			# The name of the service - used for informational purposes like logging.
+			# e.g. `myapp.com`.
+			def name
+				@evaluator.name
+			end
+			
+			# Start the service. Called before the container setup.
+			def start
+				Console.debug(self){"Starting service #{self.name}..."}
+			end
+			
+			# Setup the service into the specified container.
+			# @parameter container [Async::Container::Generic]
+			def setup(container)
+				Console.debug(self){"Setting up service #{self.name}..."}
+			end
+			
+			# Stop the service. Called after the container is stopped.
+			def stop(graceful = true)
+				Console.debug(self){"Stopping service #{self.name}..."}
+			end
+		end
+	end
+end

data/lib/async/service/health_checker.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Service
+		# A health checker for managed services.
+		module HealthChecker
+			# Start the health checker.
+			#
+			# If a timeout is specified, a transient child task will be scheduled, which will yield the instance if a block is given, then mark the instance as ready, and finally sleep for half the health check duration (so that we guarantee that the health check runs in time).
+			#
+			# If a timeout is not specified, the health checker will yield the instance immediately and then mark the instance as ready.
+			#
+			# @parameter instance [Object] The service instance to check.
+			# @parameter timeout [Numeric] The timeout duration for the health check.
+			# @parameter parent [Async::Task] The parent task to run the health checker in.
+			# @yields {|instance| ...} If a block is given, it will be called with the service instance at least once.
+			def health_checker(instance, timeout = @evaluator.health_check_timeout, parent: Async::Task.current, &block)
+				if timeout
+					parent.async(transient: true) do
+						while true
+							if block_given?
+								yield(instance)
+							end
+							
+							# 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!
+							end.resume
+							
+							sleep(timeout / 2)
+						end
+					end
+				else
+					if block_given?
+						yield(instance)
+					end
+					
+					instance.ready!
+				end
+			end
+		end
+	end
+end
+

data/lib/async/service/managed_environment.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+module Async
+	module Service
+		# Default configuration for managed services.
+		#
+		# This is provided not because it is required, but to offer a sensible default for production services, and to expose a consistent interface for service configuration.
+		module ManagedEnvironment
+			# Number of instances to start. By default, when `nil`, uses `Etc.nprocessors`.
+			#
+			# @returns [Integer | nil] The number of instances to start, or `nil` to use the default.
+			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.
+			def health_check_timeout
+				30
+			end
+			
+			# Options to use when creating the container, including `restart`, `count`, and `health_check_timeout`.
+			#
+			# @returns [Hash] The options for the container.
+			def container_options
+				{
+					restart: true,
+					count: self.count,
+					startup_timeout: self.startup_timeout,
+					health_check_timeout: self.health_check_timeout,
+				}.compact
+			end
+			
+			# Any scripts to preload before starting the service.
+			#
+			# @returns [Array(String)] The list of scripts to preload.
+			def preload
+				[]
+			end
+			
+			# General tags for metrics, traces and logging.
+			#
+			# @returns [Array(String)] The tags for the service.
+			def tags
+				[]
+			end
+			
+			# Prepare the instance for running the service.
+			#
+			# This is called before {Async::Service::ManagedService#run}.
+			#
+			# @parameter instance [Object] The container instance.
+			def prepare!(instance)
+				# No preparation required by default.
+			end
+		end
+	end
+end
+

data/lib/async/service/managed_service.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "generic_service"
+require_relative "health_checker"
+
+module Async
+	module Service
+		# A managed service with built-in health checking, restart policies, and process title formatting.
+		#
+		# This is the recommended base class for most services that need robust lifecycle management.
+		class ManagedService < GenericService
+			include HealthChecker
+			
+			private def format_title(evaluator, server)
+				"#{evaluator.name} #{server.to_s}"
+			end
+			
+			# Run the service logic.
+			#
+			# Override this method to implement your service. Return an object that represents the running service (e.g., a server, task, or worker pool) for health checking.
+			#
+			# @parameter instance [Object] The container instance.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @returns [Object] The service object (server, task, etc.)
+			def run(instance, evaluator)
+				Async do
+					sleep
+				end
+			end
+			
+			# Preload any resources specified by the environment.
+			def preload!
+				if scripts = @evaluator.preload
+					root = @evaluator.root
+					scripts = Array(scripts)
+					
+					scripts.each do |path|
+						Console.info(self){"Preloading #{path}..."}
+						full_path = File.expand_path(path, root)
+						require(full_path)
+					end
+				end
+			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.
+			# @parameter container [Async::Container] The container to configure.
+			def setup(container)
+				super
+				
+				container_options = @evaluator.container_options
+				health_check_timeout = container_options[:health_check_timeout]
+				
+				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)
+						
+						instance.status!("Running...")
+						server = run(instance, evaluator)
+						emit_running(instance, start_time)
+						
+						health_checker(instance) do
+							instance.name = format_title(evaluator, server)
+						end
+					end
+				end
+			end
+		end
+	end
+end
+

data/lib/async/service/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Service
-		VERSION = "0.15.1"
+		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

@@ -23,10 +23,23 @@ Please see the [project documentation](https://socketry.github.io/async-service/
 
   - [Best Practices](https://socketry.github.io/async-service/guides/best-practices/index) - This guide outlines recommended patterns and practices for building robust, maintainable services with `async-service`.
 
+  - [Deployment](https://socketry.github.io/async-service/guides/deployment/index) - This guide explains how to deploy `async-service` applications using systemd and Kubernetes. We'll use a simple example service to demonstrate deployment configurations.
+
 ## Releases
 
 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.
+  - Renamed `Async::Service::Managed::Service` -\> `Async::Service::ManagedService`.
+  - Renamed `Async::Service::Managed::Environment` -\> `Async::Service::ManagedEnvironment`.
+
 ### v0.15.1
 
   - `Managed::Service` should run within `Async do ... end`.
@@ -64,14 +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.
-
-### v0.8.0
-
-  - Introduce `Environment#implements?` and related methods for interface checking.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,16 @@
 # 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.
+  - Renamed `Async::Service::Managed::Service` -\> `Async::Service::ManagedService`.
+  - Renamed `Async::Service::Managed::Environment` -\> `Async::Service::ManagedEnvironment`.
+
 ## v0.15.1
 
   - `Managed::Service` should run within `Async do ... end`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  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
@@ -87,6 +87,7 @@ extra_rdoc_files: []
 files:
 - bin/async-service
 - context/best-practices.md
+- context/deployment.md
 - context/getting-started.md
 - context/index.yaml
 - context/service-architecture.md
@@ -96,11 +97,11 @@ files:
 - lib/async/service/environment.rb
 - lib/async/service/formatting.rb
 - lib/async/service/generic.rb
+- lib/async/service/generic_service.rb
+- lib/async/service/health_checker.rb
 - lib/async/service/loader.rb
-- lib/async/service/managed.rb
-- lib/async/service/managed/environment.rb
-- lib/async/service/managed/health_checker.rb
-- lib/async/service/managed/service.rb
+- lib/async/service/managed_environment.rb
+- lib/async/service/managed_service.rb
 - lib/async/service/version.rb
 - license.md
 - readme.md
@@ -125,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: []

data/lib/async/service/managed/environment.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-module Async
-	module Service
-		module Managed
-			# Default configuration for managed services.
-			#
-			# This is provided not because it is required, but to offer a sensible default for production services, and to expose a consistent interface for service configuration.
-			module Environment
-				# Number of instances to start. By default, when `nil`, uses `Etc.nprocessors`.
-				#
-				# @returns [Integer | nil] The number of instances to start, or `nil` to use the default.
-				def count
-					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.
-				def health_check_timeout
-					30
-				end
-				
-				# Options to use when creating the container, including `restart`, `count`, and `health_check_timeout`.
-				#
-				# @returns [Hash] The options for the container.
-				def container_options
-					{
-						restart: true,
-						count: self.count,
-						health_check_timeout: self.health_check_timeout,
-					}.compact
-				end
-				
-				# Any scripts to preload before starting the service.
-				#
-				# @returns [Array(String)] The list of scripts to preload.
-				def preload
-					[]
-				end
-			end
-		end
-	end
-end
-

data/lib/async/service/managed/health_checker.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-module Async
-	module Service
-		module Managed
-			# A health checker for managed services.
-			module HealthChecker
-				# Start the health checker.
-				#
-				# If a timeout is specified, a transient child task will be scheduled, which will yield the instance if a block is given, then mark the instance as ready, and finally sleep for half the health check duration (so that we guarantee that the health check runs in time).
-				#
-				# If a timeout is not specified, the health checker will yield the instance immediately and then mark the instance as ready.
-				#
-				# @parameter instance [Object] The service instance to check.
-				# @parameter timeout [Numeric] The timeout duration for the health check.
-				# @parameter parent [Async::Task] The parent task to run the health checker in.
-				# @yields {|instance| ...} If a block is given, it will be called with the service instance at least once.
-				def health_checker(instance, timeout = @evaluator.health_check_timeout, parent: Async::Task.current, &block)
-					if timeout
-						parent.async(transient: true) do
-							while true
-								if block_given?
-									yield(instance)
-								end
-								
-								# 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!
-								end.resume
-								
-								sleep(timeout / 2)
-							end
-						end
-					else
-						if block_given?
-							yield(instance)
-						end
-						
-						instance.ready!
-					end
-				end
-			end
-		end
-	end
-end

data/lib/async/service/managed/service.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "../generic"
-require_relative "../formatting"
-require_relative "health_checker"
-
-module Async
-	module Service
-		module Managed
-			# A managed service with built-in health checking, restart policies, and process title formatting.
-			#
-			# This is the recommended base class for most services that need robust lifecycle management.
-			class Service < Generic
-				include Formatting
-				include HealthChecker
-				
-				private def format_title(evaluator, server)
-					"#{evaluator.name} #{server.to_s}"
-				end
-				
-				# Run the service logic.
-				#
-				# Override this method to implement your service. Return an object that represents the running service (e.g., a server, task, or worker pool) for health checking.
-				#
-				# @parameter instance [Object] The container instance.
-				# @parameter evaluator [Environment::Evaluator] The environment evaluator.
-				# @returns [Object] The service object (server, task, etc.)
-				def run(instance, evaluator)
-					Async do
-						sleep
-					end
-				end
-				
-				# Preload any resources specified by the environment.
-				def preload!
-					if scripts = @evaluator.preload
-						root = @evaluator.root
-						scripts = Array(scripts)
-						
-						scripts.each do |path|
-							Console.info(self){"Preloading #{path}..."}
-							full_path = File.expand_path(path, root)
-							require(full_path)
-						end
-					end
-				rescue StandardError, LoadError => error
-					Console.warn(self, "Service preload failed!", error)
-				end
-			
-				# Start the service, including preloading resources.
-				def start
-					preload!
-					
-					super
-				end
-				
-				# Set up the container with health checking and process title formatting.
-				# @parameter container [Async::Container] The container to configure.
-				def setup(container)
-					super
-					
-					container_options = @evaluator.container_options
-					health_check_timeout = container_options[:health_check_timeout]
-					
-					container.run(**container_options) do |instance|
-						Async do
-							evaluator = self.environment.evaluator
-							
-							server = run(instance, evaluator)
-							
-							health_checker(instance) do
-								instance.name = format_title(evaluator, server)
-							end
-						end
-					end
-				end
-			end
-		end
-	end
-end