fractor 0.1.6 → 0.1.7

data/lib/fractor/workflow/job.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require_relative "retry_config"
+
+module Fractor
+  class Workflow
+    # Represents a single job in a workflow.
+    # Jobs encapsulate worker configuration, dependencies, and input/output mappings.
+    class Job
+      attr_reader :name, :workflow_class, :worker_class, :dependencies,
+                  :num_workers, :input_mappings, :condition_proc,
+                  :terminates, :retry_config, :error_handlers, :fallback_job,
+                  :circuit_breaker_config
+
+      def initialize(name, workflow_class)
+        @name = name
+        @workflow_class = workflow_class
+        @worker_class = nil
+        @dependencies = []
+        @num_workers = nil
+        @input_mappings = {}
+        @condition_proc = nil
+        @terminates = false
+        @outputs_to_workflow = false
+        @state = :pending
+        @retry_config = nil
+        @error_handlers = []
+        @fallback_job = nil
+        @circuit_breaker_config = nil
+      end
+
+      # Specify which worker class processes this job.
+      #
+      # @param klass [Class] A Fractor::Worker subclass
+      def runs_with(klass)
+        unless klass < Fractor::Worker
+          raise ArgumentError, "#{klass} must inherit from Fractor::Worker"
+        end
+
+        @worker_class = klass
+      end
+
+      # Specify job dependencies.
+      #
+      # @param job_names [Array<String, Symbol>] Names of jobs this job depends on
+      def needs(*job_names)
+        @dependencies = job_names.flatten.map(&:to_s)
+      end
+
+      # Set the number of parallel workers for this job.
+      #
+      # @param n [Integer] Number of workers
+      def parallel_workers(n)
+        unless n.is_a?(Integer) && n.positive?
+          raise ArgumentError, "parallel_workers must be a positive integer"
+        end
+
+        @num_workers = n
+      end
+
+      # Map inputs from the workflow input.
+      # Used when this is the first job in the workflow.
+      def inputs_from_workflow
+        @input_mappings[:workflow] = true
+      end
+      alias inputs_from :inputs_from_workflow
+
+      # Auto-wire inputs from dependencies if not explicitly configured.
+      # Called during workflow finalization.
+      def auto_wire_inputs!
+        return unless @input_mappings.empty?
+
+        if @dependencies.empty?
+          # No dependencies = must be a start job
+          @input_mappings[:workflow] = true
+        elsif @dependencies.size == 1
+          # Single dependency = auto-wire from that job
+          @input_mappings[@dependencies.first] = :all
+        end
+        # Multiple dependencies require explicit configuration
+      end
+
+      # Map inputs from a single upstream job.
+      #
+      # @param source_job [String, Symbol] The source job name
+      # @param select [Hash] Optional attribute mappings
+      def inputs_from_job(source_job, select: nil)
+        source = source_job.to_s
+        @input_mappings[source] = select || :all
+      end
+
+      # Map inputs from multiple upstream jobs.
+      #
+      # @param mappings [Hash] Hash of source_job => attribute_mappings
+      # Example:
+      #   inputs_from_multiple(
+      #     "job_a" => { validated_data: :validated_data },
+      #     "job_b" => { analysis: :results }
+      #   )
+      def inputs_from_multiple(mappings)
+        mappings.each do |source_job, attr_mappings|
+          source = source_job.to_s
+          @input_mappings[source] = attr_mappings
+        end
+      end
+
+      # Set a condition for this job to run.
+      #
+      # @param proc [Proc] A proc that receives the workflow context
+      def if_condition(proc)
+        unless proc.respond_to?(:call)
+          raise ArgumentError, "if_condition must be callable"
+        end
+
+        @condition_proc = proc
+      end
+
+      # Mark this job as a workflow terminator.
+      #
+      # @param value [Boolean] Whether this job terminates the workflow
+      def terminates_workflow(value = true)
+        @terminates = value
+      end
+
+      # Mark this job's outputs as mapping to workflow outputs.
+      def outputs_to_workflow
+        @outputs_to_workflow = true
+      end
+      alias outputs_to :outputs_to_workflow
+
+      # Configure retry behavior for this job.
+      #
+      # @param max_attempts [Integer] Maximum number of retry attempts
+      # @param backoff [Symbol] Backoff strategy (:exponential, :linear, :constant, :none)
+      # @param initial_delay [Numeric] Initial delay in seconds
+      # @param max_delay [Numeric] Maximum delay in seconds
+      # @param timeout [Numeric] Job execution timeout in seconds
+      # @param retryable_errors [Array<Class>] List of retryable error classes
+      # @param options [Hash] Additional retry options
+      def retry_on_error(max_attempts: 3, backoff: :exponential,
+                         initial_delay: 1, max_delay: nil, timeout: nil,
+                         retryable_errors: [StandardError], **options)
+        @retry_config = Workflow::RetryConfig.from_options(
+          max_attempts: max_attempts,
+          backoff: backoff,
+          initial_delay: initial_delay,
+          max_delay: max_delay,
+          timeout: timeout,
+          retryable_errors: retryable_errors,
+          **options,
+        )
+      end
+
+      # Add an error handler for this job.
+      #
+      # @param handler [Proc] A proc that receives (error, context)
+      def on_error(&handler)
+        unless handler.respond_to?(:call)
+          raise ArgumentError, "on_error must be given a block"
+        end
+
+        @error_handlers << handler
+      end
+
+      # Set a fallback job for this job.
+      #
+      # @param job_name [String, Symbol] Name of the fallback job
+      def fallback_to(job_name)
+        @fallback_job = job_name.to_s
+      end
+
+      # Configure circuit breaker for this job.
+      #
+      # @param threshold [Integer] Number of failures before opening circuit
+      # @param timeout [Integer] Seconds to wait before trying half-open
+      # @param half_open_calls [Integer] Number of test calls in half-open
+      # @param shared_key [String] Optional key for shared circuit breaker
+      def circuit_breaker(threshold: 5, timeout: 60, half_open_calls: 3,
+                          shared_key: nil)
+        @circuit_breaker_config = {
+          threshold: threshold,
+          timeout: timeout,
+          half_open_calls: half_open_calls,
+          shared_key: shared_key,
+        }
+      end
+
+      # Check if this job has circuit breaker configured.
+      #
+      # @return [Boolean] Whether circuit breaker is configured
+      def circuit_breaker_enabled?
+        !@circuit_breaker_config.nil?
+      end
+
+      # Get the circuit breaker key for this job.
+      #
+      # @return [String] The circuit breaker key
+      def circuit_breaker_key
+        return nil unless circuit_breaker_enabled?
+
+        @circuit_breaker_config[:shared_key] || "job_#{@name}"
+      end
+
+      # Check if this job has retry configured.
+      #
+      # @return [Boolean] Whether retry is configured
+      def retry_enabled?
+        !@retry_config.nil? && @retry_config.max_attempts > 1
+      end
+
+      # Get the timeout for this job.
+      #
+      # @return [Numeric, nil] Timeout in seconds or nil
+      def timeout
+        @retry_config&.timeout
+      end
+
+      # Execute error handlers for this job.
+      #
+      # @param error [Exception] The error that occurred
+      # @param context [WorkflowContext] The workflow context
+      def handle_error(error, context)
+        @error_handlers.each do |handler|
+          handler.call(error, context)
+        rescue StandardError => e
+          context.logger&.error(
+            "Error handler failed for job #{@name}: #{e.message}",
+          )
+        end
+      end
+
+      # Check if this job's outputs map to workflow outputs.
+      #
+      # @return [Boolean] Whether this job outputs to workflow
+      def outputs_to_workflow?
+        @outputs_to_workflow
+      end
+
+      # Check if this job should execute based on its condition.
+      #
+      # @param context [WorkflowContext] The workflow execution context
+      # @return [Boolean] Whether the job should execute
+      def should_execute?(context)
+        return true unless @condition_proc
+
+        @condition_proc.call(context)
+      end
+
+      # Get the input type for this job from its worker.
+      #
+      # @return [Class] The input type class
+      def input_type
+        return nil unless @worker_class
+
+        @worker_class.input_type_class
+      end
+
+      # Get the output type for this job from its worker.
+      #
+      # @return [Class] The output type class
+      def output_type
+        return nil unless @worker_class
+
+        @worker_class.output_type_class
+      end
+
+      # Check if this job is ready to execute.
+      # A job is ready when all its dependencies have completed.
+      #
+      # @param completed_jobs [Set] Set of completed job names
+      # @return [Boolean] Whether the job is ready
+      def ready?(completed_jobs)
+        @dependencies.all? { |dep| completed_jobs.include?(dep) }
+      end
+
+      # Get or set the job state.
+      #
+      # @param new_state [Symbol] :pending, :ready, :running, :completed, :failed, :skipped
+      # @return [Symbol] The current state
+      def state(new_state = nil)
+        @state = new_state if new_state
+        @state
+      end
+
+      def to_s
+        "Job[#{@name}]"
+      end
+    end
+  end
+end

