async-service 0.18.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a133d45fe4dd738fa104a0df7d8ff74279856b7f9eeb1567b22e19eab58e4c0
-  data.tar.gz: 5c655ba303639dbb3040cc84b211ebf117b7bf45af044471ee9e3ab91397b36c
+  metadata.gz: 9b31f83d5dbdb36dfdf3e6be399d8ed560caedb465854a537a7c40741d121632
+  data.tar.gz: edae5fada2d9ebcd50b89a495df5901cd78a1c6eee94b270986592cf3ca79cfb
 SHA512:
-  metadata.gz: 136b018820c0227c4755803b82ad6857e059b48cf70e10b7fca4bfd793a16f8586ee0750ba314f18e8b3fb2b719998ca22d04fb110823a1b65c11c253e638ee5
-  data.tar.gz: 537237974adbfc334426e998a289f7ce48af50d82a9c8a443790207b801f068938374bde1683b4666daac94dd3c37b9feff9aa890a768e8e77c3bddc3ec70250
+  metadata.gz: 5a0fe39a4f3a4bba63ad3bfefcafaf068191e3db7e710d0a3a7eaf9a5f92601035431aa088a39163a70426ad31dd03302c609f3a25996593290df33aac2b46a9
+  data.tar.gz: 37fc1659dd3e2cc747dc01fa85915694b7952eda09d361c1e72977f07804471221be796a0339fc61a98180acdc8042cca7fe0f195afdb5337a2f6ffae3ac8522

data/context/best-practices.md

@@ -61,7 +61,7 @@ Place environments in `lib/my_library/environment/`:
 module MyLibrary
 	module Environment
 		module WebEnvironment
-			include Async::Service::ManagedEnvironment
+			include Async::Service::Managed::Environment
 			
 			def service_class
 				MyLibrary::Service::WebService
@@ -87,7 +87,7 @@ Place services in `lib/my_library/service/`:
 # lib/my_library/service/web_service.rb
 module MyLibrary
 	module Service
-		class WebService < Async::Service::ManagedService
+		class WebService < Async::Service::Managed::Service
 			private def format_title(evaluator, server)
 				if server&.respond_to?(:connection_count)
 					"#{self.name} [#{evaluator.host}:#{evaluator.port}] (#{server.connection_count} connections)"
@@ -114,7 +114,7 @@ end
 
 ### Use `Managed::Environment` for Services
 
-Include {ruby Async::Service::ManagedEnvironment} for services that need robust lifecycle management using {ruby Async::Service::ManagedService}:
+Include {ruby Async::Service::Managed::Environment} for services that need robust lifecycle management using {ruby Async::Service::Managed::Service}:
 
 ```ruby
 module WebEnvironment
@@ -201,7 +201,7 @@ end
 
 ### Use `Managed::Service` as Base Class
 
-Prefer `Async::Service::ManagedService` over `GenericService` for most services:
+Prefer `Async::Service::Managed::Service` over `Generic` for most services:
 
 ```ruby
 class WebService < Async::Service::ManagedService
@@ -243,7 +243,7 @@ module WebEnvironment
 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.
+The `startup_timeout` ensures processes that hang during startup are detected, while `health_check_timeout` monitors processes after they've become ready. `Managed::Service` automatically sends `status!` messages during startup to keep the health check clock resetting until the service is ready.
 
 ### Implement Meaningful Process Titles
 

data/context/deployment.md

@@ -14,7 +14,7 @@ require "async/http"
 require "async/service/managed_service"
 require "async/service/managed_environment"
 
-class WebService < Async::Service::ManagedService
+class WebService < Async::Service::Managed::Service
 	def start
 		super
 		@endpoint = @evaluator.endpoint
@@ -40,7 +40,7 @@ class WebService < Async::Service::ManagedService
 end
 
 module WebEnvironment
-	include Async::Service::ManagedEnvironment
+	include Async::Service::Managed::Environment
 	
 	def endpoint
 		Async::HTTP::Endpoint.parse("http://0.0.0.0:3000")

data/context/getting-started.md

@@ -14,13 +14,13 @@ $ bundle add async-service
 
 `async-service` has several core concepts:
 
-- A {ruby Async::Service::GenericService} which represents the base class for implementing services.
+- A {ruby Async::Service::Generic} which represents the base class for implementing services.
 - A {ruby Async::Service::Configuration} which manages service configurations and environments.
 - A {ruby Async::Service::Controller} which handles starting, stopping, and managing services.
 
 ## Usage
 
-Services are long-running processes that can be managed as a group. Each service extends `Async::Service::GenericService` and implements a `setup` method that defines how the service runs.
+Services are long-running processes that can be managed as a group. Each service extends `Async::Service::Generic` and implements a `setup` method that defines how the service runs.
 
 ### Basic Service
 
