Errors and guardrails
There are only a few exception classes, but a lot of checks happen at declaration time, so a misconfigured action fails loudly the first time it loads or runs. Each message names the action (action when the class is anonymous) and what is wrong. One rule is different from the rest: a real exception raised inside a step, hook or guard passes straight out of .run, because the runner never rescues one.
Exception classes
Section titled “Exception classes”| Class | Raised when |
|---|---|
Actionable::Error |
base of everything this gem raises |
Actionable::DefinitionError |
a misconfigured action (below); also used by the adapters |
Actionable::Job::RetryableFailure |
run_actionable for a result that should be retried; has result |
Actionable::Coverage::BaselineMismatch |
the coverage report differs from its baseline |
ArgumentError |
a bad argument: a code that is not an identifier, an unsupported step target, a bad measure mode |
FieldStruct::UnknownAttributeError |
input with unknown_attributes :raise and an extra keyword |
DefinitionError, RetryableFailure and BaselineMismatch all inherit from Actionable::Error. The coverage report also raises Actionable::Error itself, for a missing baseline file or for a glob that matches no shard files.
Actionable::DefinitionError.ancestors.include?(Actionable::Error) # => trueActionable::Error.superclass # => StandardErrorFieldStruct::UnknownAttributeError.ancestors.include?(Actionable::Error) # => falseChecks that raise DefinitionError
Section titled “Checks that raise DefinitionError”| Check | When | Message starts |
|---|---|---|
| missing step or hook method | start of .run |
<Action> declares step(s) calling :a, :b and hook(s) calling :c but does not implement them |
| undeclared failure code | at the fail call |
<Action> fails with :x, which it does not declare; declare it with fails :x (declared: ...) |
| undeclared skip code | at the skip call |
<Action> skips with :x, which it does not declare; ... |
| reserved output name | at the output or fails/skips block |
<Action>: output field(s) :code conflict with reserved result attributes / methods / instance variables; rename them |
| output for a code without a schema | at the call, typed outcomes on | <Action> fails with :x and output, but :x declares no output schema; declare one with fails :x do … end`` |
| own result constant | turning on typed_outcomes |
<Action> has its own Success, which typed outcomes would replace; rename it |
| verb not last | first .run of a class |
one line per offense, see below |
| unknown step option | at the step, hook or case_step declaration |
unknown step option iff: on Kiln#fire (did you mean if:?) |
| a second description | at desc or description |
<Action> already has a description; give it once, with desc or description |
after_commit without ActiveRecord 7.2 |
at the declaration | see Rails adapter |
bare halt! |
after the main steps, nothing recorded | <Action>: halt! with nothing recorded; record an outcome first, or use skip! |
ActiveRecord::Rollback in a transactional run |
after the rollback | <Action>: a step raised ActiveRecord::Rollback; call fail! to roll back a transactional action |
class RaiseGangway < Actionable::Action step :missing_stepend
begin RaiseGangway.runrescue Actionable::DefinitionError => e e.message # => "RaiseGangway declares step(s) calling :missing_step but does not implement them"end
begin Class.new(Actionable::Action) { output { required :code, :string } }rescue Actionable::DefinitionError => e e.message.start_with?('action: output field(s) :code conflict') # => trueendThe missing-method check looks at steps, hooks, case-step value sources and branch targets, plus after_commit hooks once the Rails adapter is loaded. A method is implemented when the instance has it, public or private, and it doesn’t belong to Kernel, Object or BasicObject, which is why step :puts fails. Steps that a guard would skip are checked as well, but the guard methods themselves are not.
The declared-code checks fire at the call, so a code nobody reaches never raises. The gem’s own codes are always allowed on failures. See Declared outcomes.
The verb-position check
Section titled “The verb-position check”The first time a class runs, Prism reads every step and hook method and flags any plain verb (fail, fail_with, skip, succeed, bare or on self) that has code after it. Every offense in every method comes back together in a single DefinitionError:
Moor#tie_up (app/actions/moor.rb:6) calls `fail` with more code after it, which still runs: use fail! to stop here, or make it the method's last expression(see USAGE, Control flow)Control flow lists the tail positions that are accepted. How the check behaves:
- It happens once per class. A pass is remembered and a failure is not, so the error repeats on each run until you fix it.
- Source files are read and cached by path and modification time. Methods with no readable source (
eval,define_method, C), files that don’t parse, and a Prism that can’t load are all skipped without an error. - For a step made with
alias_method, the originaldefis what gets checked. If a module is prepended over a step method, it hides the class’s owndefand only the wrapper’s body is read. Actionable.verb_position_check = falsedisables the check for the whole process. Nothing is parsed and no class is marked as checked, so switching it back on checks each class at its next run.
Checks that raise ArgumentError
Section titled “Checks that raise ArgumentError”| Check | Message contains |
|---|---|
| a code that is not an identifier | failure code "a b" is not an identifier; use a Symbol like :out_of_stock |
fails or skips with a code that is not an identifier, at the declaration |
fails code 5 is not an identifier; use a Symbol like :out_of_stock |
step with an unsupported target |
unsupported step target: 5 |
| a guard that is neither a method name nor a callable, at the declaration | Kiln#fire: if: takes a method name (Symbol or String) or a callable, got Integer (5) |
desc, or a desc: on a step, hook or code, that isn’t a String |
Kiln#fire: desc: takes a String, got Integer |
unknown measure mode |
unknown measure mode :weird |
register_step_option with a built-in key, a key another owner registered, or no owner |
step option if: is built into actionable-rb and can't be registered |
:sampled without a valid rate |
measure :sampled requires rate: between 0 and 1, got 3 |
a schema block on :invalid_input or :invalid_output |
is a gem failure code and cannot declare an output schema |
output: that is not a Hash or a FieldStruct |
output: must be a Hash or a FieldStruct, got Integer |
an action whose initialize needs arguments, run with an input schema |
Ruby’s own wrong number of arguments |
begin Class.new(Actionable::Action) { step 5 }rescue ArgumentError => e e.message # => "unsupported step target: 5"end
begin Class.new(Actionable::Action) { measure :sampled, rate: 3 }rescue ArgumentError => e e.message # => "measure :sampled requires rate: between 0 and 1, got 3"endInput that raises instead of failing
Section titled “Input that raises instead of failing”With unknown_attributes :raise in the schema, an undeclared keyword makes .run raise FieldStruct::UnknownAttributeError and no Failure(:invalid_input) comes back. That is the one case where input handling raises.
class ReadTideTable < Actionable::Action input do required :harbour, :string unknown_attributes :raise end
step :go
private
def go = succeedend
begin ReadTideTable.run(harbour: 'x', extra: 1)rescue FieldStruct::UnknownAttributeError => e e.class # => FieldStruct::UnknownAttributeErrorendSee also
Section titled “See also”- Control flow: where plain verbs are allowed
- RuboCop cop: the same offenses in your editor
- Exceptions in field_struct: the struct-side classes
FieldStruct, Actionable and their adapters are open source under the MIT license.