Documentation
¶
Overview ¶
Package errs provides structured error handling for Encore applications.
See https://encore.dev/docs/develop/errors for more information about how errors work within Encore applications.
Index ¶
- func Convert(err error) (_ error)
- func HTTPError(w http.ResponseWriter, err error)
- func Wrap(err error, msg string, metaPairs ...interface{}) (_ error)
- func WrapCode(err error, code ErrCode, msg string, metaPairs ...interface{}) (_ error)
- type Builder
- func (*Builder) Cause(err error) (_ *Builder)
- func (*Builder) Code(c ErrCode) (_ *Builder)
- func (*Builder) Details(det ErrDetails) (_ *Builder)
- func (*Builder) Err() (_ error)
- func (*Builder) Meta(metaPairs ...interface{}) (_ *Builder)
- func (*Builder) Msg(msg string) (_ *Builder)
- func (*Builder) Msgf(format string, args ...interface{}) (_ *Builder)
- type ErrCode
- type ErrDetails
- type Error
- type Metadata
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Convert ¶ added in v0.13.1
Convert converts an error to an *Error. If the error is already an *Error it returns it unmodified. If err is nil it returns nil.
func HTTPError ¶
func HTTPError(w http.ResponseWriter, err error)
HTTPError writes structured error information to w using JSON encoding. The status code is computed with HTTPStatus.
If err is nil it writes:
{"code": "ok", "message": "", "details": null}
Types ¶
type Builder ¶ added in v0.13.1
type Builder struct {
// contains filtered or unexported fields
}
A Builder allows for gradual construction of an error. The zero value is ready for use.
Use Err() to construct the error.
func (*Builder) Details ¶ added in v0.13.1
func (*Builder) Details(det ErrDetails) (_ *Builder)
Details sets the details.
func (*Builder) Err ¶ added in v0.13.1
Err returns the constructed error. It never returns nil.
If Code has not been set or has been set to OK, the Code is set to Unknown.
If Msg has not been set and Cause is nil, the Msg is set to "unknown error".
type ErrCode ¶
type ErrCode int
ErrCode is an RPC error code.
const ( // OK indicates the operation was successful. OK ErrCode = 0 // Canceled indicates the operation was canceled (typically by the caller). // // Encore will generate this error code when cancellation is requested. Canceled ErrCode = 1 // Unknown error. An example of where this error may be returned is // if a Status value received from another address space belongs to // an error-space that is not known in this address space. Also // errors raised by APIs that do not return enough error information // may be converted to this error. // // Encore will generate this error code in the above two mentioned cases. Unknown ErrCode = 2 // InvalidArgument indicates client specified an invalid argument. // Note that this differs from FailedPrecondition. It indicates arguments // that are problematic regardless of the state of the system // (e.g., a malformed file name). // // Encore will generate this error code if the request data cannot be parsed. InvalidArgument ErrCode = 3 // 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. For // example, a successful response from a server could have been delayed // long enough for the deadline to expire. // // Encore will generate this error code when the deadline is exceeded. DeadlineExceeded ErrCode = 4 // NotFound means some requested entity (e.g., file or directory) was // not found. // // Encore will not generate this error code. NotFound ErrCode = 5 // AlreadyExists means an attempt to create an entity failed because one // already exists. // // Encore will not generate this error code. AlreadyExists ErrCode = 6 // PermissionDenied indicates the caller does not have permission to // execute the specified operation. It must not be used for rejections // caused by exhausting some resource (use ResourceExhausted // instead for those errors). It must not be // used if the caller cannot be identified (use Unauthenticated // instead for those errors). // // Encore will not generate this error code. PermissionDenied ErrCode = 7 // ResourceExhausted indicates some resource has been exhausted, perhaps // a per-user quota, or perhaps the entire file system is out of space. // // Encore will generate this error code in out-of-memory and server overload // situations, or when a message is larger than the configured maximum size. ResourceExhausted ErrCode = 8 // FailedPrecondition indicates operation was rejected because the // system is not in a state required for the operation's execution. // For example, directory to be deleted may be non-empty, an rmdir // operation is applied to a non-directory, etc. // // A litmus test that may help a service implementor in deciding // between FailedPrecondition, Aborted, and Unavailable: // (a) Use Unavailable if the client can retry just the failing call. // (b) Use Aborted if the client should retry at a higher-level // (e.g., restarting a read-modify-write sequence). // (c) Use FailedPrecondition if the client should not retry until // the system state has been explicitly fixed. E.g., if an "rmdir" // fails because the directory is non-empty, FailedPrecondition // should be returned since the client should not retry unless // they have first fixed up the directory by deleting files from it. // (d) Use FailedPrecondition if the client performs conditional // Get/Update/Delete on a resource and the resource on the // server does not match the condition. E.g., conflicting // read-modify-write on the same resource. // // Encore will not generate this error code. FailedPrecondition ErrCode = 9 // Aborted indicates the operation was aborted, typically due to a // concurrency issue like sequencer check failures, transaction aborts, // etc. // // See litmus test above for deciding between FailedPrecondition, // Aborted, and Unavailable. Aborted ErrCode = 10 // OutOfRange means operation was attempted past the valid range. // E.g., seeking or reading past end of file. // // Unlike InvalidArgument, this error indicates a problem that may // be fixed if the system state changes. For example, a 32-bit file // system will generate InvalidArgument if asked to read at an // offset that is not in the range [0,2^32-1], but it will generate // OutOfRange if asked to read from an offset past the current // file size. // // 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. // // Encore will not generate this error code. OutOfRange ErrCode = 11 // Unimplemented indicates operation is not implemented or not // supported/enabled in this service. // // Encore will generate this error code when an endpoint does not exist. Unimplemented ErrCode = 12 // Internal errors. Means some invariants expected by underlying // system has been broken. If you see one of these errors, // something is very broken. // // Encore will generate this error code in several internal error conditions. Internal ErrCode = 13 // This is a most likely a transient condition and may be corrected // by retrying with a backoff. Note that it is not always safe to retry // non-idempotent operations. // // See litmus test above for deciding between FailedPrecondition, // Aborted, and Unavailable. // // Encore will generate this error code in aubrupt shutdown of a server process // or network connection. Unavailable ErrCode = 14 // DataLoss indicates unrecoverable data loss or corruption. // // Encore will not generate this error code. DataLoss ErrCode = 15 // Unauthenticated indicates the request does not have valid // authentication credentials for the operation. // // Encore will generate this error code when the authentication metadata // is invalid or missing, and expects auth handlers to return errors with // this code when the auth token is not valid. Unauthenticated ErrCode = 16 )
func Code ¶
Code reports the error code from an error. If err is nil it reports OK. Otherwise if err is not an *Error it reports Unknown.
func (ErrCode) HTTPStatus ¶
HTTPStatus reports a suitable HTTP status code for an error, based on its code. If err is nil it reports 200. If it's not an *Error it reports 500.
func (ErrCode) MarshalJSON ¶
type ErrDetails ¶
type ErrDetails interface {
ErrDetails() // marker method; it need not do anything
}
ErrDetails is a marker interface for telling Encore the type is used for reporting error details.
We require a marker method (as opposed to using interface{}) to facilitate static analysis and to ensure the type can be properly serialized across the network.
func Details ¶
func Details(err error) (_ ErrDetails)
Details reports the error details included in the error. If err is nil or the error lacks details it reports nil.
type Error ¶
type Error struct {
// Code is the error code to return.
Code ErrCode `json:"code"`
// Message is a descriptive message of the error.
Message string `json:"message"`
// Details are user-defined additional details.
Details ErrDetails `json:"details"`
// Meta are arbitrary key-value pairs for use within
// the Encore application. They are not exposed to external clients.
Meta Metadata `json:"-"`
}
An Error is an error that provides structured information about the error. It includes an error code, a message, optionally additional structured details about the error and arbitrary key-value metadata.
The Details field is returned to external clients. The Meta field is only exposed to internal calls within Encore.
Internally it captures an underlying error for printing and for use with errors.Is/As and call stack information.
To provide accurate stack information, users are expected to convert non-Error errors into *Error as close to the root cause as possible. This is made simple with Wrap.
func (*Error) ErrorMessage ¶
ErrorMessage reports the error message, joining this error's message with the messages from any underlying errors.
Source Files