async-container 0.34.3 → 0.34.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 977328d9a4dc6b4b7c86f634de0dba5f97b6e9da9c404b39ba1beea29f5711cc
-  data.tar.gz: 766a0c91a80afa6e3867ecdaae4bcfc8fb75dde5a6e9d12a3c2afe29790d4e9b
+  metadata.gz: 45d1096677e99abf4e408324f81089d3a09dffe06faec9802505f0982a286c9c
+  data.tar.gz: 9297103dfdd8c2181881a7cc6639afcc4d16ea3acfcd4f6074429c6a06c229f5
 SHA512:
-  metadata.gz: deb356cc50190aaa1a766e1eb53f4f573d2ca07c766f5b8549ebec923d6c5b451c4f9b371864ef83313d1e66658c52cbb11cc3c6196da4b0608d2a0e7e08d25a
-  data.tar.gz: 456c21fa8ac6df624ee6558ab0935ab3d6175722908c815d0a726cced3de8708029053ba76268b1e8bc7a7e7fa185c474dcbc27ded2405ec164fe1e81246c19a
+  metadata.gz: c1e6e6c690ab46402878c54a91565decb35a5cfbb6f10b49e393949fafe2cba33da780bbdbb9a2b01dd9ad80487a16e83c7188667f22ee6e8c8696008a0e8ce2
+  data.tar.gz: fce543a64ebb908baa70bd0c5912b92b1395e3a99fc257cc3280cd3527f23215001e1aebfa50946f6fd956011f981b84e92a8ced7d4079e063fa9be542d1e8c6

data/bake/async/container/notify/log.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+def initialize(...)
+	super
+	
+	require "async/container/notify/log"
+end
+
+# Check if the log file exists and the service is ready.
+# @parameter path [String] The path to the notification log file, uses the `NOTIFY_LOG` environment variable if not provided.
+def ready?(path: Async::Container::Notify::Log.path)
+	if File.exist?(path)
+		File.foreach(path) do |line|
+			message = JSON.parse(line)
+			if message["ready"] == true
+				return true
+			end
+		end
+		
+		raise "Service is not ready yet."
+	else
+		raise "Notification log file does not exist at #{path}"
+	end
+end

data/context/getting-started.md

