active_durable 0.5.0 → 0.6.0

data/lib/active_durable/flow.rb

@@ -1,21 +1,38 @@
 # frozen_string_literal: true
 
 module ActiveDurable
-  # The object a recipe receives. Every call that touches the outside world goes through it, so it can
-  # be checkpointed in the notebook and skipped on replay.
+  # The object a recipe receives. Every call that touches the outside world goes through it, so it can be
+  # checkpointed in the notebook and skipped when the recipe runs again after a crash.
   #
+  # Step names must be unique in a recipe: they are the steps' keys in the notebook. Every step takes the options
+  # `retry:` (an Integer of attempts, `false`, or `{ attempts:, backoff: }`) and, if it has an undo,
+  # `undo_on_failure: true`.
+  #
+  # @example
   #   Durable.define :checkout do |flow, order_id:|
-  #     flow.transaction :reserve_stock, undo: -> { ... } do ... end
-  #     flow.step :charge, undo: ->(charge, ticket) { ... } do |ticket| ... end
-  #     flow.pivot(:ship) { |ticket| ... }
-  #     flow.step(:email) { ... }
+  #     order = Order.find(order_id)
+  #     flow.on(:compensated) { order.update!(status: "cancelled") }
+  #     flow.transaction :reserve_stock, undo: -> { order.release_stock! } do
+  #       order.reserve_stock!
+  #     end
+  #     flow.step :charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) } do |ticket|
+  #       Payments.charge(order, ticket)
+  #     end
+  #     flow.pivot(:ship) { |ticket| Carrier.ship(order, reference: ticket) }
+  #     flow.step(:email) { OrderMailer.shipped(order).deliver_now && true }
   #   end
   class Flow
+    # @api private
     UndoEntry = Struct.new(:name, :kind, :result, :undo)
+    # @api private
     STEP_OPTIONS = %i[retry undo_on_failure].freeze
+    # The events {#on} accepts.
+    HOOK_EVENTS = %i[completed compensated].freeze
 
+    # @api private
     attr_reader :undo_stack
 
+    # @api private
     def initialize(runner, compensating:)
       @runner = runner
       @notebook = runner.notebook
@@ -25,52 +42,134 @@ module ActiveDurable
       @position = 0
       @seen = {}
       @undo_stack = []
+      @hooks = {}
     end
 
+    # @return [String] the id of the execution this recipe is running for
     def execution_id
       @execution.id
     end
 
-    # The ticket (idempotency key) a step receives. It is the same every time the step runs.
+    # The ticket (idempotency key) a step receives: "<execution id>:<step name>". It is the same every time the
+    # step runs.
+    #
+    # @param name [Symbol, String]
+    # @return [String]
     def ticket_for(name)
       "#{execution_id}:#{name}"
     end
 
+    # @api private
     def compensating?
       @compensating
     end
 
+    # @api private
     def compensating!
       @compensating = true
     end
 
+    # @api private
     def pivoted?
       @pivoted
     end
 
-    # A step that talks to the outside world. It runs at most until it is recorded; pass the ticket to the
-    # service as its idempotency key so a repeat after a crash is recognised.
+    # A step that talks to the outside world. It runs until its result is recorded, so after a crash it may run
+    # again: pass the ticket to the service as its idempotency key, so the repeat is recognised.
+    #
+    # @param name [Symbol, String] unique in the recipe
+    # @param undo [#call, nil] how to undo it; receives (result, undo_ticket, step_ticket), as many as it declares
+    # @param options [Hash] `retry:` and `undo_on_failure:`
+    # @yieldparam ticket [String] the idempotency key of this step
+    # @yieldreturn [Object] the result, stored as JSON in the notebook
+    # @return [Object] the result, also when it was read from the notebook
+    # @raise [StepFailed] when it runs out of attempts or calls {#abort!}; rescue it to take another path
+    # @example
+    #   payment = flow.step :charge, undo: ->(charge, ticket) { Payments.refund(charge, ticket) } do |ticket|
+    #     Payments.charge(order, ticket)
+    #   end
     def step(name, undo: nil, **options, &block)
       run_step(name, "step", undo, options, block)
     end
 
