async-service-supervisor 0.13.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40d92dff9ef46f5a5864fb8c013d3756c89b0941568cbb8fad482b3d5980c26e
-  data.tar.gz: b5ca32ff2ade3e7e07bc58e4b9a52d7dabb8df87f33001907fec2032ad9977da
+  metadata.gz: acb581fece1b2ca0364e8b7f3fee2893c15d788f022377c23ba810a71276beb7
+  data.tar.gz: 68d38aa49e35ef1c63e6f214ff271daca6650dfa5bffb1d628eb0f429b5d6219
 SHA512:
-  metadata.gz: 66e3fe09be98818698e57e38070e55ef5fad22123ddeda1c15685426f5a90ab37d77b8a2da1f10ae2ebf69549f8c402870b6c535f30505b5db092e446f052c6f
-  data.tar.gz: a52324ca442e95f5161a93ebc562eebfb23838c59452a0e0d517d99686f6e7f17e696d7a1c386f34dd193252c33a96a2ff2ee026becd96a32bb55c09d7e1e967
+  metadata.gz: b46f7d61a4ec984478e0fbc062ebb14dc48899a2c004dc23c1446a69f2d095e5614f4eb6fedc0a7d6f264318ea84ce2f12a69b99bff643c18b0b2ef35b13fa8d
+  data.tar.gz: a836860985fc1753ca0b116a9d929562c8b24fd9ba474043c178e2dfa26dd59caf64106ce96a3b508762560c88d5ea39fb74f72d63559f91fab425e79c1869e1

data/lib/async/service/supervisor/memory_monitor.rb

@@ -6,7 +6,7 @@
 require "memory/leak/cluster"
 require "set"
 
-require_relative "loop"
+require_relative "monitor"
 
 module Async
 	module Service
@@ -14,7 +14,7 @@ module Async
 			# Monitors worker memory usage and restarts workers that exceed limits.
 			#
 			# Uses the `memory` gem to track process memory and detect leaks.
-			class MemoryMonitor
+			class MemoryMonitor < Monitor
 				# Create a new memory monitor.
 				#
 				# @parameter interval [Integer] The interval at which to check for memory leaks.
@@ -22,7 +22,7 @@ module Async
 				# @parameter free_size_minimum [Integer] The minimum free memory threshold, or nil for no threshold.
 				# @parameter options [Hash] Options to pass to the cluster when adding processes.
 				def initialize(interval: 10, total_size_limit: nil, free_size_minimum: nil, **options)
-					@interval = interval
+					super(interval: interval)
 					@cluster = Memory::Leak::Cluster.new(total_size_limit: total_size_limit, free_size_minimum: free_size_minimum)
 					
 					# We use these options when adding processes to the cluster:
@@ -85,28 +85,11 @@ module Async
 					end
 				end
 				
-				# The key used when this monitor's status is aggregated with others.
-				def self.monitor_type
-					:memory_monitor
-				end
-				
 				# Serialize memory cluster data for JSON.
 				def as_json
 					@cluster.as_json
 				end
 				
-				# Serialize to JSON string.
-				def to_json(...)
-					as_json.to_json(...)
-				end
-				
-				# Get status for the memory monitor.
-				#
-				# @returns [Hash] Hash with type and data keys.
-				def status
-					{type: self.class.monitor_type, data: as_json}
-				end
-				
 				# Invoked when a memory leak is detected.
 				#
 				# @parameter process_id [Integer] The process ID of the process that has a memory leak.
@@ -128,21 +111,15 @@ module Async
 					true
 				end
 				
