async-service 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce29cb5debee3f9a0b9dbdf80c0087fe52973e00c14c4d114a044fe8656d0920
-  data.tar.gz: eec4b6a5117ea33293e942a68fc656707b59a434d89df4e604e5ab95a11c9ad3
+  metadata.gz: 6e9258424ee834d70b309984ba6f2d0c89f87ed9b2a16ec38fb298dfafb33fcd
+  data.tar.gz: e91b2129702c7c8ad7f3203063d3dd526b8e6e91d322bb84388afe873cf638f0
 SHA512:
-  metadata.gz: a95d7e8bc23385c1d874368e0582156e574ed2b9fa9defbd4c2ffff75499e457c48421f0610a94bf8de1f8326245d55f77751a59b0507d31278ecc89c6af0dc2
-  data.tar.gz: f79918dd27119524826711b5fa872bc37014c93fd460683b13358c14a98dfb4d96ed34dd08c19d4ac1fead8c5ad5acf045a2e006752bcdc05cc8276531b97bec
+  metadata.gz: edc78ce3ff189ef951f19b206d02bbef4f2c121b10e24f074b6a7eab702c6ffeceb5e47c7c29d330363c7389c721b371c4584f33b9145cde42b798ec08e47237
+  data.tar.gz: be8a666be488d9d428339edea966834c0a7d5e935bcf330b8669f914b58661ed11deff0782b4202327951b108063992e5ac6f4fb9427beca5d6c1daaf09f440a

data/context/best-practices.md

@@ -61,7 +61,7 @@ Place environments in `lib/my_library/environment/`:
 module MyLibrary
 	module Environment
 		module WebEnvironment
-			include Async::Service::Managed::Environment
+			include Async::Service::ManagedEnvironment
 			
 			def service_class
 				MyLibrary::Service::WebService
@@ -87,7 +87,7 @@ Place services in `lib/my_library/service/`:
 # lib/my_library/service/web_service.rb
 module MyLibrary
 	module Service
-		class WebService < Async::Service::Managed::Service
+		class WebService < Async::Service::ManagedService
 			private def format_title(evaluator, server)
 				if server&.respond_to?(:connection_count)
 					"#{self.name} [#{evaluator.host}:#{evaluator.port}] (#{server.connection_count} connections)"
@@ -114,11 +114,11 @@ end
 
 ### Use `Managed::Environment` for Services
 
-Include {ruby Async::Service::Managed::Environment} for services that need robust lifecycle management using {ruby Async::Service::Managed::Service}:
+Include {ruby Async::Service::ManagedEnvironment} for services that need robust lifecycle management using {ruby Async::Service::ManagedService}:
 
 ```ruby
 module WebEnvironment
-	include Async::Service::Managed::Environment
+	include Async::Service::ManagedEnvironment
 	
 	def service_class
 		WebService
@@ -201,13 +201,14 @@ end
 
 ### Use `Managed::Service` as Base Class
 
-Prefer `Async::Service::Managed::Service` over `Generic` for most services:
+Prefer `Async::Service::ManagedService` over `GenericService` for most services:
 
 ```ruby
-class WebService < Async::Service::Managed::Service
+class WebService < Async::Service::ManagedService
 	# Managed::Service automatically handles:
 	# - Container setup with proper options.
 	# - Health checking with process title updates.
+	# - Status messages during startup to prevent premature timeouts.
 	# - Preloading of scripts before startup.
 	
 	private def format_title(evaluator, server)
@@ -222,6 +223,28 @@ class WebService < Async::Service::Managed::Service
 end
 ```
 
+### Configure Timeouts for Slow-Starting Services
+
+If your service takes a long time to start up (e.g., loading large datasets, connecting to external services), configure appropriate timeouts:
+
+```ruby
+module WebEnvironment
+	include Async::Service::ManagedEnvironment
+	
+	# Allow 2 minutes for startup.
+	def startup_timeout
+		120
+	end
+	
+	# Require health checks every 30 seconds.
+	def health_check_timeout
+		30
+	end
+end
+```
+
+The `startup_timeout` ensures processes that hang during startup are detected, while `health_check_timeout` monitors processes after they've become ready. `ManagedService` automatically sends `status!` messages during startup to keep the health check clock resetting until the service is ready.
+
 ### Implement Meaningful Process Titles
 
 Use the `format_title` method to provide dynamic process information:
@@ -247,7 +270,7 @@ Try to keep process titles short and focused.
 Utilize the `start` and `stop` hooks to manage shared resources effectively:
 
 ```ruby
