ruby_reactor 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de5c91a5450cb522097965aa4348760438b60babd05da33f9f7ec1a07fe9bd07
-  data.tar.gz: d565e81c6ba6e057b56912311bf16dee95ce0c441eb76f2b893658b751568b2c
+  metadata.gz: 729d8c7da4954534a2775a360d79fc96326d76b5ca69c7361ca0433e4bd6571e
+  data.tar.gz: e9e545d2ea937135f19c7c04697993125fdfc38d57fc71d6a7b0aede9bf5efa9
 SHA512:
-  metadata.gz: dde49e045303aeb4bcf414ea30b7d85d8fb8a782f873dd9ebb4a9d7d0524e74de37ba4e53ddc11ac6dea360bf1226f946d0c50e74e685da2ac70394065f436d6
-  data.tar.gz: 7b9b0b5bf75866876bdc1811dfc1118272963337431148f480d6570e19bfc2e9d93a6fdfd91a3629734501a590e23be579b98ff2e2f4f125831410351e0e6865
+  metadata.gz: 23aac29ebf4c4e018fc3ab4bffbc46d79fa68ea74d783034fb984094cb7d97e791fc194c767ab59fb4992be267c171f6cbcc1897fb6160df4bedeb88faa3f080
+  data.tar.gz: edffc8600293e035e1d318a4f4b7f7240ec67aa06704e941465e06c6eadda16e1939c36e2a826bd0b92183728360cb3babab4b26b877548559f61a64f2977c4a

data/.release-please-config.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "include-component-in-tag": false,
+  "include-v-in-tag": true,
+  "always-update": true,
+  "packages": {
+    ".": {
+      "release-type": "ruby",
+      "package-name": "ruby_reactor",
+      "version-file": "lib/ruby_reactor/version.rb",
+      "changelog-path": "CHANGELOG.md",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": false,
+      "draft": false,
+      "prerelease": false
+    }
+  }
+}

