agem

README

agem

agem (Another Go Error Module) is a Go module for merging errors and retrying tasks that produce errors.

It provides:

1. Merging errors: multiple errors can be merged together into one error using fmt.Errorf. I've found this reduces boilerplate quite a bit; especially around deferred closers.
2. The Retry function so that you can retry a function several times with a backoff period between each try.
3. Temporary errors: errors that have a boolean flag attribute attached to them indicating whether they are temporary (this can be checked using the IsTemporary function). They also implement pkg/errors' stackTracer interface as well as the standard error package's causer interface.

Documentation

Index

• func IsTemporary(err error) bool
• func MergeErrors(errs ...error) error
• func Retry(maxTries int, minDelay time.Duration, retry RetryFunction, args ...any) (err error)
• func TemporaryError(temporary bool, msg string) error
• func TemporaryErrorf(temporary bool, format string, a ...any) error
• func TemporaryWrap(temporary bool, err error, message string) error
• func TemporaryWrapf(temporary bool, err error, format string, a ...any) error
• type RetryFunction
• type RetryReturnType
  • func (rrt RetryReturnType) Error() string
  • func (rrt RetryReturnType) String() string

Examples

• IsTemporary
• MergeErrors

Functions

func IsTemporary

func IsTemporary(err error) bool

IsTemporary returns true if err is temporary.

Example

nonTempErr := TemporaryError(false, "this is not a temporary error")
tempErr := TemporaryErrorf(true, "this is a temporary error")
fmt.Printf("%q is temporary = %t\n", nonTempErr.Error(), IsTemporary(nonTempErr))
fmt.Printf("%q is temporary = %t\n", tempErr.Error(), IsTemporary(tempErr))

Output:

"this is not a temporary error" is temporary = false
"this is a temporary error" is temporary = true

func MergeErrors

func MergeErrors(errs ...error) error

MergeErrors merges all the given errors into one error. This is done by using the fmt.Errorf function and separating each error with a semicolon. If an error is nil, then the error won't be merged. If there are no non-nil errors given (this includes providing 0 errors) then nil will be returned. The returned error implements stackTracer.

Example

// Error messages will be merged using fmt.Errorf with semicolon separators
fmt.Println(MergeErrors(
	errors.New("error 1"),
	errors.New("error 2"),
	errors.New("error 3"),
))

// Nil errors will be ignored
fmt.Println(MergeErrors(
	errors.New("error 1"),
	nil,
	errors.New("error 2"),
))

// Merging no errors returns nil
fmt.Println(MergeErrors())

Output:

error 1; error 2; error 3
error 1; error 2
<nil>

func Retry

func Retry(maxTries int, minDelay time.Duration, retry RetryFunction, args ...any) (err error)

Retry will retry the given function the given number of times. The function will be retried only if it returns an error (that is not a RetryReturnType error) or a panic occurs within it and there are tries remaining. Each time this happens the tryNo variable is decremented and the following formula is used to determine the sleep duration that occurs after a failed try:

minDelay * time.Duration(maxTries+1-tryNo)

This results in a smaller delay in early tries relative to later tries. If the error returned by the function is a RetryReturnType then the following actions will be carried out, depending on which RetryReturnType is returned:

• Continue: will proceed to the next try of the RetryFunction without waiting. The output error for Retry is also set to nil, faking the success scenario. Note: this will still use up a try. This is to avoid infinite loops.

• Break: will stop retrying and will set Break as the returned error for Retry. I.e. fakes the failure scenario.

• Done: will stop retrying and will set nil as the returned error. This is the same as returning nil from the RetryFunction. I.e. fakes the success scenario.

If after the given number of maxTries, an error is still occurring in the tried function, the error will be returned. If the RetryFunction is nil, then an appropriate error will be returned.

func TemporaryError

func TemporaryError(temporary bool, msg string) error

TemporaryError creates a new temporary error with an Error method that returns the given message.

func TemporaryErrorf

func TemporaryErrorf(temporary bool, format string, a ...any) error

TemporaryErrorf creates a new temporary error with an Error method that returns the string interpolation of the given format string and arguments.

func TemporaryWrap

func TemporaryWrap(temporary bool, err error, message string) error

TemporaryWrap wraps an existing error in both a temporary error and a causer error. This is done by creating an instance of the temporaryProto and assigning the appropriate methods.

func TemporaryWrapf

func TemporaryWrapf(temporary bool, err error, format string, a ...any) error

TemporaryWrapf calls TemporaryWrap using the output of fmt.Sprintf as the message for the wrapped error.

Types

type RetryFunction

type RetryFunction func(currentTry int, maxTries int, minDelay time.Duration, args ...any) error

RetryFunction is the signature of the function that the Retry function must be given.

type RetryReturnType

type RetryReturnType int

RetryReturnType are the return types that are used within the Retry function.

const (
	// Continue to the next try.
	Continue RetryReturnType = iota
	// Break out of try loop. This also applies to Break-ing out after all tries have been exhausted because there is a
	// recurring error.
	Break
	// Done with the try loop. Exit the try loop gracefully without there being a recurring error.
	Done
)

func (RetryReturnType) Error

func (rrt RetryReturnType) Error() string

Error returns the error message for this RetryReturnType.

func (RetryReturnType) String

func (rrt RetryReturnType) String() string