Merge branch 'refactor/const-api-errors' of go/aicra into 0.3.0
continuous-integration/drone/push Build is passing Details
continuous-integration/drone/tag Build is passing Details

allow constants for api.Error and update api.Handler signature

- api.EmtyResponse().WithError(api.Error) is the new interface for api.Response
- handlers return an api.Response that is wrapped into the final response
- server.HandleFunc becomes server.Handle
This commit is contained in:
Adrien Marquès 2020-03-28 14:01:08 +00:00 committed by Gogs
commit d3e8d48bc3
6 changed files with 101 additions and 92 deletions

View File

@ -1,70 +1,94 @@
package api
var (
// ErrorSuccess represents a generic successful service execution
ErrorSuccess = func() Error { return Error{0, "all right", nil} }
// ErrorFailure is the most generic error
ErrorFailure = func() Error { return Error{1, "it failed", nil} }
// ErrorUnknown represents any error which cause is unknown.
// It might also be used for debug purposes as this error
// has to be used the less possible
ErrorUnknown = func() Error { return Error{-1, "", nil} }
ErrorUnknown Error = -1
// ErrorSuccess represents a generic successful service execution
ErrorSuccess Error = 0
// ErrorFailure is the most generic error
ErrorFailure Error = 1
// ErrorNoMatchFound has to be set when trying to fetch data and there is no result
ErrorNoMatchFound = func() Error { return Error{2, "no resource found", nil} }
ErrorNoMatchFound Error = 2
// ErrorAlreadyExists has to be set when trying to insert data, but identifiers or
// unique fields already exists
ErrorAlreadyExists = func() Error { return Error{3, "resource already exists", nil} }
ErrorAlreadyExists Error = 3
// ErrorConfig has to be set when there is a configuration error
ErrorConfig = func() Error { return Error{4, "configuration error", nil} }
ErrorConfig Error = 4
// ErrorUpload has to be set when a file upload failed
ErrorUpload = func() Error { return Error{100, "upload failed", nil} }
ErrorUpload Error = 100
// ErrorDownload has to be set when a file download failed
ErrorDownload = func() Error { return Error{101, "download failed", nil} }
ErrorDownload Error = 101
// MissingDownloadHeaders has to be set when the implementation
// of a service of type 'download' (which returns a file instead of
// a set or output fields) is missing its HEADER field
MissingDownloadHeaders = func() Error { return Error{102, "download headers are missing", nil} }
MissingDownloadHeaders Error = 102
// ErrorMissingDownloadBody has to be set when the implementation
// of a service of type 'download' (which returns a file instead of
// a set or output fields) is missing its BODY field
ErrorMissingDownloadBody = func() Error { return Error{103, "download body is missing", nil} }
ErrorMissingDownloadBody Error = 103
// ErrorUnknownService is set when there is no service matching
// the http request URI.
ErrorUnknownService = func() Error { return Error{200, "unknown service", nil} }
ErrorUnknownService Error = 200
// ErrorUncallableService is set when there the requested service's
// implementation (plugin file) is not found/callable
ErrorUncallableService = func() Error { return Error{202, "uncallable service", nil} }
ErrorUncallableService Error = 202
// ErrorNotImplemented is set when a handler is not implemented yet
ErrorNotImplemented Error = 203
// ErrorPermission is set when there is a permission error by default
// the api returns a permission error when the current scope (built
// by middlewares) does not match the scope required in the config.
// You can add your own permission policy and use this error
ErrorPermission = func() Error { return Error{300, "permission error", nil} }
ErrorPermission Error = 300
// ErrorToken has to be set (usually in authentication middleware) to tell
// the user that this authentication token is expired or invalid
ErrorToken = func() Error { return Error{301, "token error", nil} }
ErrorToken Error = 301
// ErrorMissingParam is set when a *required* parameter is missing from the
// http request
ErrorMissingParam = func() Error { return Error{400, "missing parameter", nil} }
ErrorMissingParam Error = 400
// ErrorInvalidParam is set when a given parameter fails its type check as
// defined in the config file.
ErrorInvalidParam = func() Error { return Error{401, "invalid parameter", nil} }
ErrorInvalidParam Error = 401
// ErrorInvalidDefaultParam is set when an optional parameter's default value
// does not match its type.
ErrorInvalidDefaultParam = func() Error { return Error{402, "invalid default param", nil} }
ErrorInvalidDefaultParam Error = 402
)
var errorReasons = map[Error]string{
ErrorUnknown: "unknown error",
ErrorSuccess: "all right",
ErrorFailure: "it failed",
ErrorNoMatchFound: "resource found",
ErrorAlreadyExists: "already exists",
ErrorConfig: "configuration error",
ErrorUpload: "upload failed",
ErrorDownload: "download failed",
MissingDownloadHeaders: "download headers are missing",
ErrorMissingDownloadBody: "download body is missing",
ErrorUnknownService: "unknown service",
ErrorUncallableService: "uncallable service",
ErrorNotImplemented: "not implemented",
ErrorPermission: "permission error",
ErrorToken: "token error",
ErrorMissingParam: "missing parameter",
ErrorInvalidParam: "invalid parameter",
ErrorInvalidDefaultParam: "invalid default param",
}

