conductor_ruby 0.1.0

data/examples/simple_worker.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Simple example demonstrating worker functionality with Conductor Ruby SDK
+#
+# Prerequisites:
+# 1. Conductor server running on localhost:7001 (OSS version)
+# 2. A workflow that uses 'simple_task' task type
+# 3. Bundle install completed
+#
+# Usage:
+#   bundle exec ruby examples/simple_worker.rb
+
+require_relative '../lib/conductor'
+
+puts '=' * 60
+puts 'Conductor Ruby SDK - Simple Worker Example'
+puts '=' * 60
+
+# Configure Conductor client
+config = Conductor::Configuration.new(
+  server_api_url: 'http://localhost:7001/api'
+)
+
+puts "\nConnecting to Conductor server at: #{config.server_url}"
+
+# Example 1: Class-based worker
+class SimpleWorker
+  include Conductor::Worker::WorkerModule
+
+  worker_task 'simple_task', poll_interval: 1
+
+  def execute(task)
+    puts "\n[SimpleWorker] Executing task: #{task.task_id}"
+    puts "[SimpleWorker] Input: #{task.input_data.inspect}"
+
+    # Get input
+    name = get_input(task, 'name', 'World')
+
+    # Do some work
+    sleep 0.5
+    result_message = "Hello, #{name}!"
+
+    # Create result
+    result = Conductor::Http::Models::TaskResult.complete
+    result.add_output_data('message', result_message)
+    result.add_output_data('processed_at', Time.now.to_s)
+    result.log("Processed greeting for #{name}")
+
+    puts "[SimpleWorker] Result: #{result_message}"
+    result
+  end
+end
+
+# Example 2: Block-based worker
+math_worker = Conductor::Worker.define('math_task', poll_interval: 1) do |task|
+  puts "\n[MathWorker] Executing task: #{task.task_id}"
+  puts "[MathWorker] Input: #{task.input_data.inspect}"
+
+  a = task.input_data['a'] || 0
+  b = task.input_data['b'] || 0
+  operation = task.input_data['operation'] || 'add'
+
+  result = case operation
+           when 'add' then a + b
+           when 'subtract' then a - b
+           when 'multiply' then a * b
+           when 'divide' then b.zero? ? 'Error: Division by zero' : a / b
+           else 'Unknown operation'
+           end
+
+  puts "[MathWorker] Result: #{a} #{operation} #{b} = #{result}"
+
+  # Return hash - will be converted to TaskResult automatically
+  { result: result, operation: operation }
+end
+
+# Example 3: Worker that can fail
+failing_worker = Conductor::Worker.define('failing_task', poll_interval: 1) do |task|
+  puts "\n[FailingWorker] Executing task: #{task.task_id}"
+
+  should_fail = task.input_data['should_fail']
+
+  if should_fail
+    # Return a failed result
+    result = Conductor::Http::Models::TaskResult.failed('Task failed as requested')
+    result.log('This task was designed to fail')
+    result
+  else
+    # Return success
+    { status: 'success', message: 'Task completed successfully' }
+  end
+end
+
+# Create and configure task runner
+puts "\n[TaskRunner] Creating task runner..."
+runner = Conductor::Worker::TaskRunner.new(config)
+
+# Register workers
+runner.register_worker(SimpleWorker.new)
+runner.register_worker(math_worker)
+runner.register_worker(failing_worker)
+
+puts '[TaskRunner] Registered 3 workers:'
+puts '  - simple_task (class-based)'
+puts '  - math_task (block-based)'
+puts '  - failing_task (block-based)'
+
+# Start the runner
+puts "\n[TaskRunner] Starting worker threads..."
+runner.start(threads: 1)
+
+puts "\nWorkers are now polling for tasks. Press Ctrl+C to stop."
+puts '=' * 60
+
+# Keep the main thread alive and handle Ctrl+C gracefully
+trap('INT') do
+  puts "\n\nReceived interrupt signal..."
+  runner.stop
+  puts 'Workers stopped. Exiting.'
+  exit 0
+end
+
+# Keep running
+sleep while runner.running?

