async-container 0.23.2 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7d6beef9d67eb3befeb6df39c14194bef86cefa104924e7eaff052571efbf68
-  data.tar.gz: d18ac658a4dac083de68527533e1f476dfe56085b4ba67a46fa9e3ba8e92fa45
+  metadata.gz: d8b5dae742b5445c83c515d4745a49df725f9eea920e43340913b19239af8aa6
+  data.tar.gz: b4153930bb6ee37055e5675c921193ec27221c754ced2250975a2ba13fb0fda8
 SHA512:
-  metadata.gz: 285a31c7314187bae1a4866e5865f817a33f1f4192dc6df0991d345b71f8ca148de56bc3cae8c2c36199cffafa281b20efec533d2ba636fa11b031afed287496
-  data.tar.gz: c8d2458ee451774b353512e8eeab6351d85695775d9a3d09f326f83bb3b462a31830701b82e8867e177bcb9f58b4085b19ed1832c7ab8229afb63b718fb1ac05
+  metadata.gz: 76a94fbd31a24ac6b6dccd52cde65bee5da8ec4e7fedb87493ffa4b67f64de387d88ddf7bff2edcec4e2075d928d52ed0273ffd6315cde69f8350d3e902a7db8
+  data.tar.gz: 424b331952bc76e338c21288fc710575bd651061ebcc8c5522b0c3aa4f3f4603726afdf75febba5e4ca6242d182d07603bed81043af14814ef7b397659ca3961

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

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

data/lib/async/container/generic.rb

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

@@ -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/keyed.rb

@@ -8,22 +8,23 @@ module Async
 		# 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

@@ -7,6 +7,9 @@ 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

@@ -9,6 +9,7 @@ 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"

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

@@ -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/statistics.rb

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

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.23.2"
+		VERSION = "0.24.0"
 	end
 end

data/lib/async/container.rb

@@ -5,7 +5,9 @@
 
 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.23.2
+  version: 0.24.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: 2025-03-07 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