-class WebService < Async::Service::Managed::Service
+class WebService < Async::Service::ManagedService
 	def start
 		# Bind to the endpoint in the container:
 		@endpoint = @evaluator.endpoint.bind

data/context/deployment.md

@@ -0,0 +1,284 @@
+# Deployment
+
+This guide explains how to deploy `async-service` applications using systemd and Kubernetes. We'll use a simple example service to demonstrate deployment configurations.
+
+## Example Service
+
+Let's start with a simple HTTP service that we'll deploy:
+
+```ruby
+#!/usr/bin/env async-service
+# frozen_string_literal: true
+
+require "async/http"
+require "async/service/managed_service"
+require "async/service/managed_environment"
+
+class WebService < Async::Service::ManagedService
+	def start
+		super
+		@endpoint = @evaluator.endpoint
+		@bound_endpoint = Sync{@endpoint.bound}
+	end
+	
+	def stop
+		@endpoint = nil
+		@bound_endpoint&.close
+		super
+	end
+	
+	def run(instance, evaluator)
+		Console.info(self){"Starting web server on #{@endpoint}"}
+		
+		server = Async::HTTP::Server.for(@bound_endpoint, protocol: @endpoint.protocol, scheme: @endpoint.scheme) do |request|
+			Protocol::HTTP::Response[200, {}, ["Hello, World!"]]
+		end
+		
+		instance.ready!
+		server.run
+	end
+end
+
+module WebEnvironment
+	include Async::Service::ManagedEnvironment
+	
+	def endpoint
+		Async::HTTP::Endpoint.parse("http://0.0.0.0:3000")
+	end
+end
+
+service "web" do
+	service_class WebService
+	include WebEnvironment
+end
+```
+
+Save this as `web_service.rb` and make it executable:
+
+```bash
+$ chmod +x web_service.rb
+```
+
+## Systemd Deployment
+
+Systemd can manage your `async-service` application as a system service, providing automatic startup, restart on failure, and integration with system logging.
+
+### Service File
+
+Create a systemd service file at `/etc/systemd/system/my-web-service.service`:
+
+```
+[Unit]
+Description=My Web Service
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/usr/local/bin/bundle exec /path/to/web_service.rb
+WorkingDirectory=/path/to/application
+User=www-data
+Group=www-data
+Restart=always
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Key Configuration Points
+
+- **Type=notify**: This is essential for `async-service` to notify systemd when the service is ready. The service uses the `sd_notify` protocol via the `$NOTIFY_SOCKET` environment variable.
+- **ExecStart**: Points to your service script. Use `bundle exec` if you're using Bundler.
+- **WorkingDirectory**: Set to your application root directory.
+- **User/Group**: Run the service as a non-privileged user.
+- **Restart=always**: Automatically restart the service if it fails.
+
+### Installing and Managing the Service
+
+```bash
+# Reload systemd to recognize the new service
+$ sudo systemctl daemon-reload
+
+# Enable the service to start on boot
+$ sudo systemctl enable my-web-service
+
+# Start the service
+$ sudo systemctl start my-web-service
+
+# Check service status
+$ sudo systemctl status my-web-service
+
+# View service logs
+$ sudo journalctl -u my-web-service -f
+
+# Stop the service
+$ sudo systemctl stop my-web-service
+```
+
+### Verifying Readiness
+
+The service will notify systemd when it's ready. You can verify this by checking the service status:
+
+```bash
+$ sudo systemctl status my-web-service
+```
+
+The service should show as "active (running)" once it has notified systemd of its readiness.
+
+## Kubernetes Deployment
+
+Kubernetes can manage your `async-service` application as a containerized workload, providing scaling, health checks, and rolling updates.
+
+### Dockerfile
+
+First, create a `Dockerfile` for your application:
+
+```dockerfile
+FROM ruby:3.2
+
+WORKDIR /app
+
+# Install dependencies
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --deployment --without development test
+
+# Copy application files
+COPY . .
+
+# Expose the service port
+EXPOSE 3000
+
+# Set the notification log path
+ENV NOTIFY_LOG=/tmp/notify.log
+
+# Run the service
+CMD ["bundle", "exec", "./web_service.rb"]
+```
+
+### Deployment Configuration
+
+Create a Kubernetes deployment file `web-service-deployment.yaml`:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-service
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: web-service
+  template:
+    metadata:
+      labels:
+        app: web-service
+    spec:
+      containers:
+        - name: web-service
+          image: my-registry/web-service:latest
+          ports:
+            - containerPort: 3000
+              name: http
+          env:
+            - name: NOTIFY_LOG
+              value: "/tmp/notify.log"
+          readinessProbe:
+            exec:
+              command:
+                - bundle
+                - exec
+                - bake
+                - async:container:notify:log:ready?
+            initialDelaySeconds: 5
+            periodSeconds: 5
+            timeoutSeconds: 3
+            failureThreshold: 12
+          livenessProbe:
+            httpGet:
+              path: /
+              port: 3000
+            initialDelaySeconds: 30
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 3
+          resources:
+            requests:
+              memory: "128Mi"
+              cpu: "100m"
+            limits:
+              memory: "256Mi"
+              cpu: "500m"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: web-service
+spec:
+  selector:
+    app: web-service
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 3000
+  type: LoadBalancer
+```
+
+### Key Configuration Points
+
+- **readinessProbe**: Uses the `async:container:notify:log:ready?` bake task to check if the service is ready. This reads from the `NOTIFY_LOG` file.
+- **livenessProbe**: HTTP health check to ensure the service is responding to requests.
+- **NOTIFY_LOG**: Environment variable pointing to the notification log file path.
+- **replicas**: Number of pod instances to run.
+
+### Deploying to Kubernetes
+
+```bash
+# Build and push the Docker image
+$ docker build -t my-registry/web-service:latest .
+$ docker push my-registry/web-service:latest
+
+# Apply the deployment
+$ kubectl apply -f web-service-deployment.yaml
+
+# Check deployment status
+$ kubectl get deployments
+$ kubectl get pods
+
+# View pod logs
+$ kubectl logs -f deployment/web-service
+
+# Check service endpoints
+$ kubectl get svc web-service
+
+# Scale the deployment
+$ kubectl scale deployment web-service --replicas=3
+
+# Update the deployment (rolling update)
+$ kubectl set image deployment/web-service web-service=my-registry/web-service:v2
+```
+
+### Verifying Readiness
+
+Kubernetes will wait for the readiness probe to pass before routing traffic to the pod:
+
+```bash
+# Check pod readiness
+$ kubectl get pods -l app=web-service
+
+# Describe pod to see readiness probe status
+$ kubectl describe pod <pod-name>
+```
+
+The pod will show as "Ready" once the readiness probe succeeds, indicating the service has notified that it's ready to accept traffic.
+
+## Notification Mechanism
+
+Both systemd and Kubernetes deployments rely on the notification mechanism provided by `async-container`. The service uses `instance.ready!` to signal readiness:
+
+- **Systemd**: Uses the `sd_notify` protocol via the `$NOTIFY_SOCKET` environment variable (automatically handled by `async-container`).
+- **Kubernetes**: Uses a log file (`NOTIFY_LOG`) that the readiness probe checks using the `async:container:notify:log:ready?` bake task.
+
+This ensures that your service is only considered ready when it has actually started and is prepared to handle requests, preventing premature traffic routing and improving reliability.

