The httputil.ReverseProxy Trap in Go: Why Director Drops Your HeadersArticle · digest for October 20
45-degree isometric architectural cutaway of a network gateway: a strict filter strips transit headers before forwarding the request to a Go microservice.
Article2 sections≈ 4 min

The httputil.ReverseProxy Trap in Go: Why Director Drops Your Headers

Picture a classic setup: you're building a lightweight API Gateway in Go. The service accepts a client request, validates a JWT token, and forwards the call to an internal microservice. So the backend knows who's authenticated, the proxy attaches an internal header with the user's ID.

For years, developers solved this the exact same way—grabbing the trusty httputil.ReverseProxy from the standard library and wiring up its Director field. But if that pattern is still running in your production stack, there's a serious security flaw lurking in it.

Here's what that familiar, vulnerable pattern looks like:

package main

import (
    "net/http"
    "net/http/httputil"
    "net/url"
)

func NewLegacyProxy(target *url.URL) *httputil.ReverseProxy {
    proxy := httputil.NewSingleHostReverseProxy(target)
    originalDirector := proxy.Director

    proxy.Director = func(req *http.Request) {
        originalDirector(req)
        // Forward the user ID to the internal service
        req.Header.Set("X-App-User", "authorized-user-id")
    }

    return proxy
}

At first glance, what could possibly go wrong? We explicitly set the header right before sending the request. Yet out of nowhere, your downstream service starts receiving empty values and authentication mysteriously breaks.

Anatomy of the Bug: The Sneaky Connection Header

To see why, let's pop the hood on httputil.ReverseProxy and revisit the HTTP specs (RFC 7230 and RFC 9110).

The protocol defines hop-by-hop headers. Fields like Keep-Alive, Upgrade, and Connection only apply to a single network hop, so a proxy is required to strip them before forwarding the request.

Here's the kicker: the standard lets a client list the names of any other headers inside Connection, effectively telling the proxy to treat them as hop-by-hop too!

Now look at the fatal order of operations in the old ReverseProxy:

  1. The proxy calls your Director(req) function, and you add req.Header.Set("X-App-User", "authorized-user-id").
  2. After that, Go's standard library strips hop-by-hop fields: it reads the Connection header, finds the field names listed inside it, and deletes them from the outgoing request.

If an external client sends an incoming request with this header:

GET /api/profile HTTP/1.1
Host: api.example.com
Connection: X-App-User

then Director dutifully sets the user header, and Go's internal logic wipes it out on the very next step! Your backend receives an anonymous request, opening the door to an authentication bypass.

The Safe Approach with Rewrite

Starting in Go 1.20, Director was deprecated and replaced by the Rewrite interface.

With Rewrite, the order is flipped:

  1. The proxy clones the incoming request r.In into the outgoing request r.Out.
  2. All hop-by-hop headers and any fields listed in Connection are stripped from r.Out before your code runs.
  3. Transit headers like Forwarded and X-Forwarded-* are cleared to protect against IP spoofing.
  4. Your Rewrite(r) callback is executed.

Now any header you add to r.Out.Header is guaranteed to make it to the backend:

package main

import (
    "net/http/httputil"
    "net/url"
)

func NewSecureProxy(target *url.URL) *httputil.ReverseProxy {
    return &httputil.ReverseProxy{
        Rewrite: func(r *httputil.ProxyRequest) {
            r.SetURL(target)
            r.Out.Header.Set("X-App-User", "authorized-user-id")
            r.SetXForwarded()
        },
    }
}
Migration Gotchas

Calling r.SetURL(target) rewrites r.Out.Host to the target host. If your backend expects the original host, set r.Out.Host = r.In.Host. And never set both Director and Rewrite at the same time—Go will panic immediately.

Inside Rewrite, the incoming r.In object is read-only. Switching to Rewrite takes just a couple of lines, and it closes the door on silent header stripping for good.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 2