fractor 0.1.6 → 0.1.7

data/lib/fractor/workflow/execution_strategy.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Base class for workflow execution strategies.
+    # Defines the interface for different execution patterns.
+    #
+    # @abstract Subclasses must implement the `execute` method
+    class ExecutionStrategy
+      attr_reader :executor, :debug
+
+      # Initialize a new execution strategy.
+      #
+      # @param executor [WorkflowExecutor] The workflow executor
+      # @param debug [Boolean] Whether to enable debug logging
+      def initialize(executor, debug: false)
+        @executor = executor
+        @debug = debug
+      end
+
+      # Execute a group of jobs according to the strategy.
+      #
+      # @param job_group [Array<Job>] Jobs to execute
+      # @return [Boolean] true if execution should continue
+      # @raise [WorkflowError] if execution fails
+      def execute(job_group)
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      # Check if a job should be executed based on its condition.
+      #
+      # @param job [Job] The job to check
+      # @return [Boolean] true if the job should execute
+      def should_execute_job?(job)
+        return true unless job.condition_proc
+
+        job.condition_proc.call(executor.context)
+      end
+
+      protected
+
+      # Get the workflow instance.
+      #
+      # @return [Workflow] The workflow
+      def workflow
+        executor.workflow
+      end
+
+      # Get the workflow context.
+      #
+      # @return [WorkflowContext] The context
+      def context
+        executor.context
+      end
+
+      # Get the execution hooks.
+      #
+      # @return [ExecutionHooks] The hooks
+      def hooks
+        executor.hooks
+      end
+
+      # Get the execution trace.
+      #
+      # @return [ExecutionTrace, nil] The trace or nil
+      def trace
+        executor.trace
+      end
+
+      # Get the dead letter queue.
+      #
+      # @return [DeadLetterQueue, nil] The DLQ or nil
+      def dead_letter_queue
+        executor.dead_letter_queue
+      end
+
+      # Log a debug message if debug mode is enabled.
+      #
+      # @param message [String] The message to log
+      def log_debug(message)
+        puts "[ExecutionStrategy] #{message}" if debug
+      end
+    end
+
+    # Strategy for executing jobs sequentially, one after another.
+    # Jobs are executed in the order they appear in the job group.
+    class SequentialExecutionStrategy < ExecutionStrategy
+      # Execute a group of jobs sequentially.
+      #
+      # @param job_group [Array<Job>] Jobs to execute
+      # @return [Boolean] true if execution should continue
+      def execute(job_group)
+        log_debug "Executing #{job_group.size} jobs sequentially: #{job_group.map(&:name).join(', ')}"
+
+        job_group.each do |job|
+          execute_single_job(job)
+        end
+
+        true
+      end
+
+      private
+
+      # Execute a single job.
+      #
+      # @param job [Job] The job to execute
+      def execute_single_job(job)
+        return unless should_execute_job?(job)
+
+        job_trace = trace&.start_job(job_name: job.name,
+                                     worker_class: job.worker_class&.name)
+        job_trace&.set_input(job_input(job))
+
+        result = execute_job_with_retry(job, job_trace)
+
+        job_trace&.complete!(output: result)
+        context.store_job_output(job.name, result)
+
+        executor.instance_variable_get(:@completed_jobs).add(job.name)
+        job.state(:completed)
+
+        hooks.trigger(:job_complete, job, result, 0)
+      rescue StandardError => e
+        handle_job_error(job, e)
+      end
+
+      # Get the input for a job.
+      #
+      # @param job [Job] The job
+      # @return [Object] The job input
+      def job_input(job)
+        executor.send(:prepare_job_input, job)
+      end
+
+      # Execute a job with retry logic.
+      #
+      # @param job [Job] The job to execute
+      # @param job_trace [Object] The job trace
+      # @return [Object] The execution result
+      def execute_job_with_retry(job, job_trace)
+        if job.retry_config
+          return executor.send(:execute_job_with_retry, job,
+                               job_trace)
+        end
+
+        executor.send(:execute_job_once, job, job_trace)
+      end
+
+      # Handle a job execution error.
+      #
+      # @param job [Job] The job that failed
+      # @param error [Exception] The error
+      # @raise [WorkflowError] if the error should propagate
+      def handle_job_error(job, error)
+        executor.instance_variable_get(:@failed_jobs).add(job.name)
+        job.state(:failed)
+
+        if job.fallback_job
+          executor.send(:execute_fallback_job, job, error, nil, nil)
+        else
+          executor.send(:add_to_dead_letter_queue, job, error, nil)
+          raise
+        end
+      end
+    end
+
+    # Strategy for executing jobs in parallel.
+    # Jobs are executed concurrently using Supervisor.
+    class ParallelExecutionStrategy < ExecutionStrategy
+      # Execute a group of jobs in parallel.
+      #
+      # @param job_group [Array<Job>] Jobs to execute
+      # @return [Boolean] true if execution should continue
+      def execute(job_group)
+        log_debug "Executing #{job_group.size} jobs in parallel: #{job_group.map(&:name).join(', ')}"
+
+        executor.send(:execute_jobs_parallel, job_group)
+
+        # Check if any jobs failed
+        failed_jobs = job_group.select do |job|
+          executor.instance_variable_get(:@failed_jobs).include?(job.name)
+        end
+        if failed_jobs.any?
+          handle_parallel_errors(failed_jobs)
+        end
+
+        true
+      end
+
+      private
+
+      # Handle errors from parallel execution.
+      #
+      # @param failed_jobs [Array<Job>] Jobs that failed
+      # @raise [WorkflowError] If any failed jobs don't have fallbacks
+      def handle_parallel_errors(failed_jobs)
+        jobs_without_fallback = failed_jobs.reject(&:fallback_job)
+        return if jobs_without_fallback.empty?
+
+        error_messages = jobs_without_fallback.map(&:name).join(", ")
+        raise WorkflowError,
+              "Parallel jobs failed without fallbacks: #{error_messages}"
+      end
+    end
+
+    # Strategy for executing jobs as a pipeline.
+    # Jobs are executed sequentially with data flowing from one to the next.
+    class PipelineExecutionStrategy < SequentialExecutionStrategy
+      # Execute a group of jobs as a pipeline.
+      #
+      # @param job_group [Array<Job>] Jobs to execute (must be exactly 1 for pipeline)
+      # @return [Boolean] true if execution should continue
+      def execute(job_group)
+        if job_group.size > 1
+          raise WorkflowError,
+                "Pipeline strategy expects exactly 1 job per group, got #{job_group.size}"
+        end
+
+        log_debug "Executing pipeline job: #{job_group.first.name}"
+
+        super
+      end
+    end
+  end
+end

