Proxy · XB Field Notes

A microcache serves fresh entries briefly and coalesces misses explicitly

Sun, 12 Mar 2028 00:00:00 +0000

A microcache keeps reusable responses for a short freshness lifetime, often a few seconds. Requests for the same selected representation can reuse a fresh entry during that window. The response might lag a new origin update, but it is not HTTP-stale merely because it came from a cache. Expiration, permission to serve stale content, and concurrent cache filling are separate policies.

When it breaks

A short TTL does not make a shared response safe for every user. If personalized requests read or populate a generic entry, one user’s representation can be served in another context. proxy_cache_bypass prevents reading from cache under its conditions; proxy_no_cache prevents saving the response. Using only one side can leave the other path inconsistent with the intended privacy boundary.

The cache key also defines which requests share a response. Ignoring a meaningful query or host dimension can merge different representations. Including arbitrary varying data can instead destroy reuse. The fixture below uses one backend authority and preserves the complete request URI, including arguments. A service varying by tenant, language, or other inputs must establish its own representation identity.

Caching alone does not guarantee one origin request during a cold burst. Several requests can miss the same entry before any response is stored. proxy_cache_lock coordinates filling a new entry, with finite timeout and age controls. That lock is not the TTL, and a brief freshness lifetime does not implicitly turn lock behavior on.

Check it quickly

Save the script as check-microcache.py and run it with Python, Docker, and the pinned images. The recorded environment used nginx 1.28.0 on Linux arm64. A disposable backend reports per-path request counts, and nginx uses a two-second validity setting with explicit cookie and authorization bypass conditions. The listener is restricted to host loopback:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
from concurrent.futures import ThreadPoolExecutor
import threading
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from urllib.parse import urlsplit,parse_qs
import json,threading
lock=threading.Lock();counts={};gates={'/lock':threading.Event(),'/nolock':threading.Event()}
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path)
 if parsed.path=='/control/state':
 with lock:data=dict(counts)
 elif parsed.path=='/control/release':
 gates[parse_qs(parsed.query)['path'][0]].set();data={'released':True}
 else:
 with lock:counts[self.path]=counts.get(self.path,0)+1;count=counts[self.path]
 if parsed.path in gates:assert gates[parsed.path].wait(15)
 data={'path':self.path,'count':count,'cookie':self.headers.get('Cookie'),'authorization_present':bool(self.headers.get('Authorization'))}
 body=json.dumps(data,sort_keys=True).encode();self.send_response(200)
 if parsed.path=='/cookie':self.send_header('Set-Cookie','fixture=public-example; Path=/')
 if parsed.path=='/private':self.send_header('Cache-Control','private')
 if parsed.path=='/no-store':self.send_header('Cache-Control','no-store')
 self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
extra='''
proxy_cache_path /tmp/cache levels=1:2 keys_zone=pages:1m inactive=30s max_size=10m;
map $http_cookie $skip_cookie { default 1; "" 0; }
map $http_authorization $skip_auth { default 1; "" 0; }
proxy_cache pages; proxy_cache_key "$scheme|$proxy_host|$request_uri"; proxy_cache_valid 200 2s;
proxy_cache_bypass $skip_cookie $skip_auth; proxy_no_cache $skip_cookie $skip_auth;
proxy_cache_lock on; proxy_cache_lock_timeout 5s; proxy_cache_lock_age 5s;
add_header X-Cache $upstream_cache_status always;
'''
locations='''
location /control/ { proxy_cache off; proxy_pass http://backend:8081; }
location = /nolock { proxy_cache_lock off; proxy_pass http://backend:8081; }
location / { proxy_pass http://backend:8081; }
'''
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path,headers=None):
 status,h,b=request(path,headers=headers);assert status==200;return h.get('x-cache'),json.loads(b)
 results={}
 first=get('/item?x=1');second=get('/item?x=1');assert first[0]=='MISS' and second==('HIT',first[1])
 other=get('/item?x=2');assert other[0]=='MISS' and other[1]['path']!=first[1]['path']
 results['fresh']=[first[0],second[0]];results['different_query']=other[0]
 for name,headers in [('cookie',{'Cookie':'session=public-fixture'}),('authorization',{'Authorization':'Bearer public-fixture'})]:
 private=get('/item?x=1',headers);assert private[0]=='BYPASS' and private[1]!=first[1]
 assert get('/item?x=1')==('HIT',first[1])
 new='/new-'+name;assert get(new,headers)[0]=='BYPASS'
 public=get(new);assert public[0]=='MISS' and public[1]['cookie'] is None and not public[1]['authorization_present']
 results[name]={'warm_key':'BYPASS','public_after_private_miss':public[0]}
 for path in ['/cookie','private','no-store']:
 path='/'+path.lstrip('/');a=get(path);b=get(path)
 assert a[0]==b[0]=='MISS' and a[1]['count']==1 and b[1]['count']==2
 results[path]=[a[0],b[0]]
 deadline=time.monotonic()+6
 while time.monotonic()<deadline:
 value=get('/item?x=2')
 if value[0]=='EXPIRED':break
 assert value[0]=='HIT';time.sleep(.15)
 else:raise AssertionError('TTL did not expire')
 assert value[1]['count']==2;results['after_ttl']={'status':value[0],'count':value[1]['count']}
 for path,number,origin_count in [('/lock',6,1),('/nolock',4,4)]:
 barrier=threading.Barrier(number+1)
 def client():barrier.wait();return get(path)
 with ThreadPoolExecutor(max_workers=number) as pool:
 futures=[pool.submit(client) for _ in range(number)];barrier.wait()
 wait(lambda:get('/control/state')[1].get(path)==origin_count)
 time.sleep(.3);before=get('/control/state')[1][path]
 assert before==origin_count and not any(f.done() for f in futures)
 get('/control/release?path='+path);responses=[f.result(timeout=10) for f in futures]
 assert get('/control/state')[1][path]==origin_count
 statuses=sorted(r[0] for r in responses)
 if path=='/lock':assert statuses==['HIT']*5+['MISS'] and all(r[1]==responses[0][1] for r in responses)
 else:assert statuses==['MISS']*4
 results[path]={'origin_requests_while_held':before,'cache_statuses':statuses}
 print(json.dumps(results,sort_keys=True))

The first public request to /item?x=1 reports MISS, and the next reports HIT with the same backend result. /item?x=2 has its own MISS and distinct path in the response. Polling that second entry eventually produces EXPIRED and a backend count of two. This observes actual expiration using the server’s clock; it does not assume an exact subsecond transition time.

Requests carrying the example session cookie or authorization marker report BYPASS even when a public entry is already warm. A later public request still returns the original public HIT. A second control first visits an unused key with those headers, then visits it publicly: the public request is MISS, proving that the preceding private-context response did not populate a reusable entry.

Backend responses containing Set-Cookie, Cache-Control: private, or Cache-Control: no-store each produce two successive MISS results and increasing origin counts. The configuration does not ignore those response controls. This distinguishes client-side bypass policy from origin-provided storage restrictions; the short TTL is not used as an excuse to override either privacy signal.

For a cold locked entry, six clients start together while the backend deliberately withholds the response. The backend sees one request before release; afterward, one client reports MISS and five report HIT with the same result. For a separate entry with the lock disabled, four held clients create four origin requests and all report MISS. The gate makes overlapping misses directly observable.

Choose freshness and overload behavior separately

The two-second setting applies to eligible 200 responses in this experiment. Relevant origin cache headers can take priority over configured validity. Decide which responses are shareable before selecting the lifetime, and keep the cache key aligned with the inputs that actually change their content. A high hit ratio is not evidence that the selected representation was correct.