-    # A step that only touches your own database. It runs in the same transaction that records it,
-    # so it happens exactly once.
+    # A step that only touches your own database. It runs in the same transaction that records it, so it happens
+    # exactly once. Its undo runs in a transaction too.
+    #
+    # @param (see #step)
+    # @yieldparam ticket [String]
+    # @yieldreturn [Object] the result, stored as JSON in the notebook
+    # @return [Object] the result
+    # @raise [StepFailed] when it runs out of attempts or calls {#abort!}
     def transaction(name, undo: nil, **options, &block)
       run_step(name, "transaction", undo, options, block)
     end
 
-    # The point of no return. Before it, failures are compensated; after it, steps are retried.
+    # The point of no return, such as shipping a parcel. Before it, a step that fails for good undoes the saga;
+    # after it, steps cannot declare an undo and are retried (config.after_pivot_attempts), then the execution is
+    # blocked for a person. If the pivot itself fails for good, the saga is undone: the point was never passed.
+    #
+    # @param name [Symbol, String]
+    # @param options [Hash] `retry:`
+    # @yieldparam ticket [String]
+    # @return [Object] the result
     def pivot(name, **options, &block)
       run_step(name, "pivot", nil, options, block)
     end
 
-    # Rejects the saga for a business reason: no retries, straight to compensation.
+    # Runs a block once the saga ends that way, to update your own records (the order is paid, the order is
+    # cancelled). Declare hooks before the first step, so a saga undone at its first step still knows them. The
+    # block runs in a transaction together with the notebook entry that records it: a hook that only touches your
+    # database runs exactly once, even across crashes. If it raises, the execution is blocked and
+    # {ActiveDurable.retry} runs it again.
+    #
+    # @param event [Symbol] :completed (after the last step) or :compensated (after the last undo)
+    # @return [nil]
+    # @raise [InvalidRecipe] after the first step, for another event, or twice for the same event
+    # @example
+    #   flow.on(:completed) { order.update!(status: "delivered") }
+    #   flow.on(:compensated) { order.update!(status: "cancelled") }
+    def on(event, &block)
+      raise InvalidRecipe, "flow.on needs a block" unless block
+      unless HOOK_EVENTS.include?(event)
+        raise InvalidRecipe, "flow.on(:#{event}): the events are :completed and :compensated"
+      end
+      if @position.positive?
+        raise InvalidRecipe, "flow.on(:#{event}) must come before the first step: when a saga is undone early, " \
+                             "the steps after the failure are never reached"
+      end
+      raise InvalidRecipe, "flow.on(:#{event}) is declared twice" if @hooks.key?(event)
+
+      @hooks[event] = block
+      nil
+    end
+
+    # @api private
+    def hook(event)
+      @hooks[event]
+    end
+
+    # Rejects the saga for a business reason, such as a declined card: no retries, straight to undoing what was
+    # done. Call it inside a step or in the recipe itself.
+    #
+    # @param message [String] recorded as the error
+    # @raise [Abort] always
+    # @example
+    #   flow.step :charge do |ticket|
+    #     Payments.charge(order, ticket)
+    #   rescue Payments::CardDeclined => e
+    #     flow.abort!(e.message)
+    #   end
     def abort!(message)
       raise Abort, message
     end
 
-    # Waits without holding a worker: the wake-up time is written down and the execution is released.
+    # Waits without holding a worker: the wake-up time is written down and the execution is released until then.
+    #
+    # @param name [Symbol, String]
+    # @param duration [ActiveSupport::Duration, Numeric] seconds
+    # @return [nil]
+    # @example
+    #   flow.sleep(:wait_for_delivery, 3.days)
     def sleep(name, duration)
       name, position = visit!(name, "sleep")
       entry = @notebook[name]
@@ -90,7 +189,13 @@ module ActiveDurable
       @runner.suspend!(wake_at, "sleeping")
     end
 
-    # Waits for Durable.signal(execution_id, name, payload) and returns the payload.
+    # Waits, without holding a worker, for {ActiveDurable.signal}(execution_id, name, payload). A signal sent
+    # before the saga gets here is kept.
+    #
+    # @param name [Symbol, String]
+    # @param timeout [ActiveSupport::Duration, Numeric, nil] seconds; then the step fails and the saga is undone
+    # @return [Object] the signal's payload
+    # @raise [StepFailed] when the timeout passes first
     def wait_for(name, timeout: nil)
       name, position = visit!(name, "wait")
       entry = @notebook[name]
