conductor_ruby 0.1.0

data/examples/worker_configuration_example.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+#
+# Worker Configuration Example
+#
+# Demonstrates hierarchical worker configuration using environment variables.
+#
+# This example shows how to override worker settings at deployment time without
+# changing code, using a three-tier configuration hierarchy:
+#
+# 1. Code-level defaults (lowest priority)
+# 2. Global worker config: CONDUCTOR_WORKER_ALL_<PROPERTY>
+# 3. Worker-specific config: CONDUCTOR_WORKER_<WORKER_NAME>_<PROPERTY>
+#
+# Usage:
+#   # Run with code defaults
+#   ruby worker_configuration_example.rb
+#
+#   # Run with global overrides
+#   export CONDUCTOR_WORKER_ALL_DOMAIN=production
+#   export CONDUCTOR_WORKER_ALL_POLL_INTERVAL=250
+#   ruby worker_configuration_example.rb
+#
+#   # Run with worker-specific overrides
+#   export CONDUCTOR_WORKER_ALL_DOMAIN=production
+#   export CONDUCTOR_WORKER_CRITICAL_TASK_THREAD_COUNT=20
+#   export CONDUCTOR_WORKER_CRITICAL_TASK_POLL_INTERVAL=100
+#   ruby worker_configuration_example.rb
+#
+
+require 'bundler/setup'
+require 'conductor'
+
+#
+# Example 1: Standard worker with default configuration
+#
+Conductor::Worker.define(
+  'process_order',
+  poll_interval: 1000,
+  domain: 'dev',
+  thread_count: 5,
+  poll_timeout: 100
+) do |task|
+  order_id = task.input_data['order_id'] || 'unknown'
+  {
+    status: 'processed',
+    order_id: order_id,
+    worker_type: 'standard'
+  }
+end
+
+#
+# Example 2: High-priority worker that might need more resources in production
+#
+Conductor::Worker.define(
+  'critical_task',
+  poll_interval: 1000,
+  domain: 'dev',
+  thread_count: 5,
+  poll_timeout: 100
+) do |task|
+  task_id = task.input_data['task_id'] || 'unknown'
+  {
+    status: 'completed',
+    task_id: task_id,
+    priority: 'critical'
+  }
+end
+
+#
+# Example 3: Background worker that can run with fewer resources
+#
+Conductor::Worker.define(
+  'background_task',
+  poll_interval: 2000,
+  domain: 'dev',
+  thread_count: 2,
+  poll_timeout: 200
+) do |task|
+  job_id = task.input_data['job_id'] || 'unknown'
+  {
+    status: 'completed',
+    job_id: job_id,
+    priority: 'low'
+  }
+end
+
+def print_configuration_examples
+  puts
+  puts '=' * 80
+  puts 'Worker Configuration Hierarchy Examples'
+  puts '=' * 80
+
+  # Show current environment variables
+  puts
+  puts 'Current Environment Variables:'
+  env_vars = ENV.select { |k, _| k.start_with?('CONDUCTOR_WORKER') }
+  if env_vars.any?
+    env_vars.sort.each { |key, value| puts "  #{key} = #{value}" }
+  else
+    puts '  (No CONDUCTOR_WORKER_* environment variables set)'
+  end
+
+  puts
+  puts '-' * 80
+
+  # Example 1: process_order configuration
+  puts
+  puts '1. Standard Worker (process_order):'
+  puts "   Code defaults: poll_interval=1000, domain='dev', thread_count=5"
+
+  config1 = Conductor::Worker::WorkerConfig.resolve(
+    'process_order',
+    poll_interval: 1000,
+    domain: 'dev',
+    thread_count: 5,
+    poll_timeout: 100
+  )
+  puts
+  puts '   Resolved configuration:'
+  puts "     poll_interval: #{config1[:poll_interval]}"
+  puts "     domain: #{config1[:domain]}"
+  puts "     thread_count: #{config1[:thread_count]}"
+  puts "     poll_timeout: #{config1[:poll_timeout]}"
+
+  # Example 2: critical_task configuration
+  puts
+  puts '2. Critical Worker (critical_task):'
+  puts "   Code defaults: poll_interval=1000, domain='dev', thread_count=5"
+
+  config2 = Conductor::Worker::WorkerConfig.resolve(
+    'critical_task',
+    poll_interval: 1000,
+    domain: 'dev',
+    thread_count: 5,
+    poll_timeout: 100
+  )
+  puts
+  puts '   Resolved configuration:'
+  puts "     poll_interval: #{config2[:poll_interval]}"
+  puts "     domain: #{config2[:domain]}"
+  puts "     thread_count: #{config2[:thread_count]}"
+  puts "     poll_timeout: #{config2[:poll_timeout]}"
+
+  # Example 3: background_task configuration
+  puts
+  puts '3. Background Worker (background_task):'
+  puts "   Code defaults: poll_interval=2000, domain='dev', thread_count=2"
+
+  config3 = Conductor::Worker::WorkerConfig.resolve(
+    'background_task',
+    poll_interval: 2000,
+    domain: 'dev',
+    thread_count: 2,
+    poll_timeout: 200
+  )
+  puts
+  puts '   Resolved configuration:'
+  puts "     poll_interval: #{config3[:poll_interval]}"
+  puts "     domain: #{config3[:domain]}"
+  puts "     thread_count: #{config3[:thread_count]}"
+  puts "     poll_timeout: #{config3[:poll_timeout]}"
+
+  puts
+  puts '-' * 80
+  puts
+  puts 'Configuration Priority: Worker-specific > Global > Code defaults'
+  puts
+  puts 'Example Environment Variables:'
+  puts '  # Global override (all workers)'
+  puts '  export CONDUCTOR_WORKER_ALL_DOMAIN=production'
+  puts '  export CONDUCTOR_WORKER_ALL_POLL_INTERVAL=250'
+  puts
+  puts '  # Worker-specific override (only critical_task)'
+  puts '  export CONDUCTOR_WORKER_CRITICAL_TASK_THREAD_COUNT=20'
+  puts '  export CONDUCTOR_WORKER_CRITICAL_TASK_POLL_INTERVAL=100'
+  puts
+  puts '=' * 80
+  puts
+end
+
+def print_configuration_properties
+  puts
+  puts '=' * 80
+  puts 'Available Configuration Properties'
+  puts '=' * 80
+  puts
+  puts 'Property             Type      Default    Description'
+  puts '-' * 80
+  puts 'poll_interval        Integer   100        Polling interval in milliseconds'
+  puts 'thread_count         Integer   1          Max concurrent tasks per worker'
+  puts 'domain               String    nil        Task domain for isolation'
+  puts 'worker_id            String    auto       Unique worker identifier'
+  puts 'poll_timeout         Integer   100        Server-side long poll timeout (ms)'
+  puts 'register_task_def    Boolean   false      Auto-register task definition'
+  puts 'paused               Boolean   false      Pause worker (stop polling)'
+  puts
+  puts '=' * 80
+  puts
+end
+
+def main
+  print_configuration_examples
+  print_configuration_properties
+
+  puts 'Configuration resolution complete!'
+  puts
+  puts 'To see different configurations, try setting environment variables:'
+  puts
+  puts '  # Test global override:'
+  puts '  export CONDUCTOR_WORKER_ALL_POLL_INTERVAL=500'
+  puts '  ruby worker_configuration_example.rb'
+  puts
+  puts '  # Test worker-specific override:'
+  puts '  export CONDUCTOR_WORKER_CRITICAL_TASK_THREAD_COUNT=20'
+  puts '  ruby worker_configuration_example.rb'
+  puts
+  puts '  # Test production-like scenario:'
+  puts '  export CONDUCTOR_WORKER_ALL_DOMAIN=production'
+  puts '  export CONDUCTOR_WORKER_ALL_POLL_INTERVAL=250'
+  puts '  export CONDUCTOR_WORKER_CRITICAL_TASK_THREAD_COUNT=50'
+  puts '  export CONDUCTOR_WORKER_CRITICAL_TASK_POLL_INTERVAL=50'
+  puts '  ruby worker_configuration_example.rb'
+  puts
+  puts '-' * 80
+  puts
+  puts 'To actually run workers with the resolved configuration:'
+  puts
+  puts '  # Set configuration and run workers'
+  puts '  export CONDUCTOR_SERVER_URL=http://localhost:8080/api'
+  puts '  export CONDUCTOR_WORKER_ALL_DOMAIN=production'
+  puts '  ruby worker_configuration_example.rb --run'
+  puts
+
+  # Check if --run flag is passed
+  return unless ARGV.include?('--run')
+
+  puts
+  puts '=' * 80
+  puts 'Running Workers with Resolved Configuration'
+  puts '=' * 80
+  puts
+
+  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)
+  )
+
+  begin
+    handler = Conductor::Worker::TaskHandler.new(
+      configuration: config,
+      scan_for_annotated_workers: true
+    )
+
+    shutdown = false
+    Signal.trap('INT') do
+      puts "\nShutting down..."
+      shutdown = true
+      handler.stop
+    end
+
+    puts 'Workers:'
+    handler.worker_names.each do |name|
+      puts "  - #{name}"
+    end
+    puts
+    puts 'Press Ctrl+C to stop...'
+    puts
+
+    handler.start
+    handler.join unless shutdown
+  rescue Interrupt
+    puts 'Interrupted!'
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+  end
+
+  puts 'Workers stopped.'
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/examples/workflow_dsl.rb

