async-container 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84ca0883f2ae0742253c1f2bdb08c98152770c41609ed179a81f2249d9cc46f7
-  data.tar.gz: 5d551d20be155c60557783ecf4064d0d90a3748ba18d9c66324a515208671bf0
+  metadata.gz: e15ecc1c913a50b101dae8f01ec2086eee565be48c684eaee110d80f5ffa5001
+  data.tar.gz: a30a269c56373cb3ab073e1facd9c375f41f5169fdf6a1570e0748165af26e87
 SHA512:
-  metadata.gz: fddd4b0f2ea6f459a0ad39a3e806b776abda60cb97fbface314f6f93b0690fac817b0f8b09a486aa387c1dd06dc6f6ae3c9620d146ef4e2f50318532d36ac20d
-  data.tar.gz: cd14547b2e6be8a9139bcadfbf5593e777d04d6f26f02cff4c808d9b2ba3c205e36acfc19af646dca95e2f1bd52edf9020d79461a6c5987304c28eb5bc271516
+  metadata.gz: b75e11606c5a2c9878f41564cc1523dcad05b30589281736060a58d2ad0ffc04bb4523d87fcba8183d48427100886bff1e20256a9b9d94729b80744dacbb8784
+  data.tar.gz: 9d07035b6912a654d38d9a0b3810d01451384c19f5c1f3ff967d41a47b99c06ca718e2f6a25e79a3cd4a6ff580d1484a97c9e4692b8b708a8eeb8aa09e2a9d98

data/lib/async/container/controller.rb

@@ -8,6 +8,7 @@ require_relative "best"
 
 require_relative "statistics"
 require_relative "notify"
+require_relative "policy"
 
 module Async
 	module Container
@@ -62,11 +63,18 @@ module Async
 			# The current container being managed by the controller.
 			attr :container
 			
+			# Create a policy for managing child lifecycle events.
+			# Can be overridden by a sub-class to provide a custom policy.
+			# @returns [Policy] The policy to use for the container.
+			def make_policy
+				Policy::DEFAULT
+			end
+			
 			# Create a container for the controller.
 			# Can be overridden by a sub-class.
 			# @returns [Generic] A specific container instance to use.
 			def create_container
-				@container_class.new
+				@container_class.new(policy: self.make_policy)
 			end
 			
 			# Whether the controller has a running container.

data/lib/async/container/generic.rb

@@ -10,6 +10,7 @@ require "async/clock"
 require_relative "group"
 require_relative "keyed"
 require_relative "statistics"
+require_relative "policy"
 
 module Async
 	module Container
@@ -42,8 +43,9 @@ module Async
 			
 			# Initialize the container.
 			#
+			# @parameter policy [Policy] The policy to use for managing child lifecycle events.
 			# @parameter options [Hash] Options passed to the {Group} instance.
-			def initialize(**options)
+			def initialize(policy: Policy::DEFAULT, **options)
 				@group = Group.new(**options)
 				@running = true
 				
@@ -51,6 +53,7 @@ module Async
 				
 				@statistics = Statistics.new
 				@keyed = {}
+				@policy = policy
 			end
 			
 			# @attribute [Group] The group of running children instances.
@@ -64,6 +67,9 @@ module Async
 			# @attribute [Hash(Child, Hash)] The state of each child instance.
 			attr :state
 			
+			# @attribute [Policy] The policy for managing child lifecycle events.
+			attr_accessor :policy
+			
 			# A human readable representation of the container.
 			# @returns [String]
 			def to_s
@@ -157,18 +163,30 @@ module Async
 				@running = true
 			end
 			
-			protected def health_check_failed!(child, age_clock, health_check_timeout)
-				Console.warn(self, "Child failed health check!", child: child, age: age_clock.total, health_check_timeout: health_check_timeout)
-				
-				# If the child has failed the health check, we assume the worst and kill it immediately:
-				child.kill!
+			protected def health_check_failed(child, age_clock, health_check_timeout)
+				begin
+					@policy.health_check_failed(
+						self, child,
+						age: age_clock.total,
+						timeout: health_check_timeout
+					)
+				rescue => error
+					Console.error(self, "Policy error in health_check_failed!", exception: error)
+					child.kill!
+				end
 			end
 			