Lock waiters exchange extra waiting for reduced origin work. This fixture releases the origin within the configured lock limits; it does not establish a permanent single-request guarantee when those limits expire or a backend fails. Review lock timeout, lock age, and any stale-serving policy together with the service’s acceptable latency and failure behavior.

Observe cache status alongside origin counts and response identity. MISS means the requested representation was not served as a cache hit, while BYPASS identifies the explicit read exclusion shown here. Fresh HIT, EXPIRED refill, and intentionally stale service should not be collapsed into one “cached” result. Their different effects on correctness and backend load are the reason to measure them separately.

Sources

nginx proxy module, cache validity, cache locks, bypass, no-cache, and response header controls, checked 2026-09-12.
nginx content caching guide, cache keys, status observation, and caching behavior, checked 2026-09-12.
RFC 9111 HTTP Caching, fresh versus stale responses and private/no-store directives, checked 2026-09-12.

The CONNECT method opens a raw tunnel

Mon, 13 Dec 2027 00:00:00 +0000

CONNECT asks a proxy to establish a tunnel; it does not make the proxy disappear from the data path. After admission, the proxy still forwards bytes in both directions and owns sockets, buffers, and failure handling. CONNECT itself provides no encryption: HTTPS adds a separately verified TLS session through that tunnel.

Switch protocols at the right boundary

An HTTP/1.1 CONNECT target is an authority such as server.example:443, not an ordinary path or a full HTTPS URL. The port is explicit. A successful 2xx response switches to tunnel mode immediately after its header section. A non-success response leaves the tunnel unestablished.

A successful CONNECT response must not include Content-Length or Transfer-Encoding. Subsequent tunnel bytes are not a length-delimited HTTP response body. This distinction matters when writing a relay: bytes already buffered by the HTTP parser belong to the tunnel and must not be discarded.

The client can then negotiate TLS with the destination through the relay. A proxy’s 200 only confirms tunnel admission; it does not validate the destination certificate or prove that an application request succeeded. A client must still check trust, hostname, and the application response. TLS interception is a different deployment, requiring the client to trust an intermediary that terminates TLS.

Opaque content still consumes resources

A blind relay need not interpret encrypted application content, but it still observes connection targets, byte volumes, timing, and closure. It can enforce connection budgets, timeouts, traffic limits, and revocation of admission. It does not lose all operational control merely because it cannot read the HTTP messages inside TLS.

Authenticate callers and constrain destinations in a real forward proxy. Arbitrary host and port access can expose internal services or enable misuse of unrelated protocols. Hostname policy also needs address-resolution policy; validating a name is not equivalent to validating the IP address ultimately dialed. The local exercise avoids that issue by permitting only one already-known loopback address and port.

When it breaks

A relay can return 200 before an upstream connection actually exists, discard parser-buffered bytes, or close the opposite direction before pending data is forwarded. These failures can appear as mysterious TLS errors even when certificate configuration is correct. Distinguish admission failure, tunnel transport failure, TLS identity failure, and origin HTTP failure.

Hijacking a Go HTTP/1.1 connection transfers lifecycle ownership to the handler. The normal HTTP server no longer manages that connection, and its request context is not a substitute for tunnel cleanup. Normal server shutdown does not close hijacked connections; production shutdown needs to track and drain or close them explicitly. Handle both copy directions and their deadlines. A fixed absolute deadline is a total lifetime cap, not an idle timeout that refreshes with traffic.

Check it quickly

Save this as connect_probe.go and run go run connect_probe.go with Go 1.23 or newer. The fixture creates a loopback HTTP/1.1 proxy and a TLS 1.3 origin. Only the origin’s exact authority is permitted. The client trusts its test certificate without disabling verification or changing the system trust store.

package main

import (
 "context"
 "crypto/tls"
 "crypto/x509"
 "errors"
 "fmt"
 "io"
 "log"
 "net"
 "net/http"
 "net/http/httptest"
 "net/url"
 "runtime"
 "sync/atomic"
 "time"
)

func must(err error) {
 if err != nil {
 panic(err)
 }
}

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func main() {
 var handled, admitted, denied, connectStatus atomic.Int64
 origin := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 check(r.TLS != nil && r.TLS.Version == tls.VersionTLS13, "origin requires TLS 1.3")
 fmt.Fprint(w, "through the tunnel")
 }))
 origin.Config.ErrorLog = log.New(io.Discard, "", 0) // Expected wrong-name handshake failure.
 origin.TLS = &tls.Config{MinVersion: tls.VersionTLS13, MaxVersion: tls.VersionTLS13}
 origin.StartTLS()
 defer origin.Close()
 target, err := url.Parse(origin.URL)
 must(err)
 relayed := make(chan [2]int64, 3)
 proxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 if r.Method != http.MethodConnect {
 http.Error(w, "CONNECT required", http.StatusMethodNotAllowed)
 return
 }
 if r.Host != target.Host || r.URL.Host != target.Host {
 denied.Add(1)
 http.Error(w, "target denied", http.StatusForbidden)
 return
 }
 upstream, err := net.DialTimeout("tcp", target.Host, time.Second)
 must(err)
 defer upstream.Close()
 downstream, buffered, err := w.(http.Hijacker).Hijack()
 must(err)
 defer downstream.Close()
 admitted.Add(1)
 deadline := time.Now().Add(3 * time.Second)
 must(upstream.SetDeadline(deadline))
 must(downstream.SetDeadline(deadline))
 _, err = buffered.WriteString("HTTP/1.1 200 Connection Established\r\n\r\n")
 must(err)
 must(buffered.Flush())
 upDone := make(chan int64, 1)
 go func() {
 count, _ := io.Copy(upstream, buffered) // Preserve already-buffered tunnel bytes.
 _ = upstream.(*net.TCPConn).CloseWrite()
 upDone <- count
 }()
 count, _ := io.Copy(downstream, upstream)
 _ = downstream.(*net.TCPConn).CloseWrite()
 relayed <- [2]int64{<-upDone, count}
 }))
 defer proxy.Close()
 proxyURL, err := url.Parse(proxy.URL)
 must(err)
 config := origin.Client().Transport.(*http.Transport).TLSClientConfig.Clone()
 check(!config.InsecureSkipVerify, "certificate verification must stay enabled")
 transport := &http.Transport{
 Proxy: http.ProxyURL(proxyURL), TLSClientConfig: config, DisableKeepAlives: true,
 OnProxyConnectResponse: func(_ context.Context, _ *url.URL, _ *http.Request, response *http.Response) error {
 connectStatus.Store(int64(response.StatusCode))
 if response.StatusCode == 200 {
 check(response.Header.Get("Content-Length") == "" && response.Header.Get("Transfer-Encoding") == "", "successful CONNECT must not frame a body")
 }
 return nil
 },
 }
 defer transport.CloseIdleConnections()
 get := func(tr *http.Transport, address string) (*http.Response, error) {
 return (&http.Client{Transport: tr, Timeout: 2 * time.Second}).Get(address)
 }
 success := func(label string) {
 response, err := get(transport, origin.URL)
 must(err)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.StatusCode == 200 && string(body) == "through the tunnel", "wrong origin response")
 check(connectStatus.Load() == 200 && len(response.TLS.VerifiedChains) > 0, "CONNECT and verified TLS required")
 fmt.Println(label, "CONNECT=200; verified origin response")
 }
 success("allowed")
 response, err := get(transport, "https://denied.invalid:443/")
 check(err != nil && response == nil && connectStatus.Load() == 403, "proxy must reject the target")
 check(denied.Load() == 1 && admitted.Load() == 1 && handled.Load() == 1, "denial must not open an upstream tunnel")
 fmt.Println("denied CONNECT=403; no upstream admission")

 wrong := transport.Clone()
 wrong.TLSClientConfig = config.Clone()
 wrong.TLSClientConfig.ServerName = "wrong.invalid"
 defer wrong.CloseIdleConnections()
 response, err = get(wrong, origin.URL)
 var hostnameError x509.HostnameError
 check(response == nil && errors.As(err, &hostnameError) && connectStatus.Load() == 200, "client must verify the tunneled TLS identity")
 check(handled.Load() == 1, "wrong-name TLS must not reach the HTTP handler")
 fmt.Println("wrong name CONNECT=200; TLS rejected before origin HTTP")
 success("recovery")
 check(handled.Load() == 2 && admitted.Load() == 3, "wrong final origin/tunnel counts")
 for index := 0; index < 3; index++ {
 select {
 case counts := <-relayed:
 check(counts[0] > 0 && counts[1] > 0, "proxy must relay bytes in both directions")
 case <-time.After(4 * time.Second):
 panic("relay did not finish")
 }
 }
 fmt.Println("three completed relays; two successful origin HTTP requests")
 fmt.Println(runtime.Version())
}

