conductor_ruby 0.1.0

data/examples/dynamic_workflow.rb

@@ -0,0 +1,177 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Dynamic Workflow Example
+# =========================
+#
+# Demonstrates creating and executing workflows at runtime without pre-registration.
+#
+# What it does:
+# -------------
+# - Creates a workflow programmatically using Ruby code
+# - Defines two workers: get_user_email and send_email
+# - Chains tasks together using the >> operator
+# - Executes the workflow with input data
+#
+# Use Cases:
+# ----------
+# - Workflows that cannot be defined statically (structure depends on runtime data)
+# - Programmatic workflow generation based on business rules
+# - Testing workflows without registering definitions
+# - Rapid prototyping and development
+#
+# Key Concepts:
+# -------------
+# - ConductorWorkflow: Build workflows in code
+# - Task chaining: Use >> operator to define task sequence
+# - Dynamic execution: Create and run workflows on-the-fly
+# - Worker tasks: Ruby methods/blocks that execute task logic
+#
+# Usage:
+#   bundle exec ruby examples/dynamic_workflow.rb
+#
+# Prerequisites:
+#   - Conductor server running (set CONDUCTOR_SERVER_URL)
+#   - For Orkes: Set CONDUCTOR_AUTH_KEY and CONDUCTOR_AUTH_SECRET
+
+require_relative '../lib/conductor'
+
+# Include workflow DSL for shorter class names
+include Conductor::Workflow
+
+# ============================================================================
+# WORKERS - Define task implementations
+# ============================================================================
+
+# Worker 1: Get user email by user ID
+class GetUserEmailWorker
+  include Conductor::Worker::WorkerModule
+
+  worker_task 'get_user_email'
+
+  def execute(task)
+    userid = get_input(task, 'userid', 'unknown')
+    email = "#{userid}@example.com"
+
+    puts "[GetUserEmailWorker] Generated email for userid=#{userid}: #{email}"
+
+    # Return the email as output
+    { 'result' => email }
+  end
+end
+
+# Worker 2: Send email
+class SendEmailWorker
+  include Conductor::Worker::WorkerModule
+
+  worker_task 'send_email'
+
+  def execute(task)
+    email = get_input(task, 'email', '')
+    subject = get_input(task, 'subject', 'No Subject')
+    body = get_input(task, 'body', '')
+
+    puts "[SendEmailWorker] Sending email to #{email}"
+    puts "  Subject: #{subject}"
+    puts "  Body: #{body}"
+
+    # Simulate sending email
+    { 'status' => 'sent', 'to' => email }
+  end
+end
+
+def main
+  # Configuration from environment variables
+  # CONDUCTOR_SERVER_URL: Conductor server URL (e.g., https://developer.orkescloud.com/api)
+  # CONDUCTOR_AUTH_KEY: API Authentication Key (optional for OSS)
+  # CONDUCTOR_AUTH_SECRET: API Auth Secret (optional for OSS)
+  config = Conductor::Configuration.new
+
+  puts '=' * 70
+  puts 'Conductor Ruby SDK - Dynamic Workflow Example'
+  puts '=' * 70
+  puts
+  puts "Server: #{config.server_url}"
+  puts
+
+  # Create clients using OrkesClients factory
+  clients = Conductor::Orkes::OrkesClients.new(config)
+  workflow_executor = clients.get_workflow_executor
+
+  # Start workers in the background
+  task_handler = Conductor::Worker::TaskRunner.new(config)
+  task_handler.register_worker(GetUserEmailWorker.new)
+  task_handler.register_worker(SendEmailWorker.new)
+  task_handler.start
+
+  puts 'Workers started...'
+  puts
+
+  # ============================================================================
+  # BUILD WORKFLOW DYNAMICALLY
+  # ============================================================================
+
+  # Create workflow with executor for dynamic execution
+  workflow = ConductorWorkflow.new(
+    clients.get_workflow_client,
+    'dynamic_workflow_ruby',
+    version: 1,
+    executor: workflow_executor
+  )
+
+  # Define tasks
+  # Task 1: Get user email - uses workflow input for userid
+  get_email = SimpleTask.new('get_user_email', 'get_user_email_ref')
+                        .input('userid', workflow.input('userid'))
+
+  # Task 2: Send email - uses output from get_email task
+  sendmail = SimpleTask.new('send_email', 'send_email_ref')
+                       .input('email', get_email.output('result'))
+                       .input('subject', 'Hello from Conductor Ruby SDK')
+                       .input('body', 'This is a test email from a dynamic workflow')
+
+  # Chain tasks: workflow >> task1 >> task2
+  workflow >> get_email >> sendmail
+
+  # Configure the output of the workflow
+  workflow.output_parameter('email', get_email.output('result'))
+
+  # ============================================================================
+  # EXECUTE WORKFLOW
+  # ============================================================================
+
+  puts 'Executing dynamic workflow...'
+  puts
+
+  # Execute workflow synchronously with input
+  workflow_run = workflow.execute(
+    input: { 'userid' => 'user_a' },
+    wait_for_seconds: 30
+  )
+
+  puts
+  puts 'Workflow completed!'
+  puts '-' * 70
+  puts "Workflow ID: #{workflow_run.workflow_id}"
+  puts "Status: #{workflow_run.status}"
+  puts "Output: #{workflow_run.output.inspect}"
+  puts
+  puts "Check the workflow execution at: #{config.ui_host}/execution/#{workflow_run.workflow_id}"
+
+  # Stop workers
+  task_handler.stop
+  puts
+  puts 'Workers stopped. Goodbye!'
+end
+
+if __FILE__ == $PROGRAM_NAME
+  begin
+    main
+  rescue Conductor::ApiError => e
+    puts "API Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+  end
+end

