derr

package module
v0.0.0-...-bd7407b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2025 License: Apache-2.0 Imports: 23 Imported by: 85

README

StreamingFast Errors Library

reference License

This repository contains all common code for handling errors across our various services. It is part of StreamingFast.

Usage

  1. Use derr.Wrap(err, "some message") to wrap any calls to a sub-system that could have yielded some derr.ErrorResponse (so it is passed to the user untouched).
  2. Use derr.SomeError (see errors.go) wherever possible to have consistent errors throughout our system. If you think the error you are creating can be shared, put it in errors.go and use that.
  3. Craft your own custom Error builder (in your project's errors.go, see eosws) and use that in your code. Craft a meaningful derr.C (or derr.ErrorCode) with a good name (see below), reuse where possible.
gRPC APIs

We create derr.Status errors when we want to set a specific error code. We call derr.Wrap to prefix the error message going out (without altering the outgoing Status Code).

Returning plain fmt.Errorf() upstream implies returning a codes.Internal gRPC status code.

Missing a derr.Wrap() kills the links and removes the StatusCode, so use Wrap (or Wrapf) whenever you want to add a prefix.

REST APIs

All error should be created by defining a properly named function that receives a context.Context object as well as specialized parameters to craft a proper error message and details. This specific error function should be re-using under the cover one the underlying pre-defined HTTP error creator, see list.

The most important thing is that all error should have a proper unique code defined using derr.C("value") type alias which is a sugar syntax for derr.ErrorCode("string_code_error").

This is of the uttermost importance so that we can easily grep all our source code files to extract the used specific error codes across all our services for documentation purposes.

The string code defined must be unique among all our services, human readable, should clearly represent the error in few words, should be in snake_case format and should end with _error.

For example, let's say that in your micro service, you would like to define a specialized bad request error when a particular request is invalid due to block number being too low.

Here the piece of code that your should do:

func BlockNumTooLowError(ctx context.Context, blockNum uint32, thresholdBlockNum uint32) *derr.ErrorResponse {
	return HTTPBadRequestError(ctx, err, derr.C("block_num_too_low_error"), "The requested block num is too low",
        "actual_block_num", blockNum,
        "threshold_block_num", thresholdBlockNum,
    )
}

Each of generic HTTP error creator receives the context.Context object. This context is required to extract the traceID from the context so that the trace ID is returned back to the user for future analysis of the problem.

Moreover, the idiomatic way to group errors is to put them all in a file errors.go in the root package of the service so they are all easily discoverable in a single location.

JSON Format

Here the explained JSON format:

{
  "code": "specifc_error_code",
  "trace_id": "%s",
  "message": "Sepcific error code message, audience is the end user."
  "details": {
    "key": <value>,
    ...
  },
}
Parameter Explanation
code The unique error representing this error, should be a human readable summary of the error, in snake case.
trace_id The unique trace id to further debug that error, the trace id can also be correlated in the logs.
message A message describing the error. The audience of the message is the end user. Should be a full sentence ending with a dot.
details A key-value map of extra details specific to the error. Usually contains faulty parameters and extra details about the error.
Wrap

This package is aware of wrapped errors through the github.com/pkg/errors package.

As a convenience, the package provides shortcuts to the Wrap and Wrapf of the pkgErrors package so you don't need to import it directly using a custom name like pkgErrors (to avoid conflict with the standard errors package).

You can simply use derr.Wrap and derr.Wrapf to wrap your errors with newer contextual errors.

Write Error

The package provides a facility to write any error object back to the user. The derr.WriteError(ctx context.Context, w http.ResponseWriter, message string, err error) will correctly find the derr.ErrorResponse out of the err parameter received and will output to the user.

If no derr.ErrorResponse can be found, automatically, the error is wrapped in an derr.UnexpectedError and returned like that to the user. This behavior will result in a generic error message appearing for the user.

Note that WriteError is also logging the error at the same occasion, removing the burden to log the error yourself. If the error written back to the user generates a >= 500 error code, the Error level is used. Otherwise, a Debug level is used to log the error.

This error logging will ultimately trickle down to our monitoring infrastructure, so if you use WriteError, be sure to not log it again!

Contributing

Issues and PR in this repo related strictly to the derr library.

Report any protocol-specific issues in their respective repositories

Please first refer to the general StreamingFast contribution guide, if you wish to contribute to this code base.

License

Apache 2.0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPBadRequestError = newErrorClass(http.StatusBadRequest)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPUnauthorizedError = newErrorClass(http.StatusUnauthorized)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPPaymentRequiredError = newErrorClass(http.StatusPaymentRequired)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPForbiddenError = newErrorClass(http.StatusForbidden)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPNotFoundError = newErrorClass(http.StatusNotFound)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPMethodNotAllowedError = newErrorClass(http.StatusMethodNotAllowed)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPNotAcceptableError = newErrorClass(http.StatusNotAcceptable)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPProxyAuthRequiredError = newErrorClass(http.StatusProxyAuthRequired)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPRequestTimeoutError = newErrorClass(http.StatusRequestTimeout)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPConflictError = newErrorClass(http.StatusConflict)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPGoneError = newErrorClass(http.StatusGone)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPLengthRequiredError = newErrorClass(http.StatusLengthRequired)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPPreconditionFailedError = newErrorClass(http.StatusPreconditionFailed)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPRequestEntityTooLargeError = newErrorClass(http.StatusRequestEntityTooLarge)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPRequestURITooLongError = newErrorClass(http.StatusRequestURITooLong)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPUnsupportedMediaTypeError = newErrorClass(http.StatusUnsupportedMediaType)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPRequestedRangeNotSatisfiableError = newErrorClass(http.StatusRequestedRangeNotSatisfiable)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPExpectationFailedError = newErrorClass(http.StatusExpectationFailed)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPTeapotError = newErrorClass(http.StatusTeapot)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPUnprocessableEntityError = newErrorClass(http.StatusUnprocessableEntity)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPLockedError = newErrorClass(http.StatusLocked)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPFailedDependencyError = newErrorClass(http.StatusFailedDependency)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPUpgradeRequiredError = newErrorClass(http.StatusUpgradeRequired)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPPreconditionRequiredError = newErrorClass(http.StatusPreconditionRequired)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPTooManyRequestsError = newErrorClass(http.StatusTooManyRequests)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPRequestHeaderFieldsTooLargeError = newErrorClass(http.StatusRequestHeaderFieldsTooLarge)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPUnavailableForLegalReasonsError = newErrorClass(http.StatusUnavailableForLegalReasons)
)
View Source 
var (
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPInternalServerError = newErrorClass(http.StatusInternalServerError)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPNotImplementedError = newErrorClass(http.StatusNotImplemented)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPBadGatewayError = newErrorClass(http.StatusBadGateway)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPServiceUnavailableError = newErrorClass(http.StatusServiceUnavailable)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPGatewayTimeoutError = newErrorClass(http.StatusGatewayTimeout)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPHTTPVersionNotSupportedError = newErrorClass(http.StatusHTTPVersionNotSupported)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPVariantAlsoNegotiatesError = newErrorClass(http.StatusVariantAlsoNegotiates)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPInsufficientStorageError = newErrorClass(http.StatusInsufficientStorage)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPLoopDetectedError = newErrorClass(http.StatusLoopDetected)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPNotExtendedError = newErrorClass(http.StatusNotExtended)
	// Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package,
	// which provides a more comprehensive and flexible approach to error handling in HTTP contexts.
	HTTPNetworkAuthenticationRequiredError = newErrorClass(http.StatusNetworkAuthenticationRequired)
)
View Source 
var ErrorCheck = Check

