active_durable 0.5.0 → 0.6.0

data/lib/active_durable/sweeper.rb

@@ -4,19 +4,39 @@ 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.
+  #
+  # @api private
   module Sweeper
     module_function
 
     def call(now: ActiveDurable.now)
+      ids = due(now: now)
+      ids.each { |id| ActiveDurable.enqueue(id) }
+      ids
+    end
+
+    # The rake task. With the :async adapter (the Rails default in development) a job lives in the memory of the
+    # process that enqueued it, and this process ends as soon as the task does: run the executions here instead.
+    def call_from_task(now: ActiveDurable.now)
+      return [call(now: now), :enqueued] unless in_process_adapter?
+
+      ids = due(now: now)
+      ids.each { |id| RunJob.perform_now(id) }
+      [ids, :ran]
+    end
+
+    def in_process_adapter?
+      RunJob.queue_adapter.is_a?(ActiveJob::QueueAdapters::AsyncAdapter)
+    end
+
+    def due(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
+      ready = quiet.where(status: %w[pending running])
+                   .or(quiet.where(wake_at: ..now))
+                   .or(quiet.where(status: "waiting", id: SignalRecord.pending.select(:execution_id)))
+      ready.pluck(:id)
     end
   end
 end

data/lib/active_durable/testing.rb

@@ -57,6 +57,7 @@ module ActiveDurable
       end.unshift(discovery)
     end
 
+    # @api private
     def crash_at(recipe, input, hit_number, signals)
       id = start_quietly(recipe, input)
       hits = 0
@@ -72,6 +73,9 @@ module ActiveDurable
       drain(id, signals: signals)
     end
 
+    # Starts an execution without enqueuing its job, so a test drives it with {drain}.
+    #
+    # @return [String] the execution id
     def start_quietly(recipe, input)
       previous = ActiveDurable.enqueue_disabled
       ActiveDurable.enqueue_disabled = true
@@ -80,6 +84,7 @@ module ActiveDurable
       ActiveDurable.enqueue_disabled = previous
     end
 
+    # @api private
     def with_crash_hook(hook)
       previous = ActiveDurable.crash_hook
       ActiveDurable.crash_hook = hook
@@ -89,6 +94,8 @@ module ActiveDurable
     end
 
     # Decides what has to happen before the next run. Returns false when nothing can move the execution.
+    #
+    # @api private
     def ready_for_next_run?(execution, signals)
       now = ActiveDurable.now
       if execution.locked_until && execution.locked_until > now
@@ -101,6 +108,7 @@ module ActiveDurable
       true
     end
 
+    # @api private
     def waiting_can_move?(execution, signals, now)
       return true if SignalRecord.pending.exists?(execution_id: execution.id)
 

data/lib/active_durable/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module ActiveDurable
-  VERSION = "0.5.0"
+  # The gem's version.
+  VERSION = "0.6.0"
 end

data/lib/active_durable.rb

@@ -22,9 +22,27 @@ 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/pruner"
 require_relative "active_durable/operations"
 
-# Durable sagas for Rails. See README.md.
+# Durable sagas for Rails: finish the work or undo it in order, even if the server dies.
+#
+# Define a recipe with {define}, start it with {start}, and operate it with {retry}, {compensate}, {rerun} and
+# {prune}. Inside a recipe, every call goes through a {Flow}. `Durable` is a short alias of this module.
+#
+# @example
+#   CheckoutSaga = Durable.define(:checkout) do |flow, order_id:|
+#     order = Order.find(order_id)
+#     flow.transaction(:reserve_stock, undo: -> { order.release_stock! }) { order.reserve_stock! }
+#     flow.step(:charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) }) do |ticket|
+#       Payments.charge(order, ticket)
+#     end
+#   end
+#
+#   Order.transaction do
+#     order = Order.create!(order_params)
+#     Durable.start(:checkout, id: "checkout-#{order.id}", order_id: order.id)
+#   end
 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.
@@ -34,41 +52,77 @@ module ActiveDurable
   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__)
+  autoload :PruneJob, File.expand_path("active_durable/prune_job", __dir__)
 
   class << self
+    # @api private
     attr_writer :time_offset
+    # @api private
     attr_accessor :crash_hook, :enqueue_disabled
 
+    # The settings of the whole gem.
+    #
+    # @return [Configuration]
     def config
       @config ||= Configuration.new
     end
 
+    # Changes the settings, usually in config/initializers/active_durable.rb.
+    #
+    # @yieldparam config [Configuration]
+    # @return [void]
+    # @example
+    #   ActiveDurable.configure do |config|
+    #     config.queue_name = :sagas
+    #     config.lease_duration = 10.minutes
+    #   end
     def configure
       yield config
     end
 
+    # @api private
     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.
+    # Defines a recipe: the steps of a saga. Assign the result to a constant (CheckoutSaga = Durable.define(:checkout)
+    # { ... }) in app/sagas/checkout_saga.rb, 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.
+    # 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.
+    #
+    # @param name [Symbol, String] the recipe name, used by {start}
+    # @param version [Integer] the recipe version
+    # @yieldparam flow [Flow] the object every step goes through
+    # @yieldparam input [Hash] the keyword arguments given to {start}, with string keys turned into keywords
+    # @return [Recipe] assign it to a constant
+    # @raise [ArgumentError] without a block or a name
     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.