data/examples/event_handler.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Event Handler Example
+#
+# Demonstrates creating and managing event handlers that trigger
+# workflows based on external events.
+#
+# Usage:
+#   bundle exec ruby examples/event_handler.rb
+
+require_relative '../lib/conductor'
+
+def main
+  config = Conductor::Configuration.new
+  api_client = Conductor::Http::ApiClient.new(configuration: config)
+  event_api = Conductor::Http::Api::EventResourceApi.new(api_client)
+
+  puts '=' * 70
+  puts 'Event Handler Example'
+  puts '=' * 70
+  puts "Server: #{config.server_url}"
+  puts
+
+  handler_name = "ruby_order_event_handler_#{Time.now.to_i}"
+
+  # Create an event handler
+  event_handler = {
+    'name' => handler_name,
+    'event' => 'order:created',
+    'actions' => [
+      {
+        'action' => 'start_workflow',
+        'start_workflow' => {
+          'name' => 'process_order_workflow',
+          'version' => 1,
+          'input' => {
+            'orderId' => '${event.orderId}',
+            'customerId' => '${event.customerId}'
+          }
+        }
+      }
+    ],
+    'active' => true
+  }
+
+  begin
+    # Add event handler
+    puts "Creating event handler: #{handler_name}"
+    event_api.add_event_handler(event_handler)
+    puts 'Event handler created!'
+
+    # Get all event handlers
+    handlers = event_api.get_event_handlers
+    puts "\nAll event handlers (#{handlers.length} total):"
+    handlers.first(5).each do |h|
+      name = h.is_a?(Hash) ? h['name'] : h.name
+      puts "  - #{name}"
+    end
+
+    # Get handlers for specific event
+    puts "\nHandlers for 'order:created' event:"
+    begin
+      order_handlers = event_api.get_event_handlers_for_event('order:created', true)
+      order_handlers.each do |h|
+        name = h.is_a?(Hash) ? h['name'] : h.name
+        puts "  - #{name}"
+      end
+    rescue StandardError => e
+      puts "  Could not fetch: #{e.message}"
+    end
+  ensure
+    # Cleanup
+    puts "\nDeleting event handler..."
+    begin
+      event_api.remove_event_handler(handler_name)
+      puts 'Event handler deleted'
+    rescue StandardError => e
+      puts "Could not delete: #{e.message}"
+    end
+  end
+
+  puts "\nEvent handler example complete!"
+end
+
+if __FILE__ == $PROGRAM_NAME
+  begin
+    main
+  rescue Conductor::ApiError => e
+    puts "API Error: #{e.message}"
+  rescue StandardError => e
+    puts "Error: #{e.message}"
+  end
+end

data/examples/event_listener_examples.rb

