Add openapi3 validator middleware

This change introduces middleware which wraps an `http.Handler` with
OpenAPI 3 request and response validation.

Author: cmars

openapi3filter/middleware.go

@@ -0,0 +1,272 @@
+package openapi3filter
+
+import (
+	"bytes"
+	"io"
+	"log"
+	"net/http"
+
+	"github.com/getkin/kin-openapi/routers"
+)
+
+// Validator provides HTTP request and response validation middleware.
+type Validator struct {
+	router  routers.Router
+	errFunc ErrFunc
+	logFunc LogFunc
+	strict  bool
+}
+
+// ErrFunc handles errors that may occur during validation.
+type ErrFunc func(w http.ResponseWriter, status int, code ErrCode, err error)
+
+// LogFunc handles log messages that may occur during validation.
+type LogFunc func(message string, err error)
+
+// ErrCode is used for classification of different types of errors that may
+// occur during validation. These may be used to write an appropriate response
+// in ErrFunc.
+type ErrCode int
+
+const (
+	// ErrCodeOK indicates no error. It is also the default value.
+	ErrCodeOK = 0
+	// ErrCodeCannotFindRoute happens when the validator fails to resolve the
+	// request to a defined OpenAPI route.
+	ErrCodeCannotFindRoute = iota
+	// ErrCodeRequestInvalid happens when the inbound request does not conform
+	// to the OpenAPI 3 specification.
+	ErrCodeRequestInvalid = iota
+	// ErrCodeResponseInvalid happens when the wrapped handler response does
+	// not conform to the OpenAPI 3 specification.
+	ErrCodeResponseInvalid = iota
+)
+
+func (e ErrCode) responseText() string {
+	switch e {
+	case ErrCodeOK:
+		return "OK"
+	case ErrCodeCannotFindRoute:
+		return "not found"
+	case ErrCodeRequestInvalid:
+		return "bad request"
+	default:
+		return "server error"
+	}
+}
+
+// NewValidator returns a new response validation middlware, using the given
+// routes from an OpenAPI 3 specification.
+func NewValidator(router routers.Router, options ...ValidatorOption) *Validator {
+	v := &Validator{
+		router: router,
+		errFunc: func(w http.ResponseWriter, status int, code ErrCode, _ error) {
+			http.Error(w, code.responseText(), status)
+		},
+		logFunc: func(message string, err error) {
+			log.Printf("%s: %v", message, err)
+		},
+	}
+	for i := range options {
+		options[i](v)
+	}
+	return v
+}
+
+// ValidatorOption defines an option that may be specified when creating a
+// Validator.
+type ValidatorOption func(*Validator)
+
+// OnErr provides a callback that handles writing an HTTP response on a
+// validation error. This allows customization of error responses without
+// prescribing a particular form. This callback is only called on response
+// validator errors in Strict mode.
+func OnErr(f ErrFunc) ValidatorOption {
+	return func(v *Validator) {
+		v.errFunc = f
+	}
+}
+
+// OnLog provides a callback that handles logging in the Validator. This allows
+// the validator to integrate with a services' existing logging system without
+// prescribing a particular one.
+func OnLog(f LogFunc) ValidatorOption {
+	return func(v *Validator) {
+		v.logFunc = f
+	}
+}
+
+// Strict, if set, causes an internal server error to be sent if the wrapped
+// handler response fails response validation. If not set, the response is sent
+// and the error is only logged.
+func Strict(strict bool) ValidatorOption {
+	return func(v *Validator) {
+		v.strict = strict
+	}
+}
+
+// Middleware returns an http.Handler which wraps the given handler with
+// request and response validation.
+func (v *Validator) Middleware(h http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		route, pathParams, err := v.router.FindRoute(r)
+		if err != nil {
+			v.logFunc("validation error: failed to find route for "+r.URL.String(), err)
+			v.errFunc(w, http.StatusNotFound, ErrCodeCannotFindRoute, err)
+			return
+		}
+		requestValidationInput := &RequestValidationInput{
+			Request:    r,
+			PathParams: pathParams,
+			Route:      route,
+		}
+		err = ValidateRequest(r.Context(), requestValidationInput)
+		if err != nil {
+			v.logFunc("invalid request", err)
+			v.errFunc(w, http.StatusBadRequest, ErrCodeRequestInvalid, err)
+			return
+		}
+
+		var wr responseWrapper
+		if v.strict {
+			wr = &strictResponseWrapper{w: w}
+		} else {
+			wr = &warnResponseWrapper{w: w}
+		}
+
+		h.ServeHTTP(wr, r)
+
+		err = ValidateResponse(r.Context(), &ResponseValidationInput{
+			RequestValidationInput: requestValidationInput,
+			Status:                 wr.statusCode(),
+			Header:                 wr.Header(),
+			Body:                   nopCloser{bytes.NewBuffer(wr.bodyContents())},
+		})
+		if err != nil {
+			v.logFunc("invalid response", err)
+			if v.strict {
+				v.errFunc(w, http.StatusInternalServerError, ErrCodeResponseInvalid, err)
+			}
+			return
+		}
+
+		err = wr.flushBodyContents()
+		if err != nil {
+			v.logFunc("failed to write response", err)
+		}
+	})
+}
+
+type nopCloser struct {
+	io.Reader
+}
+
+// Close implements io.Closer.
+func (nopCloser) Close() error {
+	return nil
+}
+
+type responseWrapper interface {
+	http.ResponseWriter
+
+	// flushBodyContents writes the buffered response to the client, if it has
+	// not yet been written.
+	flushBodyContents() error
+
+	// statusCode returns the response status code, 0 if not set yet.
+	statusCode() int
+
+	// bodyContents returns the buffered
+	bodyContents() []byte
+}
+
+type warnResponseWrapper struct {
+	w      http.ResponseWriter
+	fl     http.Flusher
+	status int
+	body   bytes.Buffer
+}
+
+// Write implements http.ResponseWriter.
+func (l *warnResponseWrapper) Write(b []byte) (int, error) {
+	if l.status == 0 {
+		l.w.WriteHeader(l.status)
+	}
+	n, err := l.w.Write(b)
+	if err == nil {
+		l.body.Write(b)
+	}
+	return n, err
+}
+
+// WriteHeader implements http.ResponseWriter.
+func (l *warnResponseWrapper) WriteHeader(status int) {
+	if l.status == 0 {
+		l.status = status
+	}
+	l.w.WriteHeader(l.status)
+}
+
+// Header implements http.ResponseWriter.
+func (wr *warnResponseWrapper) Header() http.Header {
+	return wr.w.Header()
+}
+
+// Flush implements the optional http.Flusher interface.
+func (wr *warnResponseWrapper) Flush() {
+	if fl, ok := wr.w.(http.Flusher); ok {
+		fl.Flush()
+	}
+}
+
+func (l *warnResponseWrapper) flushBodyContents() error {
+	return nil
+}
+
+func (l *warnResponseWrapper) statusCode() int {
+	return l.status
+}
+
+func (l *warnResponseWrapper) bodyContents() []byte {
+	return l.body.Bytes()
+}
+
+type strictResponseWrapper struct {
+	w      http.ResponseWriter
+	status int
+	body   bytes.Buffer
+}
+
+// Write implements http.ResponseWriter.
+func (wr *strictResponseWrapper) Write(b []byte) (int, error) {
+	if wr.status == 0 {
+		wr.status = http.StatusOK
+	}
+	return wr.body.Write(b)
+}
+
+// WriteHeader implements http.ResponseWriter.
+func (wr *strictResponseWrapper) WriteHeader(status int) {
+	if wr.status == 0 {
+		wr.status = status
+	}
+}
+
+// Header implements http.ResponseWriter.
+func (wr *strictResponseWrapper) Header() http.Header {
+	return wr.w.Header()
+}
+
+func (wr *strictResponseWrapper) flushBodyContents() error {
+	wr.w.WriteHeader(wr.status)
+	_, err := wr.w.Write(wr.body.Bytes())
+	return err
+}
+
+func (wr *strictResponseWrapper) statusCode() int {
+	return wr.status
+}
+
+func (wr *strictResponseWrapper) bodyContents() []byte {
+	return wr.body.Bytes()
+}