Add support for container policies.

Author: samuel-williams-shopify

async-service.gemspec

@@ -27,6 +27,6 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = ">= 3.2"
 
 	spec.add_dependency "async"
-	spec.add_dependency "async-container", "~> 0.29"
+	spec.add_dependency "async-container", "~> 0.32"
 	spec.add_dependency "string-format", "~> 0.2"
 end

bake/async/service/controller.rb

@@ -10,9 +10,6 @@ def initialize(context)
 end
 
 def run
-	# Warm up the Ruby process by preloading gems and running GC.
-	Async::Service::Controller.warmup
-	
 	controller.run
 end
 
@@ -21,5 +18,5 @@ def run
 def controller
 	configuration = context.lookup("async:service:configuration").instance.configuration
 
-	return Async::Service::Controller.new(configuration.services)
+	return configuration.make_controller
 end

lib/async/service/configuration.rb

@@ -52,11 +52,15 @@ def self.for(*environments)
 			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 @@ def services(implementing: nil)
 
 			# 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, **options)
+				controller = Controller.new(self.services(**options).to_a)
+				
+				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

lib/async/service/controller.rb

@@ -4,6 +4,7 @@
 # Copyright, 2024-2025, by Samuel Williams.
 
 require "async/container/controller"
+require_relative "policy"
 
 module Async
 	module Service
@@ -13,32 +14,11 @@ module Service
 		# 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,17 +38,41 @@ def initialize(services, **options)
 				@services = services
 			end
 
+			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|
 					service.start
 				end
 
 				super
+				
+				self.warmup
 			end
 
 			# Setup all services into the given container.

lib/async/service/loader.rb

@@ -58,6 +58,18 @@ def service(name = nil, **options, &block)
 
 				@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

lib/async/service/policy.rb

@@ -0,0 +1,47 @@
+# 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
+			# Create a policy from maximum failures and time window.
+			# @parameter maximum_failures [Integer] The maximum number of failures allowed within the window.
+			# @parameter window [Integer] The time window in seconds for counting failures.
+			# @returns [Policy] A new policy instance.
+			def self.for(maximum_failures: 1, window: 10)
+				failure_rate_threshold = maximum_failures.to_f / window
+				self.new(failure_rate_threshold)
+			end
+			
+			# Initialize the policy.
+			# @parameter failure_rate_threshold [Float] The maximum failures per second before stopping the container.
+			def initialize(failure_rate_threshold)
+				@failure_rate_threshold = failure_rate_threshold
+			end
+			
+			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
+						Console.error(self, "Failure rate exceeded threshold, stopping container!",
+							rate: rate,
+							threshold: @failure_rate_threshold
+						)
+						container.stop(true)
+					end
+				end
+			end
+			
+			# The default service policy instance.
+			DEFAULT = self.for.freeze
+		end
+	end
+end

test/async/service/configuration.rb

@@ -121,13 +121,19 @@
 		end
 
 		it "can create a controller" do
-			controller = configuration.controller
+			controller = configuration.make_controller
 			expect(controller).to be_a(Async::Service::Controller)
 
 			expect(controller.services).to have_attributes(
 				size: be == 1
 			)
 		end
+		
+		it "make_controller returns controller with policy" do
+			controller = configuration.make_controller
+			
+			expect(controller.make_policy).to be_a(Async::Container::Policy)
+		end
 	end
 
 	with "other configuration file" do

test/async/service/controller.rb

@@ -97,12 +97,5 @@
 			controller.stop
 		end
 	end
-	
-	with ".warmup" do
-		it "can warmup without errors" do
-			# Should not raise exception
-			subject.warmup
-		end
-	end
 end
 

test/async/service/policy.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/service/policy"
+require "async/container/statistics"
+
+describe Async::Service::Policy do
+	let(:policy) {subject.for(maximum_failures: 5, window: 10)}
+	
+	with "::DEFAULT" do
+		it "exists and is frozen" do
+			expect(Async::Service::Policy::DEFAULT).not.to be_nil
+			expect(Async::Service::Policy::DEFAULT).to be(:frozen?)
+		end
+		
+		it "is a Service::Policy instance" do
+			expect(Async::Service::Policy::DEFAULT).to be_a(Async::Service::Policy)
+		end
+		
+		it "has working helper methods" do
+			status = Object.new
+			def status.termsig; Signal.list["SEGV"]; end
+			
+			expect(Async::Service::Policy::DEFAULT).to be(:segfault?, status)
+		end
+	end
+	
+	with "failure rate monitoring" do
+		let(:mock_container) do
+			Class.new do
+				attr_reader :stopped, :statistics
+				
+				def initialize
+					@stopped = false
+					@statistics = Async::Container::Statistics.new(window: 10)
+				end
+				
+				def stop(graceful)
+					@stopped = true
+				end
+			end.new
+		end
+		
+		let(:mock_status) do
+			Class.new do
+				def success?
+					false
+				end
+			end.new
+		end
+		
+		it "stops container when failure rate exceeds threshold" do
+			# Policy with max 5 failures in 10 second window
+			policy = subject.for(maximum_failures: 5, window: 10)
+			
+			# Add 6 failures (exceeds threshold of 5 in 10 seconds)
+			6.times do
+				mock_container.statistics.failure!
+			end
+			
+			# 6 failures in same second = 0.6/sec which exceeds 5/10sec = 0.5/sec
+			rate = mock_container.statistics.failure_rate.per_second
+			expect(rate).to be > 0.5
+			expect(mock_container.stopped).to be == false
+			
+			# Trigger policy check
+			policy.child_exit(mock_container, nil, mock_status, name: "test", key: nil)
+			
+			expect(mock_container.stopped).to be == true
+		end
+		
+		it "does not stop container when failure rate is acceptable" do
+			# Policy with max 10 failures in 10 second window  
+			policy = subject.for(maximum_failures: 10, window: 10)
+			
+			# Add only 3 failures (below threshold)
+			3.times do
+				mock_container.statistics.failure!
+			end
+			
+			# 3 failures = 0.3/sec which is below 10/10sec = 1.0/sec
+			rate = mock_container.statistics.failure_rate.per_second
+			expect(rate).to be < 1.0
+			
+			# Trigger policy check
+			policy.child_exit(mock_container, nil, mock_status, name: "test", key: nil)
+			
+			expect(mock_container.stopped).to be == false
+		end
+		
+		it "does nothing on successful exit" do
+			policy = subject.for(maximum_failures: 1, window: 10)
+			
+			success_status = Object.new
+			def success_status.success?; true; end
+			
+			# Even with low threshold, success shouldn't trigger stop
+			policy.child_exit(mock_container, nil, success_status, name: "test", key: nil)
+			
+			expect(mock_container.stopped).to be == false
+		end
+	end
+	
+	with "custom parameters" do
+		it "can be created with custom threshold" do
+			policy = subject.for(maximum_failures: 20, window: 30)
+			
+			expect(policy).to be_a(Async::Service::Policy)
+		end
+		
+		it "can be initialized with raw threshold" do
+			policy = subject.new(0.5)
+			
+			expect(policy).to be_a(Async::Service::Policy)
+		end
+	end
+end