async-service 0.19.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c0c2a2c76b02cc502a69553db8a737d22f23ed5186b46ac35f45e6f9d5ed497
-  data.tar.gz: 4ca22e689898e5eabb150fefcab2025c248e4a0fae819bf6a7ff281de7249cf1
+  metadata.gz: dbf0b6499a4433f09585491d1097e280a739775f24557f57ea89a5f7e1c345f1
+  data.tar.gz: 7ffe1c3251852c4a57b6ad70f0e9d89f461bb272eef48cb9556f17e21369c6a6
 SHA512:
-  metadata.gz: 1d1213fbae7c10e69b300fbfeec88878987654c862ac64969a72fa2b429ef96afc3426c5f82f8395b26963a9430172b8bdff9a25270bdfb0d0e159ed762cd002
-  data.tar.gz: 42fec2e5500bcf14f06f35f149c566963404ceb8e9a155d256ebc8a76127a8a4adaee3f39452ff29e42aa8c357ec3305455cf4dc04de674973d499d9746037b4
+  metadata.gz: 477ed5f425e11f46b91da568ab84af8c32b74b873ed0909579cbad67b787a2c9230ae9aea871ae42fcb413437b5879b2ae36673c7c1a8a1117f27f759c2494cb
+  data.tar.gz: 83ec254a0835ea322ffdad5f41cfbf76ab322f739db150ab97ddecf8503b2f08408025e06613e552270f18dc9b9e3d5c934f62e7a0020e121fc55e0c13a45fef

data/context/index.yaml

@@ -10,6 +10,10 @@ files:
   title: Getting Started
   description: This guide explains how to get started with `async-service` to create
     and run services in Ruby.
+- path: policies.md
+  title: Container Policies
+  description: This guide explains how to configure container policies for your services
+    and understand the default failure handling behavior.
 - path: service-architecture.md
   title: Service Architecture
   description: This guide explains the key architectural components of `async-service`

data/context/policies.md

@@ -0,0 +1,87 @@
+# Container Policies
+
+This guide explains how to configure container policies for your services and understand the default failure handling behavior.
+
+## Default Failure Handling
+
+All services use {ruby Async::Service::Policy::DEFAULT} which monitors failure rates and stops the container when failures exceed a threshold.
+
+**Default threshold:** 6 failures in 60 seconds (0.1 failures per second).
+
+This means:
+- Services can tolerate occasional failures and transient issues.
+- More than 6 failures in any 60-second window stops the container.
+- Prevents services from restart-looping indefinitely when fundamentally broken.
+
+This fail-fast behavior is appropriate for orchestrated environments (Kubernetes, systemd) where the orchestrator will restart the entire service.
+
+### Why This Default?
+
+Without failure monitoring, a broken service with `restart: true` would restart indefinitely, wasting resources. The default policy:
+
+- **Catches problems quickly**: Broken services stop within 10-20 seconds.
+- **Prevents resource waste**: Doesn't keep trying to start services that will never succeed.
+- **Enables orchestrator recovery**: Systemd/Kubernetes can restart the whole process with a clean state.
+- **Detects environmental issues**: Bad hardware, corrupted pre-fork state, or system-level problems can't be fixed by restarting children - the entire service needs to be restarted (potentially on different hardware).
+- **Signals clear failure**: Exit code indicates the service couldn't maintain healthy operation.
+
+## Configuring Policies
+
+Use `container_policy` in your service configuration to customize failure handling:
+
+``` ruby
+# config/service.rb
+
+# More lenient: allow 5 failures per minute:
+container_policy Async::Service::Policy.new(maximum_failures: 5, window: 60)
+
+service "web" do
+	# Your service configuration.
+end
+
+service "worker" do
+	# Also uses the same policy.
+end
+```
+
+The policy applies to **all services** in the configuration file.
+
+### Choosing a Threshold
+
+Consider your service characteristics:
+
+**Strict (catch problems immediately):**
+``` ruby
+container_policy Async::Service::Policy.new(maximum_failures: 1, window: 5)
+```
+
+**Balanced (tolerate transient issues):**
+``` ruby
+container_policy Async::Service::Policy.new(maximum_failures: 5, window: 60)
+```
+
+**Lenient (allow many retries):**
+``` ruby
+container_policy Async::Service::Policy.new(maximum_failures: 20, window: 60)
+```
+
+Factors to consider:
+- **Traffic volume**: High-traffic services may have more absolute failures.
+- **Error types**: Some errors are transient (network timeouts, rate limits).
+- **Dependencies**: Upstream services may need time to recover.
+- **Deployment environment**: Kubernetes/systemd handle restarts, local dev doesn't.
+
+## Per-Container Policy Instances
+
+The `container_policy` method accepts a block that's evaluated **each time a container is created**:
+
+``` ruby
+# config/service.rb
+container_policy do
+	# This block is called for EACH container created
+	# Each container gets its own policy instance with fresh state
+	Async::Service::Policy.new(maximum_failures: 5, window: 60)
+end
+```
+
+If your policy is tracking per-container state, this will ensure each container has new policy with clean state.

