feat: oapi codegen response validator

Author: rolosp

api/v3/oasmiddleware/validator.go

@@ -66,6 +66,9 @@ func ValidateRequest(validationRouter routers.Router, opts ValidateRequestOption
 type ValidateResponseOption struct {
 	// ResponseValidationErrorHook is called when the route response body is not validated
 	ResponseValidationErrorHook ResponseValidationFunc
+	// RouteFilterHook is called after the route is found; return false to skip validation for that route.
+	// If nil, all matched routes are validated.
+	RouteFilterHook func(*routers.Route) bool
 	// FilterOptions are the openapi3filter option to pass to the underlying lib
 	FilterOptions *openapi3filter.Options
 }
@@ -75,8 +78,6 @@ type ValidateResponseOption struct {
 func ValidateResponse(validationRouter routers.Router, opts ValidateResponseOption) func(h http.Handler) http.Handler {
 	return func(h http.Handler) http.Handler {
 		fn := func(w http.ResponseWriter, r *http.Request) {
-			var err error
-
 			route, pathParams, err := validationRouter.FindRoute(r)
 
 			if err != nil {
@@ -85,6 +86,11 @@ func ValidateResponse(validationRouter routers.Router, opts ValidateResponseOpti
 					opts.ResponseValidationErrorHook(err, r)
 				}
 			} else {
+				if opts.RouteFilterHook != nil && !opts.RouteFilterHook(route) {
+					h.ServeHTTP(w, r)
+					return
+				}
+
 				// need to wrap std lib response to access the body
 				rww := NewResponseWriterWrapper(w)
 

api/v3/oasmiddleware/validator_test.go

@@ -0,0 +1,133 @@
+package oasmiddleware_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/getkin/kin-openapi/routers"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/oasmiddleware"
+)
+
+// TestValidateResponse_Violation proves that the ValidateResponse middleware fires its
+// error hook when a handler returns a response body that violates the OpenAPI spec.
+//
+// GET /openmeter/addons requires a 200 body with both "data" and "meta" fields.
+// Returning {} omits both required fields and must trigger a violation.
+func TestValidateResponse_Violation(t *testing.T) {
+	swagger, err := api.GetSwagger()
+	require.NoError(t, err)
+
+	swagger.Servers = nil
+
+	router, err := oasmiddleware.NewValidationRouter(t.Context(), swagger, &oasmiddleware.ValidationRouterOpts{
+		DeleteServers: true,
+	})
+	require.NoError(t, err)
+
+	var gotErr error
+	mw := oasmiddleware.ValidateResponse(router, oasmiddleware.ValidateResponseOption{
+		ResponseValidationErrorHook: func(err error, r *http.Request) {
+			gotErr = err
+		},
+	})
+
+	badHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{}`))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/openmeter/addons", nil)
+	rec := httptest.NewRecorder()
+
+	mw(badHandler).ServeHTTP(rec, req)
+
+	assert.Error(t, gotErr, "expected a validation error for missing required fields")
+	t.Logf("validation error (expected): %v", gotErr)
+}
+
+// TestValidateResponse_Clean proves that a well-formed response does not trigger the error hook.
+func TestValidateResponse_Clean(t *testing.T) {
+	swagger, err := api.GetSwagger()
+	require.NoError(t, err)
+
+	swagger.Servers = nil
+
+	router, err := oasmiddleware.NewValidationRouter(t.Context(), swagger, &oasmiddleware.ValidationRouterOpts{
+		DeleteServers: true,
+	})
+	require.NoError(t, err)
+
+	var gotErr error
+	mw := oasmiddleware.ValidateResponse(router, oasmiddleware.ValidateResponseOption{
+		ResponseValidationErrorHook: func(err error, r *http.Request) {
+			gotErr = err
+		},
+	})
+
+	goodHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"data":[],"meta":{"page":{"number":0,"size":100,"total":0}}}`))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/openmeter/addons", nil)
+	rec := httptest.NewRecorder()
+
+	mw(goodHandler).ServeHTTP(rec, req)
+
+	assert.NoError(t, gotErr, "expected no validation error for a well-formed response")
+}
+
+// TestValidateResponse_RouteFilterSkipsValidation proves that when RouteFilterHook returns false,
+// the response body is neither buffered nor validated — even if it would otherwise violate the spec.
+// The filter is the per-route gate that lets callers (e.g. unstable-only mode) avoid the
+// buffering overhead on routes they don't care about.
+func TestValidateResponse_RouteFilterSkipsValidation(t *testing.T) {
+	swagger, err := api.GetSwagger()
+	require.NoError(t, err)
+
+	swagger.Servers = nil
+
+	router, err := oasmiddleware.NewValidationRouter(t.Context(), swagger, &oasmiddleware.ValidationRouterOpts{
+		DeleteServers: true,
+	})
+	require.NoError(t, err)
+
+	var (
+		gotErr        error
+		filteredRoute *routers.Route
+	)
+	mw := oasmiddleware.ValidateResponse(router, oasmiddleware.ValidateResponseOption{
+		RouteFilterHook: func(route *routers.Route) bool {
+			filteredRoute = route
+			return false
+		},
+		ResponseValidationErrorHook: func(err error, r *http.Request) {
+			gotErr = err
+		},
+	})
+
+	// Body that would fail validation if the filter let it through.
+	badHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{}`))
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/openmeter/addons", nil)
+	rec := httptest.NewRecorder()
+
+	mw(badHandler).ServeHTTP(rec, req)
+
+	require.NotNil(t, filteredRoute, "RouteFilterHook should have been invoked with the matched route")
+	assert.Equal(t, "/openmeter/addons", filteredRoute.Path)
+	assert.NoError(t, gotErr, "validation error hook must not fire when the filter returns false")
+	assert.Equal(t, http.StatusOK, rec.Code, "client response should still be served")
+	assert.Equal(t, `{}`, rec.Body.String(), "client response body should still be served")
+}

api/v3/server/server.go

@@ -2,13 +2,15 @@ package server
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
 
 	"github.com/getkin/kin-openapi/openapi3"
 	"github.com/getkin/kin-openapi/openapi3filter"
+	"github.com/getkin/kin-openapi/routers"
 	"github.com/go-chi/chi/v5"
 	"github.com/samber/lo"
 
@@ -72,6 +74,7 @@ type Config struct {
 	Middlewares         []server.MiddlewareFunc
 	PostAuthMiddlewares []server.MiddlewareFunc
 	Credits             config.CreditsConfiguration
+	ResponseValidation  config.ResponseValidationConfig
 
 	// services
 	AddonService            addon.Service
@@ -384,6 +387,15 @@ func (s *Server) RegisterRoutes(r chi.Router) error {
 			validationMiddleware,
 		}
 
+		if s.ResponseValidation.Mode.Enabled() {
+			middlewares = append(middlewares, oasmiddleware.ValidateResponse(validationRouter, oasmiddleware.ValidateResponseOption{
+				RouteFilterHook: buildResponseValidationRouteFilter(s.ResponseValidation),
+				ResponseValidationErrorHook: func(err error, r *http.Request) {
+					slog.WarnContext(r.Context(), "response validation failed", slog.String("method", r.Method), slog.String("path", r.URL.Path), slog.Any("error", err))
+				},
+			}))
+		}
+
 		postAuthMiddlewares := lo.Map(s.PostAuthMiddlewares, func(mwf server.MiddlewareFunc, _ int) api.MiddlewareFunc {
 			return api.MiddlewareFunc(mwf)
 		})
@@ -399,3 +411,30 @@ func (s *Server) RegisterRoutes(r chi.Router) error {
 
 	return nil
 }
+
+// buildResponseValidationRouteFilter returns a route filter for response validation.
+// In "all" mode the filter is nil (every route is validated). In "unstable" mode only
+// operations marked x-unstable: true in the spec are validated.
+func buildResponseValidationRouteFilter(cfg config.ResponseValidationConfig) func(*routers.Route) bool {
+	if cfg.Mode != config.ResponseValidationModeUnstable {
+		return nil
+	}
+	return func(route *routers.Route) bool {
+		if route.Operation == nil {
+			return false
+		}
+		extVal, ok := route.Operation.Extensions["x-unstable"]
+		if !ok {
+			return false
+		}
+		switch v := extVal.(type) {
+		case json.RawMessage:
+			var b bool
+			return json.Unmarshal(v, &b) == nil && b
+		case bool:
+			return v
+		default:
+			return false
+		}
+	}
+}

app/config/config_test.go

@@ -418,6 +418,9 @@ func TestComplete(t *testing.T) {
 			ReadTimeout:       60 * time.Second,
 			WriteTimeout:      90 * time.Second,
 			IdleTimeout:       120 * time.Second,
+			ResponseValidation: ResponseValidationConfig{
+				Mode: ResponseValidationModeOff,
+			},
 		},
 		ProgressManager: ProgressManagerConfiguration{
 			Enabled:    false,

app/config/server.go

@@ -13,6 +13,37 @@ type ServerConfig struct {
 	ReadTimeout       time.Duration
 	WriteTimeout      time.Duration
 	IdleTimeout       time.Duration
+
+	ResponseValidation ResponseValidationConfig
+}
+
+// ResponseValidationConfig controls optional post-response OpenAPI validation on the v3 API.
+type ResponseValidationConfig struct {
+	Mode ResponseValidationMode
+}
+
+type ResponseValidationMode string
+
+const (
+	// ResponseValidationModeOff disables response validation. This is the default.
+	ResponseValidationModeOff ResponseValidationMode = "off"
+	// ResponseValidationModeUnstable validates only routes marked x-unstable: true in the spec.
+	ResponseValidationModeUnstable ResponseValidationMode = "unstable"
+	// ResponseValidationModeAll validates every route in the v3 spec.
+	ResponseValidationModeAll ResponseValidationMode = "all"
+)
+
+func (m ResponseValidationMode) Enabled() bool {
+	return m != "" && m != ResponseValidationModeOff
+}
+
+func (m ResponseValidationMode) Validate() error {
+	switch m {
+	case "", ResponseValidationModeOff, ResponseValidationModeUnstable, ResponseValidationModeAll:
+		return nil
+	default:
+		return errors.New("invalid response validation mode (allowed: off, unstable, all)")
+	}
 }
 
 func (c ServerConfig) Validate() error {
@@ -34,6 +65,10 @@ func (c ServerConfig) Validate() error {
 		errs = append(errs, errors.New("idleTimeout must be non-negative"))
 	}
 
+	if err := c.ResponseValidation.Mode.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
 	return errors.Join(errs...)
 }
 
@@ -45,4 +80,6 @@ func ConfigureServer(v *viper.Viper, prefixes ...string) {
 	v.SetDefault(prefixer("readTimeout"), 60*time.Second)
 	v.SetDefault(prefixer("writeTimeout"), 90*time.Second)
 	v.SetDefault(prefixer("idleTimeout"), 120*time.Second)
+
+	v.SetDefault(prefixer("responseValidation.mode"), string(ResponseValidationModeOff))
 }

cmd/server/main.go

@@ -192,6 +192,7 @@ func main() {
 		},
 		RouterHooks:         lo.FromPtr(app.RouterHooks),
 		PostAuthMiddlewares: app.PostAuthMiddlewares,
+		ResponseValidation:  conf.Server.ResponseValidation,
 	})
 	if err != nil {
 		logger.Error("failed to create server", "error", err)

config.example.yaml

@@ -33,6 +33,14 @@ server:
   writeTimeout: 90s
   # idleTimeout is the maximum time a keep-alive connection remains idle before being closed.
   idleTimeout: 120s
+  responseValidation:
+    # mode selects which v3 routes have their response bodies validated against the OpenAPI spec.
+    # Violations are logged as warnings; the client response is never affected.
+    # Validation buffers the full response body in memory.
+    #   off      — validation disabled (default)
+    #   unstable — validate only routes marked x-unstable: true in the spec
+    #   all      — validate every v3 route (highest overhead)
+    mode: "off"
 
 #ingest:
 #  kafka:

openmeter/server/server.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/openmeterio/openmeter/api"
 	v3server "github.com/openmeterio/openmeter/api/v3/server"
+	appconfig "github.com/openmeterio/openmeter/app/config"
 	"github.com/openmeterio/openmeter/openmeter/namespace/namespacedriver"
 	"github.com/openmeterio/openmeter/openmeter/portal/authenticator"
 	"github.com/openmeterio/openmeter/openmeter/server/router"
@@ -67,6 +68,7 @@ type Config struct {
 	RouterConfig        router.Config
 	RouterHooks         RouterHooks
 	PostAuthMiddlewares PostAuthMiddlewares
+	ResponseValidation  appconfig.ResponseValidationConfig
 }
 
 func NewServer(config *Config) (*Server, error) {
@@ -136,6 +138,7 @@ func NewServer(config *Config) (*Server, error) {
 		FeatureConnector:        config.RouterConfig.FeatureConnector,
 		Middlewares:             v3Middlewares,
 		PostAuthMiddlewares:     config.PostAuthMiddlewares,
+		ResponseValidation:      config.ResponseValidation,
 	})
 	if err != nil {
 		slog.Error("failed to create v3 API", "error", err)