-			protected def startup_failed!(child, age_clock, startup_timeout)
-				Console.warn(self, "Child failed startup!", child: child, age: age_clock.total, startup_timeout: startup_timeout)
-				
-				# If the child has failed the startup, we assume the worst and kill it immediately:
-				child.kill!
+			protected def startup_failed(child, age_clock, startup_timeout)
+				begin
+					@policy.startup_failed(
+						self, child,
+						age: age_clock.total,
+						timeout: startup_timeout
+					)
+				rescue => error
+					Console.error(self, "Policy error in startup_failed!", exception: error)
+					child.kill!
+				end
 			end
 			
 			# Spawn a child instance into the container.
@@ -194,6 +212,13 @@ module Async
 						child = self.start(name, &block)
 						state = insert(key, child)
 						
+						# Notify policy of spawn
+						begin
+							@policy.child_spawn(self, child, name: name, key: key)
+						rescue => error
+							Console.error(self, "Policy error in child_spawn!", exception: error)
+						end
+						
 						Console.debug(self, "Started child.", child: child, spawn: {key: key, restart: restart, health_check_timeout: health_check_timeout}, statistics: @statistics)
 						
 						# If a health check or startup timeout is specified, we will monitor the child process and terminate it if it does not update its state within the specified time.
@@ -211,14 +236,14 @@ module Async
 										# If a health check timeout is specified, we will monitor the child process and terminate it if it does not update its state within the specified time.
 										if health_check_timeout
 											if health_check_timeout < age_clock.total
-												health_check_failed!(child, age_clock, health_check_timeout)
+												health_check_failed(child, age_clock, health_check_timeout)
 											end
 										end
 									else
 										# If a startup timeout is specified, we will monitor the child process and terminate it if it does not become ready within the specified time.
 										if startup_timeout
 											if startup_timeout < age_clock.total
-												startup_failed!(child, age_clock, startup_timeout)
+												startup_failed(child, age_clock, startup_timeout)
 											end
 										end
 									end
@@ -237,6 +262,13 @@ module Async
 							delete(key, child)
 						end
 						
+						# Notify policy of exit
+						begin
+							@policy.child_exit(self, child, status: status, name: name, key: key)
+						rescue => error
+							Console.error(self, "Policy error in child_exit!", exception: error)
+						end
+						
 						if status&.success?
 							Console.debug(self, "Child exited successfully.", status: status, running: @running)
 						else
@@ -244,7 +276,7 @@ module Async
 							Console.error(self, "Child exited with error!", status: status, running: @running)
 						end
 						
-						if restart
+						if restart && @running
 							@statistics.restart!
 						else
 							break