-				# Run the memory monitor.
-				#
-				# @returns [Async::Task] The task that is running the memory monitor.
-				def run
-					Async do
-						Loop.run(interval: @interval) do
-							@guard.synchronize do
-								# This block must return true if the process was killed.
-								@cluster.check! do |process_id, monitor|
-									begin
-										memory_leak_detected(process_id, monitor)
-									rescue => error
-										Console.error(self, "Failed to handle memory leak!", child: {process_id: process_id}, exception: error)
-									end
-								end
+				# Run one iteration of the memory monitor.
+				def run_once
+					@guard.synchronize do
+						# This block must return true if the process was killed.
+						@cluster.check! do |process_id, monitor|
+							begin
+								memory_leak_detected(process_id, monitor)
+							rescue => error
+								Console.error(self, "Failed to handle memory leak!", child: {process_id: process_id}, exception: error)
 							end
 						end
 					end

data/lib/async/service/supervisor/monitor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/loop"
+
+module Async
+	module Service
+		module Supervisor
+			class Monitor
+				def initialize(interval: 1.0)
+					@interval = interval
+				end
+				
+				def as_json(...)
+					{}
+				end
+				
+				# Serialize to JSON string.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
+				# Get aggregated utilization status by service name.
+				#
+				# Reads utilization data from all registered workers and aggregates it
+				# by service name (from supervisor_controller.state[:name]).
+				#
+				# @returns [Hash] Hash with type and data keys.
+				def status
+					{type: self.class.name, data: as_json}
+				end
+				
+				# Run one iteration of the monitor.
+				def run_once
+					# This method can be overridden by subclasses to implement specific monitoring logic.
+				end
+				
+				# Run the utilization monitor.
+				#
+				# Periodically aggregates utilization data from all workers.
+				#
+				# @returns [Async::Task] The task that is running the utilization monitor.
+				def run(parent: Async::Task.current)
+					parent.async do
+						Loop.periodic(interval: @interval) do
+							self.run_once
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/service/supervisor/process_monitor.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025-2026, by Samuel Williams.
 
 require "process/metrics"
-require_relative "loop"
+require_relative "monitor"
 
 module Async
 	module Service
@@ -15,13 +15,13 @@ module Async
 			# Unlike {MemoryMonitor}, this monitor captures metrics for the entire process tree
 			# by tracking the parent process ID (ppid), which is more efficient than tracking
 			# individual processes.
-			class ProcessMonitor
+			class ProcessMonitor < Monitor
 				# Create a new process monitor.
 				#
 				# @parameter interval [Integer] The interval in seconds at which to log process metrics.
 				# @parameter ppid [Integer] The parent process ID to monitor. If nil, uses the current process to capture its children.
 				def initialize(interval: 60, ppid: nil)
-					@interval = interval
+					super(interval: interval)
 					@ppid = ppid || Process.ppid
 				end
 				
@@ -67,33 +67,13 @@ module Async
 					{ppid: @ppid, metrics: self.metrics}
 				end
 				
-				# Serialize to JSON string.
-				def to_json(...)
-					as_json.to_json(...)
-				end
-				
-				# Get status for the process monitor.
-				#
-				# @returns [Hash] Hash with type and data keys.
-				def status
-					{type: self.class.monitor_type, data: as_json}
-				end
-				
-				# Run the process monitor.
-				#
-				# Periodically captures and logs process metrics for the entire process tree.
-				#
-				# @returns [Async::Task] The task that is running the process monitor.
-				def run
-					Async do
-						Loop.run(interval: @interval) do
-							metrics = self.metrics
-							
-							# Log each process individually for better searchability in log platforms:
-							metrics.each do |process_id, general|
-								Console.info(self, "Process metrics captured.", general: general)
-							end
-						end
+				# Run one iteration of the process monitor.
+				def run_once
+					metrics = self.metrics
+					
+					# Log each process individually for better searchability in log platforms:
+					metrics.each do |process_id, general|
+						Console.info(self, "Process metrics captured.", general: general)
 					end
 				end
 			end

data/lib/async/service/supervisor/server.rb

@@ -87,30 +87,34 @@ module Async
 				# @parameter parent [Async::Task] The parent task to run under.
 				def run
 					Sync do |task|
+						barrier = Async::Barrier.new
+						
 						# Start all monitors:
 						@monitors.each do |monitor|