data/lib/fractor/workflow/job_dependency_validator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Validates job dependencies in workflows.
+    # Ensures dependencies exist and are acyclic.
+    #
+    # This validator prevents runtime errors by catching configuration
+    # issues before workflow execution begins.
+    class JobDependencyValidator
+      # Error raised when dependency validation fails.
+      class DependencyError < StandardError; end
+
+      def initialize(jobs)
+        @jobs = jobs
+        @jobs_by_name = build_jobs_index
+      end
+
+      # Validate all job dependencies.
+      # Raises DependencyError if any validation fails.
+      #
+      # @raise [DependencyError] if validation fails
+      # @return [true] if validation passes
+      def validate!
+        check_missing_dependencies
+        check_circular_dependencies
+        true
+      end
+
+      # Check for circular dependencies using depth-first search.
+      #
+      # @raise [DependencyError] if circular dependencies found
+      # @return [true] if no circular dependencies
+      def check_circular_dependencies
+        visited = Set.new
+        path = [] # Track current path as an array
+
+        @jobs.each do |job|
+          next if visited.include?(job.name)
+
+          cycle = dfs_cycle_check(job, visited, path)
+          if cycle
+            cycle_path = cycle.join(" -> ")
+            raise DependencyError, "Circular dependency detected: #{cycle_path}"
+          end
+        end
+
+        true
+      end
+
+      # DFS cycle detection that returns the cycle path if found.
+      #
+      # @param job [Job] The job to check
+      # @param visited [Set] Jobs already visited
+      # @param path [Array] Current path being explored
+      # @return [Array<String>, nil] Cycle path if found, nil otherwise
+      def dfs_cycle_check(job, visited, path)
+        return nil unless job
+
+        # If this job is in the current path, we found a cycle
+        if path.include?(job.name)
+          # Extract the cycle portion
+          cycle_start_index = path.index(job.name)
+          return path[cycle_start_index..] + [job.name]
+        end
+
+        # If we've already fully explored this job, no cycle from here
+        return nil if visited.include?(job.name)
+
+        # Add to current path
+        path << job.name
+
+        # Check all dependencies
+        job.dependencies.each do |dep_name|
+          dep_job = @jobs_by_name[dep_name]
+          next unless dep_job
+
+          cycle = dfs_cycle_check(dep_job, visited, path)
+          return cycle if cycle
+        end
+
+        # Remove from path and mark as visited
+        path.pop
+        visited.add(job.name)
+
+        nil
+      end
+
+      # Check that all job dependencies exist.
+      #
+      # @raise [DependencyError] if any dependencies are missing
+      # @return [true] if all dependencies exist
+      def check_missing_dependencies
+        missing = []
+
+        @jobs.each do |job|
+          job.dependencies.each do |dep_name|
+            unless @jobs_by_name.key?(dep_name)
+              missing << "#{job.name} depends on non-existent job '#{dep_name}'"
+            end
+          end
+        end
+
+        return true if missing.empty?
+
+        raise DependencyError,
+              "Missing dependencies:\n  - #{missing.join("\n  - ")}"
+      end
+
+      private
+
+      # Build an index of jobs by name for quick lookup.
+      #
+      # @return [Hash<String, Job>]
+      def build_jobs_index
+        @jobs.each_with_object({}) { |job, hash| hash[job.name] = job }
+      end
+    end
+  end
+end

