Documentation
¶
Index ¶
- func ExtractMetadata(err error) map[string]any
- 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractMetadata ¶
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 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.
Types ¶
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is a structured error that contains additional details.
func New ¶
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 ¶
NewAborted constructs a new error code with the Aborted error code. Please refer to New for further details.
func NewAlreadyExists ¶
NewAlreadyExists constructs a new error code with the AlreadyExists error code. Please refer to New for further details.
func NewCanceled ¶
NewCanceled constructs a new error code with the Canceled error code. Please refer to New for further details.
func NewDataLoss ¶
NewDataLoss constructs a new error code with the DataLoss error code. Please refer to New for further details.
func NewDeadlineExceeded ¶
NewDeadlineExceeded constructs a new error code with the DeadlineExceeded error code. Please refer to New for further details.
func NewFailedPrecondition ¶
NewFailedPrecondition constructs a new error code with the FailedPrecondition error code. Please refer to New for further details.
func NewInternal ¶
NewInternal constructs a new error code with the Internal error code. Please refer to New for further details.
func NewInvalidArgument ¶
NewInvalidArgument constructs a new error code with the InvalidArgument error code. Please refer to New for further details.
func NewNotFound ¶
NewNotFound constructs a new error code with the NotFound error code. Please refer to New for further details.
func NewPermissionDenied ¶
NewPermissionDenied constructs a new error code with the PermissionDenied error code. Please refer to New for further details.
func NewResourceExhausted ¶
NewResourceExhausted constructs a new error code with the ResourceExhausted error code. Please refer to New for further details.
func NewUnauthenticated ¶
NewUnauthenticated constructs a new error code with the Unauthenticated error code. Please refer to New for further details.
func NewUnavailable ¶
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 ¶
NewUnimplemented constructs a new error code with the Unimplemented error code. Please refer to New for further details.
func (Error) Details ¶
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) GRPCStatus ¶
GRPCStatus returns the gRPC status of this error.
func (Error) Is ¶
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 ¶
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) WithDetail ¶
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 ¶
WithGRPCCode overrides the gRPC code embedded into the error.
func (Error) WithMetadata ¶
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.
Source Files