The allowed request records CONNECT 200 and receives the complete origin body. The denied.invalid target records CONNECT 403 without another upstream admission. The name is never resolved by this fixture. A third attempt gets CONNECT 200 but fails certificate hostname verification; the origin’s HTTP handler count remains unchanged. A final correctly configured request succeeds.

Three admitted relays forward bytes in both directions; only two origin HTTP requests complete. DisableKeepAlives prevents unrelated connection reuse from concealing a new CONNECT exchange. The proxy response callback checks actual admission status and the successful response’s framing fields. Copy completion is awaited, and each hijacked socket is explicitly closed.

All assertions passed on macOS with Go 1.27.0. Requests have two-second timeouts, dialing has a one-second timeout, and tunnel sockets have a three-second absolute deadline. This is an isolated protocol exercise, not a deployable public proxy. Authentication, DNS policy, interception, buffered early-data injection, traffic shaping, sustained load, and HTTP/2 or HTTP/3 CONNECT mappings are not tested.

Sources

RFC 9110: HTTP semantics, CONNECT admission, authority targets, relay ownership, and destination restrictions, checked 2026-09-09.
RFC 9112: HTTP/1.1, message framing and the CONNECT tunnel boundary, checked 2026-09-09.
Go net/http, proxy response observation and ownership of hijacked connections, checked 2026-09-09.
Go net, connection deadlines and TCP half-close behavior, checked 2026-09-09.
Go crypto/tls, certificate validation and TLS connection state, checked 2026-09-09.

Response buffering absorbs a speed difference within a resource budget

Tue, 07 Dec 2027 00:00:00 +0000

Response buffering lets nginx read from an upstream while delivering data to a client at another pace. With proxy_buffering on, nginx uses configured memory buffers and can write part of a large response to a temporary file. It need not collect the entire response before sending the first bytes. The available buffering determines how far the two connections can progress independently.

When it breaks

An unconditional promise that slow clients never block the backend is incorrect. Memory buffers, temporary-file limits, disk throughput, and socket buffers are finite. When nginx cannot absorb more data, the upstream can experience backpressure. Disabling temporary-file buffering does not turn response buffering off; it removes one place where data could wait, making that capacity boundary easier to reach.

Buffering can also interfere with an endpoint’s latency expectations. Small events may be accumulated before a client sees them, even though complete-response collection is not required. Streaming endpoints should choose response buffering deliberately and test event visibility through the full chain. Application buffering, compression, TLS, and other intermediaries can still affect delivery after nginx’s response buffering is disabled.

The resource tradeoff occurs at the proxy. Spooling responses can release backend work sooner but consumes temporary storage and I/O while clients drain. Growing memory buffers for every connection can create a different capacity problem under concurrency. The useful question is how much data the proxy should absorb for the workload, not whether a large single buffer sounds faster.

Check it quickly