data/lib/fractor/workflow/logger.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "logger"
+require "json"
+require "time"
+
+module Fractor
+  class Workflow
+    # Logger wrapper for workflow execution logging.
+    # Provides structured logging with correlation IDs and context.
+    class WorkflowLogger
+      attr_reader :logger, :correlation_id
+
+      def initialize(logger: nil, correlation_id: nil)
+        @logger = logger || default_logger
+        @correlation_id = correlation_id || generate_correlation_id
+      end
+
+      # Log an info message with structured context
+      def info(message, context = {})
+        log(:info, message, context)
+      end
+
+      # Log a warning message with structured context
+      def warn(message, context = {})
+        log(:warn, message, context)
+      end
+
+      # Log an error message with structured context
+      def error(message, context = {})
+        log(:error, message, context)
+      end
+
+      # Log a debug message with structured context
+      def debug(message, context = {})
+        log(:debug, message, context)
+      end
+
+      # Create a child logger with additional context
+      def child(additional_context = {})
+        child_logger = self.class.new(
+          logger: @logger,
+          correlation_id: @correlation_id,
+        )
+        child_logger.instance_variable_set(
+          :@base_context,
+          base_context.merge(additional_context),
+        )
+        child_logger
+      end
+
+      private
+
+      def log(level, message, context)
+        return unless should_log?(level)
+
+        log_data = build_log_data(level, message, context)
+        formatted_message = format_message(log_data)
+        @logger.send(level, formatted_message)
+      end
+
+      def should_log?(level)
+        @logger.send("#{level}?")
+      end
+
+      def build_log_data(level, message, context)
+        {
+          timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ"),
+          level: level.to_s.upcase,
+          correlation_id: @correlation_id,
+          message: message,
+        }.merge(base_context).merge(context)
+      end
+
+      def format_message(log_data)
+        # Simple key=value format for readability
+        parts = log_data.map { |k, v| "#{k}=#{format_value(v)}" }
+        parts.join(" ")
+      end
+
+      def format_value(value)
+        case value
+        when String
+          value.include?(" ") ? "\"#{value}\"" : value
+        when Hash, Array
+          value.to_json
+        else
+          value.to_s
+        end
+      end
+
+      def base_context
+        @base_context ||= {}
+      end
+
+      def default_logger
+        Logger.new($stdout).tap do |log|
+          log.level = Logger::INFO
+          log.formatter = proc do |_severity, _datetime, _progname, msg|
+            "#{msg}\n"
+          end
+        end
+      end
+
+      def generate_correlation_id
+        "wf-#{SecureRandom.hex(8)}"
+      end
+    end
+  end
+end

