async-service-chaos_kitty 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3ea2295d1cc85dec15cac5131cc571726ecbc1b1ca17ece44598d47f66a6feb
+  data.tar.gz: 35bc5bb1c4eaf3f889413525653c931a115f71b07170ea8cd6733500207f4f83
+SHA512:
+  metadata.gz: b41e245341e3fb7140592b7782aa8561648555db543c241e26afb0a054d0029bb99efb8b0ab0fea42ef664504a65d7003517e8bc0ccdf2212b8f4579bdc6a721
+  data.tar.gz: bcaa93b95324b9c6461f8abfebabc1fe55e2255d839d7db9cd0a7c2cbe58a23bd98162a339bfa932203812e32845db6a083c4101d5a764a57a381ffdbcf14ce7

data/architecture.md

@@ -0,0 +1,153 @@
+# Architecture
+
+This document describes the architecture of async-service-chaos_kitty, which follows the same pattern as async-service-supervisor.
+
+## Overview
+
+ChaosKitty is a chaos monkey system for testing service resilience. It uses a client-server architecture where workers connect to a central chaos server, and various chaos operations are unleashed on the connected workers.
+
+## Components
+
+### Core Components
+
+#### Server (`server.rb`)
+The main chaos server that:
+- Accepts connections from workers (victims)
+- Manages chaos operations
+- Coordinates between chaos operations and connected victims
+- Tracks all connected victims via controllers
+
+#### Worker (`worker.rb`)
+A worker process that:
+- Connects to the chaos server
+- Registers itself as a victim
+- Exposes victim controller methods for chaos operations
+- Runs the main application logic
+
+#### Client (`client.rb`)
+Base client class for connecting to the chaos server. Extended by Worker.
+
+### Controllers
+
+#### ChaosController (`chaos_controller.rb`)
+Server-side controller that:
+- Manages victim registration
+- Provides access to victim proxies
+- Handles status queries
+- Tracks victim metadata (ID, process ID, connection)
+
+#### VictimController (`victim_controller.rb`)
+Client-side controller that:
+- Exposes methods that can be invoked by chaos operations
+- Implements chaos actions: delay, raise_error, allocate_memory, cpu_spin, trigger_gc
+- Logs chaos events
+
+### Chaos Operations
+
+All chaos operations follow the same pattern:
+- `register(chaos_controller)`: Called when a new victim connects
+- `remove(chaos_controller)`: Called when a victim disconnects
+- `status()`: Returns current status
+- `run()`: Starts the chaos operation loop
+
+#### Hairball (`hairball.rb`)
+Causes random delays and blocking operations.
+
+**Parameters:**
+- `interval`: How often to check for chaos opportunities
+- `probability`: Chance of causing chaos (0.0-1.0)
+- `min_delay`: Minimum delay duration
+- `max_delay`: Maximum delay duration
+
+**Effect:** Calls `victim.delay(duration:)` on random victims
+
+#### Scratch (`scratch.rb`)
+Randomly terminates victim processes.
+
+**Parameters:**
+- `interval`: How often to check for chaos opportunities
+- `probability`: Chance of causing chaos (0.0-1.0)
+- `signal`: Signal to send to process
+
+**Effect:** Sends signal to victim's process ID
+
+#### Floop (`floop.rb`)
+Creates random memory spikes.
+
+**Parameters:**
+- `interval`: How often to check for chaos opportunities
+- `probability`: Chance of causing chaos (0.0-1.0)
+- `min_size_mb`: Minimum memory allocation
+- `max_size_mb`: Maximum memory allocation
+- `hold_duration`: How long to hold the allocation
+
+**Effect:** Calls `victim.allocate_memory(size_mb:, hold_duration:)`
+
+#### Zoomies (`zoomies.rb`)
+Generates random CPU spikes.
+
+**Parameters:**
+- `interval`: How often to check for chaos opportunities
+- `probability`: Chance of causing chaos (0.0-1.0)
+- `min_duration`: Minimum CPU spin duration
+- `max_duration`: Maximum CPU spin duration
+
+**Effect:** Calls `victim.cpu_spin(duration:)`
+
+#### Yowl (`yowl.rb`)
+Raises random exceptions.
+
+**Parameters:**
+- `interval`: How often to check for chaos opportunities
+- `probability`: Chance of causing chaos (0.0-1.0)
+- `messages`: Array of possible error messages
+
+**Effect:** Calls `victim.raise_error(message:)`
+
+## Communication Flow
+
+1. **Worker Startup:**
+   - Worker creates a connection to chaos server
+   - Worker creates VictimController and binds it
+   - Worker calls `chaos.register(victim_proxy, process_id:)`
+   - Server allocates ID and calls `chaos_operation.register()` for each operation
+
+2. **Chaos Execution:**
+   - Chaos operation runs in a loop at specified interval
+   - On each iteration, randomly selects a victim
+   - Checks probability to determine if chaos should occur
+   - Invokes remote method on victim via proxy
+   - Victim controller executes the chaos action
+
+3. **Worker Shutdown:**
+   - Connection closes
+   - Server calls `chaos_operation.remove()` for each operation
+   - Controller is removed from tracking
+
+## IPC Mechanism
+
+- Uses Unix domain sockets for inter-process communication
+- Default socket path: `chaos_kitty.ipc`
+- Built on async-bus for RPC capabilities
+- Supports multi-hop forwarding for proxy calls
+
+## Threading Model
+
+- Built on Async framework for cooperative concurrency
+- Each chaos operation runs in its own Async task
+- Connection handling is concurrent
+- Chaos operations execute independently
+
+## Comparison with async-service-supervisor
+
+| Supervisor | ChaosKitty | Purpose |
+|------------|------------|---------|
+| Monitor | Chaos Operation | Watches/affects workers |
+| MemoryMonitor | Floop | Memory-related |
+| ProcessMonitor | Scratch | Process-related |
+| Worker | Worker | Connects to server |
+| SupervisorController | ChaosController | Server-side RPC |
+| WorkerController | VictimController | Client-side RPC |
+| Monitors health | Causes chaos | Core function |
+
+Both systems share the same architectural pattern but serve opposite purposes: one monitors and maintains health, the other intentionally causes problems to test resilience.

