active_durable 0.5.0 → 0.7.0

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
 
@@ -21,7 +36,11 @@ module ActiveDurable
         prepare_branches!(name, branches)
         entry = @notebook[name]
         return finish_recorded_parallel(name, entry, branches) if entry&.completed? || entry&.failed?
-        raise StopForward, name if compensating?
+
+        if compensating? # stopped halfway: undo the branches that finished
+          remember_branches(name, branches, include_failed: true)
+          raise StopForward, name
+        end
 
         run_parallel(name, position, branches)
       end
@@ -62,6 +81,12 @@ module ActiveDurable
 
       def run_parallel(name, position, branches)
         outcomes = branch_outcomes(branches)
+        blocked = outcomes.find { |_, (state, _)| state == :blocked }
+        if blocked
+          @blocked_by = blocked.last.last
+          raise @blocked_by
+        end
+
         failed = outcomes.select { |_, (state, _)| state == :failed }
         if failed.any?
           full_name, (_, error) = failed.first
@@ -80,7 +105,7 @@ module ActiveDurable
         results.deep_dup
       end
 
-      # { full_name => [:completed, result] | [:retry, wake_at] | [:failed, error] }
+      # { full_name => [:completed, result] | [:retry, wake_at] | [:failed, error] | [:blocked, error] }
       def branch_outcomes(branches)
         outcomes = {}
         runnable = []
@@ -149,17 +174,31 @@ module ActiveDurable
         result = ActiveDurable.instrument("step", execution_id: execution_id, step: branch.full_name,
                                                   kind: branch.kind) do
           if branch.kind == "transaction"
-            @notebook.transaction { record_result(branch.full_name, branch.kind, nil, branch.block.call(ticket)) }
+            @notebook.transaction(records: branch.full_name) do
+              record_result(branch.full_name, branch.kind, nil, branch.block.call(ticket))
+            end
           else
             record_result(branch.full_name, branch.kind, nil, branch.block.call(ticket))
           end
         end
         ActiveDurable.crash_point(:after_record, branch.full_name)
         [:completed, result]
-      rescue NotSerializable, InvalidRecipe
-        raise
-      rescue StandardError => e
+      rescue Abort => e
         branch_failure(branch, entry, e)
+      rescue NotSerializable, InvalidRecipe, CheckpointFailed => e
+        block_branch(branch, entry, e)
+      rescue StandardError, ScriptError, SystemStackError => e
+        return block_branch(branch, entry, CodeError.new(branch.full_name, e)) if ActiveDurable.code_error?(e)
+
+        branch_failure(branch, entry, e)
+      end
+
+      # Like block_step!, from inside a branch thread: the run blocks once every branch has finished.
+      def block_branch(branch, entry, error)
+        error.step_name ||= branch.full_name if error.respond_to?(:step_name=)
+        @notebook.block!(branch.full_name, kind: branch.kind, position: nil, attempts: entry&.attempts || 0,
+                                           error: ActiveDurable.dump_error(error, step: branch.full_name))
+        [:blocked, error]
       end
 
       def branch_failure(branch, entry, error)
@@ -188,7 +227,7 @@ module ActiveDurable
 
           if entry.completed?
             @undo_stack << UndoEntry.new(entry.name, branch.kind, entry.result, branch.undo)
-          elsif include_failed && branch.options[:undo_on_failure] && (entry.failed? || entry.retrying?)
+          elsif include_failed && branch.options[:undo_on_failure] && (entry.failed? || entry.unfinished?)
             @undo_stack << UndoEntry.new(entry.name, branch.kind, nil, branch.undo)
           end
         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:)
@@ -46,17 +48,28 @@ module ActiveDurable
                    wake_at: nil)
     end
 
+    # The step hit a bug or its result could not be recorded: it runs again after ActiveDurable.retry.
+    def block!(name, kind:, position:, attempts:, error:)
+      write!(name, kind: kind, position: position, status: "blocked", attempts: attempts, error: error, wake_at: nil)
+    end
+
     def wait!(name, kind:, position:, wake_at:)
       write!(name, kind: kind, position: position, status: "waiting", wake_at: wake_at)
     end
 
     # Runs the block in a database transaction and remembers the notebook writes made inside it only once it
