async-service 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce29cb5debee3f9a0b9dbdf80c0087fe52973e00c14c4d114a044fe8656d0920
-  data.tar.gz: eec4b6a5117ea33293e942a68fc656707b59a434d89df4e604e5ab95a11c9ad3
+  metadata.gz: 1dc20befccfdbe1d36db11898e11a469ff64f2338a7b88942d59cb58e0e8c92f
+  data.tar.gz: c2a09fad50e09a6188e30b213d921f832ac14706c8f23d721269e4e48cffe028
 SHA512:
-  metadata.gz: a95d7e8bc23385c1d874368e0582156e574ed2b9fa9defbd4c2ffff75499e457c48421f0610a94bf8de1f8326245d55f77751a59b0507d31278ecc89c6af0dc2
-  data.tar.gz: f79918dd27119524826711b5fa872bc37014c93fd460683b13358c14a98dfb4d96ed34dd08c19d4ac1fead8c5ad5acf045a2e006752bcdc05cc8276531b97bec
+  metadata.gz: ef436a78425bfab299e187e37e81f6d442dd00ffbff6c3e526c94d5753395e03158219d3b92d7e3edec4a68babf277fc97448d2a18991b6ab1d79cfdd6cafb74
+  data.tar.gz: 59468d0b53c26be506a8c4195cae58c91627352ebf09555bdcbf539d166c66d97f4c6a9ad3969fd0e8251f857cc058e4ad69e322ece8cd585b0579c0fbc44d69

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,10 +201,10 @@ 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.
@@ -247,7 +247,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,7 @@ 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. For services extending `GenericService`, you can set up health checking manually:
 
 ```ruby
 def setup(container)
@@ -284,7 +284,7 @@ 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.
+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 +305,7 @@ end
 
 ```ruby
 # Services are defined using environments:
-class WebService < Async::Service::Generic
+class WebService < Async::Service::GenericService
 	def setup(container)
 		super
 		
