How to run an action in a background job
A PullTimetable job downloads a ferry timetable. A :tide_late answer deserves another try while :garbled never will, so the queue has to know which one it got.
1. Declare the codes and say which retry
Section titled “1. Declare the codes and say which retry”Write the decision beside the code, as retry: metadata. The core never reads metadata by itself, but the job adapter does once actionable/job is loaded. An action that should ignore it says honor_retry_metadata(enabled: false).
require 'actionable/job'
class PullTimetable < Actionable::Action input { required :source, :string }
fails :tide_late, retry: true fails :garbled, retry: false
step :download
private
def download fail!(:tide_late) if input.source.include?('stalled') fail!(:garbled) if input.source.include?('scrambled') succeed('timetable loaded') endend2. Include the mixin in the job
Section titled “2. Include the mixin in the job”run_actionable runs the action and keeps its result. It raises Actionable::Job::RetryableFailure when the result deserves a retry, and for an acknowledged or discarded one it returns the result, so the job ends.
ActiveJob needs to be told to retry that error. Sidekiq retries every job that raises, so there is nothing to add.
class PullTimetableJob < ApplicationJob include Actionable::Job::Mixin retry_on Actionable::Job::RetryableFailure, wait: :polynomially_longer, attempts: 5
def perform(source) result = run_actionable(PullTimetable, source: source) Rails.logger.warn("timetable dropped: #{result.code}") if result.failure? endendclass PullTimetableWorker include Sidekiq::Job include Actionable::Job::Mixin
def perform(source) run_actionable(PullTimetable, source: source) endend3. See each disposition
Section titled “3. See each disposition”No queue gem is needed to try the mixin. A plain object will do.
class TimetableRunner include Actionable::Job::Mixin
def perform(source) = run_actionable(PullTimetable, source: source)end
runner = TimetableRunner.newrunner.perform('https://example.org/quay.json').success? # => truerunner.perform('https://example.org/scrambled').code # => :garbled
begin runner.perform('https://example.org/stalled')rescue Actionable::Job::RetryableFailure => e e.message # => "actionable run failed with retryable code :tide_late" e.result.code # => :tide_lateend4. Change what counts as permanent
Section titled “4. Change what counts as permanent”Without a retry: key, or in an action that opted out with honor_retry_metadata(enabled: false), every failure gets a retry unless its code is permanent. Out of the box the permanent codes are :invalid_input, :invalid_output and :not_found, because retrying input the action already refused can’t change the answer. To use another list, override actionable_permanent_codes.
class PickyRunner include Actionable::Job::Mixin
def actionable_permanent_codes = %i[garbled]end
Actionable::Job.disposition(Actionable::Failure.new(code: :tide_late)) # => :retryActionable::Job.disposition(Actionable::Failure.new(code: :invalid_input)) # => :discardActionable::Job.disposition(Actionable::Failure.new(code: :tide_late), permanent: [:tide_late]) # => :discardPickyRunner.new.actionable_permanent_codes # => [:garbled]An exception raised inside the action is not a failure. The mixin lets it through untouched, and your queue’s usual retry rules take over.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.