fractor 0.1.4 → 0.1.7

data/lib/fractor/workflow/builder.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Programmatic API for building workflows without DSL
+    # Useful for generating workflows dynamically
+    #
+    # Example:
+    #   builder = Fractor::Workflow::Builder.new("my-workflow")
+    #   builder.input_type(InputData)
+    #   builder.output_type(OutputData)
+    #   builder.add_job("process", ProcessWorker, inputs: :workflow)
+    #   builder.add_job("finalize", FinalizeWorker, needs: "process", inputs: "process")
+    #   workflow_class = builder.build
+    #   workflow = workflow_class.new
+    #   result = workflow.execute(input: data)
+    class Builder
+      attr_reader :name, :jobs, :input_type_class, :output_type_class
+
+      def initialize(name)
+        @name = name
+        @jobs = []
+        @input_type_class = nil
+        @output_type_class = nil
+      end
+
+      # Set input type for the workflow
+      def input_type(klass)
+        @input_type_class = klass
+        self
+      end
+
+      # Set output type for the workflow
+      def output_type(klass)
+        @output_type_class = klass
+        self
+      end
+
+      # Add a job to the workflow
+      #
+      # @param id [String] Job identifier
+      # @param worker [Class] Worker class
+      # @param needs [String, Array<String>] Job dependencies
+      # @param inputs [Symbol, String, Hash] Input configuration
+      # @param condition [Proc] Conditional execution lambda
+      # @param outputs_to_workflow [Boolean] Whether job outputs to workflow
+      # @param terminates [Boolean] Whether job terminates workflow
+      def add_job(id, worker, needs: nil, inputs: nil, condition: nil,
+                  outputs_to_workflow: false, terminates: false)
+        @jobs << {
+          id: id,
+          worker: worker,
+          needs: needs,
+          inputs: inputs,
+          condition: condition,
+          outputs_to_workflow: outputs_to_workflow,
+          terminates: terminates,
+        }
+        self
+      end
+
+      # Remove a job by id
+      def remove_job(id)
+        @jobs.reject! { |j| j[:id] == id }
+        self
+      end
+
+      # Update a job
+      def update_job(id, **options)
+        job = @jobs.find { |j| j[:id] == id }
+        return self unless job
+
+        job.merge!(options.compact)
+        self
+      end
+
+      # Build the workflow class
+      def build
+        builder_name = @name
+        builder_input_type = @input_type_class
+        builder_output_type = @output_type_class
+        builder_jobs = @jobs.dup
+
+        # Define helper methods that will be available
+        find_start_jobs_proc = lambda do |jobs|
+          jobs.select { |j| j[:needs].nil? || j[:needs].empty? }
+            .map { |j| j[:id] }
+        end
+
+        find_end_jobs_proc = lambda do |jobs|
+          jobs.select { |j| j[:outputs_to_workflow] || j[:terminates] }
+            .map { |j| j[:id] }
+        end
+
+        configure_inputs_proc = lambda do |job_dsl, inputs_config|
+          return unless inputs_config
+
+          case inputs_config
+          when :workflow, "workflow"
+            job_dsl.inputs_from_workflow
+          when String
+            job_dsl.inputs_from_job(inputs_config)
+          when Hash
+            if inputs_config[:from_job]
+              job_dsl.inputs_from_job(inputs_config[:from_job])
+            elsif inputs_config[:from_multiple]
+              job_dsl.inputs_from_multiple(inputs_config[:from_multiple])
+            end
+          end
+        end
+
+        Class.new(Fractor::Workflow) do
+          workflow builder_name do
+            input_type builder_input_type if builder_input_type
+            output_type builder_output_type if builder_output_type
+
+            # Determine start and end jobs
+            start_jobs = find_start_jobs_proc.call(builder_jobs)
+            end_jobs = find_end_jobs_proc.call(builder_jobs)
+
+            start_with(*start_jobs) if start_jobs.any?
+
+            end_jobs.each do |end_job|
+              end_with end_job, on: :success
+            end
+
+            # Define each job
+            builder_jobs.each do |job_config|
+              job_id = job_config[:id]
+              worker_class = job_config[:worker]
+              needs_list = job_config[:needs]
+              inputs_config = job_config[:inputs]
+              condition_proc = job_config[:condition]
+              outputs = job_config[:outputs_to_workflow]
+              terminates_flag = job_config[:terminates]
+
+              job job_id do
+                runs_with worker_class if worker_class
+
+                if needs_list
+                  needs_array = needs_list.is_a?(Array) ? needs_list : [needs_list]
+                  needs(*needs_array)
+                end
+
+                configure_inputs_proc.call(self, inputs_config)
+
+                if_condition condition_proc if condition_proc
+
+                outputs_to_workflow if outputs || end_jobs.include?(job_id)
+                terminates_workflow if terminates_flag || end_jobs.include?(job_id)
+              end
+            end
+          end
+        end
+      end
+
+      # Validate the workflow configuration
+      def validate!
+        if @name.nil? || @name.empty?
+          raise ArgumentError,
+                "Workflow must have a name"
+        end
+        if @jobs.empty?
+          raise ArgumentError,
+                "Workflow must have at least one job"
+        end
+
+        # Check for duplicate job IDs
+        job_ids = @jobs.map { |j| j[:id] }
+        duplicates = job_ids.select { |id| job_ids.count(id) > 1 }.uniq
+        if duplicates.any?
+          raise ArgumentError,
+                "Duplicate job IDs: #{duplicates.join(', ')}"
+        end
+
+        # Check for missing dependencies
+        @jobs.each do |job|
+          needs = job[:needs]
+          next unless needs
+
+          needs_array = needs.is_a?(Array) ? needs : [needs]
+          needs_array.each do |dep|
+            unless job_ids.include?(dep)
+              raise ArgumentError,
+                    "Job '#{job[:id]}' depends on non-existent job '#{dep}'"
+            end
+          end
+        end
+
+        true
+      end
+
+      # Build and validate in one step
+      def build!
+        validate!
+        build
+      end
+
+      # Clone this builder
+      def clone
+        new_builder = self.class.new(@name)
+        new_builder.instance_variable_set(:@input_type_class, @input_type_class)
+        new_builder.instance_variable_set(:@output_type_class,
+                                          @output_type_class)
+        new_builder.instance_variable_set(:@jobs, @jobs.dup)
+        new_builder
+      end
+    end
+  end
+end

