rpcerror

Documentation

Overview

Package rpcerror defines an error implementation used to communicate server-side RPC errors to RPC clients.

Index

• Variables
• func ToProto(err Error, m proto.Message) error
• type Code
  • func NewCode(c int32) Code
  • func (c Code) NumericValue() int32
  • func (c Code) String() string
• type Error
  • func FromProto(m proto.Message) (Error, error)
  • func New(c Code, format string, args ...interface{}) Error
  • func (e Error) Code() Code
  • func (e Error) Details() (details proto.Message, ok bool, err error)
  • func (e Error) Error() string
  • func (e Error) Message() string
  • func (e Error) WithCause(err error) Error
  • func (e Error) WithDetails(d proto.Message) Error

Variables

var (
	// Unknown is an error code used when no information is available about the
	// error.
	//
	// The Unknown code is used whenever the server behaves incorrectly. Even
	// though the reason may be known on the server, it is inappropriate to
	// provide granular information about these errors to the client.
	Unknown = Code{0}

	// InvalidInput is an error code that indicates that the input message to
	// the RPC method
	// is invalid according to some application-defined rules.
	//
	// InvalidInput means the input is inherently problematic.
	// FailedPrecondition is the appropriate code to use if the input
	// is only invalid due to the current state of the application.
	InvalidInput = Code{-1}

	// Unauthenticated is an error code that indicates that the client has
	// attempted to perform some action that requires authentication, but valid
	// authentication credentials have not been provided.
	Unauthenticated = Code{-2}

	// PermissionDenied is an error code that indicates that the caller does not
	// have permission to perform some action.
	//
	// It differs from Unauthenticated, which indicates that valid credentials
	// have not been supplied at all.
	PermissionDenied = Code{-3}

	// NotFound is an error code that indicates that the client has requested
	// some entity that was not found.
	NotFound = Code{-4}

	// AlreadyExists is an error code that indicates that client has attempted
	// to create some entity that already exists.
	AlreadyExists = Code{-5}

	// ResourceExhausted is an error code that indicates that some resource has
	// been exhausted, such as a rate limit.
	ResourceExhausted = Code{-6}

	// FailedPrecondition is an error code that indicates the application is not
	// in the required state to perform some action.
	//
	// The client should not retry until the application state has been
	// explicitly changed.
	//
	// Use Unavailable if the client can safely re-send the failed RPC request,
	// or Aborted if the client should retry at a higher level, such as by
	// beginning some business process again.
	FailedPrecondition = Code{-7}

	// Aborted is an error code that indicates some action was aborted.
	//
	// The client may retry the operation by restarting whatever higher level
	// process it belongs to, but should not simply re-send the same RPC
	// request.
	Aborted = Code{-8}

	// Unavailable is an error code that indicates that the server is
	// temporarily unable to fulfill a request.
	//
	// The client may safely retry the RPC call by re-sending the request,
	// typically after some delay.
	Unavailable = Code{-9}

	// NotImplemented is an error code that indicates an RPC method is not
	// implemented or otherwise unsupported by the server.
	NotImplemented = Code{-10}
)

Functions

func ToProto

func ToProto(err Error, m proto.Message) error

ToProto returns the Protocol Buffers representation of an error.

Types

type Code

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

Code is a numeric code that identifies the general class of an RPC error.

func NewCode

func NewCode(c int32) Code

NewCode returns a new application-defined error code.

c is the numeric value of the application-defined error code, it must be a positive integer.

Error codes should be used to organize related errors into broad categories based on their general meaning. This allows RPC clients to handle the error without being able to identify the specific cause.

Where possible, server implementations should favour using the pre-defined error codes from this package over defining custom error codes.

If custom codes are necessary, it is recommended they be treated like an enumeration by assigning the result of NewCode() to global variables with meaningful names.

func (Code) NumericValue

func (c Code) NumericValue() int32

NumericValue returns the numeric value of the error code.

func (Code) String

func (c Code) String() string

type Error

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

Error is an error produced by an RPC server that is intended to be received by the client.

These errors form part of the service's public API, as opposed to "runtime errors" (such as network timeouts, etc) which are unexpected and meaningless within the context of the application's business domain.

func FromProto

func FromProto(m proto.Message) (Error, error)

FromProto returns a new Error constructed from a Protocol Buffers representation.

func New

func New(c Code, format string, args ...interface{}) Error

New returns an error that will be sent from the server to the client.

c is the error code that best describes the error.

The error message is produced by performing sprintf-style interpolation on format and args.

The error message should be understood by technical users that maintain or operate the software making the RPC request. These people are typically not the end-users of the software.

func (Error) Code

func (e Error) Code() Code

Code returns the error's code.

Clients should use the code to decide how best to handle the error if no better determination can be made by examining the error's application-defined details value.

func (Error) Details

func (e Error) Details() (details proto.Message, ok bool, err error)

Details returns application-defined information about this error.

The client may use this information to notify the end-user about the error in whatever language or user interface may be appropriate.

It returns an error if the details can not be unmarshaled.

ok is true if error details are present in the error, even if an error occurs.

func (Error) Error

func (e Error) Error() string

func (Error) Message

func (e Error) Message() string

Message returns a human-readable description of the message.

This message is intended for technical users that maintain or operate the software making the RPC request, and should not be shown to end-users.

func (Error) WithCause

func (e Error) WithCause(err error) Error

WithCause returns a copy of e that records err as the initial cause of the error.

err is typically some unexpected runtime error that is important to the people who maintain the RPC server implementation, but not to the caller.

Information about err is never sent to the client.

func (Error) WithDetails

func (e Error) WithDetails(d proto.Message) Error

WithDetails returns a copy of e that includes some application-defined information about the error.

These details provide more specific information than can be conveyed by the error code.

It is best practice to define a distinct Protocol Buffers message type for each error that the client is expected to handle in some unique way.

The server should avoid including human-readable messages within the details value. Instead, include key information about the error that the client can use to notify the end-user about the error in whatever language or user interface may be appropriate.