active_durable 0.5.0

data/lib/active_durable/sweeper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  # The safety net. Finds executions that should be running but have no job: the process died between
+  # the commit and the enqueue, a timer job was lost, or a worker crashed and its lease expired.
+  # Enqueuing twice is harmless: only one worker can claim the lease.
+  module Sweeper
+    module_function
+
+    def call(now: ActiveDurable.now)
+      quiet = Execution.active
+                       .where("locked_until IS NULL OR locked_until < ?", now)
+                       .where("updated_at < ?", now - ActiveDurable.config.sweep_grace.to_f)
+      due = quiet.where(status: %w[pending running])
+                 .or(quiet.where(wake_at: ..now))
+                 .or(quiet.where(status: "waiting", id: SignalRecord.pending.select(:execution_id)))
+      ids = due.pluck(:id)
+      ids.each { |id| ActiveDurable.enqueue(id) }
+      ids
+    end
+  end
+end

data/lib/active_durable/testing.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "active_durable"
+
+module ActiveDurable
+  # Helpers for your test suite. require "active_durable/testing" in spec_helper.rb / test_helper.rb.
+  module Testing
+    # Raised at a crash point. It inherits from Exception so nothing in your code or ours rescues it,
+    # exactly like a process that dies.
+    class SimulatedCrash < Exception; end # rubocop:disable Lint/InheritException
+
+    module_function
+
+    # Forget simulated time and crash hooks. Call it before each test.
+    def reset!
+      ActiveDurable.time_offset = 0.0
+      ActiveDurable.crash_hook = nil
+    end
+
+    # Moves ActiveDurable's clock forward without sleeping.
+    def travel(seconds)
+      ActiveDurable.time_offset = ActiveDurable.time_offset + seconds.to_f
+    end
+
+    # Runs an execution synchronously until it finishes, fast-forwarding sleeps, retries and expired
+    # leases. Signals given as { name => payload } are delivered when the saga waits for them.
+    # Returns the execution; it stays "waiting" if it waits for a signal you did not provide.
+    def drain(execution_id, signals: {}, max_runs: 500)
+      signals = signals.transform_keys(&:to_s)
+      max_runs.times do
+        execution = Execution.find(execution_id)
+        return execution if execution.terminal?
+        return execution unless ready_for_next_run?(execution, signals)
+
+        Runner.run(execution_id)
+      end
+      raise Error, "execution #{execution_id} did not settle after #{max_runs} runs"
+    end
+
+    # Runs the saga once without failures to find every crash point, then once more per crash point,
+    # crashing there and resuming with a new worker. Yields each finished execution and the point.
+    #
+    #   ActiveDurable::Testing.crash_everywhere(:checkout, order_id: order.id) do |execution, point|
+    #     expect(FakeStripe.charges_per_ticket.values).to all(eq 1)
+    #   end
+    def crash_everywhere(recipe, signals: {}, **input)
+      points = []
+      discovery = with_crash_hook(->(kind, name) { points << [kind, name] }) do
+        drain(start_quietly(recipe, input), signals: signals)
+      end
+      yield discovery, nil if block_given?
+
+      points.each_with_index.map do |point, index|
+        execution = crash_at(recipe, input, index + 1, signals)
+        yield execution, point if block_given?
+        execution
+      end.unshift(discovery)
+    end
+
+    def crash_at(recipe, input, hit_number, signals)
+      id = start_quietly(recipe, input)
+      hits = 0
+      crash = lambda do |kind, name|
+        hits += 1
+        raise SimulatedCrash, "simulated crash at #{kind} :#{name}" if hits == hit_number
+      end
+      begin
+        with_crash_hook(crash) { drain(id, signals: signals) }
+      rescue SimulatedCrash
+        nil
+      end
+      drain(id, signals: signals)
+    end
+
+    def start_quietly(recipe, input)
+      previous = ActiveDurable.enqueue_disabled
+      ActiveDurable.enqueue_disabled = true
+      ActiveDurable.start(recipe, **input).id
+    ensure
+      ActiveDurable.enqueue_disabled = previous
+    end
+
+    def with_crash_hook(hook)
+      previous = ActiveDurable.crash_hook
+      ActiveDurable.crash_hook = hook
+      yield
+    ensure
+      ActiveDurable.crash_hook = previous
+    end
+
+    # Decides what has to happen before the next run. Returns false when nothing can move the execution.
+    def ready_for_next_run?(execution, signals)
+      now = ActiveDurable.now
+      if execution.locked_until && execution.locked_until > now
+        travel(execution.locked_until - now + 0.001) # a crashed worker still holds the lease
+      elsif execution.status == "waiting"
+        return waiting_can_move?(execution, signals, now)
+      elsif execution.wake_at && execution.wake_at > now
+        travel(execution.wake_at - now + 0.001)
+      end
+      true
+    end
+
+    def waiting_can_move?(execution, signals, now)
+      return true if SignalRecord.pending.exists?(execution_id: execution.id)
+
+      waiting = execution.steps.find_by(status: "waiting")
+      if waiting && signals.key?(waiting.name)
+        ActiveDurable.signal(execution.id, waiting.name, signals[waiting.name])
+      elsif execution.wake_at
+        travel(execution.wake_at - now + 0.001) if execution.wake_at > now
+      else
+        return false
+      end
+      true
+    end
+  end
+end

