error.go

// Package goa standardizes on structured error responses: a request that fails because of
// invalid input or unexpected condition produces a response that contains one or more structured
// error(s). Each error object has three keys: a id (number), a title and a message. The title
// for a given id is always the same, the intent is to provide a human friendly categorization.
// The message is specific to the error occurrence and provides additional details that often
// include contextual information (name of parameters etc.).
//
// The basic data structure backing errors is TypedError which simply contains the id and message.
// Multiple errors (not just TypedError instances) can be encapsulated in a MultiError. Both
// TypedError and MultiError implement the error interface, the Error methods return valid JSON
// that can be written directly to a response body.
//
// The code generated by goagen calls the helper functions exposed in this file when it encounters
// invalid data (wrong type, validation errors etc.) such as InvalidParamTypeError,
// InvalidAttributeTypeError etc. These methods take and return an error which is a MultiError that
// gets built over time. The final MultiError object then gets serialized into the response and sent
// back to the client. The response status code is inferred from the type wrapping the error object:
// a BadRequestError produces a 400 status code while any other error produce a 500. This behavior
// can be overridden by setting a custom ErrorHandler in the application.
package goa

import (
	"bytes"
	"encoding/json"
	"fmt"
	"strconv"
	"strings"
)

type (
	// ErrorID is an enum listing the possible types of errors.
	ErrorID int

	// TypedError describes an error that can be returned in a HTTP response.
	TypedError struct {
		ID   ErrorID
		Mesg string
	}

	// MultiError records multiple errors.
	MultiError []error

	// BadRequestError is the type of errors that result in a response with status code 400.
	BadRequestError struct {
		Actual error
	}
)

const (
	// ErrInvalidParamType is the error produced by the generated code when
	// a request parameter type does not match the design.
	ErrInvalidParamType = iota + 1

	// ErrMissingParam is the error produced by the generated code when a
	// required request parameter is missing.
	ErrMissingParam

	// ErrInvalidAttributeType is the error produced by the generated
	// code when a data structure attribute type does not match the design
	// definition.
	ErrInvalidAttributeType

	// ErrMissingAttribute is the error produced by the generated
	// code when a data structure attribute required by the design
	// definition is missing.
	ErrMissingAttribute

	// ErrInvalidEnumValue is the error produced by the generated code when
	// a values does not match one of the values listed in the attribute
	// definition as being valid (i.e. not part of the enum).
	ErrInvalidEnumValue

	// ErrMissingHeader is the error produced by the generated code when a
	// required header is missing.
	ErrMissingHeader

	// ErrInvalidFormat is the error produced by the generated code when
	// a value does not match the format specified in the attribute
	// definition.
	ErrInvalidFormat

	// ErrInvalidPattern is the error produced by the generated code when
	// a value does not match the regular expression specified in the
	// attribute definition.
	ErrInvalidPattern

	// ErrInvalidRange is the error produced by the generated code when
	// a value is less than the minimum specified in the design definition
	// or more than the maximum.
	ErrInvalidRange

	// ErrInvalidLength is the error produced by the generated code when
	// a value is a slice with less elements than the minimum length
	// specified in the design definition or more elements than the
	// maximum length.
	ErrInvalidLength

	// ErrInvalidVersion is the error rendered by the default mux when a
	// request specifies an invalid version.
	ErrInvalidVersion
)

// Title returns a human friendly error title
func (k ErrorID) Title() string {
	switch k {
	case ErrInvalidParamType:
		return "invalid parameter value"
	case ErrMissingParam:
		return "missing required parameter"
	case ErrInvalidAttributeType:
		return "invalid attribute type"
	case ErrMissingAttribute:
		return "missing required attribute"
	case ErrMissingHeader:
		return "missing required HTTP header"
	case ErrInvalidEnumValue:
		return "invalid value"
	case ErrInvalidFormat:
		return "value does not match validation format"
	case ErrInvalidPattern:
		return "value does not match validation pattern"
	case ErrInvalidRange:
		return "invalid value range"
	case ErrInvalidLength:
		return "invalid value length"
	case ErrInvalidVersion:
		return "invalid version"
	}
	return "unknown error"
}

// MarshalJSON implements the json marshaler interface.
func (t *TypedError) MarshalJSON() ([]byte, error) {
	return json.Marshal(struct {
		ID    int    `json:"id" xml:"id"`
		Title string `json:"title" xml:"title"`
		Msg   string `json:"msg" xml:"msg"`
	}{
		ID:    int(t.ID),
		Title: t.ID.Title(),
		Msg:   t.Mesg,
	})
}

// Error builds an error message from the typed error details.
func (t *TypedError) Error() string {
	IncrCounter([]string{"goa", "error", strconv.Itoa(int(t.ID))}, 1.0)
	js, err := json.Marshal(t)
	if err != nil {
		return `{"id":0,"title":"generic","msg":"failed to serialize error"}`
	}
	return string(js)
}

// Error summarizes all the underlying error messages in one JSON array.
func (m MultiError) Error() string {
	var buffer bytes.Buffer
	buffer.WriteString("[")
	for i, err := range m {
		txt := err.Error()
		if _, ok := err.(*TypedError); !ok {
			b, err := json.Marshal(txt)
			txt = `{"id":0,"title":"generic","msg":`
			if err != nil {
				txt += `"unknown error"}`
			} else {
				txt += string(b) + "}"
			}
		}
		buffer.WriteString(txt)
		if i < len(m)-1 {
			buffer.WriteString(",")
		}
	}
	buffer.WriteString("]")

	// you can blame rsc for that: https://code.google.com/p/go/issues/detail?id=8592#c3
	txt := buffer.String()
	txt = strings.Replace(txt, "\\u0026", "&", -1)
	txt = strings.Replace(txt, "\\u003c", "<", -1)
	txt = strings.Replace(txt, "\\u003e", ">", -1)

	return txt
}

