Failures – Jadpo

Your code says what went wrong, by name, and Jadpo decides how each failure reaches whoever called: the HTTP status, the response body and what is logged. Code never throws, never picks an HTTP status and never builds an error response.

Three kinds of thing can go wrong, and only the first is yours to declare:

A domain failure is an outcome your app expects, such as a todo that doesn't exist. You declare it and say where it can happen.
A fault is a problem outside your code: the database is down, a provider timed out, or a write may or may not have been saved. The runtime raises it.
A defect is a bug: a number overflowed, the recursion limit was reached, or the compiler got something wrong. The runtime raises it too.

	Declared by	Listed in `fails`	The client sees	The log gets
Domain failure, such as `TodoNotFound`	you, as `type X = Failure`	yes	its code, message and client fields	its code, where it was raised, the path it travelled and its internal fields
Fault, such as the database being down	the runtime	no	a fixed code for that fault	the cause chain
Defect, such as an overflow	the runtime	no	`internal_fault`	the cause and stack

Declaring a failure

A failure is a way an action or query can fail that its caller is expected to handle, such as stock running out.

Failure kinds

Every failure has a kind, which decides the HTTP status a client gets and what the failure means.

Saying what can fail: fails

A function or action lists the failures it can end with after fails, in its signature.

Raising a failure: reject

reject ends the callable with a declared failure.

Passing a failure on: attempt

attempt passes every failure of a call on to your caller, so each one must be in your own fails list.

Turning one failure into another

A failure can come from something the compiler knows can go wrong, such as a read that finds nothing, a write that breaks a unique rule or a construction, or from another call.

Handling a failure in match

A match on a call handles its outcome: one arm for success, and one for each failure the call can produce (Match).

What the client sees

Every failure reaches an HTTP client in the same envelope.

Faults

A fault is raised by the runtime when something outside your code goes wrong.

Concealing records

When policy hides a record from a caller, saying "forbidden" would reveal that it exists.

Logging not built

Every failure and fault writes one structured event.

Messages and languages

A failure's message is fixed English for developers and logs.