async-service-supervisor 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5058893b1b7ea249bcd4e273f169fb9a4649523380d545c08a281f20d6f56c0
-  data.tar.gz: d17a7bc6d6443ffd962118ae45d1dbfa6cf7a890d5b91ca1d74c9f050d45177b
+  metadata.gz: 1a442d07a68cfadfaf0a5a1e15e5ec7b0936580c74e6cc49b30997816b0e62b2
+  data.tar.gz: d275c9154c1e9cd9a8c37bee158b1121ebdbb0d78e4b86b2bead32f32d55e1f1
 SHA512:
-  metadata.gz: 344766f9eb24ca6fae65844a8e5654fb197b829efe89363b0bdff1e9bfd322fcc1e0f1b121ef1ae2579d03174b14226c0a2f76a5de3a7e3ceff4ff6f48416366
-  data.tar.gz: 2efa90fef449b5a0b52ea738a4f078a32c9df70d41a2d42dcf3e7e0d02b1f67c6290bca1b5c073ef838e482b56abd97d9d2e1fe1019e383c62659946df52cee1
+  metadata.gz: b47eb23e854c83816211f4385a6c88a8ace3b5e71512469a73c63968a2569c1288bb2cc68a6e0c2f0e874405477906d12839eefc07d83123fa5c6cf48e3c904e
+  data.tar.gz: f1831a15940111dce4550208f6d0047e21bd6fff32015f98c1aee44c650ea41fcf540707e509b84e7146ff2f3e18a08503c787699311fc0dd36a2a0806fadc7d

data/context/index.yaml

@@ -10,6 +10,11 @@ files:
   title: Getting Started
   description: This guide explains how to get started with `async-service-supervisor`
     to supervise and monitor worker processes in your Ruby applications.
+- path: migration.md
+  title: Migration Guide
+  description: This guide explains how to migrate from `async-container-supervisor`
+    to `async-service-supervisor`. The new version provides a cleaner API built on
+    `Async::Bus` for improved reliability and maintainability.
 - path: memory-monitor.md
   title: Memory Monitor
   description: This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::MemoryMonitor</code>

data/context/migration.md

@@ -0,0 +1,311 @@
+# Migration Guide
+
+This guide explains how to migrate from `async-container-supervisor` to `async-service-supervisor`. The new version provides a cleaner API built on `Async::Bus` for improved reliability and maintainability.
+
+## Overview
+
+`async-service-supervisor` is the successor to `async-container-supervisor`, providing the same process supervision capabilities with an improved architecture. The main changes include:
+
+- **Namespace migration**: `Async::Container::Supervisor` → `Async::Service::Supervisor`.
+- **Simplified worker connection API**: New `prepare!` method replaces manual worker creation.
+- **Bus-based communication**: Uses `Async::Bus` for more reliable IPC.
+- **Improved environment integration**: Better integration with `Async::Service::Managed::Environment`.
+
+## Why Migrate?
+
+The new version provides several benefits:
+
+- **Better reliability**: Built on `Async::Bus` which provides more robust communication patterns.
+- **Simpler API**: Less boilerplate code required for worker setup.
+- **Better integration**: Improved integration with the `async-service` ecosystem.
+- **Future-proof**: Aligned with the direction of the async-service framework.
+
+## Step-by-Step Migration
+
+### 1. Update Gem Dependency
+
+Update your `Gemfile` or `gems.rb`:
+
+```ruby
+# Before:
+gem "async-container-supervisor"
+
+# After:
+gem "async-service-supervisor"
+```
+
+Then run:
+
+```bash
+$ bundle install
+```
+
+### 2. Update Require Statements
+
+Update all require statements in your code:
+
+```ruby
+# Before:
+require "async/container/supervisor"
+
+# After:
+require "async/service/supervisor"
+```
+
+### 3. Update Namespace References
+
+Replace all references to `Async::Container::Supervisor` with `Async::Service::Supervisor`:
+
+```ruby
+# Before:
+include Async::Container::Supervisor::Environment
+include Async::Container::Supervisor::Supervised
+
+Async::Container::Supervisor::MemoryMonitor.new(...)
+Async::Container::Supervisor::ProcessMonitor.new(...)
+
+# After:
+include Async::Service::Supervisor::Environment
+include Async::Service::Supervisor::Supervised
+
+Async::Service::Supervisor::MemoryMonitor.new(...)
+Async::Service::Supervisor::ProcessMonitor.new(...)
+```
+
+### 4. Update Worker Service Setup
+
+The worker connection API has been simplified. Update your worker service implementation:
+
+**Before (`async-container-supervisor`):**
+
+```ruby
+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
+					instance.ready!
+				end
+			end
+		end
+	end
+end
+```
+
+**After (`async-service-supervisor`):**
+
+```ruby
+class MyWorkerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(name: self.class.name, count: 4, restart: true) do |instance|
+			Async do
+				# Get the environment evaluator:
+				evaluator = self.environment.evaluator
+				
+				# Prepare the instance (connects to supervisor if available):
+				evaluator.prepare!(instance)
+				
+				# Mark the worker as ready:
+				instance.ready!
+				
+				# Your worker logic here:
+				loop do
+					# Do work...
+					sleep 1
+					instance.ready!
+				end
+			end
+		end
+	end
+end
+```
+
+**Key changes:**
+- Removed the `implements?` check - `prepare!` handles this automatically.
+- Use `evaluator.prepare!(instance)` instead of `@evaluator.make_supervised_worker(instance).run`.
+- The `prepare!` method calls `super(instance)` first (which may invoke parent module implementations), then connects to the supervisor by calling `supervisor_worker.run`.
+
+### 5. Update Service Configuration
+
+Update your service configuration blocks:
+
+```ruby
+# Before:
+service "worker" do
+	service_class MyWorkerService
+	include Async::Container::Supervisor::Supervised
+end
+
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+end
+
+# After:
+service "worker" do
+	service_class MyWorkerService
+	include Async::Service::Supervisor::Supervised
+end
+
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+end
+```
+
+### 6. Update Monitor Configuration
+
+Monitor configuration remains the same, but update the class names:
+
+```ruby
+# Before:
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			Async::Container::Supervisor::ProcessMonitor.new(interval: 60),
+			Async::Container::Supervisor::MemoryMonitor.new(
+				interval: 10,
+				maximum_size_limit: 1024 * 1024 * 500
+			)
+		]
+	end
+end
+
+# After:
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+	
+	monitors do
+		[
+			Async::Service::Supervisor::ProcessMonitor.new(interval: 60),
+			Async::Service::Supervisor::MemoryMonitor.new(
+				interval: 10,
+				maximum_size_limit: 1024 * 1024 * 500
+			)
+		]
+	end
+end
+```
+
+### 7. Update Bake Tasks
+
+If you're using bake tasks, update the namespace:
+
+**Before:**
+
+```bash
+$ bake async:container:supervisor:restart
+$ bake async:container:supervisor:reload
+$ bake async:container:supervisor:status
+$ bake async:container:supervisor:memory_sample duration=30 connection_id=...
+```
+
+**After:**
+
+```bash
+$ bake async:service:supervisor:restart
+$ bake async:service:supervisor:reload
+$ bake async:service:supervisor:status
+```
+
+**Note:** The `memory_sample` bake task has been removed in `async-service-supervisor`. This functionality was removed as it wasn't very useful and added complexity. If you were using memory sampling, you'll need to find alternative approaches for memory leak detection, such as using the `MemoryMonitor` with appropriate limits or external memory profiling tools.
+
+### 8. Update Programmatic Client Usage
+
+If you're using the supervisor client programmatically, update the API:
+
+**Before (`async-container-supervisor`):**
+
+```ruby
+client = Async::Container::Supervisor::Client.new(endpoint: endpoint)
+client.connect do |connection|
+	# Direct call-based API:
+	result = connection.call(do: :restart)
+	result = connection.call(do: :status)
+	result = connection.call(do: :forward, operation: {...}, connection_id: "...")
+end
+```
+
+**After (`async-service-supervisor`):**
+
+```ruby
+client = Async::Service::Supervisor::Client.new(endpoint: endpoint)
+client.connect do |connection|
+	# Bus-based API with controller:
+	supervisor = connection[:supervisor]
+	supervisor.restart
+	supervisor.status
+	
+	# Worker operations use the worker controller:
+	worker = connection[:worker]
+	# Worker operations are available through the worker controller
+end
+```
+
+**Key changes:**
+- Client now extends `Async::Bus::Client` instead of custom implementation.
+- Access supervisor operations via `connection[:supervisor]` instead of `connection.call(do: :...)`.
+- Worker operations are accessed through `connection[:worker]` controller.
+- The `forward` operation (used for `memory_sample` and other worker operations) has been removed - use the worker controller API instead.
+
+### 9. Update Environment Module Usage
+
+The `Environment` module now includes `Async::Service::Managed::Environment` and has additional methods:
+
+**New in `async-service-supervisor`:**
+
+```ruby
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+	
+	# You can now override count if needed (defaults to 1):
+	def count
+		1  # Always 1 for supervisor
+	end
+	
+	# container_options now merges with Managed::Environment defaults
+end
+```
+
+The `container_options` method now properly merges with `Managed::Environment` defaults, providing better integration with the async-service framework.
+
+## Architecture Changes
+
+### Communication Protocol
+
+The underlying communication protocol has changed from a custom protocol to `Async::Bus`:
+
+- **Before**: Custom `Connection` class with `call(do: :...)` API.
+- **After**: `Async::Bus` with controller-based API (`connection[:supervisor]`, `connection[:worker]`).
+
+This provides:
+- Better type safety through controller interfaces.
+- More reliable message delivery.
+- Better error handling and reconnection logic.
+
+### Worker Registration
+
+Worker registration has been refactored:
+
+- **Before**: Workers passed state hash and received UUID connection IDs.
+- **After**: Workers use `WorkerController` and receive sequential integer IDs.
+
+The new approach provides:
+- Simpler ID management.
+- Better controller-based API.
+- More explicit worker lifecycle management.

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

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

data/readme.md

@@ -18,6 +18,8 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
   - [Getting Started](https://socketry.github.io/async-service-supervisor/guides/getting-started/index) - This guide explains how to get started with `async-service-supervisor` to supervise and monitor worker processes in your Ruby applications.
 
+  - [Migration Guide](https://socketry.github.io/async-service-supervisor/guides/migration/index) - This guide explains how to migrate from `async-container-supervisor` to `async-service-supervisor`. The new version provides a cleaner API built on `Async::Bus` for improved reliability and maintainability.
+
   - [Memory Monitor](https://socketry.github.io/async-service-supervisor/guides/memory-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::MemoryMonitor</code> to detect and restart workers that exceed memory limits or develop memory leaks.
 
   - [Process Monitor](https://socketry.github.io/async-service-supervisor/guides/process-monitor/index) - This guide explains how to use the <code class="language-ruby">Async::Service::Supervisor::ProcessMonitor</code> to log CPU and memory metrics for your worker processes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -130,6 +130,7 @@ files:
 - context/getting-started.md
 - context/index.yaml
 - context/memory-monitor.md
+- context/migration.md
 - context/process-monitor.md
 - lib/async/service/supervisor.rb
 - lib/async/service/supervisor/client.rb