data/lib/async/container/policy.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Container
+		# A policy for managing container behavior and responding to child process lifecycle events.
+		class Policy
+			# Called when a child is spawned.
+			# @parameter container [Generic] The container.
+			# @parameter child [Child] The child process.
+			# @parameter name [String] The name of the child.
+			# @parameter key [Symbol] An optional key for the child.
+			def child_spawn(container, child, name:, key:)
+			end
+			
+			# Called when a child exits.
+			# @parameter 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.
+			def child_exit(container, child, status:, name:, key:)
+			end
+			
+			# Called when a health check fails.
+			# Subclasses can override to implement custom behavior (e.g., alerting before killing).
+			# @parameter container [Generic] The container.
+			# @parameter child [Child] The child process.
+			# @parameter age [Numeric] How long the child has been running.
+			# @parameter timeout [Numeric] The health check timeout that was exceeded.
+			def health_check_failed(container, child, age:, timeout:)
+				Console.warn(container, "Health check failed!", child: child, age: age, timeout: timeout)
+				child.kill!
+			end
+			
+			# Called when startup fails (child doesn't become ready in time).
+			# Subclasses can override to implement custom behavior (e.g., alerting before killing).
+			# @parameter container [Generic] The container.
+			# @parameter child [Child] The child process.
+			# @parameter age [Numeric] How long the child has been running.
+			# @parameter timeout [Numeric] The startup timeout that was exceeded.
+			def startup_failed(container, child, age:, timeout:)
+				Console.warn(container, "Startup failed!", child: child, age: age, timeout: timeout)
+				child.kill!
+			end
+			
+			# Helper method to check if a status indicates a segfault.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Boolean] Whether the process was terminated by SIGSEGV.
+			def segfault?(status)
+				status&.termsig == Signal.list["SEGV"]
+			end
+			
+			# Helper method to check if a status indicates an abort.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Boolean] Whether the process was terminated by SIGABRT.
+			def abort?(status)
+				status&.termsig == Signal.list["ABRT"]
+			end
+			
+			# Helper method to check if a status indicates the process was killed.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Boolean] Whether the process was terminated by SIGKILL.
+			def killed?(status)
+				status&.termsig == Signal.list["KILL"]
+			end
+			
+			# Helper method to check if a status indicates success.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Boolean] Whether the process exited successfully.
+			def success?(status)
+				status&.success?
+			end
+			
+			# Helper method to get the signal that terminated the process.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Integer, nil] The signal number, or nil if not terminated by signal.
+			def signal(status)
+				status&.termsig
+			end
+			
+			# Helper method to get the exit code.
+			# @parameter status [Process::Status] The exit status.
+			# @returns [Integer, nil] The exit code, or nil if terminated by signal.
+			def exit_code(status)
+				status&.exitstatus
+			end
+			
+			# The default policy instance.
+			DEFAULT = self.new.freeze
+		end
+	end
+end

data/lib/async/container/statistics.rb

@@ -9,11 +9,75 @@ module Async
 	module Container
 		# Tracks various statistics relating to child instances in a container.
 		class Statistics
+			# Tracks rate information over a sliding time window using a circular buffer.
+			class Rate
+				# Initialize the event rate counter.
+				#
+				# @parameter window [Integer] The time window in seconds for rate calculations.
+				def initialize(window: 60)
+					@window = window
+					@samples = [0] * @window
+					@last_update = Array.new(@window, 0)
+				end
+				
+				# Get the current time in seconds.
+				# @returns [Integer] The current monotonic time in seconds.
+				def now
+					::Process.clock_gettime(::Process::CLOCK_MONOTONIC).to_i
+				end
+				
+				# Add a value to the current time slot.
+				# @parameter value [Numeric] The value to add (default: 1)
+				# @parameter time [Integer] The current time in seconds (default: monotonic time)
+				def add(value = 1, time: self.now)
+					index = time % @samples.size
+					
+					# If this slot hasn't been updated in a full window cycle, reset it
+					if (time - @last_update[index]) >= @window
+						@samples[index] = 0
+					end
+					
+					@samples[index] += value
+					@last_update[index] = time
+				end
+				
+				# Get the total count in the current window.
+				# @parameter time [Integer] The current time in seconds (default: monotonic time)
+				# @returns [Numeric] The sum of all samples in the window.
+				def total(time: self.now)
+					@samples.each_with_index.sum do |value, index|
+						# Only count samples that are within the window (inclusive of window boundary)
+						if (time - @last_update[index]) <= @window
+							value
+						else
+							0
+						end
+					end
+				end
+				
+				# Get the rate per second over the window.
+				# @parameter time [Integer] The current time in seconds (default: monotonic time)
+				# @returns [Float] The average rate per second.
+				def per_second(time: self.now)
+					total(time: time).to_f / @window
+				end
+				
+				# Get the rate per minute over the window.
+				# @parameter time [Integer] The current time in seconds (default: monotonic time)
+				# @returns [Float] The average rate per minute.
+				def per_minute(time: self.now)
+					per_second(time: time) * 60
+				end
+			end
 			# Initialize the statistics all to 0.
