actionable-rb 1.9.0

data/lib/actionable/batch_result.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Actionable
+  # The value object returned by {Action.run_each}: an ordered, +Enumerable+
+  # collection of the per-item {Result}s, plus aggregate predicates over them
+  # (decision D19). Each item ran independently — one {Result} per element, in
+  # input order — so a failure in one never affects another.
+  #
+  #   batch = ImportRow.run_each(rows) { |row| {row: row} }
+  #   batch.all_ok?            # => false
+  #   batch.failures.size      # => 2
+  #   batch.to_api_h           # => [{index: 0, status: :success, ...}, ...]
+  class BatchResult
+    include Enumerable
+
+    # @return [Array<Result>] the per-item results, in input order
+    attr_reader :results
+
+    # @param results [Array<Result>]
+    def initialize(results)
+      @results = results.to_a
+    end
+
+    # @yieldparam result [Result]
+    # @return [Enumerator, self]
+    def each(&block)
+      return to_enum(:each) unless block
+
+      @results.each(&block)
+      self
+    end
+
+    # @param index [Integer]
+    # @return [Result, nil] the result at +index+
+    def [](index)
+      @results[index]
+    end
+
+    # @return [Integer] the number of results
+    def size
+      @results.size
+    end
+    alias length size
+
+    # @return [Boolean] whether the batch ran no items
+    def empty?
+      @results.empty?
+    end
+
+    # @return [Boolean] whether every result is +ok?+ (success or skip);
+    #   vacuously true for an empty batch
+    def all_ok?
+      @results.all?(&:ok?)
+    end
+
+    # @return [Boolean] whether any result is a failure
+    def any_failure?
+      @results.any?(&:failure?)
+    end
+
+    # @return [Boolean] whether the batch is mixed — at least one failure and at
+    #   least one +ok?+ result
+    def partial?
+      any_failure? && @results.any?(&:ok?)
+    end
+
+    # @return [Array<Result>] the successful results
+    def successes
+      @results.select(&:success?)
+    end
+
+    # @return [Array<Result>] the failed results
+    def failures
+      @results.select(&:failure?)
+    end
+
+    # @return [Array<Result>] the skipped results
+    def skips
+      @results.select(&:skipped?)
+    end
+
+    # The batch as an array of API elements, each tagged with its position
+    # (see {Result#to_api_h}). Ready to render as a JSON array of per-item
+    # statuses.
+    #
+    # @param id_field [Symbol] the output field to surface as +:id+
+    # @return [Array<Hash{Symbol=>Object}>]
+    def to_api_h(id_field: :id)
+      @results.each_with_index.map { |result, index| result.to_api_h(index: index, id_field: id_field) }
+    end
+  end
+end

data/lib/actionable/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Base class for every error this gem raises. Rescue +Actionable::Error+ to
+  # catch the whole family. Genuine errors are never caught by the runner for
+  # control flow — they propagate to the caller (decision D4).
+  class Error < StandardError; end
+
+  # Raised when an action is misconfigured — a reserved output field name, or a
+  # declared step whose method isn't implemented. Surfaced early and clearly so
+  # humans and agents get an actionable message instead of a deep +NoMethodError+
+  # (decision D18).
+  class DefinitionError < Error; end
+
+  # The throw/catch tag used to unwind an action's step pipeline early.
+  # Halting (+fail!+ / +succeed!+ / +halt!+) throws this symbol; the runner
+  # catches it via {Actionable.catch_halt}. This is control flow, NOT an
+  # exception (decision D4).
+  # @return [Symbol]
+  HALT = :actionable_halt
+
+  module_function
+
+  # Run +block+ inside the halt catch point.
+  #
+  # Returns the block's value when nothing is thrown, or the value passed with
+  # +throw Actionable::HALT, value+ when the pipeline halts (+nil+ for a bare
+  # +throw Actionable::HALT+). A raised StandardError is deliberately NOT
+  # caught — it propagates to the caller (decision D4).
+  #
+  # @yieldreturn [Object]
+  # @return [Object] the block's value, or the thrown halt value
+  def catch_halt(&block)
+    catch(HALT, &block)
+  end
+end