@@ -118,6 +223,8 @@ module ActiveDurable
     end
 
     # Called when the recipe returns: every step the notebook knows about must have been reached.
+    #
+    # @api private
     def finish!
       return if compensating?
 
@@ -129,6 +236,7 @@ module ActiveDurable
                            "#{missing.size == 1 ? "it" : "them"}. #{RECIPE_CHANGED_HINT}"
     end
 
+    # @api private
     RECIPE_CHANGED_HINT = "Either the recipe changed while this execution was in flight, or code outside a " \
                           "step read data that changed between runs. Keep reads that decide the path inside " \
                           "steps, or define a new recipe version."
@@ -181,6 +289,8 @@ module ActiveDurable
       result
     rescue NotSerializable, InvalidRecipe
       raise
+    rescue NameError => e # NoMethodError too: a bug in the code, not a failure of the outside world
+      raise CodeError.new(name, e)
     rescue StandardError => e
       handle_failure(name, kind, position, entry, undo, options, e)
     end
@@ -241,6 +351,7 @@ module ActiveDurable
       name = name.to_s
       raise InvalidRecipe, "step names cannot be blank" if name.empty?
       raise InvalidRecipe, "step names cannot end in ':undo' (#{name})" if name.end_with?(":undo")
+      raise InvalidRecipe, "step names cannot start with '~' (#{name}): it marks hooks" if name.start_with?("~")
       if @seen.key?(name)
         raise DuplicateStepName, "the recipe uses the step name :#{name} twice. Each step needs its own name: " \
                                  "it is the step's key in the notebook."

data/lib/active_durable/flow_parallel.rb

@@ -9,6 +9,21 @@ module ActiveDurable
     # a crash only the unfinished branches run again. If a branch runs out of attempts, the saga compensates the
     # branches that completed (last finished, first undone) and every step before the parallel block.
     module Parallel
+      # Runs several steps at the same time. Declare the branches on the group the block receives; they run
+      # after the block returns.
+      #
+      # @param name [Symbol, String]
+      # @yieldparam branches [ParallelGroup]
+      # @return [Hash{String => Object}] each branch's result by branch name
+      # @raise [StepFailed] when a branch runs out of attempts
+      # @example
+      #   flow.parallel(:reserve) do |branches|
+      #     warehouses.each do |warehouse|
+      #       branches.step(warehouse.code, undo: ->(r, ticket) { warehouse.release(r["id"], key: ticket) }) do |ticket|
+      #         { "id" => warehouse.reserve(order.items_for(warehouse), key: ticket) }
+      #       end
+      #     end
+      #   end
       def parallel(name, &block)
         raise InvalidRecipe, "flow.parallel :#{name} needs a block" unless block
 
@@ -158,6 +173,8 @@ module ActiveDurable
         [:completed, result]
       rescue NotSerializable, InvalidRecipe
         raise
+      rescue NameError => e
+        raise CodeError.new(branch.full_name, e)
       rescue StandardError => e
         branch_failure(branch, entry, e)
       end

data/lib/active_durable/lease.rb

@@ -7,6 +7,8 @@ module ActiveDurable
   # lease. The claim writes a fresh random token. Every later write (notebook entries, status changes)
   # is conditional on that token still being there, so a worker whose lease expired and was taken over
   # cannot write anything else: its writes raise LeaseLost and it stops.
+  #
+  # @api private
   class Lease
     attr_reader :execution_id, :token
 

data/lib/active_durable/notebook.rb

@@ -3,6 +3,8 @@
 module ActiveDurable
   # The notebook of one execution: every step that ran, what it returned and its state.
   # Loaded once per run; every write is fenced by the lease.
+  #
+  # @api private
   class Notebook
     def initialize(execution, lease)
       @execution = execution
@@ -20,7 +22,7 @@ module ActiveDurable
     # Completed branch entries of a flow.parallel, in the order they finished.
     def branches_of(parallel_name)
       prefix = "#{parallel_name}/"
-      @mutex.synchronize { @entries.values.select { |entry| entry.name.start_with?(prefix) && !entry.undo? } }
+      @mutex.synchronize { @entries.values.select { |entry| entry.name.start_with?(prefix) && entry.forward? } }
             .sort_by { |entry| [entry.updated_at, entry.id] }
     end
 