data/lib/async/service/chaos_kitty/chaos_controller.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/bus/controller"
+
+module Async
+	module Service
+		module ChaosKitty
+			# Controller for chaos operations.
+			#
+			# Handles registration of victims, victim lookup, and status queries.
+			class ChaosController < Async::Bus::Controller
+				def initialize(server, connection)
+					@server = server
+					@connection = connection
+					
+					@id = nil
+					@process_id = nil
+					@victim = nil
+				end
+				
+				# @attribute [Server] The server instance.
+				attr :server
+				
+				# @attribute [Connection] The connection instance.
+				attr :connection
+				
+				# @attribute [Integer] The ID assigned to this victim.
+				attr :id
+				
+				# @attribute [Integer] The process ID of the victim.
+				attr :process_id
+				
+				# @attribute [Proxy] The proxy to the victim controller.
+				attr :victim
+				
+				# Register a victim connection with the chaos server.
+				#
+				# Allocates a unique sequential ID, stores the victim controller proxy,
+				# and notifies all chaos operations of the new connection.
+				#
+				# @parameter victim [Proxy] The proxy to the victim controller.
+				# @parameter process_id [Integer] The process ID of the victim.
+				# @returns [Integer] The connection ID assigned to the victim.
+				def register(victim, process_id:)
+					raise RuntimeError, "Already registered" if @id
+					
+					@id = @server.next_id
+					@process_id = process_id
+					@victim = victim
+					
+					@server.add(self)
+					
+					return @id
+				end
+				
+				# Get a victim controller proxy by connection ID.
+				#
+				# Returns a proxy to the victim controller that can be used to invoke
+				# operations directly on the victim. The proxy uses multi-hop forwarding
+				# to route calls through the chaos server to the victim.
+				#
+				# @parameter id [Integer] The ID of the victim.
+				# @returns [Proxy] A proxy to the victim controller.
+				# @raises [ArgumentError] If the connection ID is not found.
+				def [](id)
+					unless id
+						raise ArgumentError, "Missing 'id' parameter"
+					end
+					
+					chaos_controller = @server.controllers[id]
+					
+					unless chaos_controller
+						raise ArgumentError, "Connection not found: #{id}"
+					end
+					
+					victim = chaos_controller.victim
+					
+					unless victim
+						raise ArgumentError, "Victim controller not found for connection: #{id}"
+					end
+					
+					return victim
+				end
+				
+				# List all registered victim IDs.
+				#
+				# @returns [Array(Integer)] An array of IDs for all registered victims.
+				def keys
+					@server.controllers.keys
+				end
+				
+				# Query the status of the chaos server and all connected victims.
+				#
+				# Returns an array of status information from each chaos operation.
+				# Each chaos operation provides its own status representation.
+				#
+				# @returns [Array] An array of status information from each chaos operation.
+				def status
+					@server.chaos_operations.map do |chaos|
+						begin
+							chaos.status
+						rescue => error
+							error
+						end
+					end.compact
+				end
+			end
+		end
+	end
+end