View File

@ -1,40 +1,42 @@
package api
import (
"encoding/json"
"fmt"
)
// Error represents an http response error following the api format.
// These are used by the services to set the *execution status*
// directly into the response as JSON alongside response output fields.
type Error struct {
type Error int
// Error implements the error interface
func (e Error) Error() string {
// use unknown error if no reason
reason, ok := errorReasons[e]
if !ok {
return ErrorUnknown.Error()
}
return fmt.Sprintf("[%d] %s", e, reason)
}
// MarshalJSON implements encoding/json.Marshaler interface
func (e Error) MarshalJSON() ([]byte, error) {
// use unknown error if no reason
reason, ok := errorReasons[e]
if !ok {
return ErrorUnknown.MarshalJSON()
}
// format to proper struct
formatted := struct {
Code int `json:"code"`
Reason string `json:"reason"`
Arguments []interface{} `json:"arguments"`
}{
Code: int(e),
Reason: reason,
}
// SetArguments set one or multiple arguments to the error
// to be displayed back to API caller
func (e *Error) SetArguments(arg0 interface{}, args ...interface{}) {
// 1. clear arguments */
e.Arguments = make([]interface{}, 0)
// 2. add arg[0]
e.Arguments = append(e.Arguments, arg0)
// 3. add optional other arguments
for _, arg := range args {
e.Arguments = append(e.Arguments, arg)
}
}
// Implements 'error'
func (e Error) Error() string {
if e.Arguments == nil || len(e.Arguments) < 1 {
return fmt.Sprintf("[%d] %s", e.Code, e.Reason)
}
return fmt.Sprintf("[%d] %s (%v)", e.Code, e.Reason, e.Arguments)
return json.Marshal(formatted)
}

View File

@ -4,28 +4,23 @@ import (
"strings"
)
// HandlerFunc manages an API request
type HandlerFunc func(Request, *Response)
// HandlerFn defines the handler signature
type HandlerFn func(req Request, res *Response) Error
// Handler is an API handler ready to be bound
type Handler struct {
path string
method string
handle HandlerFunc
Fn HandlerFn
}
// NewHandler builds a handler from its http method and path
func NewHandler(method, path string, handlerFunc HandlerFunc) *Handler {
func NewHandler(method, path string, fn HandlerFn) (*Handler, error) {
return &Handler{
path: path,
method: strings.ToUpper(method),
handle: handlerFunc,
}
}
// Handle fires a handler
func (h *Handler) Handle(req Request, res *Response) {
h.handle(req, res)
Fn: fn,
}, nil
}
// GetMethod returns the handler's HTTP method

View File

@ -16,31 +16,22 @@ type Response struct {
err Error
}
// NewResponse creates an empty response. An optional error can be passed as its first argument.
func NewResponse(errors ...Error) *Response {
res := &Response{
// EmptyResponse creates an empty response.
func EmptyResponse() *Response {
return &Response{
Status: http.StatusOK,
Data: make(ResponseData),
err: ErrorFailure(),
err: ErrorFailure,
Headers: make(http.Header),
}
// optional error
if len(errors) == 1 {
res.err = errors[0]
}
// WithError sets the error from a base error with error arguments.
func (res *Response) WithError(err Error) *Response {
res.err = err
return res
}
// SetError sets the error from a base error with error arguments.
func (res *Response) SetError(baseError Error, arguments ...interface{}) {
if len(arguments) > 0 {
baseError.SetArguments(arguments[0], arguments[1:]...)
}
res.err = baseError
}
// Error implements the error interface and dispatches to internal error.
func (res *Response) Error() string {
return res.err.Error()

19
http.go
View File

@ -18,7 +18,7 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
// 1. find a matching service in the config
service := server.config.Find(req)
if service == nil {
response := api.NewResponse(api.ErrorUnknownService())
response := api.EmptyResponse().WithError(api.ErrorUnknownService)
response.ServeHTTP(res, req)
logError(response)
return
@ -30,7 +30,7 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
// 3. extract URI data
err := dataset.ExtractURI(req)
if err != nil {
response := api.NewResponse(api.ErrorMissingParam())
response := api.EmptyResponse().WithError(api.ErrorMissingParam)
response.ServeHTTP(res, req)
logError(response)
return
@ -39,7 +39,7 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
// 4. extract query data
err = dataset.ExtractQuery(req)
if err != nil {
response := api.NewResponse(api.ErrorMissingParam())
response := api.EmptyResponse().WithError(api.ErrorMissingParam)
response.ServeHTTP(res, req)
logError(response)
return
@ -48,7 +48,7 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
// 5. extract form/json data
err = dataset.ExtractForm(req)
if err != nil {
response := api.NewResponse(api.ErrorMissingParam())
response := api.EmptyResponse().WithError(api.ErrorMissingParam)
response.ServeHTTP(res, req)
logError(response)
return
@ -68,15 +68,13 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
// 7. fail if found no handler
if foundHandler == nil {
if found {
r := api.NewResponse()
r.SetError(api.ErrorUncallableService(), service.Method, service.Pattern)
r := api.EmptyResponse().WithError(api.ErrorUncallableService)
r.ServeHTTP(res, req)
logError(r)
return
}
r := api.NewResponse()
r.SetError(api.ErrorUnknownService(), service.Method, service.Pattern)
r := api.EmptyResponse().WithError(api.ErrorUnknownService)
r.ServeHTTP(res, req)
logError(r)
return
@ -93,8 +91,9 @@ func (server httpServer) ServeHTTP(res http.ResponseWriter, req *http.Request) {
apireq.Param = dataset.Data
// 10. execute
response := api.NewResponse()
foundHandler.Handle(*apireq, response)
response := api.EmptyResponse()
apiErr := foundHandler.Fn(*apireq, response)
response.WithError(apiErr)
// 11. apply headers
res.Header().Set("Content-Type", "application/json; charset=utf-8")

View File

@ -47,13 +47,11 @@ func New(configPath string, dtypes ...datatype.T) (*Server, error) {
}
// HandleFunc sets a new handler for an HTTP method to a path
func (s *Server) HandleFunc(httpMethod, path string, handlerFunc api.HandlerFunc) {
handler := api.NewHandler(httpMethod, path, handlerFunc)
s.handlers = append(s.handlers, handler)
func (s *Server) Handle(httpMethod, path string, fn api.HandlerFn) {
handler, err := api.NewHandler(httpMethod, path, fn)
if err != nil {
panic(err)
}
// Handle sets a new handler
func (s *Server) Handle(handler *api.Handler) {
s.handlers = append(s.handlers, handler)
}