-    # commits. flow.transaction steps and their undos use it: a step that rolled back must not look completed.
-    def transaction(&)
+    # commits. flow.transaction steps, their undos and hooks use it: a step that rolled back must not look
+    # completed. With `records:`, the block must have recorded that entry: Active Record swallows
+    # ActiveRecord::Rollback, so a block that raised it would otherwise look done.
+    def transaction(records: nil, &)
       pending = []
       Thread.current[pending_key] = pending
       result = Record.transaction(&)
       pending.each { |name, entry| remember(name, entry) }
+      if records && !self[records]&.completed?
+        raise Error, ":#{records} rolled back (ActiveRecord::Rollback), so nothing was recorded. Raise an error " \
+                     "or call flow.abort! to make it fail."
+      end
       result
     ensure
       Thread.current[pending_key] = nil

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,25 +9,30 @@ 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
 
-    # A blocked execution tries again from where it stopped: failed steps (or failed undos, if it was
-    # compensating) get a fresh set of attempts. Deploy the fix first when the cause was a bug.
+    # A blocked execution tries again from where it stopped: the step that blocked it (or the failed undos, if it
+    # was compensating) gets a fresh set of attempts. Failed steps the recipe already handled, such as a payment
+    # provider it replaced with another one, stay failed: running them again would pay twice. Deploy the fix
+    # first when the cause was a bug.
     def retry(execution_id)
       execution = with_idle_execution(execution_id, allowed: %w[blocked]) do |record|
-        failed = record.steps.where(status: "failed")
-        failed = record.compensating ? failed.where(kind: "undo") : failed.where.not(kind: "undo")
-        failed.update_all(status: "retrying", attempts: 0, wake_at: nil, updated_at: ActiveDurable.now)
+        blocking_steps(record).update_all(status: "retrying", attempts: 0, wake_at: nil,
+                                          updated_at: ActiveDurable.now)
         reopen!(record, error: nil)
       end
       ActiveDurable.instrument("retried", execution_id: execution.id)
       execution
     end
 
-    # Undoes every completed step, last one first. Not possible once the point of no return was passed.
+    # Undoes every completed step, last one first. Not possible once the point of no return was passed, nor while
+    # the execution is running: the lease is only renewed on notebook writes, so a worker may still be inside a
+    # slow step after its lease ran out (the sweeper resumes it if the worker died).
     def compensate(execution_id, reason: "compensated by an operator")
-      execution = with_idle_execution(execution_id, allowed: %w[blocked pending running sleeping waiting]) do |record|
+      execution = with_idle_execution(execution_id, allowed: %w[blocked pending sleeping waiting]) do |record|
         raise Error, "#{record.id} is already compensating; use ActiveDurable.retry to resume it" if record.compensating
         if record.steps.exists?(kind: "pivot", status: "completed")
           raise Error, "#{record.id} already passed its point of no return; it can only move forward"
@@ -50,9 +55,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)
-        raise Error, "#{original.id} has no step :#{from} in its notebook" unless start
-
+        start = rerun_start(original, from)
         execution = Execution.create!(id: rerun_id(original), recipe: original.recipe,
                                       recipe_version: original.recipe_version, input: original.input,
                                       status: "pending", forked_from: original.id)
@@ -63,6 +66,15 @@ module ActiveDurable
       execution
     end
 