Deprecated: use `Check` with `derr.Check`).

Functions

func Check 

func Check(prefix string, err error)

func DebugErrorChain 

func DebugErrorChain(err error) (out string)

DebugErrorChain returns a debug human friendly string represents the full stack of errors with the type of.

func Find 

func Find(err error, matcher func(err error) bool) error

Find walks the error(s) stack (causes chain) and return the first error matching the `matcher` function received in argument.

Act exactly like `errors.Is` but using a matcher function instead of trying to match a particular address.

func FindFirstMatching deprecated 

func FindFirstMatching(err error, matcher func(err error) bool) error

FindFirstMatching walks the error(s) stack (causes chain) and return the first error matching the `matcher` function received in argument.

Deprecated: FindFirstMatching has been renamed to `Find`.

func HasAny deprecated 

func HasAny(err error, cause error) bool

HasAny returns `true` if the `err` argument or any of its cause(s) is equal to `cause` argument, `false` otherwise.

Deprecated: HasAny has been renamed to `Is`, use it instead of this method.

func Is 

func Is(err error, cause error) bool

Is reports whether any error in err's chain matches target.

The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap (or Cause).

func IsClientSideNetworkError 

func IsClientSideNetworkError(err error) bool

IsClientSideNetworkError returns whether the error received is a network error caused by the client side that could not be possibly handled correctly on the server side anyway.

func IsShuttingDown 

func IsShuttingDown() bool

func Retry 

func Retry(retries uint64, f func(ctx context.Context) error) error

Retry re-executes the function `f` if it returns an error. If you return a `derr.FatalError` your function will not be retried.

func RetryContext 

func RetryContext(ctx context.Context, retries uint64, f func(ctx context.Context) error) error

RetryContext re-executes the function `f` if it returns an error. If you return a `derr.FatalError` your function will not be retried.

func SetupSignalHandler 

func SetupSignalHandler(gracefulShutdownDelay time.Duration) <-chan os.Signal

this is a graceful delay to allow residual traffic sent by the load balancer to be processed without returning 500. Once the delay has passed then the service can be shutdown

func Status 

func Status(code codes.Code, message string) error

func Statusf 

func Statusf(code codes.Code, format string, args ...interface{}) error

func Walk 

func Walk(err error, processor func(err error) (bool, error)) error

