errs

README

errs

This package provides a simple error type that can be used to map errors to HTTP and GRPC status codes.

It is heavily inspired by encore.dev/beta/errs but adds support for GRPC codes.

Usage

• go docs https://pkg.go.dev/github.com/lordvidex/errs
• Examples:

package main

import (
	"fmt"
	"github.com/lordvidex/errs"
	"encoding/json"
)

func main() {
	err := errs.B().Code(errs.NotFound).Msg("user not found").Err()
	// err.Error() == "user not found"
	// err.HTTPCode() == 404
	// err.GRPCCode() == 5
	b, _ := json.Marshal(err)
	fmt.Println(string(b)) 
	// Outputs: {"code":"not_found", "message":"user not found"}
}

• check the tests for more usage and examples

References

• google.golang.org/grpc/codes for grpc codes

Documentation

Index

• Constants
• func ClearCodeRegister()
• func Convert(err error) error
• func IsRegistered(c Code) bool
• func RegisterCode(c Code, HTTP int, GRPC codes.Code, desc string)
• func UnregisterCode(c Code)
• func Wrap(child, parent error) error
• func WrapCode(err error, code Code, messages ...string) error
• func WrapMsg(err error, message ...string) error
• type Builder
  • func B(initial ...error) *Builder
  • func (b *Builder) Code(code Code) *Builder
  • func (b *Builder) Details(details ...any) *Builder
  • func (b *Builder) Err() error
  • func (b *Builder) Msg(msg ...string) *Builder
  • func (b *Builder) Msgf(format string, parameters ...any) *Builder
• type Code
  • func (c Code) GRPC() codes.Code
  • func (c Code) HTTP() int
  • func (c Code) MarshalJSON() ([]byte, error)
  • func (c Code) String() string
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Stack() []string
  • func (e *Error) Unwrap() error

Examples

• Builder
• Builder.Msgf
• Error.Error
• Error.Stack

Constants

const CodeSize = 15

CodeSize is the number of codes defined in the STL library. All codes defined by default are mapped from 0 to CodeSize - 1. CodeSize can be useful when creating additional codes for example:

const (
	// MyCode is a custom code.
	MyCode Code = errs.CodeSize + iota // = 15
 	ExtraCode // = 16
)

Functions

func ClearCodeRegister

func ClearCodeRegister()

ClearCodeRegister removes all registration made with the function RegisterCode

func Convert

func Convert(err error) error

Convert converts any error to an *Error type. If the error is already an *Error, it is returned as is. nil errors are returned as nil.

func IsRegistered

func IsRegistered(c Code) bool

IsRegistered returns true if a custom implementation or override is being used for the code.

func RegisterCode

func RegisterCode(c Code, HTTP int, GRPC codes.Code, desc string)

RegisterCode registers a new code OR overrides an existing one.

func UnregisterCode

func UnregisterCode(c Code)

UnregisterCode unregisters the custom implementation or override of a code provided from the RegisterCode function. When a code is unregistered, UnregisterCode is a no-op.

func Wrap

func Wrap(child, parent error) error

Wrap wraps an underlying error `child` with a new error `parent`.

- when the child error is nil, the parent error is returned as is.

- when the parent error is nil, the child error is returned as is.

- when both errors are nil, nil is returned.

func WrapCode

func WrapCode(err error, code Code, messages ...string) error

WrapCode wraps an underlying error with a new error, adding message to the error's previously existing message and setting the error code to code.

func WrapMsg

func WrapMsg(err error, message ...string) error

WrapMsg wraps an underlying error with a new error, adding message to the error's previously existing message

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Example

b := B().Code(Unknown).Msg("unknown error").Details("details")
err := b.Err()
str, _ := json.Marshal(err)
fmt.Println(string(str))

Output:
{"code":"unknown","message":["unknown error"]}

func B

func B(initial ...error) *Builder

B returns a new error builder. Optionally, you can pass an error instance to the builder, ONLY the first error will be used.

Possible cases:

1. B() -> new error

2. B(err) -> update existing error (because of pointers) and returns it after calling Err()

3. B(err1, err2, err3) -> updates only err1 and returns it after calling Err()

func (*Builder) Code

func (b *Builder) Code(code Code) *Builder

func (*Builder) Details

func (b *Builder) Details(details ...any) *Builder

func (*Builder) Err

func (b *Builder) Err() error

func (*Builder) Msg

func (b *Builder) Msg(msg ...string) *Builder

func (*Builder) Msgf

func (b *Builder) Msgf(format string, parameters ...any) *Builder

Example

b := B().Code(NotFound).Msgf("file not found: %s, %d", "details", 123)
err := b.Err()
str, _ := json.Marshal(err)
fmt.Println(string(str))

Output:
{"code":"not_found","message":["file not found: details, 123"]}

type Code

type Code int

Code is the type that represents an error code. It can map to HTTP and gRPC codes. In order to properly work with custom codes or code overrides: use the RegisterCode function after creating your new Code instance.

const (
	// Unknown is the default error code.
	Unknown Code = iota

	// Canceled indicates the operation was canceled or unavailable because it was cancelled.
	Canceled

	// InvalidArgument is used when the client sends invalid arguments.
	InvalidArgument

	// DeadlineExceeded means operation expired before completion. This doesn't necessarily mean that the operation failed.
	// It is possible that the operation succeeded but the deadline was exceeded.
	DeadlineExceeded

	// Unauthenticated is used when the client is not authenticated.
	Unauthenticated

	// NotFound is used when the requested resource is not found.
	NotFound

	// AlreadyExists is used when the resource already exists.
	AlreadyExists

	// Forbidden is used when the client is not authorized to perform the requested operation.
	Forbidden

	// ResourceExhausted is used when the client has exhausted some resource.
	ResourceExhausted

	// FailedPrecondition is used when the client sends a request that is not allowed in the current state.
	FailedPrecondition

	// Aborted is used when the client sends a request that cannot be completed due to a conflict e.g. a concurrency issue.
	Aborted

	// OutOfRange means that the operation was attempted past the valid range.
	OutOfRange

	// Internal is used when an internal error occurs.
	Internal

	// Unavailable is used when the service cannot be reached due to some network issues.
	Unavailable

	// DataLoss is used when the service has lost some data.
	DataLoss
)

func (Code) GRPC

func (c Code) GRPC() codes.Code

GRPC returns the gPRC code that is mapped to the code.

func (Code) HTTP

func (c Code) HTTP() int

HTTP returns the HTTP code that is mapped to the code.

func (Code) MarshalJSON

func (c Code) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface and defines how a Code should be marshaled to JSON. By default, it marshals to a string representation defined by String function.

func (Code) String

func (c Code) String() string

String returns the string representation of the code.

type Error

type Error struct {
	// Code is the error code of the error. When marshaled to JSON, it will be a string.
	Code Code `json:"code"`

	// Msg is the user-friendly message returned to the client.
	Msg []string `json:"message"`

	// Details is the internal error message returned to the developer.
	Details []any `json:"-"`
	// contains filtered or unexported fields
}

func (*Error) Error

func (e *Error) Error() string

Example

err := B().Code(NotFound).Msg("item not found").Err()
fmt.Println(err.Error())

Output:
not_found: item not found

func (*Error) Is

func (e *Error) Is(target error) bool

func (*Error) Stack

func (e *Error) Stack() []string

Stack returns a description of the error and all it's underlying errors.

Example

err1 := B().Code(NotFound).Msg("item not found").Err()
err2 := B().Code(Internal).Msg("internal error").Err()
err, _ := Wrap(err2, err1).(*Error)
fmt.Print(err.Stack())

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying error.