go-fyi

Explore the docs »

error.fyi's Golang client library. It is used to wrap errors and add extra context when the error is returned.

Installation · Get Started · Reference · Report Bug

---

Warning The project is not production ready.

Motivation ⭕

When developing a software application error messages tend to be an afterthought or forgotten all together, which in turn might make for a poor user experience when troubleshooting errors. With error.fyi I hope to improve the story around error messaging and troubleshooting.

An error wrapped with go-fyi should always be able to answer the following:

• What caused the issue?
• How they could solve the issue.
• What to do to solve the issue.

Installation 📦

go get -u github.com/error-fyi/go-fyi

Quickstart 🚀

Note error.fyi CLI is required to generate the error.yaml from comments. Alternatively you can manually create your error.yaml.

See Get Started for more information on generating the error.yaml.

package main

import (
  "errors"
  "log"
  _"embed"

  fyi "github.com/error-fyi/go-fyi"
)

//go:embed errors.yaml
var errorsYAML []byte

// @fyi name example-app
// @fyi title Example App
// @fyi base_url docs.example.com
// @fyi version v0.1.0
func main() {
  fyi.SetManifest(errorsYAML)
  err := doSomething()
  if err != nil {
    log.Fatal(err)
  }
}

func doSomething() error {
  // TODO improve this error message
  err := errors.New("something went wrong, please try again")
  // @fyi.error code main_error_18
  // @fyi.error title Transaction Error
  // @fyi.error short There was an error during transaction, value exceeded limit
  // @fyi.error severity low
  // @fyi.error.suggestion short Retry the transaction with a lower input value
  return fyi.Error(err, "main_error_18")
}

Output:

$ go run main.go
2023/10/03 22:46:12 [something went wrong, please try again]

   TRANSACTION ERROR                                                          
                                                                              
  ## What caused the error                                                    
                                                                              
  There was an error during transaction, value exceeded limit                 
                                                                              
  ## Quick Solutions                                                          
                                                                              
  │ Additional information is available at: docs.example.com/example-          
  │ app/errors/main_error_18                                                   
                                                                              
  • Suggestion: Retry the transaction with a lower input value                

exit status 1

example manifest

---
# Code generated by fyictl: https://github.com/tfadeyi/errors.
# DO NOT EDIT.
base_url: docs.example.com
errors_definitions:
    main_error_18:
        code: main_error_18
        meta:
            loc:
                filename: main.go
                line: 24
        severity: low
        short: There was an error during transaction, value exceeded limit
        suggestions:
            "1":
                error_code: main_error_18
                id: "1"
                short: Retry the transaction with a lower input value
        title: Transaction Error
name: example-app
title: Example App
version: v0.1.0

Annotations

Go-fyi uses in code annotations to add context to the errors returned to users. The list of all available annotations can be found here.

Annotations can be added manually next to the error in the code or automatically with the aid of fyictl, which parses the code for errors and annotates them.

# annotates and wraps errors in the file.go
fyictl annotate -f file.go --wrap

# annotates and wraps errors in all the go packages under the current directory
fyictl init --recursive --wrap

Examples

Wrap error

To wrap an error with go-fyi, pass the error as the first input and the code of the error as the second argument.

Warning Make sure the code is the same as the in code annotation.

package main
import (
	"errors"
	fyi "github.com/error-fyi/go-fyi"
)
func doSomething() error {
    // TODO improve this error message
    err := errors.New("something went wrong, please try again")
    // @fyi.error code main_error_18
    // @fyi.error title Transaction Error
    // @fyi.error short There was an error during transaction, value exceeded limit
    // @fyi.error severity low
    // @fyi.error.suggestion short Retry the transaction with a lower input value
    return fyi.Error(err, "main_error_18")
}

Wrap error with options

When wrapping errors with go-fyi, it's possible to customize how the target error will be displayed to the user.

package main
import (
	"errors"
	fyi "github.com/error-fyi/go-fyi"
)
func doSomething() error {
    // TODO improve this error message
    err := errors.New("something went wrong, please try again")
    // @fyi.error code main_error_18
    // @fyi.error title Transaction Error
    // @fyi.error short There was an error during transaction, value exceeded limit
    // @fyi.error severity low
    // @fyi.error.suggestion short Retry the transaction with a lower input value
    return fyi.Error(
		err, "main_error_18",
		fyi.WithDisplayErrorURL(false),
		fyi.WithRenderMarkdown(false),
		)
}

Global configuration

It's possible to configure go-fyi different options at a global level.

package main
import (
	_"embed"
	fyi "github.com/error-fyi/go-fyi"
)

//go:embed errors.yaml
var errorsYAML []byte

// @fyi name example-app
// @fyi title Example App
// @fyi base_url docs.example.com
// @fyi version v0.1.0
func main() {
	fyi.SetManifest(errorsYAML)
	fyi.SetDisplayErrorURL(false)
	fyi.SetSilence(true)
}

Development

Development is entirely done using Nix devshell, as such Nix should be present in the development machine.

$ source env-dev.sh
$ develop

This will boot up a Nix devshell with the need tools and information.

Contributing

Everyone is welcome to contribute to the project.

Please see CONTRIBUTING.md for information on how to get started.

Feedback is always appreciated, whether it's a bug or feature request, feel free to open an issue using one of the templates.

License

MIT, see LICENSE.md.