Skip to content

Declared failures and result codes

Picture a caller that has to deal with this failure code.

fail!(:fog_bound)

Nothing in the class says it can happen. To find out, you read every step and every child action and trust that you saw them all. Codes were free-form, so nobody (a person or a tool) could learn an action’s contract without reading its body.

class CastOff < Actionable::Action
fails :fog_bound, 'harbour closed by fog', retry: false
fails :gauge_offline, retry: true
skips :already_underway
step :go
private
def go = fail!(:fog_bound)
end
CastOff.declared_failures # => {fog_bound: {retry: false}, gauge_offline: {retry: true}}
CastOff.declared_skips # => {already_underway: {}}

That list is the contract, and a reader, a test, a retry policy and a type generator all need the very same thing from it.

Declaring any failure code means the action can fail only with those. A typo then raises the first time it fires, where before it became a result nobody handled.

class Slip < Actionable::Action
fails :fog_bound
step :go
private
def go = fail!(:fog_bond)
end
begin
Slip.run
rescue Actionable::DefinitionError => e
e.message.include?('does not declare') # => true
end

An action that declares nothing is left unchecked, so this is opt-in per action. We lean toward adopting it for anything other code calls and skipping it for a one-off script.

Skips follow the same contract, with no exemption. The gem emits no skip codes of its own, so once you declare any skip, even a bare skip! has to be declared. Failures and skips are strict on their own: declaring one kind does not make the other strict. The gem’s two failure codes, :invalid_input and :invalid_output, are always allowed because the gem itself produces them.

The retry: false above is metadata. The core keeps it, shows it in describe and puts it on the result, but never interprets it. Two reasons for that. A free-form keyword on fail used to collide with error field names, so metadata lives apart from errors. And a core that understands retries ends up with opinions about queues, and those belong in an adapter.

Only one reader exists, and you load it on purpose: the job adapter, which reads retry: unless an action opts out (see Run in a background job). Anything else you attach is yours.

When every ending of an action is written down, several things come along for free.

  • Tools can tell a model or a client what an action may return
  • A retry policy comes from the declaration, so no job needs its own list
  • A suite can ask which declared outcomes no spec has reached. That is outcome coverage, and a named baseline keeps a new gap from hiding behind an old one
  • Stubs can refuse a code the action can never produce, so a spec can’t test a failure that does not exist
  • Generated types can name the codes

None of these needed a new idea. They fall out of having the list.

You write the codes down and keep them true. An undeclared code fails loudly, which we think is the right way round, though it does mean adding a line whenever a new case appears. The checks also happen at call time, so a branch that rarely fires is checked the first time it does, not when the class loads. We haven’t found a way to check every branch statically without running the code.

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