feat(postgres): PROXY protocol support + per-listener proxy_protocol config

[andybons]

What

Adds PROXY protocol support to the Postgres data-plane listener, and reorganizes the PROXY protocol config to be per-listener — mirroring how HAProxy attaches accept-proxy to each bind.

Config (breaking, pre-1.0)

• proxy.proxy_protocol — the HTTP/CONNECT listener (renamed from network.proxy_protocol)
• postgres.proxy_protocol — the Postgres data-plane listener (new)
• network.proxy_protocol — removed, no alias. PROXY protocol is a listener-ingress concern, not network allow/deny policy, so it never belonged under network:. Migration: move the line under proxy:.

Behavior

Both listeners use identical semantics via a shared proxy.WrapProxyProtocolListener helper (deduplicated from the old inline HTTP path): fail-open USE policy (header honored if present; fall back to the raw TCP peer address if absent or on a 10s header-read timeout), and a DEBUG log on malformed headers. On the Postgres plane the advertised address flows into ClientAddr and the run-token-auth log automatically. The PROXY header is consumed before the Postgres SSLRequest and TLS handshake, so interception is unaffected. (go-proxyproto parses both v1 and v2.)

Security: client_ip/client_addr is logging-only on both listeners (auth is the constant-time run token; nothing keys off the advertised address), so a forged header only pollutes logs — enable only when the port is reachable solely through the LB. Documented in the config reference, guide 11, and the observability concept page.

Fixes folded in (surfaced by review)

• Accept no longer blocks on the header parse. WrapProxyProtocolListener's Accept was calling conn.RemoteAddr() unconditionally, triggering the lazy blocking header read on the accept loop — a slow-loris stall of all new connections. Now uses the side-effect-free Raw().RemoteAddr() for proxyproto conns. This was pre-existing in the v0.17.0 HTTP path, so this hardens the HTTP listener too.
• TCP keep-alives survive the wrapper. enableKeepAlive's *net.TCPConn assertion silently failed through the PROXY wrapper (losing keepalives); fixed via a documented underlyingTCPConn unwrap.

Tests

Test-first throughout: Postgres v1 header → ClientAddr = advertised IP (red before wiring), fail-open no-header fallback, disabled-default, HTTP via the new field, the Accept-doesn't-block-on-silent-client regression test, and the keepalive-unwrap test (mutation-checked). Live-verified end-to-end: both listeners, real CA, real handshakes. go test -race ./..., vet, gofmt clean.

Docs

CHANGELOG v0.18.0 (Added: Postgres support; Changed: the breaking rename + per-listener model). Config reference, guide 11 (now covers the Postgres port), observability page, README, and both example configs updated.

[claude]

Claude finished @andybons's task in 2m 49s —— View job

---

Review: PROXY protocol support + per-listener config (#55)

Todo list

• Gather context (PR body, changed files, custom instructions)
• Read key changed files (proxy/proxyproto.go, proxy/postgres.go, config.go, gatekeeper.go)
• Check tests, security implications, race conditions
• Read docs/examples for consistency with the config rename
• Post final summary

Note: this sandbox's go tool required approval I couldn't grant non-interactively, so I reviewed by reading the diff and code paths rather than running go build/go vet/go test -race. If you want CI-equivalent verification from me, allow the go binary in --allowedTools.

Summary

Clean, well-tested change. I traced the full data flow for both listeners and didn't find correctness or security bugs.

proxy/proxyproto.go — WrapProxyProtocolListener is a solid dedup of the old inline HTTP-only logic. The Accept()-doesn't-block fix is real and worth calling out: previously conn.RemoteAddr() on a *proxyproto.Conn triggers the lazy header parse, which blocks until bytes arrive or the 10s ReadHeaderTimeout fires — that would stall the whole accept loop behind one silent client. Reading Raw().RemoteAddr() instead avoids that, and TestWrapProxyProtocolListenerAcceptDoesNotBlockOnSilentClient demonstrates it concretely.

enableKeepAlive unwrap (proxy/postgres.go) — the underlyingTCPConn helper correctly reaches through proxyProtoLogConn.Raw() → proxyproto.Conn.Raw() → *net.TCPConn without touching the header, and TestUnderlyingTCPConnUnwrapsWrappedListenerConn verifies the type assertion would otherwise silently fail (no panic, just a no-op) through the wrapper stack — a real, easy-to-miss regression this catches.

Postgres wiring order (gatekeeper.go) — the PROXY header is consumed by the wrapper before PostgresServer.StartListener ever sees a connection, so it's stripped ahead of SSLRequest/TLS as claimed. ClientAddr is read via clientConn.RemoteAddr() only after the handshake has already forced at least one Read() on the wrapped conn (postgres.go:719,779), so by the time it's called the lazy header parse has already resolved — no blocking risk there, consistent with the design.

Config rename — network.proxy_protocol → proxy.proxy_protocol / postgres.proxy_protocol is clean: no dangling references, config_test.go covers both new fields and the absent-defaults-to-false case, and the CHANGELOG/README/docs/examples are all updated consistently (checked docs/content/reference/02-config-file.md, guide 11, the observability concept page, and both example YAMLs — no stale network.proxy_protocol mentions found in prose or config).

Security — the doc language correctly frames client_ip/client_addr as logging-only and forgeable by any peer that can reach the listener directly; nothing in the auth path (authenticate, constant-time run-token compare) keys off the advertised address, so this holds.

Minor, non-blocking observation: the malformed-header detection in proxyProtoLogConn.Read (proxy/proxyproto.go) matches on strings.HasPrefix(err.Error(), "proxyproto:") — a string-matched error rather than a sentinel/typed error from go-proxyproto. This is carried over unchanged from the pre-existing gatekeeper.go implementation (not introduced by this PR), so I'm not flagging it as a blocking issue, just noting it as pre-existing fragility if go-proxyproto's error message format ever changes upstream.

No security, race, or logic issues found. Test coverage is genuinely test-first (the PR description's failing-red-first claims check out against the actual test names/assertions, e.g. client_addr before/after wiring, fail-open, disabled-default, the Accept-blocking regression, and the keepalive-unwrap test). Docs and examples are fully in sync with the breaking rename.