data/lib/actionable/history.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'oj'
+require 'time'
+
+module Actionable
+  # An ordered record of the steps a run executed, when measurement is enabled
+  # (decision D10). Each entry is a {History::Step}; nested action steps carry
+  # their child's +History+.
+  class History
+    # One recorded step: which section it ran in, its name, when it started, how
+    # long it took, the result code it produced (if any), and — for action
+    # steps — the nested child {History}.
+    class Step
+      # @return [Symbol] +:main+, +:success+, +:failure+, or +:always+
+      attr_reader :section
+      # @return [Symbol, String, Class] the step's name
+      attr_reader :name
+      # @return [Time] wall-clock start time
+      attr_reader :started_at
+      # @return [Float] elapsed seconds (monotonic)
+      attr_accessor :duration
+      # @return [Symbol, nil] the result code this step recorded, if it set one
+      attr_accessor :code
+      # @return [History, nil] the nested action's history, for action steps
+      attr_accessor :nested
+
+      # @param section [Symbol]
+      # @param name [Symbol, String, Class]
+      # @param started_at [Time]
+      def initialize(section:, name:, started_at:)
+        @section = section
+        @name = name
+        @started_at = started_at
+        @duration = 0.0
+        @code = nil
+        @nested = nil
+      end
+
+      # @return [Hash{Symbol=>Object}] a JSON-ready hash (nested history recurses)
+      def as_json(*)
+        {
+          section: section,
+          name: name.is_a?(Class) ? name.name : name,
+          started_at: started_at.iso8601(6),
+          duration: duration,
+          code: code,
+          history: nested&.as_json
+        }
+      end
+    end
+
+    # @return [Array<Step>] the recorded steps, in execution order
+    attr_reader :steps
+
+    def initialize
+      @steps = []
+    end
+
+    # Append a recorded step.
+    #
+    # @param step [Step]
+    # @return [self]
+    def <<(step)
+      @steps << step
+      self
+    end
+
+    # @return [Boolean] whether any step has been recorded
+    def empty?
+      @steps.empty?
+    end
+
+    # @return [Float] the summed duration of every recorded step
+    def took
+      @steps.sum(&:duration)
+    end
+
+    # @return [Array<Hash>] each step as a JSON-ready hash
+    def as_json(*)
+      @steps.map(&:as_json)
+    end
+
+    # @return [String] the history serialized to JSON via Oj (decision D15).
+    #   +:compat+ mode emits plain JSON (string keys, symbols as strings) rather
+    #   than Oj's default object-marker encoding.
+    def to_json(*)
+      Oj.dump(as_json, mode: :compat)
+    end
+  end
+end

