async-service-supervisor 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '029cb4427e2cee4272b2bb5d49700ece5cb157df2811801b67ae07cc038ee1ff'
-  data.tar.gz: 19805fd9a9c8b08dc4c616fa1c71b0e535f3e20d9269173e4c03edb4fd64d620
+  metadata.gz: 5d6f60f666c3e162c85ca9a275a74dd74dc2219230950d18a0ecf08cffa5761a
+  data.tar.gz: 2c78c20413ca658e6f2341999bfe42fc1600028978ab134ea10f0b0bed5ac44c
 SHA512:
-  metadata.gz: 935ca7b2c54a90461933dc59fb98e0fbc198ee0b93243e252a3b7bb1a00893ae95d72a8987a5637afd12a4ff522bca60f3f843cd5115f02fd2f11890a510fe8e
-  data.tar.gz: af3a62820c3d169de534df5f5832ab2f9b75e975f0b086114d7ec7442261b74690da9ec4a822f0071e2e4c8b347e6c11e446858ebda86b9ba06193d44bba504e
+  metadata.gz: c4f862fdaeef651d0b736381340277720b987ac70a3f2e32481a636c638a251f30f5340da9f9789938eb4c7e25b9188b1e3f83c86ae0846f2620d23c9e69365f
+  data.tar.gz: 59291a5fe82bd9dbd2b42ef041b2cde87648666c787c99c90725b88576c0484e759c11fdd6a23ce8d58ce4666f6d21e9258065a2af870f040ab74cbccf15d50a

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,64 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/loop"
+
+module Async
+	module Service
+		module Supervisor
+			# Base class for supervisor monitors that run periodically within the supervisor process.
+			#
+			# Subclasses should override {#run_once} to implement specific monitoring logic.
+			class Monitor
+				# Initialize a new monitor.
+				#
+				# @parameter interval [Numeric] The interval in seconds between each invocation of {#run_once}.
+				def initialize(interval: 1.0)
+					@interval = interval
+				end
+				
+				# Serialize the monitor state for JSON representation.
+				#
+				# @returns [Hash] An empty hash by default; subclasses should override to include relevant state.
+				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,34 +67,19 @@ 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.
+				# Emit the process metrics.
 				#
-				# @returns [Hash] Hash with type and data keys.
-				def status
-					{type: self.class.monitor_type, data: as_json}
+				# @parameter metrics [Hash] The process metrics to emit.
+				def emit(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 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
-					end
+				# Run one iteration of the process monitor.
+				def run_once
+					self.emit(self.metrics)
 				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

@@ -5,7 +5,7 @@
 
 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.14.0"
+			VERSION = "0.16.0"
 		end
 	end
 end

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.16.0
+
+  - Add `ProcessMonitor#emit(metrics)` as an override point for subclasses to consume captured process metrics (e.g. emitting StatsD gauges).
+
+### 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.
@@ -68,15 +76,6 @@ Please see the [project releases](https://socketry.github.io/async-service-super
   - Disable memory sampler by default and use text output format.
       - Introduce support for redirecting dump output to logs.
 
-### v0.8.0
-
-  - 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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.16.0
+
+  - Add `ProcessMonitor#emit(metrics)` as an override point for subclasses to consume captured process metrics (e.g. emitting StatsD gauges).
+
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.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

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
-