data/examples/simple_workflow.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Simple example demonstrating basic workflow operations with Conductor Ruby SDK
+#
+# Prerequisites:
+# 1. Conductor server running on localhost:7001 (OSS version)
+# 2. Bundle install completed
+#
+# Usage:
+#   bundle exec ruby examples/simple_workflow.rb
+
+require_relative '../lib/conductor'
+
+puts '=' * 60
+puts 'Conductor Ruby SDK - Simple Workflow Example'
+puts '=' * 60
+
+# Configure Conductor client
+config = Conductor::Configuration.new(
+  server_api_url: 'http://localhost:7001/api'
+)
+
+puts "\nConnecting to Conductor server at: #{config.server_url}"
+
+# Create workflow client
+workflow_client = Conductor::Client::WorkflowClient.new(config)
+
+puts 'Workflow client created successfully!'
+
+# Example 1: Start a workflow
+puts "\n[Example 1] Starting a workflow..."
+begin
+  request = Conductor::Http::Models::StartWorkflowRequest.new(
+    name: 'my_workflow',
+    version: 1,
+    input: {
+      'param1' => 'value1',
+      'param2' => 42
+    }
+  )
+
+  workflow_id = workflow_client.start_workflow(request)
+  puts "  ✓ Workflow started with ID: #{workflow_id}"
+
+  # Get workflow status
+  puts "\n[Example 2] Getting workflow status..."
+  workflow = workflow_client.get_workflow(workflow_id)
+  puts "  ✓ Workflow status: #{begin
+    workflow['status']
+  rescue StandardError
+    'N/A'
+  end}"
+rescue Conductor::ApiError => e
+  puts "  ✗ Error: #{e.message}"
+  puts "  Note: Make sure the workflow 'my_workflow' is registered in Conductor"
+end
+
+# Example 3: Using convenience method
+puts "\n[Example 3] Starting workflow with convenience method..."
+begin
+  workflow_id = workflow_client.start(
+    'my_workflow',
+    input: { 'key' => 'value' },
+    correlation_id: 'example-123'
+  )
+  puts "  ✓ Workflow started with ID: #{workflow_id}"
+rescue Conductor::ApiError => e
+  puts "  ✗ Error: #{e.message}"
+end
+
+# Example 4: Task result creation
+puts "\n[Example 4] Creating task results..."
+result = Conductor::Http::Models::TaskResult.complete
+result.add_output_data('result', 'success')
+result.log('Task completed successfully')
+puts "  ✓ Task result created with status: #{result.status}"
+puts "  ✓ Output data: #{result.output_data.inspect}"
+puts "  ✓ Logs: #{result.logs.inspect}"
+
+# Example 5: WorkflowStatus constants
+puts "\n[Example 5] Workflow status constants..."
+puts "  All statuses: #{Conductor::Http::Models::WorkflowStatusConstants::ALL.join(', ')}"
+puts "  Running? #{Conductor::Http::Models::WorkflowStatusConstants.running?('RUNNING')}"
+puts "  Terminal? #{Conductor::Http::Models::WorkflowStatusConstants.terminal?('COMPLETED')}"
+
+puts "\n#{'=' * 60}"
+puts 'Example completed!'
+puts '=' * 60

