behind-proxy

command
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 6 Imported by: 0

README

behind-proxy

Production-shaped configuration for running behind a TLS-terminating load balancer, and a /v1/whoami route that makes the one setting people get wrong visible in a single response.

This server speaks HTTP/2 cleartext. There is no TLS here and no way to add it, so something in front must terminate it. Everything below assumes that something exists; without it, none of this configuration matters because the traffic is already in the clear.

A note on the logger

Like ../readiness, this example logs through github.com/zionmedianetwork/logam and hands logam.NewLogger(...) straight to NewHTTP — no adapter, no wrapper. NewHTTP asks for a server.Logger, which is Infow, Warnw and Errorw and nothing else; logam.Logger has those three among its seventeen and satisfies the interface structurally.

logam is one option among several, not a requirement of this package. It is used here because this is the deployment-shaped example and it is what these services run in production. A consumer without it writes the three-line log/slog adapter shown in ../minimal and depends on nothing but the standard library — the startup warnings below, which are ordinary Warnw calls, come out the same either way.

What it demonstrates

  • HTTP_REAL_IP_SOURCE=xff with HTTP_TRUSTED_PROXIES, and what changes when you set them.
  • A named HTTP_ALLLOWED_ORIGINS (three L's — the struct field is misspelled and the variable inherits it). Unset, no cross-origin access is allowed at all; the browser clients a deployment serves have to be named.
  • HTTP_DEBUG left off, so handler errors are not narrated to callers.
  • A body limit sized for an API rather than for uploads.
  • Reading the resolved *server.HttpConfig back at startup and warning about the settings that are still at development defaults. That is worth doing in a real service: these particular defaults fail open and are otherwise invisible until an audit needs them.

Run it

Default mode — HTTP_REAL_IP_SOURCE unset, so forwarding headers are ignored:

HTTP_BIND_ADDRESS=127.0.0.1:8080 go run ./examples/behind-proxy
WARN  client address is the peer address and forwarding headers are ignored  {"variable": "HTTP_REAL_IP_SOURCE", ...}

(There is no CORS warning here any more: with HTTP_ALLLOWED_ORIGINS unset the server allows no cross-origin access, so there is nothing to warn about. Set it to * and the cors allows every origin line comes back.)

Deployment mode — the load balancer relays the client address and is trusted to:

HTTP_BIND_ADDRESS=127.0.0.1:8080 \
HTTP_REAL_IP_SOURCE=xff \
HTTP_TRUSTED_PROXIES=127.0.0.0/8,10.4.0.0/16 \
HTTP_ALLLOWED_ORIGINS=https://zion.example,https://admin.zion.example \
HTTP_MAX_BODY_LIMIT=2M \
HTTP_REQUEST_TIMEOUT=10s \
go run ./examples/behind-proxy

(127.0.0.0/8 is in the list only so that curl from your own machine plays the part of the proxy. A real deployment lists the load balancer's ranges and nothing else.)

The two curl invocations

The same spoofed header, against the two configurations.

Default (peer) — the header is ignored:

$ curl -s -H 'X-Forwarded-For: 203.0.113.9' -H 'X-Real-IP: 203.0.113.9' \
       http://127.0.0.1:8080/v1/whoami
{"data":{"client_ip":"127.0.0.1","peer":"127.0.0.1:59984","x_forwarded_for":"203.0.113.9","x_real_ip":"203.0.113.9","proto":"HTTP/1.1"}}

client_ip is the address that actually opened the connection. The caller asked to be 203.0.113.9 and was not believed. Anything built on c.RealIP() — the access log, an allowlist, a rate limiter — sees the truth.

xff with the caller's range trusted — the header is honoured:

$ curl -s -H 'X-Forwarded-For: 203.0.113.9' http://127.0.0.1:8080/v1/whoami
{"data":{"client_ip":"203.0.113.9","peer":"127.0.0.1:59987","x_forwarded_for":"203.0.113.9","x_real_ip":"","proto":"HTTP/1.1"}}

client_ip is now the address from the header, because the hop that sent it (127.0.0.1) is in HTTP_TRUSTED_PROXIES. With no header at all it falls back to the peer:

$ curl -s http://127.0.0.1:8080/v1/whoami
{"data":{"client_ip":"127.0.0.1","peer":"127.0.0.1:59988","x_forwarded_for":"","x_real_ip":"","proto":"HTTP/1.1"}}

Drop 127.0.0.0/8 from HTTP_TRUSTED_PROXIES and the first invocation goes back to reporting 127.0.0.1: an untrusted hop's header is not read.

X-Real-IP is never consulted in either mode.

Three things that surprise people

The trusted list is exhaustive, not additive. Left empty, xff trusts loopback and the private ranges — the usual sidecar or cluster-internal ingress case. The moment you name a range, that implicit trust stands down: after HTTP_TRUSTED_PROXIES=10.4.0.0/16, a header relayed from 127.0.0.1 is no longer believed. Naming the load balancer is taken as a statement of where the proxies are.

Trusted proxies with the wrong source is a startup error, not a no-op:

$ HTTP_TRUSTED_PROXIES=10.4.0.0/16 go run ./examples/behind-proxy
ERROR  http server stopped  {"error": "build http server: trusted proxies are configured but the real ip source is \"peer\", which never reads forwarding headers: set HTTP_REAL_IP_SOURCE=xff or drop HTTP_TRUSTED_PROXIES"}
exit status 1

The ranges would never be consulted, and a silent no-op leaves you believing a proxy is trusted when nothing reads its header.

xff is only safe if the proxy overwrites the header. Echo walks X-Forwarded-For from the right and stops at the first hop that is not trusted, so a client appending its own entry cannot win — but a proxy that appends to rather than replaces an incoming header still hands you a chain whose left end is attacker-controlled. Configure the proxy to overwrite.

CORS

With HTTP_ALLLOWED_ORIGINS unset, nothing is allowed cross-origin. Every preflight is answered without the header a browser needs, including one from your own front end — which is the point: a deployment that has not named its browser clients has not been asked to trust anybody.

With HTTP_ALLLOWED_ORIGINS=https://zion.example, a preflight from that origin is answered with the headers a browser needs, and one from anywhere else is not:

$ curl -s -i -X OPTIONS -H 'Origin: https://zion.example' \
       -H 'Access-Control-Request-Method: GET' http://127.0.0.1:8080/v1/whoami \
  | grep -iE '^HTTP|access-control-'
HTTP/1.1 204 No Content
Access-Control-Allow-Headers: Accept,Authorization,Content-Type,X-Request-Id
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE
Access-Control-Allow-Origin: https://zion.example
Access-Control-Max-Age: 3600

$ curl -s -i -X OPTIONS -H 'Origin: https://evil.example' \
       -H 'Access-Control-Request-Method: GET' http://127.0.0.1:8080/v1/whoami \
  | grep -iE '^HTTP|access-control-'
HTTP/1.1 204 No Content

Note the second one is still a 204 — CORS is enforced by the browser refusing the response, not by the server rejecting the request. The absence of the Access-Control-Allow-Origin header is the enforcement. curl does not care, which is exactly why testing CORS with curl misleads people.

Access-Control-Max-Age: 3600 is the preflight cache: for the next hour that browser skips the OPTIONS round trip for this route. HTTP_CORS_MAX_AGE moves it, and HTTP_CORS_MAX_AGE=0 removes the header entirely.

The request headers a preflight allows come from HTTP_ALLOWED_HEADERS — one L, unlike the origins variable — and default to the four above. The allowed methods are fixed at GET, POST, PUT, PATCH, DELETE and are not configurable.

Security headers

Every response carries them, without any variable being set:

$ curl -s -i http://127.0.0.1:8080/v1/whoami | grep -iE 'x-content-type|x-frame|referrer|x-xss'
X-Xss-Protection: 0
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Referrer-Policy: strict-origin-when-cross-origin

Strict-Transport-Security is not among them. This process serves h2c in the clear, so whether the origin it is reached at is HTTPS everywhere is a fact about the load balancer in front, not about this server. Set HTTP_HSTS_MAX_AGE when it is, and the header is sent for requests the proxy marked with X-Forwarded-Proto: https.

Documentation

Overview

Command behind-proxy is a production-shaped configuration for running behind a TLS-terminating load balancer, and a route that lets you see the one setting people get wrong: where c.RealIP() reads the client address from.

With HTTP_REAL_IP_SOURCE unset (the default, "peer") a client can put anything it likes in X-Forwarded-For and the server ignores it. With "xff" and a trusted proxy list, the header is believed — but only from a hop in that list. Naming proxies makes the list exhaustive: loopback and the private ranges stop being trusted implicitly.

Run it in the default, header-ignoring mode:

HTTP_BIND_ADDRESS=:8080 go run ./examples/behind-proxy

Or in the mode a deployment behind an in-cluster load balancer would use:

HTTP_BIND_ADDRESS=:8080 \
HTTP_REAL_IP_SOURCE=xff \
HTTP_TRUSTED_PROXIES=127.0.0.0/8,10.4.0.0/16 \
HTTP_ALLLOWED_ORIGINS=https://zion.example,https://admin.zion.example \
HTTP_MAX_BODY_LIMIT=2M \
HTTP_REQUEST_TIMEOUT=10s \
go run ./examples/behind-proxy

See the README next to this file for the two curl invocations that show the difference.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL