Repository files navigation

errata is a general purpose, language-agnostic toolkit forerror code enumeration (ECE).

ECE is the process of defining all the ways in which your software can fail. Think of it as negative documentation (describing how your systemfails as opposed to how itworks).

Consider a web application.Aren't HTTP status codes enough? No. They are sometimes useful (404 Not Found is fairly clear), but others are so vague as to be pretty meaningless (500 Internal Server Error). Often an additional semantic layer is required to communicate what exactly went wrong, and what the caller (be they a human, an API client, etc) can do in response. HTTP status codes are perfect for describing thecategory of problem (4xx client error, 5xx server error), but insufficient for the complex software of today.

Major API vendors such asTwilio,Instagram, andGoogle Cloud recognise this and use ECE in some form.errata aims to provide a mechanism for any software to deliver world-class error handling.

errata's philosophy is that errors should haveat least a static errorcode and a human-readablemessage.

• thecode is searchable, and because it's static it becomesmore easily searchable
• themessage is displayed to the user alongside the code, to provide immediate context, and ideally to give an insight into what went wrong

Besides the basiccode andmessage, including other valuable metadata like a unique reference (particularly useful in SaaS applications), labels, user guides, etc can be included.

errata uses theHCL structured configuration language, used primarily byTerraform. It's extensible, simple to read and write, and frankly -fuck YAML.

version="0.1"error"file-not-found" {message="File path is incorrect or inaccessible"categories=["file"]guide="Ensure the given file exists and can be accessed"args=[arg("path","string")  ]labels={    severity="warn"  }}...

The above example defines thecode (file-not-found) and themessage, along with some other useful metadata (more on this below).

So, what can this definitions file be used for?

errata provides a language-agnostic mechanism for generating code based on these definitions using thePongo2 templating engine.

errata comes with a CLI tool calledeish (erratainteractiveshell,pronounced "eɪʃ") which generates code based on givenerrata definitions.

$ eish generate --source=errata.hcl --template=golang --package=errors

This will generate a single file with all error definitions. See thesample application which useserrata definitions (and rather recursively, theerrata library also useserrata definitions).

eish also provides a simple web UI, allowing yourerrata definitions to be viewed and searched.

$ eish serve --source=errata.hcl

The web UI by default runs on port37707.

If your language of choice is not yet available, consider contributing a template!

errata uses thePongo2 templating engine

• Golang (reference implementation)

The code produced byerrata aims to be:

• idiomatic
• easy to use
• using native error/exception types as much as possible