async-container-supervisor 0.6.1 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0534a1e50c30335199c89b543208bf81d9bd03cc4f48466823907a4c0a6103c5
-  data.tar.gz: 5e9520963dd453e093d26bd4809a629fc6fe9bcc483bf969246b8f3bc3e3e2cd
+  metadata.gz: ad71770c6717fe41a49b28a2f4614e7f539d572332805e44cc8f857d0c6cc404
+  data.tar.gz: 2f2ed9f22cce34b84f85c132f87b5c3296b539530ea26d0127a24dacdc4b5aac
 SHA512:
-  metadata.gz: ae89477d2957e756a2fd1fe28867d8f78254ddb43de232d5f2514c3040ba9f5fcce4c6533bd31fa7d03505a14e232ae31b853068e2e80a4d1c30331bc93698e1
-  data.tar.gz: 2f351b38c9ee9c2d603e56cb7dbf63f602660b65db6a7950db67c105d34e456dbc2f7aa2105f0ce46eb99a4c2b9c5efd6a08caa1c88e863f3980cdbef3f6c399
+  metadata.gz: 360ca6f0fe692937d47579307d9abd59f4879ce4eef88d927b32441eb71f40ac827ea63bc66e2c45b9b489072385de13f49c2bfb2698ab0ff878853d6a34d768
+  data.tar.gz: 8c655ae5432df6b742660ca02251b8f7d25ca2b8a2937aa59d66cf485b562e7abc9f1bd7154cdded585f0e773de40dc9c1bb93871871a56f8cda5288ae61fc60

checksums.yaml.gz.sig

@@ -1,2 +1,3 @@
-d*ׁ�������L�T>��r�r=t�T��u�.7��6���
-�?�ͮ���������ظ����@�5����d+
���j���
+M4������v7Ȫ'[C���͟��Ą��O9����pY����i��B�v`Znj��)��+E�a����V��d���}I�QY���=qw���U�wz��i�M��p		"�X-�.����}�Ȼ�A����@��saB��y�`��*e#5x-s��\��]���m3]�>�	���7�/�(��oE`#@##~���Ǎstٱ�B�)hQ�t��@�1�,���_���)<$�nk0o
+�"�{�*~K�o��rW�Am�����
�_����S�N�-r����jG��+��1���=h
���Mw��@����a��؁�-��%�d4�@
+X��2p�o*��j�!z�Smޚ����񄵘��@\��j2�Ґ�f��L�

data/context/getting-started.md

