async-service 0.14.4 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09520c2c06a66a0524f733e446046f67e24d8a316ba4d08e566863dae765116d'
-  data.tar.gz: 8462198e099679b85c524d75a15ca8911ab17d31da71e492dbeda2958006a752
+  metadata.gz: 13ead1ca63b6d4843b39153b021809f8b521ca19a47ecec2772b567076877d49
+  data.tar.gz: 26cf9ffae20270a56937b077b8c852d86e67cb0c31f4b75486cc8bfca256282a
 SHA512:
-  metadata.gz: 39579c924d04afb7271183498a40ab91f7380f1d848dd52c5785f49823ec85d19f173ecd9cf09de92229c4b9e80a5f22dadd7f4eed5663ea1a356ad8f12534c9
-  data.tar.gz: 17bf024007654e733965b103747f72db73f5dd89484c000320dee4296426321ce92cb0ed30f1f7a45d65992aaf6269c9111c0ddcdb51bfdbe1bec0dfeb8c30c5
+  metadata.gz: d2f8fa1f3b208ab5bc3804daf82a3e7c7c5f598950d60d50dd9d39acad4956ac4c143d76a7c6218e6b29bc3e317b954727916bdc8806d117e85885dd3e6c07b0
+  data.tar.gz: f8200b507889e9beb20a46f5f3c857ecab74ab74563a1e53264acb13a033426c8c02fae4dc5b16cc959fbf3d6bc5a3942c19fa606d0245d2c437a7211890f695

data/context/best-practices.md

@@ -14,8 +14,8 @@ Create a single top-level `service.rb` file as your main entry point:
 #!/usr/bin/env async-service
 
 # Load your service configurations
-require_relative 'lib/my_library/environment/web_environment'
-require_relative 'lib/my_library/environment/worker_environment'
+require_relative "lib/my_library/environment/web_environment"
+require_relative "lib/my_library/environment/worker_environment"
 
 service "web" do
 	include MyLibrary::Environment::WebEnvironment
@@ -61,7 +61,7 @@ Place environments in `lib/my_library/environment/`:
 module MyLibrary
 	module Environment
 		module WebEnvironment
-			include Async::Service::ContainerEnvironment
+			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::ContainerService
+		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)"
@@ -98,7 +98,7 @@ module MyLibrary
 			
 			def run(instance, evaluator)
 				# Start your service and return the server object.
-				# ContainerService handles container setup, health checking, and process titles.
+				# Managed::Service handles container setup, health checking, and process titles.
 				start_web_server(evaluator.host, evaluator.port)
 			end
 			
@@ -112,13 +112,13 @@ module MyLibrary
 end
 ```
 
-### Use `ContainerEnvironment` for Services
+### Use `Managed::Environment` for Services
 
-Include {ruby Async::Service::ContainerEnvironment} for services that run in containers using {ruby Async::Service::ContainerService}:
+Include {ruby Async::Service::Managed::Environment} for services that need robust lifecycle management using {ruby Async::Service::Managed::Service}:
 
 ```ruby
 module WebEnvironment
-	include Async::Service::ContainerEnvironment
+	include Async::Service::Managed::Environment
 	
 	def service_class
 		WebService
@@ -159,9 +159,9 @@ module WebEnvironment
 	def port
 		3000
 	end
-
+	
 	def host
-		'0.0.0.0'
+		"0.0.0.0"
 	end
 end
 
@@ -172,7 +172,7 @@ module WorkerEnvironment
 	end
 	
 	def queue_name
-		'default'
+		"default"
 	end
 	
 	def count
@@ -199,16 +199,16 @@ end
 
 ## Service Best Practices
 
-### Use ContainerService as Base Class
+### Use `Managed::Service` as Base Class
 