@@ -29,7 +31,7 @@ module ActiveDurable
     end
 
     def forward_entries
-      @mutex.synchronize { @entries.values.reject(&:undo?) }
+      @mutex.synchronize { @entries.values.select(&:forward?) }
     end
 
     def complete!(name, kind:, position:, result:)

data/lib/active_durable/open_telemetry.rb

@@ -4,7 +4,7 @@ require "opentelemetry"
 require "active_durable"
 
 module ActiveDurable
-  # Traces executions, steps, compensations and undos as OpenTelemetry spans.
+  # Traces executions, steps, compensations, undos and hooks as OpenTelemetry spans.
   #
   #   # config/initializers/active_durable.rb
   #   require "active_durable/open_telemetry"
@@ -13,9 +13,14 @@ module ActiveDurable
   # Spans nest: a worker run ("active_durable.execution checkout") contains its steps, and flow.parallel
   # branches stay under it even though they run in other threads. Failed steps record the exception.
   module OpenTelemetry
-    EVENTS = %w[execution step compensation undo].freeze
+    # The ActiveSupport::Notifications events that become spans.
+    EVENTS = %w[execution step compensation undo hook].freeze
 
     class << self
+      # Starts tracing. Call it once, after configuring OpenTelemetry::SDK.
+      #
+      # @param tracer_provider [::OpenTelemetry::Trace::TracerProvider]
+      # @return [self]
       def install!(tracer_provider: ::OpenTelemetry.tracer_provider)
         uninstall!
         subscriber = Subscriber.new(tracer_provider.tracer("active_durable", ActiveDurable::VERSION))
@@ -26,6 +31,9 @@ module ActiveDurable
         self
       end
 
+      # Stops tracing.
+      #
+      # @return [void]
       def uninstall!
         Array(@subscriptions).each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
         @subscriptions = nil
@@ -34,6 +42,8 @@ module ActiveDurable
     end
 
     # Starts a span when an event starts and ends it when the event finishes, so spans nest naturally.
+    #
+    # @api private
     class Subscriber
       def initialize(tracer)
         @tracer = tracer
@@ -81,6 +91,8 @@ module ActiveDurable
     end
 
     # Carries the current span into flow.parallel branch threads.
+    #
+    # @api private
     module ContextPropagation
       def self.capture
         ::OpenTelemetry::Context.current

data/lib/active_durable/operations.rb

@@ -9,6 +9,8 @@ module ActiveDurable
   #
   # Every operation takes the execution only when no worker holds it, and rotates the lease token so a
   # stale worker can never write again.
+  #
+  # @api private
   module Operations
     module_function
 
@@ -50,7 +52,7 @@ module ActiveDurable
       Record.transaction do
         original = Execution.lock.find(execution_id)
         check_rerunnable!(original)