data/lib/fractor/workflow/chain_builder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Fluent API for building linear chain workflows.
+    # Simplifies creation of sequential processing pipelines.
+    #
+    # @example Using chain builder
+    #   workflow = Fractor::Workflow.chain("text-pipeline")
+    #     .step("uppercase", UppercaseWorker)
+    #     .step("reverse", ReverseWorker)
+    #     .step("finalize", FinalizeWorker)
+    #     .build
+    #
+    #   instance = workflow.new
+    #   result = instance.execute(input: data)
+    #
+    # @example Using define class method
+    #   workflow = Fractor::Workflow::ChainBuilder.define("text-pipeline") do |chain|
+    #     chain.step("uppercase", UppercaseWorker)
+    #     chain.step("reverse", ReverseWorker)
+    #     chain.step("finalize", FinalizeWorker)
+    #   end
+    class ChainBuilder
+      attr_reader :name, :steps
+
+      # Define a chain workflow using a block.
+      # This is a convenience method that creates and builds a ChainBuilder.
+      #
+      # @param name [String] The workflow name
+      # @yield [ChainBuilder] Block that receives the chain builder
+      # @return [Class] A new Workflow subclass
+      #
+      # @example
+      #   workflow = Fractor::Workflow::ChainBuilder.define("my-chain") do |chain|
+      #     chain.step("process", MyWorker)
+      #     chain.step("finalize", FinalizeWorker)
+      #   end
+      def self.define(name, &block)
+        builder = new(name)
+        builder.instance_eval(&block) if block
+        builder.build
+      end
+
+      def initialize(name)
+        @name = name
+        @steps = []
+        @input_type_class = nil
+        @output_type_class = nil
+      end
+
+      # Set the input type for the workflow
+      #
+      # @param klass [Class] The input type class
+      # @return [ChainBuilder] self for chaining
+      def input_type(klass)
+        @input_type_class = klass
+        self
+      end
+
+      # Set the output type for the workflow
+      #
+      # @param klass [Class] The output type class
+      # @return [ChainBuilder] self for chaining
+      def output_type(klass)
+        @output_type_class = klass
+        self
+      end
+
+      # Add a step to the chain
+      #
+      # @param name [String, Symbol] The step name
+      # @param worker [Class] The worker class for this step
+      # @param workers [Integer] Optional number of parallel workers
+      # @param condition [Proc] Optional conditional execution
+      # @return [ChainBuilder] self for chaining
+      def step(name, worker, workers: nil, condition: nil)
+        step_config = {
+          name: name.to_s,
+          worker: worker,
+          workers: workers,
+          condition: condition,
+        }
+        @steps << step_config
+        self
+      end
+
+      # Build the workflow class
+      #
+      # @return [Class] A new Workflow subclass
+      def build
+        chain_name = @name
+        chain_steps = @steps.dup
+        chain_input_type = @input_type_class
+        chain_output_type = @output_type_class
+
+        Class.new(Workflow) do
+          workflow chain_name do
+            input_type chain_input_type if chain_input_type
+            output_type chain_output_type if chain_output_type
+
+            # Build jobs sequentially
+            chain_steps.each_with_index do |step_config, index|
+              step_name = step_config[:name]
+              step_worker = step_config[:worker]
+              step_workers = step_config[:workers]
+              step_condition = step_config[:condition]
+
+              # Determine dependencies
+              needs_job = index.positive? ? chain_steps[index - 1][:name] : nil
+
+              job step_name, step_worker,
+                  needs: needs_job,
+                  workers: step_workers,
+                  condition: step_condition
+            end
+          end
+        end
+      end
+
+      # Validate and build in one step
+      #
+      # @return [Class] A new Workflow subclass
+      # @raise [ArgumentError] if the chain is invalid
+      def build!
+        validate!
+        build
+      end
+
+      # Validate the chain configuration
+      #
+      # @raise [ArgumentError] if validation fails
+      def validate!
+        if @name.nil? || @name.empty?
+          raise ArgumentError,
+                "Chain must have a name"
+        end
+
+        if @steps.empty?
+          raise ArgumentError,
+                "Chain must have at least one step"
+        end
+
+        # Check for duplicate step names
+        step_names = @steps.map { |s| s[:name] }
+        duplicates = step_names.select { |n| step_names.count(n) > 1 }.uniq
+        if duplicates.any?
+          raise ArgumentError,
+                "Duplicate step names: #{duplicates.join(', ')}"
+        end
+
+        # Validate workers
+        @steps.each do |step_config|
+          unless step_config[:worker]
+            raise ArgumentError,
+                  "Step '#{step_config[:name]}' must specify a worker class"
+          end
+
+          unless step_config[:worker] < Fractor::Worker
+            raise ArgumentError,
+                  "Step '#{step_config[:name]}' worker must inherit from Fractor::Worker"
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/fractor/workflow/circuit_breaker.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Fractor
+  class Workflow
+    # Circuit breaker implementation for fault tolerance
+    #
+    # The circuit breaker has three states:
+    # - Closed: Normal operation, requests pass through
+    # - Open: Failure threshold exceeded, requests fail fast
+    # - Half-Open: Testing if service recovered, limited requests allowed
+    #
+    # @example Basic usage
+    #   breaker = CircuitBreaker.new(threshold: 5, timeout: 60)
+    #   breaker.call do
+    #     # Risky operation
+    #   end
+    class CircuitBreaker
+      # Circuit breaker states
+      STATE_CLOSED = :closed
+      STATE_OPEN = :open
+      STATE_HALF_OPEN = :half_open
+
+      attr_reader :state, :failure_count, :last_failure_time,
+                  :threshold, :timeout, :half_open_calls
+
+      # Initialize a new circuit breaker
+      #
+      # @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
+      def initialize(threshold: 5, timeout: 60, half_open_calls: 3)
+        @threshold = threshold
+        @timeout = timeout
+        @half_open_calls = half_open_calls
+        @state = STATE_CLOSED
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_time = nil
+        @mutex = Mutex.new
+        @just_transitioned_to_half_open = false
+      end
+
+      # Execute a block with circuit breaker protection
+      #
+      # @yield Block to execute
+      # @return [Object] Result of the block
+      # @raise [CircuitOpenError] If circuit is open
+      def call(&)
+        check_state
+
+        if open?
+          raise CircuitOpenError,
+                "Circuit breaker is open (#{failure_count} failures)"
+        end
+
+        execute_with_breaker(&)
+      end
+
+      # Check if circuit breaker is closed
+      #
+      # @return [Boolean] True if closed
+      def closed?
+        state == STATE_CLOSED
+      end
+
+      # Check if circuit breaker is open
+      #
+      # @return [Boolean] True if open
+      def open?
+        state == STATE_OPEN
+      end
+
+      # Check if circuit breaker is half-open
+      #
+      # @return [Boolean] True if half-open
+      def half_open?
+        state == STATE_HALF_OPEN
+      end
+
+      # Reset the circuit breaker to closed state
+      def reset
+        @mutex.synchronize do
+          @state = STATE_CLOSED
+          @failure_count = 0
+          @success_count = 0
+          @last_failure_time = nil
+        end
+      end
+
+      # Get circuit breaker statistics
+      #
+      # @return [Hash] Statistics including state, counts, and timing
+      def stats
+        {
+          state: state,
+          failure_count: failure_count,
+          success_count: @success_count,
+          last_failure_time: last_failure_time,
+          threshold: threshold,
+          timeout: timeout,
+        }
+      end
+
+      private
+
+      # Check and update circuit breaker state
+      def check_state
+        @mutex.synchronize do
+          if open? && timeout_elapsed?
+            # Transition from open to half-open
+            @state = STATE_HALF_OPEN
+            @success_count = 0
+            @last_failure_time = nil # Clear to track new failures in half-open
+            @just_transitioned_to_half_open = true
+          end
+        end
+      end
+
+      # Execute block with circuit breaker logic
+      #
+      # @yield Block to execute
+      # @return [Object] Result of the block
+      def execute_with_breaker
+        result = yield
+        on_success
+        result
+      rescue StandardError => e
+        on_failure
+        raise e
+      end
+
+      # Handle successful execution
+      def on_success
+        @mutex.synchronize do
+          if half_open?
+            @success_count += 1
+            if @success_count >= half_open_calls
+              # Transition from half-open to closed
+              @state = STATE_CLOSED
+              @failure_count = 0
+            end
+          else
+            # Reset failure count on success in closed state
+            @failure_count = 0
+          end
+        end
+      end
+
+      # Handle failed execution
+      def on_failure
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_time = Time.now
+
+          if half_open?
+            if @just_transitioned_to_half_open
+              # Just transitioned to half-open, stay there to allow recovery attempt
+              @just_transitioned_to_half_open = false
+            else
+              # Already in half-open and failed again, reopen circuit
+              @state = STATE_OPEN
+            end
+          elsif @failure_count >= threshold
+            # Threshold exceeded, open circuit
+            @state = STATE_OPEN
+          end
+        end
+      end
+
+      # Check if timeout has elapsed since last failure
+      #
+      # @return [Boolean] True if timeout elapsed
+      def timeout_elapsed?
+        return false unless last_failure_time
+
+        Time.now - last_failure_time >= timeout
+      end
+    end
+
+    # Error raised when circuit breaker is open
+    class CircuitOpenError < StandardError; end
+  end
+end