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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Externalize ¶
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
NewUserErrorf is the same as NewUserError, with string formatting for convenience
func UserConditionWithCodef ¶ added in v0.11.0
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 ¶ added in v0.11.0
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 ¶ added in v0.11.0
UserErrorf wraps an existing error with a UserError
Types ¶
type UserError ¶ added in v0.11.0
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) GRPCStatus ¶ added in v0.11.0
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.
Source Files