async-service 0.12.0 → 0.14.0

data/lib/async/service/controller.rb

@@ -1,16 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require 'async/container/controller'
+require "async/container/controller"
 
 module Async
 	module Service
+		# Controls multiple services and their lifecycle.
+		#
+		# The controller manages starting, stopping, and monitoring multiple services
+		# within containers. It extends Async::Container::Controller to provide
+		# service-specific functionality.
 		class Controller < Async::Container::Controller
+			# Warm up the Ruby process by preloading gems and running GC.
 			def self.warmup
 				begin
-					require 'bundler'
+					require "bundler"
 					Bundler.require(:preload)
 				rescue Bundler::GemfileNotFound, LoadError
 					# Ignore.
@@ -24,6 +30,9 @@ module Async
 				end
 			end
 			
+			# Run a configuration of services.
+			# @parameter configuration [Configuration] The service configuration to run.
+			# @parameter options [Hash] Additional options for the controller.
 			def self.run(configuration, **options)
 				controller = Async::Service::Controller.new(configuration.services.to_a, **options)
 				
@@ -32,6 +41,17 @@ module Async
 				controller.run
 			end
 			
+			# Create a controller for the given services.
+			# @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)
+				self.new(services, **options)
+			end
+			
+			# Initialize a new controller with services.
+			# @parameter services [Array(Generic)] The services to manage.
+			# @parameter options [Hash] Options passed to the parent controller.
 			def initialize(services, **options)
 				super(**options)
 				

data/lib/async/service/environment.rb

@@ -5,8 +5,17 @@
 
 module Async
 	module Service
+		# Represents a service configuration with lazy evaluation and module composition.
+		#
+		# Environments store configuration as methods that can be overridden and composed using Ruby modules. They support lazy evaluation through evaluators.
 		class Environment
+			# A builder for constructing environments using a DSL.
 			class Builder < BasicObject
+				# Create a new environment with facets and values.
+				# @parameter facets [Array(Module)] Modules to include in the environment.
+				# @parameter values [Hash] Key-value pairs to define as methods.
+				# @parameter block [Proc] A block for additional configuration.
+				# @returns [Module] The constructed environment module.
 				def self.for(*facets, **values, &block)
 					top = ::Module.new
 					
@@ -46,10 +55,14 @@ module Async
 					return top
 				end
 				
+				# Initialize a new builder.
+				# @parameter facet [Module] The module to build into, defaults to a new `Module`.
 				def initialize(facet = ::Module.new)
 					@facet = facet
 				end
 				
+				# Include a module or other includable object into the environment.
+				# @parameter target [Module] The module to include.
 				def include(target)
 					if target.class == ::Module
 						@facet.include(target)
@@ -60,6 +73,10 @@ module Async
 					end
 				end
 				
+				# Define methods dynamically on the environment.
+				# @parameter name [Symbol] The method name to define.
+				# @parameter argument [Object] The value to return from the method.
+				# @parameter block [Proc] A block to use as the method implementation.
 				def method_missing(name, argument = nil, &block)
 					if block
 						@facet.define_method(name, &block)
@@ -67,12 +84,26 @@ 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.
+			# @parameter arguments [Array] Arguments passed to Builder.for
+			# @returns [Environment] A new environment instance.
 			def self.build(...)
 				Environment.new(Builder.for(...))
 			end
 			
+			# Initialize a new environment.
+			# @parameter facet [Module] The facet module containing the configuration methods.
+			# @parameter parent [Environment | Nil] The parent environment for inheritance.
 			def initialize(facet = ::Module.new, parent = nil)
 				unless facet.class == ::Module
 					raise ArgumentError, "Facet must be a module!"
@@ -88,21 +119,32 @@ module Async
 			# @attribute [Environment | Nil] The parent environment, if any.
 			attr :parent
 			
+			# Include this environment's facet into a target module.
+			# @parameter target [Module] The target module to include into.
 			def included(target)
 				@parent&.included(target)
 				target.include(@facet)
 			end
 			
+			# Create a new environment with additional configuration.
+			# @parameter arguments [Array] Arguments passed to Environment.build.
+			# @returns [Environment] A new environment with this as parent.
 			def with(...)
 				return self.class.new(Builder.for(...), self)
 			end
 			
+			# Check if this environment implements a given interface.
+			# @parameter interface [Module] The interface to check.
+			# @returns [Boolean] True if this environment implements the interface.
 			def implements?(interface)
 				@facet <= interface
 			end
 			
 			# An evaluator is lazy read-only view of an environment. It memoizes all method calls.
 			class Evaluator
+				# Create an evaluator wrapper for an environment.
+				# @parameter environment [Environment] The environment to wrap.
+				# @returns [Evaluator] A new evaluator instance.
 				def self.wrap(environment)
 					evaluator = ::Class.new(self)
 					
@@ -133,14 +175,19 @@ module Async
 					return evaluator.new
 				end
 				
+				# Initialize a new evaluator.
 				def initialize
 					@cache = {}
 				end
 				