data/lib/active_durable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  VERSION = "0.5.0"
+end

data/lib/active_durable.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "logger" # concurrent-ruby 1.3.5+ no longer loads it, and older Active Support expects it
+require "securerandom"
+require "set"
+require "time"
+require "active_support"
+require "active_support/core_ext"
+require "active_record"
+require "active_job"
+
+require_relative "active_durable/version"
+require_relative "active_durable/errors"
+require_relative "active_durable/configuration"
+require_relative "active_durable/serializer"
+require_relative "active_durable/retry_policy"
+require_relative "active_durable/registry"
+require_relative "active_durable/lease"
+require_relative "active_durable/notebook"
+require_relative "active_durable/flow"
+require_relative "active_durable/parallel"
+require_relative "active_durable/flow_parallel"
+require_relative "active_durable/runner"
+require_relative "active_durable/sweeper"
+require_relative "active_durable/operations"
+
+# Durable sagas for Rails. See README.md.
+module ActiveDurable
+  # Loaded on first use: defining them at require time would load ActiveRecord::Base and
+  # ActiveJob::Base before a Rails app has applied its configuration.
+  autoload :Record, File.expand_path("active_durable/record", __dir__)
+  autoload :Execution, File.expand_path("active_durable/execution", __dir__)
+  autoload :Step, File.expand_path("active_durable/step", __dir__)
+  autoload :SignalRecord, File.expand_path("active_durable/signal_record", __dir__)
+  autoload :RunJob, File.expand_path("active_durable/run_job", __dir__)
+  autoload :SweepJob, File.expand_path("active_durable/sweep_job", __dir__)
+
+  class << self
+    attr_writer :time_offset
+    attr_accessor :crash_hook, :enqueue_disabled
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # Defines a recipe. Assign the result to a constant (CheckoutSaga = Durable.define(:checkout) { ... })
+    # so Rails can autoload it in any process.
+    #
+    # To change a recipe while executions are in flight, keep the old block and add a new version:
+    # new executions use the highest version, and every execution keeps running the version it started with.
+    def define(name, version: 1, &)
+      registry.define(name, version: version, &)
+    end
+
+    # { ["checkout", 1] => 12, ["checkout", 2] => 340 }: executions that are not finished yet (active or
+    # blocked) per recipe version. A version can be deleted once it no longer appears here.
+    def versions_in_use
+      Execution.where(status: Execution::ACTIVE + %w[blocked]).group(:recipe, :recipe_version).count
+               .transform_keys { |(recipe, version)| [recipe, version.to_i] }
+    end
+
+    # Starts a saga. Call it inside the transaction that creates your record: the saga row is committed
+    # with it, and the job is enqueued only after the commit. Pass id: to make the call idempotent.
+    def start(name, id: nil, **input)
+      recipe = registry.latest(name)
+      attributes = { recipe: recipe.name, recipe_version: recipe.version, status: "pending",
+                     input: Serializer.normalize(input, "input") }
+      return Execution.create!(attributes.merge(id: "#{recipe.name}-#{SecureRandom.uuid}")) if id.nil?
+
+      execution = Execution.create_or_find_by!(id: id.to_s) { |record| record.assign_attributes(attributes) }
+      return execution if execution.recipe == recipe.name
+
+      raise ArgumentError, "execution #{id} already exists for recipe :#{execution.recipe}"
+    end
+
+    # Delivers a signal to a saga waiting (now or later) in flow.wait_for(name).
+    def signal(execution_id, name, payload = nil)
+      execution = Execution.find(execution_id)
+      raise Error, "execution #{execution_id} already finished (#{execution.status})" if execution.terminal?
+
+      SignalRecord.create!(execution_id: execution.id, name: name.to_s,
+                           payload: Serializer.normalize(payload, "signal payload"))
+    end
+
+    def find(execution_id)
+      Execution.find(execution_id)
+    end
+
+    # See ActiveDurable::Operations.
+    def retry(execution_id)
+      Operations.retry(execution_id)
+    end
+
+    def compensate(execution_id, reason: "compensated by an operator")
+      Operations.compensate(execution_id, reason: reason)
+    end
+
+    def rerun(execution_id, from:)
+      Operations.rerun(execution_id, from: from)
+    end
+
+    def now
+      config.clock.call + time_offset
+    end
+
+    def time_offset
+      @time_offset ||= 0.0
+    end
+
+    # Objects with #capture (called in the worker thread) and #wrap(captured) { } (called around each
+    # flow.parallel branch thread). Used to carry context such as OpenTelemetry spans into the branches.
+    def branch_wrappers
+      @branch_wrappers ||= []
+    end
+
+    def enqueue(execution_id, wait_until: nil)
+      return if enqueue_disabled
+
+      job = wait_until ? RunJob.set(wait_until: wait_until) : RunJob
+      job.perform_later(execution_id)
+    end
+
+    def instrument(event, payload = {}, &)
+      ActiveSupport::Notifications.instrument("#{event}.active_durable", payload, &)
+    end
+
+    # Hook used by ActiveDurable::Testing to simulate crashes at precise points.
+    def crash_point(kind, name)
+      crash_hook&.call(kind, name)
+    end
+  end
+end
+
+# The short name used in recipes. Skipped if your app already defines a Durable constant.
+Durable = ActiveDurable unless defined?(Durable)
+
+require_relative "active_durable/engine" if defined?(Rails::Engine)

