ruby_reactor 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de5c91a5450cb522097965aa4348760438b60babd05da33f9f7ec1a07fe9bd07
-  data.tar.gz: d565e81c6ba6e057b56912311bf16dee95ce0c441eb76f2b893658b751568b2c
+  metadata.gz: 7769f6488ce48db7f07cd9a7bb9774f697cadc6433293ca926a9e1c27b28ce3e
+  data.tar.gz: 9dd0d5edd43c8b7629474ca2c12dd8f1c755d43f7fab3bc33aaefb86a183ba7c
 SHA512:
-  metadata.gz: dde49e045303aeb4bcf414ea30b7d85d8fb8a782f873dd9ebb4a9d7d0524e74de37ba4e53ddc11ac6dea360bf1226f946d0c50e74e685da2ac70394065f436d6
-  data.tar.gz: 7b9b0b5bf75866876bdc1811dfc1118272963337431148f480d6570e19bfc2e9d93a6fdfd91a3629734501a590e23be579b98ff2e2f4f125831410351e0e6865
+  metadata.gz: afbabcc37d4dbba1a6fcb83fb15b88160979802b7cd5d69fd0aed47538080c4abd3196b40a7f7464047f94c2aafa6d5317e825446179e9129a960c0e5d119742
+  data.tar.gz: caef3d4d35e37a0c9bc35b273ad20f8a0dc31810e35cf2ea1b50df57d347762c85d2a42aa6b3125401e324725d0e8f17f9d1acfecb5f8f3bafeeaf9a7308a5d2

data/.release-please-config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "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.0"
+}

data/.tool-versions

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

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [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_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"
@@ -198,6 +198,15 @@ module RubyReactor
 
       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/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/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/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Artur
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -89,57 +88,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".release-please-config.json"
+- ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - README.md
 - Rakefile
-- documentation/DAG.md
-- documentation/README.md
-- documentation/async_reactors.md
-- documentation/composition.md
-- documentation/core_concepts.md
-- documentation/data_pipelines.md
-- documentation/examples/inventory_management.md
-- documentation/examples/order_processing.md
-- documentation/examples/payment_processing.md
-- documentation/getting_started.md
-- 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
-- gui/index.html
-- gui/package-lock.json
-- gui/package.json
-- gui/postcss.config.js
-- gui/public/vite.svg
-- gui/src/App.css
-- gui/src/App.tsx
-- gui/src/assets/react.svg
-- gui/src/components/DagVisualizer.tsx
-- gui/src/components/Dashboard.tsx
-- gui/src/components/ErrorBoundary.tsx
-- gui/src/components/ReactorDetail.tsx
-- gui/src/components/StepInspector.tsx
-- gui/src/components/__tests__/DagVisualizer.test.tsx
-- gui/src/components/__tests__/ReactorDetail.test.tsx
-- gui/src/components/__tests__/StepInspector.test.tsx
-- gui/src/globals.d.ts
-- gui/src/index.css
-- gui/src/lib/utils.ts
-- gui/src/main.tsx
-- gui/src/test/setup.ts
-- gui/tailwind.config.js
-- gui/tsconfig.app.json
-- gui/tsconfig.json
-- gui/tsconfig.node.json
-- gui/vite.config.ts
-- gui/vitest.config.ts
 - lib/ruby_reactor.rb
 - lib/ruby_reactor/configuration.rb
 - lib/ruby_reactor/context.rb
@@ -233,7 +190,6 @@ metadata:
   homepage_uri: https://github.com/arturictus/ruby_reactor
   source_code_uri: https://github.com/arturictus/ruby_reactor
   changelog_uri: https://github.com/arturictus/ruby_reactor/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -248,8 +204,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A dynamic, concurrent, dependency-resolving saga orchestrator for Ruby.
 test_files: []