+				# Inspect representation of the evaluator.
+				# @returns [String] A string representation of the evaluator with its keys.
 				def inspect
 					"#<#{Evaluator} #{self.keys}>"
 				end
 				
+				# Convert the evaluator to a hash.
+				# @returns [Hash] A hash with all evaluated keys and values.
 				def to_h
 					# Ensure all keys are evaluated:
 					self.keys.each do |name|
@@ -150,23 +197,38 @@ module Async
 					return @cache
 				end
 				
+				# Convert the evaluator to JSON.
+				# @parameter arguments [Array] Arguments passed to to_json.
+				# @returns [String] A JSON representation of the evaluator.
 				def to_json(...)
 					self.to_h.to_json(...)
 				end
 				
+				# Get value for a given key.
+				# @parameter key [Symbol] The key to look up.
+				# @returns [Object, nil] The value for the key, or nil if not found.
 				def [](key)
-					self.__send__(key)
+					if self.key?(key)
+						self.__send__(key)
+					end
 				end
 				
+				# Check if a key is available.
+				# @parameter key [Symbol] The key to check.
+				# @returns [Boolean] True if the key exists.
 				def key?(key)
 					self.keys.include?(key)
 				end
 			end
 			
+			# Create an evaluator for this environment.
+			# @returns [Evaluator] A lazy evaluator for this environment.
 			def evaluator
 				return Evaluator.wrap(self)
 			end
 			
+			# Convert the environment to a hash.
+			# @returns [Hash] A hash representation of the environment.
 			def to_h
 				evaluator.to_h
 			end

data/lib/async/service/formatting.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Service
+		# Formatting utilities for service titles.
+		#
+		# Services need meaningful process/thread names for monitoring and debugging. This module provides consistent formatting for common service metrics like connection counts, request ratios, and load values in process titles.
+		#
+		# It is expected you will include these into your service class and use them to update the `instance.name` in the health check.
+		module Formatting
+			UNITS = [nil, "K", "M", "B", "T", "P", "E", "Z", "Y"]
+			
+			# Format a count into a human-readable string.
+			# @parameter value [Numeric] The count to format.
+			# @parameter units [Array] The units to use for formatting (default: UNITS).
+			# @returns [String] A formatted string representing the count.
+			def format_count(value, units = UNITS)
+				value = value.to_f
+				index = 0
+				limit = units.size - 1
+				
+				# Handle negative numbers by working with absolute value:
+				negative = value < 0
+				value = value.abs
+				
+				while value >= 1000 and index < limit
+					value = value / 1000
+					index += 1
+				end
+				
+				result = String.new
+				result << "-" if negative
+				result << value.round(2).to_s
+				result << units[index].to_s if units[index]
+				
+				return result
+			end
+			
+			module_function :format_count
+			
+			# Format a ratio as "current/total" with human-readable counts.
+			# @parameter current [Numeric] The current value.
+			# @parameter total [Numeric] The total value.
+			# @returns [String] A formatted ratio string.
+			def format_ratio(current, total)
+				"#{format_count(current)}/#{format_count(total)}"
+			end
+			
+			module_function :format_ratio
+			
+			# Format a load value as a decimal with specified precision.
+			# @parameter load [Numeric] The load value (typically 0.0 to 1.0+).
+			# @returns [String] A formatted load string.
+			def format_load(load)
+				load.round(2).to_s
+			end
+			
+			module_function :format_load
+			
+			# Format multiple statistics into a compact string.
+			# @parameter stats [Hash] Hash of statistic names to values or [current, total] arrays.
+			# @returns [String] A formatted statistics string.
+			def format_statistics(**pairs)
+				pairs.map do |key, value|
+					case value
+					when Array
+						if value.length == 2
+							"#{key.to_s.upcase}=#{format_ratio(value[0], value[1])}"
+						else
+							"#{key.to_s.upcase}=#{value.join('/')}"
+						end
+					else
+						"#{key.to_s.upcase}=#{format_count(value)}"
+					end
+				end.join(" ")
+			end
+			
+			module_function :format_statistics
+		end
+	end
+end

data/lib/async/service/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 module Async
 	module Service
@@ -11,22 +11,30 @@ module Async
 		# Designed to be invoked within an {Async::Controller::Container}.
 		class Generic
 			# Convert the given environment into a service if possible.