data/lib/generators/active_durable/install/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveDurable
+  module Generators
+    # rails generate active_durable:install
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates the migration for ActiveDurable's tables (sagas, notebook and signals)."
+
+      def create_migration_file
+        migration_template "create_active_durable_tables.rb.tt", "db/migrate/create_active_durable_tables.rb",
+                           migration_version: migration_version
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/generators/active_durable/install/templates/create_active_durable_tables.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class CreateActiveDurableTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    # One row per saga run. It is also the buzón: create it in the same transaction as your record.
+    create_table :durable_executions, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :recipe, null: false
+      t.integer :recipe_version, null: false, default: 1
+      t.string :status, null: false
+      t.boolean :compensating, null: false, default: false
+      t.column :input, json_type
+      t.column :output, json_type
+      t.column :error, json_type
+      t.datetime :wake_at, precision: 6
+      t.datetime :locked_until, precision: 6
+      t.string :lease_token
+      t.string :forked_from
+      t.timestamps precision: 6
+    end
+    add_index :durable_executions, %i[status wake_at]
+    add_index :durable_executions, %i[recipe status]
+    add_index :durable_executions, :forked_from
+
+    # The notebook: one row per step (and per undo) of an execution.
+    create_table :durable_steps do |t|
+      t.string :execution_id, null: false
+      t.string :name, null: false
+      t.string :kind, null: false
+      t.integer :position
+      t.string :status, null: false
+      t.integer :attempts, null: false, default: 0
+      t.column :result, json_type
+      t.column :error, json_type
+      t.datetime :wake_at, precision: 6
+      t.timestamps precision: 6
+    end
+    add_index :durable_steps, %i[execution_id name], unique: true
+    add_index :durable_steps, %i[execution_id position]
+    add_foreign_key :durable_steps, :durable_executions, column: :execution_id, on_delete: :cascade
+
+    # Signals for flow.wait_for. They can arrive before the saga starts waiting.
+    create_table :durable_signals do |t|
+      t.string :execution_id, null: false
+      t.string :name, null: false
+      t.column :payload, json_type
+      t.datetime :consumed_at, precision: 6
+      t.datetime :created_at, null: false, precision: 6
+    end
+    add_index :durable_signals, %i[execution_id name consumed_at]
+    add_foreign_key :durable_signals, :durable_executions, column: :execution_id, on_delete: :cascade
+  end
+
+  private
+
+  # jsonb on PostgreSQL, json elsewhere. No database defaults on these columns: MySQL rejects them.
+  def json_type
+    connection.adapter_name.downcase.include?("postg") ? :jsonb : :json
+  end
+end

