Typed error wrapper for Trebejo command failures.
Wraps the raw {:error, reason} from Arrea.Command (or any other
source) into a %Trebejo.Error{} struct so callers can pattern-match
on a single error type without inspecting raw exit codes or stderr
strings.
Fields
:kind— atom describing the failure category (seekind/0).:exit_status— integer exit code reported by the process, when available.nilfor non-process errors (timeout, port crash).:cmd— command line that was attempted (string).:stderr— captured stderr (or merged output) for diagnostics, trimmed.nilif not captured.:reason— raw underlying reason (atom, tuple, or string).:duration_ms— wall-clock time spent before the error, in ms. Useful to distinguish a 31s timeout from a 30s+1ms timeout.
Kind taxonomy
| kind | when |
|---|---|
:not_found | exit 127 — command not found |
:permission_denied | exit 126 — binary exists but not executable |
:invalid_args | exit 2/64/65 — bad arguments / syntax error |
:timeout | command exceeded the configured timeout |
:signal | process killed by a signal (e.g. SIGTERM → 137) |
:exit_nonzero | non-zero exit status that doesn't map to a more specific kind |
:port_closed | the streaming port closed before EOF |
:circuit_open | the call was rejected by Arrea.CircuitBreaker |
:rate_limited | the call was rejected by Arrea.RateLimiter |
:bulkhead_full | the call was rejected by Arrea.Bulkhead |
:unknown | fallback for anything that does not match the taxonomy above |
Summary
Functions
Classify a Unix exit code into a kind/0.
Build a %Trebejo.Error{} from an exit code, stderr and command line.
Render the error as a one-line, human-readable string.
Wrap a raw {:error, reason} from Arrea.Command (or any executor).
Types
@type kind() ::
:not_found
| :permission_denied
| :invalid_args
| :timeout
| :signal
| :exit_nonzero
| :port_closed
| :circuit_open
| :rate_limited
| :bulkhead_full
| :unknown
@type t() :: %Trebejo.Error{ cmd: String.t() | nil, duration_ms: non_neg_integer() | nil, exit_status: non_neg_integer() | nil, kind: kind(), reason: term(), stderr: String.t() | nil }
Functions
@spec classify_exit(non_neg_integer()) :: kind()
Classify a Unix exit code into a kind/0.
@spec from_exit(non_neg_integer(), String.t(), String.t() | nil, keyword()) :: t()
Build a %Trebejo.Error{} from an exit code, stderr and command line.
Examples
iex> Trebejo.Error.from_exit(127, "", "nonexistent")
%Trebejo.Error{kind: :not_found, exit_status: 127, ...}
iex> Trebejo.Error.from_exit(126, "perm denied", "./bin")
%Trebejo.Error{kind: :permission_denied, exit_status: 126, ...}Render the error as a one-line, human-readable string.
Wrap a raw {:error, reason} from Arrea.Command (or any executor).
Recognises :timeout and passes through Arrea-side reasons as-is.