@@ -0,0 +1,316 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Using the Conductor Ruby SDK Workflow DSL
+#
+# This example demonstrates how to define workflows programmatically using
+# the new Ruby-idiomatic DSL, which provides a clean and expressive way to build workflows.
+#
+# Key Features:
+# - Method-per-type: simple(), http(), wait(), terminate(), etc.
+# - Auto-generated reference names
+# - Hash-style [] for output references: task[:field]
+# - wf[:param] for workflow inputs
+# - Block-based control flow: parallel, decide, loop_times
+#
+# Run with: bundle exec ruby examples/workflow_dsl.rb
+
+require_relative '../lib/conductor'
+
+puts '=' * 70
+puts 'Conductor Ruby SDK - New DSL Examples'
+puts '=' * 70
+puts
+
+# ============================================================================
+# Example 1: Simple Sequential Workflow
+# ============================================================================
+puts '=== Example 1: Simple Sequential Workflow ==='
+
+simple_workflow = Conductor.workflow :ruby_simple_workflow, version: 1 do
+  description 'A simple sequential workflow created with the new Ruby DSL'
+  timeout 3600
+  owner_email 'developer@example.com'
+
+  # Tasks are created with simple method calls
+  # wf[:userName] returns "${workflow.input.userName}"
+  greet = simple :greet_user, name: wf[:userName]
+
+  # Reference previous task outputs with task[:field]
+  # greet[:message] returns "${greet_user_ref.output.message}"
+  process = simple :process_greeting, greeting: greet[:message]
+
+  # Set workflow output
+  output result: process[:result]
+end
+
+puts "Workflow: #{simple_workflow.name}"
+puts "Tasks: #{simple_workflow.builder.tasks.size}"
+puts
+
+# ============================================================================
+# Example 2: Parallel Execution
+# ============================================================================
+puts '=== Example 2: Parallel Execution ==='
+
+parallel_workflow = Conductor.workflow :ruby_parallel_workflow, version: 1 do
+  description 'Workflow with parallel task execution'
+  timeout 300
+
+  # Initial task
+  fetch = simple :fetch_data, source: wf[:dataSource]
+
+  # Parallel block - tasks execute concurrently
+  parallel do
+    simple :process_type_a, data: fetch[:data]
+    simple :process_type_b, data: fetch[:data]
+  end
+
+  # Aggregation after parallel tasks complete
+  # Note: Access parallel outputs via the specific task ref names
+  aggregate = simple :aggregate_results,
+                     result_a: '${process_type_a_ref.output.result}',
+                     result_b: '${process_type_b_ref.output.result}'
+
+  output combined: aggregate[:result]
+end
+
+puts "Workflow: #{parallel_workflow.name}"
+puts "Task count: #{parallel_workflow.builder.tasks.size} (includes fork/join)"
+puts
+
+# ============================================================================
+# Example 3: Conditional Branching with Switch
+# ============================================================================
+puts '=== Example 3: Conditional Branching with Switch ==='
+
+conditional_workflow = Conductor.workflow :ruby_conditional_workflow, version: 1 do
+  description 'Workflow with conditional branching'
+
+  # Classification task
+  classify = simple :classify_request, request: wf[:request]
+
+  # Switch based on the classification output
+  decide classify[:requestType] do
+    on 'TYPE_A' do
+      simple :handle_type_a, data: classify[:data]
+    end
+
+    on 'TYPE_B' do
+      simple :handle_type_b, data: classify[:data]
+    end
+
+    otherwise do
+      simple :handle_default, data: classify[:data]
+    end
+  end
+
+  output status: 'completed'
+end
+
+puts "Workflow: #{conditional_workflow.name}"
+puts 'Switch cases: TYPE_A, TYPE_B, default'
+puts
+
+# ============================================================================
+# Example 4: HTTP Task
+# ============================================================================
+puts '=== Example 4: HTTP Task ==='
+
+http_workflow = Conductor.workflow :ruby_http_workflow, version: 1 do
+  description 'Workflow with HTTP calls'
+
+  # HTTP task with dynamic URL from workflow input
+  api_call = http :call_api,
+                  url: 'https://api.example.com/users/${workflow.input.userId}',
+                  method: :get,
+                  headers: { 'Authorization' => 'Bearer ${workflow.input.token}' }
+
+  # Process the response
+  process = simple :process_response,
+                   status_code: api_call[:statusCode],
+                   body: api_call[:body]
+
+  output result: process[:result]
+end
+
+puts "Workflow: #{http_workflow.name}"
+puts 'HTTP endpoint: api.example.com/users'
+puts
+
+# ============================================================================
+# Example 5: Sub-Workflow Task
+# ============================================================================
+puts '=== Example 5: Sub-Workflow Task ==='
+
+parent_workflow = Conductor.workflow :ruby_parent_workflow, version: 1 do
+  description 'Parent workflow that calls a sub-workflow'
+
+  prepare = simple :prepare_data, input: wf[:data]
+
+  # Call an existing workflow as a sub-workflow
+  child_result = sub_workflow :call_child,
+                              workflow: 'child_workflow_name',
+                              version: 1,
+                              data: prepare[:preparedData]
+
+  process = simple :process_child_result, child_output: child_result[:output]
+
+  output final_result: process[:result]
+end
+
+puts "Workflow: #{parent_workflow.name}"
+puts 'Calls sub-workflow: child_workflow_name'
+puts
+
+# ============================================================================
+# Example 6: Loop with Times
+# ============================================================================
+puts '=== Example 6: Loop with Times ==='
+
+loop_workflow = Conductor.workflow :ruby_loop_workflow, version: 1 do
+  description 'Workflow with loop iteration'
+
+  init = simple :initialize, count: 0
+
+  # Loop 3 times
+  loop_times 3 do
+    simple :process_batch, iteration: '${do_while_ref.output.iteration}'
+  end
+
+  finalize = simple :finalize, batches_processed: 3
+
+  output result: finalize[:summary]
+end
+
+puts "Workflow: #{loop_workflow.name}"
+puts 'Loops 3 times'
+puts
+
+# ============================================================================
+# Example 7: Inline Workflow Definition
+# ============================================================================
+puts '=== Example 7: Inline Workflow ==='
+
+inline_demo = Conductor.workflow :ruby_inline_workflow, version: 1 do
+  description 'Workflow with inline sub-workflow'
+
+  start = simple :start_processing, data: wf[:input_data]
+
+  # Define a sub-workflow inline
+  inline_workflow :process_order, version: 1 do
+    validate = simple :validate_order
+    simple :charge_payment, amount: validate[:total]
+    simple :ship_order
+  end
+
+  complete = simple :complete_processing
+
+  output status: 'done'
+end
+
+puts "Workflow: #{inline_demo.name}"
+puts 'Contains inline sub-workflow'
+puts
+
+# ============================================================================
+# Example 8: Wait and Human Tasks
+# ============================================================================
+puts '=== Example 8: Wait and Human Tasks ==='
+
+approval_workflow = Conductor.workflow :ruby_approval_workflow, version: 1 do
+  description 'Workflow with wait and human tasks'
+
+  submit = simple :submit_request, request: wf[:request]
+
+  # Human task for approval
+  approval = human :manager_approval,
+                   assignee: wf[:manager_email],
+                   display_name: 'Approve Request'
+
+  # Conditional based on approval
+  decide approval[:decision] do
+    on 'approved' do
+      simple :process_approved
+    end
+
+    on 'rejected' do
+      terminate :failed, 'Request rejected by manager'
+    end
+
+    otherwise do
+      # Wait for escalation
+      wait 86_400 # 24 hours
+      simple :escalate_request
+    end
+  end
+
+  output status: 'completed'
+end
+
+puts "Workflow: #{approval_workflow.name}"
+puts 'Includes human task and wait'
+puts
+
+# ============================================================================
+# Example 9: Complete Workflow with All Features
+# ============================================================================
+puts '=== Example 9: Complete Example Workflow ==='
+
+complete_workflow = Conductor.workflow :ruby_complete_example, version: 1 do
+  description 'Complete example workflow demonstrating all features'
+  timeout 7200
+  owner_email 'team@example.com'
+
+  # Initialize
+  init = simple :initialize, user_id: wf[:userId]
+
+  # Validate
+  validate = simple :validate_input, data: init[:output]
+
+  # Process
+  process = simple :process_action, validated_data: validate[:output]
+
+  # Notify
+  notify = simple :notify_user,
+                  user_id: wf[:userId],
+                  result: process[:result]
+
+  # Set output parameters
+  output(
+    status: notify[:status],
+    completed_at: notify[:timestamp]
+  )
+end
+
+# Convert to workflow definition (for inspection)
+workflow_def = complete_workflow.to_workflow_def
+puts "Workflow: #{complete_workflow.name}"
+puts "Version: #{workflow_def.version}"
+puts "Task count: #{workflow_def.tasks.length}"
+puts "Timeout: #{workflow_def.timeout_seconds} seconds"
+puts
+
+# ============================================================================
+# Summary
+# ============================================================================
+puts '=' * 70
+puts 'Examples completed!'
+puts '=' * 70
+puts
+puts 'New DSL Features Demonstrated:'
+puts '  - Conductor.workflow :name do...end - Entry point'
+puts '  - simple, http, wait, terminate, sub_workflow, human - Task methods'
+puts '  - parallel do...end - Concurrent execution'
+puts '  - decide expr do...end - Conditional branching'
+puts '  - loop_times N do...end - Loop iteration'
+puts '  - inline_workflow :name do...end - Inline sub-workflows'
+puts '  - wf[:param] - Workflow input references'
+puts '  - task[:field] - Task output references'
+puts '  - output key: value - Workflow output'
+puts
+puts 'To run workflows against a Conductor server:'
+puts '  1. Set CONDUCTOR_SERVER_URL environment variable'
+puts '  2. Add executor: parameter to Conductor.workflow'
+puts '  3. Call workflow.register(overwrite: true)'
+puts '  4. Call workflow.execute(input: { ... })'