errors

package
v12.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2023 License: BSD-3-Clause Imports: 10 Imported by: 6

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Is is an alias of the standard errors.Is function.
	Is = errors.Is
	// As is an alias of the standard errors.As function.
	As = errors.As
	// New is an alias of the standard errors.New function.
	New = errors.New
	// Unwrap is an alias of the standard errors.Unwrap function.
	Unwrap = errors.Unwrap
)
View Source 
var (
	// ErrUnexpected is the HTTP error which sent to the client
	// when server fails to send an error, it's a fallback error.
	// The server fails to send an error on two cases:
	// 1. when the provided error code name is not registered (the error value is the ErrUnexpectedErrorCode)
	// 2. when the error contains data but cannot be encoded to json (the value of the error is the result error of json.Marshal).
	ErrUnexpected = E("UNEXPECTED_ERROR", http.StatusInternalServerError)
	// ErrUnexpectedErrorCode is the error which logged
	// when the given error code name is not registered.
	ErrUnexpectedErrorCode = New("unexpected error code name")
)
View Source 
var DefaultContextErrorHandler context.ErrorHandler = new(jsonErrorHandler)

DefaultContextErrorHandler returns a context error handler which fires a JSON bad request (400) error message when a rich rest response failed to be written to the client. Register it on Application.SetContextErrorHandler method.

View Source 
var DefaultPathParameterTypeErrorHandler handler.ParamErrorHandler = func(ctx *context.Context, paramIndex int, err error) {
	param := ctx.Params().GetEntryAt(paramIndex)
	InvalidArgument.DataWithDetails(ctx, "invalid path parameter", err.Error(), param)
}

DefaultPathParameterTypeErrorHandler registers an error handler for macro path type parameter. Register it with Application.Macros().SetErrorHandler(DefaultPathParameterTypeErrorHandler).

View Source 
var SkipCanceled = true

SkipCanceled is a package-level setting which by default skips the logging of a canceled response or operation. See the "Context.IsCanceled()" method and "iris.IsCanceled()" function that decide if the error is caused by a canceled operation.

Change of this setting MUST be done on initialization of the program.

Functions

func AsValidationErrors 

func AsValidationErrors(err error) (interface{}, bool)

AsValidationErrors reports wheether the given "err" is a type of validation error(s). Its behavior can be modified before serve-time through the "RegisterValidationErrorMapper" function.

func HandleAPIError 

func HandleAPIError(ctx *context.Context, err error)

HandleAPIError handles remote server errors. Optionally, use it when you write your server's HTTP clients using the the /x/client package. When the HTTP Client sends data to a remote server but that remote server failed to accept the request as expected, then the error will be proxied to this server's end-client.

When the given "err" is not a type of client.APIError then the error will be sent using the "Internal.LogErr" method which sends HTTP internal server error to the end-client and prints the "err" using the "LogError" package-level function.

func RegisterErrorCode 

func RegisterErrorCode(canonicalName ErrorCodeName, httpStatusCode int)

RegisterErrorCode registers a custom HTTP Error.

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

func RegisterErrorCodeMap 

func RegisterErrorCodeMap(errorMap map[ErrorCodeName]int)

RegisterErrorCodeMap registers one or more custom HTTP Errors.

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

func RegisterValidationErrorMapper 

func RegisterValidationErrorMapper(m ValidationErrorMapper)

RegisterValidationErrorMapper registers a custom implementation of validation error mapping. Call it on program initilization, main() or init() functions.

func RegisterValidationErrorMapperFunc 

func RegisterValidationErrorMapperFunc(fn func(err error) (interface{}, bool, bool))

RegisterValidationErrorMapperFunc registers a custom function implementation of validation error mapping. Call it on program initilization, main() or init() functions.

Types

type Error 

type Error struct {
	ErrorCode  ErrorCode       `json:"http_error_code" yaml:"HTTPErrorCode"`
	Message    string          `json:"message,omitempty" yaml:"Message"`
	Details    string          `json:"details,omitempty" yaml:"Details"`
	Validation interface{}     `json:"validation,omitempty" yaml:"Validation,omitempty"`
	Data       json.RawMessage `json:"data,omitempty" yaml:"Data,omitempty"` // any other custom json data.
}

Error represents the JSON form of "http wire errors".

Examples can be found at: 

https://github.com/kataras/iris/tree/master/_examples/routing/http-wire-errors.

func (*Error) Error 

func (err *Error) Error() string

Error method completes the error interface. It just returns the canonical name, status code, message and details.

type ErrorCode 

type ErrorCode struct {
	CanonicalName ErrorCodeName `json:"canonical_name" yaml:"CanonicalName"`
	Status        int           `json:"status" yaml:"Status"`
}

ErrorCode represents the JSON form ErrorCode of the Error.

type ErrorCodeName 

type ErrorCodeName string

ErrorCodeName is a custom string type represents canonical error names.

It contains functionality for safe and easy error populating. See its "Message", "Details", "Data" and "Log" methods. 