+    # Executions that are not finished yet (active or blocked) per recipe version. A version can be deleted once it
+    # no longer appears here. `bin/rails active_durable:versions` prints it.
+    #
+    # @return [Hash{Array(String, Integer) => Integer}] for example { ["checkout", 1] => 12, ["checkout", 2] => 340 }
     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.
+    # Starts a saga. Call it inside the transaction that creates your record: the saga row is committed with it,
+    # and its job is enqueued only after the commit, so a crash in between cannot lose it.
+    #
+    # @param name [Symbol, String] a recipe given to {define}
+    # @param id [String, nil] the execution id. With one, the call is idempotent: starting the same id twice returns
+    #   the first execution. Without one, a random id is used.
+    # @param input [Hash] keyword arguments for the recipe; stored as JSON
+    # @return [Execution]
+    # @raise [UnknownRecipe] if no recipe has that name
+    # @raise [ArgumentError] if the id already belongs to an execution of another recipe
+    # @raise [NotSerializable] if the input cannot be stored as JSON
+    # @example
+    #   Durable.start(:checkout, id: "checkout-#{order.id}", order_id: order.id)
     def start(name, id: nil, **input)
       recipe = registry.latest(name)
       attributes = { recipe: recipe.name, recipe_version: recipe.version, status: "pending",
@@ -81,7 +135,17 @@ module ActiveDurable
       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).
+    # Delivers a signal to a saga waiting, now or later, in flow.wait_for(name). A signal that arrives before the
+    # saga waits is kept until it does.
+    #
+    # @param execution_id [String]
+    # @param name [Symbol, String] the name given to {Flow#wait_for}
+    # @param payload [Object] what wait_for returns; stored as JSON
+    # @return [void]
+    # @raise [ActiveRecord::RecordNotFound] if there is no such execution
+    # @raise [Error] if the execution already finished
+    # @example In a webhook controller
+    #   Durable.signal("loan-42", :kyc_done, verified: true)
     def signal(execution_id, name, payload = nil)
       execution = Execution.find(execution_id)
       raise Error, "execution #{execution_id} already finished (#{execution.status})" if execution.terminal?
@@ -90,37 +154,74 @@ module ActiveDurable
                            payload: Serializer.normalize(payload, "signal payload"))
     end
 
+    # @param execution_id [String]
+    # @return [Execution]
+    # @raise [ActiveRecord::RecordNotFound]
     def find(execution_id)
       Execution.find(execution_id)
     end
 
-    # See ActiveDurable::Operations.
+    # Resumes a blocked execution where it stopped: failed steps (or failed undos, if it was undoing) get a fresh
+    # set of attempts. Use it after fixing what blocked it, such as a bug in the recipe or a failing hook.
+    #
+    # @param execution_id [String]
+    # @return [Execution]
+    # @raise [Error] if the execution is not blocked, or a worker is running it right now
     def retry(execution_id)
       Operations.retry(execution_id)
     end
 
+    # Undoes every finished step of an execution that has not passed its point of no return, last one first, and
+    # then runs its flow.on(:compensated) hook.
+    #
+    # @param execution_id [String]
+    # @param reason [String] recorded as the execution's error
+    # @return [Execution]
+    # @raise [Error] if it already passed flow.pivot, is already undoing, or a worker is running it right now
     def compensate(execution_id, reason: "compensated by an operator")
       Operations.compensate(execution_id, reason: reason)
     end
 
+    # Starts a new execution that reuses the original's steps before `from` and runs `from` and the following ones
+    # again, with new tickets (so they have effects again). A blocked original becomes superseded.
+    #
+    # @param execution_id [String]
+    # @param from [Symbol, String] a step in the original's notebook
+    # @return [Execution] the new execution
+    # @raise [Error] if the original has no such step, is active, or a worker is running it right now
     def rerun(execution_id, from:)
       Operations.rerun(execution_id, from: from)
     end
 
+    # Deletes finished executions (completed, compensated, superseded) older than `older_than`, with their notebook
+    # and signals. Active and blocked executions are never deleted. {PruneJob} calls it with the default.
+    #
+    # @param older_than [ActiveSupport::Duration, Numeric] seconds; config.keep_finished_for by default
+    # @return [Integer] how many executions were deleted
+    # @raise [ArgumentError] if older_than is nil
+    def prune(older_than: config.keep_finished_for)
+      Pruner.call(older_than: older_than)
+    end
+
+    # @api private
     def now
       config.clock.call + time_offset
     end
 
+    # @api private
     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.
+    #
+    # @api private
     def branch_wrappers
       @branch_wrappers ||= []
     end
 
+    # @api private
     def enqueue(execution_id, wait_until: nil)
       return if enqueue_disabled
 
@@ -128,11 +229,14 @@ module ActiveDurable
       job.perform_later(execution_id)
     end
 
