errors

Documentation

Overview

Custom errors.

Actually, common errors are also good but we can do better. And we need to do better if we want to unleash a potential to return great errors to clients. This package extends a standard library and adds its own wrappers we encourage to use. The main benefit of doing that is consistency in error management, integration into our JSONified error reporting etc.

When to use this errors? We encourage you to use Errors when you work with layers or executors. You can of course return any errors you like but then httransform is going to be limited in how it processes a data.

Index

• Constants
• func As(err error, target interface{}) bool
• func Is(err, target error) bool
• func New(text string) error
• func Unwrap(err error) error
• type Error
  • func Annotate(err error, message, code string, statusCode int) *Error
  • func (e *Error) Error() string
  • func (e *Error) ErrorJSON() string
  • func (e *Error) GetChainCode() string
  • func (e *Error) GetChainStatusCode() int
  • func (e *Error) GetCode() string
  • func (e *Error) GetMessage() string
  • func (e *Error) GetStatusCode() int
  • func (e *Error) Unwrap() error
  • func (e *Error) WriteTo(ctx *fasthttp.RequestCtx)
• type ErrorJSON
• type ErrorRenderer

Constants

const (
	// DefaultChainStatusCode is used if we do not have ANY status code
	// in correct error chain.
	DefaultChainStatusCode = fasthttp.StatusInternalServerError

	// DefaultChainErrorCode is used if we do not have ANY code in
	// correct error chain.
	DefaultChainErrorCode = "internal_error"
)

Functions

func As

func As(err error, target interface{}) bool

As is just calling stderrors.As. It is here for convenience.

func Is

func Is(err, target error) bool

Is is just calling stderrors.Is. It is here for convenience.

func New

func New(text string) error

New created a new Error from this package.

func Unwrap

func Unwrap(err error) error

Unwrap is just calling stderrors.Unwrap. It is here for convenience.

Types

type Error

type Error struct {
	// StatusCode defines a status code which should be returned to a
	// client.
	StatusCode int

	// Message defines some custom message which is specific for this
	// error.
	Message string

	// Code defines a special code for machine-readable processing.
	Code string

	// Err keeps an original error
	Err error
}

Error defines a custom error which can be returned from a layer or executor. This error has a stack of attached errors and can render JSON. Also, it keeps a status code so if you are searching for a correct way of setting your own response code, this is a best one.

It is important to keep Error chain consistent. If we have an error chain like Error -> Error -> ??? -> Error -> ??? -> Error, then only first 2 errors are going to be used for JSON generation.

func Annotate

func Annotate(err error, message, code string, statusCode int) *Error

Annotate wraps/chains error into new Error instance.

func (*Error) Error

func (e *Error) Error() string

Error to conform error interface.

func (*Error) ErrorJSON

func (e *Error) ErrorJSON() string

ErrorJSON returns a JSON encoded representation of the error.

JSON has a following structure:

{
  "error": {
    "code": "executor",
    "message": "cannot execute a request",
    "stack": [
      {
        "code": "executor",
        "message": "cannot execute a request",
        "status_code": 0
      },
      {
        "code": "",
        "message": "cannot dial to the netloc",
        "status_code": 0
      },
      {
        "code": "",
        "message": "cannot upgrade connection to tls",
        "status_code": 0
      },
      {
        "code": "tls_handshake",
        "message": "cannot perform TLS handshake",
        "status_code": 0
      },
      {
        "code": "",
        "message": "x509: cannot validate certificate for 23.23.154.131 because it doesn't contain any IP SANs",
        "status_code": 0
      }
    ]
  }
}

* code is a first chain code of the error

* message is own error message

* stack has a list of errors (last error is initiator) with similar structure.

func (*Error) GetChainCode

func (e *Error) GetChainCode() string

GetChainCode returns an error code of the whole error chain.

Lets assume that we have errors A, B. A wraps B, B wraps C. Code of A is "" (default one), B - "foo", C - "bar". So, we have a chain of statuses "" -> "foo" -> "bar". GetChainCode returns a first != "" status ("foo" in our case). If whole chain is empty, it returns "internal_error".

func (*Error) GetChainStatusCode

func (e *Error) GetChainStatusCode() int

GetChainStatusCode returns a status code of the whole error chain.

Lets assume that we have errors A, B. A wraps B, B wraps C. Status code of A is 0 (default one), B - 400, C - 500. So, we have a chain of statuses 0 -> 400 -> 500. GetChainStatusCode returns a first != 0 status (400 in our case). If whole chain is empty, it returns 500.

func (*Error) GetCode

func (e *Error) GetCode() string

GetCode returns a code of THIS error (not a chain one). It also works with nil pointers so it is a preferrable way of getting a data out of this error.

func (*Error) GetMessage

func (e *Error) GetMessage() string

GetMessage returns a message of THIS error (not a chain one). It also works with nil pointers so it is a preferrable way of getting a data out of this error.

func (*Error) GetStatusCode

func (e *Error) GetStatusCode() int

GetStatusCode returns a status code of THIS error (not a chain one). It also works with nil pointers so it is a preferrable way of getting a data out of this error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap to conform go 1.13 error interface.

func (*Error) WriteTo

func (e *Error) WriteTo(ctx *fasthttp.RequestCtx)

WriteTo writes this error into a given fasthttp request context.

type ErrorJSON

type ErrorJSON interface {
	error

	// ErrorJSON returns JSON string of the error.
	ErrorJSON() string
}

ErrorJSON is just an interface for error which can render itself into JSONs.

type ErrorRenderer

type ErrorRenderer interface {
	error

	// WriteTo dumps a contents of the error into fasthttp request context.
	WriteTo(*fasthttp.RequestCtx)
}

ErrorRenderer is ErrorJSON which an render itself into fasthttp request ctx.