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'Job.disposition
Section titled “Job.disposition”Actionable::Job.disposition(result, permanent: DEFAULT_PERMANENT_CODES, honor_retry: true)# => :ack | :discard | :retryWith 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) # => :ackActionable::Job.disposition(Actionable::Skipped.new) # => :ackActionable::Job.disposition(Actionable::Failure.new(code: :invalid_input)) # => :discardActionable::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) # => :retryActionable::Job.disposition(flagged, honor_retry: false) # => :discard
stop = Actionable::Failure.new(code: :rough_sea, metadata: { retry: false })Actionable::Job.disposition(stop) # => :discardActionable::Job.disposition(Actionable::Skipped.new(metadata: { retry: true })) # => :retryhonor_retry_metadata
Section titled “honor_retry_metadata”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: falseend
class StrictTideTable < TideTable honor_retry_metadata(enabled: false)end
TideTable.honor_retry_metadata? # => trueStrictTideTable.honor_retry_metadata? # => falseActionable::Action.honor_retry_metadata? # => trueTideTable.declared_failures # => {rough_sea: {retry: true}, smudged_chart: {retry: false}}Job::Mixin
Section titled “Job::Mixin”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) endendNo 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.newbegin worker.performrescue Actionable::Job::RetryableFailure => e e.message # => "actionable run failed with retryable code :rough_sea" e.result.code # => :rough_seaendworker.actionable_result.failure? # => trueRetryableFailure
Section titled “RetryableFailure”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.
See also
Section titled “See also”- Declared outcomes: where
retry:metadata is declared - Errors and guardrails: the exception classes
- Results:
metadataon failures and skips
FieldStruct, Actionable and their adapters are open source under the MIT license.