@@ -0,0 +1,166 @@
+# Getting Started
+
+This guide explains how to get started with `async-container-supervisor` to supervise and monitor worker processes in your Ruby applications.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add async-container-supervisor
+```
+
+## Core Concepts
+
+`async-container-supervisor` provides a robust process supervision system built on top of {ruby Async::Service::Generic}. The key components are:
+
+- {ruby Async::Container::Supervisor::Environment}: An environment mixin that sets up a supervisor service in your application.
+- {ruby Async::Container::Supervisor::Supervised}: An environment mixin that enables workers to connect to and be supervised by the supervisor.
+- {ruby Async::Container::Supervisor::Server}: The server that handles communication with workers and performs monitoring.
+- {ruby Async::Container::Supervisor::Worker}: A client that connects workers to the supervisor for health monitoring and diagnostics.
+
+### Process Architecture
+
+The supervisor operates as a multi-process architecture with three layers:
+
+```mermaid
+graph TD
+    Controller[Async::Container::Controller<br/>Root Process]
+    
+    Controller -->|spawns & manages| Supervisor[Supervisor Process<br/>async-container-supervisor]
+    Controller -->|spawns & manages| Worker1[Worker Process 1]
+    Controller -->|spawns & manages| Worker2[Worker Process 2]
+    Controller -->|spawns & manages| WorkerN[Worker Process N...]
+    
+    Worker1 -.->|connects via IPC| Supervisor
+    Worker2 -.->|connects via IPC| Supervisor
+    WorkerN -.->|connects via IPC| Supervisor
+    
+    style Controller fill:#e1f5ff
+    style Supervisor fill:#fff4e1
+    style Worker1 fill:#e8f5e9
+    style Worker2 fill:#e8f5e9
+    style WorkerN fill:#e8f5e9
+```
+
+**Important:** The supervisor process is itself just another process managed by the root controller. If the supervisor crashes, the controller will restart it, and all worker processes will automatically reconnect to the new supervisor. This design ensures high availability and fault tolerance.
+
+## Usage
+
+To use the supervisor, you need to define two services: one for the supervisor itself and one for your workers that will be supervised.
+
+### Basic Example
+
+Create a service configuration file (e.g., `service.rb`):
+
+```ruby
+#!/usr/bin/env async-service
+# frozen_string_literal: true
+
+require "async/container/supervisor"
+
+class MyWorkerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(name: self.class.name, count: 4, restart: true) do |instance|
+			Async do
+				# Connect to the supervisor if available:
+				if @environment.implements?(Async::Container::Supervisor::Supervised)
+					@evaluator.make_supervised_worker(instance).run
+				end
+				
+				# Mark the worker as ready:
+				instance.ready!
+				
+				# Your worker logic here:
+				loop do
+					# Do work...
+					sleep 1
+					
+					# Periodically update readiness:
+					instance.ready!
+				end
+			end
+		end
+	end
+end
+
+# Define the worker service:
+service "worker" do
+	service_class MyWorkerService
+	
+	# Enable supervision for this service:
+	include Async::Container::Supervisor::Supervised
+end
+
+# Define the supervisor service:
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+end
+```
+
+### Running the Service
+
+Make the service executable and run it:
+
+```bash
+$ chmod +x service.rb
+$ ./service.rb
+```
+
+This will start:
+- A supervisor process listening on a Unix socket
+- Four worker processes that connect to the supervisor
+
+### Adding Health Monitors
+
+You can add monitors to detect and respond to unhealthy conditions. For example, to add a memory monitor:
+
+```ruby
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			# Restart workers that exceed 500MB of memory:
+			Async::Container::Supervisor::MemoryMonitor.new(
+				interval: 10,  # Check every 10 seconds
+				limit: 1024 * 1024 * 500  # 500MB limit
+			)
+		]
+	end
+end
+```
+
+The {ruby Async::Container::Supervisor::MemoryMonitor} will periodically check worker memory usage and restart any workers that exceed the configured limit.
+
+### Collecting Diagnostics
+
+The supervisor can collect various diagnostics from workers on demand:
+
+- **Memory dumps**: Full heap dumps for memory analysis
+- **Thread dumps**: Stack traces of all threads
+- **Scheduler dumps**: Async fiber hierarchy
+- **Garbage collection profiles**: GC performance data
+
+These can be triggered programmatically or via command-line tools (when available).
+
+## Advanced Usage
+
+### Custom Monitors
+
+You can create custom monitors by implementing the monitor interface. A monitor should:
+
+1. Accept connections and periodically check worker health
+2. Take action (like restarting workers) when unhealthy conditions are detected
+
+### Fault Tolerance
+
+The supervisor architecture is designed for fault tolerance:
+
+- **Supervisor crashes**: When the supervisor process crashes, the root controller automatically restarts it. Workers detect the disconnection and reconnect to the new supervisor.
+- **Worker crashes**: The container automatically restarts crashed workers based on the `restart: true` configuration.
+- **Communication failures**: Workers gracefully handle supervisor unavailability and will attempt to reconnect.
+
+This design ensures your application remains operational even when individual processes fail.

data/context/index.yaml

@@ -0,0 +1,12 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A supervisor for managing multiple container processes.
+metadata:
+  documentation_uri: https://socketry.github.io/async-container-supervisor/
+  source_code_uri: https://github.com/socketry/async-container-supervisor.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `async-container-supervisor`
+    to supervise and monitor worker processes in your Ruby applications.

data/lib/async/container/supervisor/connection.rb

@@ -185,9 +185,12 @@ module Async
 							if call = @calls[id]
 								# Response to a call:
 								call.push(**message)
-							else
+							elsif message.key?(:do)
 								# Incoming call:
 								Call.dispatch(self, target, id, message)
+							else
+								# Likely a response to a timed-out call, ignore it:
+								Console.debug(self, "Ignoring message:", message)
 							end
 						else
 							Console.error(self, "Unknown message:", message)

data/lib/async/container/supervisor/dispatchable.rb

@@ -14,7 +14,7 @@ module Async
 					method_name = "do_#{call.message[:do]}"
 					self.public_send(method_name, call)
 				rescue => error
-					Console.error(self, "Error while dispatching call.", exception: error, call: call)
+					Console.error(self, "Error while dispatching call!", exception: error, call: call)
 					
 					call.fail(error: {
 						class: error.class,

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

@@ -27,11 +27,9 @@ module Async
 					call.connection.state.merge!(call.message[:state])
 					
 					@monitors.each do |monitor|
-						begin
-							monitor.register(call.connection)
-						rescue => error
-							Console.error(self, "Error while registering process!", monitor: monitor, exception: error)
-						end
+						monitor.register(call.connection)
+					rescue => error
+						Console.error(self, "Error while registering process!", monitor: monitor, exception: error)
 					end
 				ensure
 					call.finish
@@ -59,22 +57,18 @@ module Async
 				
 				def remove(connection)
 					@monitors.each do |monitor|
-						begin
-							monitor.remove(connection)
-						rescue => error
-							Console.error(self, "Error while removing process!", monitor: monitor, exception: error)
-						end
+						monitor.remove(connection)
+					rescue => error
+						Console.error(self, "Error while removing process!", monitor: monitor, exception: error)
 					end
 				end
 				
 				def run(parent: Task.current)
 					parent.async do |task|
 						@monitors.each do |monitor|
-							begin
-								monitor.run
-							rescue => error
-								Console.error(self, "Error while starting monitor!", monitor: monitor, exception: error)
-							end
+							monitor.run
+						rescue => error
+							Console.error(self, "Error while starting monitor!", monitor: monitor, exception: error)
 						end
 						
 						@endpoint.accept do |peer|

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

@@ -6,7 +6,7 @@
 module Async
 	module Container
 		module Supervisor
-			VERSION = "0.6.1"
+			VERSION = "0.6.3"
 		end
 	end
 end

data/readme.md

@@ -16,10 +16,20 @@ Provides a supervisor service for
 
 Please see the [project documentation](https://socketry.github.io/async-container-supervisor/) for more details.
 
+  - [Getting Started](https://socketry.github.io/async-container-supervisor/guides/getting-started/index) - This guide explains how to get started with `async-container-supervisor` to supervise and monitor worker processes in your Ruby applications.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-container-supervisor/releases/index) for all releases.
 
+### v0.6.3
+
+  - Add agent context documentation.
+
+### v0.6.2
+
+  - Fix timed out RPCs and subsequent responses which should be ignored.
+
 ### v0.6.0
 
   - Add `async:container:supervisor:reload` command to restart the container (blue/green deployment).

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.6.3
+
+  - Add agent context documentation.
+
+## v0.6.2
+
+  - Fix timed out RPCs and subsequent responses which should be ignored.
+
 ## v0.6.0
 
   - Add `async:container:supervisor:reload` command to restart the container (blue/green deployment).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.3
 platform: ruby
 authors:
 - Samuel Williams
@@ -85,6 +85,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - bake/async/container/supervisor.rb
+- context/getting-started.md
+- context/index.yaml
 - lib/async/container/supervisor.rb
 - lib/async/container/supervisor/client.rb
 - lib/async/container/supervisor/connection.rb