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 IsRegistered(c Code) bool
• func RegisterCode(c Code, HTTP int, GRPC codes.Code, desc string)
• func UnregisterCode(c Code)
• func Wrap(err error, message string, stacktrace ...any) error
• func WrapCode(err error, message string, code Code, stacktrace ...any) error
• type Builder
  • func B() *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

Examples

• Builder
• Builder.Msgf
• Error.Error

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 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(err error, message string, stacktrace ...any) error

func WrapCode

func WrapCode(err error, message string, code Code, stacktrace ...any) error

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() *Builder

B returns a new error builder.

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:"-"`
}

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