Walk traverse error causes in a top to bottom fashion. Starting from the top `err` received, will invoke `processor(err)` with it. Walk calls immediately on start the `processor(err)` with the root error received that can be `nil`, so you must ready to handle the fact that you might receive `nil`.

If the `processor` returns `true`, check if `err` has a cause and continue walking it like this recursively. If `processor` return a `non-nil` value, stop walking at this point. If `processor` returns an `error` stop walking from there and bubble up the error through `Walk` return value.

Returns an `error` if `processor` returned an `error`, `nil` otherwise

func Wrap 

func Wrap(err error, message string) error

Wrap is a shortcut for `pkgErrors.Wrap` (where `pkgErrors` is `github.com/pkg/errors`)

func WrapCode 

func WrapCode(code codes.Code, err error, message string) error

func Wrapf 

func Wrapf(err error, format string, args ...interface{}) error

Wrapf is a shortcut for `pkgErrors.Wrapf` (where `pkgErrors` is `github.com/pkg/errors`)

func WrapfCode 

func WrapfCode(code codes.Code, err error, format string, args ...interface{}) error

func WriteError deprecated 

func WriteError(ctx context.Context, w http.ResponseWriter, message string, err error)

WriteError writes the receiver error to HTTP and log it into a Zap logger at the same time with the right level based on the actual status code. The `WriteError` handles various type for the `err` parameter.

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

Types

type ErrorCode deprecated 

type ErrorCode string

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func C deprecated 

func C(code string) ErrorCode

C is a sugar syntax for `derr.ErrorCode("a_string_code")` (sugared to `derr.C("a_string_code")`)

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

type ErrorResponse deprecated 

type ErrorResponse struct {
	Code    ErrorCode              `json:"code"`
	TraceID string                 `json:"trace_id"`
	Status  int                    `json:"-"`
	Message string                 `json:"message"`
	Details map[string]interface{} `json:"details,omitempty"`
	Causer  error                  `json:"-"`
}

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func HTTPErrorFromStatus deprecated 

func HTTPErrorFromStatus(status int, ctx context.Context, cause error, code ErrorCode, message interface{}, keyvals ...interface{}) *ErrorResponse

HTTPErrorFromStatus can be used to programmaticaly route the right status to one of the HTTP error class above

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func InvalidJSONError deprecated 

func InvalidJSONError(ctx context.Context, err error) *ErrorResponse

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func MissingBodyError deprecated 

func MissingBodyError(ctx context.Context) *ErrorResponse

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func RequestValidationError deprecated 

func RequestValidationError(ctx context.Context, errors url.Values) *ErrorResponse

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func ServiceUnavailableError deprecated 

func ServiceUnavailableError(ctx context.Context, cause error, serviceName string) *ErrorResponse

ServiceUnavailableError represents a failure at the transport layer to reach a given micro-service. Note that while `serviceName` is required, it's not directly available to final response for now, will probably encrypt it into an opaque string if you ever make usage of it

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func ToErrorResponse deprecated 

func ToErrorResponse(ctx context.Context, err error) *ErrorResponse

ToErrorResponse turns a plain `error` interface into a proper `ErrorResponse` object. It does so with the following rules:

- If `err` is already an `ErrorResponse`, turns it into such and returns it. - If `err` was wrapped, find the most cause which is an `ErrorResponse` and returns it. - If `err` is a status.Status (or one that was wrapped), convert it to an ErrorResponse - Otherwise, return an `UnexpectedError` with the cause sets to `err` received.

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func UnexpectedError deprecated 

func UnexpectedError(ctx context.Context, cause error) *ErrorResponse

Deprecated: HTTP error handling has moved to [dhttp](https://github.com/streamingfast/dhttp) package, which provides a more comprehensive and flexible approach to error handling in HTTP contexts.

func (*ErrorResponse) Cause 

func (e *ErrorResponse) Cause() error

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

func (*ErrorResponse) ResponseStatus 

func (e *ErrorResponse) ResponseStatus() int

type FatalError 

type FatalError struct {
	// contains filtered or unexported fields
}

func NewFatalError 

func NewFatalError(original error) *FatalError

NewFatalError creates a new FatalError struct ensuring `original` error is non-nil otherwise this function panics with an error.

func (*FatalError) Error 

func (r *FatalError) Error() string

func (*FatalError) Unwrap 

func (r *FatalError) Unwrap() error

type RetryableError 

type RetryableError struct {
	// contains filtered or unexported fields
}

RetryableError can be returned by your handler either [SinkerHandlers#HandleBlockScopedData] or [SinkerHandlers#HandleBlockUndoSignal] to notify the sinker that it's a retryable error and the stream can continue

func NewRetryableError 

func NewRetryableError(original error) *RetryableError

NewRetryableError creates a new RetryableError struct ensuring `original` error is non-nil otherwise this function panics with an error.

func (*RetryableError) Error 

func (r *RetryableError) Error() string

func (*RetryableError) Unwrap 

func (r *RetryableError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.