data/lib/async/service/configuration.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "loader"
 require_relative "generic_service"
@@ -52,11 +52,15 @@ module Async
 			end
 			
 			# Initialize an empty configuration.
-			def initialize(environments = [])
+			# @parameter environments [Array] Environment instances.
+			# @parameter container_policy [Proc] Optional proc that returns a policy for container lifecycle management.
+			def initialize(environments = [], container_policy: nil)
 				@environments = environments
+				@container_policy = container_policy
 			end
 			
 			attr :environments
+			attr_accessor :container_policy
 			
 			# Check if the configuration is empty.
 			# @returns [Boolean] True if no environments are configured.
@@ -84,11 +88,22 @@ module Async
 			
 			# Create a controller for the configured services.
 			#
+			# @parameter container_policy [Proc] A proc that returns the policy to use for managing child lifecycle events.
+			# @parameter options [Hash] Additional options passed to the controller.
 			# @returns [Controller] A controller that can be used to start/stop services.
-			def controller(**options)
-				Controller.new(self.services(**options).to_a)
+			def make_controller(container_policy: @container_policy, implementing: nil, **options)
+				controller = Controller.new(self.services(implementing: implementing).to_a, **options)
+				
+				if container_policy
+					controller.define_singleton_method(:make_policy, &container_policy)
+				end
+				
+				return controller
 			end
 			
+			# Alias for backwards compatibility.
+			alias controller make_controller
+			
 			# Add the environment to the configuration.
 			def add(environment)
 				@environments << environment

data/lib/async/service/controller.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require "async/container/controller"
+require_relative "policy"
 
 module Async
 	module Service
@@ -13,32 +14,11 @@ module Async
 		# 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"
-					Bundler.require(:preload)
-				rescue Bundler::GemfileNotFound, LoadError
-					# Ignore.
-				end
-				
-				if Process.respond_to?(:warmup)
-					Process.warmup
-				elsif GC.respond_to?(:compact)
-					3.times{GC.start}
-					GC.compact
-				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)
-				
-				self.warmup
-				
-				controller.run
+				configuration.make_controller(**options).run
 			end
 			
 			# Create a controller for the given services.
@@ -58,10 +38,34 @@ module Async
 				@services = services
 			end
 			
+			# Warm up the Ruby process by preloading gems, running GC, and compacting memory.
+			# This reduces startup latency and improves copy-on-write efficiency.
+			def warmup
+				begin
+					require "bundler"
+					Bundler.require(:preload)
+				rescue Bundler::GemfileNotFound, LoadError
+					# Ignore.
+				end
+				
+				if ::Process.respond_to?(:warmup)
+					::Process.warmup
+				elsif ::GC.respond_to?(:compact)
+					3.times{::GC.start}
+					::GC.compact
+				end
+			end
+			
 			# All the services associated with this controller.
 			# @attribute [Array(Async::Service::Generic)]
 			attr :services
 			
+			# Create a policy for managing child lifecycle events.
+			# @returns [Policy] The service-level policy with failure rate monitoring.
+			def make_policy
+				Policy::DEFAULT
+			end
+			
 			# Start all named services.
 			def start
 				@services.each do |service|
@@ -69,6 +73,8 @@ module Async
 				end
 				
 				super
+				
+				self.warmup
 			end
 			
 			# Setup all services into the given container.

data/lib/async/service/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 module Async
 	module Service

data/lib/async/service/generic_service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # Compatibility shim for Async::Service::GenericService
 # Use Async::Service::Generic instead

data/lib/async/service/health_checker.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # Compatibility shim for Async::Service::HealthChecker
 # Use Async::Service::Managed::HealthChecker instead

data/lib/async/service/loader.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "environment"
 
@@ -58,6 +58,18 @@ module Async
 				
 				@configuration.add(self.environment(**options, &block))
 			end
+			
+			# Set the container policy for all services in this configuration.
+			# Can be called with either an argument or a block.
+			# @parameter value [Async::Container::Policy] The policy to use for managing child lifecycle events.
+			# @parameter block [Proc] A block that returns a policy instance.
+			def container_policy(value = nil, &block)
+				if @configuration.container_policy
+					Console.warn(self, "Container policy is already set, overriding previous value!")
+				end
+				
+				@configuration.container_policy = block_given? ? block : proc{value}
+			end
 		end
 	end
 end

data/lib/async/service/managed_environment.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # Compatibility shim for Async::Service::ManagedEnvironment
 # Use Async::Service::Managed::Environment instead

data/lib/async/service/managed_service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # Compatibility shim for Async::Service::ManagedService
 # Use Async::Service::Managed::Service instead