-							monitor.run
+							monitor.run(parent: barrier)
 						rescue => error
 							Console.error(self, "Error while starting monitor!", monitor: monitor, exception: error)
 						end
 						
-						# Accept connections from workers:
-						self.accept do |connection|
-							# Create a supervisor controller for this connection:
-							supervisor_controller = SupervisorController.new(self, connection)
-							
-							# Bind supervisor controller:
-							connection.bind(:supervisor, supervisor_controller)
-							
-							# Run the connection:
-							connection.run
-						ensure
-							self.remove(supervisor_controller)
+						barrier.async do
+							# Accept connections from workers:
+							self.accept do |connection|
+								# Create a supervisor controller for this connection:
+								supervisor_controller = SupervisorController.new(self, connection)
+								
+								# Bind supervisor controller:
+								connection.bind(:supervisor, supervisor_controller)
+								
+								# Run the connection:
+								connection.run
+							ensure
+								self.remove(supervisor_controller)
+							end
 						end
 						
-						task.children&.each(&:wait)
+						barrier.wait
 					ensure
-						task.stop
+						barrier&.stop
 					end
 				end
 			end

data/lib/async/service/supervisor/utilization_monitor.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by Samuel Williams.
 
 require "set"
 
-require_relative "loop"
+require_relative "monitor"
 require "async/utilization"
 
 module Async
@@ -15,7 +15,7 @@ module Async
 			#
 			# Uses shared memory to efficiently collect utilization metrics from workers
 			# and aggregates them by service name for monitoring and reporting.
-			class UtilizationMonitor
+			class UtilizationMonitor < Monitor
 				# Allocates and manages shared memory segments for worker utilization data.
 				#
 				# Manages a shared memory file that workers can write utilization metrics to.
@@ -195,8 +195,8 @@ module Async
 				# @parameter size [Integer] Total size of the shared memory buffer.
 				# @parameter segment_size [Integer] Size of each allocation segment (default: 512 bytes).
 				def initialize(path: "utilization.shm", interval: 10, size: IO::Buffer::PAGE_SIZE * 8, segment_size: 512)
+					super(interval: interval)
 					@path = path
-					@interval = interval
 					@segment_size = segment_size
 					
 					@allocator = SegmentAllocator.new(path, size: size, segment_size: segment_size)
@@ -313,21 +313,6 @@ module Async
 					end
 				end
 				
-				# Serialize to JSON string.
-				def to_json(...)
-					as_json.to_json(...)
-				end
-				
-				# Get aggregated utilization status by service name.
-				#
-				# Reads utilization data from all registered workers and aggregates it
-				# by service name (from supervisor_controller.state[:name]).
-				#
-				# @returns [Hash] Hash with type and data keys.
-				def status
-					{type: self.class.monitor_type, data: as_json}
-				end
-				
 				# Emit the utilization metrics.
 				#
 				# @parameter status [Hash] The utilization metrics.
@@ -335,17 +320,9 @@ module Async
 					Console.info(self, "Utilization:", metrics: metrics)
 				end
 				
-				# Run the utilization monitor.
-				#
-				# Periodically aggregates utilization data from all workers.
-				#
-				# @returns [Async::Task] The task that is running the utilization monitor.
-				def run
-					Async do
-						Loop.run(interval: @interval) do
-							self.emit(self.as_json)
-						end
-					end
+				# Run one iteration of the utilization monitor.
+				def run_once
+					self.emit(self.as_json)
 				end
 			end
 		end

data/lib/async/service/supervisor/version.rb

@@ -9,7 +9,7 @@ module Async
 	module Service
 		# @namespace
 		module Supervisor
-			VERSION = "0.13.1"
+			VERSION = "0.15.0"
 		end
 	end
 end

data/lib/async/service/supervisor/worker.rb

@@ -76,12 +76,20 @@ module Async
 					observer.schema.to_a
 				end
 				