-        start = original.steps.where.not(kind: "undo").find_by(name: from)
+        start = original.steps.where.not(kind: %w[undo hook]).find_by(name: from)
         raise Error, "#{original.id} has no step :#{from} in its notebook" unless start
 
         execution = Execution.create!(id: rerun_id(original), recipe: original.recipe,
@@ -101,7 +103,8 @@ module ActiveDurable
 
     def copy_steps(original, execution, before:)
       now = ActiveDurable.now
-      rows = original.steps.where.not(kind: "undo").where(status: "completed").where(position: ...before).map do |step|
+      rows = original.steps.where.not(kind: %w[undo hook]).where(status: "completed").where(position: ...before)
+                     .map do |step|
         { execution_id: execution.id, name: step.name, kind: step.kind, position: step.position,
           status: "completed", attempts: step.attempts, result: step.result, created_at: now, updated_at: now }
       end

data/lib/active_durable/parallel.rb

@@ -13,20 +13,35 @@ module ActiveDurable
   #   end
   #   results # => { "MEX" => {...}, "GDL" => {...} }
   class ParallelGroup
+    # @api private
     Branch = Struct.new(:name, :full_name, :kind, :undo, :options, :block)
+    # @api private
     OPTIONS = %i[retry undo_on_failure].freeze
 
+    # @api private
     attr_reader :branches
 
+    # @api private
     def initialize(parallel_name)
       @parallel_name = parallel_name
       @branches = []
     end
 
+    # A branch that talks to the outside world, like {Flow#step}.
+    #
+    # @param name [Symbol, String] unique in this parallel block
+    # @param undo [#call, nil]
+    # @param options [Hash] `retry:` and `undo_on_failure:`
+    # @yieldparam ticket [String]
+    # @return [void]
     def step(name, undo: nil, **options, &block)
       add(name, "step", undo, options, block)
     end
 
+    # A branch that only touches your own database, like {Flow#transaction}.
+    #
+    # @param (see #step)
+    # @return [void]
     def transaction(name, undo: nil, **options, &block)
       add(name, "transaction", undo, options, block)
     end

data/lib/active_durable/prune_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  # Deletes finished executions older than config.keep_finished_for. Schedule it once a day (Solid Queue
+  # recurring tasks, cron, sidekiq-cron...).
+  class PruneJob < ActiveJob::Base
+    queue_as { ActiveDurable.config.queue_name }
+
+    # Deletes finished executions older than config.keep_finished_for.
+    #
+    # @return [void]
+    def perform
+      Pruner.call
+    end
+  end
+end

data/lib/active_durable/pruner.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  # Deletes finished executions (completed, compensated, superseded) older than a cutoff, with their notebook and
+  # their signals. Active and blocked executions are never touched: they still need a worker or a person.
+  #
+  # @api private
+  module Pruner
+    FINISHED = %w[completed compensated superseded].freeze
+
+    module_function
+
+    # Returns how many executions were deleted. Each batch is deleted in its own transaction, steps and signals
+    # first, so it never depends on the database cascading the foreign keys.
+    def call(older_than: ActiveDurable.config.keep_finished_for, batch_size: 1_000, now: ActiveDurable.now)
+      raise ArgumentError, "older_than must be set, for example 30.days" if older_than.nil?
+
+      cutoff = now - older_than.to_f
+      deleted = 0
+      loop do
+        ids = Execution.where(status: FINISHED).where("updated_at < ?", cutoff).limit(batch_size).pluck(:id)
+        break if ids.empty?
+
+        Record.transaction do
+          Step.where(execution_id: ids).delete_all
+          SignalRecord.where(execution_id: ids).delete_all
+          Execution.where(id: ids).delete_all
+        end
+        deleted += ids.size
+      end
+      deleted
+    end
+  end
+end

data/lib/active_durable/record.rb

@@ -3,6 +3,8 @@
 module ActiveDurable
   # Base class for the gem's tables. It shares ActiveRecord::Base's connection on purpose:
   # flow.transaction is only atomic when the notebook lives in the same database as your data.
+  #
+  # @api private
   class Record < ActiveRecord::Base
     self.abstract_class = true
 

data/lib/active_durable/registry.rb

@@ -2,6 +2,8 @@
 
 module ActiveDurable
   # A named recipe: the block that describes the steps of a saga.
+  #
+  # @api private
   class Recipe
     attr_reader :name, :version, :block
 
@@ -25,6 +27,8 @@ module ActiveDurable
   # Recipes are looked up by name when a worker picks up an execution, possibly in a fresh process.
   # In a Rails app, put each recipe in app/sagas/<name>_saga.rb and assign it to a constant
   # (CheckoutSaga = Durable.define(:checkout) { ... }). The registry autoloads that constant on a miss.
+  #
+  # @api private
   class Registry
     def initialize
       @recipes = {}

data/lib/active_durable/retry_policy.rb

@@ -6,6 +6,8 @@ module ActiveDurable
   #   flow.step :charge, retry: 5 { ... }
   #   flow.step :charge, retry: { attempts: 5, backoff: [1, 10, 60] } { ... }
   #   flow.step :charge, retry: false { ... }   # a single attempt
+  #
+  # @api private
   class RetryPolicy
     attr_reader :attempts
 

data/lib/active_durable/run_job.rb

@@ -5,6 +5,9 @@ module ActiveDurable
   class RunJob < ActiveJob::Base
     queue_as { ActiveDurable.config.queue_name }
 
+    # Runs the execution until it finishes, sleeps, waits or blocks.
+    #
+    # @param execution_id [String]
     def perform(execution_id)
       Runner.run(execution_id)
     end

data/lib/active_durable/runner.rb

@@ -3,6 +3,8 @@
 module ActiveDurable
   # Runs one execution as far as it can go: claims the lease, replays the recipe against the notebook,
   # and ends by completing, suspending (sleep, wait, retry), compensating or blocking.
+  #
+  # @api private
   class Runner
     SUSPEND = :active_durable_suspend
 
@@ -58,15 +60,23 @@ module ActiveDurable
       fail!(e)
     end
 
+    # Only a step that failed for good (StepFailed) or a business rejection (Abort) undoes the saga. Anything else
+    # the recipe raises is a bug: the execution is blocked, so fixing the code and calling ActiveDurable.retry
+    # carries it forward instead of refunding customers.
     def fail!(error)
-      return block!(error) if @flow.nil? || @flow.pivoted?
+      return block!(error) if @flow.nil? || @flow.pivoted? || !compensates?(error)
 
       start_compensation!(error) unless @flow.compensating?
       compensate!
     end
 
+    def compensates?(error)
+      error.is_a?(StepFailed) || error.is_a?(Abort)
+    end
+
     def complete!(output)
       output = Serializer.normalize(output, "the recipe's return value")
+      run_hook(:completed)
       lease.release!(status: "completed", output: output, wake_at: nil)
       ActiveDurable.instrument("completed", execution_id: execution.id, recipe: execution.recipe)
       :completed
@@ -98,13 +108,35 @@ module ActiveDurable
       ActiveDurable.instrument("compensation", execution_id: execution.id) do
         @flow.undo_stack.reverse_each { |entry| undo!(entry) }
       end
+      run_hook(:compensated)
       lease.release!(status: "compensated", wake_at: nil)
       ActiveDurable.instrument("compensated", execution_id: execution.id, recipe: execution.recipe)
       :compensated
-    rescue UndoFailed => e
+    rescue UndoFailed, HookFailed => e
       block!(e)
     end
 
+    # Runs a flow.on hook once: its notebook entry is written in the same transaction as the hook's own changes.
+    def run_hook(event)
+      hook = @flow.hook(event)
+      name = "~#{event}"
+      return if hook.nil? || notebook[name]&.completed?
+
+      ActiveDurable.crash_point(:before_hook, name)
+      ActiveDurable.instrument("hook", execution_id: execution.id, step: name, kind: "hook") do
+        notebook.transaction do
+          hook.call
+          ActiveDurable.crash_point(:after_hook_call, name)
+          notebook.complete!(name, kind: "hook", position: nil, result: nil)
+        end
+      end
+      ActiveDurable.crash_point(:after_hook_record, name)
+    rescue StandardError => e
+      raise if e.is_a?(HookFailed)
+
+      raise HookFailed.new(event, e)
+    end
+
     def undo!(entry)
       name = "#{entry.name}:undo"
       record = notebook[name]

data/lib/active_durable/serializer.rb

@@ -4,6 +4,8 @@ module ActiveDurable
   # Step results, inputs and signal payloads live in the notebook as JSON. This module turns a value
   # into exactly what a later replay will read back (string keys, no symbols), so the first run and a
   # replay behave the same. Anything that is not plain JSON is rejected with a message that says where.
+  #
+  # @api private
   module Serializer
     module_function
 

data/lib/active_durable/signal_record.rb

@@ -2,6 +2,8 @@
 
 module ActiveDurable
   # A message for a saga that is (or will be) waiting in flow.wait_for.
+  #
+  # @api private
   class SignalRecord < Record
     self.table_name = "durable_signals"
 

data/lib/active_durable/step.rb

@@ -30,5 +30,15 @@ module ActiveDurable
     def undo?
       kind == "undo"
     end
+
+    # Written once a flow.on(:completed) or flow.on(:compensated) hook ran.
+    def hook?
+      kind == "hook"
+    end
+
+    # A step of the recipe or a parallel branch: neither an undo nor a hook.
+    def forward?
+      !undo? && !hook?
+    end
   end
 end

data/lib/active_durable/sweep_job.rb

@@ -5,6 +5,9 @@ module ActiveDurable
   class SweepJob < ActiveJob::Base
     queue_as { ActiveDurable.config.queue_name }
 
+    # Enqueues the executions that should be running but have no job.
+    #
+    # @return [void]
     def perform
       Sweeper.call
     end