@@ -440,7 +440,7 @@ Create reusable configuration modules:
 
 ```ruby
 module ManagedEnvironment
-	include Async::Service::Managed::Environment
+	include Async::Service::ManagedEnvironment
 	
 	def count
 		4
@@ -464,7 +464,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.

data/lib/async/service/generic.rb

@@ -3,63 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2024-2025, by Samuel Williams.
 
+# Compatibility shim for Async::Service::Generic
+# Use Async::Service::GenericService instead
+require_relative "generic_service"
+
 module Async
 	module Service
-		# Captures the stateful behaviour of a specific service.
-		# Specifies the interfaces required by derived classes.
-		#
-		# Designed to be invoked within an {Async::Controller::Container}.
-		class Generic
-			# Convert the given environment into a service if possible.
-			# @parameter environment [Environment] The environment to use to construct the service.
-			# @returns [Generic | Nil] The constructed service if the environment specifies a service class.
-			def self.wrap(environment)
-				evaluator = environment.evaluator
-				
-				if evaluator.key?(:service_class)
-					if service_class = evaluator.service_class
-						return service_class.new(environment, evaluator)
-					end
-				end
-			end
-			
-			# Initialize the service from the given environment.
-			# @parameter environment [Environment]
-			def initialize(environment, evaluator = environment.evaluator)
-				@environment = environment
-				@evaluator = evaluator
-			end
-			
-			# @attribute [Environment] The environment which is used to configure the service.
-			attr :environment
-			
-			# Convert the service evaluator to a hash.
-			# @returns [Hash] A hash representation of the evaluator.
-			def to_h
-				@evaluator.to_h
-			end
-			
-			# The name of the service - used for informational purposes like logging.
-			# e.g. `myapp.com`.
-			def name
-				@evaluator.name
-			end
-			
-			# Start the service. Called before the container setup.
-			def start
-				Console.debug(self){"Starting service #{self.name}..."}
-			end
-			
-			# Setup the service into the specified container.
-			# @parameter container [Async::Container::Generic]
-			def setup(container)
-				Console.debug(self){"Setting up service #{self.name}..."}
-			end
-			
-			# Stop the service. Called after the container is stopped.
-			def stop(graceful = true)
-				Console.debug(self){"Stopping service #{self.name}..."}
-			end
-		end
+		# @deprecated Use {GenericService} instead.
+		Generic = GenericService
 	end
 end

data/lib/async/service/generic_service.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024-2025, by Samuel Williams.
+
+module Async
+	module Service
+		# Captures the stateful behaviour of a specific service.
+		# Specifies the interfaces required by derived classes.
+		#
+		# Designed to be invoked within an {Async::Controller::Container}.
+		class GenericService
+			# Convert the given environment into a service if possible.
+			# @parameter environment [Environment] The environment to use to construct the service.
+			# @returns [GenericService | Nil] The constructed service if the environment specifies a service class.
+			def self.wrap(environment)
+				evaluator = environment.evaluator
+				
+				if evaluator.key?(:service_class)
+					if service_class = evaluator.service_class
+						return service_class.new(environment, evaluator)
+					end
+				end
+			end
+			
+			# Initialize the service from the given environment.
+			# @parameter environment [Environment]
+			def initialize(environment, evaluator = environment.evaluator)
+				@environment = environment
+				@evaluator = evaluator
+			end
+			
+			# @attribute [Environment] The environment which is used to configure the service.
+			attr :environment
+			
+			# Convert the service evaluator to a hash.
+			# @returns [Hash] A hash representation of the evaluator.
+			def to_h
+				@evaluator.to_h
+			end
+			
+			# The name of the service - used for informational purposes like logging.
+			# e.g. `myapp.com`.
+			def name
+				@evaluator.name
+			end
+			
+			# Start the service. Called before the container setup.
+			def start
+				Console.debug(self){"Starting service #{self.name}..."}
+			end
+			
+			# Setup the service into the specified container.
+			# @parameter container [Async::Container::Generic]
+			def setup(container)
+				Console.debug(self){"Setting up service #{self.name}..."}
+			end
+			
+			# Stop the service. Called after the container is stopped.
+			def stop(graceful = true)
+				Console.debug(self){"Stopping service #{self.name}..."}
+			end
+		end
+	end
+end

data/lib/async/service/health_checker.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Service
+		# A health checker for managed services.
+		module HealthChecker
+			# Start the health checker.
+			#
+			# If a timeout is specified, a transient child task will be scheduled, which will yield the instance if a block is given, then mark the instance as ready, and finally sleep for half the health check duration (so that we guarantee that the health check runs in time).
+			#
+			# If a timeout is not specified, the health checker will yield the instance immediately and then mark the instance as ready.
+			#
+			# @parameter instance [Object] The service instance to check.
+			# @parameter timeout [Numeric] The timeout duration for the health check.
+			# @parameter parent [Async::Task] The parent task to run the health checker in.
+			# @yields {|instance| ...} If a block is given, it will be called with the service instance at least once.
+			def health_checker(instance, timeout = @evaluator.health_check_timeout, parent: Async::Task.current, &block)
+				if timeout
+					parent.async(transient: true) do
+						while true
+							if block_given?
+								yield(instance)
+							end
+							
+							# We deliberately create a fiber here, to confirm that fiber creation is working.
+							# If something has gone wrong with fiber allocation, we will crash here, and that's okay.
+							Fiber.new do
+								instance.ready!
+							end.resume
+							
+							sleep(timeout / 2)
+						end
+					end
+				else
+					if block_given?
+						yield(instance)
+					end
+					
+					instance.ready!
+				end
+			end
+		end
+	end
+end
+

data/lib/async/service/managed_environment.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Service
+		# Default configuration for managed services.
+		#
+		# This is provided not because it is required, but to offer a sensible default for production services, and to expose a consistent interface for service configuration.
+		module ManagedEnvironment
+			# Number of instances to start. By default, when `nil`, uses `Etc.nprocessors`.
+			#
+			# @returns [Integer | nil] The number of instances to start, or `nil` to use the default.
+			def count
+				nil
+			end
+			
+			# The timeout duration for the health check. Set to `nil` to disable the health check.
+			#
+			# @returns [Numeric | nil] The health check timeout in seconds.
+			def health_check_timeout
+				30
+			end
+			
+			# Options to use when creating the container, including `restart`, `count`, and `health_check_timeout`.
+			#
+			# @returns [Hash] The options for the container.
+			def container_options
+				{
+					restart: true,
+					count: self.count,
+					health_check_timeout: self.health_check_timeout,
+				}.compact
+			end
+			
+			# Any scripts to preload before starting the service.
+			#
+			# @returns [Array(String)] The list of scripts to preload.
+			def preload
+				[]
+			end
+			
+			# General tags for metrics, traces and logging.
+			#
+			# @returns [Array(String)] The tags for the service.
+			def tags
+				[]
+			end
+			
+			# Prepare the instance for running the service.
+			#
+			# This is called before {Async::Service::ManagedService#run}.
+			#
+			# @parameter instance [Object] The container instance.
+			def prepare!(instance)
+				# No preparation required by default.
+			end
+		end
+	end
+end
+

data/lib/async/service/managed_service.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "generic_service"
+require_relative "health_checker"
+
+module Async
+	module Service
+		# A managed service with built-in health checking, restart policies, and process title formatting.
+		#
+		# This is the recommended base class for most services that need robust lifecycle management.
+		class ManagedService < GenericService
+			include HealthChecker
+			
+			private def format_title(evaluator, server)
+				"#{evaluator.name} #{server.to_s}"
+			end
+			
+			# Run the service logic.
+			#
+			# Override this method to implement your service. Return an object that represents the running service (e.g., a server, task, or worker pool) for health checking.
+			#
+			# @parameter instance [Object] The container instance.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @returns [Object] The service object (server, task, etc.)
+			def run(instance, evaluator)
+				Async do
+					sleep
+				end
+			end
+			
+			# Preload any resources specified by the environment.
+			def preload!
+				if scripts = @evaluator.preload
+					root = @evaluator.root
+					scripts = Array(scripts)
+					
+					scripts.each do |path|
+						Console.info(self){"Preloading #{path}..."}
+						full_path = File.expand_path(path, root)
+						require(full_path)
+					end
+				end
+			rescue StandardError, LoadError => error
+				Console.warn(self, "Service preload failed!", error)
+			end
+		
+			# Start the service, including preloading resources.
+			def start
+				preload!
+				
+				super
+			end
+
+			def emit_prepared(instance, start_time)
+			end
+
+			def emit_running(instance, start_time)
+			end
+			
+			# Set up the container with health checking and process title formatting.
+			# @parameter container [Async::Container] The container to configure.
+			def setup(container)
+				super
+				
+				container_options = @evaluator.container_options
+				health_check_timeout = container_options[:health_check_timeout]
+				
+				container.run(**container_options) do |instance|
+					start_time = Async::Clock.start
+
+					Async do
+						evaluator = self.environment.evaluator
+						
+						evaluator.prepare!(instance)
+						
+						emit_prepared(instance, start_time)
+
+						server = run(instance, evaluator)
+						
+						emit_running(instance, start_time)
+						
+						health_checker(instance) do
+							instance.name = format_title(evaluator, server)
+						end
+					end
+				end
+			end
+		end
+	end
+end
+

data/lib/async/service/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Service
-		VERSION = "0.15.1"
+		VERSION = "0.16.0"
 	end
 end

data/readme.md

@@ -23,10 +23,18 @@ Please see the [project documentation](https://socketry.github.io/async-service/
 
   - [Best Practices](https://socketry.github.io/async-service/guides/best-practices/index) - This guide outlines recommended patterns and practices for building robust, maintainable services with `async-service`.
 
+  - [Deployment](https://socketry.github.io/async-service/guides/deployment/index) - This guide explains how to deploy `async-service` applications using systemd and Kubernetes. We'll use a simple example service to demonstrate deployment configurations.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-service/releases/index) for all releases.
 
+### v0.16.0
+
+  - Renamed `Async::Service::Generic` -\> `Async::Service::GenericService`, added compatibilty alias.
+  - Renamed `Async::Service::Managed::Service` -\> `Async::Service::ManagedService`.
+  - Renamed `Async::Service::Managed::Environment` -\> `Async::Service::ManagedEnvironment`.
+
 ### v0.15.1
 
   - `Managed::Service` should run within `Async do ... end`.
@@ -68,10 +76,6 @@ Please see the [project releases](https://socketry.github.io/async-service/relea
 
   - Allow providing a list of modules to include in environments.
 
-### v0.8.0
-
-  - Introduce `Environment#implements?` and related methods for interface checking.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.16.0
+
+  - Renamed `Async::Service::Generic` -\> `Async::Service::GenericService`, added compatibilty alias.
+  - Renamed `Async::Service::Managed::Service` -\> `Async::Service::ManagedService`.
+  - Renamed `Async::Service::Managed::Environment` -\> `Async::Service::ManagedEnvironment`.
+
 ## v0.15.1
 
   - `Managed::Service` should run within `Async do ... end`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.16.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -87,6 +87,7 @@ extra_rdoc_files: []
 files:
 - bin/async-service
 - context/best-practices.md
