structerr

Documentation

Index

• func ExtractMetadata(err error) map[string]any
• func FieldsProducer(_ context.Context, err error) log.Fields
• func GRPCCode(err error) codes.Code
• 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 (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) MetadataItems() []MetadataItem
  • func (e Error) Unwrap() error
  • func (e Error) WithDetail(detail proto.Message) Error
  • func (e Error) WithGRPCCode(code codes.Code) Error
  • func (e Error) WithMetadata(key string, value any) Error
  • func (e Error) WithMetadataItems(items ...MetadataItem) Error
• type ErrorMetadater
• type MetadataItem

Functions

func ExtractMetadata

func ExtractMetadata(err error) map[string]any

ExtractMetadata extracts metadata from the given error if any of the errors in its chain contain any. Errors may contain in case they are either a `structerr.Error` or in case they implement the `ErrorMetadater` interface. The metadata will contain the combination of all added metadata of this error as well as any wrapped Errors.

When the same metadata 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 FieldsProducer

func FieldsProducer(_ context.Context, err error) log.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.

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 an Unknown error code. This constructor should be used in the general case where it is not clear what the specific error category is. As Unknown errors get treated specially, they will be overridden when wrapped with an error that has a more specific error code.

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. Please note that the Unavailable status code is a signal telling clients to retry automatically. This auto-retry mechanism is handled at the library layer, without client consensus. Typically, it is used for the situations where the gRPC is not available or is not responding. Here are some discrete examples:

• Server downtime: The server hosting the gRPC service is down for maintenance or has crashed.
• Network issues: Connectivity problems between the client and server, like network congestion or a broken connection, can cause the service to appear unavailable.
• Load balancing failure: In a distributed system, the load balancer may be unable to route the client's request to a healthy instance of the gRPC service. This can happen if all instances are down or if the load balancer is misconfigured.
• TLS/SSL handshake failure: If there's a problem during the TLS/SSL handshake between the client and the server, the connection may fail, leading to an UNAVAILABLE status code.

Thus, this status code should be used by interceptors or network-related components. gRPC handlers should use another status code instead.

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 (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. Please refer to `ExtractMetadata()` for the exact semantics of this function.

func (Error) MetadataItems

func (e Error) MetadataItems() []MetadataItem

MetadataItems returns a copy of all metadata items added to this error. This function has the same semantics as `Metadata()`. The results are sorted by their metadata key.

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) 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.

func (Error) WithMetadataItems

func (e Error) WithMetadataItems(items ...MetadataItem) Error

WithMetadataItems is a convenience function to append multiple metadata items to an error. It behaves the same as if `WithMetadata()` was called for each of the items separately.

type ErrorMetadater

type ErrorMetadater interface {
	// ErrorMetadata returns the list of metadata items attached to this error.
	ErrorMetadata() []MetadataItem
}

ErrorMetadater is an interface that can be implemented by error types in order to provide custom metadata items without itself being a `structerr.Error`.

type MetadataItem

type MetadataItem struct {
	// Key is the key of the metadata item that will be used as the logging key.
	Key string
	// Value is the value of the metadata item that will be formatted as the logging value.
	Value any
}

MetadataItem is an item that associated a metadata key with an arbitrary value.