data/lib/tasks/active_durable.rake

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+namespace :active_durable do
+  desc "List recipe versions that unfinished executions still use, so you know when an old version can go"
+  task versions: :environment do
+    in_use = ActiveDurable.versions_in_use
+    if in_use.empty?
+      puts "No unfinished executions."
+    else
+      in_use.sort.each do |(recipe, version), count|
+        defined = ActiveDurable.registry.versions_for(recipe).any? { |r| r.version == version }
+        puts format("%-30<recipe>s v%-4<version>d %6<count>d unfinished%<warning>s",
+                    recipe: recipe, version: version, count: count,
+                    warning: defined ? "" : "  <- NOT DEFINED: these executions will block")
+      end
+    end
+  end
+
+  desc "Enqueue executions that should be running but have no job (run it every minute)"
+  task sweep: :environment do
+    ids = ActiveDurable::Sweeper.call
+    puts "ActiveDurable: enqueued #{ids.size} execution(s)"
+  end
+end

data/sig/active_durable.rbs

@@ -0,0 +1,4 @@
+module ActiveDurable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: active_durable
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- William Romero
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: |
+  ActiveDurable runs multi-step business flows (checkouts, onboarding, payouts) as durable sagas
+  stored in your own database. Completed steps are checkpointed and never repeated after a crash,
+  failures before the point of no return are compensated in reverse order, and failures after it
+  are retried. No Redis and no extra servers: just Active Record and Active Job.
+email:
+- williamromerovela@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/active_durable/application_controller.rb
+- app/controllers/active_durable/executions_controller.rb
+- app/helpers/active_durable/dashboard_helper.rb
+- app/views/active_durable/executions/index.html.erb
+- app/views/active_durable/executions/show.html.erb
+- app/views/layouts/active_durable/application.html.erb
+- config/routes.rb
+- lib/active_durable.rb
+- lib/active_durable/configuration.rb
+- lib/active_durable/engine.rb
+- lib/active_durable/errors.rb
+- lib/active_durable/execution.rb
+- lib/active_durable/flow.rb
+- lib/active_durable/flow_parallel.rb
+- lib/active_durable/lease.rb
+- lib/active_durable/notebook.rb
+- lib/active_durable/open_telemetry.rb
+- lib/active_durable/operations.rb
+- lib/active_durable/parallel.rb
+- lib/active_durable/record.rb
+- lib/active_durable/registry.rb
+- lib/active_durable/retry_policy.rb
+- lib/active_durable/run_job.rb
+- lib/active_durable/runner.rb
+- lib/active_durable/serializer.rb
+- lib/active_durable/signal_record.rb
+- lib/active_durable/step.rb
+- lib/active_durable/sweep_job.rb
+- lib/active_durable/sweeper.rb
+- lib/active_durable/testing.rb
+- lib/active_durable/version.rb
+- lib/generators/active_durable/install/install_generator.rb
+- lib/generators/active_durable/install/templates/create_active_durable_tables.rb.tt
+- lib/tasks/active_durable.rake
+- sig/active_durable.rbs
+homepage: https://github.com/williamromero/active_durable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/williamromero/active_durable
+  source_code_uri: https://github.com/williamromero/active_durable
+  changelog_uri: https://github.com/williamromero/active_durable/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/williamromero/active_durable/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.7
+signing_key:
+specification_version: 4
+summary: 'Durable sagas for Rails: finish the work or undo it in order, even if the
+  server dies.'
+test_files: []