ruby_reactor 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 729d8c7da4954534a2775a360d79fc96326d76b5ca69c7361ca0433e4bd6571e
-  data.tar.gz: e9e545d2ea937135f19c7c04697993125fdfc38d57fc71d6a7b0aede9bf5efa9
+  metadata.gz: 134fc0713b22bad85e193592696b24417cb3c30afe8e1e7cec41328df4dafeb5
+  data.tar.gz: 469b9dc316a61f0814b964ff1afd9292bf4a98790807e367ffda3c575c62e4f5
 SHA512:
-  metadata.gz: 23aac29ebf4c4e018fc3ab4bffbc46d79fa68ea74d783034fb984094cb7d97e791fc194c767ab59fb4992be267c171f6cbcc1897fb6160df4bedeb88faa3f080
-  data.tar.gz: edffc8600293e035e1d318a4f4b7f7240ec67aa06704e941465e06c6eadda16e1939c36e2a826bd0b92183728360cb3babab4b26b877548559f61a64f2977c4a
+  metadata.gz: 6c28f483542f87de327e23554783dfffc1d92b89c181c85d1317763aaa0a4f824f07cfbc8dbc9589f9b814bae2d4debe11acaf87c84a9b9f6b7a501110a71ff4
+  data.tar.gz: b856bce9fb30b8e2e8e1b27d01b4801ffa87e95b2214cccddd73d1b0447b5801dd3f90a722977e6955786b81e70b60ac2339450552df216df37fb334a05735b5

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.1"
+  ".": "0.5.0"
 }

data/.rubocop.yml

@@ -14,6 +14,7 @@ AllCops:
     - db/**/*
     - config/**/*
     - demo_app/**/*
