async-service 0.13.0 → 0.14.0

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)
@@ -68,15 +85,25 @@ module Async
 					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!"
@@ -92,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)
 					
@@ -137,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|
@@ -154,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

@@ -11,7 +11,7 @@ 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
@@ -24,12 +24,17 @@ module Async
 			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
@@ -40,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
@@ -51,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

@@ -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

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.13.0"
+		VERSION = "0.14.0"
 	end
 end

data/lib/async/service.rb

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

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.

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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -36,7 +36,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-03-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -71,16 +71,25 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
 - bin/async-service
+- context/best-practices.md
+- context/getting-started.md
+- context/index.yaml
+- 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/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async-service
 licenses:
 - MIT
@@ -94,14 +103,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A service layer for Async.
 test_files: []