data/examples/task_context_example.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+#
+# Task Context Example
+#
+# Demonstrates how to use TaskContext to access task information and modify
+# task results during execution.
+#
+# The TaskContext provides:
+# - Access to task metadata (task_id, workflow_id, retry_count, etc.)
+# - Ability to add logs visible in Conductor UI
+# - Ability to set callback delays for polling/retry patterns
+# - Access to input parameters
+#
+# Usage:
+#   ruby examples/task_context_example.rb
+#
+# Environment variables:
+#   CONDUCTOR_SERVER_URL  - Conductor server URL (default: http://localhost:8080/api)
+#   CONDUCTOR_AUTH_KEY    - Authentication key (optional)
+#   CONDUCTOR_AUTH_SECRET - Authentication secret (optional)
+#
+
+require 'bundler/setup'
+require 'conductor'
+
+#
+# Example 1: Basic TaskContext usage - accessing task info
+#
+Conductor::Worker.define('task_info_example', poll_interval: 100, thread_count: 5) do |task|
+  # Get the current task context
+  ctx = Conductor::Worker::TaskContext.current
+
+  # Access task information
+  task_id = ctx.task_id
+  workflow_id = ctx.workflow_instance_id
+  retry_count = ctx.retry_count
+  poll_count = task.poll_count || 0
+
+  puts "Task ID: #{task_id}"
+  puts "Workflow ID: #{workflow_id}"
+  puts "Retry Count: #{retry_count}"
+  puts "Poll Count: #{poll_count}"
+
+  {
+    task_id: task_id,
+    workflow_id: workflow_id,
+    retry_count: retry_count,
+    result: 'processed'
+  }
+end
+
+#
+# Example 2: Adding logs via TaskContext
+#
+Conductor::Worker.define('logging_example', poll_interval: 100, thread_count: 5) do |task|
+  order_id = task.input_data['order_id'] || 'unknown'
+  items = task.input_data['items'] || []
+
+  ctx = Conductor::Worker::TaskContext.current
+
+  # Add logs as processing progresses
+  ctx.add_log("Starting to process order #{order_id}")
+  ctx.add_log("Order has #{items.size} items")
+
+  items.each_with_index do |item, i|
+    sleep(0.1) # Simulate processing
+    ctx.add_log("Processed item #{i + 1}/#{items.size}: #{item}")
+  end
+
+  ctx.add_log('Order processing completed')
+
+  {
+    order_id: order_id,
+    items_processed: items.size,
+    status: 'completed'
+  }
+end
+
+#
+# Example 3: Callback pattern - polling external service
+#
+Conductor::Worker.define('polling_example', poll_interval: 100, thread_count: 10) do |task|
+  job_id = task.input_data['job_id'] || 'unknown'
+
+  ctx = Conductor::Worker::TaskContext.current
+
+  ctx.add_log("Checking status of job #{job_id}")
+
+  # Simulate checking external service
+  is_complete = rand > 0.7 # 30% chance of completion
+
+  if is_complete
+    ctx.add_log("Job #{job_id} is complete!")
+    {
+      job_id: job_id,
+      status: 'completed',
+      result: 'Job finished successfully'
+    }
+  else
+    # Job still running - poll again in 30 seconds
+    ctx.add_log("Job #{job_id} still running, will check again in 30s")
+    ctx.set_callback_after(30)
+
+    Conductor::Worker::TaskInProgress.new(
+      callback_after_seconds: 30,
+      output: {
+        job_id: job_id,
+        status: 'in_progress',
+        message: 'Job still running'
+      }
+    )
+  end
+end
+
+#
+# Example 4: Retry logic with context awareness
+#
+Conductor::Worker.define('retry_aware_example', poll_interval: 100, thread_count: 5) do |task|
+  operation = task.input_data['operation'] || 'default'
+
+  ctx = Conductor::Worker::TaskContext.current
+
+  retry_count = ctx.retry_count
+
+  if retry_count.positive?
+    ctx.add_log("This is retry attempt ##{retry_count}")
+    # Could implement exponential backoff, different logic, etc.
+  end
+
+  ctx.add_log("Executing operation: #{operation}")
+
+  # Simulate operation
+  success = rand > 0.3
+
+  if success
+    ctx.add_log('Operation succeeded')
+    { status: 'success', operation: operation }
+  else
+    ctx.add_log('Operation failed, will retry')
+    raise StandardError, 'Operation failed'
+  end
+end
+
+#
+# Example 5: Accessing input parameters via context
+#
+Conductor::Worker.define('input_access_example', poll_interval: 100, thread_count: 5) do |_task|
+  ctx = Conductor::Worker::TaskContext.current
+
+  # Get all input parameters
+  input_data = ctx.input
+
+  ctx.add_log("Received input parameters: #{input_data.keys}")
+
+  # Process based on input
+  input_data.each do |key, value|
+    ctx.add_log("  #{key} = #{value}")
+  end
+
+  {
+    processed_keys: input_data.keys,
+    input_count: input_data.size
+  }
+end
+
+#
+# Example 6: Long-running task with progress tracking
+#
+Conductor::Worker.define('progress_tracking_example', poll_interval: 100, thread_count: 5) do |task|
+  total_steps = task.input_data['total_steps'] || 5
+
+  ctx = Conductor::Worker::TaskContext.current
+  poll_count = task.poll_count || 0
+
+  ctx.add_log("Progress: step #{poll_count + 1}/#{total_steps}")
+
+  if poll_count < total_steps - 1
+    # Still processing
+    progress = ((poll_count + 1).to_f / total_steps * 100).round
+
+    Conductor::Worker::TaskInProgress.new(
+      callback_after_seconds: 1,
+      output: {
+        current_step: poll_count + 1,
+        total_steps: total_steps,
+        progress_percent: progress,
+        status: 'in_progress'
+      }
+    )
+  else
+    # Complete
+    ctx.add_log('All steps completed!')
+    {
+      current_step: total_steps,
+      total_steps: total_steps,
+      progress_percent: 100,
+      status: 'completed'
+    }
+  end
+end
+
+def main
+  config = Conductor::Configuration.new(
+    server_api_url: ENV.fetch('CONDUCTOR_SERVER_URL', 'http://localhost:8080/api'),
+    auth_key: ENV.fetch('CONDUCTOR_AUTH_KEY', nil),
+    auth_secret: ENV.fetch('CONDUCTOR_AUTH_SECRET', nil)
+  )
+
+  puts '=' * 60
+  puts 'Conductor TaskContext Examples'
+  puts '=' * 60
+  puts
+  puts 'Workers demonstrating TaskContext usage:'
+  puts '  - task_info_example      - Access task metadata'
+  puts '  - logging_example        - Add logs to task'
+  puts '  - polling_example        - Use callback_after for polling'
+  puts '  - retry_aware_example    - Handle retries intelligently'
+  puts '  - input_access_example   - Access task input via context'
+  puts '  - progress_tracking_example - Track progress across polls'
+  puts
+  puts 'Key TaskContext Features:'
+  puts '  - Access task metadata (ID, workflow ID, retry count)'
+  puts '  - Add logs visible in Conductor UI'
+  puts '  - Set callback delays for polling patterns'
+  puts '  - Thread-safe via Thread.current'
+  puts '=' * 60
+  puts
+  puts 'Starting workers... Press Ctrl+C to stop'
+  puts
+
+  begin
+    handler = Conductor::Worker::TaskHandler.new(
+      configuration: config,
+      scan_for_annotated_workers: true
+    )
+
+    shutdown = false
+    Signal.trap('INT') do
+      puts "\nShutting down gracefully..."
+      shutdown = true
+      handler.stop
+    end
+
+    handler.start
+    handler.join unless shutdown
+  rescue Interrupt
+    puts 'Interrupted!'
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+  end
+
+  puts "\nWorkers stopped. Goodbye!"
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/task_listener_example.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+#
+# Example demonstrating TaskRunnerEventsListener for pre/post processing of worker tasks.
+#
+# This example shows how to implement a custom event listener to:
+# - Log task execution events
+# - Add custom headers or context before task execution
+# - Process task results after execution
+# - Track task timing and errors
+# - Implement retry logic or custom error handling
+#
+# The listener pattern is useful for:
+# - Request/response logging
+# - Distributed tracing integration
+# - Custom metrics collection
+# - Authentication/authorization
+# - Data enrichment
+# - Error recovery
+#
+# Usage:
+#   ruby task_listener_example.rb
+#
+# Environment variables:
+#   CONDUCTOR_SERVER_URL - Conductor server URL (default: http://localhost:8080/api)
+#   CONDUCTOR_AUTH_KEY   - Authentication key (optional)
+#   CONDUCTOR_AUTH_SECRET - Authentication secret (optional)
+#
+
+require 'bundler/setup'
+require 'conductor'
+require_relative 'event_listener_examples'
+
+# Configure logging
+logger = Logger.new($stdout)
+logger.level = Logger::INFO
+logger.formatter = proc do |severity, datetime, _progname, msg|
+  "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity} -- #{msg}\n"
+end
+
+#
+# Example worker tasks
+#
+
+# Simple calculator worker
+Conductor::Worker.define('calculate', poll_interval: 100, thread_count: 5) do |task|
+  n = task.input_data['n'] || 10
+
+  # Fibonacci calculation (demonstrates CPU-bound work)
+  fib = ->(x) { x <= 1 ? x : fib.call(x - 1) + fib.call(x - 2) }
+  result = fib.call(n)
+
+  { fibonacci: result, input: n }
+end
+
+# Long-running task with progress tracking
+Conductor::Worker.define('long_running_task', poll_interval: 100, thread_count: 3) do |task|
+  job_id = task.input_data['job_id'] || 'unknown'
+
+  # Access task context for poll count
+  ctx = Conductor::Worker::TaskContext.current
+  poll_count = task.poll_count || 0
+
+  ctx.add_log("Processing job #{job_id}, poll #{poll_count}/5")
+
+  if poll_count < 5
+    # Still processing - return TaskInProgress
+    Conductor::Worker::TaskInProgress.new(
+      callback_after_seconds: 1,
+      output: {
+        job_id: job_id,
+        status: 'processing',
+        poll_count: poll_count,
+        progress: poll_count * 20,
+        message: "Working on job #{job_id}, poll #{poll_count}/5"
+      }
+    )
+  else
+    # Complete after 5 polls
+    ctx.add_log("Job #{job_id} completed")
+    {
+      job_id: job_id,
+      status: 'completed',
+      result: 'success',
+      total_time_seconds: 5,
+      total_polls: poll_count
+    }
+  end
+end
+
+# Worker that simulates failures for testing error handling
+Conductor::Worker.define('flaky_worker', poll_interval: 100, thread_count: 2) do |task|
+  fail_rate = task.input_data['fail_rate'] || 0.3
+
+  raise StandardError, 'Random failure for testing' if rand < fail_rate
+
+  { status: 'success', fail_rate: fail_rate }
+end
+
+def main
+  # Configure Conductor connection
+  config = Conductor::Configuration.new(
+    server_api_url: ENV['CONDUCTOR_SERVER_URL'] || 'http://localhost:8080/api',
+    auth_key: ENV.fetch('CONDUCTOR_AUTH_KEY', nil),
+    auth_secret: ENV.fetch('CONDUCTOR_AUTH_SECRET', nil)
+  )
+
+  # Create event listeners
+  logger_listener = TaskExecutionLogger.new
+  timing_tracker = TaskTimingTracker.new
+  tracing_listener = DistributedTracingListener.new
+  error_tracker = ErrorTrackingListener.new(
+    alert_threshold: 3,
+    alert_callback: ->(alert) { puts "[ALERT CALLBACK] #{alert.inspect}" }
+  )
+
+  puts '=' * 80
+  puts 'TaskRunnerEventsListener Example'
+  puts '=' * 80
+  puts
+  puts 'This example demonstrates event listeners for task pre/post processing:'
+  puts '  1. TaskExecutionLogger - Logs all task lifecycle events'
+  puts '  2. TaskTimingTracker - Tracks and reports execution statistics'
+  puts '  3. DistributedTracingListener - Simulates distributed tracing'
+  puts '  4. ErrorTrackingListener - Aggregates errors and alerts'
+  puts
+  puts 'Workers available:'
+  puts '  - calculate: Fibonacci calculator'
+  puts '  - long_running_task: Multi-poll task with progress tracking'
+  puts '  - flaky_worker: Random failure simulation'
+  puts
+  puts 'Press Ctrl+C to stop...'
+  puts '=' * 80
+  puts
+
+  begin
+    # Create task handler with multiple listeners
+    handler = Conductor::Worker::TaskHandler.new(
+      configuration: config,
+      scan_for_annotated_workers: true,
+      event_listeners: [
+        logger_listener,
+        timing_tracker,
+        tracing_listener,
+        error_tracker
+      ]
+    )
+
+    # Handle graceful shutdown
+    shutdown = false
+    Signal.trap('INT') do
+      puts "\nShutting down gracefully..."
+      shutdown = true
+      handler.stop
+    end
+
+    handler.start
+
+    # Print statistics periodically
+    Thread.new do
+      loop do
+        sleep 30
+        break if shutdown
+
+        puts "\n--- Statistics ---"
+        timing_tracker.all_stats.each do |task_type, stats|
+          puts "#{task_type}: #{stats.inspect}"
+        end
+
+        error_summary = error_tracker.error_summary
+        puts "Errors: #{error_summary.inspect}" unless error_summary.empty?
+        puts '------------------\n'
+      end
+    end
+
+    handler.join unless shutdown
+  rescue Interrupt
+    puts 'Interrupted!'
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+  end
+
+  puts "\nFinal Statistics:"
+  timing_tracker.all_stats.each do |task_type, stats|
+    puts "  #{task_type}: #{stats.inspect}"
+  end
+
+  puts "\nWorkers stopped. Goodbye!"
+end
+
+main if __FILE__ == $PROGRAM_NAME