DEV Community: Artur Pañach

Ruby Reactor Now Has Middlewares and OpenTelemetry — Here's Why That Matters

Artur Pañach — Wed, 17 Jun 2026 00:42:49 +0000

You've built a checkout reactor that reserves inventory, charges a card, generates a shipping label, and sends a confirmation email. It runs through Sidekiq. When something fails, compensation logic rolls it back. It works.

Then your team asks: "How many checkouts failed this week? Which step? How long does the charge step take at p99? Can we see a trace through the entire system?"

Before v0.5.0, you'd need to add logging calls to every step, build a custom Sidekiq middleware, and figure out how to correlate traces across async job boundaries. Now it's one line of config.

Enter Middlewares

Ruby Reactor 0.5.0 introduces a middleware pipeline — the same pattern that powers Rack, but designed for saga execution. A middleware is a plain Ruby object that hooks into the reactor lifecycle:

class TimingMiddleware < RubyReactor::Middleware
  def initialize(**options)
    super
    @started = {}
  end

  def on_start_step(step_name, _arguments, _context)
    @started[step_name] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  end

  def on_complete_step(step_name, _result, _context)
    started = @started.delete(step_name)
    return unless started
    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
    logger.info("step #{step_name} took #{elapsed.round(4)}s")
  end
end

This middleware times every step. Register it globally:

RubyReactor.configure do |config|
  config.middlewares = [TimingMiddleware]
end

Now every reactor — every checkout, every refund, every data import — gets step-level timing, for free.

The full lifecycle (20+ events)

Middlewares can observe the complete execution lifecycle:

Phase	Events
Reactor	`on_start_reactor`, `on_complete_reactor`, `on_failed_reactor`
Step	`on_start_step`, `on_complete_step`, `on_failed_step`, `on_retry_attempt`
Compensation	`on_start_compensation`, `on_complete_compensation`, `on_failed_compensation`
Undo	`on_start_undo`, `on_complete_undo`, `on_failed_undo`
Coordination	`on_lock_acquired`, `on_lock_failed`, `on_semaphore_acquired`, …
Async	`on_before_async_enqueue`

You can build custom logging, metrics, audit trails, and alerting — all without touching your reactor code.

Why this matters

Separation of concerns — business logic lives in steps, observability lives in middlewares
Composability — stack multiple middlewares (timing + logging + alerting) like Lego
Safety — middleware errors are caught and logged, never crash your reactor
Per-reactor override — declare middleware AuditMiddleware, level: :info on specific reactors

OpenTelemetry: Distributed Tracing, Zero Config

The most powerful middleware ships built-in: RubyReactor::OpenTelemetry.

One line of configuration:

RubyReactor.configure do |config|
  config.middlewares = [RubyReactor::OpenTelemetry]
end

That's it. Every reactor run becomes a full OpenTelemetry trace:

CheckoutReactor (span)
├── step.reserve_inventory (span)
├── step.charge_card (span)
│   └── step.charge_card.enqueue (span) ← async hand-off
├── step.generate_label (span)
└── step.send_confirmation (span)

If a step fails and compensation runs:

├── step.charge_card (span, ERROR)
├── compensate.charge_card (span)
└── undo.reserve_inventory (span)

Async boundaries? Handled.

When a reactor hands work to a Sidekiq worker — an async step, a retry, or a map element — the middleware automatically injects the trace context into the serialized payload. The worker picks it up and continues the trace. The result is a single, connected trace across processes.

Sensitive data? Redacted.

class LoginReactor < RubyReactor::Reactor
  input :email
  input :password, redact: true  # shows as [REDACTED] in traces
end

No secrets leaking into your observability platform.

Any exporter works

Ruby Reactor produces OpenTelemetry spans. Where they go is up to your OTel SDK configuration:

# Datadog, Honeycomb, Jaeger, Grafana — pick your exporter
OpenTelemetry::SDK.configure do |c|
  c.service_name = "checkout_service"
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new
    )
  )
end

What else is new in the 0.5.x line

v0.5.1 — Enhanced Validations
The input DSL got streamlined. Cleaner syntax for dry-validation schemas, better error messages when validation fails.

v0.5.2 — Nonce Lock
with_ordered_lock assigns a monotonically increasing nonce to each enqueued execution. Guarantees exactly-once processing with strict FIFO ordering — perfect for ledgers and payment processing where order matters.

Enhanced Testing
New RSpec matchers for coordination primitives: be_skipped, be_locked, have_ordered_lock_next, have_ordered_lock_in_flight, be_ordered_lock_drained. Plus sidekiq_helpers and storage_reset utilities.

Why this matters for production Ruby apps

Observability is no longer optional. If you're running business workflows in production, you need to know:

Which steps are slow? (timing middleware)
What's failing and why? (tracing + error events)
Is the system healthy? (metrics middleware)
Who changed what and when? (audit middleware)

Ruby Reactor 0.5.x gives you this without pulling in external workflow engines, without custom Sidekiq middleware, and without scattering logging calls through your business logic.