data/lib/async/service/chaos_kitty/client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/bus/client"
+
+module Async
+	module Service
+		module ChaosKitty
+			# A client provides a mechanism to connect to a chaos server in order to execute operations.
+			class Client < Async::Bus::Client
+				# Initialize a new client.
+				#
+				# @parameter endpoint [IO::Endpoint] The chaos endpoint to connect to.
+				def initialize(endpoint: ChaosKitty.endpoint, **options)
+					super(endpoint, **options)
+				end
+			end
+		end
+	end
+end

data/lib/async/service/chaos_kitty/endpoint.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "io/endpoint/unix_endpoint"
+
+module Async
+	module Service
+		module ChaosKitty
+			# Get the chaos kitty IPC endpoint.
+			#
+			# @parameter path [String] The path for the Unix socket (default: "chaos_kitty.ipc").
+			# @returns [IO::Endpoint] The Unix socket endpoint.
+			def self.endpoint(path = "chaos_kitty.ipc")
+				::IO::Endpoint.unix(path)
+			end
+		end
+	end
+end

data/lib/async/service/chaos_kitty/floop.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "set"
+require_relative "loop"
+
+module Async
+	module Service
+		module ChaosKitty
+			# Floop causes random memory spikes in victim processes.
+			#
+			# Like a cat flopping over dramatically, this chaos operation randomly
+			# allocates large amounts of memory to test memory handling and limits.
+			class Floop
+				# Create a new floop chaos operation.
+				#
+				# @parameter interval [Integer] How often to check for chaos opportunities.
+				# @parameter probability [Float] Probability (0.0 to 1.0) of causing chaos on each check.
+				# @parameter min_size_mb [Integer] Minimum memory allocation in megabytes.
+				# @parameter max_size_mb [Integer] Maximum memory allocation in megabytes.
+				# @parameter hold_duration [Numeric] How long to hold the allocation.
+				def initialize(interval: 30, probability: 0.2, min_size_mb: 10, max_size_mb: 100, hold_duration: 2)
+					@interval = interval
+					@probability = probability
+					@min_size_mb = min_size_mb
+					@max_size_mb = max_size_mb
+					@hold_duration = hold_duration
+					@victims = Set.new.compare_by_identity
+				end
+				
+				# @attribute [Set] The set of registered victims.
+				attr_reader :victims
+				
+				# Register a victim with the floop chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def register(chaos_controller)
+					Console.debug(self, "😺 Registering victim for floop chaos.", id: chaos_controller.id)
+					@victims.add(chaos_controller)
+				end
+				
+				# Remove a victim from the floop chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def remove(chaos_controller)
+					@victims.delete(chaos_controller)
+				end
+				
+				# Get status for the floop chaos.
+				#
+				# @returns [Hash] Status including victim count and configuration.
+				def status
+					{
+						floop: {
+							victims: @victims.size,
+							probability: @probability,
+							size_range_mb: [@min_size_mb, @max_size_mb],
+							hold_duration: @hold_duration
+						}
+					}
+				end
+				
+				# Unleash a floop on a random victim.
+				def unleash_floop
+					return if @victims.empty?
+					
+					# Pick a random victim
+					victim = @victims.to_a.sample
+					return unless victim
+					
+					# Check probability
+					return unless rand < @probability
+					
+					# Calculate random size
+					size_mb = @min_size_mb + rand(@max_size_mb - @min_size_mb)
+					
+					Console.info(self, "😾 *FLOOP* Memory spike incoming!", id: victim.id, size_mb: size_mb)
+					
+					begin
+						victim_proxy = victim.connection[:victim]
+						if victim_proxy
+							victim_proxy.allocate_memory(size_mb: size_mb, hold_duration: @hold_duration)
+						end
+					rescue => error
+						Console.error(self, "Failed to unleash floop!", id: victim.id, exception: error)
+					end
+				end
+				
+				# Run the floop chaos operation.
+				#
+				# @returns [Async::Task] The task that is running the floop chaos.
+				def run
+					Async do
+						Loop.run(interval: @interval) do
+							unleash_floop
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/service/chaos_kitty/hairball.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "set"
+require_relative "loop"
+
+module Async
+	module Service
+		module ChaosKitty
+			# Hairball causes random delays and blocking in victim processes.
+			#
+			# Like a cat hacking up a hairball, this chaos operation randomly
+			# blocks victims, simulating slow responses or stuck operations.
+			class Hairball
+				# Create a new hairball chaos operation.
+				#
+				# @parameter interval [Integer] How often to check for chaos opportunities.
+				# @parameter probability [Float] Probability (0.0 to 1.0) of causing chaos on each check.
+				# @parameter min_delay [Numeric] Minimum delay duration in seconds.
+				# @parameter max_delay [Numeric] Maximum delay duration in seconds.
+				def initialize(interval: 30, probability: 0.3, min_delay: 0.5, max_delay: 5.0)
+					@interval = interval
+					@probability = probability
+					@min_delay = min_delay
+					@max_delay = max_delay
+					@victims = Set.new.compare_by_identity
+				end
+				
+				# @attribute [Set] The set of registered victims.
+				attr_reader :victims
+				
+				# Register a victim with the hairball chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def register(chaos_controller)
+					Console.debug(self, "😺 Registering victim for hairball chaos.", id: chaos_controller.id)
+					@victims.add(chaos_controller)
+				end
+				
+				# Remove a victim from the hairball chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def remove(chaos_controller)
+					@victims.delete(chaos_controller)
+				end
+				
+				# Get status for the hairball chaos.
+				#
+				# @returns [Hash] Status including victim count and configuration.
+				def status
+					{
+						hairball: {
+							victims: @victims.size,
+							probability: @probability,
+							delay_range: [@min_delay, @max_delay]
+						}
+					}
+				end
+				
+				# Unleash a hairball on a random victim.
+				def unleash_hairball
+					return if @victims.empty?
+					
+					# Pick a random victim
+					victim = @victims.to_a.sample
+					return unless victim
+					
+					# Check probability
+					return unless rand < @probability
+					
+					# Calculate random delay
+					delay = @min_delay + rand * (@max_delay - @min_delay)
+					
+					Console.info(self, "😾 *HACK* *HACK* Hairball time!", id: victim.id, delay: delay)
+					
+					begin
+						victim_proxy = victim.connection[:victim]
+						if victim_proxy
+							victim_proxy.delay(duration: delay)
+						end
+					rescue => error
+						Console.error(self, "Failed to unleash hairball!", id: victim.id, exception: error)
+					end
+				end
+				
+				# Run the hairball chaos operation.
+				#
+				# @returns [Async::Task] The task that is running the hairball chaos.
+				def run
+					Async do
+						Loop.run(interval: @interval) do
+							unleash_hairball
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/service/chaos_kitty/loop.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Service
+		module ChaosKitty
+			# A helper for running loops at aligned intervals.
+			module Loop
+				# A robust loop that executes a block at aligned intervals.
+				#
+				# The alignment is modulo the current clock in seconds.
+				#
+				# If an error occurs during the execution of the block, it is logged and the loop continues.
+				#
+				# @parameter interval [Integer] The interval in seconds between executions of the block.
+				def self.run(interval: 60, &block)
+					while true
+						# Compute the wait time to the next interval:
+						wait = interval - (Time.now.to_f % interval)
+						if wait.positive?
+							# Sleep until the next interval boundary:
+							sleep(wait)
+						end
+						
+						begin
+							yield
+						rescue => error
+							Console.error(self, "Loop error:", error)
+						end
+					end
+				end
+			end
+			
+			private_constant :Loop
+		end
+	end
+end

