rpcerror

Documentation

Overview

Package rpcerror provides helper types and functions for dealing with errors that cross gRPC boundaries.

gRPC best practices dictate that the only error that should ever be returned by RPC server endpoints is `status.Status`. If an RPC server does not do this, gRPC will wrap it in a `status.Status` with an error code of Unknown, which is not useful to clients. This package provides a few functions, namely `New`, `Newf`, `Wrap`, and `Wrapf`, which provide RPC servers an easy way to wrap up existing errors or create new errors to return from RPC endpoints.

For the client side, this package provides functions `FromError` and `Convert`, as well as types `Error` and `ErrorCause`, which allows RPC clients to inspect the error that occurred (including its error status) and, if one was provided, the cause of the error (i.e. the one that was wrapped via `Wrap` or `Wrapf`).

Index

• func New(code codes.Code, message string) error
• func Newf(code codes.Code, messageFormat string, args ...interface{}) error
• func WithDetails(err error, details ...proto.Message) error
• func Wrap(code codes.Code, err error, message string) error
• func Wrapf(code codes.Code, err error, messageFormat string, args ...interface{}) error
• type Error
  • func Convert(err error) *Error
  • func FromError(err error) (*Error, bool)
  • func (r *Error) Cause() *ErrorCause
  • func (r *Error) Code() codes.Code
  • func (r *Error) Details() []interface{}
  • func (r *Error) Error() string
  • func (r *Error) Message() string
• type ErrorCause
  • func (r *ErrorCause) Message() string
  • func (r *ErrorCause) StackTrace() string

Functions

func New

func New(code codes.Code, message string) error

New creates a new gRPC-compatible `error` with the given error code and message.

func Newf

func Newf(code codes.Code, messageFormat string, args ...interface{}) error

Newf creates a new gRPC-compatible `error` with the given code and formatted message.

func WithDetails

func WithDetails(err error, details ...proto.Message) error

WithDetails adds arbitrary protobuf payloads to errors created by this package. These errors will be accessible by calling `Details` on `Error` instances created by `FromError`.

func Wrap

func Wrap(code codes.Code, err error, message string) error

Wrap wraps an `error` into a gRPC-compatible `error`, recording the warpped error as the "cause" of the returned error.

It is a logic error to call this function on an error previously returned by `rpcerrors.Wrap`.

func Wrapf

func Wrapf(code codes.Code, err error, messageFormat string, args ...interface{}) error

Wrapf wraps an `error` into a gRPC-compatible `error`, plus a formatted message, recording the wrapped error as the "cause" of the returned error.

It is a logic error to call this function on an error previously returned by `rpcerrors.Wrap`.

Types

type Error

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

Error represents an error response from an RPC server endpoint. It contains a gRPC error code, a message, and a chain of "wrapped" errors that led to the final dispatch of this particular error message.

func Convert

func Convert(err error) *Error

Convert converts an error to an Error using `FromError`, but panics if the conversion fails.

func FromError

func FromError(err error) (*Error, bool)

FromError "unwraps" an error created by functions in the `rpcerror` package and produces an `Error` structure from them.

This function is designed to be used by clients interacting with gRPC servers. If the gRPC server issued an error using one of the error creation functions in `rpcerror`, this function will produce a non-null `Error`.

Returns false if the given error is not a gRPC Status error.

func (*Error) Cause

func (r *Error) Cause() *ErrorCause

Cause returns the error that was the root cause of this error, or nil if one wasn't provided.

func (*Error) Code

func (r *Error) Code() codes.Code

Code returns the gRPC error code for this error.

func (*Error) Details

func (r *Error) Details() []interface{}

Details returns the list of all auxiliary protobuf objects that were attached to this error by the server. It's up to the caller to try and downcast them to look for the one they are interested in.

func (*Error) Error

func (r *Error) Error() string

func (*Error) Message

func (r *Error) Message() string

Message returns the message associated with this error cause.

type ErrorCause

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

ErrorCause represents a root cause of an error that ultimately caused an RPC endpoint to issue an error. ErrorCauses are optionally attached to Errors.

All ErrorCauses have messages, but only a subset of them have stack traces. Notably, the pkg/errors package will affix stack traces to errors created through the errors.New and errors.Wrap.

func (*ErrorCause) Message

func (r *ErrorCause) Message() string

Message returns the message associated with this error cause.

func (*ErrorCause) StackTrace

func (r *ErrorCause) StackTrace() string

StackTrace returns the stack trace associated with this error, or the empty string if one wasn't provided.