data/lib/actionable/input_dispatch.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Runtime selection of an input schema from a discriminator value (decision
+  # D19, declared with +input_for+). Each branch maps a match value to a
+  # FieldStruct schema; an optional +default+ catches the rest. Lets a
+  # polymorphic payload (e.g. +event_type+ → shape) use typed, validated input.
+  #
+  #   input_for :event_type do
+  #     on 'sale',   SaleShape
+  #     on 'refund', RefundShape
+  #     default      UnknownShape
+  #   end
+  class InputDispatch
+    # Collects +on+/+default+ branch declarations inside an +input_for+ block.
+    class Builder
+      # @return [Array<Array(Object, Class<FieldStruct::Base>)>] ordered [match, schema] pairs
+      attr_reader :branches
+      # @return [Class<FieldStruct::Base>, nil] the fallback schema, if declared
+      attr_reader :default_schema
+
+      def initialize
+        @branches = []
+        @default_schema = nil
+      end
+
+      # Register a branch. +value+ matches the discriminator by +==+, by
+      # Array membership, or by +Regexp#match?+ (see {ValueMatch}).
+      #
+      # @param value [Object, Array, Regexp]
+      # @param schema [Class<FieldStruct::Base>]
+      # @return [void]
+      def on(value, schema)
+        @branches << [value, schema]
+      end
+
+      # Register the fallback schema, used when no +on+ branch matches.
+      #
+      # @param schema [Class<FieldStruct::Base>]
+      # @return [void]
+      def default(schema)
+        @default_schema = schema
+      end
+    end
+
+    # @return [Symbol] the discriminator field read from +.run+'s kwargs
+    attr_reader :discriminator
+    # @return [Array<Array(Object, Class<FieldStruct::Base>)>] ordered [match, schema] pairs
+    attr_reader :branches
+    # @return [Class<FieldStruct::Base>, nil] the fallback schema
+    attr_reader :default_schema
+
+    # Build a dispatch from an +input_for+ declaration.
+    #
+    # @param discriminator [Symbol, String] the kwarg whose value selects the schema
+    # @yield the branch declarations (+on+ / +default+)
+    # @return [InputDispatch]
+    def self.define(discriminator, &block)
+      builder = Builder.new
+      builder.instance_eval(&block)
+      new(discriminator.to_sym, builder.branches, builder.default_schema)
+    end
+
+    # @param discriminator [Symbol]
+    # @param branches [Array<Array(Object, Class<FieldStruct::Base>)>]
+    # @param default_schema [Class<FieldStruct::Base>, nil]
+    def initialize(discriminator, branches, default_schema)
+      @discriminator = discriminator
+      @branches = branches
+      @default_schema = default_schema
+    end
+
+    # The schema for a discriminator value: the first matching branch, else the
+    # default, else +nil+ (no match and no default).
+    #
+    # @param value [Object] the discriminator value
+    # @return [Class<FieldStruct::Base>, nil]
+    def schema_for(value)
+      @branches.each { |branch_value, schema| return schema if ValueMatch.matches?(branch_value, value) }
+      @default_schema
+    end
+
+    # @return [Array<Class<FieldStruct::Base>>] every distinct schema reachable
+    #   through this dispatch (branches plus default)
+    def schemas
+      (@branches.map(&:last) + [@default_schema]).compact.uniq
+    end
+
+    # @return [Array<Object>] the branch match values, in declaration order
+    def variants
+      @branches.map(&:first)
+    end
+  end
+end

data/lib/actionable/job.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# Optional background-job integration (decision D19). Load it explicitly with
+# `require 'actionable/job'`. Framework-agnostic and pure Ruby — it maps an
+# action {Actionable::Result} to a queue *disposition* and provides a {Mixin}
+# you include into a Sidekiq worker or ActiveJob job. Never loaded by the core
+# entry point.
+require_relative '../actionable' # ensure the core is loaded (self-contained entry)
+
+module Actionable
+  # Runs an action inside a background job and maps its result to a queue
+  # disposition: a success or skip is done (+:ack+); a failure either retries
+  # (transient) or is discarded (permanent). Genuine exceptions are never
+  # swallowed — they propagate so the queue's own retry/backoff handles them
+  # (invariant 2).
+  module Job
+    # Failure codes that should NOT be retried — a re-run can't fix bad input or
+    # a missing record, so the job is discarded rather than retried. Override
+    # per job via {Mixin#actionable_permanent_codes}.
+    # @return [Array<Symbol>]
+    DEFAULT_PERMANENT_CODES = %i[invalid_input invalid_output not_found].freeze
+
+    # Raised by {Mixin#run_actionable} for a retryable failure, so the host
+    # queue (Sidekiq / ActiveJob) sees a raised error and applies its retry
+    # policy. Carries the offending result.
+    class RetryableFailure < StandardError
+      # @return [Result] the failed result that triggered the retry
+      attr_reader :result
+
+      # @param result [Result] a {Failure}, or a {Skipped} retried because its
+      #   metadata says +retry: true+ (see {RetryMetadata#honor_retry_metadata})
+      def initialize(result)
+        @result = result
+        verb = result.skipped? ? 'skipped' : 'failed'
+        super("actionable run #{verb} with retryable code #{result.code.inspect}")
+      end
+    end
+
+    # The +honor_retry_metadata+ class macro (owner ruling P10). Extended onto
+    # {Actionable::Action} by +actionable/job+, so an action can opt in to having
+    # {Mixin#run_actionable} act on the +retry:+ metadata of its declared codes.
+    # Metadata stays neutral by default (decisions D20/D21).
+    module RetryMetadata
+      # Opt this action in (or, with +enabled: false+, back out) to {Job}
+      # honoring the +retry:+ metadata of its declared failures and skips:
+      # +retry: true+ retries the job, +retry: false+ does not. A code with no
+      # +retry:+ key keeps the default mapping. Inherited; a subclass can turn
+      # it off.
+      #
+      #   class Reindex < Actionable::Action
+      #     honor_retry_metadata
+      #     skips :not_ready, retry: true # the job retries until the index is ready
+      #   end
+      #
+      # @param enabled [Boolean]
+      # @return [void]
+      def honor_retry_metadata(enabled: true)
+        @honor_retry_metadata = enabled
+      end
+
+      # Whether {Job} honors this action's +retry:+ metadata, inherited from
+      # ancestors when not set locally. +false+ unless an ancestor opted in.
+      #
+      # @return [Boolean]
+      def honor_retry_metadata?
+        return @honor_retry_metadata if defined?(@honor_retry_metadata)
+        return superclass.honor_retry_metadata? if superclass.respond_to?(:honor_retry_metadata?)
+
+        false
+      end
+    end
+
+    module_function
+
+    # Map a result to a queue disposition.
+    #
+    # With +honor_retry: true+, a failure or skip whose metadata has a +retry:+
+    # key is decided by it instead: truthy is +:retry+, falsy is +:discard+ for
+    # a failure and +:ack+ for a skip. Results without the key, and successes,
+    # map as usual.
+    #
+    # @param result [Result] the action's result
+    # @param permanent [Array<Symbol>] failure codes treated as non-retryable
+    # @param honor_retry [Boolean] act on the result's +retry:+ metadata
+    # @return [:ack, :retry, :discard] +:ack+ for a success or skip; +:discard+
+    #   for a failure whose code is +permanent+; +:retry+ for any other failure
+    def disposition(result, permanent: DEFAULT_PERMANENT_CODES, honor_retry: false)
+      return metadata_disposition(result) if honor_retry && retry_declared?(result)
+      return :ack if result.ok?
+
+      permanent.include?(result.code) ? :discard : :retry
+    end
+
+    # @param result [Result]
+    # @return [Boolean] whether the result carries +retry:+ metadata
+    def retry_declared?(result)
+      !result.success? && result.metadata.key?(:retry)
+    end
+    private_class_method :retry_declared?
+
+    # @param result [Failure, Skipped] a result whose metadata has +retry:+
+    # @return [:ack, :retry, :discard]
+    def metadata_disposition(result)
+      return :retry if result.metadata[:retry]
+
+      result.failure? ? :discard : :ack
+    end
+    private_class_method :metadata_disposition
+
+    # Mix into a Sidekiq worker or ActiveJob job. Call {#run_actionable} from
+    # +perform+; it runs the action, records the result on {#actionable_result},
+    # and raises {RetryableFailure} for a retryable failure (so the queue
+    # retries) — returning normally for +:ack+ and +:discard+.
+    #
+    #   class ProjectEventJob
+    #     include Sidekiq::Job
+    #     include Actionable::Job::Mixin
+    #     def perform(event_id) = run_actionable(ProjectApiEvent, event_id: event_id)
+    #   end
+    module Mixin
+      # @return [Result, nil] the result of the most recent {#run_actionable}
+      attr_reader :actionable_result
+
+      # Run +action_class+ with the given arguments, map the outcome, and either
+      # return the result (+:ack+ / +:discard+) or raise {RetryableFailure}
+      # (+:retry+). A genuine exception inside the action propagates unchanged.
+      # When the action opted in with +honor_retry_metadata+, its declared
+      # +retry:+ metadata decides (see {Job.disposition}).
+      #
+      # @param action_class [Class<Actionable::Action>]
+      # @param args [Object] positional arguments, forwarded to +.run+
+      # @param kwargs [Object] keyword arguments, forwarded to +.run+
+      # @return [Result] the run's result (for an ack/discard outcome)
+      # @raise [RetryableFailure] when the failure should be retried
+      def run_actionable(action_class, *args, **kwargs)
+        @actionable_result = action_class.run(*args, **kwargs)
+        disposition = Actionable::Job.disposition(
+          @actionable_result,
+          permanent: actionable_permanent_codes,
+          honor_retry: action_class.respond_to?(:honor_retry_metadata?) && action_class.honor_retry_metadata?
+        )
+        raise RetryableFailure, @actionable_result if disposition == :retry
+
+        @actionable_result
+      end
+
+      # @return [Array<Symbol>] failure codes this job treats as non-retryable;
+      #   override to customize. Defaults to {DEFAULT_PERMANENT_CODES}.
+      def actionable_permanent_codes
+        DEFAULT_PERMANENT_CODES
+      end
+    end
+  end
+end
+
+# Wire the adapter into the core: the honor_retry_metadata macro onto Action.
+Actionable::Action.extend(Actionable::Job::RetryMetadata)

data/lib/actionable/measurement.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Actionable
+  # Thread-local measurement context (decision D10). It lets a measuring run
+  # cascade into the nested actions it invokes, and lets an action step attach
+  # its child's history to the step record currently open in the parent runner.
+  #
+  # All state is per-thread and saved/restored around each scope, so concurrent
+  # runs on different threads never interfere.
+  module Measurement
+    class << self
+      # @return [Boolean] whether the current thread is inside a measuring run
+      def active?
+        store[:active]
+      end
+
+      # @return [History::Step, nil] the step record nested history attaches to
+      def open_step
+        store[:open_step]
+      end
+
+      # Mark measurement active for the block, so nested runs measure too.
+      #
+      # @yieldreturn [Object]
+      # @return [Object] the block's value
+      def measuring(&)
+        with({active: true}, &)
+      end
+
+      # Make +record+ the open step for the block, so a nested action step can
+      # attach its child's history to it.
+      #
+      # @param record [History::Step]
+      # @yieldreturn [Object]
+      # @return [Object] the block's value
+      def recording(record, &)
+        with({open_step: record}, &)
+      end
+
+      private
+
+      # This thread's measurement state: +:active+ and +:open_step+.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def store
+        Thread.current[:actionable_measurement] ||= {active: false, open_step: nil}
+      end
+
+      # Merge +changes+ into the state for the block, restoring it afterwards.
+      #
+      # @param changes [Hash{Symbol=>Object}] the keys to override
+      # @yield the scope the changes apply to
+      # @yieldreturn [Object]
+      # @return [Object] the block's value
+      def with(changes)
+        previous = store.dup
+        store.merge!(changes)
+        yield
+      ensure
+        Thread.current[:actionable_measurement] = previous
+      end
+    end
+  end
+end

data/lib/actionable/rails/after_commit.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Actionable
+  module Rails
+    # The +after_commit+ hook kind. Prepended onto {Actionable::Action}'s
+    # singleton class by +actionable/rails+, so the core never knows about it
+    # (decision D8).
+    #
+    # An +after_commit+ hook runs once, after the database work of a
+    # successful run has really committed: it is registered with
+    # +ActiveRecord.after_all_transactions_commit+ when the run ends, so it
+    # waits for the outermost open transaction (not the action's own
+    # savepoint), runs immediately when none is open, and never runs if any
+    # enclosing transaction rolls back.
+    module AfterCommit
+      # The first ActiveRecord version with +after_all_transactions_commit+.
+      # @return [String]
+      MINIMUM_ACTIVE_RECORD = '7.2'
+
+      # Declare a hook that runs after the outermost database transaction
+      # commits, iff the run's final result is a {Success}.
+      #
+      #   after_commit :send_receipt
+      #   after_commit NotifyWarehouse, input: %i[order]
+      #
+      # The run is over by then: the result has been returned (or is about to
+      # be, when no transaction is open), so the hook cannot change it, a
+      # halting verb only stops the remaining +after_commit+ hooks, and the
+      # hook is not recorded in the history. An exception it raises propagates
+      # from wherever the commit happens: the outer +transaction+ call, or
+      # +.run+ itself when no transaction was open.
+      #
+      # @param target [Symbol, String, Class<Actionable::Action>] the instance
+      #   method or nested action to run
+      # @param options [Object] step options (+:if+, +:unless+, and for a
+      #   nested action +:input+)
+      # @raise [DefinitionError] when ActiveRecord is not loaded or predates
+      #   +after_all_transactions_commit+
+      # @return [Set<Steps::Base>]
+      def after_commit(target, **options)
+        ensure_after_commit_supported!
+        declare(after_commit_hooks, Steps.build(target, **options))
+      end
+
+      # Hooks that run after the outermost transaction commits a successful run.
+      # @return [Set<Steps::Base>]
+      def after_commit_hooks
+        @after_commit_hooks ||= Set.new
+      end
+
+      # {Actionable::Action.describe}, with the +after_commit+ hooks listed as
+      # one more +:hooks+ section, so {Actionable::Action.describe_text} shows
+      # them too (only when there are any, like the core sections).
+      #
+      # @return [Hash{Symbol=>Object}]
+      def describe
+        summary = super
+        summary[:hooks] = summary[:hooks].merge(after_commit: after_commit_hooks.map(&:name))
+        summary
+      end
+
+      # Give each subclass its own copy of the inherited +after_commit+ hooks.
+      #
+      # @param subclass [Class]
+      # @return [void]
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@after_commit_hooks, after_commit_hooks.dup)
+      end
+
+      private
+
+      # Extend the run-start guard (decision D18) to the +after_commit+ hooks.
+      #
+      # @param instance [Action]
+      # @return [void]
+      def ensure_steps_implemented!(instance)
+        super
+        missing = after_commit_hooks.flat_map(&:required_methods).uniq.reject { |method| implements?(instance, method) }
+        return if missing.empty?
+
+        raise DefinitionError,
+          "#{name || "action"} declares after_commit hook(s) calling #{missing.map(&:inspect).join(", ")} " \
+          'but does not implement them'
+      end
+
+      # Extend the recording-verb position check (owner ruling R5) to the
+      # +after_commit+ hooks.
+      #
+      # @return [Array<Steps::Base>]
+      def verb_checked_steps
+        super + after_commit_hooks.to_a
+      end
+
+      # @raise [DefinitionError] when +after_all_transactions_commit+ is unavailable
+      # @return [void]
+      def ensure_after_commit_supported!
+        return if defined?(::ActiveRecord) && ::ActiveRecord.respond_to?(:after_all_transactions_commit)
+
+        raise DefinitionError,
+          "after_commit needs ActiveRecord >= #{MINIMUM_ACTIVE_RECORD} " \
+          '(ActiveRecord.after_all_transactions_commit); load a supported ActiveRecord before declaring it'
+      end
+    end
+
+    # Prepended onto {Actionable::Runner} (outside {RunnerTransaction}) to
+    # register a successful run's +after_commit+ hooks once the run, and its
+    # own transaction, are over.
+    module RunnerAfterCommit
+      # @return [Result]
+      def run
+        result = super
+        schedule_after_commit if result.success?
+        result
+      end
+
+      private
+
+      # @return [void]
+      def schedule_after_commit
+        klass = @instance.class
+        return unless klass.respond_to?(:after_commit_hooks)
+
+        hooks = klass.after_commit_hooks.to_a
+        return if hooks.empty?
+
+        ::ActiveRecord.after_all_transactions_commit { run_after_commit_hooks(hooks) }
+      end
+
+      # Run the hooks in order. A halt stops the remaining ones; nothing they
+      # record reaches the already-returned result.
+      #
+      # @param hooks [Array<Steps::Base>]
+      # @return [void]
+      def run_after_commit_hooks(hooks)
+        Actionable.catch_halt do
+          hooks.each { |hook| hook.call(@instance) unless hook.skip?(@instance) }
+        end
+      end
+    end
+  end
+end