var (
	Cancelled          ErrorCodeName = E("CANCELLED", context.StatusTokenRequired)
	Unknown            ErrorCodeName = E("UNKNOWN", http.StatusInternalServerError)
	InvalidArgument    ErrorCodeName = E("INVALID_ARGUMENT", http.StatusBadRequest)
	DeadlineExceeded   ErrorCodeName = E("DEADLINE_EXCEEDED", http.StatusGatewayTimeout)
	NotFound           ErrorCodeName = E("NOT_FOUND", http.StatusNotFound)
	AlreadyExists      ErrorCodeName = E("ALREADY_EXISTS", http.StatusConflict)
	PermissionDenied   ErrorCodeName = E("PERMISSION_DENIED", http.StatusForbidden)
	Unauthenticated    ErrorCodeName = E("UNAUTHENTICATED", http.StatusUnauthorized)
	ResourceExhausted  ErrorCodeName = E("RESOURCE_EXHAUSTED", http.StatusTooManyRequests)
	FailedPrecondition ErrorCodeName = E("FAILED_PRECONDITION", http.StatusBadRequest)
	Aborted            ErrorCodeName = E("ABORTED", http.StatusConflict)
	OutOfRange         ErrorCodeName = E("OUT_OF_RANGE", http.StatusBadRequest)
	Unimplemented      ErrorCodeName = E("UNIMPLEMENTED", http.StatusNotImplemented)
	Internal           ErrorCodeName = E("INTERNAL", http.StatusInternalServerError)
	Unavailable        ErrorCodeName = E("UNAVAILABLE", http.StatusServiceUnavailable)
	DataLoss           ErrorCodeName = E("DATA_LOSS", http.StatusInternalServerError)
)

List of default error codes a server should follow and send back to the client.

func E 

func E(httpErrorCanonicalName string, httpStatusCode int) ErrorCodeName

E registers a custom HTTP Error and returns its canonical name for future use. The method "New" is reserved and was kept as it is for compatibility with the standard errors package, therefore the "E" name was chosen instead. The key stroke "e" is near and accessible while typing the "errors" word so developers may find it easy to use.

See "RegisterErrorCode" and "RegisterErrorCodeMap" for alternatives.

Example: 

	var (
   NotFound = errors.E("NOT_FOUND", http.StatusNotFound)
	)
	...
	NotFound.Details(ctx, "resource not found", "user with id: %q was not found", userID)

This method MUST be called on initialization, before HTTP server starts as the internal map is not protected by mutex.

func (ErrorCodeName) Data 

func (e ErrorCodeName) Data(ctx *context.Context, msg string, data interface{})

Data sends an error with a message and json data to the client.

func (ErrorCodeName) DataWithDetails 

func (e ErrorCodeName) DataWithDetails(ctx *context.Context, msg, details string, data interface{})

DataWithDetails sends an error with a message, details and json data to the client.

func (ErrorCodeName) Details 

func (e ErrorCodeName) Details(ctx *context.Context, msg, details string, detailsArgs ...interface{})

Details sends an error with a message and details to the client.

func (ErrorCodeName) Err 

func (e ErrorCodeName) Err(ctx *context.Context, err error)

Err sends the error's text as a message to the client. In exception, if the given "err" is a type of validation error then the Validation method is called instead.

func (ErrorCodeName) Log 

func (e ErrorCodeName) Log(ctx *context.Context, format string, args ...interface{})

Log sends an error of "format" and optional "args" to the client and prints that error using the "LogError" package-level function, which can be customized.

See "LogErr" too.

func (ErrorCodeName) LogErr 

func (e ErrorCodeName) LogErr(ctx *context.Context, err error)

LogErr sends the given "err" as message to the client and prints that error to using the "LogError" package-level function, which can be customized.

func (ErrorCodeName) Message 

func (e ErrorCodeName) Message(ctx *context.Context, format string, args ...interface{})

Message sends an error with a simple message to the client.

func (ErrorCodeName) Validation 

func (e ErrorCodeName) Validation(ctx *context.Context, validationErrors ...ValidationError)

Validation sends an error which renders the invalid fields to the client.

type LogErrorFunc 

type LogErrorFunc = func(ctx *context.Context, err error)

LogErrorFunc is an alias of a function type which accepts the Iris request context and an error and it's fired whenever an error should be logged.

See "OnErrorLog" variable to change the way an error is logged, by default the error is logged using the Application's Logger's Error method. 

var LogError LogErrorFunc = func(ctx *context.Context, err error) {
	ctx.Application().Logger().Error(err)
}

LogError can be modified to customize the way an error is logged to the server (most common: internal server errors, database errors et.c.). Can be used to customize the error logging, e.g. using Sentry (cloud-based error console).

type ValidationError 

type ValidationError interface {
	error

	GetField() string
	GetValue() interface{}
	GetReason() string
}

ValidationError is an interface which IF it custom error types completes, then it can by mapped to a validation error.

A validation error(s) can be given by ErrorCodeName's Validation or Err methods.

Example can be found at: 

https://github.com/kataras/iris/tree/master/_examples/routing/http-wire-errors/custom-validation-errors

type ValidationErrorMapper 

type ValidationErrorMapper interface {
	// The implementation must check the given "err"
	// and make decision if it's an error of validation
	// and if so it should return the value (err or another one)
	// and true as the last output argument.
	//
	// Outputs:
	//  1. the validation error(s) value
	//  2. true if the interface{} is an array, otherise false
	//  3. true if it's a validation error or false if not.
	MapValidationErrors(err error) (interface{}, bool, bool)
}

ValidationErrorMapper is the interface which custom validation error mappers should complete.

func NewValidationErrorTypeMapper 

func NewValidationErrorTypeMapper(types ...error) ValidationErrorMapper

NewValidationErrorTypeMapper returns a validation error mapper which compares the error with one or more of the given "types", through reflection. Each of the given types MUST complete the standard error type, so it can be passed through the error code.

type ValidationErrorMapperFunc 

type ValidationErrorMapperFunc func(err error) (interface{}, bool, bool)

ValidationErrorMapperFunc is an "ValidationErrorMapper" but in type of a function.

func (ValidationErrorMapperFunc) MapValidationErrors 

func (v ValidationErrorMapperFunc) MapValidationErrors(err error) (interface{}, bool, bool)

MapValidationErrors completes the "ValidationErrorMapper" interface.

type ValidationErrors 

type ValidationErrors []ValidationError

func (ValidationErrors) Error 

func (errs ValidationErrors) Error() string

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.