README
¶
semerr 
Semantic error wrappers for Go
Usage and documentation
See https://pkg.go.dev/github.com/codingllama/semerr.
Design Principles
- Practical. Simple. Small. Fast.
- No external dependencies.
- No bloat.
- No breaking changes.
- Ready to Go.
Documentation
¶
Overview ¶
Package semerr provides semantic error wrappers. It is designed to be simple, small, fast, integrated with the stdlib and to pull zero external dependencies.
All semantic errors are simple structs, meant to be used by themselves or wrapping another error:
// Standalone use:
err1 := semerr.NotFoundError{}
// Annotate existing error:
err2 := semerr.InvalidArgumentError{
fmt.Errorf("invalid user name %q: max allowed length is %d", name, maxNameLen)
}
Errors can be type checked using errors.As:
if ok := errors.As(err, &semerr.NotFoundError{}); ok {
// handle not found
}
Errors can be converted to their gRPC or HTTP counterparts using the GRPCCode and HTTPStatus functions.
// Example of semerr to gRPC status conversion. // Suitable for a gRPC server interceptor. c, _ := semerr.GRPCCode(err) statusErr := status.Error(codes.Code(c), err.Error())
Semantic errors are based on the gRPC canonical error codes.
Example (Annotate) ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
func main() {
var err error = semerr.NotFoundError{errors.New("user not found")}
fmt.Println(err)
// Verify error type.
fmt.Println(errors.As(err, &semerr.NotFoundError{}))
// Get code and status.
code, _ := semerr.GRPCCode(err)
status, _ := semerr.HTTPStatus(err)
fmt.Println(code, status)
}
Output: user not found true 5 404
Example (Standalone) ¶
package main
import (
"fmt"
"github.com/codingllama/semerr"
)
func main() {
err := semerr.NotFoundError{} // that's it!
fmt.Println(err.Error())
fmt.Println(err.GRPCCode())
fmt.Println(err.HTTPStatus())
}
Output: not found 5 404
Example (Wrap) ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
func main() {
err := fmt.Errorf("user 10 %w", semerr.NotFoundError{})
fmt.Println(err)
// Error is identified as a NotFoundError.
fmt.Println(errors.Is(err, semerr.NotFoundError{}))
// Get code and status.
code, _ := semerr.GRPCCode(err)
status, _ := semerr.HTTPStatus(err)
fmt.Println(code, status)
}
Output: user 10 not found true 5 404
Index ¶
- func FromGRPCCode(c Code, err error) error
- func FromHTTPStatus(status int, err error) error
- func HTTPStatus(err error) (status int, ok bool)
- type AbortedError
- type AlreadyExistsError
- type CanceledError
- type Code
- type DataLossError
- type DeadlineExceededError
- type FailedPreconditionError
- type InternalError
- type InvalidArgumentError
- type NotFoundError
- type OutOfRangeError
- type PermissionDeniedError
- type ResourceExhaustedError
- type UnauthenticatedError
- type UnavailableError
- type UnimplementedError
- type UnknownError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromGRPCCode ¶
FromGRPCCode returns the semerr corresponding to c.
- If c is OK or unmapped, returns err.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
// codes is a mock for the grpc/codes package.
var codes = struct{ NotFound uint32 }{
NotFound: uint32(semerr.NotFoundError{}.GRPCCode()),
}
func main() {
// err is wrapped in a semerr.NotFoundError.
err := semerr.FromGRPCCode(semerr.Code(codes.NotFound), errors.New("user not found"))
fmt.Println(err)
fmt.Println(errors.As(err, &semerr.NotFoundError{})) // Assert type.
}
Output: user not found true
func FromHTTPStatus ¶
FromHTTPStatus returns the semerr corresponding to status.
Not all semantic errors map to distinct HTTP statuses. In case of conflicts, FromHTTPStatus tries to choose the better suited type for the status.
- If status is 200 or unmapped, returns err.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
func main() {
// err is wrapped in a semerr.NotFoundError.
err := semerr.FromHTTPStatus(404, errors.New("user not found"))
fmt.Println(err)
fmt.Println(errors.As(err, &semerr.NotFoundError{})) // Assert type.
}
Output: user not found true
func HTTPStatus ¶
HTTPStatus returns the HTTP status code for err.
- If err is nil, returns 200 and true.
- If err is a semerr, returns its status true.
- If is not a semerr, returns 500 and false.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
func main() {
// nil returns 200 and true.
status, ok := semerr.HTTPStatus(nil)
fmt.Println(status, ok)
// Semantic errors return their status and true.
status, ok = semerr.HTTPStatus(semerr.NotFoundError{})
fmt.Println(status, ok)
// Unknown errors return 500 and false.
status, ok = semerr.HTTPStatus(errors.New("not a semantic error"))
fmt.Println(status, ok)
}
Output: 200 true 404 true 500 false
Types ¶
type AbortedError ¶
type AbortedError struct{ Err error }
AbortedError is the semantic error for Aborted.
func (AbortedError) Error ¶
func (e AbortedError) Error() string
Error returns Err.Error() or "aborted".
type AlreadyExistsError ¶
type AlreadyExistsError struct{ Err error }
AlreadyExistsError is the semantic error for AlreadyExists.
func (AlreadyExistsError) Error ¶
func (e AlreadyExistsError) Error() string
Error returns Err.Error() or "already exists".
func (AlreadyExistsError) GRPCCode ¶
func (AlreadyExistsError) GRPCCode() Code
GRPCCode returns AlreadyExists.
func (AlreadyExistsError) HTTPStatus ¶
func (AlreadyExistsError) HTTPStatus() int
HTTPStatus returns 409.
type CanceledError ¶
type CanceledError struct{ Err error }
CanceledError is the semantic error for Canceled.
func (CanceledError) Error ¶
func (e CanceledError) Error() string
Error returns Err.Error() or "canceled".
type Code ¶
type Code uint32
Code is the semerr representation of a gRPC canonical error code.
func GRPCCode ¶
GRPCCode returns the gRPC code for err.
- If err is nil, returns OK and true.
- If err is a semerr, returns its code and true.
- If is not a semerr, returns Unknown and false.
Example ¶
package main
import (
"errors"
"fmt"
"github.com/codingllama/semerr"
)
func main() {
// nil returns OK and true.
code, ok := semerr.GRPCCode(nil)
fmt.Println(code, ok)
// Semantic errors return their code and true.
code, ok = semerr.GRPCCode(semerr.NotFoundError{})
fmt.Println(code, ok)
// Unknown errors return Unknown and false.
code, ok = semerr.GRPCCode(errors.New("not a semantic error"))
fmt.Println(code, ok)
}
Output: 0 true 5 true 2 false
type DataLossError ¶
type DataLossError struct{ Err error }
DataLossError is the semantic error for DataLoss.
func (DataLossError) Error ¶
func (e DataLossError) Error() string
Error returns Err.Error() or "data loss".
type DeadlineExceededError ¶
type DeadlineExceededError struct{ Err error }
DeadlineExceededError is the semantic error for DeadlineExceeded.
func (DeadlineExceededError) Error ¶
func (e DeadlineExceededError) Error() string
Error returns Err.Error() or "deadline exceeded".
func (DeadlineExceededError) GRPCCode ¶
func (DeadlineExceededError) GRPCCode() Code
GRPCCode returns DeadlineExceeded.
func (DeadlineExceededError) HTTPStatus ¶
func (DeadlineExceededError) HTTPStatus() int
HTTPStatus returns 504.
func (DeadlineExceededError) Unwrap ¶
func (e DeadlineExceededError) Unwrap() error
Unwrap returns Err.
type FailedPreconditionError ¶
type FailedPreconditionError struct{ Err error }
FailedPreconditionError is the semantic error for FailedPrecondition.
func (FailedPreconditionError) Error ¶
func (e FailedPreconditionError) Error() string
Error returns Err.Error() or "failed precondition".
func (FailedPreconditionError) GRPCCode ¶
func (FailedPreconditionError) GRPCCode() Code
GRPCCode returns FailedPrecondition.
func (FailedPreconditionError) HTTPStatus ¶
func (FailedPreconditionError) HTTPStatus() int
HTTPStatus returns 400.
func (FailedPreconditionError) Unwrap ¶
func (e FailedPreconditionError) Unwrap() error
Unwrap returns Err.
type InternalError ¶
type InternalError struct{ Err error }
InternalError is the semantic error for Internal.
func (InternalError) Error ¶
func (e InternalError) Error() string
Error returns Err.Error() or "internal".
type InvalidArgumentError ¶
type InvalidArgumentError struct{ Err error }
InvalidArgumentError is the semantic error for InvalidArgument.
func (InvalidArgumentError) Error ¶
func (e InvalidArgumentError) Error() string
Error returns Err.Error() or "invalid argument".
func (InvalidArgumentError) GRPCCode ¶
func (InvalidArgumentError) GRPCCode() Code
GRPCCode returns InvalidArgument.
func (InvalidArgumentError) HTTPStatus ¶
func (InvalidArgumentError) HTTPStatus() int
HTTPStatus returns 400.
func (InvalidArgumentError) Unwrap ¶
func (e InvalidArgumentError) Unwrap() error
Unwrap returns Err.
type NotFoundError ¶
type NotFoundError struct{ Err error }
NotFoundError is the semantic error for NotFound.
func (NotFoundError) Error ¶
func (e NotFoundError) Error() string
Error returns Err.Error() or "not found".
type OutOfRangeError ¶
type OutOfRangeError struct{ Err error }
OutOfRangeError is the semantic error for OutOfRange.
func (OutOfRangeError) Error ¶
func (e OutOfRangeError) Error() string
Error returns Err.Error() or "out of range".
func (OutOfRangeError) GRPCCode ¶
func (OutOfRangeError) GRPCCode() Code
GRPCCode returns OutOfRange.
type PermissionDeniedError ¶
type PermissionDeniedError struct{ Err error }
PermissionDeniedError is the semantic error for PermissionDenied.
func (PermissionDeniedError) Error ¶
func (e PermissionDeniedError) Error() string
Error returns Err.Error() or "permission denied".
func (PermissionDeniedError) GRPCCode ¶
func (PermissionDeniedError) GRPCCode() Code
GRPCCode returns PermissionDenied.
func (PermissionDeniedError) HTTPStatus ¶
func (PermissionDeniedError) HTTPStatus() int
HTTPStatus returns 403.
func (PermissionDeniedError) Unwrap ¶
func (e PermissionDeniedError) Unwrap() error
Unwrap returns Err.
type ResourceExhaustedError ¶
type ResourceExhaustedError struct{ Err error }
ResourceExhaustedError is the semantic error for ResourceExhausted.
func (ResourceExhaustedError) Error ¶
func (e ResourceExhaustedError) Error() string
Error returns Err.Error() or "resource exhausted".
func (ResourceExhaustedError) GRPCCode ¶
func (ResourceExhaustedError) GRPCCode() Code
GRPCCode returns ResourceExhausted.
func (ResourceExhaustedError) HTTPStatus ¶
func (ResourceExhaustedError) HTTPStatus() int
HTTPStatus returns 429.
func (ResourceExhaustedError) Unwrap ¶
func (e ResourceExhaustedError) Unwrap() error
Unwrap returns Err.
type UnauthenticatedError ¶
type UnauthenticatedError struct{ Err error }
UnauthenticatedError is the semantic error for Unauthenticated.
func (UnauthenticatedError) Error ¶
func (e UnauthenticatedError) Error() string
Error returns Err.Error() or "unauthenticated".
func (UnauthenticatedError) GRPCCode ¶
func (UnauthenticatedError) GRPCCode() Code
GRPCCode returns Unauthenticated.
func (UnauthenticatedError) HTTPStatus ¶
func (UnauthenticatedError) HTTPStatus() int
HTTPStatus returns 401.
func (UnauthenticatedError) Unwrap ¶
func (e UnauthenticatedError) Unwrap() error
Unwrap returns Err.
type UnavailableError ¶
UnavailableError is the semantic error for Unavailable.
func (UnavailableError) Error ¶
func (e UnavailableError) Error() string
Error returns Err.Error() or "unavailable".
func (UnavailableError) GRPCCode ¶
func (UnavailableError) GRPCCode() Code
GRPCCode returns Unavailable.
func (UnavailableError) HTTPStatus ¶
func (UnavailableError) HTTPStatus() int
HTTPStatus returns 503.
type UnimplementedError ¶
type UnimplementedError struct{ Err error }
UnimplementedError is the semantic error for Unimplemented.
func (UnimplementedError) Error ¶
func (e UnimplementedError) Error() string
Error returns Err.Error() or "unimplemented".
func (UnimplementedError) GRPCCode ¶
func (UnimplementedError) GRPCCode() Code
GRPCCode returns Unimplemented.
func (UnimplementedError) HTTPStatus ¶
func (UnimplementedError) HTTPStatus() int
HTTPStatus returns 501.
type UnknownError ¶
type UnknownError struct{ Err error }
UnknownError is the semantic error for Unknown.
func (UnknownError) Error ¶
func (e UnknownError) Error() string
Error returns Err.Error() or "unknown".
Source Files
Directories