data/.release-please-manifest.json

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

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.8

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.4.1](https://github.com/arturictus/ruby_reactor/compare/v0.4.0...v0.4.1) (2026-05-25)
+
+
+### Bug Fixes
+
+* trigger release pipeline ([#29](https://github.com/arturictus/ruby_reactor/issues/29)) ([862478b](https://github.com/arturictus/ruby_reactor/commit/862478b3d0811b00e920119057bf4c1bfb1808af))
+* trigger release workflows ([#31](https://github.com/arturictus/ruby_reactor/issues/31)) ([ed44dcd](https://github.com/arturictus/ruby_reactor/commit/ed44dcd00e3288e2fab99f9794821943dacc1d4b))
+
+## [0.4.0](https://github.com/arturictus/ruby_reactor/compare/ruby_reactor-v0.3.2...ruby_reactor/v0.4.0) (2026-05-17)
+
+
+### Features
+
+* `AsyncResult` returning intermediate_results ([#10](https://github.com/arturictus/ruby_reactor/issues/10)) ([0cb96d6](https://github.com/arturictus/ruby_reactor/commit/0cb96d66e88097665998601276e38e1c2249c581))
+* enhance deserialization error handling in Sidekiq worker ([#23](https://github.com/arturictus/ruby_reactor/issues/23)) ([60dde95](https://github.com/arturictus/ruby_reactor/commit/60dde95606d52cc6a9d352ad0117b4092a1ebb9d))
+* Enhance failure messages with step, reactor, redacted inputs, a… ([#11](https://github.com/arturictus/ruby_reactor/issues/11)) ([952feae](https://github.com/arturictus/ruby_reactor/commit/952feaeb6ebbe5fbe2daf470263d8e769ba64138))
+* Introduce reactor interrupt functionality, allowing pausing and… ([#13](https://github.com/arturictus/ruby_reactor/issues/13)) ([53d0861](https://github.com/arturictus/ruby_reactor/commit/53d0861f0238f0e2247e581b0a27cba2f42cfba6))
+* Rspec helpers ([#19](https://github.com/arturictus/ruby_reactor/issues/19)) ([cb71f80](https://github.com/arturictus/ruby_reactor/commit/cb71f80c0708dacf6c10c0beac88446b00f30f54))
+* Web Dashboard ([#14](https://github.com/arturictus/ruby_reactor/issues/14)) ([80255dd](https://github.com/arturictus/ruby_reactor/commit/80255dd40800af8f6ed804de9c6f151331742fd5))

data/README.md

@@ -132,22 +132,40 @@ puts result.value  # => "Hello from Ruby Reactor!"
 
 ## Web Dashboard
 
-RubyReactor comes with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps.
+RubyReactor ships with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps. The dashboard is a Rack app (a [Roda](https://roda.jeremyevans.net/) application) bundled inside the gem with its pre-compiled JS/CSS assets — no extra install or asset build step is required.
 
 ### Rails Installation
 
-Mount the dashboard engine in your `config/routes.rb`:
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "ruby_reactor"
+```
+
+Then mount the dashboard in your `config/routes.rb`:
 
 ```ruby
 Rails.application.routes.draw do
   # ... other routes
-  mount RubyReactor::Web::Application => '/ruby_reactor'
+  mount RubyReactor::Web::Application => "/ruby_reactor"
 end
 ```
 
+That's it — visit `/ruby_reactor` and the UI loads. `RubyReactor::Web::Application` is autoloaded by Zeitwerk on first reference, so no extra `require` is needed.
+
+### Rack / Sinatra / Standalone
+
+Because it's a plain Rack app, you can mount it anywhere `call(env)` is accepted:
+
+```ruby
+# config.ru
+require "ruby_reactor/web/application"
+run RubyReactor::Web::Application
+```
+
 ![RubyReactor Dashboard Screenshot](documentation/images/failed_order_processing.png)
 
-You can secure the dashboard using standard Rails authentication methods (e.g., `authenticate` block with Devise).
+You can secure the dashboard using standard Rails authentication methods (e.g., wrapping the `mount` line in an `authenticate` block with Devise, or in a `constraints` block).
 
 ## Usage
 
@@ -871,6 +889,64 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Running Redis for the test suite
+
+The gem's RSpec suite expects Redis on port `6780` (see [spec/spec_helper.rb](spec/spec_helper.rb)). Start it via Docker Compose:
+
+```bash
+docker compose up -d redis-test
+```
+
+Then run the suite:
+
+```bash
+bundle exec rspec
+```
+
+Stop it when done:
+
+```bash
+docker compose stop redis-test
+```
+
+### Running the demo Rails app
+
+The demo Rails app under [demo_app/](demo_app/) has its own Redis (port `6380`) and bind-mounts the repo so edits to `lib/` are live. Two ways to run it:
+
+**Option A — fully containerized (Redis + Rails + Sidekiq):**
+
+```bash
+docker compose up demo-redis demo-app demo-sidekiq
+```
+
+App available at <http://localhost:3789>.
+
+**Option B — Redis in Docker, Rails on host:**
+
+```bash
+docker compose up -d demo-redis
+
+cd demo_app
+bin/rails db:prepare
+REDIS_URL=redis://localhost:6380/1 bin/rails server
+# in another shell, if you need Sidekiq:
+REDIS_URL=redis://localhost:6380/1 bundle exec sidekiq
+```
+
+To run the demo app specs:
+
+```bash
+cd demo_app
+bundle exec rspec
+```
+
+Tear everything down:
+
+```bash
+docker compose down          # stop containers
+docker compose down -v       # also remove demo_redis_data + bundle_cache volumes
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/arturictus/ruby_reactor. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/arturictus/ruby_reactor/blob/main/CODE_OF_CONDUCT.md).

data/lib/ruby_reactor/context.rb

@@ -5,7 +5,7 @@ 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, :status, :failure_reason
+                  :cancelled, :cancellation_reason, :parent_context_id, :retried_from_id, :status, :failure_reason
 
     def initialize(inputs = {}, reactor_class = nil)
       @context_id = SecureRandom.uuid
@@ -29,6 +29,7 @@ module RubyReactor
       @failure_reason = nil
       @parent_context = nil
       @parent_context_id = nil
+      @retried_from_id = nil
       @root_context = nil
     end
 
@@ -119,7 +120,8 @@ module RubyReactor
         cancellation_reason: @cancellation_reason,
         status: @status,
         failure_reason: ContextSerializer.serialize_value(@failure_reason),
-        parent_context_id: @parent_context&.context_id || @parent_context_id
+        parent_context_id: @parent_context&.context_id || @parent_context_id,
+        retried_from_id: @retried_from_id
       }
     end
 
@@ -144,6 +146,7 @@ module RubyReactor
       context.status = data["status"] || "pending"
       context.failure_reason = ContextSerializer.deserialize_value(data["failure_reason"])
       context.parent_context_id = data["parent_context_id"]
+      context.retried_from_id = data["retried_from_id"]
 
       context
     end

data/lib/ruby_reactor/context_serializer.rb

@@ -145,7 +145,7 @@ module RubyReactor
             when "Regexp"
               Regexp.new(value["source"], value["options"])
             when "GlobalID"
-              GlobalID::Locator.locate(value["gid"])
+              locate_global_id(value["gid"])
             when "Template::Element"
               RubyReactor::Template::Element.new(value["map_name"], value["path"])
             when "Template::Input"
@@ -181,23 +181,76 @@ module RubyReactor
       def simplify_for_api(value)
         case value
         when Hash
-          value.each_with_object({}) do |(k, v), hash|
+          simplified = value.each_with_object({}) do |(k, v), hash|
             hash[k.to_s] = simplify_for_api(v)
           end
+          enrich_failure_for_api(simplified)
         when Array
           value.map { |v| simplify_for_api(v) }
         when Success, Failure, Context
-          simplify_for_api(value.to_h)
+          enrich_failure_for_api(simplify_for_api(value.to_h))
         when Symbol
           value.to_s
         else
           value
         end
       end
+
+      def enrich_failure_for_api(hash)
+        return hash unless hash.is_a?(Hash)
+        return hash unless failure_payload?(hash)
+
+        hash = flatten_typed_failure(hash) if hash["_type"] == "Failure"
+
+        if hash["code_snippet"].is_a?(Array) && !hash["code_snippet"].empty?
+          return hash
+        end
+
+        file_path, line_number = resolve_failure_location(hash)
+        return hash unless file_path && line_number
+
+        snippet = RubyReactor::Utils::CodeExtractor.extract(file_path, line_number)
+        return hash unless snippet
+
+        normalized_snippet = snippet.map { |line| line.transform_keys(&:to_s) }
+
+        hash.merge(
+          "file_path" => file_path,
+          "line_number" => line_number,
+          "code_snippet" => normalized_snippet
+        )
+      end
+
+      def failure_payload?(hash)
+        hash["_type"] == "Failure" || (hash.key?("step_name") && hash["backtrace"].is_a?(Array))
+      end
+
+      def flatten_typed_failure(hash)
+        flattened = hash.dup
+        flattened.delete("_type")
+        flattened.merge("message" => hash["error"] || hash["message"])
+      end
+
+      def resolve_failure_location(hash)
+        file_path = hash["file_path"]
+        line_number = hash["line_number"]
+        return [file_path, line_number] if file_path && line_number
+
+        RubyReactor::Utils::BacktraceLocation.extract(hash["backtrace"])
+      end
       # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
       private
 
+      def locate_global_id(gid)
+        unless defined?(GlobalID::Locator)
+          raise RubyReactor::Error::DeserializationError,
+                "globalid gem is required to deserialize GlobalID values (gid: #{gid})"
+        end
+
+        GlobalID::Locator.locate(gid)
+      end
+
       def validate_size(data)
         size = data.bytesize
         return if size <= MAX_CONTEXT_SIZE

data/lib/ruby_reactor/dsl/reactor.rb

@@ -152,12 +152,21 @@ module RubyReactor
         # Entry point for running the reactor
         def run(inputs = {})
           reactor = new
-          reactor.run(inputs)
+          result = reactor.run(inputs)
+          attach_execution_id!(result, reactor.context.context_id)
         end
 
         def call(inputs = {})
           run(inputs)
         end
+
+        def attach_execution_id!(result, execution_id)
+          return result if result.respond_to?(:execution_id) && result.execution_id
+
+          result.define_singleton_method(:execution_id) { execution_id }
+          result
+        end
+        private :attach_execution_id!
       end
     end
   end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -189,18 +189,7 @@ module RubyReactor
       end
 
       def extract_location(backtrace)
-        return [nil, nil] unless backtrace && !backtrace.empty?
-
-        # Filter out internal reactor frames if needed, or just take the first one
-        # For now, let's take the first line of the backtrace which should be the error source
-        # But we might want to skip our own internal frames if we want to point to user code
-        # Let's start with the top frame, assuming backtrace is already correct (from original error)
-
-        first_line = backtrace.first
-        match = first_line.match(/^(.+?):(\d+)(?::in `.*')?$/)
-        return [nil, nil] unless match
-
-        [match[1], match[2].to_i]
+        RubyReactor::Utils::BacktraceLocation.extract(backtrace)
       end
     end
   end

data/lib/ruby_reactor/executor.rb

@@ -75,7 +75,7 @@ module RubyReactor
       @result
     ensure
       release_locks
-      save_context
+      save_context if persist_context?
     end
 
     def resume_execution
@@ -134,6 +134,12 @@ module RubyReactor
       storage.store_context(@context.context_id, serialized_context, reactor_class_name)
     end
 
+    def persist_context?
+      @context.status.to_s != "pending" ||
+        @context.execution_trace.any? ||
+        @context.intermediate_results.any?
+    end
+
     private
 
     def acquire_locks

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -60,6 +60,7 @@ module RubyReactor
       end
 
       def [](index)
+        index += count if index.negative?
         return nil if index.negative? || index >= count
 
         results = @storage.retrieve_map_results_batch(
@@ -80,15 +81,15 @@ module RubyReactor
       end
 
       def last
-        self[count - 1]
+        self[-1]
       end
 
       def successes
-        lazy.select { |result| result.is_a?(RubyReactor::Success) }.map(&:value)
+        lazy.grep(RubyReactor::Success).map(&:value)
       end
 
       def failures
-        lazy.select { |result| result.is_a?(RubyReactor::Failure) }.map(&:error)
+        lazy.grep(RubyReactor::Failure).map(&:error)
       end
 
       private

data/lib/ruby_reactor/rate_limit.rb

@@ -15,7 +15,7 @@ module RubyReactor
     class ExceededError < StandardError
       attr_reader :retry_after_seconds, :key_base, :limit, :period_seconds, :period_name
 
-      def initialize(message, retry_after_seconds:, key_base:, limit:, period_seconds:, period_name:)
+      def initialize(message, retry_after_seconds:, key_base:, limit:, period_seconds:, period_name:) # rubocop:disable Metrics/ParameterLists
         super(message)
         @retry_after_seconds = retry_after_seconds
         @key_base = key_base
@@ -42,7 +42,7 @@ module RubyReactor
       @limits.each do |spec|
         argv << spec[:period_seconds]
         argv << spec[:limit]
-        argv << spec[:period_seconds] * 2 # TTL: generous, auto-cleans stale buckets
+        argv << (spec[:period_seconds] * 2) # TTL: generous, auto-cleans stale buckets
       end
 
       allowed, retry_after, failed_index = adapter.rate_limit_check_and_increment(keys, argv)

data/lib/ruby_reactor/reactor.rb

@@ -10,10 +10,17 @@ module RubyReactor
 
     def self.find(id)
       reactor_class_name = name
-      serialized_context = configuration.storage_adapter.retrieve_context(id, reactor_class_name)
-      raise Error::ValidationError, "Context '#{id}' not found" unless serialized_context
-
-      context = Context.deserialize_from_retry(serialized_context)
+      raw_data = configuration.storage_adapter.retrieve_context(id, reactor_class_name)
+      raise Error::ValidationError, "Context '#{id}' not found" unless raw_data
+
+      context = case raw_data
+                when String
+                  ContextSerializer.deserialize(raw_data)
+                when Hash
+                  Context.deserialize_from_retry(raw_data)
+                else
+                  raise Error::ValidationError, "Invalid context format for '#{id}'"
+                end
       new(context)
     end
 

data/lib/ruby_reactor/sidekiq_workers/worker.rb

@@ -18,7 +18,16 @@ module RubyReactor
       end
 
       def perform(serialized_context, reactor_class_name = nil, snooze_count = 0)
-        context = ContextSerializer.deserialize(serialized_context)
+        begin
+          context = ContextSerializer.deserialize(serialized_context)
+        rescue RubyReactor::Error::DeserializationError,
+               RubyReactor::Error::SchemaVersionError => e
+          # Permanent failures — retrying the same blob will keep failing.
+          # Mark the context as failed (best-effort) and return so Sidekiq
+          # does not burn its retry budget.
+          handle_deserialization_failure(serialized_context, reactor_class_name, e)
+          return
+        end
 
         # If reactor_class_name is provided, use it to get the reactor class
         # This handles cases where the class can't be found via const_get
@@ -110,6 +119,54 @@ module RubyReactor
         RubyReactor.configuration.logger.error("RubyReactor infrastructure failure: #{exception.message}")
         RubyReactor.configuration.logger.error("Job details: #{msg.inspect}")
       end
+
+      def handle_deserialization_failure(serialized_context, reactor_class_name, error)
+        metadata = extract_failure_metadata(serialized_context)
+        context_id = metadata[:context_id]
+        resolved_reactor_class_name = reactor_class_name || metadata[:reactor_class_name]
+
+        RubyReactor.configuration.logger.error(
+          "RubyReactor deserialization failure for context " \
+          "#{context_id || "unknown"}: #{error.class.name}: #{error.message}"
+        )
+
+        return unless context_id && resolved_reactor_class_name
+
+        payload = build_failed_context_payload(context_id, resolved_reactor_class_name, error)
+        RubyReactor.configuration.storage_adapter.store_context(
+          context_id,
+          payload,
+          resolved_reactor_class_name
+        )
+      rescue StandardError => e
+        # Don't let a persistence failure mask the original deserialization error.
+        RubyReactor.configuration.logger.error(
+          "RubyReactor failed to persist deserialization failure: #{e.class.name}: #{e.message}"
+        )
+      end
+
+      def extract_failure_metadata(serialized_context)
+        data = JSON.parse(serialized_context)
+        {
+          context_id: data["context_id"],
+          reactor_class_name: data["reactor_class"]
+        }
+      rescue StandardError
+        {}
+      end
+
+      def build_failed_context_payload(context_id, reactor_class_name, error)
+        JSON.generate(
+          "schema_version" => ContextSerializer::SCHEMA_VERSION,
+          "context_id" => context_id,
+          "reactor_class" => reactor_class_name,
+          "status" => "failed",
+          "failure_reason" => {
+            "message" => error.message,
+            "exception_class" => error.class.name
+          }
+        )
+      end
     end
   end
 end

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -196,13 +196,20 @@ module RubyReactor
       end
 
       def determine_status(data)
-        return data["status"] if data["status"] && %w[failed paused completed running].include?(data["status"])
+        status = data["status"].to_s
+        return status if status && %w[failed paused completed running skipped pending].include?(status)
         return "cancelled" if data["cancelled"]
         # Heuristic
         return "failed" if data["retry_count"]&.positive? && !data["current_step"].nil?
-        return "completed" unless data["current_step"]
+        return "running" if data["current_step"]
+        return "completed" if execution_evidence?(data)
 
-        "running"
+        "pending"
+      end
+
+      def execution_evidence?(data)
+        (data["execution_trace"] || []).any? ||
+          (data["intermediate_results"] || {}).any?
       end
 
       def store_map_element_context_id(map_id, context_id, reactor_class_name)

data/lib/ruby_reactor/storage/redis_locking.rb

@@ -245,6 +245,23 @@ module RubyReactor
       def period_marker?(key_base, every, now: Time.now.utc)
         @redis.exists?(RubyReactor::Period.key(key_base, every, now: now))
       end
+
+      # TTL in seconds for a held lock (-2 if key does not exist).
+      def lock_ttl(prefixed_key)
+        @redis.ttl(prefixed_key)
+      end
+
+      # TTL in seconds for the current rate-limit bucket (-2 if unset).
+      def rate_limit_ttl(key_base, every, now: Time.now.to_i)
+        period_seconds = RubyReactor::Period.period_seconds(every)
+        bucket = now / period_seconds
+        @redis.ttl("rate:#{key_base}:#{every}:#{bucket}")
+      end
+
+      # TTL in seconds for a period marker (-2 if unset).
+      def period_ttl(key_base, every, now: Time.now.utc)
+        @redis.ttl(RubyReactor::Period.key(key_base, every, now: now))
+      end
     end
     # rubocop:enable Naming/PredicateMethod
   end

data/lib/ruby_reactor/utils/backtrace_location.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Utils
+    class BacktraceLocation
+      # Ruby 3.x backtraces use single-quoted method names; older formats use backticks.
+      LINE_PATTERN = /^(.+?):(\d+)(?::in .*)?$/
+
+      def self.parse(line)
+        match = line.match(LINE_PATTERN)
+        return nil unless match
+
+        [match[1], match[2].to_i]
+      end
+
+      def self.internal_path?(file_path)
+        file_path.start_with?(RubyReactor.internal_lib_path)
+      end
+
+      def self.extract(backtrace)
+        return [nil, nil] unless backtrace.is_a?(Array) && backtrace.any?
+
+        skip_internal = ENV["RUBY_REACTOR_DEBUG"] != "true"
+
+        backtrace.each do |line|
+          file_path, line_number = parse(line)
+          next unless file_path
+          next if skip_internal && internal_path?(file_path)
+
+          return [file_path, line_number]
+        end
+
+        parse(backtrace.first) || [nil, nil]
+      end
+    end
+  end
+end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.3.2"
+  VERSION = "0.4.1"
 end