-			# @parameter environment [Build::Environment] The environment to use to construct the service.
+			# @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 service_class = evaluator.service_class || self
-					return service_class.new(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 [Build::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
@@ -37,7 +45,7 @@ module Async
 				@evaluator.name
 			end
 			
-			# Start the service.
+			# Start the service. Called before the container setup.
 			def start
 				Console.debug(self) {"Starting service #{self.name}..."}
 			end
@@ -48,10 +56,44 @@ module Async
 				Console.debug(self) {"Setting up service #{self.name}..."}
 			end
 			
-			# Stop the service.
+			# 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
+			end
 		end
 	end
 end

data/lib/async/service/loader.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative 'environment'
+require_relative "environment"
 
 module Async
 	module Service
-	# The domain specific language for loading configuration files.
+		# The domain specific language for loading configuration files.
 		class Loader
 			# Initialize the loader, attached to a specific configuration instance.
 			# Any environments generated by the loader will be added to the configuration.
@@ -38,6 +38,8 @@ module Async
 				loader.instance_eval(File.read(path), path)
 			end
 			
+			# Load a file relative to the loader's root directory.
+			# @parameter path [String] The path to the file to load.
 			def load_file(path)
 				Loader.load_file(@configuration, File.expand_path(path, @root))
 			end
@@ -47,11 +49,14 @@ module Async
 				Environment.build(**initial, &block)
 			end
 			
-			# Define a host with the specified name.
-			# Adds `root` and `authority` keys.
+			# Define a service with the specified name.
+			# Adds `root` and `name` keys.
 			# @parameter name [String] The name of the environment, usually a hostname.
-			def service(name, &block)
-				@configuration.add(self.environment(name: name, root: @root, &block))
+			def service(name = nil, **options, &block)
+				options[:name] = name
+				options[:root] ||= @root
+				
+				@configuration.add(self.environment(**options, &block))
 			end
 		end
 	end

data/lib/async/service/version.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 module Async
 	module Service
-		VERSION = "0.12.0"
+		VERSION = "0.14.0"
 	end
 end

data/lib/async/service.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
-require_relative 'service/configuration'
-require_relative 'service/controller'
-require_relative 'service/version'
+require_relative "service/configuration"
+require_relative "service/controller"
+require_relative "service/version"
+
+# @namespace
+module Async
+	# @namespace
+	module Service
+	end
+end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2024, by Samuel Williams.  
+Copyright, 2024-2025, 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

@@ -1,9 +1,76 @@
 # Async::Service
 
-Provides a simple service interface for configuring and running services.
+Provides a simple service interface for configuring and running asynchronous services in Ruby.
 
 [![Development Status](https://github.com/socketry/async-service/workflows/Test/badge.svg)](https://github.com/socketry/async-service/actions?workflow=Test)
 
+## Features
+
+  - **Service Management**: Define, configure, and run long-running services.
+  - **Container Integration**: Built on `async-container` for robust process management.
+  - **Multiple Services**: Run and coordinate multiple services together.
+  - **Automatic Restart**: Services automatically restart on failure.
+  - **Graceful Shutdown**: Clean shutdown handling with proper resource cleanup.
+  - **Environment Configuration**: Configure services with environment variables and settings.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-service/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-service/guides/getting-started/index) - This guide explains how to get started with `async-service` to create and run services in Ruby.
+
+  - [Service Architecture](https://socketry.github.io/async-service/guides/service-architecture/index) - This guide explains the key architectural components of `async-service` and how they work together to provide a clean separation of concerns.
+
+  - [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`.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-service/releases/index) for all releases.
+
+### v0.14.0
+
+  - Introduce `ContainerEnvironment` and `ContainerService` for implementing best-practice services.
+
+### v0.13.0
+
+  - Fix null services handling.
+  - Modernize code and improve documentation.
+  - 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.
+
+### v0.11.0
+
+  - 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.
+
+### v0.8.0
+
+  - Introduce `Environment#implements?` and related methods for interface checking.
+
+### v0.7.0
+
+  - Allow instance methods that take arguments in environments.
+
+### v0.6.1
+
+  - Fix requirement that facet must be a module.
+
+### v0.6.0
+
+  - Unify construction of environments for better consistency.
+
 ## Contributing
 
 We welcome contributions to this project.
@@ -16,8 +83,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,85 @@
+# Releases
+
+## v0.14.0
+
+  - Introduce `ContainerEnvironment` and `ContainerService` for implementing best-practice services.
+
+## v0.13.0
+
+  - Fix null services handling.
+  - Modernize code and improve documentation.
+  - 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.
+
+## v0.11.0
+
+  - 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.
+
+## v0.8.0
+
+  - Introduce `Environment#implements?` and related methods for interface checking.
+
+## v0.7.0
+
+  - Allow instance methods that take arguments in environments.
+
+## v0.6.1
+
+  - Fix requirement that facet must be a module.
+
+## v0.6.0
+
+  - Unify construction of environments for better consistency.
+
+## v0.5.1
+
+  - Relax dependency on async-container for better compatibility.
+
+## v0.5.0
+
+  - Add support for passing through options to controllers.
+
+## v0.4.0
+
+  - Reuse evaluator for service instances for better performance.
+  - Expose `Configuration.load` and `Controller.start` for better composition.
+  - Add simple service example.
+
+## v0.3.1
+
+  - Fix usage of `raise` in `BasicObject` context.
+
+## v0.3.0
+
+  - Use modules for environments instead of basic objects.
+  - Allow non-modules to be included in environments.
+
+## v0.2.1
+
+  - Add missing call to `super` in service implementations.
+
+## v0.2.0
+
+  - Add support for loading other configuration files.
+  - Minor bug fixes and improvements.
+
+## v0.1.0
+
+  - Initial release with core service framework.
+  - Environment abstraction for service configuration.
+  - Improved evaluator implementation with comprehensive tests.
+  - Controller for handling service execution.
+  - Support for explicit `service_class` configuration.