ruby_reactor 0.3.0 → 0.3.2

data/lib/ruby_reactor.rb

@@ -4,6 +4,11 @@ require "zeitwerk"
 require "pathname"
 require_relative "ruby_reactor/registry"
 require_relative "ruby_reactor/utils/code_extractor"
+require_relative "ruby_reactor/dsl/lockable" # Add this
+require_relative "ruby_reactor/lock"
+require_relative "ruby_reactor/semaphore"
+require_relative "ruby_reactor/period"
+require_relative "ruby_reactor/rate_limit"
 
 # Load dry-validation if available (for validation features)
 begin
@@ -20,7 +25,7 @@ rescue LoadError
 end
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("api" => "API")
+loader.inflector.inflect("api" => "API", "rspec" => "RSpec")
 loader.setup
 
 module RubyReactor
@@ -39,20 +44,76 @@ module RubyReactor
     def failure?
       false
     end
+
+    def skipped?
+      false
+    end
+
+    def to_h
+      { success: true, value: @value }
+    end
+  end
+
+  # A "clean halt" signal. Two ways to produce one:
+  #
+  #   1. Implicitly, when a reactor's `with_period` gate finds the bucket has
+  #      already been claimed. The executor short-circuits before any step
+  #      runs.
+  #
+  #   2. Explicitly, by returning `RubyReactor.Skipped(reason: "...")` from a
+  #      step's `run` block. The reactor halts immediately — no further steps,
+  #      and crucially **no compensation** of already-completed steps. Use this
+  #      when a step discovers that the rest of the workflow is not needed
+  #      (e.g. "user already opted out", "nothing to do this round") and the
+  #      partial progress is still correct to keep.
+  #
+  # Subclass of Success so callers that only check `success?` continue to work;
+  # `skipped?` distinguishes it.
+  class Skipped < Success
+    attr_reader :reason, :period_key, :step_name
+
+    def initialize(reason: nil, period_key: nil, step_name: nil)
+      super(nil)
+      @reason = reason
+      @period_key = period_key
+      @step_name = step_name
+    end
+
+    def skipped?
+      true
+    end
   end
 
   class Failure
     attr_reader :error, :retryable, :step_name, :inputs, :backtrace, :reactor_name, :step_arguments, :exception_class,
                 :file_path, :line_number, :code_snippet, :validation_errors
 
-    # rubocop:disable Metrics/ParameterLists
+    # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def initialize(error, retryable: nil, step_name: nil, inputs: {}, backtrace: nil, redact_inputs: [],
                    reactor_name: nil, step_arguments: {}, exception_class: nil,
                    file_path: nil, line_number: nil, code_snippet: nil, invalid_payload: false, validation_errors: nil)
-      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       @error = error
+
+      # Handle case where error is a serialized hash (e.g. from async failure propagation)
+      if @error.is_a?(Hash)
+        attributes = extract_attributes_from_hash(@error)
+        @error = attributes[:error]
+        retryable = attributes[:retryable] if retryable.nil?
+        step_name ||= attributes[:step_name]
+        reactor_name ||= attributes[:reactor_name]
+        inputs = attributes[:inputs] if inputs.empty?
+        step_arguments = attributes[:step_arguments] if step_arguments.empty?
+        raw_backtrace ||= attributes[:backtrace] || backtrace
+        exception_class ||= attributes[:exception_class]
+        file_path ||= attributes[:file_path]
+        line_number ||= attributes[:line_number]
+        code_snippet ||= attributes[:code_snippet]
+        validation_errors ||= attributes[:validation_errors]
+      end
+
       @retryable = if retryable.nil?
-                     error.respond_to?(:retryable?) ? error.retryable? : true
+                     @error.respond_to?(:retryable?) ? @error.retryable? : true
                    else
                      retryable
                    end
@@ -60,10 +121,10 @@ module RubyReactor
       @reactor_name = reactor_name
       @inputs = inputs
       @step_arguments = step_arguments
-      raw_backtrace = backtrace || (error.respond_to?(:backtrace) ? error.backtrace : caller)
+      raw_backtrace ||= backtrace || (@error.respond_to?(:backtrace) ? @error.backtrace : caller)
       @backtrace = filter_backtrace(raw_backtrace)
       @redact_inputs = redact_inputs
-      @exception_class = exception_class || (error.is_a?(Exception) ? error.class.name : nil)
+      @exception_class = exception_class || (@error.is_a?(Exception) ? @error.class.name : nil)
       @file_path = file_path
       @line_number = line_number
       @code_snippet = code_snippet
@@ -83,6 +144,10 @@ module RubyReactor
       @retryable
     end
 
+    def skipped?
+      false
+    end
+
     def invalid_payload?
       @invalid_payload
     end
@@ -99,6 +164,28 @@ module RubyReactor
       msg.join("\n")
     end
 
+    def to_s
+      message
+    end
+
+    def to_h
+      {
+        success: false,
+        error: error_message,
+        step_name: @step_name,
+        inputs: @inputs,
+        redact_inputs: @redact_inputs,
+        reactor_name: @reactor_name,
+        step_arguments: @step_arguments,
+        exception_class: @exception_class,
+        file_path: @file_path,
+        line_number: @line_number,
+        code_snippet: @code_snippet,
+        validation_errors: @validation_errors,
+        backtrace: @backtrace
+      }
+    end
+
     private
 
     def build_header
