errors

Documentation

Overview

Package errors provides a central interface to handling all errors in the Athens domain. It closely follows Upspin's error handling with a few differences that reflect the system design of the Athen's architecture. If you're unfamiliar with Upspin's error handling, we recommend that you read this article first before coming back here https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html. Athen's errors are central around dealing with modules. So every error will most likely carry a Module and a Version inside of them. Furthermore, because Athens is designed to run on multiple clouds, we have to design our errors and our logger to be friendly with each other. Therefore, the logger's SystemError method, although it accepts any type of error, it knows how to deal with errors constructed from this package in a debuggable way. To construct an Athens error, call the errors.E function. The E function takes an Op and a variadic interface{}, but the values of the Error struct are what you can pass to it. Values such as the error Kind, Module, Version, Error Message, and Seveirty (seriousness of an error) are all optional. The only truly required value is the errors.Op so you can construct a traceable stack that leads to where the error happened. However, adding more information can help catch an issue quicker and would help Cloud Log Monitoring services be more efficient to maintainers as you can run queries on Athens Errors such as "Give me all errors of KindUnexpected" or "Give me all errors where caused by a particular Module"

Index

• Constants
• func E(op Op, args ...interface{}) error
• func Expect(err error, kinds ...int) logrus.Level
• func Is(err error, kind int) bool
• func IsNotFoundErr(err error) bool
• func IsRepoNotFoundErr(err error) bool
• func Kind(err error) int
• func KindText(err error) string
• func Severity(err error) logrus.Level
• type Error
  • func (e Error) Error() string
• type M
• type Op
  • func Ops(err Error) []Op
  • func (o Op) String() string
• type V

Constants

const (
	KindNotFound       = http.StatusNotFound
	KindBadRequest     = http.StatusBadRequest
	KindUnexpected     = http.StatusInternalServerError
	KindAlreadyExists  = http.StatusConflict
	KindRateLimit      = http.StatusTooManyRequests
	KindNotImplemented = http.StatusNotImplemented
	KindRedirect       = http.StatusMovedPermanently
)

Kind enums

Functions

func E

func E(op Op, args ...interface{}) error

E is a helper function to construct an Error type Operation always comes first, module path and version come second, they are optional. Args must have at least an error or a string to describe what exactly went wrong. You can optionally pass a Logrus severity to indicate the log level of an error based on the context it was constructed in.

func Expect

func Expect(err error, kinds ...int) logrus.Level

Expect is a helper that returns an Info level if the error has the expected kind, otherwise it returns an Error level.

func Is

func Is(err error, kind int) bool

Is is a shorthand for checking an error against a kind.

func IsNotFoundErr

func IsNotFoundErr(err error) bool

IsNotFoundErr helper function for KindNotFound

func IsRepoNotFoundErr

func IsRepoNotFoundErr(err error) bool

IsRepoNotFoundErr returns true if the Go command line hints at a repository not found.

func Kind

func Kind(err error) int

Kind recursively searches for the first error kind it finds.

func KindText

func KindText(err error) string

KindText returns a friendly string of the Kind type. Since we use http status codes to represent error kinds, this method just deferrs to the net/http text representations of statuses.

func Severity

func Severity(err error) logrus.Level

Severity returns the log level of an error if none exists, then the level is Error because it is an unexpected.

Types

type Error

type Error struct {
	// Kind categories Athens errors into a smaller
	// subset of errors. This way we can generalize
	// what an error really is: such as "not found",
	// "bad request", etc. The official categories
	// are HTTP status code but the ones we use are
	// imported into this package.
	Kind     int
	Op       Op
	Module   M
	Version  V
	Err      error
	Severity logrus.Level
}

Error is an Athens system error. It carries information and behavior as to what caused this error so that callers can implement logic around it.

func (Error) Error

func (e Error) Error() string

Error returns the underlying error's string message. The logger takes care of filling out the stack levels and extra information.

type M

type M string

M represents a module in an error this is so that we can distinguish a module from a regular error string or version.

type Op

type Op string

Op describes any independent function or method in Athens. A series of operations forms a more readable stack trace.

func Ops

func Ops(err Error) []Op

Ops aggregates the error's operation with all the embedded errors' operations. This way you can construct a queryable stack trace.

func (Op) String

func (o Op) String() string

type V

type V string

V represents a module version in an error