{"id":20865886,"url":"https://github.com/dannykopping/errata","last_synced_at":"2025-05-12T10:32:42.853Z","repository":{"id":40592989,"uuid":"309918815","full_name":"dannykopping/errata","owner":"dannykopping","description":"Language-agnostic toolkit for error code enumeration","archived":false,"fork":false,"pushed_at":"2023-01-11T16:54:01.000Z","size":47576,"stargazers_count":15,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-01T06:03:06.666Z","etag":null,"topics":["ece","error-handling","error-messages","errors","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dannykopping.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-04T07:03:57.000Z","updated_at":"2025-03-21T08:43:16.000Z","dependencies_parsed_at":"2023-02-09T03:46:15.832Z","dependency_job_id":null,"html_url":"https://github.com/dannykopping/errata","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannykopping%2Ferrata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannykopping%2Ferrata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannykopping%2Ferrata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannykopping%2Ferrata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dannykopping","download_url":"https://codeload.github.com/dannykopping/errata/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253720140,"owners_count":21952979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ece","error-handling","error-messages","errors","golang"],"created_at":"2024-11-18T05:55:09.470Z","updated_at":"2025-05-12T10:32:37.840Z","avatar_url":"https://github.com/dannykopping.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# errata\n\n**errata** is a general purpose, language-agnostic toolkit for _error code enumeration (ECE)_.\n\nECE 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_).\n\nConsider 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. \n\nMajor API vendors such as [Twilio](https://www.twilio.com/docs/api/errors), [Instagram](https://developers.facebook.com/docs/instagram-api/reference/error-codes/), and [Google Cloud](https://cloud.google.com/resource-manager/docs/core_errors) recognise this and use ECE in some form. **errata** aims to provide a mechanism for any software to deliver world-class error handling.\n\n## Basic Concepts\n\n**errata**'s philosophy is that errors should have _at least_ a static error `code` and a human-readable `message`.\n\n- the `code` is searchable, and because it's static it becomes _more easily_ searchable\n- the `message` is displayed to the user alongside the code, to provide immediate context, and ideally to give an insight into what went wrong\n\nBesides 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.\n\n### Definitions\n\n**errata** uses the [HCL](https://github.com/hashicorp/hcl) structured configuration language, used primarily by [Terraform](https://www.terraform.io/). It's extensible, simple to read and write, and frankly - _fuck YAML_.\n\n```hcl\nversion = \"0.1\"\n\nerror \"file-not-found\" {\n  message    = \"File path is incorrect or inaccessible\"\n  categories = [\"file\"]\n  guide      = \"Ensure the given file exists and can be accessed\"\n  args       = [\n    arg(\"path\", \"string\")\n  ]\n  labels     = {\n    severity = \"warn\"\n  }\n}\n\n...\n```\n\nThe above example defines the `code` (**file-not-found**) and the `message`, along with some other useful metadata (more on this below).\n\nSo, what can this definitions file be used for?\n\n### Code Generation\n\n**errata** provides a language-agnostic mechanism for generating code based on these definitions using the [Pongo2](https://github.com/flosch/pongo2) templating engine.\n\n**errata** comes with a CLI tool called **eish** (_**e**rrata **i**nteractive **sh**ell_,\n[pronounced \"eɪʃ\"](http://ipa-reader.xyz/?text=e%C9%AA%CA%83)) which generates code based on given **errata** definitions.\n\n```bash\n$ eish generate --source=errata.hcl --template=golang --package=errors\n```\n\nThis will generate a single file with all error definitions. See the [sample application](sample/) which uses **errata** definitions (and rather recursively, the **errata** library also uses [**errata** definitions](errata.hcl)).\n\n### Web UI\n\n`eish` also provides a simple web UI, allowing your **errata** definitions to be viewed and searched.\n\n```bash\n$ eish serve --source=errata.hcl\n```\n\nThe web UI by default runs on port `37707`.\n\n![Web UI](web-ui.png)\n\n### Supported Languages\n\n_If your language of choice is not yet available, consider contributing a template!_\n\n\u003e _**errata** uses the [Pongo2](https://github.com/flosch/pongo2) templating engine_\n\n- [Golang](templates/golang.tmpl) (reference implementation)\n\nThe code produced by **errata** aims to be:\n\n- idiomatic\n- easy to use\n- using native error/exception types as much as possible","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannykopping%2Ferrata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannykopping%2Ferrata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannykopping%2Ferrata/lists"}