srverrors

Srverrors

srverrors lets you create and serve HTTP errors with additional info such as ID of the HTTP request and error causes (error details). Each error has its own unqiue error code and user friendly message.
You can declare your own JSON error structure that will be returned in the HTTP response body or use the default one.
Errors for your service can be generated from the YAML file with errors definitions.

• Creating an error
  • Manually
  • Declare an error type
  • Generate error types from YAML
• Serving an error
  • Writing an HTTP response
  • Custom JSON error structure

Creating an error

Manually

An error can be created using srverrors.New or srverrors.NewWithErr functions, providing HTTP status code, error code and user friendly message. Creating an error with srverrors.NewWithErr allows you to pass original error.
Error code is unchangeable code of the error type from your service.

   if err := CheckAuth(token); err != nil {
        return srverrors.NewWithErr(http.StatusUnauthorized, "001-001", "Invalid token.", err)
   }

Declare an error type

HTTP services usually have a list of HTTP errors they respond with and this list should be provided in documentation of the service.

Creating errors of certain types manually, like in the example above, is not very convenient, so the best way to define a new type of the error in your service is to declare functions that return errors of certain types. A certain error type also can be declared as a struct with the `srverrors.Err` interface.

Declaring an error type:

   type InvalidParametersError struct {
	    srverrors.Err
    }

    func CreateInvalidParametersError() *InvalidParametersError {
	    srvErr := srverrors.New(http.StatusBadRequest, "002-567", "Invalid request parameters.")
	    return &InvalidParametersError{srvErr}
    }

    func (e *InvalidParametersError) AddInvalidEmail(email string) {
	    e.AddCause("email", email, "Invalid email address.")
    }

Creating an error in your code:

   if !isEmailValid(email) {
	    err := CreateInvalidParametersError()
	    err.AddInvalidEmail(email)
	    return err
   }

Generate error types from YAML

Error types can be declared in the YAML file and generated from it. To do so, install the generator:

go install github.com/Quanare/srverrors/srverrors-generator

Then create the source YAML file in the following format:

<Error type>:
  code: <Error code>
  message: <Error message>
  http_status_code: <Error HTTP status code>

And run the generator srverrors-generator -s <source file path> -o <result .go file path> -p <name of the result file's package>.

You can check example source YAML file and result of the generation from that file. Command to generate the example:

srverrors-generator -s ./srverrors-generator/test-data/source.yaml -o ./srverrors-generator/test-data/expected_result.go -p test_data

Serving an error

srverrors.Presenter allows you to write an HTTP error response in the format you want.
If you don't define your own format, the default format is used. The default format is declared with srverrors.DefaultErrView and srverrors.DefaultCauseView.

Example of the default format:

{
    "error":{
        "code": "022-044",
        "message": "User is not allowed to see the application."
    },
    "request_id": "c3057227-feb5-4b64-b0fd-dfb83714c7df",
    "causes":
    [
        {
            "param": "role",
            "value": "guest",
            "message": "Invalid role."
        }
    ]
}

Writing an HTTP response

To write an error response, use Presenter.WriteJSONResponse.

Custom JSON error structure

To define your own format, do the following:

1. Implement srverrors.ErrView and srverrors.CauseView.

    type CustomViewErr struct {
        ErrorCode    string                `json:"error_code"`
        ErrorMessage string                `json:"error_message"`
        RequestID    string                `json:"id,omitempty"`
        Causes       []srverrors.CauseView `json:"details,omitempty"`
    }
   
    func (ev *CustomViewErr) SetCode(code string) {
        ev.ErrorCode = code
    }
   
    func (ev *CustomViewErr) SetMessage(message string) {
        ev.ErrorMessage = message
    }
   
    func (ev *CustomViewErr) SetRequestID(requestID string) {
        ev.RequestID = requestID
    }
   
    func (ev *CustomViewErr) SetCauses(causes []srverrors.CauseView) {
        ev.Causes = causes
    }
   
    type CustomViewCause struct {
        Type         string `json:"type"`
        Value        string `json:"value"`
        ErrorMessage string `json:"error_message"`
    }
   
    func (cv *CustomViewCause) SetParam(paramType string) {
        cv.Type = paramType
    }
   
    func (cv *CustomViewCause) SetValue(value string) {
        cv.Value = value
    }
   
    func (cv *CustomViewCause) SetMessage(message string) {
        cv.ErrorMessage = message
    }
   

2. Create a Presenter with PresenterConfig filled with functions that returns empty instances of your implementations.

   p := srverrors.CreatePresenter(srverrors.PresenterConfig{
            GetErrView: func() srverrors.ErrView {
                return &CustomViewErr{}
            },
            GetCauseView: func() srverrors.CauseView {
                return &CustomViewCause{}
            },
   })
   

With this example, the response body would be:

 {
    "error_code":"022-044",
    "error_message":"User is not allowed to see the application.",
    "id":"c3057227-feb5-4b64-b0fd-dfb83714c7df",
    "details":[
       {
          "type":"role",
          "value":"guest",
          "error_message":"Invalid role."
       }
    ]
 }