data/lib/async/service/chaos_kitty/scratch.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "set"
+require_relative "loop"
+
+module Async
+	module Service
+		module ChaosKitty
+			# Scratch randomly kills victim processes.
+			#
+			# Like a cat scratching furniture, this chaos operation randomly
+			# terminates victim processes to test resilience and recovery.
+			class Scratch
+				# Create a new scratch chaos operation.
+				#
+				# @parameter interval [Integer] How often to check for chaos opportunities.
+				# @parameter probability [Float] Probability (0.0 to 1.0) of causing chaos on each check.
+				# @parameter signal [Symbol] The signal to send when scratching.
+				def initialize(interval: 60, probability: 0.1, signal: :TERM)
+					@interval = interval
+					@probability = probability
+					@signal = signal
+					@victims = Set.new.compare_by_identity
+				end
+				
+				# @attribute [Set] The set of registered victims.
+				attr_reader :victims
+				
+				# Register a victim with the scratch chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def register(chaos_controller)
+					Console.debug(self, "😺 Registering victim for scratch chaos.", id: chaos_controller.id)
+					@victims.add(chaos_controller)
+				end
+				
+				# Remove a victim from the scratch chaos.
+				#
+				# @parameter chaos_controller [ChaosController] The chaos controller for the victim.
+				def remove(chaos_controller)
+					@victims.delete(chaos_controller)
+				end
+				
+				# Get status for the scratch chaos.
+				#
+				# @returns [Hash] Status including victim count and configuration.
+				def status
+					{
+						scratch: {
+							victims: @victims.size,
+							probability: @probability,
+							signal: @signal
+						}
+					}
+				end
+				
+				# Unleash a scratch on a random victim.
+				def unleash_scratch
+					return if @victims.empty?
+					
+					# Pick a random victim
+					victim = @victims.to_a.sample
+					return unless victim
+					
+					# Check probability
+					return unless rand < @probability
+					
+					process_id = victim.process_id
+					return unless process_id
+					
+					Console.info(self, "😾 *SCRATCH* Taking down a victim!", id: victim.id, process_id: process_id, signal: @signal)
+					
+					begin
+						Process.kill(@signal, process_id)
+					rescue Errno::ESRCH
+						Console.warn(self, "Process already gone!", process_id: process_id)
+					rescue => error
+						Console.error(self, "Failed to scratch victim!", process_id: process_id, exception: error)
+					end
+				end
+				
+				# Run the scratch chaos operation.
+				#
+				# @returns [Async::Task] The task that is running the scratch chaos.
+				def run
+					Async do
+						Loop.run(interval: @interval) do
+							unleash_scratch
+						end
+					end
+				end
+			end
+		end
+	end
+end