feat: add error handler with more configuration

As a means to **??**o

This has been a long-standing issue **??**

With thanks to Per, Mike and MattiasMartens who have **??**, as well as
many others in the past who have **??**

Closes #11, #27.

Co-authored-by: Per Bockman <per.bockman@gmail.com>
Co-authored-by: Mike Schinkel <mike@newclarity.net>
Co-authored-by: MattiasMartens <33037520+MattiasMartens@users.noreply.github.com>

Author: 4 people

oapi_validate.go

@@ -8,6 +8,7 @@
 package nethttpmiddleware
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"log"
@@ -21,8 +22,42 @@ import (
 )
 
 // ErrorHandler is called when there is an error in validation
+//
+// NOTE that you likely want to use ErrorHandlerWithOpts, as it provides more **??** and access to the underlying `error`
+// If both an `ErrorHandlerWithOpts` and `ErrorHandler` are set, the `ErrorHandlerWithOpts` takes precedence
 type ErrorHandler func(w http.ResponseWriter, message string, statusCode int)
 
+// ErrorHandlerWithOpts provides
+// NOTE that this should ideally be used instead of ErrorHandler
+// If both an `ErrorHandlerWithOpts` and `ErrorHandler` are set, the `ErrorHandlerWithOpts` takes precedence
+type ErrorHandlerWithOpts func(ctx context.Context, w http.ResponseWriter, r *http.Request, opts ErrorHandlerOpts)
+
+type ErrorHandlerOptsMatchedRoute struct {
+	// Route indicates the Route that this error is received by, providing full context into the OpenAPI Spec TODO
+	// TODO
+	// NOTE nil when not found
+	Route *routers.Route
+
+	// TODO
+	// NOTE nil/empty when not found
+	PathParams map[string]string
+}
+
+// ErrorHandlerOpts contains additional options that are passed to the `ErrorHandlerWithOpts` function in the case of a validation error being returned by the middleware
+type ErrorHandlerOpts struct {
+	// TODO
+	// NOTE that this will be nil if there is no matched route (i.e. it's a **??**)
+	MatchedRoute *ErrorHandlerOptsMatchedRoute
+
+	// Error is the underlying error that triggered this error handler to be executed.
+	Error error
+
+	// StatusCode indicates the HTTP Status Code that TODO
+	//
+	// NOTE that this is a suggestion, and can be ignored if believed to be TODO
+	StatusCode int
+}
+
 // MultiErrorHandler is called when the OpenAPI filter returns an openapi3.MultiError (https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3#MultiError)
 type MultiErrorHandler func(openapi3.MultiError) (int, error)
 
@@ -32,11 +67,18 @@ type Options struct {
 	Options openapi3filter.Options
 	// ErrorHandler is called when a validation error occurs.
 	//
+	// TODO
+	//
 	// If not provided, `http.Error` will be called
 	ErrorHandler ErrorHandler
+
+	// TODO
+	ErrorHandlerWithOpts ErrorHandlerWithOpts
+
 	// MultiErrorHandler is called when there is an openapi3.MultiError (https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3#MultiError) returned by the `openapi3filter`.
 	//
 	// If not provided `defaultMultiErrorHandler` will be used.
+	// NOTE nto called if ErrorHandlerWithOpts
 	MultiErrorHandler MultiErrorHandler
 	// SilenceServersWarning allows silencing a warning for https://github.com/deepmap/oapi-codegen/issues/882 that reports when an OpenAPI spec has `spec.Servers != nil`
 	SilenceServersWarning bool
@@ -62,27 +104,115 @@ func OapiRequestValidatorWithOptions(spec *openapi3.T, options *Options) func(ne
 
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-			// validate request
-			statusCode, err := validateRequest(r, router, options)
-			if err == nil {
-				// serve
-				next.ServeHTTP(w, r)
-				return
-			}
-
 			if options == nil {
-				http.Error(w, err.Error(), statusCode)
-				return
-			}
-
-			if options.ErrorHandler != nil {
-				options.ErrorHandler(w, err.Error(), statusCode)
+				performRequestValidationForErrorHandler(next, w, r, router, options, http.Error)
+			} else if options.ErrorHandlerWithOpts != nil {
+				performRequestValidationForErrorHandlerWithOpts(next, w, r, router, options)
+			} else if options.ErrorHandler != nil {
+				performRequestValidationForErrorHandler(next, w, r, router, options, options.ErrorHandler)
+			} else {
+				// NOTE that this shouldn't happen, but let's be sure that we always end up calling the default error handler if no other handler is defined
+				performRequestValidationForErrorHandler(next, w, r, router, options, http.Error)
 			}
 		})
 	}
 
 }
 