+    - .ruby-lsp/**/*
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0](https://github.com/arturictus/ruby_reactor/compare/v0.4.1...v0.5.0) (2026-06-11)
+
+
+### Features
+
+* Middlewares & OpenTelemetry ([#32](https://github.com/arturictus/ruby_reactor/issues/32)) ([a9e10ce](https://github.com/arturictus/ruby_reactor/commit/a9e10ceb6fa6381ead57a5905931343f8d1182d1))
+
 ## [0.4.1](https://github.com/arturictus/ruby_reactor/compare/v0.4.0...v0.4.1) (2026-05-25)
 
 

data/README.md

@@ -475,6 +475,8 @@ end
 
 By using `async true` with `batch_size`, the system applies **Back Pressure** to efficiently manage resources. [Read more about Back Pressure & Resource Management](documentation/data_pipelines.md#back-pressure--resource-management).
 
+`batch_size` is optional: with `async true` alone, RubyReactor fans out one worker per element (defaulting the batch size to the full source size) and aggregates the outcomes into a `ResultEnumerator` — convenient for small collections, but with no back pressure. See [Async Without `batch_size`](documentation/data_pipelines.md#async-without-batch_size).
+
 #### Map with Dynamic Source (ActiveRecord)
 
 You can use a block for `source` to dynamically fetch data, such as from ActiveRecord queries. The result is wrapped in a `ResultEnumerator` for easy access to successes and failures.
@@ -859,6 +861,10 @@ Comprehensive guide to testing reactors with RubyReactor's testing utilities. Le
 
 Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), and calendar-bucketed dedup (`with_period`, returning `Skipped` results). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, and once-per-day/month/year scheduling patterns.
 
+### [Middlewares & OpenTelemetry](documentation/middlewares.md)
+
+Hook into the execution lifecycle with observer middlewares. Covers the full set of lifecycle events (reactor, step, retry, compensation/undo, async hand-off, locks/semaphores), writing and registering custom middlewares (global and per-reactor), and the built-in `RubyReactor::OpenTelemetry` tracing middleware — span structure, input/argument redaction, distributed trace propagation across async/retry boundaries, and custom exporters.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -871,7 +877,7 @@ Coordinate access to shared resources across processes with Redis-backed primiti
 - [X] `map` step to iterate over arrays in parallel
 - [X] `compose` special step to execute reactors as step
 - [X] `interrupt` to pause and resume reactors
-- [ ] Middlewares
+- [X] Middlewares
 - [ ] Async ruby to parallelize same level steps
 - [x] Web dashboard to inspect reactor results and errors
 - [ ] Multiple storage adapters
@@ -880,7 +886,7 @@ Coordinate access to shared resources across processes with Redis-backed primiti
 - [ ] Multiple Async adapters
   - [X] Sidekiq
   - [ ] ActiveJob
-- [ ] OpenTelemetry support
+- [X] OpenTelemetry support
 - [X] locks
 
 ## Development

data/lib/ruby_reactor/configuration.rb

@@ -8,7 +8,8 @@ module RubyReactor
     include Singleton
 
     attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
-                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts
+                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts,
+                :middlewares
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
@@ -54,5 +55,9 @@ module RubyReactor
                              raise "Unknown storage adapter: #{storage.adapter}"
                            end
     end
+
+    def middlewares
+      @middlewares ||= []
+    end
   end
 end

data/lib/ruby_reactor/context.rb

@@ -5,7 +5,8 @@ module RubyReactor
     attr_accessor :inputs, :intermediate_results, :private_data, :current_step, :retry_count, :concurrency_key,
                   :retry_context, :reactor_class, :execution_trace, :inline_async_execution, :undo_stack,
                   :parent_context, :root_context, :composed_contexts, :context_id, :map_operations, :map_metadata,
-                  :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason
+                  :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason,
+                  :middlewares
 
     def initialize(inputs = {}, reactor_class = nil)
       @context_id = SecureRandom.uuid

data/lib/ruby_reactor/context_serializer.rb

@@ -202,9 +202,7 @@ module RubyReactor
 
         hash = flatten_typed_failure(hash) if hash["_type"] == "Failure"
 
-        if hash["code_snippet"].is_a?(Array) && !hash["code_snippet"].empty?
-          return hash
-        end
+        return hash if hash["code_snippet"].is_a?(Array) && !hash["code_snippet"].empty?
 
         file_path, line_number = resolve_failure_location(hash)
         return hash unless file_path && line_number

data/lib/ruby_reactor/dsl/reactor.rb

@@ -123,8 +123,12 @@ module RubyReactor
           @return_step
         end
 
-        def middleware(middleware_class)
-          middlewares << middleware_class
+        def middleware(middleware_class, **options)
+          middlewares << if options.empty?
+                           middleware_class
+                         else
+                           [middleware_class, options]
+                         end
         end
 
         def validate_inputs(inputs_hash)

data/lib/ruby_reactor/executor/compensation_manager.rb

@@ -51,61 +51,89 @@ module RubyReactor
 
       private
 
+      def middlewares
+        @context.middlewares || RubyReactor::MiddlewareRunner.new([])
+      end
+
       def compensate_step(step_config, error, arguments)
-        compensate_result = if step_config.compensate_block
-                              step_config.compensate_block.call(error, arguments, @context)
-                            elsif step_config.has_impl?
-                              step_config.impl.compensate(error, arguments, @context)
-                            else
-                              RubyReactor.Success() # Default compensation
-                            end
-
-        # Ensure we have a value to log
-        logged_result = if compensate_result.respond_to?(:value)
-                          compensate_result.value
-                        elsif compensate_result.respond_to?(:error)
-                          compensate_result.error
-                        else
-                          compensate_result
-                        end
+        middlewares.on(:start_compensation, step_config.name, error, arguments, @context)
+        begin
+          compensate_result = if step_config.compensate_block
+                                step_config.compensate_block.call(error, arguments, @context)
+                              elsif step_config.has_impl?
+                                step_config.impl.compensate(error, arguments, @context)
+                              else
+                                RubyReactor.Success() # Default compensation
+                              end
 
-        @context.execution_trace << {
-          type: :compensate,
-          step: step_config.name,
-          timestamp: Time.now,
-          result: logged_result,
-          arguments: arguments
-        }
-        @undo_trace << { type: :compensation, step: step_config.name, error: error, arguments: arguments }
-        compensate_result
+          # Ensure we have a value to log
+          logged_result = if compensate_result.respond_to?(:value)
+                            compensate_result.value
+                          elsif compensate_result.respond_to?(:error)
+                            compensate_result.error
+                          else
+                            compensate_result
+                          end
+
+          @context.execution_trace << {
+            type: :compensate,
+            step: step_config.name,
+            timestamp: Time.now,
+            result: logged_result,
+            arguments: arguments
+          }
+          @undo_trace << { type: :compensation, step: step_config.name, error: error, arguments: arguments }
+
+          if compensate_result.is_a?(RubyReactor::Failure)
+            middlewares.on(:failed_compensation, step_config.name, compensate_result, @context)
+          else
+            middlewares.on(:complete_compensation, step_config.name, compensate_result, @context)
+          end
+
+          compensate_result
+        rescue StandardError => e
+          middlewares.on(:failed_compensation, step_config.name, e, @context)
+          raise e
+        end
       end
 
       def undo_step(step_config, result, arguments)
-        undo_result = if step_config.undo_block
-                        step_config.undo_block.call(result.value, arguments, @context)
-                      elsif step_config.has_impl?
-                        step_config.impl.undo(result.value, arguments, @context)
-                      else
-                        RubyReactor.Success()
-                      end
-
-        # Ensure we have a value to log (if it's a Success/Failure object, get the value or error)
-        logged_result = if undo_result.respond_to?(:value)
-                          undo_result.value
-                        elsif undo_result.respond_to?(:error)
-                          undo_result.error
+        middlewares.on(:start_undo, step_config.name, result, arguments, @context)
+        begin
+          undo_result = if step_config.undo_block
+                          step_config.undo_block.call(result.value, arguments, @context)
+                        elsif step_config.has_impl?
+                          step_config.impl.undo(result.value, arguments, @context)
                         else
-                          undo_result
+                          RubyReactor.Success()
                         end
 
-        @context.execution_trace << { type: :undo, step: step_config.name, timestamp: Time.now, result: logged_result,
-                                      arguments: arguments }
-        undo_result
-      rescue StandardError => e
-        # Log undo failure but don't halt the rollback process
-        @context.execution_trace << { type: :undo_failure, step: step_config.name, timestamp: Time.now,
-                                      error: e.message }
-        RubyReactor.Failure(e)
+          # Ensure we have a value to log (if it's a Success/Failure object, get the value or error)
+          logged_result = if undo_result.respond_to?(:value)
+                            undo_result.value
+                          elsif undo_result.respond_to?(:error)
+                            undo_result.error
+                          else
+                            undo_result
+                          end
+
+          @context.execution_trace << { type: :undo, step: step_config.name, timestamp: Time.now, result: logged_result,
+                                        arguments: arguments }
+
+          if undo_result.is_a?(RubyReactor::Failure)
+            middlewares.on(:failed_undo, step_config.name, undo_result, @context)
+          else
+            middlewares.on(:complete_undo, step_config.name, undo_result, @context)
+          end
+
+          undo_result
+        rescue StandardError => e
+          middlewares.on(:failed_undo, step_config.name, e, @context)
+          # Log undo failure but don't halt the rollback process
+          @context.execution_trace << { type: :undo_failure, step: step_config.name, timestamp: Time.now,
+                                        error: e.message }
+          RubyReactor.Failure(e)
+        end
       end
     end
   end

data/lib/ruby_reactor/executor/retry_manager.rb

@@ -3,8 +3,9 @@
 module RubyReactor
   class Executor
     class RetryManager
-      def initialize(context)
+      def initialize(context, middlewares = nil)
         @context = context
+        @middlewares = middlewares || context.middlewares || Executor.middlewares_for(context.reactor_class)
       end
 
       def execute_with_retry(step_config, reactor_class)
@@ -47,11 +48,10 @@ module RubyReactor
                                  @context.root_context || @context
                                end
 
-        puts "SERIALIZING CONTEXT: #{context_to_serialize.reactor_class.name}"
-        puts "INPUTS KEYS: #{context_to_serialize.inputs.keys}" if context_to_serialize.respond_to?(:inputs)
-
         reactor_class_name = context_to_serialize.reactor_class.name
 
+        @middlewares.on(:before_async_enqueue, context_to_serialize)
+
         serialized_context = ContextSerializer.serialize(context_to_serialize)
 
         if @context.map_metadata
@@ -68,7 +68,8 @@ module RubyReactor
             parent_reactor_class_name: map_args[:parent_reactor_class_name],
             step_name: map_args[:step_name],
             batch_size: map_args[:batch_size],
-            serialized_context: serialized_context
+            serialized_context: serialized_context,
+            fail_fast: map_args[:fail_fast]
           )
         else
           configuration.async_router.perform_in(delay, serialized_context, reactor_class_name)
@@ -111,6 +112,15 @@ module RubyReactor
       end
 
       def handle_retryable_failure(step_config, reactor_class, result)
+        attempt_number = @context.retry_context.attempts_for_step(step_config.name)
+        @middlewares.on(
+          :retry_attempt,
+          step_config.name,
+          attempt_number,
+          result.error,
+          @context
+        )
+
         # Check if we should requeue (async retry)
         is_async = reactor_class.async? || step_config.async? ||
                    @context.root_context&.reactor_class&.async? ||

data/lib/ruby_reactor/executor/step_executor.rb

@@ -10,6 +10,7 @@ module RubyReactor
         @retry_manager = managers[:retry_manager]
         @result_handler = managers[:result_handler]
         @compensation_manager = managers[:compensation_manager]
+        @middlewares = managers[:middlewares] || context.middlewares || Executor.middlewares_for(reactor_class)
       end
 
       def execute_all_steps
@@ -61,12 +62,28 @@ module RubyReactor
           return RubyReactor.Success(@context.get_result(step_config.name))
         end
 
-        if step_config.interrupt?
-          handle_interrupt_step(step_config)
-        elsif step_config.async? && !@context.inline_async_execution
-          handle_async_step(step_config)
-        else
-          execute_step_with_retry(step_config)
+        resolved_arguments = resolve_arguments(step_config)
+
+        @middlewares.on(:start_step, step_config.name, resolved_arguments, @context)
+        completed = false
+        begin
+          result = if step_config.interrupt?
+                     handle_interrupt_step(step_config)
+                   elsif step_config.async? && !@context.inline_async_execution
+                     handle_async_step(step_config)
+                   else
+                     execute_step_with_retry(step_config, resolved_arguments)
+                   end
+          completed = true
+          if result.is_a?(RubyReactor::Failure)
+            @middlewares.on(:failed_step, step_config.name, result, @context)
+          else
+            @middlewares.on(:complete_step, step_config.name, result, @context)
+          end
+          result
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          @middlewares.on(:failed_step, step_config.name, e, @context) unless completed
+          raise
         end
       end
 
@@ -95,24 +112,22 @@ module RubyReactor
         )
       end
 
-      def execute_step_with_retry(step_config)
+      def execute_step_with_retry(step_config, resolved_arguments = nil)
+        resolved_arguments ||= resolve_arguments(step_config)
         result = @retry_manager.execute_with_retry(step_config, @reactor_class) do
-          safe_execute_step_sync(step_config)
+          safe_execute_step_sync(step_config, resolved_arguments)
         end
 
         unless result.is_a?(RetryQueuedResult) || result.is_a?(RubyReactor::AsyncResult)
-          resolved_arguments = resolve_arguments(step_config)
           @result_handler.handle_step_result(step_config, result, resolved_arguments)
         end
 
         result
       end
 
-      def safe_execute_step_sync(step_config)
-        resolved_arguments = {}
-        execute_step_sync_without_result_handling(step_config) do |args|
-          resolved_arguments = args
-        end
+      def safe_execute_step_sync(step_config, resolved_arguments = nil)
+        resolved_arguments ||= resolve_arguments(step_config)
+        execute_step_sync_without_result_handling(step_config, resolved_arguments)
       rescue StandardError => e
         # Identify redacted inputs
         redact_inputs = @reactor_class.inputs.select { |_, config| config[:redact] }.keys
@@ -127,7 +142,7 @@ module RubyReactor
         )
       end
 
-      def execute_step_sync(step_config)
+      def execute_step_sync(step_config, resolved_arguments = nil)
         @context.with_step(step_config.name) do
           # Check conditions and guards
           unless step_config.should_run?(@context)
@@ -136,7 +151,7 @@ module RubyReactor
           end
 
           # Resolve arguments
-          resolved_arguments = resolve_arguments(step_config)
+          resolved_arguments ||= resolve_arguments(step_config)
 
           # Validate arguments if validator is defined
           validate_step_arguments(step_config, resolved_arguments)
@@ -150,7 +165,7 @@ module RubyReactor
       end
 
       # Execute step without handling the result (used during retries)
-      def execute_step_sync_without_result_handling(step_config)
+      def execute_step_sync_without_result_handling(step_config, resolved_arguments = nil)
         @context.with_step(step_config.name) do
           # Check conditions and guards
           unless step_config.should_run?(@context)
@@ -159,7 +174,7 @@ module RubyReactor
           end
 
           # Resolve arguments
-          resolved_arguments = resolve_arguments(step_config)
+          resolved_arguments ||= resolve_arguments(step_config)
 
           yield resolved_arguments if block_given?
 
@@ -181,6 +196,9 @@ module RubyReactor
         context_to_serialize = @context.root_context || @context
         reactor_class_name = context_to_serialize.reactor_class.name
 
+        # Inject OTel context before serialization
+        @middlewares.on(:before_async_enqueue, context_to_serialize)
+
         serialized_context = ContextSerializer.serialize(context_to_serialize)
 
         configuration.async_router.perform_async(