+    # @api private
     def instrument(event, payload = {}, &)
       ActiveSupport::Notifications.instrument("#{event}.active_durable", payload, &)
     end
 
     # Hook used by ActiveDurable::Testing to simulate crashes at precise points.
+    #
+    # @api private
     def crash_point(kind, name)
       crash_hook&.call(kind, name)
     end

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

@@ -4,6 +4,7 @@ require "rails/generators"
 require "rails/generators/active_record"
 
 module ActiveDurable
+  # Rails generators: `active_durable:install` for new apps, `active_durable:upgrade` after updating the gem.
   module Generators
     # rails generate active_durable:install
     class InstallGenerator < Rails::Generators::Base
@@ -12,6 +13,7 @@ module ActiveDurable
       source_root File.expand_path("templates", __dir__)
       desc "Creates the migration for ActiveDurable's tables (sagas, notebook and signals)."
 
+      # @api private
       def create_migration_file
         migration_template "create_active_durable_tables.rb.tt", "db/migrate/create_active_durable_tables.rb",
                            migration_version: migration_version

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

@@ -19,6 +19,7 @@ class CreateActiveDurableTables < ActiveRecord::Migration<%= migration_version %
       t.timestamps precision: 6
     end
     add_index :durable_executions, %i[status wake_at]
+    add_index :durable_executions, %i[status updated_at]
     add_index :durable_executions, %i[recipe status]
     add_index :durable_executions, :forked_from
 

data/lib/generators/active_durable/upgrade/templates/add_active_durable_prune_index.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# ActiveDurable 0.6: finds finished executions to prune, and quiet ones to sweep, without scanning the table.
+class AddActiveDurablePruneIndex < ActiveRecord::Migration<%= migration_version %>
+  def up
+    add_index :durable_executions, %i[status updated_at] unless index_exists?(:durable_executions, %i[status updated_at])
+  end
+
+  def down
+    return unless index_exists?(:durable_executions, %i[status updated_at])
+
+    remove_index :durable_executions, column: %i[status updated_at]
+  end
+end

data/lib/generators/active_durable/upgrade/upgrade_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveDurable
+  module Generators
+    # rails generate active_durable:upgrade
+    #
+    # Adds the migrations a newer ActiveDurable needs to an app that installed an older one. It skips the ones the
+    # app already has, and each migration checks the database first, so running it twice changes nothing.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Adds the migrations that newer ActiveDurable versions need. Run it after updating the gem."
+
+      # In the order they were released. Never edit one that shipped: add a new one.
+      MIGRATIONS = %w[add_active_durable_prune_index].freeze
+
+      # @api private
+      def create_migration_files
+        MIGRATIONS.each do |name|
+          if self.class.migration_exists?(File.join(destination_root, "db/migrate"), name)
+            say_status :skip, "db/migrate/*_#{name}.rb (already there)", :yellow
+          else
+            migration_template "#{name}.rb.tt", "db/migrate/#{name}.rb", migration_version: migration_version
+          end
+        end
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::Migration.current_version}]"
+      end
+    end
+  end
+end

data/lib/tasks/active_durable.rake

@@ -16,9 +16,20 @@ namespace :active_durable do
     end
   end
 
+  desc "Delete finished executions older than config.keep_finished_for, with their notebook (run it daily)"
+  task prune: :environment do
+    days = (ActiveDurable.config.keep_finished_for.to_f / 86_400).round(2)
+    days = days.to_i if days == days.to_i
+    puts "ActiveDurable: deleted #{ActiveDurable.prune} finished execution(s) older than #{days} days"
+  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)"
+    ids, how = ActiveDurable::Sweeper.call_from_task
+    if how == :ran
+      puts "ActiveDurable: ran #{ids.size} execution(s) in this process (the :async adapter would lose their jobs)"
+    else
+      puts "ActiveDurable: enqueued #{ids.size} execution(s)"
+    end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_durable
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - William Romero
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -17,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -31,6 +36,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +46,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -45,6 +56,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -52,6 +66,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 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,
@@ -63,6 +80,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -86,6 +104,8 @@ files:
 - lib/active_durable/open_telemetry.rb
 - lib/active_durable/operations.rb
 - lib/active_durable/parallel.rb
+- lib/active_durable/prune_job.rb
+- lib/active_durable/pruner.rb
 - lib/active_durable/record.rb
 - lib/active_durable/registry.rb
 - lib/active_durable/retry_policy.rb
@@ -100,18 +120,18 @@ files:
 - 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/generators/active_durable/upgrade/templates/add_active_durable_prune_index.rb.tt
+- lib/generators/active_durable/upgrade/upgrade_generator.rb
 - lib/tasks/active_durable.rake
 - sig/active_durable.rbs
-homepage: https://github.com/williamromero/active_durable
+homepage: https://webresstudio.github.io/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
+  source_code_uri: https://github.com/webresstudio/active_durable
+  changelog_uri: https://github.com/webresstudio/active_durable/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/webresstudio/active_durable/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -126,8 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Durable sagas for Rails: finish the work or undo it in order, even if the
   server dies.'