README
¶
Atlas App Toolkit Error Handling
This document is a brief overview of facilities provided by error handling package. The rationale for implementing it are four noble reasons:
- Provide ability to add specific details and field information to an error.
- Provide ability to handle multiple errors without returning control to a callee.
- Ability to map errors from 3-rd party libraries (gorm, to name one).
- Mapping from error to container should be performed automatically in gRPC interceptor.
Error Container
Error container is a data structure that implements Error interface and GRPCStatus method, enabling passing it around as a conventional error from one side and as a protobuf Status to gRPC gateway from the other side.
There are several approaches exist to work with it:
- Single error mode
- Multiple errors mode
Single Error Return
This code snippet demonstrates the usage of error container as conventional error:
func validateNameLength(name string) error {
if len(name) > 255 {
return errors.NewContainer(
codes.InvalidArgument, "Name validation error."
).WithDetail(
codes.InvalidArgument, "object", "Invalid name length."
).WithField(
"name", "Specify name with length less than 255.")
}
return nil
}
Gather Multiple Errors
func (svc *Service) validateName(name string) error {
err := errors.InitContainer()
if len(name) > 255 {
err = err.WithDetail(codes.InvalidArgument, "object", "Invalid name length.")
err = err.WithField("name", "Specify name with length less than 255.")
}
if strings.HasPrefix(name, "_") {
err = err.WithDetail(codes.InvalidArgument, "object", "Invalid name.").WithField(
"name", "Name cannot start with an underscore")
}
return err.IfSet(codes.InvalidArgument, "Invalid name.")
}
To gather multiple errors across several procedures use context functions:
func (svc *Service) globalValidate(ctx context.Context, input *pb.Input) error {
svc.validateName(ctx, input.Name)
svc.validateIP(ctx, input.IP)
// in some particular cases we expect that something really bad
// should happen, so we can analyse it and throw instead of validation errors.
if err := validateNamePermExternal(svc.AuthInfo); err != nil {
return errors.New(ctx, codes.Unauthorized, "Client is not authorized.").
WithDetails(/* ... */)
}
return errors.IfSet(ctx, codes.InvalidArgument, "Overall validation failed.")
// Alternatively if we want to return the latest errCode/errMessage set instead
// of overwriting it:
// return errors.Error(ctx)
}
func (svc *Service) validateName(ctx context.Context, name string) {
if len(name) > 255 {
errors.Detail(ctx, codes.InvalidArgument, "object", "Invalid name length.")
errors.Field(ctx, "name", "Specify name with length less than 255.")
}
}
func (svc *Service) validateIP(ctx context.Context, ip string) { /* ip validation */ }
Error Mapper
Error mapper performs conditional mapping from one error message to another. Error mapping functions are passed to a gRPC Error interceptor and called against error returned from handler.
Below we demonstrate a cases and customization techniques for mapping functions:
interceptor := errors.UnaryServerInterceptor(
// List of mappings
// Base case: simply map error to an error container.
errors.NewMapping(fmt.Errorf("Some Error"), errors.NewContainer(/* ... */).WithDetail(/* ... */)),
// Extended Condition, mapped if error message contains "fk_contraint" or starts with "pg_sql:"
// MapFunc calls logger and returns Internal Error, depending on debug mode it could add details.
errors.NewMapping(
errors.CondOr(
errors.CondReMatch("fk_constraint"),
errors.CondHasPrefix("pg_sql:"),
),
errors.MapFunc(func (ctx context.Context, err error) (error, bool) {
logger.FromContext(ctx).Debug(fmt.Sprintf("DB Error: %v", err))
err := errors.NewContainer(codes.Internal, "database error")
if InDebugMode(ctx) {
err.WithDetail(/* ... */)
}
// boolean flag indicates whether the mapping succeeded
// it can be used to emulate fallthrough behavior (setting false)
return err, true
})
),
// Skip error
errors.NewMapping(fmt.Errorf("Error to Skip"), nil)
)
Such model allows us to define our own error classes and map them appropriately as in example below:
// service validation code.
type RequiredFieldErr string
(e RequiredFieldErr) Error() { return string(e) }
func RequiredFieldCond() errors.MapCond {
return errors.MapCond(func(err error) bool {
_, ok := err.(RequiredFieldErr)
return ok
})
}
func validateReqArgs(in *pb.Input) error {
if in.Name == "" {
return RequiredFieldErr("name")
}
return nil
}
// interceptor init code
interceptor := errors.UnaryServerInterceptor(
errors.NewMapping(
RequiredFieldCond(),
errors.MapFunc(func(ctx context.Context, err error) (error, bool) {
return errors.NewContainer(
codes.InvalidArgument, "Required field missing: %v", err
).WithField(string(err), "%q argument is required.", string(err)
), true
}),
)
)
Documentation
¶
Overview ¶
The Error Container entity serves a purpose for keeping track of errors, details and fields information. This component can be used explicitly (for example when we want to sequentially fill it with details and fields), as well as implicitly (all errors that are returned from handler are transformed to an Error Container, and passed as GRPCStatus to a gRPC Gateway).
Index ¶
- Constants
- func Error(ctx context.Context) error
- func IfSet(ctx context.Context, code codes.Code, format string, args ...interface{}) error
- func Map(ctx context.Context, err error) error
- func NewContext(ctx context.Context, c *Container) context.Context
- func UnaryServerInterceptor(mapFuncs ...MapFunc) grpc.UnaryServerInterceptor
- type Container
- func Detail(ctx context.Context, code codes.Code, target string, format string, ...) *Container
- func Details(ctx context.Context, details ...*errdetails.TargetInfo) *Container
- func Field(ctx context.Context, target string, format string, args ...interface{}) *Container
- func Fields(ctx context.Context, fields map[string][]string) *Container
- func FromContext(ctx context.Context) *Container
- func InitContainer() *Container
- func New(ctx context.Context, code codes.Code, format string, args ...interface{}) *Container
- func NewContainer(code codes.Code, format string, args ...interface{}) *Container
- func Set(ctx context.Context, target string, code codes.Code, format string, ...) *Container
- func (c Container) Error() string
- func (c *Container) GRPCStatus() *status.Status
- func (c *Container) IfSet(code codes.Code, format string, args ...interface{}) error
- func (c *Container) IsSet() bool
- func (c *Container) New(code codes.Code, format string, args ...interface{}) *Container
- func (c *Container) Set(target string, code codes.Code, format string, args ...interface{}) *Container
- func (c *Container) WithDetail(code codes.Code, target string, format string, args ...interface{}) *Container
- func (c *Container) WithDetails(details ...*errdetails.TargetInfo) *Container
- func (c *Container) WithField(target string, format string, args ...interface{}) *Container
- func (c *Container) WithFields(fields map[string][]string) *Container
- type MapCond
- type MapFunc
- type Mapper
Constants ¶
const (
// Context key for Error Container.
DefaultErrorContainerKey = "Error-Container"
)
Variables ¶
This section is empty.
Functions ¶
func Error ¶
Error function returns an error container if any error field, detail or message was set, else it returns nil. Use New to define and return error message in place.
func IfSet ¶
IfSet function intializes general error code and error message for context stored error container if and onyl if any error was set previously by calling Set, WithField(s), WithDetails(s).
func Map ¶
Map function performs mapping based on context stored error container's mapping configuration.
func NewContext ¶
NewContext function creates a context with error container saved in it.
func UnaryServerInterceptor ¶
func UnaryServerInterceptor(mapFuncs ...MapFunc) grpc.UnaryServerInterceptor
UnaryServerInterceptor returns grpc.UnaryServerInterceptor that should be used as a middleware to generate Error Messages with Details and Field Information with Mapping given.
Types ¶
type Container ¶
type Container struct {
// Mapper structure performs necessary mappings.
Mapper
// contains filtered or unexported fields
}
Container struct is an entity that servers a purpose of error container and consist of methods to append details, field errors and setting general error code/message.
func Detail ¶
func Detail(ctx context.Context, code codes.Code, target string, format string, args ...interface{}) *Container
Detail function appends a new detail to a context stored error container's 'details' section.
func Details ¶
func Details(ctx context.Context, details ...*errdetails.TargetInfo) *Container
Details function appends a list of details to a context stored error container's 'details' section.
func Field ¶
Field function appends a field error detail to a context stored error container's 'fields' section.
func Fields ¶
Fields function appends a multiple fields error details to a context stored error container's 'fields' section.
func FromContext ¶
FromContext function retrieves an error container value from context.
func InitContainer ¶
func InitContainer() *Container
func New ¶
New function resets any error that was inside context stored error container and replaces it with a new error.
func NewContainer ¶
NewContainer function returns a new entity of error container.
func Set ¶
func Set(ctx context.Context, target string, code codes.Code, format string, args ...interface{}) *Container
Set function initializes a general error code and error message for context stored error container and also appends a details with the same content to an error container's 'details' section.
func (*Container) GRPCStatus ¶
GRPCStatus function returns an error container as GRPC status.
func (*Container) IfSet ¶
IfSet function initializes general error code and error message for error container if and only if any error was set previously by calling Set, WithField(s), WithDetail(s).
func (*Container) IsSet ¶
IsSet function returns flag that determines whether the main error code and error message were set or not.
func (*Container) New ¶
New function instantinates general error code and error message for error container.
func (*Container) Set ¶
func (c *Container) Set(target string, code codes.Code, format string, args ...interface{}) *Container
Set function initializes general error code and error message for error container and also appends a detail with the same content to a an error container's 'details' section.
func (*Container) WithDetail ¶
func (c *Container) WithDetail(code codes.Code, target string, format string, args ...interface{}) *Container
WithDetail function appends a new Detail to an error container's 'details' section.
func (*Container) WithDetails ¶
func (c *Container) WithDetails(details ...*errdetails.TargetInfo) *Container
WithDetails function appends a list of error details to an error container's 'details' section.
type MapCond ¶
MapCond function takes an error and returns flag that indicates whether the map condition was met.
func CondAnd ¶
CondAnd function takes a list of condition function as an input and returns a function that asserts true if and only if all conditions are satisfied.
func CondEq ¶
CondEq function takes a string as an input and returns a condition function that checks whether the error is equal to a string given.
func CondHasPrefix ¶
CondHasPrefix function takes a string as an input and returns a condition function that checks whether the error starts with the string given.
func CondHasSuffix ¶
CondHasSuffix function takes a string as an input and returns a condition function that checks whether the error ends with the string given.
func CondNot ¶
CondNot function takes a condtion function as an input and returns a function that asserts inverse result.
func CondOr ¶
CondOr function takes a list of condition function as an input and returns a function that asserts true if at least one of conditions is satisfied.
func CondReMatch ¶
CondReMatch function takes a string regexp pattern as an input and returns a condition function that checks whether the error matches the pattern given.
type MapFunc ¶
MapFunc function takes an error and returns mapped error and flag that indicates whether the mapping was performed successfully.
func NewMapping ¶
NewMapping function creates a mapping function based on error interfaces passed to it. src can be either MapCond and dst can be MapFunc.
type Mapper ¶
type Mapper struct {
// contains filtered or unexported fields
}
Mapper struct ...
func (*Mapper) AddMapping ¶
AddMapping function appends a list of mapping functions to a mapping chain.
Source Files
Directories