-Prefer `Async::Service::ContainerService` over `Generic` for most services:
+Prefer `Async::Service::Managed::Service` over `Generic` for most services:
 
 ```ruby
-class WebService < Async::Service::ContainerService
-	# ContainerService automatically handles:
+class WebService < Async::Service::Managed::Service
+	# Managed::Service automatically handles:
 	# - Container setup with proper options.
 	# - Health checking with process title updates.
-	# - Integration with Formatting module.
+	# - Preloading of scripts before startup.
 	
 	private def format_title(evaluator, server)
 		# Customize process title display
@@ -247,20 +247,22 @@ Try to keep process titles short and focused.
 Utilize the `start` and `stop` hooks to manage shared resources effectively:
 
 ```ruby
-class WebService < Async::Service::ContainerService
+class WebService < Async::Service::Managed::Service
 	def start
 		# Bind to the endpoint in the container:
 		@endpoint = @evaluator.endpoint.bind
 		
 		super
 	end
-
+	
 	def stop
 		@endpoint&.close
 	end
 end
 ```
 
+These hooks are invoked **before** the container is setup (e.g. pre-forking).
+
 ## Testing Best Practices
 
 ### Test Environments in Isolation
@@ -302,7 +304,7 @@ describe MyLibrary::Service::WebService do
 	before do
 		controller.start
 	end
-
+	
 	after do
 		controller.stop
 	end

data/context/getting-started.md

@@ -29,7 +29,7 @@ Create a simple service that runs continuously:
 ```ruby
 #!/usr/bin/env async-service
 
-require 'async/service'
+require "async/service"
 
 class HelloService < Async::Service::Generic
 	def setup(container)
@@ -99,7 +99,7 @@ You can define multiple services in a single configuration file:
 ```ruby
 #!/usr/bin/env async-service
 
-require 'async/service'
+require "async/service"
 
 class WebService < Async::Service::Generic
 	def setup(container)
@@ -141,7 +141,7 @@ end
 You can also create and run services programmatically:
 
 ```ruby
-require 'async/service'
+require "async/service"
 
 configuration = Async::Service::Configuration.build do
 	service "my-service" do

data/context/service-architecture.md

@@ -262,6 +262,8 @@ end
 
 ### Health Checking
 
+For services using `Async::Service::Managed::Service`, health checking is handled automatically. For services extending `Generic`, you can set up health checking manually:
+
 ```ruby
 def setup(container)
 	container_options = @evaluator.container_options
@@ -270,7 +272,7 @@ def setup(container)
 	container.run(**container_options) do |instance|
 		# Prepare your service.
 		
-		Sync do
+		Async do
 			# Start your service.
 			
 			# Set up health checking, if a timeout was specified:
@@ -282,6 +284,8 @@ def setup(container)
 end
 ```
 
+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
 
 The four layers interact in a specific pattern:
@@ -435,15 +439,13 @@ configuration = Async::Service::Configuration.load(["config/web.rb", "config/wor
 Create reusable configuration modules:
 
 ```ruby
-module ContainerEnvironment
+module ManagedEnvironment
+	include Async::Service::Managed::Environment
+	
 	def count
 		4
 	end
-
-	def restart
-		true
-	end
-
+	
 	def health_check_timeout
 		30
 	end
@@ -451,7 +453,7 @@ end
 
 configuration = Async::Service::Configuration.build do
 	service "my-service" do
-		include ContainerEnvironment
+		include ManagedEnvironment
 		service_class MyService
 	end
 end

data/lib/async/service/environment.rb

@@ -84,14 +84,6 @@ module Async
 						@facet.define_method(name){argument}
 					end
 				end
-				
-				# Always respond to missing methods for dynamic method definition.
-				# @parameter name [Symbol] The method name.
-				# @parameter include_private [Boolean] Whether to include private methods.
-				# @returns [Boolean] Always true to enable dynamic method definition.
-				def respond_to_missing?(name, include_private = false)
-					true
-				end
 			end
 			
 			# Build a new environment using the builder DSL.
@@ -170,7 +162,7 @@ module Async
 					end
 					
 					# This lists all zero-argument methods:
-					evaluator.define_method(:keys) {keys}
+					evaluator.define_method(:keys){keys}
 					
 					return evaluator.new
 				end

data/lib/async/service/generic.rb

@@ -47,52 +47,18 @@ module Async
 			
 			# Start the service. Called before the container setup.
 			def start
-				Console.debug(self) {"Starting service #{self.name}..."}
+				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}..."}
+				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
-			
-			protected
-			
-			# 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
-							
-							instance.ready!
-							
-							sleep(timeout / 2)
-						end
-					end
-				else
-					if block_given?
-						yield(instance)
-					end
-					
-					instance.ready!
-				end
+				Console.debug(self){"Stopping service #{self.name}..."}
 			end
 		end
 	end

data/lib/async/service/loader.rb

@@ -38,6 +38,8 @@ module Async
 				loader.instance_eval(File.read(path), path)
 			end
 			
+			# Load a configuration file relative to the loader's root path.
+			# @parameter path [String] The path to the configuration file, relative to the loader's root.
 			def load_file(path)
 				Loader.load_file(@configuration, File.expand_path(path, @root))
 			end

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

@@ -0,0 +1,48 @@
+# 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

@@ -0,0 +1,49 @@
+# 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

@@ -0,0 +1,82 @@
+# 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|
+						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
+

data/lib/async/service/managed.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "managed/environment"
+require_relative "managed/service"
+
+module Async
+	module Service
+		# Managed services provide robust lifecycle management including health checking, restart policies, and process title formatting.
+		#
+		# This module contains components for building managed services that can run multiple instances with automatic restart and health monitoring.
+		module Managed
+		end
+	end
+end

data/lib/async/service/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Service
-		VERSION = "0.14.4"
+		VERSION = "0.15.0"
 	end
 end

data/readme.md

@@ -27,6 +27,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.15.0
+
+  - Rename `ContainerEnvironment` and `ContainerService` to `Managed::Environment` and `Managed::Service` respectively.
+  - Health check uses `Fiber.new{instance.ready!}.resume` to confirm fiber allocation is working.
+
 ### v0.14.4
 
   - Use `String::Format` gem for formatting.
@@ -67,10 +72,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
 
   - Allow instance methods that take arguments in environments.
 
-### v0.6.1
-
-  - Fix requirement that facet must be a module.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.15.0
+
+  - Rename `ContainerEnvironment` and `ContainerService` to `Managed::Environment` and `Managed::Service` respectively.
+  - Health check uses `Fiber.new{instance.ready!}.resume` to confirm fiber allocation is working.
+
 ## v0.14.4
 
   - Use `String::Format` gem for formatting.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.14.4
+  version: 0.15.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -92,13 +92,15 @@ files:
 - context/service-architecture.md
 - lib/async/service.rb
 - lib/async/service/configuration.rb
-- lib/async/service/container_environment.rb
-- lib/async/service/container_service.rb
 - lib/async/service/controller.rb
 - lib/async/service/environment.rb
 - lib/async/service/formatting.rb
 - lib/async/service/generic.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/version.rb
 - license.md
 - readme.md

data/lib/async/service/container_environment.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-module Async
-	module Service
-		# Default configuration for container-based services.
-		#
-		# This is provided not because it is required, but to offer a sensible default for containerized applications, and to expose a consistent interface for service configuration.
-		module ContainerEnvironment
-			# 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 server.
-			#
-			# @returns [Array(String)] The list of scripts to preload.
-			def preload
-				[]
-			end
-		end
-	end
-end

data/lib/async/service/container_service.rb

@@ -1,77 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "generic"
-require_relative "formatting"
-
-module Async
-	module Service
-		# A service that runs in a container with built-in health checking and process title formatting.
-		#
-		# This is the recommended base class for most services.
-		class ContainerService < Async::Service::Generic
-			include Async::Service::Formatting
-			
-			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 => 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|
-					evaluator = self.environment.evaluator
-					
-					server = run(instance, evaluator)
-					
-					health_checker(instance) do
-						instance.name = format_title(evaluator, server)
-					end
-				end
-			end	
-		end
-	end
-end