@@ -31,7 +31,7 @@ Create a simple service that runs continuously:
 
 require "async/service"
 
-class HelloService < Async::Service::GenericService
+class HelloService < Async::Service::Generic
 	def setup(container)
 		super
 		
@@ -73,7 +73,7 @@ end
 In your service implementation, you can access these values through the environment and evaluator:
 
 ```ruby
-class WebServerService < Async::Service::GenericService
+class WebServerService < Async::Service::Generic
 	def setup(container)
 		super
 		
@@ -103,7 +103,7 @@ You can define multiple services in a single configuration file:
 
 require "async/service"
 
-class WebService < Async::Service::GenericService
+class WebService < Async::Service::Generic
 	def setup(container)
 		super
 		
@@ -115,7 +115,7 @@ class WebService < Async::Service::GenericService
 	end
 end
 
-class WorkerService < Async::Service::GenericService
+class WorkerService < Async::Service::Generic
 	def setup(container)
 		super
 		

data/context/service-architecture.md

@@ -82,14 +82,14 @@ end
 
 ## Service
 
-The {ruby Async::Service::GenericService} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
+The {ruby Async::Service::Generic} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
 
 ### Business Logic
 
 Services contain the actual implementation of what your service does:
 
 ```ruby
-class WebService < Async::Service::GenericService
+class WebService < Async::Service::Generic
 	def setup(container)
 		super
 		
@@ -148,7 +148,7 @@ By evaluating the log_path in the child process, you ensure that each instance h
 Services define their startup, running, and shutdown behavior:
 
 ```ruby
-class MyService < Async::Service::GenericService
+class MyService < Async::Service::Generic
 	def start
 		super
 		# Service-specific startup logic including pre-loading libraries and binding to network interfaces before forking.
@@ -262,9 +262,9 @@ end
 
 ### Health Checking
 
-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 using `Async::Service::Managed::Service`, 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:
+For services extending `Generic`, you can set up health checking manually:
 
 ```ruby
 def setup(container)
@@ -302,7 +302,7 @@ You can configure these timeouts via `container_options`:
 
 ```ruby
 module WebEnvironment
-	include Async::Service::ManagedEnvironment
+	include Async::Service::Managed::Environment
 	
 	def container_options
 		super.merge(
@@ -313,7 +313,7 @@ module WebEnvironment
 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.
+Note: `Async::Service::Managed::Service` 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
 
@@ -334,7 +334,7 @@ end
 
 ```ruby
 # Services are defined using environments:
-class WebService < Async::Service::GenericService
+class WebService < Async::Service::Generic
 	def setup(container)
 		super
 		
@@ -469,7 +469,7 @@ Create reusable configuration modules:
 
 ```ruby
 module ManagedEnvironment
-	include Async::Service::ManagedEnvironment
+	include Async::Service::Managed::Environment
 	
 	def count
 		4
@@ -493,7 +493,7 @@ end
 Build service hierarchies:
 
 ```ruby
-class BaseWebService < Async::Service::GenericService
+class BaseWebService < Async::Service::Generic
 	def setup(container)
 		super
 		# Common web service setup

data/lib/async/service/configuration.rb

@@ -75,7 +75,7 @@ module Async
 				
 				@environments.each do |environment|
 					if implementing.nil? or environment.implements?(implementing)
-						if service = GenericService.wrap(environment)
+						if service = Generic.wrap(environment)
 							yield service
 						end
 					end

data/lib/async/service/controller.rb

@@ -42,7 +42,7 @@ module Async
 			end
 			
 			# Create a controller for the given services.
-			# @parameter services [Array(GenericService)] The services to control.
+			# @parameter services [Array(Generic)] The services to control.
 			# @parameter options [Hash] Additional options for the controller.
 			# @returns [Controller] A new controller instance.
 			def self.for(*services, **options)
@@ -50,7 +50,7 @@ module Async
 			end
 			
 			# Initialize a new controller with services.
-			# @parameter services [Array(GenericService)] The services to manage.
+			# @parameter services [Array(Generic)] The services to manage.
 			# @parameter options [Hash] Options passed to the parent controller.
 			def initialize(services, **options)
 				super(**options)
@@ -59,7 +59,7 @@ module Async
 			end
 			
 			# All the services associated with this controller.
-			# @attribute [Array(Async::Service::GenericService)] 
+			# @attribute [Array(Async::Service::Generic)]
 			attr :services
 			
 			# Start all named services.

data/lib/async/service/generic.rb

@@ -1,15 +1,65 @@
 # frozen_string_literal: true
 
 # 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"
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	module Service
-		# @deprecated Use {GenericService} instead.
-		Generic = GenericService
+		# 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
 	end
 end

data/lib/async/service/generic_service.rb

@@ -1,65 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
+
+# Compatibility shim for Async::Service::GenericService
+# Use Async::Service::Generic instead
+require_relative "generic"
 
 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
