Forwarding to Upstreams

## What the constructor actually builds `httputil.NewSingleHostReverseProxy(target *url.URL) *ReverseProxy` is a convenience wrapper. `httputil.ReverseProxy` is a struct with hooks; the constructor fills in exactly one of them — `Director`, the function that turns the inbound request into the outbound one. Everything else on the struct (`Transport`, `ModifyResponse`, `ErrorHandler`, `ErrorLog`) stays at its zero value, and you set what you need afterwards. The generated Director does three things to the request that will be sent upstream: - sets `URL.Scheme` to the target's scheme (`http` or `https`), - sets `URL.Host` to the target's host and port, - joins the target's path in front of the request's path, so a target of `http://up:9000/base` and an inbound `/dir` produce `/base/dir`. It does **not** touch `req.Host`. That matters: in Go's HTTP client the `Host` field, when non-empty, overrides the host taken from the URL. So the upstream receives the Host name the browser asked for, not the target's. If the upstream does virtual hosting on its own name you have to change that yourself. ## Serving it `(*ReverseProxy).ServeHTTP` gives the type an `http.Handler` implementation, so there is nothing special about wiring it up: ```go mux := http.NewServeMux() mux.Handle("/api/", proxy) ``` One proxy value serves all requests concurrently — it holds no per-request state, so build it once at start-up rather than per request. Because it is a plain handler, logging, authentication or rate-limiting middleware wraps it exactly the way it wraps any other handler, and the proxy simply becomes the innermost one. Note what the mux does *not* do for you: `mux.Handle("/api/", proxy)` matches on the prefix but does not remove it, so the upstream receives `/api/users`, not `/users`. If you want it removed, wrap with `http.StripPrefix("/api", proxy)`. ## What ServeHTTP does around your Director The request the Director mutates is a clone, not the caller's request. Around the hook, `ServeHTTP`: 1. clones the inbound request with the request's context, so a client disconnect cancels the upstream call; 2. runs the Director; 3. removes hop-by-hop headers — the per-connection ones such as `Connection`, `Keep-Alive`, `Transfer-Encoding` and `Upgrade`, plus any header named in the `Connection` header — so they do not leak to the next hop; 4. appends the client's IP address, taken from `RemoteAddr`, to `X-Forwarded-For`; 5. performs the round trip; 6. removes hop-by-hop headers from the response, copies the remaining headers and status to the `http.ResponseWriter`, then streams the body back. If the round trip fails, there is no response to copy, and the proxy writes `502 Bad Gateway` and logs the error. ## The mental model to carry away A Go reverse proxy is not a TCP tunnel. It parses the client's request, constructs a **new** HTTP request of its own, and speaks HTTP to the upstream as a client — which is why the upstream sees whatever headers your hook left on the outbound request and nothing more. That framing explains all the follow-on questions: why the Host header is a decision you own, why the client's address has to be forwarded in a header, and why anything per-connection is dropped at the boundary. ## Minimal shape ```go target, err := url.Parse("http://127.0.0.1:9001") if err != nil { log.Fatal(err) } proxy := httputil.NewSingleHostReverseProxy(target) http.Handle("/api/", proxy) ``` That is a working reverse proxy in five lines, and every later refinement — rewriting the path, deciding what forwarding headers to trust, turning an unreachable upstream into a nicer status — is a field you set on the same struct.