HTTP Server and Middleware#

Flipt's HTTP layer is constructed in internal/cmd/http.go via NewHTTPServer. It wraps Go's net/http.Server with ReadTimeout: 10s, WriteTimeout: 30s, and MaxHeaderBytes: 1MB 1, using Chi v5 as the router. Each logical API surface gets its own gRPC-gateway runtime.ServeMux that proxies requests to Flipt's in-process gRPC services.

Route Structure#

Each API surface gets its own runtime.ServeMux mounted at a distinct path prefix 2:

All API routes (except /metrics, /health, and the UI) are grouped under a sub-router that applies removeTrailingSlash and optional OTel tracing/audit middleware before mounting 3. CSRF protection (http.NewCrossOriginProtection) is conditionally applied to this same group when a session CSRF key is configured 4.

Global Middleware Chain#

Applied in registration order to the root Chi router 5:

1. CORS (go-chi/cors) — conditional on cfg.Cors.Enabled 6
2. middleware.RequestID — injects a request ID header 7
3. middleware.RealIP — rewrites r.RemoteAddr from X-Real-IP / X-Forwarded-For 8
4. Pretty-print handler — sets Accept: application/json+pretty when ?pretty is present in the query string 9
5. middleware.Compress — gzip compression at default level 10
6. http_middleware.HandleNoBodyResponse — suppresses response body for 204/304 11
7. middleware.Recoverer — panic recovery 12

⚠️ No UTF-8 path validation exists in this chain. See Known Issue: UTF-8 Path Validation Gap below.

Gateway Construction (internal/gateway/gateway.go)#

NewGatewayServeMux wraps runtime.NewServeMux and applies shared options once (via sync.Once):

• V1toV2MarshallerAdapter — backwards-compat marshaller that handles null map values rejected by the proto v2 marshaller 13 (see issue #664)
• application/json+pretty marshaller — indented JSON output, activated by the ?pretty query param 14
• Trace header forwarding — propagates Traceparent, Tracestate, and Baggage into gRPC metadata via a custom IncomingHeaderMatcher 15

Per-mux options are merged on top of these shared options when creating specific gateway instances.

Custom Error Handlers#

OFREP (/ofrep)#

The OFREP ServeMux is initialized with ofrep_middleware.ErrorHandler, which translates gRPC status codes into the OpenFeature Remote Evaluation Protocol error schema 16:

• codes.NotFound → FLAG_NOT_FOUND
• codes.InvalidArgument → INVALID_CONTEXT
• all others → GENERAL

The error body includes a key field populated from gRPC status details when present, and an errorDetails string from the status message 17.

Auth (/auth/v1)#

authenticationHTTPMount configures a dedicated ServeMux with authmiddleware.ErrorHandler. On a codes.Unauthenticated response, if a token cookie was present in the request, the error handler clears all session cookies (flipt_client_state and the token cookie) before delegating to the default gRPC-gateway error handler. This prevents user agents from re-sending an invalid session token.

The auth sub-router also wraps in authmiddleware.Handler, which intercepts PUT /auth/v1/self/expire to clear cookies on explicit logout.

Known Issue: UTF-8 Path Validation Gap#

Affects: Confirmed v2.10.0; likely all v2 releases 18

Request paths containing percent-encoded bytes that are invalid UTF-8 (e.g., /%c0, /%ff, /%ed%a0%80) return 500 Internal Server Error with no log output at any log level 18.

Valid-UTF-8 paths like /caf%c3%a9 correctly return 404 for unknown routes. The divergence occurs because 18:

1. Go's net/http percent-decodes the raw path, producing a non-UTF-8 byte sequence in r.URL.Path.
2. The middleware chain passes the request through untouched — no middleware validates path encoding.
3. grpc-gateway's ServeMux or Go's internal routing panics/errors on the invalid string, producing a 500 via middleware.Recoverer without logging.

Proposed fix: Add a middleware after RealIP that calls utf8.ValidString(r.URL.Path) and returns 400 Bad Request for invalid paths 18. There is no current workaround short of a WAF or reverse proxy that rejects malformed paths upstream.

Tracked in: GitHub Issue #6337