+				# Create the worker controller for this worker.
+				#
+				# Override this method to provide a custom worker controller that exposes additional RPCs to the supervisor.
+				#
+				# @returns [WorkerController] The worker controller instance.
+				def make_controller
+					WorkerController.new(self)
+				end
+				
 				protected def connected!(connection)
 					super
 					
 					# Create and bind worker controller
-					worker_controller = WorkerController.new(self)
-					worker_proxy = connection.bind(:worker, worker_controller)
+					worker_proxy = connection.bind(:worker, make_controller)
 					
 					# Register the worker with the supervisor
 					# The supervisor allocates a unique ID and returns it

data/readme.md

@@ -28,6 +28,14 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor/releases/index) for all releases.
 
+### v0.15.0
+
+  - Improve robustness and error handling of default monitors and server loop, ensuring that monitor failures either completely crash the server or retry appropriately, rather than leaving the server in a broken state.
+
+### v0.14.0
+
+  - Add `Worker#make_controller` as an override point for providing a custom worker controller with additional RPCs.
+
 ### v0.13.1
 
   - Unlink shared memory file before opening on supervisor restart, preventing SIGBUS when workers still have the file mapped.
@@ -69,14 +77,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
   - Add `Async::Service::Supervisor::ProcessMonitor` for logging CPU and memory metrics periodically.
   - Fix documentation to use correct `maximum_size_limit:` parameter name for `MemoryMonitor` (was incorrectly documented as `limit:`).
 
-### v0.7.0
-
-  - If a memory leak is detected, sample memory usage for 60 seconds before exiting.
-
-### v0.6.4
-
-  - Make client task (in supervised worker) transient, so that it doesn't keep the reactor alive unnecessarily. It also won't be stopped by default when SIGINT is received, so that the worker will remain connected to the supervisor until the worker is completely terminated.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.15.0
+
+  - Improve robustness and error handling of default monitors and server loop, ensuring that monitor failures either completely crash the server or retry appropriately, rather than leaving the server in a broken state.
+
+## v0.14.0
+
+  - Add `Worker#make_controller` as an override point for providing a custom worker controller with additional RPCs.
+
 ## v0.13.1
 
   - Unlink shared memory file before opening on supervisor restart, preventing SIGBUS when workers still have the file mapped.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.15.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,6 +38,20 @@ cert_chain:
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.38'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.38'
 - !ruby/object:Gem::Dependency
   name: async-bus
   requirement: !ruby/object:Gem::Requirement
@@ -151,8 +165,8 @@ files:
 - lib/async/service/supervisor/client.rb
 - lib/async/service/supervisor/endpoint.rb
 - lib/async/service/supervisor/environment.rb
-- lib/async/service/supervisor/loop.rb
 - lib/async/service/supervisor/memory_monitor.rb
+- lib/async/service/supervisor/monitor.rb
 - lib/async/service/supervisor/process_monitor.rb
 - lib/async/service/supervisor/server.rb
 - lib/async/service/supervisor/service.rb
@@ -185,7 +199,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A supervisor for managing multiple container processes.
 test_files: []

data/lib/async/service/supervisor/loop.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025-2026, by Samuel Williams.
-
-module Async
-	module Service
-		module Supervisor
-			# A helper for running loops at aligned intervals.
-			module Loop
-				# A robust loop that executes a block at aligned intervals.
-				#
-				# The alignment is modulo the current clock in seconds.
-				#
-				# If an error occurs during the execution of the block, it is logged and the loop continues.
-				#
-				# @parameter interval [Integer] The interval in seconds between executions of the block.
-				def self.run(interval: 60, &block)
-					while true
-						# Compute the wait time to the next interval:
-						wait = interval - (Time.now.to_f % interval)
-						if wait.positive?
-							# Sleep until the next interval boundary:
-							sleep(wait)
-						end
-						
-						begin
-							yield
-						rescue => error
-							Console.error(self, "Loop error:", error)
-						end
-					end
-				end
-			end
-			
-			private_constant :Loop
-		end
-	end
-end
-