-			def initialize
+			# @parameter window [Integer] The time window in seconds for rate calculations.
+			def initialize(window: 60)
 				@spawns = 0
 				@restarts = 0
 				@failures = 0
+				
+				@restart_rate = Rate.new(window: window)
+				@failure_rate = Rate.new(window: window)
 			end
 			
 			# How many child instances have been spawned.
@@ -36,13 +100,23 @@ module Async
 			# Increment the number of restarts by 1.
 			def restart!
 				@restarts += 1
+				@restart_rate.add(1)
 			end
 			
 			# Increment the number of failures by 1.
 			def failure!
 				@failures += 1
+				@failure_rate.add(1)
 			end
 			
+			# Get the restart rate tracker.
+			# @attribute [Rate]
+			attr :restart_rate
+			
+			# Get the failure rate tracker.
+			# @attribute [Rate]
+			attr :failure_rate
+			
 			# Whether there have been any failures.
 			# @returns [Boolean] If the failure count is greater than 0.
 			def failed?
@@ -65,6 +139,8 @@ module Async
 					spawns: @spawns,
 					restarts: @restarts,
 					failures: @failures,
+					restart_rate: @restart_rate.per_second,
+					failure_rate: @failure_rate.per_second,
 				}
 			end
 			

data/lib/async/container/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.30.0"
+		VERSION = "0.31.0"
 	end
 end

data/readme.md

@@ -18,6 +18,8 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
   - [Getting Started](https://socketry.github.io/async-container/guides/getting-started/index) - This guide explains how to use `async-container` to build basic scalable systems.
 
+  - [Container Policies](https://socketry.github.io/async-container/guides/policies/index) - This guide explains how to use policies to monitor container health and implement custom failure handling strategies.
+
   - [Systemd Integration](https://socketry.github.io/async-container/guides/systemd-integration/index) - This guide explains how to use `async-container` with systemd to manage your application as a service.
 
   - [Kubernetes Integration](https://socketry.github.io/async-container/guides/kubernetes-integration/index) - This guide explains how to use `async-container` with Kubernetes to manage your application as a containerized service.
@@ -26,6 +28,12 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
 Please see the [project releases](https://socketry.github.io/async-container/releases/index) for all releases.
 
+### v0.31.0
+
+  - Introduce `Async::Container::Policy` for managing child lifecycle events and implementing custom failure handling strategies.
+  - Add `Async::Container::Statistics::Rate` for tracking failure and restart rates over sliding time windows.
+  - Fix restart counter to only increment when actually restarting (check `@running` flag).
+
 ### v0.30.0
 
   - `SIGTERM` is now graceful, the same as `SIGINT`, for better compatibility with Kubernetes and systemd.
@@ -66,10 +74,6 @@ Please see the [project releases](https://socketry.github.io/async-container/rel
   - Increased default interrupt timeout and terminate timeout to 10 seconds each.
   - Expose `ASYNC_CONTAINER_INTERRUPT_TIMEOUT` and `ASYNC_CONTAINER_TERMINATE_TIMEOUT` environment variables for configuring default timeouts.
 
-### v0.26.0
-
-  - [Production Reliability Improvements](https://socketry.github.io/async-container/releases/index#production-reliability-improvements)
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.31.0
+
+  - Introduce `Async::Container::Policy` for managing child lifecycle events and implementing custom failure handling strategies.
+  - Add `Async::Container::Statistics::Rate` for tracking failure and restart rates over sliding time windows.
+  - Fix restart counter to only increment when actually restarting (check `@running` flag).
+
 ## v0.30.0
 
   - `SIGTERM` is now graceful, the same as `SIGINT`, for better compatibility with Kubernetes and systemd.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -78,6 +78,7 @@ files:
 - lib/async/container/notify/pipe.rb
 - lib/async/container/notify/server.rb
 - lib/async/container/notify/socket.rb
+- lib/async/container/policy.rb
 - lib/async/container/statistics.rb
 - lib/async/container/threaded.rb
 - lib/async/container/version.rb