data/lib/fractor/workflow/pre_execution_context.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Manages pre-execution validation for workflows.
+    # Provides hooks for custom validation logic and detailed error messages.
+    #
+    # This class ensures workflows are validated with full context before
+    # execution begins, catching errors early with clear messages.
+    class PreExecutionContext
+      attr_reader :workflow, :input, :errors, :warnings
+
+      def initialize(workflow, input)
+        @workflow = workflow
+        @input = input
+        @errors = []
+        @warnings = []
+        @validation_hooks = []
+      end
+
+      # Register a custom validation hook.
+      # Hooks should return true if validation passes, or add error messages.
+      #
+      # @param name [String, Symbol] Optional name for the validation
+      # @yield [context] Block that receives the pre-execution context
+      #
+      # @example Add custom validation
+      #   context.add_validation_hook(:check_api_key) do |ctx|
+      #     unless ctx.input.api_key
+      #       ctx.add_error("API key is required")
+      #     end
+      #   end
+      def add_validation_hook(name = nil, &block)
+        unless block
+          raise ArgumentError, "Must provide a block for validation hook"
+        end
+
+        @validation_hooks << { name: name, block: block }
+      end
+
+      # Run all validations and return whether validation passed.
+      #
+      # @return [Boolean] true if all validations pass
+      # @raise [WorkflowError] if validation fails
+      def validate!
+        reset_results
+
+        # Run built-in validations
+        validate_workflow_definition!
+        validate_input_type!
+        validate_input_presence!
+
+        # Run custom validation hooks
+        run_validation_hooks
+
+        # Raise error if any validation failed
+        unless @errors.empty?
+          raise WorkflowError, validation_error_message
+        end
+
+        # Log warnings if any
+        log_warnings unless @warnings.empty?
+
+        true
+      end
+
+      # Add an error message to the validation context.
+      #
+      # @param message [String] The error message
+      def add_error(message)
+        @errors << message
+      end
+
+      # Add a warning message to the validation context.
+      #
+      # @param message [String] The warning message
+      def add_warning(message)
+        @warnings << message
+      end
+
+      # Check if validation passed (errors only).
+      #
+      # @return [Boolean] true if no errors
+      def valid?
+        @errors.empty?
+      end
+
+      # Check if there are any warnings (regardless of errors).
+      #
+      # @return [Boolean] true if warnings present
+      def has_warnings?
+        !@warnings.empty?
+      end
+
+      private
+
+      def reset_results
+        @errors = []
+        @warnings = []
+      end
+
+      def validate_workflow_definition!
+        # Ensure workflow is properly defined
+        workflow_class = @workflow.class
+
+        if workflow_class.jobs.empty?
+          add_error("Workflow '#{workflow_class.workflow_name}' has no jobs defined")
+        end
+
+        # Check for start job in pipeline mode
+        if workflow_class.workflow_mode == :pipeline && !workflow_class.start_job_name
+          add_error("Pipeline workflow must define start_with")
+        end
+      end
+
+      def validate_input_type!
+        expected_type = @workflow.class.input_model_class
+        return unless expected_type
+
+        unless @input.is_a?(expected_type)
+          add_error(
+            "Workflow '#{@workflow.class.workflow_name}' expects input of type " \
+            "#{expected_type}, got #{@input.class}",
+          )
+        end
+      end
+
+      def validate_input_presence!
+        return if @input
+
+        # Check if workflow requires input
+        if @workflow.class.input_model_class || requires_workflow_input?
+          add_error(
+            "Workflow '#{@workflow.class.workflow_name}' requires input but none was provided",
+          )
+        end
+      end
+
+      def requires_workflow_input?
+        # Check if any job takes input from workflow
+        @workflow.class.jobs.values.any? do |job|
+          job.input_mappings.key?(:workflow)
+        end
+      end
+
+      def run_validation_hooks
+        @validation_hooks.each do |hook|
+          hook[:block].call(self)
+        rescue StandardError => e
+          add_error(
+            "Validation hook '#{hook[:name] || 'unnamed'}' raised error: #{e.message}",
+          )
+        end
+      end
+
+      def validation_error_message
+        workflow_name = @workflow.class.workflow_name
+
+        lines = [
+          "Workflow '#{workflow_name}' validation failed",
+          "",
+          "Errors:",
+        ]
+
+        @errors.each_with_index do |error, index|
+          lines << "  #{index + 1}. #{error}"
+        end
+
+        unless @warnings.empty?
+          lines << ""
+          lines << "Warnings:"
+          @warnings.each_with_index do |warning, index|
+            lines << "  #{index + 1}. #{warning}"
+          end
+        end
+
+        lines << ""
+        lines << "Fix: Address the errors above before executing the workflow."
+
+        lines.join("\n")
+      end
+
+      def log_warnings
+        workflow_name = @workflow.class.workflow_name
+
+        warn "Workflow '#{workflow_name}' validation warnings:"
+        @warnings.each_with_index do |warning, index|
+          warn "  #{index + 1}. #{warning}"
+        end
+      end
+    end
+  end
+end