@@ -147,10 +234,6 @@ module RubyReactor
       msg << backtrace.take(10).map { |line| "  #{line}" }.join("\n")
     end
 
-    def to_s
-      message
-    end
-
     def filter_backtrace(backtrace)
       return backtrace if ENV["RUBY_REACTOR_DEBUG"] == "true"
       return backtrace if backtrace.nil? || backtrace.empty?
@@ -177,6 +260,26 @@ module RubyReactor
     def error_message
       @error.respond_to?(:message) ? @error.message : @error.to_s
     end
+
+    def extract_attributes_from_hash(error_hash)
+      # Ensure indifferent access
+      err = ->(k) { error_hash[k.to_s] || error_hash[k.to_sym] }
+
+      {
+        error: err[:message] || err[:error] || error_hash,
+        retryable: err[:retryable],
+        step_name: err[:step_name],
+        reactor_name: err[:reactor_name],
+        inputs: err[:inputs] || {},
+        step_arguments: err[:step_arguments] || {},
+        backtrace: err[:backtrace],
+        exception_class: err[:exception_class],
+        file_path: err[:file_path],
+        line_number: err[:line_number],
+        code_snippet: err[:code_snippet],
+        validation_errors: err[:validation_errors]
+      }
+    end
   end
 
   # Async result for background job execution
@@ -211,6 +314,12 @@ module RubyReactor
     Failure.new(error, **kwargs)
   end
 
+  # Build a `Skipped` result. Return one from a step's `run` block to halt the
+  # reactor cleanly without triggering compensation of previous steps.
+  def self.Skipped(reason: nil, **kwargs)
+    Skipped.new(reason: reason, **kwargs)
+  end
+
   def self.configure
     yield(Configuration.instance) if block_given?
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Artur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-13 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -107,7 +107,9 @@ files:
 - documentation/images/failed_order_processing.png
 - documentation/images/payment_workflow.png
 - documentation/interrupts.md
+- documentation/locks_and_semaphores.md
 - documentation/retry_configuration.md
+- documentation/testing.md
 - gui/.gitignore
 - gui/README.md
 - gui/eslint.config.js
@@ -139,7 +141,6 @@ files:
 - gui/vite.config.ts
 - gui/vitest.config.ts
 - lib/ruby_reactor.rb
-- lib/ruby_reactor/async_router.rb
 - lib/ruby_reactor/configuration.rb
 - lib/ruby_reactor/context.rb
 - lib/ruby_reactor/context_serializer.rb
@@ -147,6 +148,7 @@ files:
 - lib/ruby_reactor/dsl/compose_builder.rb
 - lib/ruby_reactor/dsl/interrupt_builder.rb
 - lib/ruby_reactor/dsl/interrupt_step_config.rb
+- lib/ruby_reactor/dsl/lockable.rb
 - lib/ruby_reactor/dsl/map_builder.rb
 - lib/ruby_reactor/dsl/reactor.rb
 - lib/ruby_reactor/dsl/step_builder.rb
@@ -170,6 +172,7 @@ files:
 - lib/ruby_reactor/executor/retry_manager.rb
 - lib/ruby_reactor/executor/step_executor.rb
 - lib/ruby_reactor/interrupt_result.rb
+- lib/ruby_reactor/lock.rb
 - lib/ruby_reactor/map/collector.rb
 - lib/ruby_reactor/map/dispatcher.rb
 - lib/ruby_reactor/map/element_executor.rb
@@ -177,10 +180,19 @@ files:
 - lib/ruby_reactor/map/helpers.rb
 - lib/ruby_reactor/map/result_enumerator.rb
 - lib/ruby_reactor/max_retries_exhausted_failure.rb
+- lib/ruby_reactor/period.rb
+- lib/ruby_reactor/rate_limit.rb
 - lib/ruby_reactor/reactor.rb
 - lib/ruby_reactor/registry.rb
 - lib/ruby_reactor/retry_context.rb
 - lib/ruby_reactor/retry_queued_result.rb
+- lib/ruby_reactor/rspec.rb
+- lib/ruby_reactor/rspec/helpers.rb
+- lib/ruby_reactor/rspec/matchers.rb
+- lib/ruby_reactor/rspec/step_executor_patch.rb
+- lib/ruby_reactor/rspec/test_subject.rb
+- lib/ruby_reactor/semaphore.rb
+- lib/ruby_reactor/sidekiq_adapter.rb
 - lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb
 - lib/ruby_reactor/sidekiq_workers/map_element_worker.rb
 - lib/ruby_reactor/sidekiq_workers/map_execution_worker.rb
@@ -191,6 +203,7 @@ files:
 - lib/ruby_reactor/storage/adapter.rb
 - lib/ruby_reactor/storage/configuration.rb
 - lib/ruby_reactor/storage/redis_adapter.rb
+- lib/ruby_reactor/storage/redis_locking.rb
 - lib/ruby_reactor/template/base.rb
 - lib/ruby_reactor/template/dynamic_source.rb
 - lib/ruby_reactor/template/element.rb