+    def rerun_start(original, 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
+      return start if start.position
+
+      parallel = from.split("/", 2).first
+      raise Error, ":#{from} is a branch of flow.parallel :#{parallel}; rerun from :#{parallel} instead"
+    end
+
     def with_idle_execution(execution_id, allowed:)
       execution = Record.transaction do
         record = Execution.lock.find(execution_id)
@@ -93,17 +105,44 @@ module ActiveDurable
                    "only completed executions, or blocked ones that are not compensating, can be rerun"
     end
 
+    # Moving forward: the step named by the error, or the whole flow.parallel it belongs to, and every step that
+    # hit a bug. Compensating: every failed undo, since each of them stopped the compensation.
+    def blocking_steps(record)
+      steps = record.steps
+      return steps.where(kind: "undo", status: "failed") if record.compensating
+
+      name = record.error.is_a?(Hash) ? record.error["step"].to_s : ""
+      failed = steps.where(status: "failed").where.not(kind: %w[undo hook])
+      parallel = failed.where(kind: "parallel").pluck(:name)
+                       .find { |group| name == group || name.start_with?("#{group}/") }
+      named = if parallel
+                failed.where(name: parallel).or(failed.where("name LIKE ?", "#{Step.sanitize_sql_like(parallel)}/%"))
+              else
+                failed.where(name: name)
+              end
+      named.or(steps.where(status: "blocked"))
+    end
+
+    # A random suffix, never a count: a pruned rerun must not hand its id, and so its tickets, to a new one.
     def rerun_id(original)
-      root = original.id.sub(/~rerun-\d+\z/, "")
-      count = Execution.where("id LIKE ?", "#{Execution.sanitize_sql_like(root)}~rerun-%").count
-      "#{root}~rerun-#{count + 1}"
+      root = original.id.sub(/~rerun-\h+\z/, "")
+      "#{root}~rerun-#{SecureRandom.hex(4)}"
     end
 
+    # The steps before `from` that completed or failed (a failure the recipe handled must stay handled), and the
+    # branches of each flow.parallel among them, in the order they finished, so their undos still run.
     def copy_steps(original, execution, before:)
+      forward = original.steps.where.not(kind: %w[undo hook]).where(status: %w[completed failed])
+      kept = forward.where(position: ...before).order(:position).to_a
+      groups = kept.select { |step| step.kind == "parallel" }.map { |step| "#{step.name}/" }
+      branches = forward.where(position: nil).order(:updated_at, :id).select do |step|
+        groups.any? { |prefix| step.name.start_with?(prefix) }
+      end
       now = ActiveDurable.now
-      rows = original.steps.where.not(kind: "undo").where(status: "completed").where(position: ...before).map do |step|
+      rows = (kept + branches).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 }
+          status: step.status, attempts: step.attempts, result: step.result, error: step.error,
+          created_at: now, updated_at: now }
       end
       Step.insert_all!(rows) if rows.any?
     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,32 @@
+# 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
+    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: Execution::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
 
@@ -36,7 +38,7 @@ module ActiveDurable
       lease.release!(status: status, wake_at: wake_at)
       ActiveDurable.enqueue(execution.id, wait_until: wake_at) if wake_at
       # A signal may have been committed while we held the lease; its own job found us busy.
-      if status == "waiting" && SignalRecord.pending.exists?(execution_id: execution.id)
+      if status == "waiting" && SignalRecord.awaited.exists?(execution_id: execution.id)
         ActiveDurable.enqueue(execution.id)
       end
       throw SUSPEND, status.to_sym
@@ -56,17 +58,29 @@ module ActiveDurable
       block!(e)
     rescue StandardError => e
       fail!(e)
