fractor 0.1.4 → 0.1.7

data/examples/continuous_chat_server/simulate.rb

@@ -0,0 +1,343 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "optparse"
+require "json"
+
+module ContinuousChat
+  # Simulation controller that manages the server and clients
+  class Simulation
+    attr_reader :server_port, :log_dir
+
+    def initialize(server_port = 3000, duration = 10, log_dir = "logs")
+      @server_port = server_port
+      @duration = duration
+      @log_dir = log_dir
+      @server_pid = nil
+      @client_pids = {}
+      @running = false
+
+      # Create log directory if it doesn't exist
+      FileUtils.mkdir_p(@log_dir)
+    end
+
+    # Start the simulation
+    def start
+      puts "Starting chat simulation on port #{@server_port}"
+      puts "Logs will be saved to #{@log_dir}"
+
+      # Start the server
+      start_server
+
+      # Give the server time to initialize
+      puts "Waiting for server to initialize..."
+      sleep(2)
+
+      # Start the clients
+      start_clients
+
+      @running = true
+      puts "Chat simulation started"
+
+      # Wait for the specified duration
+      puts "Simulation will run for #{@duration} seconds"
+
+      # Give clients time to connect
+      sleep(2)
+      puts "Clients should be connecting now..."
+
+      # Wait for messages to be processed
+      remaining_time = @duration - 4
+      if remaining_time.positive?
+        puts "Waiting #{remaining_time} more seconds for processing..."
+        sleep(remaining_time)
+      end
+
+      puts "Simulation time complete, stopping..."
+
+      # Stop the simulation
+      stop
+
+      # Analyze the logs
+      analyze_logs
+
+      true
+    rescue StandardError => e
+      puts "Failed to start simulation: #{e.message}"
+      stop
+      false
+    end
+
+    # Stop the simulation
+    def stop
+      puts "Stopping chat simulation..."
+
+      # Stop all clients
+      stop_clients
+
+      # Stop the server
+      stop_server
+
+      @running = false
+      puts "Chat simulation stopped"
+    end
+
+    private
+
+    # Start the server process
+    def start_server
+      server_log_file = File.join(@log_dir, "server_messages.log")
+
+      # Get the directory where this script is located
+      script_dir = File.dirname(__FILE__)
+      server_script = File.join(script_dir, "chat_server.rb")
+
+      server_cmd = "ruby #{server_script} #{@server_port} #{server_log_file}"
+
+      puts "Starting server: #{server_cmd}"
+
+      # Start the server process as a fork
+      @server_pid = fork do
+        exec(server_cmd)
+      end
+
+      puts "Server started with PID #{@server_pid}"
+    end
+
+    # Stop the server process
+    def stop_server
+      return unless @server_pid
+
+      puts "Stopping server (PID #{@server_pid})..."
+
+      # Send SIGINT to the server process
+      begin
+        Process.kill("INT", @server_pid)
+        # Give it a moment to shut down gracefully
+        sleep(1)
+
+        # Force kill if still running
+        Process.kill("KILL", @server_pid) if process_running?(@server_pid)
+      rescue Errno::ESRCH
+        # Process already gone
+      end
+
+      @server_pid = nil
+      puts "Server stopped"
+    end
+
+    # Start client processes
+    def start_clients
+      # Define the client usernames and their messages
+      clients = {
+        "alice" => [
+          { content: "Hello everyone!", recipient: "all" },
+          { content: "I'm working on a Ruby project using sockets",
+            recipient: "all" },
+          { content: "It's a simple chat server and client", recipient: "all" },
+        ],
+        "bob" => [
+          { content: "Hi Alice!", recipient: "alice" },
+          { content: "That sounds interesting. What kind of project?",
+            recipient: "alice" },
+          { content: "Cool! I love Ruby's socket features",
+            recipient: "alice" },
+        ],
+        "charlie" => [
+          { content: "How's everyone doing today?", recipient: "all" },
+          { content: "Are you using any specific libraries?",
+            recipient: "alice" },
+          { content: "Non-blocking IO in chat clients is efficient",
+            recipient: "all" },
+        ],
+      }
+
+      puts "Starting #{clients.size} clients: #{clients.keys.join(', ')}"
+
+      # Start each client in a separate process
+      clients.each do |username, messages|
+        start_client(username, messages)
+      end
+    end
+
+    # Start a single client process
+    def start_client(username, messages)
+      client_log_file = File.join(@log_dir, "client_#{username}_messages.log")
+      messages_file = File.join(@log_dir,
+                                "client_#{username}_send_messages.json")
+
+      # Write the messages to a JSON file
+      File.write(messages_file, JSON.generate(messages))
+
+      # Get the directory where this script is located
+      script_dir = File.dirname(__FILE__)
+      client_script = File.join(script_dir, "chat_client.rb")
+
+      # Build the client command
+      client_cmd = "ruby #{client_script} #{username} #{@server_port} #{client_log_file}"
+
+      puts "Starting client #{username}"
+
+      # Start the client process as a fork
+      @client_pids[username] = fork do
+        exec(client_cmd)
+      end
+
+      puts "Client #{username} started with PID #{@client_pids[username]}"
+    end
+
+    # Stop all client processes
+    def stop_clients
+      return if @client_pids.empty?
+
+      puts "Stopping #{@client_pids.size} clients..."
+
+      @client_pids.each do |username, pid|
+        # Try to gracefully terminate the process
+        begin
+          Process.kill("INT", pid)
+          # Give it a moment to shut down
+          sleep(0.5)
+
+          # Force kill if still running
+          Process.kill("KILL", pid) if process_running?(pid)
+        rescue Errno::ESRCH
+          # Process already gone
+        end
+
+        puts "Client #{username} stopped"
+      rescue StandardError => e
+        puts "Error stopping client #{username}: #{e.message}"
+      end
+
+      @client_pids.clear
+    end
+
+    # Check if a process is still running
+    def process_running?(pid)
+      Process.getpgid(pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    # Analyze the log files after the simulation
+    def analyze_logs
+      puts "\nSimulation Results"
+      puts "================="
+
+      # Analyze server log
+      server_log_file = File.join(@log_dir, "server_messages.log")
+      if File.exist?(server_log_file)
+        server_log = File.readlines(server_log_file)
+        puts "Server processed #{server_log.size} log entries"
+
+        # Count message types
+        message_count = server_log.count do |line|
+          line.include?("Received from")
+        end
+        broadcast_count = server_log.count do |line|
+          line.include?('Broadcasting: {:type=>"broadcast"')
+        end
+        direct_count = server_log.count do |line|
+          line =~ /Received from \w+:.*"recipient":"(?!all)/
+        end
+
+        puts "  - #{message_count} messages received from clients"
+        puts "  - #{broadcast_count} broadcast messages sent"
+        puts "  - #{direct_count} direct messages sent"
+      else
+        puts "Server log file not found"
+      end
+
+      puts "\nClient Activity:"
+      # Analyze each client log
+      @client_pids.each_key do |username|
+        client_log_file = File.join(@log_dir, "client_#{username}_messages.log")
+        if File.exist?(client_log_file)
+          client_log = File.readlines(client_log_file)
+          sent_count = client_log.count { |line| line.include?("Sent message") }
+          received_count = client_log.count do |line|
+            line.include?("Received:")
+          end
+
+          puts "  #{username}: Sent #{sent_count} messages, Received #{received_count} messages"
+        else
+          puts "  #{username}: Log file not found"
+        end
+      end
+
+      puts "\nLog files are available in the #{@log_dir} directory for detailed analysis."
+    end
+  end
+end
+
+# When run directly, start the simulation
+if __FILE__ == $PROGRAM_NAME
+  options = {
+    port: 3000,
+    duration: 10,
+    log_dir: "logs",
+  }
+
+  # Parse command line options
+  OptionParser.new do |opts|
+    opts.banner = "Usage: ruby simulate.rb [options]"
+
+    opts.on("-p", "--port PORT", Integer,
+            "Server port (default: 3000)") do |port|
+      options[:port] = port
+    end
+
+    opts.on("-d", "--duration SECONDS", Integer,
+            "Simulation duration in seconds (default: 10)") do |duration|
+      options[:duration] = duration
+    end
+
+    opts.on("-l", "--log-dir DIR",
+            "Directory for log files (default: logs)") do |dir|
+      options[:log_dir] = dir
+    end
+
+    opts.on("-h", "--help", "Show this help message") do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  puts "Starting Chat Simulation"
+  puts "======================"
+  puts "This simulation runs a chat server and multiple clients as separate processes"
+  puts "to demonstrate a basic chat application with socket communication."
+  puts
+
+  # Create and run the simulation
+  simulation = ContinuousChat::Simulation.new(
+    options[:port],
+    options[:duration],
+    options[:log_dir],
+  )
+
+  # Set up signal handlers to properly clean up child processes
+  Signal.trap("INT") do
+    puts "\nSimulation interrupted"
+    simulation.stop
+    exit
+  end
+
+  Signal.trap("TERM") do
+    puts "\nSimulation terminated"
+    simulation.stop
+    exit
+  end
+
+  begin
+    simulation.start
+  rescue Interrupt
+    puts "\nSimulation interrupted"
+    simulation.stop
+  end
+
+  puts "Simulation completed"
+end

data/examples/error_reporting.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require_relative "../lib/fractor"
+require_relative "../lib/fractor/error_reporter"
+
+# Example demonstrating comprehensive error reporting and analytics
+#
+# This example shows how to:
+# 1. Set up an ErrorReporter to track errors
+# 2. Record successes and failures
+# 3. Generate comprehensive error reports
+# 4. Export metrics to Prometheus format
+# 5. Set up error handlers for real-time notifications
+
+# Simulate various types of workers
+class NetworkWorker < Fractor::Worker
+  def process(work)
+    # Simulate network errors
+    if work.input[:fail]
+      Fractor::WorkResult.new(
+        error: SocketError.new("Connection refused"),
+        error_code: :connection_refused,
+        error_context: { endpoint: work.input[:endpoint], attempt: 1 },
+        work: work,
+      )
+    else
+      Fractor::WorkResult.new(result: "Data fetched", work: work)
+    end
+  end
+end
+
+class ValidationWorker < Fractor::Worker
+  def process(work)
+    # Simulate validation errors
+    if work.input[:invalid]
+      Fractor::WorkResult.new(
+        error: ArgumentError.new("Invalid input"),
+        error_code: :validation_failed,
+        error_context: { field: "email", value: work.input[:value] },
+        work: work,
+      )
+    else
+      Fractor::WorkResult.new(result: "Valid", work: work)
+    end
+  end
+end
+
+class CriticalWorker < Fractor::Worker
+  def process(work)
+    # Simulate critical errors
+    if work.input[:critical]
+      Fractor::WorkResult.new(
+        error: SystemStackError.new("Stack overflow"),
+        error_severity: :critical,
+        error_context: { stack_depth: 10000 },
+        work: work,
+      )
+    else
+      Fractor::WorkResult.new(result: "Success", work: work)
+    end
+  end
+end
+
+puts "=" * 80
+puts "Error Reporting Example"
+puts "=" * 80
+puts ""
+
+# Initialize error reporter
+reporter = Fractor::ErrorReporter.new
+
+# Set up error handler for real-time notifications
+reporter.on_error do |work_result, job_name|
+  if work_result.critical?
+    puts "🚨 CRITICAL ERROR DETECTED!"
+    puts "   Job: #{job_name || 'unknown'}"
+    puts "   Error: #{work_result.error.message}"
+    puts ""
+  end
+end
+
+puts "1. Recording various work results..."
+puts "-" * 80
+
+# Simulate successful work
+5.times do |i|
+  work = Fractor::Work.new({ endpoint: "api.example.com", id: i })
+  result = NetworkWorker.new.process(work)
+  reporter.record(result, job_name: "network_job")
+end
+puts "✓ Recorded 5 successful network operations"
+
+# Simulate network errors
+3.times do |i|
+  work = Fractor::Work.new({ fail: true, endpoint: "api.example.com", id: i })
+  result = NetworkWorker.new.process(work)
+  reporter.record(result, job_name: "network_job")
+end
+puts "✗ Recorded 3 network errors"
+
+# Simulate validation errors
+4.times do |i|
+  work = Fractor::Work.new({ invalid: true, value: "bad-email-#{i}" })
+  result = ValidationWorker.new.process(work)
+  reporter.record(result, job_name: "validation_job")
+end
+puts "✗ Recorded 4 validation errors"
+
+# Simulate critical error
+work = Fractor::Work.new({ critical: true })
+result = CriticalWorker.new.process(work)
+reporter.record(result, job_name: "critical_job")
+puts "🚨 Recorded 1 critical error"
+
+# Add some successful validations
+3.times do |i|
+  work = Fractor::Work.new({ valid: true, value: "good-email-#{i}@example.com" })
+  result = ValidationWorker.new.process(work)
+  reporter.record(result, job_name: "validation_job")
+end
+puts "✓ Recorded 3 successful validations"
+
+puts ""
+puts "2. Overall Statistics"
+puts "-" * 80
+puts "Total Successes: #{reporter.total_successes}"
+puts "Total Errors:    #{reporter.total_errors}"
+puts "Error Rate:      #{reporter.overall_error_rate}%"
+puts ""
+
+puts "3. Top Error Categories"
+puts "-" * 80
+reporter.top_categories.each do |category, count|
+  puts "#{category.to_s.ljust(15)}: #{count} errors"
+end
+puts ""
+
+puts "4. Top Error Jobs"
+puts "-" * 80
+reporter.top_jobs.each do |job, count|
+  puts "#{job.to_s.ljust(20)}: #{count} errors"
+end
+puts ""
+
+puts "5. Critical Errors"
+puts "-" * 80
+critical = reporter.critical_errors
+if critical.empty?
+  puts "No critical errors"
+else
+  critical.each do |error_info|
+    puts "Category: #{error_info[:category]}"
+    puts "Count:    #{error_info[:count]}"
+    puts "Recent:"
+    error_info[:recent].each do |err|
+      puts "  - #{err[:error_class]}: #{err[:error_message]}"
+    end
+  end
+end
+puts ""
+
+puts "6. Errors by Severity"
+puts "-" * 80
+reporter.errors_by_severity.each do |severity, count|
+  icon = case severity
+         when :critical then "🚨"
+         when :error then "❌"
+         when :warning then "⚠️"
+         else "ℹ️"
+         end
+  puts "#{icon} #{severity.to_s.ljust(10)}: #{count}"
+end
+puts ""
+
+puts "7. Job-Specific Statistics"
+puts "-" * 80
+reporter.top_jobs.each_key do |job_name|
+  stats = reporter.job_stats(job_name)
+  puts "Job: #{job_name}"
+  puts "  Total Errors:     #{stats[:total_count]}"
+  puts "  Error Rate:       #{stats[:error_rate]}/s"
+  puts "  Most Common Code: #{stats[:most_common_code]}"
+  puts "  Highest Severity: #{stats[:highest_severity]}"
+  puts "  Trend:            #{stats[:trending]}"
+  puts ""
+end
+
+puts "8. Formatted Text Report"
+puts "-" * 80
+puts ""
+puts reporter.formatted_report
+puts ""
+
+puts "9. Prometheus Metrics Export"
+puts "-" * 80
+puts reporter.to_prometheus
+puts ""
+
+puts "10. JSON Export"
+puts "-" * 80
+require "json"
+puts JSON.pretty_generate(reporter.report)
+puts ""
+
+puts "=" * 80
+puts "Example completed successfully!"
+puts "=" * 80

data/examples/file_processor/README.adoc

@@ -0,0 +1,170 @@
+= Batch File Processor Example
+:toc:
+:toclevels: 3
+
+Production-ready batch file processor that handles CSV, JSON, and XML files with validation, transformation, retry logic, and dead letter queue (DLQ) support using Fractor.
+
+== Purpose
+
+This example demonstrates:
+
+* Batch processing of multiple file formats (CSV, JSON, XML)
+* Data validation and transformation
+* Dead letter queue for failed files
+* Retry logic for transient failures
+* Progress tracking and reporting
+* Checksum verification
+
+== Features
+
+=== Multi-Format Support
+
+* **CSV**: Headers with data rows
+* **JSON**: Arrays or objects
+* **XML**: Records with elements
+
+=== Dead Letter Queue (DLQ)
+
+Files that fail validation or parsing are moved to a DLQ for later inspection and retry:
+
+* Failed files preserved with error details
+* Inspection of DLQ contents
+* Individual file retry from DLQ
+* Automatic removal on successful retry
+
+=== Data Transformation
+
+* Type conversion (strings to numbers, booleans)
+* Key normalization (symbol keys)
+* Automatic data enrichment
+
+== Usage
+
+=== Basic Processing
+
+Process all CSV, JSON, and XML files:
+
+[source,bash]
+----
+ruby file_processor.rb sample_files/*.{csv,json,xml}
+----
+
+=== Custom Workers
+
+Process with 8 workers:
+
+[source,bash]
+----
+ruby file_processor.rb -w 8 sample_files/*.csv
+----
+
+=== Disable Validation
+
+Skip validation step:
+
+[source,bash]
+----
+ruby file_processor.rb --no-validate sample_files/*.json
+----
+
+=== Inspect DLQ
+
+View failed files in dead letter queue:
+
+[source,bash]
+----
+ruby file_processor.rb --inspect-dlq
+----
+
+=== Retry DLQ File
+
+Retry a specific file from DLQ:
+
+[source,bash]
+----
+ruby file_processor.rb --retry-dlq invalid_dlq.json
+----
+
+=== Generate Report
+
+Save processing report to file:
+
+[source,bash]
+----
+ruby file_processor.rb -o report.txt sample_files/*.csv
+----
+
+== Architecture
+
+The processor consists of:
+
+* **FileWork**: Work item encapsulating file path and options
+* **FileProcessorWorker**: Worker that parses, validates, and transforms files
+* **BatchFileProcessor**: Orchestrates processing and manages DLQ
+* **ProcessingReport**: Generates summary reports
+
+== Examples
+
+=== Example 1: Successful Processing
+
+[source,bash]
+----
+$ ruby file_processor.rb sample_files/users.csv
+
+Processing 1 files with 4 workers...
+Validation: enabled
+Transformation: enabled
+
+[✓] users.csv: 5 records processed
+
+=== Processing Complete ===
+Successful: 1
+Errors: 0
+DLQ: 0
+----
+
+=== Example 2: Mixed Results with DLQ
+
+[source,bash]
+----
+$ ruby file_processor.rb sample_files/*.csv
+
+Processing 2 files with 4 workers...
+
+[✓] users.csv: 5 records processed
+[✗] invalid.csv: No records found
+
+=== Processing Complete ===
+Successful: 1
+Errors: 1
+DLQ: 1
+----
+
+=== Example 3: DLQ Inspection
+
+[source,bash]
+----
+$ ruby file_processor.rb --inspect-dlq
+
+=== Dead Letter Queue Inspection ===
+
+File: invalid.csv
+  Error: No records found
+  Moved at: 2024-10-25T13:00:00+08:00
+  Checksum: abc123...
+----
+
+== Testing
+
+Run the test suite:
+
+[source,bash]
+----
+bundle exec rspec spec/examples/file_processor_spec.rb
+----
+
+== See Also
+
+* link:../../README.adoc[Fractor Main Documentation]
+* link:../log_analyzer/README.adoc[Log Analyzer Example]
+* link:../api_aggregator/README.adoc[API Aggregator Example]