@@ -0,0 +1,430 @@
+# frozen_string_literal: true
+
+#
+# Reusable event listener examples for TaskRunnerEventsListener.
+#
+# This module provides example event listener implementations that can be used
+# in any application to monitor and track task execution.
+#
+# Available Listeners:
+#   - TaskExecutionLogger: Simple logging of all task lifecycle events
+#   - TaskTimingTracker: Statistical tracking of task execution times
+#   - DistributedTracingListener: Simulated distributed tracing integration
+#   - ErrorTrackingListener: Error aggregation and alerting
+#
+# Usage:
+#   require_relative 'event_listener_examples'
+#
+#   handler = Conductor::Worker::TaskHandler.new(
+#     configuration: config,
+#     event_listeners: [
+#       TaskExecutionLogger.new,
+#       TaskTimingTracker.new
+#     ]
+#   )
+#   handler.start
+#   handler.join
+#
+
+require 'logger'
+require 'conductor'
+
+# Simple listener that logs all task execution events.
+#
+# Demonstrates basic pre/post processing:
+# - on_task_execution_started: Pre-processing before task executes
+# - on_task_execution_completed: Post-processing after successful execution
+# - on_task_execution_failure: Error handling after failed execution
+#
+class TaskExecutionLogger
+  def initialize(logger: nil)
+    @logger = logger || Logger.new($stdout)
+    @logger.formatter = proc do |severity, datetime, _progname, msg|
+      "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity} -- #{msg}\n"
+    end
+  end
+
+  # Called before task execution begins (pre-processing).
+  #
+  # Use this for:
+  # - Setting up context (tracing, logging context)
+  # - Validating preconditions
+  # - Starting timers
+  # - Recording audit events
+  #
+  def on_task_execution_started(event)
+    @logger.info("[PRE] Starting task '#{event.task_type}' " \
+                 "(task_id=#{event.task_id}, worker=#{event.worker_id})")
+  end
+
+  # Called after task execution completes successfully (post-processing).
+  #
+  # Use this for:
+  # - Logging results
+  # - Sending notifications
+  # - Updating external systems
+  # - Recording metrics
+  #
+  def on_task_execution_completed(event)
+    @logger.info("[POST] Completed task '#{event.task_type}' " \
+                 "(task_id=#{event.task_id}, duration=#{event.duration_ms.round(2)}ms, " \
+                 "output_size=#{event.output_size_bytes || 0} bytes)")
+  end
+
+  # Called when task execution fails (error handling).
+  #
+  # Use this for:
+  # - Error logging
+  # - Alerting
+  # - Retry logic
+  # - Cleanup operations
+  #
+  def on_task_execution_failure(event)
+    @logger.error("[ERROR] Failed task '#{event.task_type}' " \
+                  "(task_id=#{event.task_id}, duration=#{event.duration_ms.round(2)}ms, " \
+                  "error=#{event.cause.class}: #{event.cause.message})")
+  end
+
+  # Called when polling for tasks begins.
+  def on_poll_started(event)
+    @logger.debug("Polling for '#{event.task_type}' tasks (poll_count=#{event.poll_count})")
+  end
+
+  # Called when polling completes successfully.
+  def on_poll_completed(event)
+    return unless event.tasks_received.positive?
+
+    @logger.debug("Received #{event.tasks_received} '#{event.task_type}' tasks " \
+                  "in #{event.duration_ms.round(2)}ms")
+  end
+
+  # Called when polling fails.
+  def on_poll_failure(event)
+    @logger.warn("Poll failed for '#{event.task_type}': #{event.cause.message}")
+  end
+
+  # Called when task update fails after all retries (CRITICAL).
+  def on_task_update_failure(event)
+    @logger.fatal("[CRITICAL] Task result LOST for '#{event.task_type}' " \
+                  "(task_id=#{event.task_id}, retries=#{event.retry_count})")
+  end
+end
+
+# Advanced listener that tracks task execution times and provides statistics.
+#
+# Demonstrates:
+# - Stateful event processing
+# - Aggregating data across multiple events
+# - Custom business logic in listeners
+#
+class TaskTimingTracker
+  attr_reader :task_times, :task_errors
+
+  def initialize(logger: nil, report_interval: 10)
+    @logger = logger || Logger.new($stdout)
+    @task_times = Hash.new { |h, k| h[k] = [] }
+    @task_errors = Hash.new(0)
+    @report_interval = report_interval
+    @mutex = Mutex.new
+  end
+
+  # Track successful task execution times.
+  def on_task_execution_completed(event)
+    @mutex.synchronize do
+      @task_times[event.task_type] << event.duration_ms
+
+      # Print stats every N completions
+      count = @task_times[event.task_type].size
+      return unless (count % @report_interval).zero?
+
+      durations = @task_times[event.task_type]
+      avg = durations.sum / durations.size
+      min_time = durations.min
+      max_time = durations.max
+
+      @logger.info("Stats for '#{event.task_type}': " \
+                   "count=#{count}, avg=#{avg.round(2)}ms, " \
+                   "min=#{min_time.round(2)}ms, max=#{max_time.round(2)}ms")
+    end
+  end
+
+  # Track task failures.
+  def on_task_execution_failure(event)
+    @mutex.synchronize do
+      @task_errors[event.task_type] += 1
+      @logger.warn("Task '#{event.task_type}' has failed #{@task_errors[event.task_type]} times")
+    end
+  end
+
+  # Get statistics for a task type.
+  # @param task_type [String] Task type name
+  # @return [Hash] Statistics including count, avg, min, max, error_count
+  def stats_for(task_type)
+    @mutex.synchronize do
+      durations = @task_times[task_type]
+      return nil if durations.empty?
+
+      {
+        count: durations.size,
+        avg_ms: durations.sum / durations.size,
+        min_ms: durations.min,
+        max_ms: durations.max,
+        error_count: @task_errors[task_type]
+      }
+    end
+  end
+
+  # Get all statistics.
+  # @return [Hash] Statistics for all task types
+  def all_stats
+    @mutex.synchronize do
+      @task_times.keys.each_with_object({}) do |task_type, result|
+        durations = @task_times[task_type]
+        result[task_type] = {
+          count: durations.size,
+          avg_ms: durations.sum / durations.size,
+          min_ms: durations.min,
+          max_ms: durations.max,
+          error_count: @task_errors[task_type]
+        }
+      end
+    end
+  end
+end
+
+# Example listener for distributed tracing integration.
+#
+# Demonstrates how to:
+# - Generate trace IDs
+# - Propagate trace context
+# - Create spans for task execution
+#
+# In production, replace the logging with actual tracing library calls
+# (OpenTelemetry, Jaeger, Zipkin, etc.)
+#
+class DistributedTracingListener
+  def initialize(logger: nil)
+    @logger = logger || Logger.new($stdout)
+    @active_traces = {}
+    @mutex = Mutex.new
+  end
+
+  # Start a trace span when task execution begins.
+  def on_task_execution_started(event)
+    trace_id = "trace-#{event.task_id[0..7]}"
+    span_id = "span-#{event.task_id[0..7]}"
+
+    @mutex.synchronize do
+      @active_traces[event.task_id] = {
+        trace_id: trace_id,
+        span_id: span_id,
+        start_time: Time.now,
+        task_type: event.task_type
+      }
+    end
+
+    @logger.info("[TRACE] Started span: trace_id=#{trace_id}, span_id=#{span_id}, " \
+                 "task_type=#{event.task_type}")
+  end
+
+  # End the trace span when task execution completes.
+  def on_task_execution_completed(event)
+    trace_info = @mutex.synchronize { @active_traces.delete(event.task_id) }
+    return unless trace_info
+
+    duration = (Time.now - trace_info[:start_time]) * 1000
+
+    @logger.info("[TRACE] Completed span: trace_id=#{trace_info[:trace_id]}, " \
+                 "span_id=#{trace_info[:span_id]}, duration=#{duration.round(2)}ms, status=SUCCESS")
+  end
+
+  # Mark the trace span as failed.
+  def on_task_execution_failure(event)
+    trace_info = @mutex.synchronize { @active_traces.delete(event.task_id) }
+    return unless trace_info
+
+    duration = (Time.now - trace_info[:start_time]) * 1000
+
+    @logger.info("[TRACE] Failed span: trace_id=#{trace_info[:trace_id]}, " \
+                 "span_id=#{trace_info[:span_id]}, duration=#{duration.round(2)}ms, " \
+                 "status=ERROR, error=#{event.cause.class}")
+  end
+end
+
+# Error tracking listener for aggregating and alerting on errors.
+#
+# Demonstrates:
+# - Error aggregation by type
+# - Threshold-based alerting
+# - Integration with external error tracking services
+#
+class ErrorTrackingListener
+  def initialize(logger: nil, alert_threshold: 5, alert_callback: nil)
+    @logger = logger || Logger.new($stdout)
+    @alert_threshold = alert_threshold
+    @alert_callback = alert_callback
+    @errors = Hash.new { |h, k| h[k] = [] }
+    @mutex = Mutex.new
+  end
+
+  def on_task_execution_failure(event)
+    @mutex.synchronize do
+      error_key = "#{event.task_type}:#{event.cause.class}"
+      @errors[error_key] << {
+        task_id: event.task_id,
+        workflow_instance_id: event.workflow_instance_id,
+        message: event.cause.message,
+        is_retryable: event.is_retryable,
+        timestamp: event.timestamp
+      }
+
+      # Check if threshold exceeded
+      recent_errors = @errors[error_key].select do |e|
+        e[:timestamp] > Time.now - 300 # Last 5 minutes
+      end
+
+      trigger_alert(event.task_type, event.cause.class.to_s, recent_errors.size) if recent_errors.size >= @alert_threshold
+    end
+  end
+
+  def on_task_update_failure(event)
+    @logger.fatal("[ALERT] CRITICAL: Task result lost! task_id=#{event.task_id}, " \
+                  "task_type=#{event.task_type}, retries=#{event.retry_count}")
+
+    # Always alert on task update failures
+    return unless @alert_callback
+
+    @alert_callback.call(
+      type: :task_update_failure,
+      severity: :critical,
+      task_id: event.task_id,
+      task_type: event.task_type,
+      retry_count: event.retry_count
+    )
+  end
+
+  # Get error summary.
+  # @return [Hash] Error counts by task_type:error_class
+  def error_summary
+    @mutex.synchronize do
+      @errors.transform_values(&:size)
+    end
+  end
+
+  private
+
+  def trigger_alert(task_type, error_class, count)
+    @logger.warn("[ALERT] High error rate: #{task_type} has #{count} " \
+                 "#{error_class} errors in last 5 minutes")
+
+    return unless @alert_callback
+
+    @alert_callback.call(
+      type: :high_error_rate,
+      severity: :warning,
+      task_type: task_type,
+      error_class: error_class,
+      count: count
+    )
+  end
+end
+
+# SLA monitoring listener that alerts when tasks exceed duration thresholds.
+#
+# Demonstrates:
+# - Configuration-driven thresholds
+# - Percentage-based alerting
+# - P99 latency tracking
+#
+class SLAMonitorListener
+  def initialize(thresholds: {}, logger: nil, alert_callback: nil)
+    @thresholds = thresholds # { 'task_type' => max_duration_ms }
+    @logger = logger || Logger.new($stdout)
+    @alert_callback = alert_callback
+    @violations = Hash.new { |h, k| h[k] = [] }
+    @mutex = Mutex.new
+  end
+
+  def on_task_execution_completed(event)
+    threshold = @thresholds[event.task_type]
+    return unless threshold && event.duration_ms > threshold
+
+    @mutex.synchronize do
+      @violations[event.task_type] << {
+        task_id: event.task_id,
+        duration_ms: event.duration_ms,
+        threshold_ms: threshold,
+        timestamp: event.timestamp
+      }
+    end
+
+    @logger.warn("[SLA] Violation: '#{event.task_type}' took #{event.duration_ms.round(2)}ms " \
+                 "(threshold: #{threshold}ms)")
+
+    return unless @alert_callback
+
+    @alert_callback.call(
+      type: :sla_violation,
+      task_type: event.task_type,
+      task_id: event.task_id,
+      duration_ms: event.duration_ms,
+      threshold_ms: threshold
+    )
+  end
+
+  # Get SLA violation summary.
+  # @return [Hash] Violation counts by task type
+  def violation_summary
+    @mutex.synchronize do
+      @violations.transform_values(&:size)
+    end
+  end
+
+  # Get recent violations for a task type.
+  # @param task_type [String] Task type name
+  # @param limit [Integer] Maximum number of violations to return
+  # @return [Array<Hash>] Recent violations
+  def recent_violations(task_type, limit: 10)
+    @mutex.synchronize do
+      @violations[task_type].last(limit)
+    end
+  end
+end
+
+# Example showing how to run with event listeners (for documentation)
+if __FILE__ == $PROGRAM_NAME
+  puts <<~USAGE
+    Event Listener Examples
+
+    This file provides reusable event listener implementations.
+    Import them in your application:
+
+      require_relative 'event_listener_examples'
+
+      # Create listeners
+      logger_listener = TaskExecutionLogger.new
+      timing_tracker = TaskTimingTracker.new
+      tracing_listener = DistributedTracingListener.new
+
+      # Use with TaskHandler
+      handler = Conductor::Worker::TaskHandler.new(
+        configuration: config,
+        event_listeners: [
+          logger_listener,
+          timing_tracker,
+          tracing_listener
+        ]
+      )
+
+      handler.start
+      handler.join
+
+    Available Listeners:
+      - TaskExecutionLogger: Logs all task lifecycle events
+      - TaskTimingTracker: Tracks execution statistics
+      - DistributedTracingListener: Simulates distributed tracing
+      - ErrorTrackingListener: Aggregates errors and alerts
+      - SLAMonitorListener: Monitors SLA violations
+
+  USAGE
+end