data/lib/async/service/policy.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/container/policy"
+
+module Async
+	module Service
+		# A service-level policy that extends the base container policy with failure rate monitoring.
+		# This policy will stop the container if the failure rate exceeds a threshold.
+		class Policy < Async::Container::Policy
+			# Initialize the policy.
+			# @parameter maximum_failures [Integer] The maximum number of failures allowed within the window.
+			# @parameter window [Integer] The time window in seconds for counting failures.
+			def initialize(maximum_failures: 6, window: 60)
+				@maximum_failures = maximum_failures
+				@window = window
+				
+				@failure_rate_threshold = maximum_failures.to_f / window
+			end
+			
+			# The maximum number of failures allowed within the window.
+			# @attribute [Integer]
+			attr :maximum_failures
+			
+			# The time window in seconds for statistics tracking.
+			# @attribute [Integer]
+			attr :window
+			
+			# The failure rate threshold in failures per second.
+			# @attribute [Float]
+			attr :failure_rate_threshold
+			
+			# Create statistics for a container with the configured window.
+			# @returns [Async::Container::Statistics] A new statistics instance.
+			def make_statistics
+				Async::Container::Statistics.new(window: @window)
+			end
+			
+			# Called when a child exits. Monitors failure rate and stops the container if threshold is exceeded.
+			# @parameter container [Async::Container::Generic] The container.
+			# @parameter child [Child] The child process.
+			# @parameter status [Process::Status] The exit status.
+			# @parameter name [String] The name of the child.
+			# @parameter key [Symbol] An optional key for the child.
+			# @parameter options [Hash] Additional options for future extensibility.
+			def child_exit(container, child, status, name:, key:, **options)
+				unless success?(status)
+					# Check failure rate after this failure is recorded
+					rate = container.statistics.failure_rate.per_second
+					
+					if rate > @failure_rate_threshold
+						# Only stop if container is still running (avoid redundant stop calls during shutdown)
+						if container.running?
+							Console.error(self, "Failure rate exceeded threshold, stopping container!",
+								rate: rate,
+								threshold: @failure_rate_threshold
+							)
+							container.stop(true)
+						end
+					end
+				end
+			end
+			
+			# The default service policy instance.
+			DEFAULT = self.new.freeze
+		end
+	end
+end

data/lib/async/service/version.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 # @namespace
 module Async
 	# @namespace
 	module Service
-		VERSION = "0.19.1"
+		VERSION = "0.20.0"
 	end
 end

data/lib/async/service.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "service/configuration"
 require_relative "service/controller"

data/readme.md

@@ -19,6 +19,8 @@ Please see the [project documentation](https://socketry.github.io/async-service/
 
   - [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.
 
+  - [Container Policies](https://socketry.github.io/async-service/guides/policies/index) - This guide explains how to configure container policies for your services and understand the default failure handling behavior.
+
   - [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`.
@@ -29,6 +31,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.20.0
+
+  - Introduce `Async::Service::Policy` for monitoring service health and implementing failure handling strategies. Default threshold: 6 failures in 60 seconds (0.1 failures/second).
+  - Add `container_policy` configuration method for specifying custom policies in service configuration files.
+  - Add `Configuration#make_controller` (aliased as `controller`) for creating controllers with policy injection.
+  - Add `Service::Controller#make_policy` which returns `Service::Policy::DEFAULT` by default.
+
 ### v0.19.0
 
   - Renamed `Async::Service::GenericService` -\> `Async::Service::Generic`, added compatibility alias for `GenericService`.
@@ -74,13 +83,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
 
   - 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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,12 @@
 # Releases
 
+## v0.20.0
+
+  - Introduce `Async::Service::Policy` for monitoring service health and implementing failure handling strategies. Default threshold: 6 failures in 60 seconds (0.1 failures/second).
+  - Add `container_policy` configuration method for specifying custom policies in service configuration files.
+  - Add `Configuration#make_controller` (aliased as `controller`) for creating controllers with policy injection.
+  - Add `Service::Controller#make_policy` which returns `Service::Policy::DEFAULT` by default.
+
 ## v0.19.0
 
   - Renamed `Async::Service::GenericService` -\> `Async::Service::Generic`, added compatibility alias for `GenericService`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.20.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.29'
+        version: '0.33'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.29'
+        version: '0.33'
 - !ruby/object:Gem::Dependency
   name: string-format
   requirement: !ruby/object:Gem::Requirement
@@ -90,6 +90,7 @@ files:
 - context/deployment.md
 - context/getting-started.md
 - context/index.yaml
+- context/policies.md
 - context/service-architecture.md
 - lib/async/service.rb
 - lib/async/service/configuration.rb
@@ -105,6 +106,7 @@ files:
 - lib/async/service/managed/service.rb
 - lib/async/service/managed_environment.rb
 - lib/async/service/managed_service.rb
+- lib/async/service/policy.rb
 - lib/async/service/version.rb
 - license.md
 - readme.md