data/lib/fractor/workflow/execution_trace.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Fractor
+  class Workflow
+    # Tracks execution details for workflow runs.
+    # Provides detailed trace of job execution, timings, and results.
+    class ExecutionTrace
+      attr_reader :workflow_name, :execution_id, :correlation_id,
+                  :started_at, :completed_at, :job_traces
+
+      def initialize(workflow_name:, execution_id:, correlation_id:)
+        @workflow_name = workflow_name
+        @execution_id = execution_id
+        @correlation_id = correlation_id
+        @started_at = Time.now.utc
+        @completed_at = nil
+        @job_traces = []
+      end
+
+      # Record the start of a job execution
+      def start_job(job_name:, worker_class:)
+        job_trace = JobTrace.new(
+          job_name: job_name,
+          worker_class: worker_class,
+        )
+        @job_traces << job_trace
+        job_trace
+      end
+
+      # Mark the workflow as completed
+      def complete!
+        @completed_at = Time.now.utc
+      end
+
+      # Total duration in milliseconds
+      def total_duration_ms
+        return nil unless @completed_at
+
+        ((@completed_at - @started_at) * 1000).round(2)
+      end
+
+      # Convert trace to hash for serialization
+      def to_h
+        {
+          workflow: @workflow_name,
+          execution_id: @execution_id,
+          correlation_id: @correlation_id,
+          started_at: @started_at.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+          completed_at: @completed_at&.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+          total_duration_ms: total_duration_ms,
+          jobs: @job_traces.map(&:to_h),
+        }
+      end
+
+      # Convert trace to JSON
+      def to_json(*_args)
+        to_h.to_json
+      end
+
+      # Trace data for a single job execution
+      class JobTrace
+        attr_reader :job_name, :worker_class, :started_at,
+                    :completed_at, :status, :error
+
+        def initialize(job_name:, worker_class:)
+          @job_name = job_name
+          @worker_class = worker_class
+          @started_at = Time.now.utc
+          @completed_at = nil
+          @status = :running
+          @error = nil
+          @input_hash = nil
+          @output_hash = nil
+        end
+
+        # Mark job as successfully completed
+        def complete!(output: nil)
+          @completed_at = Time.now.utc
+          @status = :success
+          @output_hash = hash_value(output) if output
+        end
+
+        # Mark job as failed
+        def fail!(error:)
+          @completed_at = Time.now.utc
+          @status = :failed
+          @error = {
+            class: error.class.name,
+            message: error.message,
+            backtrace: error.backtrace&.first(5),
+          }
+        end
+
+        # Set input hash for tracking
+        def set_input(input)
+          @input_hash = hash_value(input)
+        end
+
+        # Duration in milliseconds
+        def duration_ms
+          return nil unless @completed_at
+
+          ((@completed_at - @started_at) * 1000).round(2)
+        end
+
+        # Convert to hash for serialization
+        def to_h
+          {
+            name: @job_name,
+            worker: @worker_class,
+            started_at: @started_at.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+            completed_at: @completed_at&.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+            duration_ms: duration_ms,
+            status: @status.to_s,
+            input_hash: @input_hash,
+            output_hash: @output_hash,
+            error: @error,
+          }.compact
+        end
+
+        private
+
+        def hash_value(value)
+          return nil unless value
+
+          # Create a simple hash for tracking (not cryptographic)
+          value.to_s.hash.abs.to_s(16)[0..7]
+        end
+      end
+    end
+  end
+end