+- context/deployment.md
 - context/getting-started.md
 - context/index.yaml
 - context/service-architecture.md
@@ -96,11 +97,11 @@ files:
 - lib/async/service/environment.rb
 - lib/async/service/formatting.rb
 - lib/async/service/generic.rb
+- lib/async/service/generic_service.rb
+- lib/async/service/health_checker.rb
 - lib/async/service/loader.rb
-- lib/async/service/managed.rb
-- lib/async/service/managed/environment.rb
-- lib/async/service/managed/health_checker.rb
-- lib/async/service/managed/service.rb
+- lib/async/service/managed_environment.rb
+- lib/async/service/managed_service.rb
 - lib/async/service/version.rb
 - license.md
 - readme.md

data/lib/async/service/managed/environment.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-module Async
-	module Service
-		module Managed
-			# Default configuration for managed services.
-			#
-			# This is provided not because it is required, but to offer a sensible default for production services, and to expose a consistent interface for service configuration.
-			module Environment
-				# Number of instances to start. By default, when `nil`, uses `Etc.nprocessors`.
-				#
-				# @returns [Integer | nil] The number of instances to start, or `nil` to use the default.
-				def count
-					nil
-				end
-				
-				# The timeout duration for the health check. Set to `nil` to disable the health check.
-				#
-				# @returns [Numeric | nil] The health check timeout in seconds.
-				def health_check_timeout
-					30
-				end
-				
-				# Options to use when creating the container, including `restart`, `count`, and `health_check_timeout`.
-				#
-				# @returns [Hash] The options for the container.
-				def container_options
-					{
-						restart: true,
-						count: self.count,
-						health_check_timeout: self.health_check_timeout,
-					}.compact
-				end
-				
-				# Any scripts to preload before starting the service.
-				#
-				# @returns [Array(String)] The list of scripts to preload.
-				def preload
-					[]
-				end
-			end
-		end
-	end
-end
-

