errata

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.

Basic Concepts

errata's philosophy is that errors should have at least a static error code and a human-readable message.

• the code is searchable, and because it's static it becomes more easily searchable
• the message is 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.

Definitions

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?

Code Generation

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=errors

This 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).

Web UI

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

$ eish serve --source=errata.hcl

The web UI by default runs on port 37707.

Supported Languages

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