async-service 0.13.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd7c0c91471cbf80069a3c770f1a9489e1dac8a2b22db648a0942f31e35e2743
-  data.tar.gz: a1aa57c3746945251bde7ad98baec11d28bd477a9c39bfe33fcdf22ac9f42f71
+  metadata.gz: 89fe1d184a09d9ded720abd6de21db5b499eb60aa50f24401264dc65213e0e1a
+  data.tar.gz: '0208be218dd12d5ad922cd830a304b53086494eb66f9dd2cda984758589677b4'
 SHA512:
-  metadata.gz: 400055e9c5d608f4eae1551304c25b96207e7b2c6b92cadeba6f476dac3c0de1a2ff2d24eb39da282d7ba52a0a6f90c400063b8a94fe883ca064ed3cbbcc1099
-  data.tar.gz: 0f416c8a882c91cc453111f0949498bf8e17d463b8dc623d06da07ca5e2435c966b2a6668c25170fe474afb9e684c368ef73522d6f29101cc1f319473624556a
+  metadata.gz: df3091625c43fff8e041d194fe64c0068e5e907b896ecd882f1682506890d05f04e7cb8606a0de13fa3bcdae28f89356c6720b31d0de195370c06bc952fd8680
+  data.tar.gz: c1a424f264717708460ab5216c6328d3fe946a0ea8ab56022a0b6a18c57afc8cac7872211dd836f260ba5e53460297a6be5dce4d56b43edc7911dbb437c88060

data/agent.md

@@ -0,0 +1,129 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+**Setup Instructions:** If the referenced files are not present or if dependencies have been updated, run `bake agent:context:install` to install the latest context files.
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Getting Started](.context/agent-context/getting-started.md)
+
+This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
+
+### async
+
+A concurrency framework for Ruby.
+
+#### [Getting Started](.context/async/getting-started.md)
+
+This guide shows how to add async to your project and run code asynchronously.
+
+#### [Scheduler](.context/async/scheduler.md)
+
+This guide gives an overview of how the scheduler is implemented.
+
+#### [Tasks](.context/async/tasks.md)
+
+This guide explains how asynchronous tasks work and how to use them.
+
+#### [Best Practices](.context/async/best-practices.md)
+
+This guide gives an overview of best practices for using Async.
+
+#### [Debugging](.context/async/debugging.md)
+
+This guide explains how to debug issues with programs that use Async.
+
+#### [Thread safety](.context/async/thread-safety.md)
+
+This guide explains thread safety in Ruby, focusing on fibers and threads, common pitfalls, and best practices to avoid problems like data corruption, race conditions, and deadlocks.
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
+
+#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
+
+This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
+
+### falcon
+
+A fast, asynchronous, rack-compatible web server.
+
+#### [Getting Started](.context/falcon/getting-started.md)
+
+This guide gives an overview of how to use Falcon for running Ruby web applications.
+
+#### [Rails Integration](.context/falcon/rails-integration.md)
+
+This guide explains how to host Rails applications with Falcon.
+
+#### [Deployment](.context/falcon/deployment.md)
+
+This guide explains how to deploy applications using the Falcon web server. It covers the recommended deployment methods, configuration options, and examples for different environments, including systemd and kubernetes.
+
+#### [Performance Tuning](.context/falcon/performance-tuning.md)
+
+This guide explains the performance characteristics of Falcon.
+
+#### [WebSockets](.context/falcon/websockets.md)
+
+This guide explains how to use WebSockets with Falcon.
+
+#### [Interim Responses](.context/falcon/interim-responses.md)
+
+This guide explains how to use interim responses in Falcon to send early hints to the client.
+
+#### [How It Works](.context/falcon/how-it-works.md)
+
+This guide gives an overview of how Falcon handles an incoming web request.
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
+
+### utopia-project
+
+A project documentation tool based on Utopia.
+
+#### [Getting Started](.context/utopia-project/getting-started.md)
+
+This guide explains how to use `utopia-project` to add documentation to your project.
+
+#### [Documentation Guides](.context/utopia-project/documentation-guidelines.md)
+
+This guide explains how to create and maintain documentation for your project using `utopia-project`.
+
+#### [GitHub Pages Integration](.context/utopia-project/github-pages-integration.md)
+
+This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.

data/context/best-practices.md

@@ -0,0 +1,320 @@
+# Best Practices
+
+This guide outlines recommended patterns and practices for building robust, maintainable services with `async-service`.
+
+## Application Structure
+
+If you are creating an application that runs services, you should define a top level `services.rb` file that includes all your service configurations. This file serves as the main entry point for your services. If you are specifically working with the Falcon web server, this file is typically called `falcon.rb` for historical reasons.
+
+### Service Configuration
+
+Create a single top-level `service.rb` file as your main entry point:
+
+```ruby
+#!/usr/bin/env async-service
+
+# Load your service configurations
+require_relative 'lib/my_library/environment/web_environment'
+require_relative 'lib/my_library/environment/worker_environment'
+
+service "web" do
+	include MyLibrary::Environment::WebEnvironment
+end
+
+service "worker" do 
+	include MyLibrary::Environment::WorkerEnvironment
+end
+```
+
+### Multiple Service Configurations
+
+In some cases, you may want to define multiple service configurations, e.g. for different environments or deployment targets. In those cases, you may create `web_service.rb` or `job_service.rb`, but this usage should be discouraged.
+
+## Library Structure
+
+If you are creating a library that exposes services, use the following structure and guidelines:
+
+### Directory Structure
+
+Organize your code following these conventions:
+
+```
+├── service.rb
+└── lib/
+    └── my_library/
+        ├── environment/
+        │   ├── web_environment.rb
+        │   ├── worker_environment.rb
+        │   ├── database_environment.rb
+        │   └── tls_environment.rb
+        └── service/
+            ├── web_service.rb
+            └── worker_service.rb
+```
+
+### Environment Organization
+
+Place environments in `lib/my_library/environment/`:
+
+```ruby
+# lib/my_library/environment/web_environment.rb
+module MyLibrary
+	module Environment
+		module WebEnvironment
+			include Async::Service::ContainerEnvironment
+			
+			def service_class
+				MyLibrary::Service::WebService
+			end
+			
+			def port
+				3000
+			end
+			
+			def host
+				"localhost"
+			end
+		end
+	end
+end
+```
+
+### Service Organization
+
+Place services in `lib/my_library/service/`:
+
+```ruby
+# lib/my_library/service/web_service.rb
+module MyLibrary
+	module Service
+		class WebService < Async::Service::ContainerService
+			private def format_title(evaluator, server)
+				if server&.respond_to?(:connection_count)
+					"#{self.name} [#{evaluator.host}:#{evaluator.port}] (#{server.connection_count} connections)"
+				else
+					"#{self.name} [#{evaluator.host}:#{evaluator.port}]"
+				end
+			end
+			
+			def run(instance, evaluator)
+				# Start your service and return the server object.
+				# ContainerService handles container setup, health checking, and process titles.
+				start_web_server(evaluator.host, evaluator.port)
+			end
+			
+			private
+			
+			def start_web_server(host, port)
+				# The return value of this method will be the server object which is returned from `run` and passed to `format_title`.
+			end
+		end
+	end
+end
+```
+
+### Use `ContainerEnvironment` for Services
+
+Include {ruby Async::Service::ContainerEnvironment} for services that run in containers using {ruby Async::Service::ContainerService}:
+
+```ruby
+module WebEnvironment
+	include Async::Service::ContainerEnvironment
+	
+	def service_class
+		WebService
+	end
+end
+```
+
+## Environment Best Practices
+
+### Use Plain Modules
+
+Prefer plain Ruby modules for environments:
+
+```ruby
+module DatabaseEnvironment
+	def database_url
+		"postgresql://localhost/app"
+	end
+	
+	def max_connections
+		10
+	end
+end
+```
+
+### One-to-One Service-Environment Correspondence
+
+Maintain a 1:1 relationship between services and their primary environments:
+
+```ruby
+# Primary environment for WebService
+module WebEnvironment
+	def service_class
+		WebService
+	end
+	
+	# Default configuration:
+	def port
+		3000
+	end
+
+	def host
+		'0.0.0.0'
+	end
+end
+
+# Primary environment for WorkerService  
+module WorkerEnvironment
+	def service_class
+		WorkerService
+	end
+	
+	def queue_name
+		'default'
+	end
+	
+	def count
+		4
+	end
+end
+```
+
+### Compose with Auxiliary Environments
+
+Use additional environments for cross-cutting concerns:
+
+```ruby
+module WebEnvironment
+	include DatabaseEnvironment
+	include TLSEnvironment
+	include LoggingEnvironment
+	
+	def service_class
+		WebService
+	end
+end
+```
+
+## Service Best Practices
+
+### Use ContainerService as Base Class
+
+Prefer `Async::Service::ContainerService` over `Generic` for most services:
+
+```ruby
+class WebService < Async::Service::ContainerService
+	# ContainerService automatically handles:
+	# - Container setup with proper options.
+	# - Health checking with process title updates.
+	# - Integration with Formatting module.
+	
+	private def format_title(evaluator, server)
+		# Customize process title display
+		"#{self.name} [#{evaluator.host}:#{evaluator.port}]"
+	end
+	
+	def run(instance, evaluator)
+		# Focus only on your service logic
+		start_web_server(evaluator.host, evaluator.port)
+	end
+end
+```
+
+### Implement Meaningful Process Titles
+
+Use the `format_title` method to provide dynamic process information:
+
+```ruby
+private def format_title(evaluator, server)
+	# Good - Include service-specific info
+	"#{self.name} [#{evaluator.host}:#{evaluator.port}]"
+	
+	# Better - Include dynamic runtime status
+	if connection_count = server&.connection_count
+		"#{self.name} [#{evaluator.host}:#{evaluator.port}] (C=#{format_count connection_count})"
+	else
+		"#{self.name} [#{evaluator.host}:#{evaluator.port}]"
+	end
+end
+```
+
+Try to keep process titles short and focused.
+
+### Use `start` and `stop` Hooks for Shared Resources
+
+Utilize the `start` and `stop` hooks to manage shared resources effectively:
+
+```ruby
+class WebService < Async::Service::ContainerService
+	def start
+		# Bind to the endpoint in the container:
+		@endpoint = @evaluator.endpoint.bind
+		
+		super
+	end
+
+	def stop
+		@endpoint&.close
+	end
+end
+```
+
+## Testing Best Practices
+
+### Test Environments in Isolation
+
+Test environment modules independently:
+
+```ruby
+# test/my_library/environment/web_environment.rb
+describe MyLibrary::Environment::WebEnvironment do
+	let(:environment) do
+		Async::Service::Environment.build do
+			include MyLibrary::Environment::WebEnvironment
+		end
+	end
+	
+	it "provides default port" do
+		expect(environment.port).to be == 3000
+	end
+end
+```
+
+### Test Services with Service Controller
+
+Use test environments for service testing:
+
+```ruby
+# test/my_library/service/web_service.rb
+describe MyLibrary::Service::WebService do
+	let(:environment) do
+		Async::Service::Environment.build do
+			include MyLibrary::Environment::WebEnvironment
+		end
+	end
+	
+	let(:evaluator) {environment.evaluator}
+	let(:service) {evaluator.service_class(environment, evaluator)}
+	let(:controller) {Async::Service::Controller.for(service)}
+	
+	before do
+		controller.start
+	end
+
+	after do
+		controller.stop
+	end
+	
+	let(:uri) {URI "http://#{evaluator.host}:#{evaluator.port}"}
+	
+	it "responds to requests" do
+		Net::HTTP.get(uri).tap do |response|
+			expect(response).to be_a(Net::HTTPSuccess)
+		end
+	end
+end
+```
+
+Note that full end-to-end service tests like this are typically slow and hard to isolate, so it's better to use unit tests for individual components whenever possible.

data/context/getting-started.md

@@ -0,0 +1,190 @@
+# Getting Started
+
+This guide explains how to get started with `async-service` to create and run services in Ruby.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add async-service
+```
+
+## Core Concepts
+
+`async-service` has several core concepts:
+
+- A {ruby Async::Service::Generic} 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.
+
+### Basic Service
+
+Create a simple service that runs continuously:
+
+```ruby
+#!/usr/bin/env async-service
+
+require 'async/service'
+
+class HelloService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			instance.ready!
+			
+			while true
+				puts "Hello World!"
+				sleep 1
+			end
+		end
+	end
+end
+
+service "hello" do
+	service_class HelloService
+end
+```
+
+Make the file executable and run it:
+
+```bash
+$ chmod +x hello_service.rb
+$ ./hello_service.rb
+```
+
+### Service Configuration
+
+Services can be configured with custom properties:
+
+```ruby
+service "web-server" do
+	service_class WebServerService
+	port 3000
+	host "localhost"
+end
+```
+
+In your service implementation, you can access these values through the environment and evaluator:
+
+```ruby
+class WebServerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			# Access the configuration for the service:
+			evaluator = self.environment.evaluator
+			port = evaluator.port
+			host = evaluator.host
+			
+			puts "Starting web server on #{host}:#{port}"
+			instance.ready!
+			
+			# Your web server implementation here
+		end
+	end
+end
+```
+
+### Multiple Services
+
+You can define multiple services in a single configuration file:
+
+```ruby
+#!/usr/bin/env async-service
+
+require 'async/service'
+
+class WebService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 1, restart: true) do |instance|
+			instance.ready!
+			puts "Web service starting..."
+			# Web server implementation
+		end
+	end
+end
+
+class WorkerService < Async::Service::Generic
+	def setup(container)
+		super
+		
+		container.run(count: 2, restart: true) do |instance|
+			instance.ready!
+			puts "Worker #{instance.name} starting..."
+			# Background job processing
+		end
+	end
+end
+
+service "web" do
+	service_class WebService
+	port 3000
+	host "localhost"
+end
+
+service "worker" do
+	service_class WorkerService
+end
+```
+
+### Programmatic Usage
+
+You can also create and run services programmatically:
+
+```ruby
+require 'async/service'
+
+configuration = Async::Service::Configuration.build do
+	service "my-service" do
+		service_class MyService
+	end
+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

@@ -0,0 +1,20 @@
+# 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 service layer for Async.
+metadata:
+  documentation_uri: https://socketry.github.io/async-service/
+  source_code_uri: https://github.com/socketry/async-service.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `async-service` to create
+    and run services in Ruby.
+- path: service-architecture.md
+  title: Service Architecture
+  description: This guide explains the key architectural components of `async-service`
+    and how they work together to provide a clean separation of concerns.
+- path: best-practices.md
+  title: Best Practices
+  description: This guide outlines recommended patterns and practices for building
+    robust, maintainable services with `async-service`.