+func performRequestValidationForErrorHandler(next http.Handler, w http.ResponseWriter, r *http.Request, router routers.Router, options *Options, errorHandler ErrorHandler) {
+	// validate request
+	statusCode, err := validateRequest(r, router, options)
+	if err == nil {
+		// serve
+		next.ServeHTTP(w, r)
+		return
+	}
+
+	errorHandler(w, err.Error(), statusCode)
+}
+
+// **??**
+// Note that this is an inline-and-modified version of `validateRequest` that **??**.
+func performRequestValidationForErrorHandlerWithOpts(next http.Handler, w http.ResponseWriter, r *http.Request, router routers.Router, options *Options) {
+	// Find route
+	route, pathParams, err := router.FindRoute(r)
+	if err != nil {
+		errOpts := ErrorHandlerOpts{
+			// MatchedRoute will be nil, as we've not matched a route we know about
+			Error:      err,
+			StatusCode: http.StatusNotFound,
+		}
+
+		options.ErrorHandlerWithOpts(r.Context(), w, r, errOpts)
+		return
+	}
+
+	errOpts := ErrorHandlerOpts{
+		MatchedRoute: &ErrorHandlerOptsMatchedRoute{
+			Route:      route,
+			PathParams: pathParams,
+		},
+		// other options will be added before executing
+	}
+
+	// Validate request
+	requestValidationInput := &openapi3filter.RequestValidationInput{
+		Request:    r,
+		PathParams: pathParams,
+		Route:      route,
+	}
+
+	if options != nil {
+		requestValidationInput.Options = &options.Options
+	}
+
+	err = openapi3filter.ValidateRequest(r.Context(), requestValidationInput)
+	if err == nil {
+		// it's a valid request, so serve it
+		next.ServeHTTP(w, r)
+		return
+	}
+
+	switch e := err.(type) {
+	case openapi3.MultiError:
+		errOpts.Error = e
+		errOpts.StatusCode = determineStatusCodeForMultiError(e)
+
+		// for _, err := range e {
+		// 	errs = append(errs, err)
+		// }
+		//
+		// errOpts.Error = errors.Join(errs...)
+		//
+		// fmt.Printf("e: %#v\n", e)
+		// // there's no point returning a MultiError if there's a singleton error
+		// if len(e) == 1 {
+		// 	for _, ee := range e {
+		// 		errOpts.Error = ee
+		// 		fmt.Printf("ee: %#v\n", ee)
+		// 	}
+		//
+		// }
+
+	case *openapi3filter.RequestError:
+		// We've got a bad request
+		errOpts.Error = e
+		errOpts.StatusCode = http.StatusBadRequest
+	case *openapi3filter.SecurityRequirementsError:
+		// return http.StatusUnauthorized, err
+		errOpts.Error = e
+		errOpts.StatusCode = http.StatusUnauthorized
+	default:
+		// This should never happen today, but if our upstream code changes,
+		// we don't want to crash the server, so handle the unexpected error.
+		// return http.StatusInternalServerError,
+		errOpts.Error = fmt.Errorf("error validating route: %w", e)
+		errOpts.StatusCode = http.StatusUnauthorized
+	}
+
+	options.ErrorHandlerWithOpts(r.Context(), w, r, errOpts)
+}
+
 // validateRequest is called from the middleware above and actually does the work
 // of validating a request.
 func validateRequest(r *http.Request, router routers.Router, options *Options) (int, error) {
@@ -150,3 +280,35 @@ func getMultiErrorHandlerFromOptions(options *Options) MultiErrorHandler {
 func defaultMultiErrorHandler(me openapi3.MultiError) (int, error) {
 	return http.StatusBadRequest, me
 }
+
+func determineStatusCodeForMultiError(errs openapi3.MultiError) int {
+	numRequestErrors := 0
+	numSecurityRequirementsErrors := 0
+
+	for _, err := range errs {
+		switch err.(type) {
+		case *openapi3filter.RequestError:
+			numRequestErrors++
+		case *openapi3filter.SecurityRequirementsError:
+			numSecurityRequirementsErrors++
+		default:
+			// if we have /any/ unknown error types, we should suggest returning an HTTP 500 Internal Server Error
+			return http.StatusInternalServerError
+		}
+	}
+
+	if numRequestErrors > 0 && numSecurityRequirementsErrors > 0 {
+		return http.StatusInternalServerError
+	}
+
+	if numRequestErrors > 0 {
+		return http.StatusBadRequest
+	}
+
+	if numSecurityRequirementsErrors > 0 {
+		return http.StatusUnauthorized
+	}
+
+	// we shouldn't hit this, but to be safe, return an HTTP 500 Internal Server Error if we don't have any cases above
+	return http.StatusInternalServerError
+}