async-container 0.23.2 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7d6beef9d67eb3befeb6df39c14194bef86cefa104924e7eaff052571efbf68
-  data.tar.gz: d18ac658a4dac083de68527533e1f476dfe56085b4ba67a46fa9e3ba8e92fa45
+  metadata.gz: e2613c963c3efb08cf02c6a6299668b2b9ed83b583bbe84ebc973fa099b62e4a
+  data.tar.gz: 9cc9cd1ac55d85be9684e9a042be6ff3e93dd44e69c2ce212ec5f7441cbf7b1d
 SHA512:
-  metadata.gz: 285a31c7314187bae1a4866e5865f817a33f1f4192dc6df0991d345b71f8ca148de56bc3cae8c2c36199cffafa281b20efec533d2ba636fa11b031afed287496
-  data.tar.gz: c8d2458ee451774b353512e8eeab6351d85695775d9a3d09f326f83bb3b462a31830701b82e8867e177bcb9f58b4085b19ed1832c7ab8229afb63b718fb1ac05
+  metadata.gz: ca31eb9ecbdd3c343ec77621778bcf7cfba210b5a1b7ba05a02d0e590f3574c8e0e25a4bcb85be5a6af05a601874084a2fab94dd2c422073c588816c899c7f46
+  data.tar.gz: 6ade195ca0f67619dbffee9b6f4dd6d567ccd05b2dd069075a10403c897806c1f33c3f44b06ef91a5ea5212b85c4cbf4c3a8f1ca4e02988a9559781c991e884f

data/lib/async/container/error.rb

@@ -5,6 +5,7 @@
 
 module Async
 	module Container
+		# Represents an error that occured during container execution.
 		class Error < StandardError
 		end
 		
@@ -13,15 +14,18 @@ module Async
 		# Similar to {Interrupt}, but represents `SIGTERM`.
 		class Terminate < SignalException
 			SIGTERM = Signal.list["TERM"]
-
+			
+			# Create a new terminate error.
 			def initialize
 				super(SIGTERM)
 			end
 		end
 		
+		# Similar to {Interrupt}, but represents `SIGHUP`.
 		class Restart < SignalException
 			SIGHUP = Signal.list["HUP"]
 			
+			# Create a new restart error.
 			def initialize
 				super(SIGHUP)
 			end
@@ -29,13 +33,16 @@ module Async
 		
 		# Represents the error which occured when a container failed to start up correctly.
 		class SetupError < Error
+			# Create a new setup error.
+			#
+			# @parameter container [Generic] The container that failed.
 			def initialize(container)
 				super("Could not create container!")
 				
 				@container = container
 			end
 			
-			# The container that failed.
+			# @attribute [Generic] The container that failed.
 			attr :container
 		end
 	end

data/lib/async/container/forked.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 require_relative "error"
 
@@ -35,12 +35,18 @@ module Async
 						return instance
 					end
 					
+					# Initialize the child process instance.
+					#
+					# @parameter io [IO] The IO object to use for communication.
 					def initialize(io)
 						super
 						
 						@name = nil
 					end
 					
+					# Generate a hash representation of the process.
+					#
+					# @returns [Hash] The process as a hash, including `process_id` and `name`.
 					def as_json(...)
 						{
 							process_id: ::Process.pid,
@@ -48,11 +54,15 @@ module Async
 						}
 					end
 					
+					# Generate a JSON representation of the process.
+					#
+					# @returns [String] The process as JSON.
 					def to_json(...)
 						as_json.to_json(...)
 					end
 					
 					# Set the process title to the specified value.
+					#
 					# @parameter value [String] The name of the process.
 					def name= value
 						@name = value
@@ -61,14 +71,17 @@ module Async
 						::Process.setproctitle(@name.to_s)
 					end
 					
-					# The name of the process.
-					# @returns [String]
+					# @returns [String] The name of the process.
 					def name
 						@name
 					end
 					
 					# Replace the current child process with a different one. Forwards arguments and options to {::Process.exec}.
 					# This method replaces the child process with the new executable, thus this method never returns.
+					#
+					# @parameter arguments [Array] The arguments to pass to the new process.
+					# @parameter ready [Boolean] If true, informs the parent process that the child is ready. Otherwise, the child process will need to use a notification protocol to inform the parent process that it is ready.
+					# @parameter options [Hash] Additional options to pass to {::Process.exec}.
 					def exec(*arguments, ready: true, **options)
 						if ready
 							self.ready!(status: "(exec)")
