Documentation
¶
Overview ¶
Copyright (c) 2024 Eli Janssen Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
Copyright 2018 Twitch Interactive, Inc. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at
http://www.apache.org/licenses/LICENSE-2.0
or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
originally from: https://github.com/twitchtv/twirp/blob/3c51d65f753a1049c77bc51e0e8c7922b1fb7e4d/errors.go modified 2023-2024
Index ¶
- func AssertError[T ~byte | ~string | ~uint32](t *testing.T, err error, code T, msg string, meta ...map[string]string)
- func CollectMsgs(err error) []string
- func GetMsg(err error) string
- func WithInfo(info string) withFunc
- func WithMeta(key, value string) withFunc
- func WithMetaVals(vals map[string]string) withFunc
- type Code
- type Error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AssertError ¶
func CollectMsgs ¶ added in v1.4.0
CollectMsgs collects any human-readable messages in the error stack.
func GetMsg ¶ added in v1.4.0
GetMsgs collects any human-readable messages in the error stack, and returns it as a space separated string.
func WithMetaVals ¶ added in v1.4.0
Types ¶
type Code ¶ added in v1.4.0
type Code byte
Code represents a error type.
const ( // NoError is the zero-value, is considered an empty error and should not be // used. NoError Code = 0x00 // Canceled indicates the operation was cancelled (typically by the caller). Canceled Code = 0x01 // Unknown error. For example when handling errors raised by APIs that do not // return enough error information. Unknown Code = 0x02 // InvalidArgument indicates client specified an invalid argument. It // indicates arguments that are problematic regardless of the state of the // system (i.e. a malformed file name, required argument, number out of range, // etc.). InvalidArgument Code = 0x03 // DeadlineExceeded means operation expired before completion. For operations // that change the state of the system, this error may be returned even if the // operation has completed successfully (timeout). DeadlineExceeded Code = 0x04 // NotFound means some requested entity was not found. NotFound Code = 0x05 // AlreadyExists means an attempt to create an entity failed because one // already exists. AlreadyExists Code = 0x06 // PermissionDenied indicates the caller does not have permission to execute // the specified operation. It must not be used if the caller cannot be // identified (Unauthenticated). PermissionDenied Code = 0x07 // ResourceExhausted indicates some resource has been exhausted or rate-limited, // perhaps a per-user quota, or perhaps the entire file system is out of space. ResourceExhausted Code = 0x08 // FailedPrecondition indicates operation was rejected because the system is // not in a state required for the operation's execution. For example, doing // an rmdir operation on a directory that is non-empty, or on a non-directory // object, or when having conflicting read-modify-write on the same resource. FailedPrecondition Code = 0x09 // Aborted indicates the operation was aborted, typically due to a concurrency // issue like sequencer check failures, transaction aborts, etc. Aborted Code = 0x0a // OutOfRange means operation was attempted past the valid range. For example, // seeking or reading past end of a paginated collection. // // Unlike InvalidArgument, this error indicates a problem that may be fixed if // the system state changes (i.e. adding more items to the collection). // // There is a fair bit of overlap between FailedPrecondition and OutOfRange. // We recommend using OutOfRange (the more specific error) when it applies so // that callers who are iterating through a space can easily look for an // OutOfRange error to detect when they are done. OutOfRange Code = 0x0b // Unimplemented indicates operation is not implemented or not // supported/enabled in this service. Unimplemented Code = 0x0c // Internal errors. When some invariants expected by the underlying system // have been broken. In other words, something bad happened in the library or // backend service. Do not confuse with HTTP Internal Server Error; an // Internal error could also happen on the client code, i.e. when parsing a // server response. Internal Code = 0x0d // likely a transient condition and may be corrected by retrying with a // backoff. Unavailable Code = 0x0e // DataLoss indicates unrecoverable data loss or corruption. DataLoss Code = 0x0f // Unauthenticated indicates the request does not have valid authentication // credentials for the operation. Unauthenticated Code = 0x10 )
Valid error types. Most error types are equivalent to gRPC status codes and follow similar semantics. ref: https://grpc.github.io/grpc/core/md_doc_statuscodes.html
func (Code) Error ¶ added in v1.4.0
code.Error(text) builds a new error with code and text. Example:
errs.NotFound.Error("resource not found")
errs.Internal.Error("oops")
func (Code) Errorf ¶ added in v1.4.0
code.Errorf(format, args...) builds a new error with code and formatted text. The format may include "%w" to wrap other errors. Examples:
errs.Internal.Error("oops: %w", originalErr)
errs.NotFound.Error("resource not found with id: %q", resourceID)
type Error ¶
type Error interface {
// Code is of the valid error codes.
Code() Code
// Msg returns a human-readable, unstructured messages describing the error.
Msg() string
// Meta returns the stored value for the given key. If the key has no set
// value, Meta returns an empty string. There is no way to distinguish between
// an unset value and an explicit empty string.
Meta(key string) string
// MetaMap returns the complete key-value metadata map stored on the error.
MetaMap() map[string]string
// Error returns a string of the form "error <Code>: <Text>"
Error() string
// Unwrap returns the underlying error
Unwrap() error
// Is reports whether any error in err's tree matches target.
Is(error) bool
// WithMsg returns the Error with the given message set.
WithMsg(info string) Error
// WithMeta returns the Error with the key-value pair provided
// as metadata. If the key is already set, it is overwritten.
WithMeta(key, value string) Error
// WithMetaVals returns the Error with the Meta values provided
// as metadata. If a Meta.Key is already present, it is overwritten.
WithMetaVals(vals map[string]string) Error
}
Error represents an error in a service call.
func ArgumentError ¶ added in v1.4.0
ArgumentError is a convenience constructor for InvalidArgument errors. The argument name is included on the "argument" metadata for convenience.