@@ -0,0 +1,144 @@
+# Getting Started
+
+This guide explains how to use `async-container` to build basic scalable systems.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add async-container
+~~~
+
+## Core Concepts
+
+`async-container` has several core concepts:
+
+- {ruby Async::Container::Forked} and {ruby Async::Container::Threaded} are used to manage one or more child processes and threads respectively for parallel execution. While threads share the address space which can reduce overall memory usage, processes have better isolation and fault tolerance.
+- {ruby Async::Container::Controller} manages one or more containers and handles graceful restarts. Containers should be implemented in such a way that multiple containers can be running at the same time.
+
+## Containers
+
+A container represents a set of child processes (or threads) which are doing work for you.
+
+``` ruby
+require "async/container"
+
+Console.logger.debug!
+
+container = Async::Container.new
+
+container.spawn do |task|
+	Console.debug task, "Sleeping..."
+	sleep(1)
+	Console.debug task, "Waking up!"
+end
+
+Console.debug "Waiting for container..."
+container.wait
+Console.debug "Finished."
+```
+
+### Stopping Child Processes
+
+Containers provide three approaches for stopping child processes (or threads). When you call `container.stop()`, a progressive approach is used:
+
+- **Interrupt** means **"Please start shutting down gracefully"**. This is the gentlest shutdown request, giving applications maximum time to finish current work and cleanup resources.
+
+- **Terminate** means **"Shut down now"**. This is more urgent - the process should stop what it's doing and terminate promptly, but still has a chance to cleanup.
+
+- **Kill** means **"Die immediately"**. This forcefully terminates the process with no cleanup opportunity. This is the method of last resort.
+
+The escalation sequence follows this pattern:
+1. interrupt → wait for timeout → still running?
+2. terminate → wait for timeout → still running? 
+3. kill → process terminated.
+
+This gives well-behaved processes multiple opportunities to shut down gracefully, while ensuring that unresponsive processes are eventually killed.
+
+**Implementation Note:** For forked containers, these methods send Unix signals (`SIGINT`, `SIGTERM`, `SIGKILL`). For threaded containers, they use different mechanisms appropriate to threads. The container abstraction hides these implementation details.
+
+### Health Checking and Timeouts
+
+Containers can monitor child processes to detect hung or unresponsive processes using two timeout mechanisms:
+
+- **`startup_timeout`**: Maximum time a process can take to become ready (call `instance.ready!`) before being terminated. This detects processes that hang during startup.
+- **`health_check_timeout`**: Maximum time between health check messages after a 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.
+
+``` ruby
+require "async/container"
+
+container = Async::Container.new
+
+container.run(
+	count: 2,
+	restart: true,
+	# Allow up to 60 seconds for startup:
+	startup_timeout: 60,
+	# Require health checks every 30 seconds after ready:
+	health_check_timeout: 30
+) do |instance|
+	# Send status updates during startup:
+	instance.status!("Preparing...")
+	
+	# Do initialization work...
+	
+	# Signal readiness:
+	instance.ready!
+	
+	# After ready, send periodic health checks:
+	while true
+		instance.ready!
+		sleep(10)
+	end
+end
+
+container.wait
+```
+
+**Note:** Any message sent through the notification pipe (including `status!` and `ready!`) resets the timeout clock. This allows processes to take time during startup while still detecting hung processes.
+
+## Controllers
+
+The controller provides the life-cycle management for one or more containers of processes. It provides behaviour like starting, restarting, reloading and stopping. You can see some [example implementations in Falcon](https://github.com/socketry/falcon/blob/master/lib/falcon/controller/). If the process running the controller receives `SIGHUP` it will recreate the container gracefully.
+
+``` ruby
+require "async/container"
+
+Console.logger.debug!
+
+class Controller < Async::Container::Controller
+	def create_container
+		Async::Container::Forked.new
+		# or Async::Container::Threaded.new
+		# or Async::Container::Hybrid.new
+	end
+	
+	def setup(container)
+		container.run count: 2, restart: true do |instance|
+			while true
+				Console.debug(instance, "Sleeping...")
+				sleep(1)
+			end
+		end
+	end
+end
+
+controller = Controller.new
+
+controller.run
+
+# If you send SIGHUP to this process, it will recreate the container.
+```
+
+### Controller Signal Handling
+
+Controllers are designed to run at the process level and are therefore responsible for processing signals. When your controller process receives these signals:
+
+- `SIGHUP` → Gracefully reload the container (restart with new configuration).
+- `SIGINT` → Begin graceful shutdown of the entire controller and all children.
+- `SIGTERM` → Begin immediate shutdown of the controller and all children.
+
+Ideally, do not send `SIGKILL` to a controller, as it will immediately terminate the controller without giving it a chance to gracefully shut down child processes. This can leave orphaned processes running and prevent proper cleanup.

data/context/index.yaml

@@ -0,0 +1,25 @@
+# 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: Abstract container-based parallelism using threads and processes where
+  appropriate.
+metadata:
+  documentation_uri: https://socketry.github.io/async-container/
+  source_code_uri: https://github.com/socketry/async-container.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `async-container` to build basic scalable
+    systems.
+- path: policies.md
+  title: Container Policies
+  description: This guide explains how to use policies to monitor container health
+    and implement custom failure handling strategies.
+- path: systemd-integration.md
+  title: Systemd Integration
+  description: This guide explains how to use `async-container` with systemd to manage
+    your application as a service.
+- path: kubernetes-integration.md
+  title: Kubernetes Integration
+  description: This guide explains how to use `async-container` with Kubernetes to
+    manage your application as a containerized service.

data/context/kubernetes-integration.md

@@ -0,0 +1,45 @@
+# Kubernetes Integration
+
+This guide explains how to use `async-container` with Kubernetes to manage your application as a containerized service.
+
+## Deployment Configuration
+
+Create a deployment configuration file for your application:
+
+```yaml
+# my-app-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - name: my-app
+          image: my-app-image:latest
+          env:
+            - name: NOTIFY_LOG
+              value: "/tmp/notify.log"
+          ports:
+            - containerPort: 3000
+          readinessProbe:
+            exec:
+              command: ["bundle", "exec", "bake", "async:container:notify:log:ready?"]
+            initialDelaySeconds: 5
+            periodSeconds: 5
+            failureThreshold: 12
+```
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when Kubernetes terminates pods during rolling updates, scaling down, or pod eviction.
+
+**Note**: Kubernetes sends `SIGTERM` to containers when terminating pods. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before Kubernetes sends `SIGKILL` (after the termination grace period).

data/context/policies.md

@@ -0,0 +1,168 @@
+# Container Policies
+
+This guide explains how to use policies to monitor container health and implement custom failure handling strategies.
+
+## Motivation
+
+Containers restart failing child processes automatically, but sometimes you need more intelligent behavior:
+
+- **Detect failure patterns**: Repeated segfaults indicate serious bugs that won't fix themselves by restarting.
+- **Prevent resource waste**: Stop trying to restart processes that will never succeed.
+- **Monitor health**: Track failure rates and alert when thresholds are exceeded.
+- **Custom responses**: Implement application-specific logic for different failure types.
+
+Use policies when you need:
+- **Segfault detection**: Stop the container after multiple segfaults indicate memory corruption.
+- **Failure rate monitoring**: Alert or stop when children fail too frequently.
+- **Custom logging**: Track specific failure types for debugging.
+- **Graceful degradation**: Give unhealthy children extra time before killing them.
+
+## Default Behavior
+
+Containers use {ruby Async::Container::Policy::DEFAULT} unless you specify otherwise. The default policy:
+
+- Allows children to restart indefinitely if configured with `restart: true`.
+- Kills children immediately when health checks fail.
+- Kills children immediately when startup timeouts are exceeded.
+
+This is appropriate for most applications, but you can customize it.
+
+## Creating Custom Policies
+
+Policies are Ruby classes that inherit from {ruby Async::Container::Policy} and override callback methods:
+
+``` ruby
+require "async/container"
+
+class SegfaultDetectionPolicy < Async::Container::Policy
+	def initialize(max_segfaults: 3, window: 60)
+		@max_segfaults = max_segfaults
+		@segfault_rate = Async::Container::Rate.new(window: window)
+	end
+	
+	def child_exit(container, child, status, name:, key:, **options)
+		if segfault?(status)
+			@segfault_rate.add(1)
+			
+			segfault_count = @segfault_rate.total
+			
+			Console.warn(self, "Segfault detected", 
+				name: name, 
+				count: segfault_count,
+				rate: @segfault_rate.per_minute
+			)
+		end
+		
+		# Stop container if too many segfaults
+		if segfault_count >= @max_segfaults
+			unless container.stopping?
+				Console.error(self, "Too many segfaults, stopping container",
+					count: segfault_count,
+					rate: @segfault_rate.per_second
+				)
+				container.stop(false)
+			end
+		end
+	end
+end
+
+controller = Async::Container::Controller.new 
+
+# Use the custom policy:
+def controller.make_policy
+	SegfaultDetectionPolicy.new(max_segfaults: 5, window: 120)
+end
+
+# ...
+
+controller.run
+```
+
+## Policy Callbacks
+
+Policies can implement these callbacks:
+
+### `child_spawn`
+
+Called when a child process starts:
+
+``` ruby
+def child_spawn(container, child, name:, key:, **options)
+	Console.info(self, "Child started", name: name)
+end
+```
+
+Use this for tracking which children are running or initializing per-child state.
+
+### `child_exit`
+
+Called when a child process exits (success or failure):
+
+``` ruby
+def child_exit(container, child, status, name:, key:, **options)
+	if success?(status)
+		Console.info(self, "Child succeeded", name: name)
+	else
+		Console.warn(self, "Child failed", 
+			name: name,
+			exit_code: exit_code(status),
+			signal: signal(status)
+		)
+	end
+end
+```
+
+This is the main callback for implementing failure detection logic. You can:
+- Track failure rates.
+- Detect specific failure types (segfaults, aborts).
+- Call `container.stop` to stop the entire container.
+
+### `health_check_failed`
+
+Called when a health check timeout is exceeded. The default implementation logs and kills the child:
+
+``` ruby
+def health_check_failed(container, child, age:, timeout:, **options)
+	Console.warn(self, "Health check failed", child: child, age: age)
+	
+	# Send alert before killing
+	send_alert("Health check failed for child")
+	
+	# Call default behavior
+	super
+end
+```
+
+Override this to:
+- Send alerts before killing.
+- Give children more time (don't kill immediately).
+- Implement custom recovery logic.
+
+### `startup_failed`
+
+Called when a startup timeout is exceeded. The default implementation logs and kills the child:
+
+``` ruby
+def startup_failed(container, child, age:, timeout:, **options)
+	# Custom logging with more context
+	Console.error(self, "Child never became ready",
+		child: child,
+		age: age,
+		timeout: timeout
+	)
+	
+	# Kill the child (default behavior)
+	super
+end
+```
+
+## Helper Methods
+
+The {ruby Async::Container::Policy} class provides helper methods for detecting specific failure conditions:
+
+- `segfault?(status)` - Returns true if the process was terminated by SIGSEGV.
+- `abort?(status)` - Returns true if the process was terminated by SIGABRT.
+- `killed?(status)` - Returns true if the process was terminated by SIGKILL.
+- `success?(status)` - Returns true if the process exited successfully.
+- `signal(status)` - Returns the signal number that terminated the process.
+- `exit_code(status)` - Returns the exit code.

data/context/systemd-integration.md

@@ -0,0 +1,28 @@
+# Systemd Integration
+
+This guide explains how to use `async-container` with systemd to manage your application as a service.
+
+## Service File
+
+Install a template file into `/etc/systemd/system/`:
+
+```
+# my-daemon.service
+[Unit]
+Description=My Daemon
+
+[Service]
+Type=notify
+ExecStart=bundle exec my-daemon
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Ensure `Type=notify` is set, so that the service can notify systemd when it is ready.
+
+## Graceful Shutdown
+
+Controllers handle `SIGTERM` gracefully (same as `SIGINT`). This ensures proper graceful shutdown when systemd stops the service.
+
+**Note**: systemd sends `SIGTERM` to services when stopping them. With graceful handling, your application will have time to clean up resources, finish in-flight requests, and shut down gracefully before systemd escalates to `SIGKILL` (after the timeout specified in the service file).

data/lib/async/container/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.34.3"
+		VERSION = "0.34.4"
 	end
 end

data/readme.md

@@ -28,6 +28,10 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
 Please see the [project releases](https://socketry.github.io/async-container/releases/index) for all releases.
 
+### v0.34.4
+
+  - Add missing `bake` and `context` files to the release.
+
 ### v0.34.3
 
   - `Controller#restart` and `Controller#reload` now include a `status:` message in the `ready!` notification, so `systemctl status` shows "Running with N children." instead of the stale "Initializing controller..." message.
@@ -68,11 +72,6 @@ Please see the [project releases](https://socketry.github.io/async-container/rel
 
   - Introduce `Client#healthy!` for sending health check messages.
 
-### v0.28.0
-
-  - Add `startup_timeout` parameter to `spawn` and `run` methods for detecting processes that hang during startup and never become ready.
-  - Health check timeout now only applies after a process becomes ready, preventing premature timeouts for slow-starting applications.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.34.4
+
+  - Add missing `bake` and `context` files to the release.
+
 ## v0.34.3
 
   - `Controller#restart` and `Controller#reload` now include a `status:` message in the `ready!` notification, so `systemctl status` shows "Running with N children." instead of the stale "Initializing controller..." message.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.34.3
+  version: 0.34.4
 platform: ruby
 authors:
 - Samuel Williams
@@ -61,6 +61,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- bake/async/container/notify/log.rb
+- context/getting-started.md
+- context/index.yaml
+- context/kubernetes-integration.md
+- context/policies.md
+- context/systemd-integration.md
 - lib/async/container.rb
 - lib/async/container/best.rb
 - lib/async/container/channel.rb
@@ -107,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.
 test_files: []