// NewBadRequestError wraps the given error into a BadRequestError.
func NewBadRequestError(err error) *BadRequestError {
	return &BadRequestError{Actual: err}
}

// Error implements error.
func (b *BadRequestError) Error() string {
	return b.Actual.Error()
}

// InvalidParamTypeError appends a typed error of id ErrInvalidParamType to
// err and returns it.
func InvalidParamTypeError(name string, val interface{}, expected string, err error) error {
	terr := TypedError{
		ID: ErrInvalidParamType,
		Mesg: fmt.Sprintf("invalid value %#v for parameter %#v, must be a %s",
			val, name, expected),
	}
	return ReportError(err, &terr)
}

// MissingParamError appends a typed error of id ErrMissingParam to err and
// returns it.
func MissingParamError(name string, err error) error {
	terr := TypedError{
		ID:   ErrMissingParam,
		Mesg: fmt.Sprintf("missing required parameter %#v", name),
	}
	return ReportError(err, &terr)
}

// InvalidAttributeTypeError appends a typed error of id ErrIncompatibleType
// to err and returns it.
func InvalidAttributeTypeError(ctx string, val interface{}, expected string, err error) error {
	terr := TypedError{
		ID: ErrInvalidAttributeType,
		Mesg: fmt.Sprintf("type of %s must be %s but got value %#v", ctx,
			expected, val),
	}
	return ReportError(err, &terr)
}

// MissingAttributeError appends a typed error of id ErrMissingAttribute to
// err and returns it.
func MissingAttributeError(ctx, name string, err error) error {
	terr := TypedError{
		ID:   ErrMissingAttribute,
		Mesg: fmt.Sprintf("attribute %#v of %s is missing and required", name, ctx),
	}
	return ReportError(err, &terr)
}

// MissingHeaderError appends a typed error of id ErrMissingHeader to err and
// returns it.
func MissingHeaderError(name string, err error) error {
	terr := TypedError{
		ID:   ErrMissingHeader,
		Mesg: fmt.Sprintf("missing required HTTP header %#v", name),
	}
	return ReportError(err, &terr)
}

// InvalidEnumValueError appends a typed error of id ErrInvalidEnumValue to
// err and returns it.
func InvalidEnumValueError(ctx string, val interface{}, allowed []interface{}, err error) error {
	elems := make([]string, len(allowed))
	for i, a := range allowed {
		elems[i] = fmt.Sprintf("%#v", a)
	}
	terr := TypedError{
		ID: ErrInvalidEnumValue,
		Mesg: fmt.Sprintf("value of %s must be one of %s but got value %#v", ctx,
			strings.Join(elems, ", "), val),
	}
	return ReportError(err, &terr)
}

// InvalidFormatError appends a typed error of id ErrInvalidFormat to err and
// returns it.
func InvalidFormatError(ctx, target string, format Format, formatError, err error) error {
	terr := TypedError{
		ID: ErrInvalidFormat,
		Mesg: fmt.Sprintf("%s must be formatted as a %s but got value %#v, %s",
			ctx, format, target, formatError.Error()),
	}
	return ReportError(err, &terr)
}

// InvalidPatternError appends a typed error of id ErrInvalidPattern to err and
// returns it.
func InvalidPatternError(ctx, target string, pattern string, err error) error {
	terr := TypedError{
		ID: ErrInvalidPattern,
		Mesg: fmt.Sprintf("%s must match the regexp %#v but got value %#v",
			ctx, pattern, target),
	}
	return ReportError(err, &terr)
}

// InvalidRangeError appends a typed error of id ErrInvalidRange to err and
// returns it.
func InvalidRangeError(ctx string, target interface{}, value int, min bool, err error) error {
	comp := "greater or equal"
	if !min {
		comp = "lesser or equal"
	}
	terr := TypedError{
		ID: ErrInvalidRange,
		Mesg: fmt.Sprintf("%s must be %s than %d but got value %#v",
			ctx, comp, value, target),
	}
	return ReportError(err, &terr)
}

// InvalidLengthError appends a typed error of id ErrInvalidLength to err and
// returns it.
func InvalidLengthError(ctx string, target interface{}, ln, value int, min bool, err error) error {
	comp := "greater or equal"
	if !min {
		comp = "lesser or equal"
	}
	terr := TypedError{
		ID: ErrInvalidLength,
		Mesg: fmt.Sprintf("length of %s must be %s than %d but got value %#v (len=%d)",
			ctx, comp, value, target, ln),
	}
	return ReportError(err, &terr)
}

// ReportError coerces the first argument into a MultiError then appends the second argument and
// returns the resulting MultiError.
func ReportError(err error, err2 error) error {
	if err == nil {
		if err2 == nil {
			return MultiError{}
		}
		if _, ok := err2.(MultiError); ok {
			return err2
		}
		return MultiError{err2}
	}
	merr, ok := err.(MultiError)
	if err2 == nil {
		if ok {
			return err
		}
		return MultiError{err}
	}
	merr2, ok2 := err2.(MultiError)
	if ok {
		if ok2 {
			return append(merr, merr2...)
		}
		return append(merr, err2)
	}
	merr = MultiError{err}
	if ok2 {
		return append(merr, merr2...)
	}
	return append(merr, err2)
}