+		# @deprecated Use {Generic} instead.
+		GenericService = Generic
 	end
 end

data/lib/async/service/health_checker.rb

@@ -1,48 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
+
+# Compatibility shim for Async::Service::HealthChecker
+# Use Async::Service::Managed::HealthChecker instead
+require_relative "managed/health_checker"
 
 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.healthy!
-							end.resume
-							
-							sleep(timeout / 2.0)
-						end
-					end
-				else
-					if block_given?
-						yield(instance)
-					end
-					
-					instance.healthy!
-				end
-			end
-		end
+		# @deprecated Use {Managed::HealthChecker} instead.
+		HealthChecker = Managed::HealthChecker
 	end
 end
 

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, 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 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::Managed::Service#run}.
+				#
+				# @parameter instance [Object] The container instance.
+				def prepare!(instance)
+					# No preparation required by default.
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, 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.healthy!
+								end.resume
+								
+								sleep(timeout / 2.0)
+							end
+						end
+					else
+						if block_given?
+							yield(instance)
+						end
+						
+						instance.healthy!
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025-2026, by Samuel Williams.
+
+require_relative "../generic"
+require_relative "health_checker"
+
+module Async
+	module Service
+		# @namespace
+		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 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 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
+				
+				# 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.
+				# @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|
+						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)
+							
+							instance.status!("Running...")
+							server = run(instance, evaluator)
+							emit_running(instance, clock)
+							
+							instance.ready!
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/service/managed_environment.rb

@@ -1,70 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
+
+# Compatibility shim for Async::Service::ManagedEnvironment
+# Use Async::Service::Managed::Environment instead
+require_relative "managed/environment"
 
 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
+		# @deprecated Use {Managed::Environment} instead.
+		ManagedEnvironment = Managed::Environment
 	end
 end
 

data/lib/async/service/managed_service.rb

@@ -1,115 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative "generic_service"
-require_relative "health_checker"
+# Compatibility shim for Async::Service::ManagedService
+# Use Async::Service::Managed::Service instead
+require_relative "managed/service"
 
 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 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
-			
-			# 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.
-			# @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|
-					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)
-						
-						instance.status!("Running...")
-						server = run(instance, evaluator)
-						emit_running(instance, clock)
-						
-						instance.ready!
-					end
-				end
-			end
-		end
+		# @deprecated Use {Managed::Service} instead.
+		ManagedService = Managed::Service
 	end
 end
 

data/lib/async/service/version.rb

@@ -3,8 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module Service
-		VERSION = "0.18.1"
+		VERSION = "0.19.0"
 	end
 end

data/lib/async/service.rb

@@ -6,10 +6,3 @@
 require_relative "service/configuration"
 require_relative "service/controller"
 require_relative "service/version"
-
-# @namespace
-module Async
-	# @namespace
-	module Service
-	end
-end

data/readme.md

@@ -29,6 +29,13 @@ 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.19.0
+
+  - Renamed `Async::Service::GenericService` -\> `Async::Service::Generic`, added compatibility alias for `GenericService`.
+  - Renamed `Async::Service::ManagedService` -\> `Async::Service::Managed::Service`, added compatibility alias for `ManagedService`.
+  - Renamed `Async::Service::ManagedEnvironment` -\> `Async::Service::Managed::Environment`, added compatibility alias for `ManagedEnvironment`.
+  - Renamed `Async::Service::HealthChecker` -\> `Async::Service::Managed::HealthChecker`, added compatibility alias for `HealthChecker`.
+
 ### v0.18.1
 
   - Remove prepared and running log messages - not as useful as I imagined, and quite noisy.
@@ -74,10 +81,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
   - Make service name optional and improve code comments.
   - Add `respond_to_missing?` for completeness.
 
-### v0.12.0
-
-  - Add convenient `Configuration.build{...}` method for constructing inline configurations.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,12 @@
 # Releases
 
+## v0.19.0
+
+  - Renamed `Async::Service::GenericService` -\> `Async::Service::Generic`, added compatibility alias for `GenericService`.
+  - Renamed `Async::Service::ManagedService` -\> `Async::Service::Managed::Service`, added compatibility alias for `ManagedService`.
+  - Renamed `Async::Service::ManagedEnvironment` -\> `Async::Service::Managed::Environment`, added compatibility alias for `ManagedEnvironment`.
+  - Renamed `Async::Service::HealthChecker` -\> `Async::Service::Managed::HealthChecker`, added compatibility alias for `HealthChecker`.
+
 ## v0.18.1
 
   - Remove prepared and running log messages - not as useful as I imagined, and quite noisy.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.18.1
+  version: 0.19.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -100,6 +100,9 @@ files:
 - lib/async/service/generic_service.rb
 - lib/async/service/health_checker.rb
 - lib/async/service/loader.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
@@ -126,7 +129,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: []