structerr

Documentation

Index

• func FieldsProducer(_ context.Context, err error) logrus.Fields
• func GRPCCode(err error) codes.Code
• func StreamInterceptor(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
• func UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
• type Error
  • func New(format string, a ...any) Error
  • func NewAborted(format string, a ...any) Error
  • func NewAlreadyExists(format string, a ...any) Error
  • func NewCanceled(format string, a ...any) Error
  • func NewDataLoss(format string, a ...any) Error
  • func NewDeadlineExceeded(format string, a ...any) Error
  • func NewFailedPrecondition(format string, a ...any) Error
  • func NewInternal(format string, a ...any) Error
  • func NewInvalidArgument(format string, a ...any) Error
  • func NewNotFound(format string, a ...any) Error
  • func NewPermissionDenied(format string, a ...any) Error
  • func NewResourceExhausted(format string, a ...any) Error
  • func NewUnauthenticated(format string, a ...any) Error
  • func NewUnavailable(format string, a ...any) Error
  • func NewUnimplemented(format string, a ...any) Error
  • func NewUnknown(format string, a ...any) Error
  • func (e Error) Code() codes.Code
  • func (e Error) Details() []proto.Message
  • func (e Error) Error() string
  • func (e Error) GRPCStatus() *status.Status
  • func (e Error) Is(targetErr error) bool
  • func (e Error) Metadata() map[string]any
  • func (e Error) Unwrap() error
  • func (e Error) WithDetail(detail proto.Message) Error
  • func (e Error) WithGRPCCode(code codes.Code) Error
  • func (e Error) WithInterceptedMetadata(key string, value any) Error
  • func (e Error) WithMetadata(key string, value any) Error

Functions

func FieldsProducer

func FieldsProducer(_ context.Context, err error) logrus.Fields

FieldsProducer extracts metadata from err if it contains a `structerr.Error` and exposes it as logged fields. This function is supposed to be used with `log.MessageProducer()`.

func GRPCCode

func GRPCCode(err error) codes.Code

GRPCCode translates errors into codes.Code values.

• If present, it will un-wrap the top-level error that implements the `GRPCStatus()` function and return its error code. As we internally use `structerr`s to propagate gRPC error codes the error code propagation semantics match what the `structerr` is doing in that case.
• If no error is found in the chain that implements `GRPCStatus()` then `codes.Unknown` is returned.
• If err is nil then `codes.OK` is returned.

Semantics of this function thus match what the calling-side of an RPC would see if the given error was returned from that RPC.

func StreamInterceptor

func StreamInterceptor(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

StreamInterceptor is an interceptor for streaming RPC calls that injects error metadata as detailed error. This is only supposed to be used for testing purposes as error metadata is considered to be a server-side detail. No clients should start to rely on it.

func UnaryInterceptor

func UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

UnaryInterceptor is an interceptor for unary RPC calls that injects error metadata as detailed error. This is only supposed to be used for testing purposes as error metadata is considered to be a server-side detail. No clients should start to rely on it.

Types

type Error

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

Error is a structured error that contains additional details.

func New

func New(format string, a ...any) Error

New returns a new Error with the default error code, which is Internal. When this function is used to wrap another Error, then the error code of that wrapped Error will be retained. The intent of this is to always retain the most specific error code in the general case.

func NewAborted

func NewAborted(format string, a ...any) Error

NewAborted constructs a new error code with the Aborted error code. Please refer to New for further details.

func NewAlreadyExists

func NewAlreadyExists(format string, a ...any) Error

NewAlreadyExists constructs a new error code with the AlreadyExists error code. Please refer to New for further details.

func NewCanceled

func NewCanceled(format string, a ...any) Error

NewCanceled constructs a new error code with the Canceled error code. Please refer to New for further details.

func NewDataLoss

func NewDataLoss(format string, a ...any) Error

NewDataLoss constructs a new error code with the DataLoss error code. Please refer to New for further details.

func NewDeadlineExceeded

func NewDeadlineExceeded(format string, a ...any) Error

NewDeadlineExceeded constructs a new error code with the DeadlineExceeded error code. Please refer to New for further details.

func NewFailedPrecondition

func NewFailedPrecondition(format string, a ...any) Error

NewFailedPrecondition constructs a new error code with the FailedPrecondition error code. Please refer to New for further details.

func NewInternal

func NewInternal(format string, a ...any) Error

NewInternal constructs a new error code with the Internal error code. Please refer to New for further details.

func NewInvalidArgument

func NewInvalidArgument(format string, a ...any) Error

NewInvalidArgument constructs a new error code with the InvalidArgument error code. Please refer to New for further details.

func NewNotFound

func NewNotFound(format string, a ...any) Error

NewNotFound constructs a new error code with the NotFound error code. Please refer to New for further details.

func NewPermissionDenied

func NewPermissionDenied(format string, a ...any) Error

NewPermissionDenied constructs a new error code with the PermissionDenied error code. Please refer to New for further details.

func NewResourceExhausted

func NewResourceExhausted(format string, a ...any) Error

NewResourceExhausted constructs a new error code with the ResourceExhausted error code. Please refer to New for further details.

func NewUnauthenticated

func NewUnauthenticated(format string, a ...any) Error

NewUnauthenticated constructs a new error code with the Unauthenticated error code. Please refer to New for further details.

func NewUnavailable

func NewUnavailable(format string, a ...any) Error

NewUnavailable constructs a new error code with the Unavailable error code. Please refer to New for further details.

func NewUnimplemented

func NewUnimplemented(format string, a ...any) Error

NewUnimplemented constructs a new error code with the Unimplemented error code. Please refer to New for further details.

func NewUnknown

func NewUnknown(format string, a ...any) Error

NewUnknown constructs a new error code with the Unknown error code. Please refer to New for further details.

func (Error) Code

func (e Error) Code() codes.Code

Code returns the error code of the Error.

func (Error) Details

func (e Error) Details() []proto.Message

Details returns the chain error details set by this and any wrapped Error. The returned array contains error details ordered from top-level error details to bottom-level error details.

func (Error) Error

func (e Error) Error() string

Error returns the error message of the Error.

func (Error) GRPCStatus

func (e Error) GRPCStatus() *status.Status

GRPCStatus returns the gRPC status of this error.

func (Error) Is

func (e Error) Is(targetErr error) bool

Is checks whether the error is equivalent to the target error. Errors are only considered equivalent if the GRPC representation of this error is the same.

func (Error) Metadata

func (e Error) Metadata() map[string]any

Metadata returns the Error's metadata. The metadata will contain the combination of all added metadata of this error as well as any wrapped Errors.

When the same metada key exists multiple times in the error chain, then the value that is highest up the callchain will be returned. This is done because in general, the higher up the callchain one is the more context is available.

func (Error) Unwrap

func (e Error) Unwrap() error

Unwrap returns the wrapped error if any, otherwise it returns nil.

func (Error) WithDetail

func (e Error) WithDetail(detail proto.Message) Error

WithDetail sets the Error detail that provides additional structured information about the error via gRPC so that callers can programmatically determine the exact circumstances of an error.

func (Error) WithGRPCCode

func (e Error) WithGRPCCode(code codes.Code) Error

WithGRPCCode overrides the gRPC code embedded into the error.

func (Error) WithInterceptedMetadata

func (e Error) WithInterceptedMetadata(key string, value any) Error

WithInterceptedMetadata adds an additional metadata item to the Error in the form of an error detail. Note that this is only intended to be used in the context of tests where we convert error metadata into structured errors via the UnaryInterceptor and StreamInterceptor so that we can test that metadata has been set as expected on the client-side of a gRPC call.

func (Error) WithMetadata

func (e Error) WithMetadata(key string, value any) Error

WithMetadata adds an additional metadata item to the Error. The metadata has the intent to provide more context around errors to the consumer of the Error. Calling this function multiple times with the same key will override any previous values.