@@ -81,6 +94,7 @@ module Async
 				end
 				
 				# Fork a child process appropriate for a container.
+				#
 				# @returns [Process]
 				def self.fork(**options)
 					# $stderr.puts fork: caller
@@ -105,6 +119,13 @@ module Async
 					end
 				end
 				
+				# Spawn a child process using {::Process.spawn}.
+				#
+				# The child process will need to inform the parent process that it is ready using a notification protocol.
+				#
+				# @parameter arguments [Array] The arguments to pass to the new process.
+				# @parameter name [String] The name of the process.
+				# @parameter options [Hash] Additional options to pass to {::Process.spawn}.
 				def self.spawn(*arguments, name: nil, **options)
 					self.new(name: name) do |process|
 						Notify::Pipe.new(process.out).before_spawn(arguments, options)
@@ -168,6 +189,7 @@ module Async
 					"\#<#{self.class} name=#{@name.inspect} status=#{@status.inspect} pid=#{@pid.inspect}>"
 				end
 				
+				# @returns [String] A string representation of the process.
 				alias to_s inspect
 				
 				# Invoke {#terminate!} and then {#wait} for the child process to exit.
@@ -215,7 +237,7 @@ module Async
 						Console.debug(self, "Waiting for process to exit...", pid: @pid)
 						
 						_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
-
+						
 						while @status.nil?
 							sleep(0.1)
 							

data/lib/async/container/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "etc"
 require "async/clock"
@@ -32,12 +32,16 @@ module Async
 		
 		# A base class for implementing containers.
 		class Generic
-			def self.run(*arguments, **options, &block)
-				self.new.run(*arguments, **options, &block)
+			# Run a new container.
+			def self.run(...)
+				self.new.run(...)
 			end
 			
 			UNNAMED = "Unnamed"
 			
+			# Initialize the container.
+			#
+			# @parameter options [Hash] Options passed to the {Group} instance.
 			def initialize(**options)
 				@group = Group.new(**options)
 				@running = true
@@ -145,6 +149,13 @@ 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!
+			end
+			
 			# Spawn a child instance into the container.
 			# @parameter name [String] The name of the child instance.
 			# @parameter restart [Boolean] Whether to restart the child instance if it fails.
@@ -176,9 +187,7 @@ module Async
 								case message
 								when :health_check!
 									if health_check_timeout&.<(age_clock.total)
-										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!
+										health_check_failed!(child, age_clock, health_check_timeout)
 									end
 								else
 									state.update(message)

data/lib/async/container/group.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require "fiber"
 require "async/clock"
@@ -25,6 +25,7 @@ module Async
 				@queue = nil
 			end
 			
+			# @returns [String] A human-readable representation of the group.
 			def inspect
 				"#<#{self.class} running=#{@running.size}>"
 			end

data/lib/async/container/hybrid.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2022, by Anton Sozontov.
 
 require_relative "forked"

data/lib/async/container/keyed.rb

@@ -1,29 +1,30 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module Container
 		# Tracks a key/value pair such that unmarked keys can be identified and cleaned up.
 		# This helps implement persistent processes that start up child processes per directory or configuration file. If those directories and/or configuration files are removed, the child process can then be cleaned up automatically, because those key/value pairs will not be marked when reloading the container.
 		class Keyed
+			# Initialize the keyed instance
+			#
+			# @parameter key [Object] The key.
+			# @parameter value [Object] The value.
 			def initialize(key, value)
 				@key = key
 				@value = value
 				@marked = true
 			end
 			
-			# The key. Normally a symbol or a file-system path.
-			# @attribute [Object]
+			# @attribute [Object] The key value, normally a symbol or a file-system path.
 			attr :key
 			
-			# The value. Normally a child instance of some sort.
-			# @attribute [Object]
+			# @attribute [Object] The value, normally a child instance.
 			attr :value
 			
-			# Has the instance been marked?
-			# @returns [Boolean]
+			# @returns [Boolean] True if the instance has been marked, during reloading the container.
 			def marked?
 				@marked
 			end
@@ -39,6 +40,8 @@ module Async
 			end
 			
 			# Stop the instance if it was not marked.
+			#
+			# @returns [Boolean] True if the instance was stopped.
 			def stop?
 				unless @marked
 					@value.stop

data/lib/async/container/notify/client.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module Container
 		# Handles the details of several process readiness protocols.
 		module Notify