Save the script as check-response-buffering.py and run it with Python, Docker, the pinned images, and spare temporary disk capacity. The recorded environment used nginx 1.28.0 on Linux arm64. A private backend exposes controlled response gates and progress counters; nginx listens only through host loopback. The experiment sends three 32 MiB bodies and cleans up its resources:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from urllib.parse import urlsplit,parse_qs
import json,socket,threading
lock=threading.Lock();state={};gates={};chunk=b'x'*65536;total=32*1024*1024
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path);path=parsed.path
 if path=='/state':
 with lock:data=json.dumps(state).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data);return
 if path=='/release':
 target=parse_qs(parsed.query)['path'][0]
 with lock:gates[target].set()
 self.send_response(204);self.end_headers();return
 gated=path.startswith('/early-');size=2*len(chunk) if gated else total
 with lock:state[path]={'written':0,'done':False};gates[path]=threading.Event()
 self.connection.setsockopt(socket.SOL_SOCKET,socket.SO_SNDBUF,65536)
 self.send_response(200);self.send_header('Content-Length',str(size));self.end_headers()
 for offset in range(0,size,len(chunk)):
 self.wfile.write(chunk)
 with lock:state[path]['written']=offset+len(chunk)
 if gated and offset==0:assert gates[path].wait(15)
 with lock:state[path]['done']=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /early-on { proxy_buffering on; proxy_pass http://backend:8081; }
location /early-off { proxy_buffering off; proxy_pass http://backend:8081; }
location /large-on { proxy_buffering on; proxy_pass http://backend:8081; }
location /large-off { proxy_buffering off; proxy_pass http://backend:8081; }
location /large-nodisk { proxy_buffering on; proxy_max_temp_file_size 0; proxy_pass http://backend:8081; }
location / { proxy_pass http://backend:8081; }
'''
extra='''
proxy_buffer_size 4k; proxy_buffers 4 4k; proxy_busy_buffers_size 8k;
proxy_temp_file_write_size 8k; proxy_max_temp_file_size 64m; proxy_temp_path /tmp/proxy;
'''
with lab(config(locations,extra),backend=backend) as (proxy,request):
 results={}
 def state():return json.loads(request('/state')[2])
 for mode in ('on','off'):
 path='/early-'+mode;connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=10)
 connection.request('GET',path);response=connection.getresponse();first=response.read(1024)
 snapshot=state()[path];assert response.status==200 and first==b'x'*1024 and not snapshot['done']
 assert request('/release?path='+path)[0]==204
 rest=response.read();connection.close();assert first+rest==b'x'*(2*65536)
 results[path]={'first_bytes_before_backend_completion':len(first),'backend_written_at_first_read':snapshot['written']}
 total=32*1024*1024;expected=hashlib.sha256(b'x'*total).hexdigest()
 for mode in ('on','off','nodisk'):
 path='/large-'+mode;sock=socket.socket();sock.setsockopt(socket.SOL_SOCKET,socket.SO_RCVBUF,65536)
 sock.settimeout(20);sock.connect(('127.0.0.1',request.port))
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=20);connection.sock=sock
 connection.request('GET',path);response=connection.getresponse();assert response.status==200
 wait(lambda:state().get(path,{}).get('written',0)>0)
 if mode=='on':wait(lambda:state()[path]['done'])
 else:
 previous=-1;stable_since=time.monotonic();deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 current=state()[path];assert not current['done'],current
 if current['written']!=previous:previous=current['written'];stable_since=time.monotonic()
 if time.monotonic()-stable_since>1:break
 time.sleep(.05)
 else:raise AssertionError('backend did not reach observable backpressure')
 before=state()[path]
 if mode!='on':assert 0<before['written']<total
 sock.setsockopt(socket.SOL_SOCKET,socket.SO_RCVBUF,1024*1024)
 digest=hashlib.sha256();received=0
 while block:=response.read(1024*1024):digest.update(block);received+=len(block)
 connection.close();wait(lambda:state()[path]['done'])
 assert received==total and digest.hexdigest()==expected
 results[path]={'before_client_drain':before,'received_bytes':received,'sha256':digest.hexdigest()}
 log=docker('exec',proxy,'cat','/tmp/error.log').stdout
 spills=[line for line in log.splitlines() if 'buffered to a temporary file' in line]
 assert any('/large-on ' in line for line in spills),log
 assert not any('/large-off ' in line or '/large-nodisk ' in line for line in spills)
 results['temporary_file_used_for_large_on']=True
 print(json.dumps(results,sort_keys=True))

First, the backend writes 65,536 bytes of a 131,072-byte response, then waits for an explicit release. In both buffering modes, the client reads 1,024 body bytes while the backend remains unfinished. Only afterward does the script release the second half and check the full response. This directly disproves the idea that enabled response buffering always delays delivery until the complete upstream response exists.

Next, a client receives headers for a 32 MiB response and pauses body consumption. With response buffering enabled and a 64 MiB temporary-file limit, the backend records that it finished writing its entire response before the client drains it. nginx’s error log confirms that the response used a temporary file. Backend progress and the actual spooling message support the conclusion together.

With buffering disabled, the backend’s completed-write counter stops below 32 MiB while the client remains paused. The fixture requires that counter to stay unchanged for a controlled interval, then resumes reading. The backend finishes and the complete digest matches. A second control leaves buffering enabled but sets proxy_max_temp_file_size 0; it also reaches observable backpressure before client consumption resumes.

The exact intermediate byte counts vary with socket and platform behavior. They are observations, not recommended buffer sizes or portable thresholds. The meaningful distinction is that one path finishes producing the response while the client is paused, whereas the two constrained paths do not. All three eventually deliver exactly 33,554,432 bytes with the same expected SHA-256 digest.

Budget buffering and verify visible progress

proxy_buffer_size handles the first upstream response portion, normally including headers. proxy_buffers configures additional response buffers, while temporary-file directives govern disk use for this uncached path. Do not confuse their limits with a maximum accepted response length: a response can continue as the client drains and frees capacity instead of being rejected merely for exceeding memory buffers.

An upstream may request response buffering changes with X-Accel-Buffering, unless nginx is configured to ignore that header. Audit that application-controlled behavior when a location’s expected policy seems ineffective. Request-body buffering is a separate setting and is not changed by this response control.

For an ordinary download, consider backend occupancy together with proxy disk use and client completion time. For progressive events, measure when each event becomes visible and include slow readers in the check. A fast localhost transfer alone cannot demonstrate protection against a slow-client workload or prove that streaming latency meets the application’s contract.

Sources

nginx proxy module, response buffers, temporary files, and X-Accel-Buffering controls, checked 2026-09-12.
nginx reverse proxy guide, buffered and synchronous forwarding to clients, checked 2026-09-12.

A reverse proxy needs an explicit header trust boundary

Fri, 27 Aug 2027 00:00:00 +0000

A reverse proxy accepts a client connection and makes a separate request to an upstream application. The application’s socket peer is therefore the proxy, while information about an earlier client can arrive through request headers. Those headers are useful only when the deployment defines who may set them and how they are validated. Proxying a request does not automatically make every forwarded identity or scheme claim trustworthy.

When it breaks

A client can supply X-Forwarded-For before reaching the proxy. Ordinary forwarding may preserve that value, and $proxy_add_x_forwarded_for appends the current peer address rather than removing an untrusted prefix. An application that blindly trusts the first address can therefore attribute the request to a client-selected value. The correct interpretation depends on the actual trusted proxy chain.

Host handling is another independent decision. nginx’s default upstream Host is based on the proxy destination, not automatically the public Host the client used. An application building absolute redirects or selecting virtual hosts can consequently behave differently behind the proxy. Forward only the intended host context and apply the application’s accepted-host policy; copying a header does not validate the name it contains.

The proxy also does not guarantee that backend details remain undisclosed. Response headers, redirects, bodies, diagnostics, or other public configuration can reveal information about the origin. Restricting direct reachability and controlling selected response fields are useful measures, but they are different from claiming that one proxy_pass directive hides all upstream identity or provides every required transport protection.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx and Python images. The recorded environment used nginx 1.28.0 and Python 3.11.16 on Linux arm64 with Docker 29.3.1. It creates a private Docker network and a real echo backend, publishes only the proxy on host loopback, validates configuration, and cleans up its own resources. No production endpoint or credential is involved:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

locations=r'''
location /default { proxy_pass http://backend:8081; }
location /append { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://backend:8081; }
location /edge {
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For $remote_addr;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header X-Forwarded-Host $host;
 proxy_hide_header X-Backend-Info;
 proxy_pass http://backend:8081;
}
'''
with lab(config(locations,'server_tokens off;'),backend=backend) as (container,request):
 forged={'Host':'public.example','X-Forwarded-For':'198.51.100.77','X-Forwarded-Proto':'forged-scheme','X-Real-IP':'198.51.100.88'}
 status,headers,body=request('/default',headers=forged);plain=json.loads(body)
 assert status==200 and plain['headers']['Host']=='backend:8081'
 assert plain['headers']['X-Forwarded-For']=='198.51.100.77' and plain['headers']['X-Forwarded-Proto']=='forged-scheme'
 assert headers['x-backend-info']=='fixture-node'
 status,headers,body=request('/append',headers=forged);appended=json.loads(body)['headers']['X-Forwarded-For'].split(', ')
 assert status==200 and len(appended)==2 and appended[0]=='198.51.100.77'
 status,headers,body=request('/edge',headers=forged);edge=json.loads(body)['headers']
 assert status==200 and edge['Host']==edge['X-Forwarded-Host']=='public.example'
 assert edge['X-Forwarded-For']==edge['X-Real-IP']==appended[-1]
 assert edge['X-Forwarded-For'] not in ['198.51.100.77','198.51.100.88'] and edge['X-Forwarded-Proto']=='http'
 assert 'x-backend-info' not in headers and headers['server']=='nginx'
 print('ordinary forwarding preserves forged forwarding headers and defaults Host to the upstream authority')
 print('append retains the untrusted prefix; the direct-client edge configuration replaces it with the actual socket peer and scheme')
 print('explicit response-header suppression removes one backend field, while server_tokens off still exposes the nginx product name')

Every test request supplies public.example as Host and deliberately forged forwarding values using documentation-only IP addresses. The default route sends Host as backend:8081 and preserves the forged X-Forwarded-For and X-Forwarded-Proto. This directly demonstrates that normal proxy forwarding is not an identity-sanitization step and does not preserve the public host automatically.

The append route uses $proxy_add_x_forwarded_for. Its backend receives two comma-separated addresses: the client-supplied address first, followed by nginx’s observed socket peer. The original untrusted prefix remains. Appending useful connection context does not make the entire resulting list equally authoritative, and trusting its leftmost entry would defeat the intended boundary in this direct-client setup.

The edge route replaces X-Forwarded-For and X-Real-IP with $remote_addr, sets the forwarded scheme from $scheme, and forwards the chosen host context explicitly. The backend receives the actual observed peer value rather than either forged address, and the scheme is http in this deliberately plain-HTTP fixture. The test compares the values across requests without assuming a particular Docker bridge address.

That socket peer can reflect Docker’s networking path; it is not a claim to reconstruct an arbitrary internet user’s address through every NAT or earlier proxy. If the edge itself sits behind a trusted load balancer, the deployment needs a deliberate policy for accepting that hop’s information. The example tests a direct-client trust boundary, not every possible proxy chain.

The backend also emits X-Backend-Info: fixture-node. The default route exposes it, while the edge route’s explicit proxy_hide_header removes it. With server_tokens disabled, the response still says Server: nginx. This separates suppression of one backend field from hiding the proxy product name or proving that no other response content discloses implementation details.

Connect network access and header interpretation

Limit which callers can reach the backend directly when it relies on proxy-established context. Configure trusted proxy addresses narrowly if using the real IP module, and ensure the resulting address interpretation matches the application’s own trust settings. A broad trust range can allow an unintended caller to supply apparently authoritative forwarding information.

Decide where TLS terminates and whether the upstream connection also needs encryption and certificate verification. The scheme nginx observes on one hop does not automatically describe an earlier hop. Test redirects, secure-cookie behavior, and generated URLs through the actual deployment path when they depend on forwarded scheme or host.

Finally, inspect the request received by the application and the response received by the client. Header configuration, network isolation, and disclosure controls each answer a different question. Evidence from both sides makes their combined behavior reviewable without assuming that the proxy silently supplies every missing guarantee.

Sources

nginx HTTP proxy module, default Host handling, forwarded headers, and response-header suppression, checked 2026-09-12.
nginx real IP module, explicitly trusted address sources and proxy chains, checked 2026-09-12.
nginx core server_tokens and variables, socket-peer address, request scheme, and server-version disclosure, checked 2026-09-12.

nginx proxy cache balances stale and fresh

Thu, 24 Jun 2027 00:00:00 +0000

An nginx proxy cache has several independent decisions: identifying the stored response, deciding whether it may be reused, deciding whether a new response may be stored, and handling an expired copy. Treating those decisions as one TTL setting makes failures difficult to explain. Verify the resulting request path and bytes, not merely that nginx accepts the configuration.

Separate storage from freshness

Proxy_cache_path names the disk storage and a shared-memory keys_zone for metadata; proxy_cache enables that zone for requests. The metadata size does not bound response-body storage. Max_size is managed by cache maintenance rather than an instantaneous disk quota, while inactive retention is not the response’s freshness lifetime. An expired response can remain stored and useful for revalidation.

The default key is $scheme$proxy_host$request_uri. Request_uri already includes the query string, so appending $is_args$args repeats it. Do not casually substitute a normalized URI or omit representation-changing inputs. GET and HEAD share the default cache behavior because HEAD conversion is enabled; disabling that conversion requires accounting for the request method in the key.

Verify the active response policy

Proxy_cache_valid supplies configured lifetimes by response status, but processed origin freshness headers have higher priority. X-Accel-Expires has its own precedence; Cache-Control and Expires apply when it is absent. Ignoring those headers changes the contract. In the exercise, origin max-age one overrides configured validity of sixty seconds, while no-store prevents response storage.

Proxy_cache_revalidate enables conditional requests for expired items using validators such as ETag and Last-Modified. A matching 304 can preserve the body and refresh metadata; a changed 200 supplies replacement bytes. This does not imply asynchronous refresh. Background updating is a separate directive and also needs permission to serve stale content during updating.

When it breaks

Proxy_cache_bypass prevents reading from cache; proxy_no_cache prevents saving the new response. A route requiring both behaviors needs both decisions expressed. Bypassing once also does not purge an older entry. The fixture pairs the directives with a laboratory header and proves that the original cached response remains available afterward. That header is a test switch, not an authentication policy.

Proxy_cache_use_stale http_500 permits an existing stale response after an upstream 500. It cannot help a completely cold key, and the directive does not itself specify a maximum stale duration. An origin stale-if-error window has lower priority than these directive parameters, so adding that header does not cap this setting. Decide whether old content is acceptable before enabling it.

Otherwise a successful-looking response can conceal an origin failure or keep obsolete data visible. Record the upstream outcome, nginx cache status, and delivered body together. A syntax check cannot establish account isolation, and a single warm hit cannot prove behavior during concurrent cold loads. Cache locking, retention under pressure, and multi-worker behavior require their own verification.

Check it quickly

Use a POSIX environment with a C compiler, make, curl, tar, and Python 3.11 or newer. This ran on macOS with clang 21.0.0, Python 3.14.4, and nginx 1.30.4. The commands build an isolated HTTP-only test binary without installation or sudo. They omit rewrite and gzip modules to avoid their external dependencies; this is not a TLS deployment recipe.

nginx_lab=$(mktemp -d)
curl --fail --location --output "$nginx_lab/nginx.tar.gz" https://nginx.org/download/nginx-1.30.4.tar.gz
tar -xzf "$nginx_lab/nginx.tar.gz" -C "$nginx_lab"
cd "$nginx_lab/nginx-1.30.4"
./configure --prefix="$nginx_lab/install" --without-http_rewrite_module --without-http_gzip_module
make -j2
export NGINX_BIN="$nginx_lab/nginx-1.30.4/objs/nginx"

Run the Python block with python3 in that shell. It creates its own configuration and cache directory, checks the configuration, and starts only loopback services on selected ports. Two short waits allow real cache expiry. It shuts down its own nginx process and origin, then removes only the temporary runtime directory. Source downloads need the network; requests in the experiment remain local.

import hashlib
import os
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
import signal
import socket
import subprocess
from tempfile import TemporaryDirectory
from threading import Thread
import time

state = {"body": b"A", "fail": False}
seen = []


class Origin(BaseHTTPRequestHandler):
 def log_message(self, *_):
 pass

 def do_GET(self):
 tag = '"' + hashlib.sha256(state["body"]).hexdigest() + '"'
 conditional = self.headers.get("If-None-Match")
 if self.path == "/short" and state["fail"]:
 status, body = 500, b"failure"
 elif conditional == tag:
 status, body = 304, b""
 else:
 status, body = 200, state["body"]
 directive = "max-age=1" if self.path == "/short" else "max-age=60"
 if self.path == "/no-store" or status == 500:
 directive = "no-store"
 seen.append((self.path, status, conditional))
 self.send_response(status)
 self.send_header("Cache-Control", directive)
 if status != 500:
 self.send_header("ETag", tag)
 if status != 304:
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


origin = HTTPServer(("127.0.0.1", 0), Origin)
worker = Thread(target=origin.serve_forever)
worker.start()
try:
 with TemporaryDirectory(prefix="nginx-cache-lab-") as directory:
 root = Path(directory)
 with socket.socket() as reservation:
 reservation.bind(("127.0.0.1", 0))
 port = reservation.getsockname()[1]
 config = root / "nginx.conf"
 config.write_text(f"""
pid nginx.pid;
error_log stderr error;
events {{ worker_connections 64; }}
http {{
 access_log off;
 proxy_cache_path "{root}/cache" keys_zone=lab:1m max_size=10m;
 server {{
 listen 127.0.0.1:{port};
 location / {{
 proxy_pass http://127.0.0.1:{origin.server_port};
 proxy_cache lab;
 proxy_cache_valid 200 60s;
 proxy_cache_revalidate on;
 proxy_cache_use_stale http_500;
 proxy_cache_bypass $http_x_lab_bypass;
 proxy_no_cache $http_x_lab_bypass;
 proxy_connect_timeout 2s;
 proxy_read_timeout 2s;
 add_header X-Lab-Cache $upstream_cache_status always;
 }}
 }}
}}
""", encoding="utf-8")
 command = [os.environ["NGINX_BIN"], "-p", str(root) + "/",
 "-c", str(config), "-e", "stderr"]
 checked = subprocess.run(command + ["-t"], capture_output=True, text=True)
 assert checked.returncode == 0, checked.stderr
 process = subprocess.Popen(command + ["-g", "daemon off; master_process off;"],
 stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True)
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "nginx exited during startup"
 try:
 with socket.create_connection(("127.0.0.1", port), timeout=0.1):
 break
 except OSError:
 if time.monotonic() >= deadline:
 raise TimeoutError("nginx did not become ready")
 time.sleep(0.05)

 def get(path, expected, body, bypass=False):
 connection = HTTPConnection("127.0.0.1", port, timeout=3)
 try:
 connection.request("GET", path, headers={"X-Lab-Bypass": "1"} if bypass else {})
 response = connection.getresponse()
 actual = (response.status, response.getheader("X-Lab-Cache"), response.read())
 assert actual == (200, expected, body), actual
 print(path, expected, body.decode())
 finally:
 connection.close()

 get("/long", "MISS", b"A")
 get("/long", "HIT", b"A")
 state["body"] = b"B"
 get("/long", "BYPASS", b"B", bypass=True)
 get("/long", "HIT", b"A")
 assert sum(path == "/long" for path, _, _ in seen) == 2

 get("/short", "MISS", b"B")
 time.sleep(2.1)
 get("/short", "REVALIDATED", b"B")
 assert seen[-1][1:] == (304, '"' + hashlib.sha256(b"B").hexdigest() + '"')
 state["fail"] = True
 time.sleep(2.1)
 get("/short", "STALE", b"B")
 assert seen[-1][1] == 500
 state.update(body=b"C", fail=False)
 get("/short", "EXPIRED", b"C")
 get("/short", "HIT", b"C")
 get("/no-store", "MISS", b"C")
 get("/no-store", "MISS", b"C")
 assert sum(path == "/no-store" for path, _, _ in seen) == 2
 finally:
 if process.poll() is None:
 process.send_signal(signal.SIGQUIT)
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors
finally:
 origin.shutdown()
 worker.join()
 origin.server_close()

The long-lived route reports MISS A, HIT A, BYPASS B, then HIT A. Only two requests reached that origin path, and B was not saved by the bypass request. The short-lived route reports MISS B and, after expiry, REVALIDATED B; the origin log confirms a 304 and the correct conditional ETag.

With an injected origin 500 it serves STALE B. Once the origin recovers with C, EXPIRED C replaces the body and the following request is HIT C. Two no-store requests both remain MISS. These are real nginx decisions for this single-process fixture, not evidence for background refresh, distributed invalidation, production authorization, disk-pressure handling, or every stale-policy combination.

Sources

nginx proxy module, keys, header precedence, revalidation, bypass, storage, and stale directives, checked 2026-09-07.
nginx build configuration, build prefix and optional module dependencies, checked 2026-09-07.
nginx content caching guide, disk storage, shared metadata, and cache management, checked 2026-09-07.
RFC 9111: stale responses, freshness and permitted stale reuse, checked 2026-09-07.

proxy_pass maps the URI as well as selecting an upstream

Fri, 02 Apr 2027 00:00:00 +0000

nginx proxy_pass chooses an upstream destination and also affects the request URI sent there. The important distinction is whether the directive includes a URI component, not simply whether its text ends with a slash. In an ordinary prefix location, a literal target URI replaces the matching normalized prefix. An authority-only target can pass the original request URI when the request has not been rewritten.

When it breaks

An application serving /users may return 404 when the proxy forwards /api/users, even though the network connection succeeds. The opposite mismatch occurs when an application expects the public prefix and the proxy removes it. Comparing only client status and upstream reachability misses this class of error; inspect the exact method, path, query, and host the backend receives.

Slash boundaries are part of literal replacement. A target ending in /v1 still contains a URI, so replacing /join/ in /join/item yields /v1item. It does not preserve the original path merely because the target lacks a trailing slash. Thinking in terms of the replaced prefix and remaining suffix explains this result more accurately than a universal trailing-slash slogan.

Variables introduce another documented branch. When a variable-supplied proxy URL contains a URI, that URI is used as specified instead of applying the ordinary literal-prefix replacement rule. Regex and named locations also lack the same unambiguous prefix boundary. Configuration that works in a plain prefix location cannot be copied into those contexts without checking the corresponding contract.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx and Python images available. The recorded environment used nginx 1.28.0 and Python 3.11.16 on Linux arm64 with Docker 29.3.1. It starts an actual HTTP backend that echoes received request fields, validates nginx configuration, publishes only the proxy on host loopback, and removes its own images, containers, and network:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True);target.write_text(content)
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

locations=r'''
location /keep/ { proxy_pass http://backend:8081; }
location /strip/ { proxy_pass http://backend:8081/; }
location /replace/ { proxy_pass http://backend:8081/v1/; }
location /join/ { proxy_pass http://backend:8081/v1; }
location /variable/ { set $destination "http://fixture_pool/fixed?chosen=1"; proxy_pass $destination; }
'''
invalid=config(r'location ~ ^/bad/ { proxy_pass http://backend:8081/replacement/; }')
with lab(config(locations,'upstream fixture_pool { server backend:8081; }'),{'invalid.conf':invalid},backend) as (container,request):
 cases={'/keep/item?x=1':'/keep/item?x=1','/strip/item?x=1':'/item?x=1','/replace/item?x=1':'/v1/item?x=1','/join/item?x=1':'/v1item?x=1','/keep/a%2Fb?x=1':'/keep/a%2Fb?x=1','/strip/a%2Fb?x=1':'/a/b?x=1','/variable/item?original=1':'/fixed?chosen=1'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and json.loads(body)['path']==expected,(path,status,body)
 invalid_result=docker('exec',container,'nginx','-t','-c','/srv/invalid.conf',check=False)
 assert invalid_result.returncode!=0 and 'cannot have URI part in location given by regular expression' in invalid_result.stderr
 print('no URI preserves the original path; a literal URI replaces the normalized matching prefix, including its slash boundaries')
 print('a variable-supplied URI is used as specified; regex-location URI replacement is rejected by nginx -t')

An authority-only target in /keep/ forwards /keep/item?x=1 unchanged. A target ending in / inside /strip/ instead forwards /item?x=1. The query survives both of these literal examples. The backend’s JSON response supplies the evidence, rather than an assumption based on what the public URL looked like before nginx handled it.

The /replace/ location maps its prefix to /v1/, so /replace/item?x=1 becomes /v1/item?x=1. The deliberately missing separator in the /join/ target produces /v1item?x=1. Both requests reach the backend successfully. Their distinct paths demonstrate why a successful TCP connection or HTTP response does not establish the intended route mapping.

Encoded separators expose the normalization boundary. /keep/a%2Fb?x=1 remains encoded in the authority-only case, while /strip/a%2Fb?x=1 reaches the backend as /a/b?x=1 after normalized prefix replacement. This can change how an application divides path segments. Align the proxy and application’s path interpretation when encoded identifiers or access-control boundaries depend on those separators.

The variable example names a predefined upstream group and supplies /fixed?chosen=1 as its target URI. Requesting /variable/item?original=1 reaches exactly that fixed URI; the original suffix and query are not automatically appended. Using a known upstream group also keeps this example separate from arbitrary per-request hostname resolution and its resolver requirements.

A second configuration deliberately puts a proxy target with a URI part inside a regex location. nginx -t rejects it with the documented URI-part restriction. The active configuration is not replaced by this invalid file. This verifies a real configuration failure in addition to the successful routing cases.

Treat each public-to-backend mapping as a contract

For every proxy location, write down the public prefix, replacement URI if any, and expected backend path and query. Include boundary slashes and encoded forms in tests. If a rewrite changes the URI before proxying, revisit authority-only behavior too: forwarding the original request is conditional on processing the original URI, not an unconditional promise for every rewritten request.

Keep destination selection constrained to intended backends. A variable derived from untrusted request data should not become unrestricted authority to contact arbitrary hosts. Named upstream groups, explicit mappings, and appropriate rejection behavior should follow the application’s actual routing requirements rather than silently accepting an unknown destination.

Configure forwarded headers, connection reuse, timeouts, and upstream TLS according to their own contracts. A resolver directive is not a general switch that makes variable targets or keepalive universally correct. Test those behaviors separately and retain the backend observations that prove the selected URI mapping.

Sources

nginx proxy_pass reference, URI replacement, unchanged request forwarding, variable targets, and regex restrictions, checked 2026-09-12.
nginx core location matching, normalized prefix selection before proxy processing, checked 2026-09-12.
nginx upstream module, named upstream groups and backend selection, checked 2026-09-12.

Upstream keepalive caches idle connections, not active capacity

Mon, 15 Mar 2027 00:00:00 +0000

An nginx upstream keepalive cache preserves eligible idle backend connections for later requests. In the tested configuration, keepalive 2 permits two idle connections in that upstream cache for each worker. It does not restrict the worker to two active backend connections. Reuse reduces repeated connection setup; it does not itself impose an application concurrency budget or guarantee lower latency for every request.

When it breaks

An idle-cache size mistaken for a connection cap leaves the backend exposed to more simultaneous work than expected. A busy worker can open additional active connections while its retained idle cache remains small. With several workers, each worker’s idle cache also matters. Count active and idle resources separately when comparing nginx settings with a backend’s actual connection capacity.

Connection reuse requires a reusable protocol exchange. For this nginx 1.28.0 HTTP example, upstream HTTP/1.1 and clearing the default Connection: close header are explicit configuration choices. Merely setting Host does not establish persistence. A backend can still close connections, and incomplete or incorrectly framed messages cannot be treated as clean reusable exchanges just because a cache is configured.

Client-side persistence is a different connection relationship. A fresh client connection can be served using a previously cached upstream connection, while a long-lived client can trigger several backend connections. Assuming those lifetimes match leads to misleading measurements. Connection setup savings also differ between a plain HTTP upstream and a TLS upstream; this experiment uses plain HTTP behind nginx.

Check it quickly

Save the script as check-upstream-keepalive.py and run it with Python, Docker, and the pinned images. It uses one nginx 1.28.0 worker and a Python HTTP/1.1 backend on a private network. Each accepted backend connection receives an identity, and each response has an explicit length. Client requests enter through host loopback:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
from concurrent.futures import ThreadPoolExecutor
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import itertools,json,threading
ids=itertools.count(1);lock=threading.Lock();opened=set();active=set();release=threading.Event()
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def setup(self):
 super().setup();self.ident=next(ids)
 with lock:opened.add(self.ident)
 def finish(self):
 try:super().finish()
 finally:
 with lock:opened.discard(self.ident)
 def log_message(self,*args):pass
 def do_GET(self):
 if self.path=='/hold':
 with lock:active.add(self.ident)
 assert release.wait(15)
 with lock:active.remove(self.ident)
 elif self.path=='/release':release.set()
 with lock:data=json.dumps({'connection':self.ident,'active':sorted(active),'other_open':sorted(opened-{self.ident}),
 'host':self.headers.get('Host'),'connection_header':self.headers.get('Connection')}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /reuse/ { proxy_http_version 1.1; proxy_set_header Connection ""; proxy_pass http://pool/; }
location /close/ { proxy_http_version 1.1; proxy_set_header Connection close; proxy_pass http://pool/; }
location /host-only/ { proxy_http_version 1.1; proxy_set_header Host service.example; proxy_pass http://pool/; }
location /control/ { proxy_set_header Connection close; proxy_pass http://backend:8081/; }
'''
extra='upstream pool { server backend:8081; keepalive 2; keepalive_timeout 30s; }'
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path):
 status,_,body=request(path);assert status==200;return json.loads(body)
 results={}
 for mode in ['reuse','close','host-only']:
 first=get('/'+mode+'/id');second=get('/'+mode+'/id')
 assert (first['connection']==second['connection'])==(mode=='reuse')
 if mode=='host-only':assert first['host']=='service.example' and first['connection_header']=='close'
 results[mode]={'connections':[first['connection'],second['connection']],'host':first['host'],'connection_header':first['connection_header']}
 with ThreadPoolExecutor(max_workers=4) as pool:
 futures=[pool.submit(get,'/reuse/hold') for _ in range(4)]
 wait(lambda:len(get('/control/state')['active'])==4)
 active=get('/control/state')['active'];assert len(set(active))==4
 get('/control/release');replies=[f.result(timeout=10) for f in futures]
 assert len({r['connection'] for r in replies})==4
 wait(lambda:len(get('/control/state')['other_open'])==2)
 results['concurrent_active']=active;results['idle_after_burst']=get('/control/state')['other_open']
 print(json.dumps(results,sort_keys=True))

Two sequential /reuse/id requests return the same backend connection identity. The client helper opens and closes its own HTTP connection for each request, so this is upstream reuse across distinct downstream connections. The location explicitly uses upstream HTTP/1.1 and sends no Connection header. Reading each complete response leaves the backend exchange eligible to become idle.

The /close/id control sends Connection: close and returns different backend identities for successive requests. The /host-only/id control changes Host but leaves the closing behavior intact; its responses also use different connections. These comparisons show why a routing header is not a substitute for correct persistence settings, even when all paths contact the same application.

Next, four clients request responses that the backend deliberately holds open. The controller waits until the backend reports four active connection identities before releasing any response. That directly demonstrates four simultaneous upstream connections under keepalive 2. It does not infer concurrency from timing or from a count of completed requests that might have been processed sequentially.

After release, all four replies complete. The fixture observes exactly two remaining idle backend connections, excluding the short-lived control connection used to inspect state. Which identities survive can vary with completion order; their count is the assertion. This distinguishes the configured idle retention limit from the larger set of active connections used during the burst.

Match reuse settings to backend behavior

Size idle retention using connection setup cost, expected reuse, backend limits, and the number of nginx workers. A retained connection consumes resources even while it carries no request. A very large cache can therefore compete with new useful connections, while a very small one may repeatedly discard connections that would soon have been reused.

Request-count, idle-time, and total connection-lifetime controls can recycle persistent connections for different reasons. Do not respond to every reconnection by increasing all of them. Observe backend closes, configuration, completed response framing, and actual connection identities first. The tested idle timeout is thirty seconds; the short burst does not benchmark long-running connection aging or TLS session behavior.

Finally, use an actual concurrency or admission policy when limiting backend work is the objective. Keepalive is reuse policy. The fixture chooses its protocol and cache settings explicitly because rolling documentation includes later nginx defaults and features. Apply the semantics of the deployed version, and verify both reuse and a concurrent burst instead of assuming one successful repeated request proves the capacity boundary.

Sources

nginx upstream module, idle connection caches, worker scope, and keepalive limits, checked 2026-09-12.
nginx 1.28.0 upstream keepalive source, the tested version’s idle-cache and connection reuse implementation, checked 2026-09-12.
RFC 9112 HTTP/1.1, persistent connections, message framing, and Connection close, checked 2026-09-12.

A reverse proxy enforces an entry policy only on traffic that traverses it

Thu, 05 Nov 2026 00:00:00 +0000

A reverse proxy accepts client requests and makes a separate upstream exchange with an application. It can centralize routing, transport, headers, and admission policy when those behaviors are configured. It does not automatically hide every backend interface, authenticate every caller, or terminate TLS. The useful boundary is the actual traffic path and policy applied there, not simply the proxy’s position in a diagram.

When it breaks

A backend reachable through another route can bypass controls implemented only at the proxy. Not publishing a container port reduces one exposure path, but peers on an attached network may still reach the application. If backend authorization relies entirely on the claim that all traffic passed through the public proxy, a direct internal request can invalidate that assumption.

URI mapping can create a subtler bypass. Blocking /admin at the proxy does not help if a broad /api/ mapping also exposes the same backend handler as /api/admin. Review the final upstream URI, not just the visible client path. Publishing a specific endpoint is different from exposing every handler beneath a convenient prefix and hoping names stay separate.

Forwarded metadata requires deliberate handling. A client may send a fabricated address or scheme header, and a proxy does not make that value trustworthy merely by forwarding it. The application needs to know which fields the trusted hop sets and which callers can reach it. A browser response header also does not replace request authorization or network reachability controls.

Check it quickly

Save this as check-proxy-entry.py and run it with Python, Docker, and the pinned images. The recorded setup uses nginx 1.28.0 with a disposable echo application on a private Docker network. Only the proxy has a host loopback port binding. This fixture uses HTTP to inspect routing and policy; it does not perform a TLS deployment:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None,extra_ports=()):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 published=[arg for value in (8080,*extra_ports) for arg in ('-p','127.0.0.1::'+str(value))]
 docker('run','-d','--name',containers[0],'--network',name,*published,tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port;request.network=name
 request.ports={int(key.split('/')[0]):int(value[0]['HostPort']) for key,value in details['NetworkSettings']['Ports'].items() if value}
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def respond(self,body=b''):
 data=json.dumps({'path':self.path,'method':self.command,'body':body.decode(),
 'host':self.headers.get('Host'),'forwarded_for':self.headers.get('X-Forwarded-For'),
 'forwarded_proto':self.headers.get('X-Forwarded-Proto')}).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)))
 self.end_headers();self.wfile.write(data)
 def do_GET(self):self.respond()
 def do_POST(self):self.respond(self.rfile.read(int(self.headers['Content-Length'])))
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location = /api/echo {
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For $remote_addr;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_pass http://backend:8081/echo;
}
location /admin { deny all; }
location / { return 404; }
'''
extra='client_max_body_size 1k; add_header X-Content-Type-Options nosniff always;'
bad='events {} http { server { listen not-a-port; } }'
with lab(config(locations,extra),{'invalid.conf':bad},backend) as (proxy,request):
 status,h,b=request('/api/echo',method='POST',body=b'hello',headers={'Host':'edge.example',
 'X-Forwarded-For':'192.0.2.123','X-Forwarded-Proto':'https'})
 data=json.loads(b);assert status==200 and data['path']=='/echo' and data['body']=='hello' and data['method']=='POST'
 assert data['host']=='edge.example' and data['forwarded_for']!='192.0.2.123' and data['forwarded_proto']=='http'
 assert h['x-content-type-options']=='nosniff';results={'proxied_request':data}
 status,h,_=request('/admin');assert status==403 and h['x-content-type-options']=='nosniff';results['admin_at_proxy']=status
 assert request('/api/echo',method='POST',body=b'x'*2048)[0]==413
 assert request('/unknown')[0]==404 and request('/api/admin')[0]==404
 results['size_and_route_rejections']=[413,404];results['admin_alias_rejected']=404
 details=json.loads(docker('inspect',request.network+'-backend').stdout)[0]
 assert not details['HostConfig']['PortBindings']
 code='import json,urllib.request;print(json.dumps(json.load(urllib.request.urlopen("http://backend:8081/admin"))))'
 internal=docker('run','--rm','--network',request.network,PYTHON,'python','-c',code)
 direct=json.loads(internal.stdout);assert direct['path']=='/admin'
 results['backend_has_host_port_binding']=False;results['internal_direct_path']=direct['path']
 probe=docker('exec',proxy,'nginx','-t','-c','/srv/invalid.conf',check=False);assert probe.returncode!=0
 assert request('/api/echo')[0]==200;results['invalid_candidate_rejected_live_config_survives']=True
 print(json.dumps(results,sort_keys=True))

A POST to the exact public path /api/echo reaches backend /echo with method and body preserved. The supplied Host is forwarded deliberately. A fabricated X-Forwarded-For value is replaced by nginx’s observed socket peer, and a fabricated https scheme becomes the actual http scheme of this listener. The response reveals what the backend received rather than assuming a header directive had the intended effect.

At the proxy, /admin returns 403 and /api/admin returns 404. The latter control prevents the alternative URI mapping from reaching that backend handler. An oversized 2,048-byte submission exceeds the 1 KiB limit and returns 413; an unknown route returns 404. The configured nosniff header appears on both the successful response and the explicit access rejection.

The script checks Docker’s backend configuration and confirms that it has no host port binding. It then starts a separate disposable client on the same private network and requests backend /admin directly. That request succeeds. The result is intentional evidence of the boundary: the proxy’s denial does not apply to a path that never visits the proxy.

A final candidate configuration contains an invalid listener value. nginx rejects it during syntax validation, while the existing valid process continues answering /api/echo. This demonstrates that checking a separate candidate does not activate it. It does not claim that an arbitrary reload, certificate rotation, or full deployment workflow has thereby been validated.

Keep entry policy and application responsibility explicit

Inventory the ways clients can reach each backend, including internal peers and separately published listeners. Apply application authorization where the trust model requires it, and limit network access to the intended callers. A private bridge is a connectivity arrangement, not proof that every attached workload has the same privileges or that backend traffic is encrypted.

Choose URI exposure and forwarded fields as part of the application contract. An exact public route can prevent accidental handler exposure in this small example; a larger application needs a reviewed route family rather than an arbitrary list copied from a test. Verify near-miss and rewritten paths whenever several external URLs could name the same internal operation.

TLS can terminate at the proxy, continue to the backend, or follow another explicitly designed boundary. Certificates, upstream verification, renewal, and protocol choices need their own checks. Similarly, one proxy remains one capacity and failure component even when it fronts many healthy applications. Centralizing policy reduces duplication only when the resulting configuration and availability are actually managed.

Finally, validate through the entry point and through any other allowed path. Check what the application receives, what the client sees, and which requests never reach the application. The proxy is a useful place to enforce shared behavior, but correctness comes from those observable boundaries rather than an assumption that a single front door is the building’s only entrance.

Sources

nginx HTTP proxy module, URI mapping, forwarded request headers, and backend transport configuration, checked 2026-09-12.
nginx reverse proxy guide, the client-facing proxy and its independent upstream exchange, checked 2026-09-12.
nginx HTTP core module, exact locations, body limits, and request handling boundaries, checked 2026-09-12.

Proxy · XB Field Notes

A microcache serves fresh entries briefly and coalesces misses explicitly

When it breaks

Check it quickly

Choose freshness and overload behavior separately

Sources

The CONNECT method opens a raw tunnel

Switch protocols at the right boundary

Opaque content still consumes resources

When it breaks

Check it quickly

Further reading

Sources

Response buffering absorbs a speed difference within a resource budget

When it breaks

Check it quickly

Budget buffering and verify visible progress

Sources

A reverse proxy needs an explicit header trust boundary

When it breaks

Check it quickly

Connect network access and header interpretation

Sources

nginx proxy cache balances stale and fresh

Separate storage from freshness

Verify the active response policy

When it breaks

Check it quickly

Further reading

Sources

proxy_pass maps the URI as well as selecting an upstream

When it breaks

Check it quickly

Treat each public-to-backend mapping as a contract

Sources

Upstream keepalive caches idle connections, not active capacity

When it breaks

Check it quickly

Match reuse settings to backend behavior

Sources

A reverse proxy enforces an entry policy only on traffic that traverses it

When it breaks

Check it quickly

Keep entry policy and application responsibility explicit

Further reading

Sources