+    rescue ScriptError, SystemStackError => e # LoadError, NotImplementedError: bugs that StandardError misses
+      block!(@flow&.blocked_by || 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. A step that hit a bug blocks the run even if the recipe
+    # rescued its error.
     def fail!(error)
-      return block!(error) if @flow.nil? || @flow.pivoted?
+      return block!(@flow.blocked_by) if @flow&.blocked_by
+      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 +112,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(records: name) 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, ScriptError, SystemStackError => e
+      raise if e.is_a?(HookFailed)
+
+      raise HookFailed.new(event, e)
+    end
+
     def undo!(entry)
       name = "#{entry.name}:undo"
       record = notebook[name]
@@ -116,13 +152,13 @@ module ActiveDurable
       ActiveDurable.crash_point(:before_undo, entry.name)
       ActiveDurable.instrument("undo", execution_id: execution.id, step: entry.name) do
         if entry.kind == "transaction"
-          notebook.transaction { call_undo(entry, ticket, name) }
+          notebook.transaction(records: name) { call_undo(entry, ticket, name) }
         else
           call_undo(entry, ticket, name)
         end
       end
       ActiveDurable.crash_point(:after_undo_record, entry.name)
-    rescue StandardError => e
+    rescue StandardError, ScriptError, SystemStackError => e
       retry_undo!(entry, name, record, e)
     end
 
@@ -140,13 +176,19 @@ module ActiveDurable
       notebook.complete!(name, kind: "undo", position: nil, result: nil)
     end
 
+    # An undo is retried until config.undo_attempts, then the execution is blocked. A bug blocks it at once.
     def retry_undo!(entry, name, record, error)
       attempts = (record&.attempts || 0) + 1
       dumped = ActiveDurable.dump_error(error, step: name)
       max = ActiveDurable.config.undo_attempts
+      if ActiveDurable.code_error?(error)
+        notebook.fail!(name, kind: "undo", position: nil, attempts: attempts, error: dumped)
+        raise UndoFailed.new("undo of :#{entry.name} cannot run: #{error.class}: #{error.message}", step_name: name)
+      end
       if attempts >= max
         notebook.fail!(name, kind: "undo", position: nil, attempts: attempts, error: dumped)
-        raise UndoFailed, "undo of :#{entry.name} failed #{attempts} times (#{error.class}: #{error.message})"
+        raise UndoFailed.new("undo of :#{entry.name} failed #{attempts} times (#{error.class}: #{error.message})",
+                             step_name: name)
       end
 
       wake_at = ActiveDurable.now + RetryPolicy.new(attempts: max).delay(attempts)

data/lib/active_durable/serializer.rb

@@ -2,14 +2,18 @@
 
 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.
+  # into exactly what a later replay will read back (string keys, no symbols, UTF-8 strings), so the first run
+  # and a replay behave the same. Anything that is not plain JSON, or that some database cannot store (a NUL
+  # character, bytes that are not UTF-8), is rejected with a message that says where.
+  #
+  # @api private
   module Serializer
     module_function
 
     def normalize(value, path = "value")
       case value
-      when nil, true, false, String, Integer then value
+      when nil, true, false, Integer then value
+      when String then utf8(value, path)
       when Float then finite_float(value, path)
       when Symbol then value.to_s
       when Array then value.each_with_index.map { |item, index| normalize(item, "#{path}[#{index}]") }
@@ -27,10 +31,32 @@ module ActiveDurable
         key = key.to_s if key.is_a?(Symbol)
         raise NotSerializable, "#{path} has a #{key.class} key; use strings or symbols" unless key.is_a?(String)
 
+        key = utf8(key, "a key of #{path}")
         out[key] = normalize(item, "#{path}[#{key.inspect}]")
       end
     end
 
+    # Binary strings (Net::HTTP response bodies) are fine when their bytes are UTF-8; other encodings are converted.
+    def utf8(value, path)
+      string = value
+      if [Encoding::BINARY, Encoding::US_ASCII].include?(string.encoding)
+        string = string.dup.force_encoding(Encoding::UTF_8)
+      elsif string.encoding != Encoding::UTF_8
+        string = string.encode(Encoding::UTF_8)
+      end
+      unless string.valid_encoding?
+        raise NotSerializable, "#{path} has bytes that are not UTF-8. Decode it with the right encoding, or " \
+                               "Base64-encode binary data."
+      end
+      if string.include?("\u0000")
+        raise NotSerializable, "#{path} contains a NUL character (\\u0000), which PostgreSQL cannot store. " \
+                               "Strip it, or Base64-encode binary data."
+      end
+      string
+    rescue EncodingError => e
+      raise NotSerializable, "#{path} cannot be converted to UTF-8 (#{e.message})"
+    end
+
     def finite_float(value, path)
       raise NotSerializable, "#{path} is #{value}, which JSON cannot store" unless value.finite?