data/lib/fractor/workflow/helpers.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Helper workers that provide common patterns to reduce boilerplate
+    module Helpers
+      # Simple worker for basic transformations
+      # Just implement the transform method
+      #
+      # Example:
+      #   class MyWorker < Fractor::Workflow::Helpers::SimpleWorker
+      #     input_type InputData
+      #     output_type OutputData
+      #
+      #     def transform(input)
+      #       OutputData.new(result: input.value * 2)
+      #     end
+      #   end
+      class SimpleWorker < Fractor::Worker
+        def process(work)
+          input = work.input
+          output = transform(input)
+          Fractor::WorkResult.new(result: output, work: work)
+        end
+
+        # Override this method in subclasses
+        def transform(input)
+          raise NotImplementedError, "Subclasses must implement #transform"
+        end
+      end
+
+      # Worker for mapping over collections
+      # Implement the map_item method
+      #
+      # Example:
+      #   class ProcessItems < Fractor::Workflow::Helpers::MapWorker
+      #     def map_item(item)
+      #       item.upcase
+      #     end
+      #   end
+      class MapWorker < Fractor::Worker
+        def process(work)
+          input = work.input
+          collection = extract_collection(input)
+
+          mapped = collection.map { |item| map_item(item) }
+          output = build_output(mapped, input)
+
+          Fractor::WorkResult.new(result: output, work: work)
+        end
+
+        # Override in subclasses to define how to map each item
+        def map_item(item)
+          raise NotImplementedError, "Subclasses must implement #map_item"
+        end
+
+        # Override to specify how to extract collection from input
+        # Default: assumes input responds to :to_a
+        def extract_collection(input)
+          input.respond_to?(:to_a) ? input.to_a : [input]
+        end
+
+        # Override to specify how to build output from mapped collection
+        # Default: returns the array
+        def build_output(mapped_collection, _original_input)
+          mapped_collection
+        end
+      end
+
+      # Worker for filtering collections
+      # Implement the filter_item? method
+      #
+      # Example:
+      #   class FilterPositive < Fractor::Workflow::Helpers::FilterWorker
+      #     def filter_item?(item)
+      #       item > 0
+      #     end
+      #   end
+      class FilterWorker < Fractor::Worker
+        def process(work)
+          input = work.input
+          collection = extract_collection(input)
+
+          filtered = collection.select { |item| filter_item?(item) }
+          output = build_output(filtered, input)
+
+          Fractor::WorkResult.new(result: output, work: work)
+        end
+
+        # Override in subclasses to define filter logic
+        def filter_item?(item)
+          raise NotImplementedError, "Subclasses must implement #filter_item?"
+        end
+
+        # Override to specify how to extract collection from input
+        def extract_collection(input)
+          input.respond_to?(:to_a) ? input.to_a : [input]
+        end
+
+        # Override to specify how to build output from filtered collection
+        def build_output(filtered_collection, _original_input)
+          filtered_collection
+        end
+      end
+
+      # Worker for reducing/aggregating collections
+      # Implement the reduce_items method
+      #
+      # Example:
+      #   class SumNumbers < Fractor::Workflow::Helpers::ReduceWorker
+      #     def reduce_items(collection)
+      #       collection.sum
+      #     end
+      #   end
+      class ReduceWorker < Fractor::Worker
+        def process(work)
+          input = work.input
+          collection = extract_collection(input)
+
+          result = reduce_items(collection)
+          output = build_output(result, input)
+
+          Fractor::WorkResult.new(result: output, work: work)
+        end
+
+        # Override in subclasses to define reduce logic
+        def reduce_items(collection)
+          raise NotImplementedError, "Subclasses must implement #reduce_items"
+        end
+
+        # Override to specify how to extract collection from input
+        def extract_collection(input)
+          input.respond_to?(:to_a) ? input.to_a : [input]
+        end
+
+        # Override to specify how to build output from reduced value
+        def build_output(reduced_value, _original_input)
+          reduced_value
+        end
+      end
+
+      # Worker for validation
+      # Implement the validate method
+      #
+      # Example:
+      #   class ValidateAge < Fractor::Workflow::Helpers::ValidationWorker
+      #     def validate(input)
+      #       return unless input.age < 0
+      #       add_error("Age must be positive")
+      #     end
+      #   end
+      class ValidationWorker < Fractor::Worker
+        def initialize
+          super
+          @errors = []
+        end
+
+        def process(work)
+          input = work.input
+          @errors = []
+
+          validate(input)
+
+          output = build_output(input, @errors)
+          Fractor::WorkResult.new(result: output, work: work)
+        end
+
+        # Override in subclasses to define validation logic
+        # Use add_error(message) to record errors
+        def validate(input)
+          raise NotImplementedError, "Subclasses must implement #validate"
+        end
+
+        # Add a validation error
+        def add_error(message)
+          @errors << message
+        end
+
+        # Override to customize output format
+        # Default: returns hash with valid? flag and errors
+        def build_output(input, errors)
+          {
+            valid: errors.empty?,
+            errors: errors,
+            input: input,
+          }
+        end
+      end
+    end
+  end
+end