data/lib/async/service/managed/health_checker.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-module Async
-	module Service
-		module Managed
-			# A health checker for managed services.
-			module HealthChecker
-				# Start the health checker.
-				#
-				# If a timeout is specified, a transient child task will be scheduled, which will yield the instance if a block is given, then mark the instance as ready, and finally sleep for half the health check duration (so that we guarantee that the health check runs in time).
-				#
-				# If a timeout is not specified, the health checker will yield the instance immediately and then mark the instance as ready.
-				#
-				# @parameter instance [Object] The service instance to check.
-				# @parameter timeout [Numeric] The timeout duration for the health check.
-				# @parameter parent [Async::Task] The parent task to run the health checker in.
-				# @yields {|instance| ...} If a block is given, it will be called with the service instance at least once.
-				def health_checker(instance, timeout = @evaluator.health_check_timeout, parent: Async::Task.current, &block)
-					if timeout
-						parent.async(transient: true) do
-							while true
-								if block_given?
-									yield(instance)
-								end
-								
-								# We deliberately create a fiber here, to confirm that fiber creation is working.
-								# If something has gone wrong with fiber allocation, we will crash here, and that's okay.
-								Fiber.new do
-									instance.ready!
-								end.resume
-								
-								sleep(timeout / 2)
-							end
-						end
-					else
-						if block_given?
-							yield(instance)
-						end
-						
-						instance.ready!
-					end
-				end
-			end
-		end
-	end
-end

data/lib/async/service/managed/service.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "../generic"
-require_relative "../formatting"
-require_relative "health_checker"
-
-module Async
-	module Service
-		module Managed
-			# A managed service with built-in health checking, restart policies, and process title formatting.
-			#
-			# This is the recommended base class for most services that need robust lifecycle management.
-			class Service < Generic
-				include Formatting
-				include HealthChecker
-				
-				private def format_title(evaluator, server)
-					"#{evaluator.name} #{server.to_s}"
-				end
-				
-				# Run the service logic.
-				#
-				# Override this method to implement your service. Return an object that represents the running service (e.g., a server, task, or worker pool) for health checking.
-				#
-				# @parameter instance [Object] The container instance.
-				# @parameter evaluator [Environment::Evaluator] The environment evaluator.
-				# @returns [Object] The service object (server, task, etc.)
-				def run(instance, evaluator)
-					Async do
-						sleep
-					end
-				end
-				
-				# Preload any resources specified by the environment.
-				def preload!
-					if scripts = @evaluator.preload
-						root = @evaluator.root
-						scripts = Array(scripts)
-						
-						scripts.each do |path|
-							Console.info(self){"Preloading #{path}..."}
-							full_path = File.expand_path(path, root)
-							require(full_path)
-						end
-					end
-				rescue StandardError, LoadError => error
-					Console.warn(self, "Service preload failed!", error)
-				end
-			
-				# Start the service, including preloading resources.
-				def start
-					preload!
-					
-					super
-				end
-				
-				# Set up the container with health checking and process title formatting.
-				# @parameter container [Async::Container] The container to configure.
-				def setup(container)
-					super
-					
-					container_options = @evaluator.container_options
-					health_check_timeout = container_options[:health_check_timeout]
-					
-					container.run(**container_options) do |instance|
-						Async do
-							evaluator = self.environment.evaluator
-							
-							server = run(instance, evaluator)
-							
-							health_checker(instance) do
-								instance.name = format_title(evaluator, server)
-							end
-						end
-					end
-				end
-			end
-		end
-	end
-end

data/lib/async/service/managed.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-
-require_relative "managed/environment"
-require_relative "managed/service"
-
-module Async
-	module Service
-		# Managed services provide robust lifecycle management including health checking, restart policies, and process title formatting.
-		#
-		# This module contains components for building managed services that can run multiple instances with automatic restart and health monitoring.
-		module Managed
-		end
-	end
-end