+			# Represents a client that can send messages to the parent controller in order to notify it of readiness, status changes, etc.
+			#
+			# A process readiness protocol (e.g. `sd_notify`) is a simple protocol for a child process to notify the parent process that it is ready (e.g. to accept connections, to process requests, etc). This can help dependency-based startup systems to start services in the correct order, and to handle failures gracefully.
 			class Client
 				# Notify the parent controller that the child has become ready, with a brief status message.
 				# @parameters message [Hash] Additional details to send with the message.

data/lib/async/container/notify/log.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2025, by Samuel Williams.
 
 require_relative "client"
 require "socket"
@@ -9,13 +9,21 @@ require "socket"
 module Async
 	module Container
 		module Notify
+			# Represents a client that uses a local log file to communicate readiness, status changes, etc.
 			class Log < Client
 				# The name of the environment variable which contains the path to the notification socket.
 				NOTIFY_LOG = "NOTIFY_LOG"
 				
+				# @returns [String] The path to the notification log file.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
+				def self.path(environment = ENV)
+					environment[NOTIFY_LOG]
+				end
+				
 				# Open a notification client attached to the current {NOTIFY_LOG} if possible.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
 				def self.open!(environment = ENV)
-					if path = environment.delete(NOTIFY_LOG)
+					if path = self.path(environment)
 						self.new(path)
 					end
 				end

data/lib/async/container/notify/pipe.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Juan Antonio Martín Lucas.
 
 require_relative "client"
@@ -42,18 +42,18 @@ module Async
 					if notify_pipe = options.delete(:notify_pipe)
 						options[notify_pipe] = @io
 						environment[NOTIFY_PIPE] = notify_pipe.to_s
-					
+						
 					# Use stdout if it's not redirected:
 					# This can cause issues if the user expects stdout to be connected to a terminal.
 					# elsif !options.key?(:out)
 					# 	options[:out] = @io
 					# 	environment[NOTIFY_PIPE] = "1"
-					
+						
 					# Use fileno 3 if it's available:
 					elsif !options.key?(3)
 						options[3] = @io
 						environment[NOTIFY_PIPE] = "3"
-					
+						
 					# Otherwise, give up!
 					else
 						raise ArgumentError, "Please specify valid file descriptor for notify_pipe!"

data/lib/async/container/notify/server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Olle Jonsson.
 
 require "tmpdir"
@@ -11,9 +11,14 @@ require "securerandom"
 module Async
 	module Container
 		module Notify
+			# A simple UDP server that can be used to receive messages from a child process, tracking readiness, status changes, etc.
 			class Server
 				MAXIMUM_MESSAGE_SIZE = 4096
 				
+				# Parse a message, according to the `sd_notify` protocol.
+				#
+				# @parameter message [String] The message to parse.
+				# @returns [Hash] The parsed message.
 				def self.load(message)
 					lines = message.split("\n")
 					
@@ -38,6 +43,9 @@ module Async
 					return Hash[pairs]
 				end
 				
+				# Generate a new unique path for the UNIX socket.
+				#
+				# @returns [String] The path for the UNIX socket.
 				def self.generate_path
 					File.expand_path(
 						"async-container-#{::Process.pid}-#{SecureRandom.hex(8)}.ipc",
@@ -45,21 +53,33 @@ module Async
 					)
 				end
 				
+				# Open a new server instance with a temporary and unique path.
 				def self.open(path = self.generate_path)
 					self.new(path)
 				end
 				
+				# Initialize the server with the given path.
+				#
+				# @parameter path [String] The path to the UNIX socket.
 				def initialize(path)
 					@path = path
 				end
 				
+				# @attribute [String] The path to the UNIX socket.
 				attr :path
 				
+				# Generate a bound context for receiving messages.
+				#
+				# @returns [Context] The bound context.
 				def bind
 					Context.new(@path)
 				end
 				
+				# A bound context for receiving messages.
 				class Context
+					# Initialize the context with the given path.
+					#
+					# @parameter path [String] The path to the UNIX socket.
 					def initialize(path)
 						@path = path
 						@bound = Addrinfo.unix(@path, ::Socket::SOCK_DGRAM).bind
@@ -67,12 +87,16 @@ module Async
 						@state = {}
 					end
 					
+					# Close the bound context.
 					def close
 						@bound.close
 						
 						File.unlink(@path)
 					end
 					
+					# Receive a message from the bound context.
+					#
+					# @returns [Hash] The parsed message.
 					def receive
 						while true
 							data, _address, _flags, *_controls = @bound.recvmsg(MAXIMUM_MESSAGE_SIZE)