Gem: gem 'ruby_reactor', '~> 0.5'
Repo: github.com/arturictus/ruby_reactor
Middleware docs: documentation/middlewares.md

If you've been putting off observability for your Sidekiq workflows, there's no longer an excuse. ⭐ the repo and give it a try.

How to Pause and Resume Ruby Workflows Mid-Flight

Artur Pañach — Wed, 03 Jun 2026 23:20:31 +0000

Ruby Reactor 0.4.0 introduces interrupts — the first native saga pause/resume mechanism in the Ruby ecosystem.

You've built a checkout flow. The user submits their order, you reserve inventory, charge their card, and generate a shipping label. Everything's a Sidekiq job. It works.

Then you get the requirement: "After payment, wait for the fraud detection webhook before shipping."

Suddenly your clean Sidekiq pipeline needs to stop, hold state for an indeterminate amount of time, and resume when Stripe calls back. Your options are:

Polling loop (wasteful, fragile)
Split into two jobs (now you have to manage state yourself)
Temporal / AWS Step Functions (massive infrastructure lift)

None of these feel right. This is where Ruby Reactor interrupts come in.

What is an Interrupt?

An interrupt is a special step that pauses reactor execution mid-flight, persists the entire execution state to Redis, and waits for an external signal to resume. While paused, no Sidekiq jobs are running. No polling. No wasted resources.

class FraudCheckReactor < RubyReactor::Reactor
  input :order_id

  step :reserve_inventory do
    argument :order_id, input(:order_id)
    run { |args| Inventory.reserve(args[:order_id]) }
    undo { |_err, args| Inventory.release(args[:order_id]) }
  end

  step :charge_card do
    argument :order_id, input(:order_id)
    run { |args| Payment.charge(args[:order_id]) }
    undo { |_err, args| Payment.refund(args[:order_id]) }
  end

  # 👇 Pause here until Stripe calls back
  interrupt :wait_for_fraud_check do
    wait_for :charge_card
    correlation_id { |ctx| "order-#{ctx.input(:order_id)}" }
    timeout 3600, strategy: :active
    validate do
      required(:status).filled(:string, included_in?: %w[passed failed])
    end
    max_attempts 3
  end

  step :ship_order do
    argument :status, result(:wait_for_fraud_check, :status)
    run do |args|
      args[:status] == "passed" ? Shipping.create_label : Failure("Fraud check failed")
    end
    undo { |_err, args| Shipping.cancel(args[:order_id]) }
  end

  returns :ship_order
end

How It Works

1. Start the reactor:

execution = FraudCheckReactor.run(order_id: 42)
execution.status  # => :paused

The reactor runs reserve_inventory → charge_card → then pauses at wait_for_fraud_check. Everything before the interrupt is committed. The execution state is serialized to Redis.

2. Resume when the webhook arrives:

# In your Stripe webhook controller
FraudCheckReactor.continue_by_correlation_id(
  correlation_id: "order-42",
  payload: { status: "passed" },
  step_name: :wait_for_fraud_check
)

The reactor wakes up, validates the payload (using the validate schema), feeds the payload as the interrupt's result, and continues to ship_order.

Why This Matters

The interrupt pattern solves a class of problems that previously forced Ruby developers into bad choices:

Without interrupts	With interrupts
Polling loops that burn DB/Redis	Zero resource usage while waiting
Manual state management across jobs	Reactor handles all state persistence
Hard-to-debug split job chains	Single reactor definition = single mental model
No timeout handling (orphaned states)	`timeout` with `:active` or `:lazy` strategies
No validation on resume payloads	`validate` block validates incoming data

Real-World Use Cases

Webhook-driven workflows:

Stripe payment confirmation → interrupt → continue on payment_intent.succeeded
External KYC provider → interrupt → continue on verification complete
Async report generation → interrupt → continue when report URL is ready

Human-in-the-loop:

Manager approval for large transactions
Customer confirmation for subscription changes
Support agent review for flagged accounts

Long-running external jobs:

Video transcoding (submit → interrupt → continue on complete)
ML model training (kick off → interrupt → continue on model ready)

Comparison: How Others Handle This

Tool	Pause/Resume	Mechanism
Ruby Reactor 0.4.0	✅ Built-in `interrupt`	Correlation ID, Redis state, timeout
dry-transaction	❌ No support	—
Trailblazer	❌ Manual only	Custom state machine required
Temporal (Go/Node)	✅ Native	Signal-based, built into engine
AWS Step Functions	✅ Native	Task token, built into service

Ruby Reactor is the only Ruby-native library that offers this pattern without pulling in external workflow engines.

Getting Started

gem install ruby_reactor

gem 'ruby_reactor', '~> 0.4'

Full interrupt docs: github.com/arturictus/ruby_reactor

If you're building workflows that need to pause and wait for external events, give Ruby Reactor a ⭐ and try it in your next Rails app.

Discussion questions: What's your current approach to webhook-driven workflows in Ruby? Polling? Split jobs? Let me know in the comments. 👇