hcerr

Documentation

Overview

Package hcerr contains helpers to format and sanitize errors before returning them to clients as grpc status errors.

At the service layer, it's not safe to assume that errors produced from lower layers can be returned directly to callers. Errors may contain sensitive and irrelevant information, like the internal address of a database that we've failed to connect to.

Hcerr helps the service layer log context from these errors, and return a known safe error to the caller.

If an error producer deeper in the call stack wants to produce an error that a caller will see, they can use hcerr.UserErrorf()

Index

• func Externalize(log hclog.Logger, err error, msg string, args ...interface{}) error
• func NewUserError(message string) error
• func NewUserErrorf(format string, a ...interface{}) error
• func UserConditionWithCodef(c codes.Code, format string, a ...interface{}) error
• func UserErrorWithCodef(c codes.Code, err error, format string, a ...interface{}) error
• func UserErrorf(err error, format string, a ...interface{}) error
• type UserError
  • func (m *UserError) Error() string
  • func (m *UserError) GRPCStatus() *status.Status
  • func (m *UserError) Unwrap() error

Functions

func Externalize

func Externalize(log hclog.Logger, err error, msg string, args ...interface{}) error

Externalize is intended to be called by top-level grpc handler that's about to return an error to the framework. Details from the err will be logged, but not returned directly to the client, to prevent leaking too much detail. If the error includes a grpc status, that, along with the msg and args, will be returned to the client.

Args follow the same pattern as `hclog`. They are expected to be in order of "label, variable, label, variable", etc. Example: `hcerr.Externalize(log, err, "failed doing thing", "id", thing.id, "organization id", org.id)` All args will be printed as strings to transmit to clients, so rather than adding a big complex struct as an arg, pull out the fields of interest and add them as multiple args. These will be displayed as key/value pairs to the client. If there are an odd number of args, this assumes it's a mistake and adds "EXTRA_VALUE_AT_END" as the label for the final arg.

Any UserError errors found in the chain will have their messages added to the final error.

func NewUserError

func NewUserError(message string) error

NewUserError returns a new error with a message intended to be seen by server callers. The message should not contain anything sensitive or internal (i.e. database addresses, details of our internal processing, etc), and should be helpful to users in diagnosing why this error occurred and what they can do to avoid it in the future.

func NewUserErrorf

func NewUserErrorf(format string, a ...interface{}) error

NewUserErrorf is the same as NewUserError, with string formatting for convenience

func UserConditionWithCodef

func UserConditionWithCodef(c codes.Code, format string, a ...interface{}) error

UserConditionWithCodef generates a new error that takes a grpc status code, which will be used by the final hcerr.Externalize call as the status code to present to the user.

func UserErrorWithCodef

func UserErrorWithCodef(c codes.Code, err error, format string, a ...interface{}) error

UserErrorWithCodef wraps an existing error with a UserError, and takes a grpc status code, which will be used by the final hcerr.Externalize call as the status code to present to the user.

func UserErrorf

func UserErrorf(err error, format string, a ...interface{}) error

UserErrorf wraps an existing error with a UserError

Types

type UserError

type UserError struct {
	UserMessage string
	// contains filtered or unexported fields
}

UserError is a custom error type designed to package details that will be displayed to a user, alongside some internal error message that may be unsafe to surface.

UserError also implements grpcError, allowing it to optionally contain a custom grpc status code, which will be returned to the user if set.

func (*UserError) Error

func (m *UserError) Error() string

func (*UserError) GRPCStatus

func (m *UserError) GRPCStatus() *status.Status

GRPCStatus implements grpcError. If no code has been set, and no status error exists further up the error stack, will default to Internal with no message.

func (*UserError) Unwrap

func (m *UserError) Unwrap() error