update

proxy_pass/forwarded.conf

@@ -1,11 +1,24 @@
+# Preserve the original Host header, including a non-default port, because many
+# upstream frameworks use it when generating absolute URLs.
 proxy_set_header	Host	$http_host;
+
+# Keep the de-facto standard X-Forwarded-* headers and the older Scheme header
+# together. Some upstreams still read Scheme while newer ones prefer
+# X-Forwarded-Proto.
 proxy_set_header	Scheme	$scheme;
 proxy_set_header	X-Real-IP	$remote_addr;
 proxy_set_header	X-Forwarded-Host	$host;
 proxy_set_header	X-Forwarded-Proto	$scheme;
+
+# Preserve WebDAV and object-storage style Destination requests when proxying.
 proxy_set_header	Destination	$http_destination;
 proxy_set_header	X-Forwarded-Server	$host;
 proxy_set_header	X-Forwarded-For	$proxy_add_x_forwarded_for;
+
+# Leave this legacy hint in place because some older applications and middleware
+# still branch on it when they know they are behind nginx.
 proxy_set_header	X-NginX-Proxy	true;
 
-proxy_redirect	off;
+# Avoid rewriting Location headers implicitly. Callers can add explicit
+# proxy_redirect rules locally if an upstream really needs them.
+proxy_redirect	off;

proxy_pass/hide-powered-by.conf

@@ -1 +1,4 @@
+# Keep this separate from forwarded.conf so callers can decide whether hiding
+# upstream branding is worth potentially masking framework details during
+# debugging.
 proxy_hide_header X-Powered-By;

proxy_pass/https-upstream.conf

@@ -0,0 +1,6 @@
+# Enable SNI when proxy_pass targets an HTTPS origin by hostname. Without this,
+# multi-tenant upstreams can return the wrong certificate or application.
+proxy_ssl_server_name on;
+
+# Do not force proxy_ssl_name or proxy_ssl_verify here. Those depend on whether
+# the caller proxies to a hostname, an upstream block, or a private CA.

proxy_pass/streaming.conf

@@ -0,0 +1,16 @@
+# Use HTTP/1.1 only in explicit streaming locations. Keeping this out of the
+# default forwarded.conf avoids changing connection semantics for every proxy.
+proxy_http_version 1.1;
+
+# Disable buffering so SSE, token streams, and other incremental responses can
+# flush chunks immediately instead of waiting for nginx to coalesce them.
+proxy_buffering off;
+
+# Disable request buffering as well for duplex APIs and streaming uploads. Put
+# this behind an opt-in snippet because large upload endpoints may want the
+# default buffered behavior instead.
+proxy_request_buffering off;
+
+# gzip can delay flushes by collecting more bytes before compression. Turn it
+# off in explicit streaming locations even if gzip is enabled globally.
+gzip off;

proxy_pass/timeout-300.conf

@@ -1,4 +1,9 @@
+# Keep this as an opt-in long-request profile instead of raising timeouts in
+# forwarded.conf for every proxy location.
 proxy_connect_timeout	300;
 proxy_send_timeout	300;
 proxy_read_timeout	300;
-send_timeout	300;
+
+# send_timeout covers the downstream client socket too, so long-lived responses
+# do not inherit a shorter default than the upstream leg.
+send_timeout	300;

proxy_pass/websocket.conf

@@ -1,3 +1,8 @@
+# nginx defaults to proxying with HTTP/1.0. Websocket upgrade requires 1.1, so
+# keep that here instead of in the generic forwarded.conf snippet.
 proxy_http_version	1.1;
 proxy_set_header	Upgrade	$http_upgrade;
-proxy_set_header	Connection	$connection_upgrade;
+
+# Use the mapped value from http/websocket-map.conf so non-upgrade requests can
+# still close cleanly instead of always advertising "Connection: upgrade".
+proxy_set_header	Connection	$connection_upgrade;