feat(fxhttpserver): Added possibility to register custom error handler (#314)

Author: ekkinox

fxhttpserver/README.md

@@ -19,6 +19,7 @@
     * [Middlewares](#middlewares)
     * [Handlers](#handlers)
     * [Handlers groups](#handlers-groups)
+    * [Error Handler](#error-handler)
   * [WebSocket](#websocket)
   * [Templates](#templates)
   * [Override](#override)
@@ -126,7 +127,7 @@ modules:
           namespace: foo              # http server metrics namespace (empty by default)
           subsystem: bar              # http server metrics subsystem (empty by default)
         buckets: 0.1, 1, 10           # to override default request duration buckets
-        normalize:               
+        normalize:
           request_path: true          # to normalize http request path, disabled by default
           response_status: true       # to normalize http response status code (2xx, 3xx, ...), disabled by default
       templates:
@@ -145,7 +146,7 @@ Notes:
 
 ### Registration
 
-This module offers the possibility to easily register handlers, groups and middlewares.
+This module offers the possibility to easily register handlers, groups, middlewares and error handlers.
 
 #### Middlewares
 
@@ -204,7 +205,7 @@ func main() {
 		fxmetrics.FxMetricsModule,
 		fxgenerate.FxGenerateModule,
 		fxhttpserver.FxHttpServerModule, // load the module
-		fx.Provide(
+		fx.Options(
 			fxhttpserver.AsMiddleware(middleware.CORS(), fxhttpserver.GlobalUse), // register echo CORS middleware via echo.Use()
 			fxhttpserver.AsMiddleware(NewSomeMiddleware, fxhttpserver.GlobalPre), // register and autowire the SomeMiddleware via echo.Pre()
 		),
@@ -296,15 +297,15 @@ func main() {
 		fxmetrics.FxMetricsModule,
 		fxgenerate.FxGenerateModule,
 		fxhttpserver.FxHttpServerModule, // load the module
-		fx.Provide(
+		fx.Options(
 			// register and autowire the SomeHandler handler for [GET] /some-path, with the SomeMiddleware and echo CORS() middlewares
 			fxhttpserver.AsHandler("GET", "/some-path", NewSomeHandler, NewSomeMiddleware, middleware.CORS()),
 		),
 	).Run()
 }
 ```
 
-Notes: 
+Notes:
 
 - you can specify several valid HTTP methods (comma separated) while registering a handler, for example `fxhttpserver.AsHandler("GET,POST", ...)`
 - you can use the shortcut `*` to register a handler for all valid HTTP methods, for example `fxhttpserver.AsHandler("*", ...)`
@@ -416,7 +417,7 @@ func main() {
 		fxmetrics.FxMetricsModule,
 		fxgenerate.FxGenerateModule,
 		fxhttpserver.FxHttpServerModule, // load the module
-		fx.Provide(
+		fx.Options(
 			// register and autowire the SomeHandler handler with NewSomeMiddleware middleware for [GET] /group/some-path
 			// register and autowire the OtherHandler handler with echo CORS middleware for [POST] /group/other-path
 			// register the echo CSRF middleware for all handlers of this group
@@ -439,6 +440,67 @@ Notes:
 - you can use the shortcut `*` to register a handler for all valid HTTP methods, for example `fxhttpserver.NewHandlerRegistration("*", ...)`
 - valid HTTP methods are `CONNECT`, `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, `TRACE`, `PROPFIND` and `REPORT`
 
+#### Error Handler
+
+You can use the `AsErrorHandler()` function to register a custom error handler on your http server.
+
+You can provide any [ErrorHandler](registry.go) interface implementation (will be autowired from Fx container)
+
+```go
+package main
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/ankorstore/yokai/config"
+	"github.com/ankorstore/yokai/fxconfig"
+	"github.com/ankorstore/yokai/fxgenerate"
+	"github.com/ankorstore/yokai/fxhttpserver"
+	"github.com/ankorstore/yokai/fxlog"
+	"github.com/ankorstore/yokai/fxmetrics"
+	"github.com/ankorstore/yokai/fxtrace"
+	"github.com/ankorstore/yokai/httpserver"
+	"github.com/labstack/echo/v4"
+	"github.com/labstack/echo/v4/middleware"
+	"go.uber.org/fx"
+)
+
+type SomeErrorHandler struct {
+	config *config.Config
+}
+
+func NewSomeErrorHandler(config *config.Config) *SomeErrorHandler {
+	return &SomeErrorHandler{
+		config: config,
+	}
+}
+
+func (h *SomeErrorHandler) Handle() echo.HTTPErrorHandler {
+	return func(err error, c echo.Context) {
+		if c.Response().Committed {
+			return
+		}
+
+		c.String(http.StatusInternalServerError, fmt.Sprintf("error handled in %s: %s", h.config.AppName(), err))
+	}
+}
+
+func main() {
+	fx.New(
+		fxconfig.FxConfigModule, // load the module dependencies
+		fxlog.FxLogModule,
+		fxtrace.FxTraceModule,
+		fxmetrics.FxMetricsModule,
+		fxgenerate.FxGenerateModule,
+		fxhttpserver.FxHttpServerModule, // load the module
+		fx.Options(
+			fxhttpserver.AsErrorHandler(NewSomeErrorHandler), // register SomeErrorHandler as error handler
+		),
+	).Run()
+}
+```
+
 ### WebSocket
 
 This module supports the `WebSocket` protocol, see the [Echo documentation](https://echo.labstack.com/docs/cookbook/websocket) for more information.
@@ -468,9 +530,9 @@ And the template:
 ```html
 <!-- templates/app.html -->
 <html>
-    <body>
-        <h1>App name is {{index . "name"}}</h1>
-    </body>
+<body>
+<h1>App name is {{index . "name"}}</h1>
+</body>
 </html>
 ```
 
@@ -521,7 +583,7 @@ func main() {
 		fxmetrics.FxMetricsModule,
 		fxgenerate.FxGenerateModule,
 		fxhttpserver.FxHttpServerModule, // load the module
-		fx.Provide(
+		fx.Options(
 			fxhttpserver.AsHandler("GET", "/app", NewTemplateHandler),
 		),
 	).Run()

fxhttpserver/go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/ankorstore/yokai/fxmetrics v1.2.0
 	github.com/ankorstore/yokai/fxtrace v1.2.0
 	github.com/ankorstore/yokai/generate v1.2.0
-	github.com/ankorstore/yokai/httpserver v1.5.0
+	github.com/ankorstore/yokai/httpserver v1.6.0
 	github.com/ankorstore/yokai/log v1.2.0
 	github.com/ankorstore/yokai/trace v1.3.0
 	github.com/labstack/echo/v4 v4.12.0

fxhttpserver/go.sum

@@ -12,8 +12,8 @@ github.com/ankorstore/yokai/fxtrace v1.2.0 h1:SXlWbjKSsb2wVH+hXSE9OD2VwyqkznwwW+
 github.com/ankorstore/yokai/fxtrace v1.2.0/go.mod h1:ch72eVTlIedETOApK7SXk2NEWpn3yYeM018dNRccocg=
 github.com/ankorstore/yokai/generate v1.2.0 h1:37siukjPGSS2kRnCnPhiuiF373+0tgwp0teXHnMsBhA=
 github.com/ankorstore/yokai/generate v1.2.0/go.mod h1:gqS/i20wnvCOhcXydYdiGcASzBaeuW7GK6YYg/kkuY4=
-github.com/ankorstore/yokai/httpserver v1.5.0 h1:42nfCFCGWuBKbwU8Jhlf1/ofrezDes8HlCa0mhiVoI8=
-github.com/ankorstore/yokai/httpserver v1.5.0/go.mod h1:AOCL4cK2bPKrtGFULvOvc8mKHAOw2bLW30CKJra2BB0=
+github.com/ankorstore/yokai/httpserver v1.6.0 h1:Xq3Jh1UM8tMQAnCM1wwGgi+Bm9NZwzJEJJcl56G4oNM=
+github.com/ankorstore/yokai/httpserver v1.6.0/go.mod h1:AOCL4cK2bPKrtGFULvOvc8mKHAOw2bLW30CKJra2BB0=
 github.com/ankorstore/yokai/log v1.2.0 h1:jiuDiC0dtqIGIOsFQslUHYoFJ1qjI+rOMa6dI1LBf2Y=
 github.com/ankorstore/yokai/log v1.2.0/go.mod h1:MVvUcms1AYGo0BT6l88B9KJdvtK6/qGKdgyKVXfbmyc=
 github.com/ankorstore/yokai/trace v1.3.0 h1:0ji32oymIcxTmH5h6GRWLo5ypwBbWrZkXRf9rWF9070=

fxhttpserver/module.go

@@ -63,23 +63,30 @@ func NewFxHttpServer(p FxHttpServerParam) (*echo.Echo, error) {
 	)
 
 	// renderer
-	var renderer echo.Renderer
+	var echoRenderer echo.Renderer
 	if p.Config.GetBool("modules.http.server.templates.enabled") {
-		renderer = httpserver.NewHtmlTemplateRenderer(p.Config.GetString("modules.http.server.templates.path"))
+		echoRenderer = httpserver.NewHtmlTemplateRenderer(p.Config.GetString("modules.http.server.templates.path"))
+	}
+
+	// error handler
+	var echoErrorHandler ErrorHandler
+	resolvedErrorHandlers := p.Registry.ResolveErrorHandlers()
+	if len(resolvedErrorHandlers) > 0 {
+		echoErrorHandler = resolvedErrorHandlers[0]
+	} else {
+		echoErrorHandler = httpserver.NewJsonErrorHandler(
+			p.Config.GetBool("modules.http.server.errors.obfuscate") || !appDebug,
+			p.Config.GetBool("modules.http.server.errors.stack") || appDebug,
+		)
 	}
 
 	// server
 	httpServer, err := p.Factory.Create(
 		httpserver.WithDebug(appDebug),
 		httpserver.WithBanner(false),
 		httpserver.WithLogger(echoLogger),
-		httpserver.WithRenderer(renderer),
-		httpserver.WithHttpErrorHandler(
-			httpserver.JsonErrorHandler(
-				p.Config.GetBool("modules.http.server.errors.obfuscate") || !appDebug,
-				p.Config.GetBool("modules.http.server.errors.stack") || appDebug,
-			),
-		),
+		httpserver.WithRenderer(echoRenderer),
+		httpserver.WithHttpErrorHandler(echoErrorHandler.Handle()),
 	)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create http server: %w", err)

fxhttpserver/module_test.go

@@ -10,6 +10,7 @@ import (
 	"github.com/ankorstore/yokai/fxconfig"
 	"github.com/ankorstore/yokai/fxgenerate"
 	"github.com/ankorstore/yokai/fxhttpserver"
+	"github.com/ankorstore/yokai/fxhttpserver/testdata/errorhandler"
 	"github.com/ankorstore/yokai/fxhttpserver/testdata/factory"
 	"github.com/ankorstore/yokai/fxhttpserver/testdata/handler"
 	"github.com/ankorstore/yokai/fxhttpserver/testdata/middleware"
@@ -1145,6 +1146,37 @@ func TestModuleWithTemplates(t *testing.T) {
 	)
 }
 
+func TestModuleWithCustomErrorHandler(t *testing.T) {
+	t.Setenv("APP_CONFIG_PATH", "testdata/config")
+	t.Setenv("APP_DEBUG", "true")
+
+	var httpServer *echo.Echo
+
+	fxtest.New(
+		t,
+		fx.NopLogger,
+		fxconfig.FxConfigModule,
+		fxlog.FxLogModule,
+		fxtrace.FxTraceModule,
+		fxmetrics.FxMetricsModule,
+		fxgenerate.FxGenerateModule,
+		fxhttpserver.FxHttpServerModule,
+		fx.Options(
+			fxhttpserver.AsHandler("GET", "/error", handler.NewTestErrorHandler),
+			fxhttpserver.AsErrorHandler(errorhandler.NewTestErrorHandler),
+		),
+		fx.Populate(&httpServer),
+	).RequireStart().RequireStop()
+
+	// [GET] /error
+	req := httptest.NewRequest(http.MethodGet, "/error", nil)
+	rec := httptest.NewRecorder()
+	httpServer.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusInternalServerError, rec.Code)
+	assert.Contains(t, rec.Body.String(), "error handled in test error handler of test: test error")
+}
+
 func TestModuleWithInvalidHandlerMethods(t *testing.T) {
 	t.Setenv("APP_CONFIG_PATH", "testdata/config")
 	t.Setenv("APP_DEBUG", "true")

fxhttpserver/register.go

@@ -291,3 +291,14 @@ func RegisterHandlersGroup(handlersGroupRegistration *HandlersGroupRegistration)
 		),
 	)
 }
+
+// AsErrorHandler replaces the default error handler.
+func AsErrorHandler(errorHandler any) fx.Option {
+	return fx.Provide(
+		fx.Annotate(
+			errorHandler,
+			fx.As(new(ErrorHandler)),
+			fx.ResultTags(`group:"httpserver-error-handlers"`),
+		),
+	)
+}

fxhttpserver/register_test.go

@@ -1,9 +1,11 @@
 package fxhttpserver_test
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/ankorstore/yokai/fxhttpserver"
+	"github.com/ankorstore/yokai/fxhttpserver/testdata/errorhandler"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -122,3 +124,11 @@ func TestHandlersGroupRegistration(t *testing.T) {
 		})
 	}
 }
+
+func TestErrorHandlerRegistration(t *testing.T) {
+	t.Parallel()
+
+	result := fxhttpserver.AsErrorHandler(errorhandler.NewTestErrorHandler)
+
+	assert.Equal(t, "fx.provideOption", fmt.Sprintf("%T", result))
+}

fxhttpserver/registry.go

@@ -17,13 +17,19 @@ type Handler interface {
 	Handle() echo.HandlerFunc
 }
 
+// ErrorHandler is the interface for error handlers.
+type ErrorHandler interface {
+	Handle() echo.HTTPErrorHandler
+}
+
 // HttpServerRegistry is the registry collecting middlewares, handlers, handlers groups and their definitions.
 type HttpServerRegistry struct {
 	middlewares              []Middleware
 	middlewareDefinitions    []MiddlewareDefinition
 	handlers                 []Handler
 	handlerDefinitions       []HandlerDefinition
 	handlersGroupDefinitions []HandlersGroupDefinition
+	errorHandlers            []ErrorHandler
 }
 
 // FxHttpServerRegistryParam allows injection of the required dependencies in [NewFxHttpServerRegistry].
@@ -34,16 +40,19 @@ type FxHttpServerRegistryParam struct {
 	Handlers                 []Handler                 `group:"httpserver-handlers"`
 	HandlerDefinitions       []HandlerDefinition       `group:"httpserver-handler-definitions"`
 	HandlersGroupDefinitions []HandlersGroupDefinition `group:"httpserver-handlers-group-definitions"`
+	ErrorHandlers            []ErrorHandler            `group:"httpserver-error-handlers"`
 }
 
 // NewFxHttpServerRegistry returns as new [HttpServerRegistry].
 func NewFxHttpServerRegistry(p FxHttpServerRegistryParam) *HttpServerRegistry {
 	return &HttpServerRegistry{
+
 		middlewares:              p.Middlewares,
 		middlewareDefinitions:    p.MiddlewareDefinitions,
 		handlers:                 p.Handlers,
 		handlerDefinitions:       p.HandlerDefinitions,
 		handlersGroupDefinitions: p.HandlersGroupDefinitions,
+		errorHandlers:            p.ErrorHandlers,
 	}
 }
 
@@ -143,6 +152,11 @@ func (r *HttpServerRegistry) ResolveHandlersGroups() ([]ResolvedHandlersGroup, e
 	return resolvedHandlersGroups, nil
 }
 
+// ResolveErrorHandlers resolves resolves a list of [ErrorHandler].
+func (r *HttpServerRegistry) ResolveErrorHandlers() []ErrorHandler {
+	return r.errorHandlers
+}
+
 func (r *HttpServerRegistry) resolveMiddlewareDefinition(middlewareDefinition MiddlewareDefinition) (ResolvedMiddleware, error) {
 	if middlewareDefinition.Concrete() {
 		if castMiddleware, ok := middlewareDefinition.Middleware().(func(echo.HandlerFunc) echo.HandlerFunc); ok {

fxhttpserver/registry_test.go

@@ -1,6 +1,7 @@
 package fxhttpserver_test
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/ankorstore/yokai/fxhttpserver"
@@ -17,6 +18,8 @@ var testHandler = func(c echo.Context) error {
 	return nil
 }
 
+var testErrorHandler = func(err error, c echo.Context) {}
+
 type testMiddlewareDefinitionMock struct {
 	mock.Mock
 }
@@ -87,6 +90,10 @@ func (h testHandlerImplementation) Handle() echo.HandlerFunc {
 	return testHandler
 }
 
+type testErrorHandlerImplementation struct{}
+
+func (h testErrorHandlerImplementation) Handle() echo.HTTPErrorHandler { return testErrorHandler }
+
 func TestNewFxHttpServerRegistry(t *testing.T) {
 	t.Parallel()
 
@@ -468,3 +475,20 @@ func TestResolveHandlersGroupFailureOnInvalidHandlerMiddlewareImplementation(t *
 	assert.Error(t, err)
 	assert.Equal(t, "cannot cast middleware definition as MiddlewareFunc", err.Error())
 }
+
+func TestResolveErrorHandlerSuccess(t *testing.T) {
+	t.Parallel()
+
+	param := fxhttpserver.FxHttpServerRegistryParam{
+		ErrorHandlers: []fxhttpserver.ErrorHandler{
+			testErrorHandlerImplementation{},
+		},
+	}
+	registry := fxhttpserver.NewFxHttpServerRegistry(param)
+
+	resolvedErrorHandlers := registry.ResolveErrorHandlers()
+
+	assert.Len(t, resolvedErrorHandlers, 1)
+
+	assert.Equal(t, "echo.HTTPErrorHandler", fmt.Sprintf("%T", resolvedErrorHandlers[0].Handle()))
+}