Skip to content

Background jobs

Inside your job class, the adapter runs an action and converts its result into a queue disposition. It is plain Ruby and wants neither queue gem. The run stays synchronous, and nothing gets enqueued by the adapter. Require it yourself:

require 'actionable/job'
Actionable::Job.disposition(result, permanent: DEFAULT_PERMANENT_CODES, honor_retry: true)
# => :ack | :discard | :retry

With honor_retry: false, or for a result with no retry key in its metadata:

Result Disposition
success or skip :ack
failure whose code is in permanent :discard
any other failure :retry

DEFAULT_PERMANENT_CODES is [:invalid_input, :invalid_output, :not_found], because retrying input the action already turned down can’t help.

By default the retry key in a failure’s or skip’s metadata settles the question on its own. Truthy means :retry, permanent code or not, skip or not. Falsy means :discard for a failure and :ack for a skip. A result without that key, and any success, follows the table above. Results that don’t respond to metadata are never affected by the flag. Pass honor_retry: false to use only the table.

require 'actionable/job'
Actionable::Job::DEFAULT_PERMANENT_CODES # => [:invalid_input, :invalid_output, :not_found]
Actionable::Job.disposition(Actionable::Success.new) # => :ack
Actionable::Job.disposition(Actionable::Skipped.new) # => :ack
Actionable::Job.disposition(Actionable::Failure.new(code: :invalid_input)) # => :discard
Actionable::Job.disposition(Actionable::Failure.new(code: :rough_sea)) # => :retry
Actionable::Job.disposition(Actionable::Failure.new(code: :rough_sea), permanent: [:rough_sea]) # => :discard
flagged = Actionable::Failure.new(code: :invalid_input, metadata: { retry: true })
Actionable::Job.disposition(flagged) # => :retry
Actionable::Job.disposition(flagged, honor_retry: false) # => :discard
stop = Actionable::Failure.new(code: :rough_sea, metadata: { retry: false })
Actionable::Job.disposition(stop) # => :discard
Actionable::Job.disposition(Actionable::Skipped.new(metadata: { retry: true })) # => :retry
honor_retry_metadata(enabled: true)
honor_retry_metadata?

Once the adapter is loaded, jobs read retry metadata by default. An action opts out with honor_retry_metadata(enabled: false), and a subclass can switch it back on with honor_retry_metadata. The reader looks up the superclass chain at call time and answers true unless someone switched it off. The macro only exists on Action once the adapter is loaded, and the core itself still never reads metadata. You declare the metadata itself with fails (see Declared outcomes).

require 'actionable/job'
class TideTable < Actionable::Action
fails :rough_sea, retry: true
fails :smudged_chart, retry: false
end
class StrictTideTable < TideTable
honor_retry_metadata(enabled: false)
end
TideTable.honor_retry_metadata? # => true
StrictTideTable.honor_retry_metadata? # => false
Actionable::Action.honor_retry_metadata? # => true
TideTable.declared_failures # => {rough_sea: {retry: true}, smudged_chart: {retry: false}}

Mix Actionable::Job::Mixin into a Sidekiq worker or an ActiveJob class to get:

Member Meaning
run_actionable(action_class, *args, **kwargs) run the action, keep the result, raise on :retry, otherwise return the result
actionable_result the result of the last run_actionable
actionable_permanent_codes the permanent list; override it to change the codes

When the action responds to honor_retry_metadata?, run_actionable takes honor_retry from it. On :ack and :discard it hands back the result, so the job ends normally and the caller can decide whether a discard is worth logging. A real exception from inside the action passes through untouched. ActiveJob needs retry_on Actionable::Job::RetryableFailure declared, while Sidekiq already retries any job that raises.

class TideTableJob < ApplicationJob
include Actionable::Job::Mixin
retry_on Actionable::Job::RetryableFailure, wait: :polynomially_longer
def perform(harbour)
run_actionable(TideTable, harbour: harbour)
end
end

No queue gem is needed for the mixin, so a plain object will do for a try:

require 'actionable/job'
class Choppy < Actionable::Action
fails :rough_sea
step :sail
private
def sail = fail!(:rough_sea)
end
class DispatchWorker
include Actionable::Job::Mixin
def perform = run_actionable(Choppy)
end
worker = DispatchWorker.new
begin
worker.perform
rescue Actionable::Job::RetryableFailure => e
e.message # => "actionable run failed with retryable code :rough_sea"
e.result.code # => :rough_sea
end
worker.actionable_result.failure? # => true

Actionable::Job::RetryableFailure.new(result) is an Actionable::Error with a result reader. Its message reads actionable run failed with retryable code :code for a failure, and actionable run skipped with retryable code :code for a retried skip.

FieldStruct, Actionable and their adapters are open source under the MIT license.