errkind

README

errkind

Package errkind is used to create and detect specific kinds of errors.

Read the package documentation for more information.

Documentation

Overview

Package errkind is used to create and detect specific kinds of errors, based on single method interfaces that the errors support.

Supported interfaces

Temporary errors are detected using the “temporaryer” interface. Some errors in the Go standard library implement this interface. (See net.AddrError, net.DNSConfigError, and net.DNSError for examples).

type temporaryer interface {
    Temporary() bool
}

Some packages return errors which implement the `coder` interface, which allows the error to report an application-specific error condition.

type coder interface {
    Code() string
}

The AWS SDK for Go is a popular third party library that follows this convention.

In addition some third party packages (including the AWS SDK) follow the convention of reporting HTTP status values using the `statusCoder` interface.

type statusCoder interface {
    StatusCode() int
}

The publicMessager interface identifies an error as having a message suitable for displaying to a requesting client. The error message does not contain any implementation details that could leak sensitive information.

type publicMessager interface {
    PublicMessage()
}

The publicStatusCoder interface identifies an error has having a status code suitable for returning to a requesting client.

type publicStatusCoder interface {
    PublicStatusCode()
}

Index

• func BadRequest(msg ...string) errors.Error
• func Code(err error) string
• func Forbidden(msg ...string) errors.Error
• func HasCode(err error, codes ...string) bool
• func HasPublicMessage(err error) bool
• func HasStatusCode(err error, statusCodes ...int) bool
• func IsTemporary(err error) bool
• func NotFound(msg ...string) errors.Error
• func NotImplemented(msg ...string) errors.Error
• func Public(message string, status int) errors.Error
• func PublicWithCode(message string, status int, code string) errors.Error
• func Status(err error) int
• func StatusCode(err error) int
• func Temporary(msg string) errors.Error
• func Unauthorized(msg ...string) errors.Error

Examples

• BadRequest
• Forbidden
• NotImplemented

Functions

func BadRequest

func BadRequest(msg ...string) errors.Error

BadRequest returns an client error that has a status of 400 (bad request).

The returned error has a PublicStatusCode() method, which indicates that the status code is public and can be returned to a client.

Example

// supply a message
{
	err := BadRequest("message for bad request")
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

// don't supply a message
{
	err := BadRequest()
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

Output:

message for bad request (400)
bad request (400)

func Code

func Code(err error) string

Code returns the string error code associated with err, or a blank string if there is no code.

func Forbidden

func Forbidden(msg ...string) errors.Error

Forbidden returns an error that has a status of 403 (forbidden).

The returned error has a PublicStatusCode() method, which indicates that the status code is public and can be returned to a client.

Example

// supply a message
{
	err := Forbidden("message for forbidden")
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

// don't supply a message
{
	err := Forbidden()
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

Output:

message for forbidden (403)
forbidden (403)

func HasCode

func HasCode(err error, codes ...string) bool

HasCode determines whether the error has any of the codes associated with it.

func HasPublicMessage

func HasPublicMessage(err error) bool

HasPublicMessage returns true for errors that indicate that their message does not contain sensitive information and can be displayed to external clients.

An error has a public message if it implements the following interface.

type publicMessager interface {
    PublicMessage()
}

It usually makes sense to obtain the cause of an error first before testing to see if it is public. Any public error that is wrapped using errors.Wrap, or errors.With will return a new error that is no longer public.

// get the cause of the error
err = errors.Cause(err)
if errkind.HasPublicMessage(err) {
    // ... can provide err.Error() to the client
}

func HasStatusCode

func HasStatusCode(err error, statusCodes ...int) bool

HasStatusCode determines whether the error has any of the statuses associated with it.

func IsTemporary

func IsTemporary(err error) bool

IsTemporary returns true for errors that indicate an error condition that may succeed if retried.

An error is considered temporary if it implements the following interface and its Temporary method returns true.

type temporaryer interface {
    Temporary() bool
}

func NotFound

func NotFound(msg ...string) errors.Error

NotFound returns an error that has a status of 404 (not found).

The returned error has a PublicStatusCode() method, which indicates that the status code is public and can be returned to a client.

func NotImplemented

func NotImplemented(msg ...string) errors.Error

NotImplemented returns an error with a status of 501 (not implemented).

The returned error has a PublicStatusCode() method, which indicates that the status code is public and can be returned to a client.

Example

// supply a message
{
	err := NotImplemented("message for not implemented")
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

// don't supply a message
{
	err := NotImplemented()
	fmt.Printf("%v (%d)\n", err, StatusCode(err))
}

Output:

message for not implemented caller="example_test.go:44" (501)
not implemented caller="example_test.go:50" (501)

func Public

func Public(message string, status int) errors.Error

Public returns an error with the message and status. The message should not contain any implementation details as it may be displayed to a requesting client.

Note that if you attach any key/value pairs to the public error using the With method, then that will return a new error that is not public, as implementation details may be present in the key/value pairs. The cause of the new error, however, will still be public.

func PublicWithCode

func PublicWithCode(message string, status int, code string) errors.Error

PublicWithCode returns an error with the message, status and code. The code can be useful for indicating specific error conditions to a requesting client.

The message and code should not contain any implementation details as it may be displayed to a requesting client.

Note that if you attach any key/value pairs to the public error using the With method, then that will return a new error that is not public, as implementation details may be present in the key/value pairs. The cause of the new error, however, will still be public.

func Status

func Status(err error) int

Status does the same thing as StatusCode.

Deprecated: use StatusCode instead.

func StatusCode

func StatusCode(err error) int

StatusCode returns the status code associated with err, or zero if there is no status.

func Temporary

func Temporary(msg string) errors.Error

Temporary returns an error that indicates it is temporary.

func Unauthorized

func Unauthorized(msg ...string) errors.Error

Unauthorized returns a client error that has a status of 401 (unauthorized).

The returned error has a PublicStatusCode() method, which indicates that the status code is public and can be returned to a client.