data/context/getting-started.md

@@ -14,13 +14,13 @@ $ bundle add async-service
 
 `async-service` has several core concepts:
 
-- A {ruby Async::Service::Generic} which represents the base class for implementing services.
+- A {ruby Async::Service::GenericService} which represents the base class for implementing services.
 - A {ruby Async::Service::Configuration} which manages service configurations and environments.
 - A {ruby Async::Service::Controller} which handles starting, stopping, and managing services.
 
 ## Usage
 
-Services are long-running processes that can be managed as a group. Each service extends `Async::Service::Generic` and implements a `setup` method that defines how the service runs.
+Services are long-running processes that can be managed as a group. Each service extends `Async::Service::GenericService` and implements a `setup` method that defines how the service runs.
 
 ### Basic Service
 
@@ -31,7 +31,7 @@ Create a simple service that runs continuously:
 
 require "async/service"
 
-class HelloService < Async::Service::Generic
+class HelloService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -73,7 +73,7 @@ end
 In your service implementation, you can access these values through the environment and evaluator:
 
 ```ruby
-class WebServerService < Async::Service::Generic
+class WebServerService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -92,6 +92,8 @@ class WebServerService < Async::Service::Generic
 end
 ```
 
+The evaluator is a memoized instance of the service's configuration, allowing for efficient access to configuration values throughout the service's lifecycle. If a service worker is restarted, it will create a new evaluator and a fresh environment.
+
 ### Multiple Services
 
 You can define multiple services in a single configuration file:
@@ -101,7 +103,7 @@ You can define multiple services in a single configuration file:
 
 require "async/service"
 
-class WebService < Async::Service::Generic
+class WebService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -113,7 +115,7 @@ class WebService < Async::Service::Generic
 	end
 end
 
-class WorkerService < Async::Service::Generic
+class WorkerService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -151,40 +153,3 @@ end
 
 Async::Service::Controller.run(configuration)
 ```
-
-### Accessing Configuration Values
-
-Services have access to their configuration through the environment and evaluator:
-
-```ruby
-class ConfigurableService < Async::Service::Generic
-	def setup(container)
-		super
-		
-		container.run(count: 1, restart: true) do |instance|
-			# Clone the evaluator for thread safety
-			evaluator = self.environment.evaluator
-			database_url = evaluator.database_url
-			max_connections = evaluator.max_connections
-			debug_mode = evaluator.debug_mode
-			
-			puts "Database URL: #{database_url}"
-			puts "Max connections: #{max_connections}"
-			puts "Debug mode: #{debug_mode}"
-			
-			instance.ready!
-			
-			# Your service implementation using these values
-		end
-	end
-end
-
-service "configurable" do
-	service_class ConfigurableService
-	database_url "postgresql://localhost/myapp"
-	max_connections 10
-	debug_mode true
-end
-```
-
-The evaluator is a memoized instance of the service's configuration, allowing for efficient access to configuration values throughout the service's lifecycle.

data/context/index.yaml

@@ -18,3 +18,8 @@ files:
   title: Best Practices
   description: This guide outlines recommended patterns and practices for building
     robust, maintainable services with `async-service`.
+- path: deployment.md
+  title: Deployment
+  description: This guide explains how to deploy `async-service` applications using
+    systemd and Kubernetes. We'll use a simple example service to demonstrate deployment
+    configurations.

data/context/service-architecture.md

@@ -82,14 +82,14 @@ end
 
 ## Service
 
-The {ruby Async::Service::Generic} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
+The {ruby Async::Service::GenericService} represents the service implementation layer. It handles the actual business logic of your services, provides access to configuration through environment evaluators, and manages the service lifecycle including startup, execution, and shutdown phases.
 
 ### Business Logic
 
 Services contain the actual implementation of what your service does:
 
 ```ruby
-class WebService < Async::Service::Generic
+class WebService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -148,7 +148,7 @@ By evaluating the log_path in the child process, you ensure that each instance h
 Services define their startup, running, and shutdown behavior:
 
 ```ruby
-class MyService < Async::Service::Generic
+class MyService < Async::Service::GenericService
 	def start
 		super
 		# Service-specific startup logic including pre-loading libraries and binding to network interfaces before forking.
@@ -262,7 +262,9 @@ end
 
 ### Health Checking
 
-For services using `Async::Service::Managed::Service`, health checking is handled automatically. For services extending `Generic`, you can set up health checking manually:
+For services using `Async::Service::ManagedService`, health checking is handled automatically. The service sends `status!` messages during startup to prevent premature health check timeouts, then transitions to sending `ready!` messages once the service is actually ready.
+
+For services extending `GenericService`, you can set up health checking manually:
 
 ```ruby
 def setup(container)
@@ -270,12 +272,15 @@ def setup(container)
 	health_check_timeout = container_options[:health_check_timeout]
 	
 	container.run(**container_options) do |instance|
+		# Send status updates during startup:
+		instance.status!("Preparing...")
 		# Prepare your service.
 		
 		Async do
 			# Start your service.
+			instance.status!("Starting...")
 			
-			# Set up health checking, if a timeout was specified:
+			# Once ready, set up health checking:
 			health_checker(instance, health_check_timeout) do
 				instance.name = "#{self.name}: #{current_status}"
 			end
@@ -284,7 +289,31 @@ def setup(container)
 end
 ```
 
-Note: `Async::Service::Managed::Service` automatically handles health checking, container options, and process title formatting, so you typically don't need to set this up manually.
+#### Startup Timeout vs Health Check Timeout
+
+The container supports two separate timeout mechanisms:
+
+- **`startup_timeout`**: Maximum time a process can take to become ready (call `ready!`) before being terminated. This detects processes that hang during startup and never become ready.
+- **`health_check_timeout`**: Maximum time between health check messages after the process has become ready. This detects processes that stop responding after they've started.
+
+Both timeouts use a single clock that starts when the process starts. The clock resets when the process becomes ready, transitioning from startup timeout monitoring to health check timeout monitoring.
+
+You can configure these timeouts via `container_options`:
+
+```ruby
+module WebEnvironment
+	include Async::Service::ManagedEnvironment
+	
+	def container_options
+		super.merge(
+			startup_timeout: 60,      # Allow up to 60 seconds for startup.
+			health_check_timeout: 30  # Require health checks every 30 seconds after ready.
+		)
+	end
+end
+```
+
+Note: `Async::Service::ManagedService` automatically handles health checking, container options, and process title formatting, so you typically don't need to set this up manually.
 
 ## How They Work Together
 
@@ -305,7 +334,7 @@ end
 
 ```ruby
 # Services are defined using environments:
-class WebService < Async::Service::Generic
+class WebService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -440,7 +469,7 @@ Create reusable configuration modules:
 
 ```ruby
 module ManagedEnvironment
-	include Async::Service::Managed::Environment
+	include Async::Service::ManagedEnvironment
 	
 	def count
 		4
@@ -464,7 +493,7 @@ end
 Build service hierarchies:
 
 ```ruby
-class BaseWebService < Async::Service::Generic
+class BaseWebService < Async::Service::GenericService
 	def setup(container)
 		super
 		# Common web service setup

data/lib/async/service/configuration.rb

@@ -4,7 +4,7 @@
 # Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "loader"
-require_relative "generic"
+require_relative "generic_service"
 require_relative "controller"
 
 module Async
@@ -70,7 +70,7 @@ module Async
 				
 				@environments.each do |environment|
 					if implementing.nil? or environment.implements?(implementing)
-						if service = Generic.wrap(environment)
+						if service = GenericService.wrap(environment)
 							yield service
 						end
 					end

data/lib/async/service/controller.rb

@@ -42,7 +42,7 @@ module Async
 			end
 			
 			# Create a controller for the given services.
-			# @parameter services [Array(Generic)] The services to control.
+			# @parameter services [Array(GenericService)] The services to control.
 			# @parameter options [Hash] Additional options for the controller.
 			# @returns [Controller] A new controller instance.
 			def self.for(*services, **options)
@@ -50,7 +50,7 @@ module Async
 			end
 			
 			# Initialize a new controller with services.
-			# @parameter services [Array(Generic)] The services to manage.
+			# @parameter services [Array(GenericService)] The services to manage.
 			# @parameter options [Hash] Options passed to the parent controller.
 			def initialize(services, **options)
 				super(**options)
@@ -59,7 +59,7 @@ module Async
 			end
 			
 			# All the services associated with this controller.
-			# @attribute [Array(Async::Service::Generic)] 
+			# @attribute [Array(Async::Service::GenericService)] 
 			attr :services
 			
 			# Start all named services.