data/lib/async/container/notify/socket.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "client"
 require "socket"

data/lib/async/container/notify.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "notify/pipe"
 require_relative "notify/socket"

data/lib/async/container/statistics.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "async/reactor"
 
@@ -9,6 +9,7 @@ module Async
 	module Container
 		# Tracks various statistics relating to child instances in a container.
 		class Statistics
+			# Initialize the statistics all to 0.
 			def initialize
 				@spawns = 0
 				@restarts = 0

data/lib/async/container/threaded.rb

@@ -11,9 +11,6 @@ module Async
 	module Container
 		# A multi-thread container which uses {Thread.fork}.
 		class Threaded < Generic
-			class Kill < Exception
-			end
-			
 			# Indicates that this is not a multi-process container.
 			def self.multiprocess?
 				false
@@ -52,12 +49,18 @@ module Async
 						return instance
 					end
 					
+					# Initialize the child thread instance.
+					#
+					# @parameter io [IO] The IO object to use for communication with the parent.
 					def initialize(io)
 						@thread = ::Thread.current
 						
 						super
 					end
 					
+					# Generate a hash representation of the thread.
+					#
+					# @returns [Hash] The thread as a hash, including `process_id`, `thread_id`, and `name`.
 					def as_json(...)
 						{
 							process_id: ::Process.pid,
@@ -66,6 +69,9 @@ module Async
 						}
 					end
 					
+					# Generate a JSON representation of the thread.
+					#
+					# @returns [String] The thread as JSON.
 					def to_json(...)
 						as_json.to_json(...)
 					end
@@ -101,6 +107,9 @@ module Async
 					end
 				end
 				
+				# Start a new child thread and execute the provided block in it.
+				#
+				# @parameter options [Hash] Additional options to to the new child instance.
 				def self.fork(**options)
 					self.new(**options) do |thread|
 						::Thread.new do
@@ -113,6 +122,7 @@ module Async
 				end
 				
 				# Initialize the thread.
+				#
 				# @parameter name [String] The name to use for the child thread.
 				def initialize(name: nil)
 					super()
@@ -230,6 +240,9 @@ module Async
 						@error.nil?
 					end
 					
+					# Convert the status to a hash, suitable for serialization.
+					#
+					# @returns [Boolean | String] If the status is an error, the error message is returned, otherwise `true`.
 					def as_json(...)
 						if @error
 							@error.inspect

data/lib/async/container/version.rb

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

data/lib/async/container.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 require_relative "container/controller"
 
+# @namespace
 module Async
+	# @namespace
 	module Container
 	end
 end

data/lib/metrics/provider/async/container/generic.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "../../../../async/container/generic"
+require "metrics/provider"
+
+Metrics::Provider(Async::Container::Generic) do
+	ASYNC_CONTAINER_GENERIC_HEALTH_CHECK_FAILED = Metrics.metric("async.container.generic.health_check_failed", :counter, description: "The number of health checks that failed.")
+	
+	protected def health_check_failed!(child, age_clock, health_check_timeout)
+		ASYNC_CONTAINER_GENERIC_HEALTH_CHECK_FAILED.emit(1)
+		
+		super
+	end
+end

data/lib/metrics/provider/async/container.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "container/generic"

data/readme.md

@@ -18,10 +18,22 @@ 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.
 
+  - [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.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-container/releases/index) for all releases.
 
+### v0.25.0
+
+  - Introduce `async:container:notify:log:ready?` task for detecting process readiness.
+
+### v0.24.0
+
+  - Add support for health check failure metrics.
+
 ### v0.23.0
 
   - [Add support for `NOTIFY_LOG` for Kubernetes readiness probes.](https://socketry.github.io/async-container/releases/index#add-support-for-notify_log-for-kubernetes-readiness-probes.)

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.25.0
+
+  - Introduce `async:container:notify:log:ready?` task for detecting process readiness.
+
+## v0.24.0
+
+  - Add support for health check failure metrics.
+
 ## v0.23.0
 
 ### Add support for `NOTIFY_LOG` for Kubernetes readiness probes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.23.2
+  version: 0.25.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-28 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -80,6 +80,8 @@ files:
 - lib/async/container/statistics.rb
 - lib/async/container/threaded.rb
 - lib/async/container/version.rb
+- lib/metrics/provider/async/container.rb
+- lib/metrics/provider/async/container/generic.rb
 - license.md
 - readme.md
 - releases.md
@@ -96,14 +98,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.7
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.
 test_files: []