Documentation
¶
Overview ¶
Package apperror provides a way to create and match errors with semantics.
Example (Checking_multiple_error_kinds_with_if_and_switch) ¶
package main
import (
"artk.dev/apperror"
"fmt"
)
func main() {
operation := func() error {
return nil
}
// Nesting the switch inside a branch to separate happy and sad paths
// could be of use sometimes.
if err := operation(); err != nil {
// Handle the sad path.
switch apperror.KindOf(err) {
case apperror.NotFoundError:
fmt.Println("Not found:", err)
case apperror.ConflictError:
fmt.Println("Conflict:", err)
case apperror.ForbiddenError:
fmt.Println("Forbidden:", err)
default:
fmt.Println("Other error:", err)
}
return
}
// Handle the happy path.
fmt.Println("OK.")
}
Output: OK.
Example (Checking_multiple_error_kinds_with_switch_only) ¶
package main
import (
"artk.dev/apperror"
"fmt"
)
func main() {
operation := func() error {
return nil
}
switch err := operation(); apperror.KindOf(err) {
case apperror.OK:
// You can either handle the error here or leave it blank
// and handle the normal path without indentation. In either
// case, you likely want to have a case for OK so that it is
// not handled by the default clause.
case apperror.NotFoundError:
fmt.Println("Not found:", err)
return
case apperror.ConflictError:
fmt.Println("Conflict:", err)
return
case apperror.ForbiddenError:
fmt.Println("Forbidden:", err)
return
default:
fmt.Println("Other error:", err)
return
}
// Handle the happy path.
fmt.Println("OK.")
}
Output: OK.
Example (Ignoring_an_already_deleted_item) ¶
package main
import (
"artk.dev/apperror"
"fmt"
)
func main() {
deleteItem := func(x int) error {
if x == 2 {
return apperror.NotFoundf("not found: %v", x)
}
return nil
}
// In this example, it is acceptable if the items are not found.
for _, x := range []int{0, 2, 7, 42} {
err := deleteItem(x)
if apperror.IsNotFound(err) {
fmt.Println("Already gone:", x)
continue
} else if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println("Deleted:", x)
}
fmt.Println("Done.")
}
Output: Deleted: 0 Already gone: 2 Deleted: 7 Deleted: 42 Done.
Example (Retrying_temporary_failures) ¶
package main
import (
"artk.dev/apperror"
"fmt"
"time"
)
func main() {
// An example operation that can fail temporarily.
var i int
operation := func() (int, error) {
i++
if i < 3 {
return i, apperror.Timeoutf("timed out (%v)", i)
}
return i, nil
}
// Retry after a temporary failure up to a limited number of times.
var value int
var err error
for range 3 {
value, err = operation()
// We went with IsFinal instead of IsTransient or IsTemporary
// because most of the time you want to break out of a loop.
// Since IsFinal returns true in that case, we avoid the NOT
// operator and keep the logic positive. It is also shorter.
if apperror.IsFinal(err) {
break
}
fmt.Println("Operation failed:", err)
time.Sleep(time.Nanosecond)
}
if err != nil {
fmt.Println("Unexpected error:", err)
return
}
fmt.Println("Success:", value)
fmt.Println("Done.")
}
Output: Operation failed: timed out (1) Operation failed: timed out (2) Success: 3 Done.
Index ¶
- func As(kind Kind, err error) error
- func AsConflict(err error) error
- func AsForbidden(err error) error
- func AsNotFound(err error) error
- func AsPreconditionFailed(err error) error
- func AsTimeout(err error) error
- func AsTooManyRequests(err error) error
- func AsUnauthorized(err error) error
- func AsUnknown(err error) error
- func AsValidation(err error) error
- func Conflict(msg string) error
- func Conflictf(msg string, a ...any) error
- func Forbidden(msg string) error
- func Forbiddenf(msg string, a ...any) error
- func IsConflict(err error) bool
- func IsFinal(err error) bool
- func IsForbidden(err error) bool
- func IsNotFound(err error) bool
- func IsPreconditionFailed(err error) bool
- func IsTimeout(err error) bool
- func IsTooManyRequests(err error) bool
- func IsUnauthorized(err error) bool
- func IsUnknown(err error) bool
- func IsUser(err error) bool
- func IsValidation(err error) bool
- func New(kind Kind, msg string) error
- func Newf(kind Kind, msg string, a ...any) error
- func NotFound(msg string) error
- func NotFoundf(msg string, a ...any) error
- func PreconditionFailed(msg string) error
- func PreconditionFailedf(msg string, a ...any) error
- func Timeout(msg string) error
- func Timeoutf(msg string, a ...any) error
- func TooManyRequests(msg string) error
- func TooManyRequestsf(msg string, a ...any) error
- func Unauthorized(msg string) error
- func Unauthorizedf(msg string, a ...any) error
- func Unknown(msg string) error
- func Unknownf(msg string, a ...any) error
- func Validation(msg string) error
- func Validationf(msg string, a ...any) error
- type Kind
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As wraps an existing error into a Kind. Invalid Kind values are mapped to Unknown. If the kind is OK or the error is nil, the function will return nil.
func AsConflict ¶
AsConflict wraps an existing error as a conflict error. It returns nil for nil errors.
func AsForbidden ¶
AsForbidden wraps an existing error as a forbidden error. It returns nil for nil errors.
func AsNotFound ¶
AsNotFound wraps an existing error as a not found error. It returns nil for nil errors.
func AsPreconditionFailed ¶
AsPreconditionFailed wraps an existing error as a precondition failed error. It returns nil for nil errors.
func AsTimeout ¶
AsTimeout wraps an existing error as a timeout error. It returns nil for nil errors.
func AsTooManyRequests ¶
AsTooManyRequests wraps an existing error as a too many requests error. It returns nil for nil errors.
func AsUnauthorized ¶
AsUnauthorized wraps an existing error as a unauthorized error. It returns nil for nil errors.
func AsUnknown ¶
AsUnknown wraps an existing error as a unknown error. It returns nil for nil errors.
func AsValidation ¶
AsValidation wraps an existing error as a validation error. It returns nil for nil errors.
func Forbiddenf ¶ added in v0.2.0
Forbiddenf creates a new forbidden error.
func IsFinal ¶
IsFinal returns true for error kinds that are not expected to change by merely repeating the operation.
Note that this function exclusively considers error kinds, not the context in which they were produced. Not all operations can be repeated safely, and this function cannot provide guidance on making such a judgment.
func IsPreconditionFailed ¶
IsPreconditionFailed matches precondition failed errors.
func IsTooManyRequests ¶
IsTooManyRequests matches too many requests errors.
func IsUnauthorized ¶
IsUnauthorized matches unauthorized errors.
func IsUser ¶
IsUser returns true for errors that are usually attributable to the user, as opposed to the implementation. For an analogy, think HTTP 400s (client errors) vs. HTTP 500s (server errors).
func New ¶
New creates an error of the specified Kind. Invalid Kind values are mapped to Unknown. If the kind is OK, the function will return nil.
func Newf ¶ added in v0.6.0
Newf creates an error of the specified Kind with a formatted string. Invalid Kind values are mapped to Unknown. If the kind is OK, the function will return nil.
func PreconditionFailed ¶
PreconditionFailed creates a new precondition failed error.
func PreconditionFailedf ¶ added in v0.2.0
PreconditionFailedf creates a new precondition failed error.
func TooManyRequests ¶
TooManyRequests creates a new too many requests error.
func TooManyRequestsf ¶ added in v0.2.0
TooManyRequestsf creates a new too many requests error.
func Unauthorized ¶
Unauthorized creates a new unauthorized error.
func Unauthorizedf ¶ added in v0.2.0
Unauthorizedf creates a new unauthorized error.
func Unknown ¶
Unknown returns a semantic error of UnknownError.
While any non-semantic error will be detected as an unknown error, the error returned by this stringConstructor implements the kinder interface and can be checked faster.
func Unknownf ¶ added in v0.2.0
Unknownf returns a semantic error of UnknownError.
While any non-semantic error will be detected as an unknown error, the error returned by this stringConstructor implements the kinder interface and can be checked faster.
func Validationf ¶ added in v0.2.0
Validationf creates a new validation error.
Types ¶
type Kind ¶
type Kind int
Kind implies semantic connotations about an error. In most cases, knowing the kind of error is all that user code needs for correct handling, and there is no need to consider the exact error type or message.
The numerical values of these constants are not guaranteed to be stable and therefore must not be relied on.
Source Files