errata is a general purpose, language-agnostic toolkit for error 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 system fails as opposed to how it works).
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 the category of problem (4xx client error, 5xx server error), but insufficient for the complex software of today.
Major API vendors such as Twilio, Instagram, and Google 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 have at least a static error code and a human-readable message.
- the
codeis searchable, and because it's static it becomes more easily searchable - the
messageis displayed to the user alongside the code, to provide immediate context, and ideally to give an insight into what went wrong
Besides the basic code and message, including other valuable metadata like a unique reference (particularly useful in SaaS applications), labels, user guides, etc can be included.
errata uses the HCL structured configuration language, used primarily by Terraform. 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 the code (file-not-found) and the message, 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 the Pongo2 templating engine.
errata comes with a CLI tool called eish (errata interactive shell, pronounced "eɪʃ") which generates code based on given errata definitions.
$ eish generate --source=errata.hcl --template=golang --package=errorsThis will generate a single file with all error definitions. See the sample application which uses errata definitions (and rather recursively, the errata library also uses errata definitions).
eish also provides a simple web UI, allowing your errata definitions to be viewed and searched.
$ eish serve --source=errata.hclThe web UI by default runs on port 37707.
If your language of choice is not yet available, consider contributing a template!
errata uses the Pongo2 templating engine
- Golang (reference implementation)
The code produced by errata aims to be:
- idiomatic
- easy to use
- using native error/exception types as much as possible
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent