Nginx · 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.

nginx validators are only as sound as their representation identity

Thu, 17 Feb 2028 00:00:00 +0000

A validator lets a recipient ask whether its stored representation still matches the selected one. A successful conditional GET can return 304 without retransmitting the body. Freshness is a separate decision: it determines when a stored response can be reused without that request. An ETag does not itself specify a cache lifetime, and a 304 is not a replacement body.

When it breaks

Calling every ETag a body hash hides an important nginx detail. In the tested 1.28.0 static-file implementation, the generated tag combines modification time and content length. It does not hash file contents. Replacing bytes while preserving both inputs can retain the same tag, allowing a client holding different bytes to receive an apparently successful validation.

Weak and strong validators also serve different comparisons. A strong validator must distinguish representation data changes for uses requiring byte identity. A weak validator can group representations considered semantically equivalent, even when their bytes differ. The W/ prefix does not mean “byte-equivalent changes,” nor does it make the tag suitable for every precondition or resumable byte-range operation.

Conditional requests do not guarantee that application work was avoided. A server might compute the representation before deciding that its validator matches. Static nginx handling has no application renderer in this example. A smaller response proves saved body transfer here; it does not establish a universal reduction in database queries, rendering cost, or origin request count.

Check it quickly

Save the script as check-validators.py, obtain the pinned nginx image, and run it with Python and Docker. It serves a disposable four-byte static file through host loopback using nginx 1.28.0. File times are deliberately controlled inside the experiment container; the host and Docker VM clocks are not changed:

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'
files={'asset.txt':'AAAA','noetag.txt':'AAAA'}
with lab(config('location = /noetag.txt { etag off; }'),files) as (proxy,request):
 def timestamp(value):docker('exec',proxy,'touch','-m','-d','@'+str(value),'/srv/asset.txt')
 timestamp(1577836800)
 status,headers,body=request('/asset.txt');assert status==200 and body==b'AAAA'
 tag=headers['etag'];modified=headers['last-modified'];results={'etag':tag,'last_modified':modified}
 cases={
 'matching_tag':({'If-None-Match':tag},304),
 'weak_comparison':({'If-None-Match':'W/'+tag},304),
 'matching_date':({'If-Modified-Since':modified},304),
 'tag_takes_precedence':({'If-None-Match':'"different"','If-Modified-Since':modified},200),
 'weak_if_match_rejected':({'If-Match':'W/'+tag},412),
 }
 for name,(conditions,expected) in cases.items():
 status,_,body=request('/asset.txt',headers=conditions);assert status==expected,(name,status)
 if status==304:assert body==b''
 results[name]=status
 docker('exec',proxy,'sh','-c','printf BBBB > /srv/asset.txt');timestamp(1577836800)
 status,current,body=request('/asset.txt');assert status==200 and body==b'BBBB' and current['etag']==tag
 status,_,body=request('/asset.txt',headers={'If-None-Match':tag});assert status==304 and body==b''
 results['changed_bytes_preserved_metadata']=status
 timestamp(1577836802)
 status,current,body=request('/asset.txt',headers={'If-None-Match':tag})
 assert status==200 and body==b'BBBB' and current['etag']!=tag and current['last-modified']!=modified
 results['changed_metadata']={'status':status,'etag':current['etag']}
 status,current,_=request('/noetag.txt');assert status==200 and 'etag' not in current
 print(json.dumps(results,sort_keys=True))

The initial file contains AAAA, has modification time 2020-01-01, and produces ETag "5e0be100-4". A GET carrying that tag in If-None-Match returns 304 with an empty body. Adding W/ to the request tag still returns 304 because this condition uses weak comparison. An equal If-Modified-Since date also returns 304 in the tested configuration.

When a nonmatching If-None-Match accompanies the matching date, the response is 200. The entity-tag condition takes precedence over the date condition; a client cannot make the mismatching tag disappear by also supplying a favorable timestamp. The separate If-Match check rejects the weak request tag with 412. That test is a GET precondition check, not an executed write workflow.

Next, the script changes AAAA to BBBB and restores the original modification time. An unconditional GET proves the bytes changed, while the tag remains identical. Sending the old tag now yields 304 again. This deliberate counterexample demonstrates why metadata preservation during deployment can violate the intended identity contract, even though nginx follows its configured tag-generation algorithm.

Advancing the file time by two seconds changes the generated tag and Last-Modified value. The old entity tag then receives 200 with BBBB. The final control disables etag on another resource and confirms that no ETag header is generated there. Disabling tags removes that validator; it does not automatically provide a stronger replacement or disable every form of caching.

Make deployments preserve the validator contract

For assets whose bytes must remain addressable independently, content-derived filenames can separate versions at the URL level. For stable URLs, ensure deployment metadata changes when representation bytes change, or deliberately supply an appropriate content-derived validator through the serving application. Review rapid same-length updates as well as tools that preserve timestamps while copying new content.

Treat Last-Modified with similar care. It represents a timestamp with limited precision, not a cryptographic identity. Do not assume every date is a strong validator for range resumption. The relevant protocol conditions and the server’s update behavior matter, especially when multiple revisions can occur within the timestamp’s effective resolution.

Finally, test the representation actually delivered through intermediaries and content codings. A validator for one selected representation must not falsely identify another byte sequence where strong comparison is required. Keep cache lifetime, validation, privacy, and byte integrity as explicit decisions, and verify both the unchanged and changed cases during deployment checks.

Sources

RFC 9110 HTTP Semantics, strong and weak validators, conditional precedence, and 304/412 responses, checked 2026-09-12.
RFC 9111 HTTP Caching, freshness, stored responses, and successful validation, checked 2026-09-12.
nginx 1.28.0 core source, the static ETag calculation from modification time and content length, checked 2026-09-12.
nginx HTTP core module, etag and if_modified_since configuration, checked 2026-09-12.

HTTP3 rides UDP while HTTP2 stays safe over TCP

Sat, 12 Feb 2028 00:00:00 +0000

HTTP/3 runs QUIC over UDP:443, and the reason to care is what a lost packet costs. On a TCP connection every stream shares one byte stream, so a dropped segment blocks delivery of everything behind it until the retransmission arrives. QUIC gives each stream its own loss recovery, so the same drop blocks only the streams whose data was in that packet.

The awkward part is that this is not a flag you can turn on: the client must learn the server speaks HTTP/3 before it can try, and the path it learns that over is the one you were trying to improve.

Two transports, one port number

UDP:443 and TCP:443 are separate namespaces, so a single listener can hold both. That is why an nginx server block can carry listen 443 quic reuseport; next to listen 443 ssl; http2 on; and serve both on one port number. The reuseport matters more than it looks: without it, a second bind of UDP:443 fails with EADDRINUSE, which is the error you get when two server blocks both claim the QUIC listener.

QUIC is not HTTP/2 moved onto UDP. It folds the transport and TLS handshakes into one flight — one round trip, zero on a resumed session — and carries a connection ID independent of address and port. That ID is what makes connection migration possible, and it is also what breaks load balancers that assume a flow stays on one 5-tuple.

Alt-Svc is how the client finds out

The first connection to an origin is always over HTTP/2 on TCP, because the client has no idea yet. The response carries an advertisement: Alt-Svc: h3=":443"; ma=86400. Parsed, that is protocol h3, authority :443 and a freshness lifetime of 86400 seconds, or 24 hours. On the next connection to that origin the client tries QUIC first, so the upgrade lands on a subsequent visit and never on the first one.

ma is the part that bites. While the advertisement is fresh, the client tries HTTP/3 first on every new connection — including after HTTP/3 has failed repeatedly. Model UDP:443 silently dropped by a middlebox: the client burns 15 seconds in QUIC probe-timeout backoff (1, 2, 4 then 8 seconds) before falling back to HTTP/2. At 20 visits a day that is 300 wasted seconds daily until the cache expires a day later. Start the TCP connection in parallel instead of waiting for QUIC to give up, and the identical blocked path resolves in 0.1 seconds. The fallback penalty is a design choice, not a protocol cost.

0-RTT and migration are the two sharp edges

0-RTT lets a returning client send application data in the very first flight, using a ticket from the previous session. That data is replayable — anyone who captures the flight can send it again — so only requests that are safe to repeat belong in it. A “create order” call in 0-RTT is a duplicate order waiting for a reason.

Connection migration is the other edge. Because QUIC keys the connection on its connection ID rather than the address, a client that roams from Wi-Fi to cellular keeps the same connection. Put a load balancer that hashes the 5-tuple in front of that and the continued connection lands on a different backend: with eight backends, a model of the same client before and after roaming picks backend 7 and then backend 4. The protocol’s mobility becomes the load balancer’s problem.

When it breaks

The first failure is an Alt-Svc cached on the client while the network drops UDP. It presents as a slow first byte on every navigation for a whole day, with nothing unusual in the server log — the QUIC Initials never arrive, so there is nothing to log. Compare server-side HTTP/3 connection counts against client-perceived latency; a wide gap with a healthy h2 path is the signature. Shorten ma, race the TCP connection, and do not advertise h3 on paths you cannot verify.

The second failure is connection migration breaking session affinity. A mobile client changes address mid-session, HTTP/3 keeps the connection alive, and the backend that now owns it has none of the cache or session state the old one had. It presents as intermittent auth failures, cache misses and half-completed uploads, only ever on mobile clients, which is what makes it hard to reproduce. Route on connection ID, or pin affinity to something that survives the address change.

Check it quickly

Confirm both paths are actually alive:

curl -sI https://example.com/ | grep -i alt-svc
curl -s --http3-only -o /dev/null -w '%{http_version} %{time_appconnect}\n' https://example.com/
nginx -T 2>/dev/null | grep -nE 'listen .*quic|http3|Alt-Svc'
ss -lun | grep -E ':443\b'

The first should print an h3 advertisement with a bounded ma. The second prints 3 and a small connect time if UDP works, or fails outright if the path blocks it — a failure here while the first succeeds is the middlebox case. The third shows whether the config actually wires QUIC and the header together, and the fourth proves a UDP socket is bound on 443.

Sources

RFC 9114 HTTP/3, HTTP/3 semantics over QUIC, checked 2026-09-16.
RFC 7838 HTTP Alternative Services, the Alt-Svc header and its freshness lifetime, checked 2026-09-16.
ngx_http_v3_module, the nginx QUIC and HTTP/3 directives, checked 2026-09-16.
RFC 9000 QUIC, stream-level loss recovery, connection IDs and 0-RTT, checked 2026-09-16.

SNI lets one IP host many TLS sites

Mon, 07 Feb 2028 00:00:00 +0000

Server Name Indication (SNI) sends the hostname during the TLS handshake, so one IP address can serve many different certificates and sites. Before SNI, the math was brutal: one certificate per IP, one IP per site, and IPv4 addresses spent like water. Name-based virtual hosting worked for plaintext HTTP but broke for TLS, because the server had to choose a certificate before the encrypted request revealed which site the client wanted. SNI resolves the paradox by moving the hostname earlier — into the handshake itself, ahead of encryption.

The practical result is the modern shared edge: CDNs, PaaS routers, and single-box multi-tenant servers all multiplex thousands of certificates onto few addresses. But the mechanism has sharp edges worth knowing — privacy leakage, legacy clients, and the default-certificate trap — because each bites exactly when a new tenant onboards or an old client complains.

The name goes first

During the handshake, before keys are exchanged, the client sends the hostname it wants, and the server selects a matching certificate for that vhost. Because the name arrives before encryption, nginx can route and pick the right cert in one connection. The extension lives in the ClientHello message, the very first TLS flight, so no round trip is added — selection happens inline with the handshake the client was already performing.

This ordering also explains why SNI cannot be retrofitted server-side alone. The client must send the extension; a client that never learned SNI gets whatever certificate the server offers by default, and validates it against the name it wanted. Ancient embedded libraries, decade-old payment terminals, and industrial controllers still show up without SNI in real fleets — know your client population before assuming universal support.

Match by server_name block

The hostname is routing metadata, not secret data: it travels in plaintext so a load balancer can see it. nginx matches it against server_name to choose the right server block and certificate path. Each server block carries its own certificate and key directives, and nginx selects among blocks sharing one listen socket by comparing the SNI value against server_name entries — exact names first, then leading wildcards, then trailing wildcards, then regex, mirroring HTTP Host matching.

Keep the TLS server_name list and the HTTP Host expectations identical. A common misconfiguration serves the right certificate but the wrong application: SNI matched block A while the Host header routes to block B, producing signed-but-wrong responses. Mirror the names and test both layers.

Control the default fallback

When no vhost matches, the first configured certificate is offered as the default. Order your listen 443 ssl blocks so the fallback is what you want to serve for unknown names. The default block answers three kinds of clients: scanners probing your IP, SNI-less legacy clients, and typosquatted or expired-DNS names pointing at you. Each deserves a deliberate answer — a neutral landing page, a connection close, or a 444-style drop — not whichever tenant happened to be configured first.

Mark the intended default explicitly with default_server so reordering files never silently changes behavior. And monitor the fallback: a traffic rise there is early signal of DNS misconfiguration, expiry elsewhere, or active scanning.

When it breaks

The classic failure is the wrong-certificate alert after adding a tenant: the new server block exists, the certificate files are valid, but clients see the old default. Causes rank by frequency: the block was added to a file nginx never loaded (missing include or failed reload), server_name has a typo the eye skips, or two blocks claim the same name and the first wins. Diagnose with nginx -T dumping the effective config — read what the server sees, not what the files suggest — and test with openssl s_client -servername to observe exactly which certificate each name receives.

The second failure is the privacy leak nobody planned for: SNI hostnames travel in cleartext, visible to every middlebox and passive observer between client and server. For sensitive tenants this leaks browsing intent even under fully valid TLS. Where that matters, Encrypted Client Hello is the emerging answer, but deployment is partial — document the exposure for tenants whose threat model includes network observers rather than promising secrecy TLS was never designed to give at this layer.

Check it quickly

Verify per-name certificates and the fallback:

nginx -T 2>&1 | grep -B2 -A4 'server_name\|ssl_certificate ' | head -n 40
openssl s_client -connect 203.0.113.10:443 -servername shop.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer
openssl s_client -connect 203.0.113.10:443 -servername unknown.invalid </dev/null 2>/dev/null | openssl x509 -noout -subject

Each name must return its own certificate; the unknown name must return the deliberate default.

Sources

TLS SNI overview, Explains SNI purpose and privacy tradeoffs, checked 2026-06-01.
nginx Server Name Indication, official guide to HTTPS server configuration, checked 2026-09-05.

gzip, HTTP/2, and Brotli need separate verification

Fri, 28 Jan 2028 00:00:00 +0000

HTTP/2 changes HTTP transport framing and multiplexing; gzip and Brotli encode representation data. Enabling HTTP/2 does not automatically compress response bodies, and enabling gzip does not prove that a client negotiated HTTP/2. HTTP/2 header compression is another mechanism again. A reliable check records the negotiated protocol, response Content-Encoding, transferred body size, and the bytes obtained after decoding.

When it breaks

Requesting Accept-Encoding: gzip, br and saving the result as .br does not prove Brotli was used. The server may choose gzip or send an acceptable identity representation. The response header names the actual coding. Guessing from the request list or output filename can lead to applying the wrong decoder and reporting compression results that never occurred.

Brotli support is also a deployment capability, not an implication of nginx being installed. Separate modules provide Brotli filtering or precompressed-file handling. Their availability and build compatibility must be established for the actual binary and configuration. Adding an unsupported directive can prevent configuration validation, while merely advertising Brotli from the client cannot install server functionality.

Automatic client decoding creates another measurement trap. curl --compressed can save a large decoded file after receiving a much smaller encoded body. Comparing that file’s size with a raw compressed output compares different things. Conversely, using --http2 without checking the negotiated version can mistake an allowed protocol fallback for a successful HTTP/2 test.

Check it quickly

Save the script as check-h2-coding.py and run it with Docker, Python, OpenSSL, and a curl build supporting HTTP/2. The recorded client was curl 8.7.1 with nghttp2; the server was nginx 1.28.0 on Linux arm64. It generates a short-lived local certificate and explicitly trusts that certificate with --cacert, while publishing only a loopback port:

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 gzip,hashlib
payload=(b'{"message":"'+b'HTTP content coding and transport are separate. '*1000+b'"}\n')
with TemporaryDirectory(prefix='xbcatm-local-tls-') as directory:
 root=Path(directory);cert=root/'cert.pem';key=root/'key.pem'
 result=subprocess.run(['openssl','req','-x509','-newkey','ec','-pkeyopt','ec_paramgen_curve:prime256v1',
 '-nodes','-keyout',str(key),'-out',str(cert),'-days','1','-subj','/CN=localhost',
 '-addext','subjectAltName=DNS:localhost,IP:127.0.0.1'],capture_output=True,text=True)
 assert result.returncode==0,result.stderr
 configuration=config('location = /app.json {} location / { return 404; }',
 'gzip on; gzip_types application/json; gzip_vary on; types { application/json json; }')
 configuration=configuration.replace('listen 8080;', 'listen 8080 ssl; http2 on; ssl_certificate /srv/cert.pem; ssl_certificate_key /srv/key.pem;')
 files={'cert.pem':cert.read_bytes(),'key.pem':key.read_bytes(),'app.json':payload,
 'brotli.conf':'events {} http { brotli on; server { listen 8080; } }'}
 with lab(configuration,files) as (proxy,request):
 probe=docker('exec',proxy,'nginx','-t','-c','/srv/brotli.conf',check=False)
 assert probe.returncode!=0 and 'unknown directive "brotli"' in probe.stderr
 results={'brotli_directive_supported':False}
 for name,version,accept,decode in [
 ('h2_gzip','2','gzip, br',False),('h1_gzip','1.1','gzip',False),
 ('h2_br_only','2','br',False),('h2_identity','2','identity',False),
 ('h2_decoded','2','gzip',True)]:
 output=root/(name+'.body');header=root/(name+'.headers')
 args=['curl','--silent','--show-error','--fail','--noproxy','*','--cacert',str(cert),
 '--http2' if version=='2' else '--http1.1','--header','Accept-Encoding: '+accept,
 '--output',str(output),'--dump-header',str(header),'--write-out','%{http_version}\n%{size_download}\n',
 f'https://127.0.0.1:{request.port}/app.json']
 if decode:args.insert(1,'--compressed')
 run=subprocess.run(args,capture_output=True,text=True,timeout=15);assert run.returncode==0,run.stderr
 actual,download=run.stdout.strip().splitlines();assert actual==version,(name,run.stdout)
 headers={k.lower():v.strip() for line in header.read_text().splitlines() if ':' in line for k,v in [line.split(':',1)]}
 body=output.read_bytes();encoded='gzip' in accept
 assert headers.get('content-encoding')==('gzip' if encoded else None)
 assert (gzip.decompress(body) if encoded and not decode else body)==payload
 assert headers['vary']=='Accept-Encoding'
 results[name]={'protocol':actual,'content_encoding':headers.get('content-encoding','identity'),
 'download_body_bytes':int(download),'saved_file_bytes':len(body)}
 assert results['h2_gzip']['download_body_bytes']<len(payload)
 assert results['h2_decoded']['saved_file_bytes']==len(payload)
 rejected={}
 for path in ['/key.pem','/cert.pem','/brotli.conf']:
 run=subprocess.run(['curl','--silent','--show-error','--noproxy','*','--cacert',str(cert),
 '--http2','--output',str(root/'rejected.body'),'--write-out','%{http_code}',
 f'https://127.0.0.1:{request.port}'+path],capture_output=True,text=True,timeout=15)
 assert run.returncode==0 and run.stdout=='404',(path,run.stdout,run.stderr)
 rejected[path]=404
 results['non_asset_statuses']=rejected
 results['original_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

The certificate includes the loopback IP in its subject alternative names, so the local HTTPS request can validate both trust and the requested identity. The fixture does not disable certificate verification. Only the JSON asset is routed for serving; requests for the key, certificate, and probe configuration must return 404. Temporary key material stays within the disposable test files and image, and the experiment removes its containers, image tags, network, and temporary files afterward.

The synthetic JSON representation contains 48,015 bytes. Over negotiated HTTP/2, a request advertising gzip and Brotli receives Content-Encoding: gzip and a 381-byte body in the recorded run. Decoding reproduces every original byte. Explicit HTTP/1.1 produces gzip too. These outcomes show that the body coding works across both tested transports rather than depending on HTTP/2 being selected.

An HTTP/2 identity request receives 48,015 unencoded bytes. A request advertising only br also receives identity in this configuration, which remains acceptable under that header. The fixture separately tests a configuration containing brotli on and requires nginx to reject it as an unknown directive. Together, those observations establish that this tested setup did not serve Brotli.

With --compressed, curl still reports a 381-byte downloaded body, but the saved file contains the original 48,015 decoded bytes. The script checks both measurements and the content itself. The downloaded-body figure excludes other transport overhead; it is not a complete packet capture or a measurement of all TLS and HTTP/2 framing bytes on the connection.

Verify capabilities before comparing performance

The example enables HTTP/2 explicitly on a TLS listener and checks curl’s resulting protocol value. It serves static content locally, so it makes no claim about an upstream application’s transport. A reverse proxy can negotiate one protocol with clients and use another with its backend; inspect each connection separately when that distinction affects capacity or behavior.

For Brotli deployment, establish the module or precompressed serving path, then require an actual br response and a successful Brotli decode before measuring its savings. This experiment provides a negative capability check, not a Brotli benchmark. Installing a module or rebuilding nginx is a separate configuration change with its own compatibility and serving checks.

Finally, compare representative content with consistent measurements. This highly repetitive test body demonstrates correct coding and decoding, not a universal compression ratio or page-speed improvement. Record cache selection through Vary, encoded body bytes, decoding correctness, CPU use, and client latency as distinct observations. Neither a transport version nor a codec name alone establishes that a page became faster.

Sources

nginx gzip module, response content coding and Vary configuration, checked 2026-09-12.
nginx HTTP/2 module, HTTP/2 enablement and TLS ALPN requirements, checked 2026-09-12.
Google ngx_brotli module README, the separate Brotli filter/static modules and build requirements, checked 2026-09-12.
RFC 9110 HTTP Semantics, content-coding negotiation and identity acceptability, checked 2026-09-12.

Choose whether nginx redirects the client or rewrites internally

Fri, 21 Jan 2028 00:00:00 +0000

An nginx redirect and an internal rewrite change different parts of the request flow. A redirect returns a status and Location for the client to consider, potentially causing a new request. An internal rewrite changes nginx’s current URI while processing the existing request. Choosing between them determines whether the client sees a new address, whether location selection runs again, and how the final handler receives path and query data.

When it breaks

Replacing an intended internal mapping with a redirect adds a client round trip and exposes a different URL. Replacing a permanent public move with an internal rewrite leaves clients using the old address. Neither return nor rewrite should be treated as a universal shorthand that always defaults to the same redirect behavior; explicit status codes and rewrite flags make the intended transition reviewable.

Status choice affects method semantics and caching. A 307 or 308 preserves the request method when automatically redirected, while 301 and 302 allow the historical POST-to-GET change. Permanent does not mean every client instantly updates every stored link, and temporary does not mean a response can never be cached. Cache directives, request context, and client behavior still matter.

Internal rewrites can also select an unexpected handler or repeatedly match themselves. The last flag starts another location search for the changed URI, whereas break continues processing in the current location after ending the current rewrite sequence. Query arguments can be appended or discarded according to the replacement syntax. Treating these distinctions as interchangeable can cause wrong files, duplicate parameters, or HTTP 500 loops.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image. The recorded environment used nginx 1.28.0 on Linux arm64 with Docker 29.3.1. It builds and syntax-checks a disposable configuration, publishes only a loopback port, tests real responses without automatic redirect following, and removes its own resources. A small static file makes the break handler distinguishable:

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'

locations=r'''
location = /old { return 308 /destination$is_args$args; }
location = /destination { return 200 "$request_method|$uri|$args"; }
location /last/ { rewrite ^/last/(.*)$ /target/$1 last; }
location /break/ { rewrite ^/break/(.*)$ /target/$1 break; add_header X-Route break always; }
location /target/ { add_header X-Route target always; return 200 "$uri|$args"; }
location /append/ { rewrite ^/append/(.*)$ /target/$1?new=1 last; }
location /discard/ { rewrite ^/discard/(.*)$ /target/$1? last; }
location /loop/ { rewrite ^ /loop/again last; }
'''
with lab(config(locations,'absolute_redirect off;'),{'target/item':'static-file'}) as (container,request):
 status,headers,body=request('/old?x=1',method='POST',body='public-body')
 assert status==308 and headers['location']=='/destination?x=1'
 status,headers,body=request(headers['location'],method='POST',body='public-body');assert status==200 and body==b'POST|/destination|x=1'
 status,headers,body=request('/last/item?x=1');assert status==200 and headers['x-route']=='target' and body==b'/target/item|x=1'
 status,headers,body=request('/break/item?x=1');assert status==200 and headers['x-route']=='break' and body==b'static-file'
 status,headers,body=request('/append/item?old=2');assert status==200 and body==b'/target/item|new=1&old=2'
 status,headers,body=request('/discard/item?old=2');assert status==200 and body==b'/target/item|'
 assert request('/loop/start')[0]==500
 assert 'rewrite or internal redirection cycle' in docker('exec',container,'cat','/tmp/error.log').stdout
 print('return 308 creates a client-visible redirect; the explicit follow-up retains POST and the query')
 print('last restarts location selection; break keeps the location while changing the URI used by its static handler')
 print('rewrite appends old query arguments unless discarded explicitly; an internal rewrite cycle is stopped with HTTP 500')

A POST to /old?x=1 receives status 308 and Location: /destination?x=1. The fixture disables absolute redirect generation so this local target remains relative and does not depend on an assigned host port. The response is inspected before any follow-up, establishing exactly what nginx told the client to do.

The script then explicitly sends a second POST to that Location and receives POST|/destination|x=1. This verifies the destination and query when following with the intended method. It does not claim to test every browser’s automatic redirect handling or cache behavior; the test client deliberately controls the follow-up rather than silently hiding it.

The request /last/item?x=1 rewrites to /target/item and starts location selection again. The target location returns its diagnostic URI and an X-Route value of target. By contrast, /break/item?x=1 changes the URI but remains in the original location, whose static handler serves /srv/target/item and marks the response as break.

These outcomes show that break does not stop all request processing. It stops the current rewrite sequence while allowing the configured content handling to continue. Likewise, last is not an external redirect: the client receives the final 200 response directly, without a Location hop to the internally selected target.

For /append/item?old=2, the replacement’s new=1 query is combined with the original arguments, producing new=1&old=2. The discard example ends its replacement with a question mark and produces no arguments. Both cases assert the final values, preventing a redirect or rewrite test from overlooking duplicate, leaked, or unexpectedly removed query data.

The loop route repeatedly rewrites into its own matching path family. nginx stops the cycle with HTTP 500 and writes an internal-redirection-cycle diagnostic to its error log. A successful syntax check therefore does not prove a request cannot loop; only exercising the matching paths establishes that the configured transitions terminate as intended.

Test the transition the client actually receives

Use a direct return with an explicit status for simple public redirects, and reserve rewrite patterns for mappings that require their matching behavior. Keep destination paths and query handling explicit. Avoid deriving unrestricted redirect destinations from untrusted input, and verify canonical-host policy where an absolute target depends on incoming host information.

For a public migration, test status, Location, method expectations, and the final target before choosing cache policy. A temporary status is not a substitute for explicit cache controls when reuse must be prevented. For internal mappings, test the final location, filesystem or upstream path, arguments, and error cases.

Include near-miss paths and already-normalized targets in regression checks. A rule that works once can still redirect its own destination or collide with a later location. Keep the evidence for both the original response and the eventual result so a routing change remains explainable after deployment.

Sources

nginx rewrite module, return redirects, last versus break, query handling, and rewrite limits, checked 2026-09-12.
RFC 9110 HTTP semantics, redirect status meanings and method-preservation requirements, checked 2026-09-12.
RFC 9111 HTTP caching, cacheability depending on response semantics and cache controls, checked 2026-09-12.

An nginx prefix is a candidate until matching finishes

Mon, 17 Jan 2028 00:00:00 +0000

An nginx location selects configuration for a request within the chosen server. For the flat prefix and regex locations tested here, an exact match finishes the search; otherwise nginx remembers the longest matching prefix and can then choose the first matching regex. If no applicable regex wins, the remembered prefix supplies the configuration. This is a selection process, not simply the first block encountered in the file.

When it breaks

A prefix is a string prefix, not automatically a complete path segment. location /api also matches /apix. If the intended family is the endpoint /api plus descendants under /api/, express those boundaries deliberately. Depending on an unstated segment boundary can apply the wrong handler, cache policy, or access rule to paths that merely share the same initial letters.

The longest ordinary prefix is not always the final choice. A regex matching .php can take a request that also matched a more detailed API prefix. Moving that prefix above the regex does not change the basic priority rule. Configuration order matters for competing regexes, while ordinary prefixes are compared by matching length rather than declaration position.

The ^~ modifier suppresses regex searching when that prefix is the selected longest prefix at the relevant level. It is not a regex operator, and it is not an unconditional protection for every path that begins with a shorter marked prefix. Nested location structures and internal redirects require additional reasoning; the following fixture intentionally uses a flat server to make each selection unambiguous.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image available. The recorded environment used nginx 1.28.0 on Linux arm64 with Docker 29.3.1. It builds a temporary configuration image, validates it with nginx -t, sends real HTTP requests through a port published only on host loopback, and removes its own containers, image tags, 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'

locations=r'''
location / { return 200 "fallback"; }
location /api/ { return 200 "api-slash"; }
location /api/admin/ { return 200 "admin"; }
location = /api { return 200 "exact"; }
location /api { return 200 "api-string"; }
location ^~ /static/ { return 200 "static"; }
location ~ \.php$ { return 200 "php-regex"; }
'''
with lab(config(locations)) as (container,request):
 cases={'/api':'exact','/api?x=1':'exact','/apix':'api-string','/api/users':'api-slash','/api/admin/log':'admin','/api/admin/test.php':'php-regex','/static/test.php':'static','/unmatched':'fallback'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 print('exact matching ignores the query; ordinary prefixes use longest string match, including /api matching /apix')
 print('a regex overrides the ordinary longest prefix, while the selected ^~ prefix skips that regex')

Both /api and /api?x=1 return exact. The query string does not participate in location matching, so adding an argument does not make the exact path stop matching. The selected block explicitly returns that marker. Exact matching selects configuration; it does not inherently mean a filesystem root is read or a particular application is invoked.

The request /apix returns api-string, demonstrating that the plain /api prefix reaches beyond a complete API segment. /api/users instead returns api-slash, because /api/ is the longer matching prefix. /api/admin/log returns admin, showing the next level of ordinary longest-prefix selection without relying on the order those blocks appear.

Requesting /api/admin/test.php returns php-regex. The long /api/admin/ prefix was a candidate, but the regex phase selected another block. This is the important failure shape for a route whose author assumed a longer prefix automatically defeated a general script handler. A successful status alone would conceal the mistake, so each handler returns a distinguishable body.

Requesting /static/test.php returns static, because the selected /static/ prefix has ^~. The same suffix regex therefore does not take that request. An unmatched path returns the broad fallback marker. Together, these cases demonstrate the actual selection boundaries rather than merely proving that nginx accepts the configuration syntax.

The client sends the paths explicitly and checks response bodies as well as statuses. The fixture contains no real authentication policy or script execution, so its markers validate routing decisions only. When applying the pattern to a protected endpoint, test the actual handler and access behavior that will run after selection.

Review the selected handler and its later transitions

Start with the intended URL families, then list exact endpoints, descendant prefixes, and any overlapping regexes. Include near-miss paths such as /apix, case variants where relevant, and encoded or normalized forms. nginx matches a normalized URI, so a security review based only on the raw request text can miss which configuration ultimately applies.

Inspect the effective configuration, including included files and the selected virtual server. A correct location in a server block that the request never enters cannot fix routing in another block. Use controlled response markers or logs during verification rather than inferring selection from a familiar page returned by several handlers.

Finally, account for rewrites, index handling, and other internal redirects that can trigger a new location search. The first selected block may not be the final handler. Test the full request path and preserve enough evidence to explain both the initial match and the response actually produced.

Sources

nginx core location directive, normalized URI matching, exact matches, prefixes, and regex selection, checked 2026-09-12.
How nginx processes a request, server selection and location-based request handling, checked 2026-09-12.

nginx burst capacity decides which requests wait and which are rejected

Wed, 05 Jan 2028 00:00:00 +0000

nginx request limiting uses a leaky-bucket method to account for excess requests against a configured rate. The burst allowance determines how much excess can be accepted, while nodelay and delay affect when accepted excess proceeds. These are admission and scheduling decisions. They do not make every request above the nominal rate fail, nor do they measure concurrent application work.

When it breaks

Describing nodelay as “drop the excess immediately” reverses its useful effect. Within the burst allowance, it lets excess requests proceed without the normal delay. Requests beyond that allowance are rejected. The accepted burst still consumes capacity that must recover over time; repeatedly arriving bursts do not receive a fresh allowance merely because earlier requests completed quickly.

Delayed requests also do not automatically become a sequence of 503 responses. Requests admitted within the burst can wait and then receive successful application responses. Rejection occurs when the configured allowance is exceeded, with the selected rejection status. A client’s own deadline may expire while waiting, so an acceptable server-side queue can still be unsuitable for that client’s latency contract.

Configuration syntax needs verification too. In nginx 1.28.0, writing burst=0 is rejected even though omitting burst selects a default allowance of zero. An invalid configuration is not an especially strict working limiter. Use syntax validation and actual requests, and ensure the protected location reaches request limiting rather than ending in an earlier rewrite-phase return.

Check it quickly

Save this as check-burst.py and run it with Python, Docker, and the pinned images. The recorded setup uses nginx 1.28.0 and a real HTTP backend. Each case gets a separate public fixture key, a one-request-per-second rate, and six clients released together. nginx exposes its limit decision in a response header:

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 do_GET(self):
 body=json.dumps({'path':self.path,'method':self.command}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
from concurrent.futures import ThreadPoolExecutor
import threading
extra='limit_req_zone $arg_k zone=budget:1m rate=1r/s; add_header X-Limit $limit_req_status always;'
locations='location / { return 404; }\n'
for path,policy in [('delay','burst=2'),('nowait','burst=2 nodelay'),('partial','burst=2 delay=1'),('strict','')]:
 locations+=f'location /{path} {{ limit_req zone=budget {policy}; limit_req_status 429; proxy_pass http://backend:8081; }}\n'
locations+='location /default { limit_req zone=budget; proxy_pass http://backend:8081; }'
invalid=config('location / { limit_req zone=b burst=0 nodelay; proxy_pass http://backend:8081; }',
 'limit_req_zone $binary_remote_addr zone=b:1m rate=1r/s;')
with lab(config(locations,extra),{'invalid.conf':invalid},backend) as (proxy,request):
 results={}
 for mode in ['delay','nowait','partial','strict']:
 barrier=threading.Barrier(7)
 def client():
 barrier.wait();start=time.monotonic();status,headers,_=request('/'+mode+'?k='+mode)
 return {'status':status,'limit':headers.get('x-limit'),'elapsed':round(time.monotonic()-start,3)}
 with ThreadPoolExecutor(max_workers=6) as pool:
 futures=[pool.submit(client) for _ in range(6)];barrier.wait();observed=[f.result() for f in futures]
 good=[r for r in observed if r['status']==200];bad=[r for r in observed if r['status']==429]
 assert len(good)==(1 if mode=='strict' else 3) and len(good)+len(bad)==6,observed
 assert all(r['limit']=='REJECTED' for r in bad)
 assert all(r['limit'] in {'PASSED','DELAYED'} for r in good)
 delayed=sum(r['limit']=='DELAYED' for r in good)
 assert delayed=={'delay':2,'nowait':0,'partial':1,'strict':0}[mode],observed
 if mode=='delay':assert sorted(r['elapsed'] for r in good)[-1]>=1.7
 if mode=='partial':assert max(r['elapsed'] for r in good)>=.7
 results[mode]=observed
 if mode=='nowait':
 assert request('/nowait?k=nowait')[0]==429
 time.sleep(1.1);assert request('/nowait?k=nowait')[0]==200
 results['nodelay_debt_then_recovery']=[429,200]
 first=request('/default?k=default');second=request('/default?k=default')
 assert first[0]==200 and second[0]==503 and second[1]['x-limit']=='REJECTED'
 results['default_rejection']=503
 rejected=docker('exec',proxy,'nginx','-t','-c','/srv/invalid.conf',check=False)
 assert rejected.returncode!=0 and 'invalid burst value' in rejected.stderr
 results['literal_burst_zero_valid']=False
 print(json.dumps(results,sort_keys=True))

With burst=2, one request proceeds immediately and two accepted excess requests are delayed. The recorded successful responses complete near zero, one, and two seconds; three other requests return 429. Their headers distinguish PASSED, DELAYED, and REJECTED. These observations show accepted waiting work completing successfully, rather than treating every delayed request as an eventual error.

With burst=2 nodelay, three requests succeed without the limiter marking them DELAYED, and three return 429. An immediate additional request using the same key is also rejected. After waiting 1.1 seconds, another request succeeds. The experiment therefore checks both immediate burst admission and the continuing debt that prevents the next burst from bypassing the configured rate accounting.

With burst=2 delay=1, two accepted requests proceed without delay and the third is delayed by about one second. Three are rejected. Omitting burst admits only one of the six closely arriving requests, with five rejections. The tests assert decision classes and broad delay bounds rather than presenting millisecond measurements as a portable performance benchmark.

The protected comparison locations explicitly choose 429. A separate location leaves the rejection status at its default and returns 503 on the second immediate request. Finally, nginx syntax-checks a disposable configuration containing literal burst=0 and rejects it. The running valid configuration remains separate from that failed candidate, so the negative syntax test does not interrupt the other cases.

Fit the waiting policy to the endpoint

Use delayed excess when smoothing accepted arrivals is useful and waiting fits the request deadline. Use nodelay when a bounded immediate burst is acceptable to the backend. Partial delay provides a middle region before pacing starts. None of these settings alone caps the number of long-running requests already executing, so do not confuse arrival rate with concurrent resource occupancy.

Choose the key as carefully as the rate. The query key here makes independent cases reproducible; it is intentionally client-controlled and is not a production identity scheme. A client that can change its key can change which budget it consumes. An IP key has different boundaries, including multiple users sharing an address and trusted proxy handling.

Expose enough information to separate application errors from limiter rejections and delayed requests. A 429 response can describe the rate policy and may include Retry-After when a meaningful retry time is available, but this example does not generate that header automatically. Verify the effective status, scheduling, and backend behavior instead of assuming a directive name describes the complete client experience.

Sources

nginx request limit module, leaky-bucket accounting, burst, delay, nodelay, and rejection status, checked 2026-09-12.
RFC 6585 additional HTTP status codes, the meaning of 429 Too Many Requests, checked 2026-09-12.

nginx chooses the first matching regex, not a specificity score

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

nginx does not assign a general specificity score to every location expression. Ordinary prefixes are selected by matching length, exact locations can finish the search, and competing regex locations are evaluated in declaration order. A regex that looks narrower to a human can lose to a broader expression placed earlier. Mixing these selection rules is a common reason apparently careful routing changes affect unexpected paths.

When it breaks

A general suffix regex for .css can win before a later regex restricted to /assets/. The later expression may look more specific because it names a directory, but nginx does not compare the apparent specificity of those two patterns. If they both match, their order decides which configuration handles the request in the flat structure used here.

Reordering ordinary prefix blocks is a different operation. Moving /assets/ above / does not make it win more strongly; its longer matching prefix already gives it priority when the prefix result applies. A review that treats all location declarations as one first-match list can therefore make ineffective changes while missing the regex order that actually controls the failing route.

A shorter ^~ prefix is also not a permanent shield around an entire subtree. If a longer ordinary prefix is selected, the shorter marked prefix is no longer the candidate that suppresses the regex phase. Adding one seemingly harmless more-detailed prefix can therefore allow a suffix regex to take requests that previously stayed in the marked location.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image. The recorded environment used nginx 1.28.0 on Linux arm64 with Docker 29.3.1. It builds two temporary configurations, checks each with nginx -t, and issues real requests through host-loopback ports. Each configuration uses only flat locations, and its containers, image tags, and private network are cleaned up:

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'

prefixes=[
 'location / { return 200 "fallback"; }',
 'location /assets/ { return 200 "asset-prefix"; }',
 'location = /assets/exact.css { return 200 "exact"; }',
 'location ^~ /static/ { return 200 "static-prefix"; }',
 'location /static/dynamic/ { return 200 "dynamic-prefix"; }']
regexes=[r'location ~ \.css$ { return 200 "generic-css"; }',r'location ~ ^/assets/ { return 200 "asset-regex"; }']
for reverse,expected in [(False,'generic-css'),(True,'asset-regex')]:
 ordered_prefixes=list(reversed(prefixes)) if reverse else prefixes
 ordered_regexes=list(reversed(regexes)) if reverse else regexes
 locations='\n'.join(ordered_prefixes+ordered_regexes)+'\n'+r'location ~* \.txt$ { return 200 "case-folded-text"; }'
 with lab(config(locations)) as (container,request):
 cases={'/assets/file.css':expected,'/assets/exact.css':'exact','/static/file.css':'static-prefix','/static/dynamic/file.css':'generic-css','/static/dynamic/plain':'dynamic-prefix','/README.TXT':'case-folded-text','/elsewhere.CSS':'fallback','/elsewhere':'fallback'}
 for path,wanted in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==wanted,(path,status,body)
print('reversing the matching regex declarations changes the winner; the first matching regex is not necessarily the most specific')
print('exact locations and longest-prefix selection ignore declaration order; a longer ordinary prefix can make a shorter ^~ prefix irrelevant')

The first configuration places the .css regex before the regex beginning with /assets/. Requesting /assets/file.css returns generic-css. The second configuration reverses those regexes, and the identical request returns asset-regex. Nothing in the request became more or less specific; only the order of two simultaneously matching patterns changed.

The script also reverses the ordinary prefix declarations between configurations. Their relevant results remain stable. /static/dynamic/plain continues to use the longer ordinary prefix, and the broad fallback handles an unrelated path. This comparison separates textual rearrangement of prefixes from textual rearrangement of regexes instead of assuming both edits have the same routing effect.

An exact /assets/exact.css location wins in both configurations despite matching both regex patterns. It returns exact. The test therefore includes a route deliberately isolated from regex ordering, rather than presenting the first matching regex as an unconditional rule that overrides every other location type.

The path /static/file.css stays in the ^~ /static/ prefix and returns static-prefix. But /static/dynamic/file.css has a longer ordinary prefix, so the .css regex is considered and returns generic-css. This verifies the selected-prefix qualification on ^~; the modifier belongs to that location, not to an invisible inherited protection on every deeper prefix.

Case modifiers are tested separately. The ~* text-file pattern matches /README.TXT, while the case-sensitive .css pattern does not match /elsewhere.CSS, which reaches the fallback. These are observations for the explicit regexes and Linux environment in the fixture, not a claim that all filesystem paths or every platform use identical case rules.

Make overlaps visible in review

For each regex, identify paths that also match earlier expressions and record which handler is intended to win. Include boundary cases where two patterns overlap, as well as cases where neither matches. A test that exercises only one regex in isolation cannot reveal the priority conflict introduced when another expression is added before it.

Use exact or prefix locations when they naturally describe the route, and keep intentional regex overlaps understandable. A regex is not inherently wrong, but its ordering becomes part of the service contract. Changes to included configuration can alter the effective sequence, so inspect the complete loaded configuration rather than reviewing a file fragment without its surrounding context.

When adding a longer prefix below an existing marked prefix, retest suffix routes through that new path. Do not assume the earlier ^~ still governs the request. Finally, verify downstream behavior such as cache headers, proxying, and access control in the winning block; selecting the expected marker is a routing test, not proof that every policy inside that block is correct.

Sources

nginx core location directive, first matching regex, prefix priority, and case modifiers, checked 2026-09-12.
How nginx processes a request, configuration selection inside the matched server, checked 2026-09-12.
nginx 1.28.0 core implementation, version-specific prefix and regex location-search behavior, checked 2026-09-12.

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.

Enable gzip explicitly, then verify negotiation and decoded bytes

Sun, 29 Aug 2027 00:00:00 +0000

gzip is a response content coding: nginx can send a compressed representation that an accepting client decodes. Enabling it requires gzip on; gzip_types extends the eligible MIME types but does not activate compression by itself. The result depends on the response, request capabilities, and effective configuration. A smaller body is useful only if it still decodes to the intended content.

When it breaks

A MIME list beneath gzip off changes no response into gzip. Another common omission is gzip_vary on. nginx does not unconditionally add Vary: Accept-Encoding merely because compression occurred; the directive controls that behavior. A shared cache selecting representations needs the relevant request-header dimensions, otherwise clients with different coding capabilities can receive an inappropriate stored response.

The minimum-length setting has a narrower contract than its name suggests. gzip_min_length determines length from the response’s Content-Length field. It does not necessarily know the final size of a response whose length is unspecified. A tiny dynamically streamed response can therefore be compressed even when an equally small static file falls below the configured threshold.

Measurements can also be misleading. The size of a decompressed output file is not the compressed transfer-body size, and compressed body bytes do not include all HTTP framing, headers, or TLS traffic. File extensions such as .gz prove nothing by themselves. Check the actual content coding and decode the bytes before interpreting any apparent bandwidth saving.

Check it quickly

Save this as check-gzip.py and run it with Python, Docker, and the pinned images. The recorded setup used nginx 1.28.0 on Linux arm64 and a small Python backend. nginx enables gzip at level three, allows JSON in addition to its built-in HTML eligibility, sets a 1,024-byte floor, and explicitly enables Vary:

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 gzip,hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 self.send_response(200);self.send_header('Content-Type','application/json')
 self.send_header('Connection','close');self.end_headers();self.wfile.write(b'{"ok":true}\n');self.close_connection=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
payload=json.dumps({'message':'compressible nginx response '*1000}).encode()
locations='''
location = /disabled.json { gzip off; gzip_types application/json; }
location = /novary.json { gzip_vary off; }
location = /stream { proxy_pass http://backend:8081; }
'''
extra='''
types { application/json json; text/html html; application/octet-stream bin; }
gzip on; gzip_types application/json; gzip_vary on; gzip_min_length 1024; gzip_comp_level 3;
'''
files={name:payload for name in ['large.json','other.bin','page.html','disabled.json','novary.json']};files['tiny.json']=b'{"ok":true}\n'
with lab(config(locations,extra),files,backend) as (_,request):
 results={}
 for encoding in ['gzip','identity','gzip;q=0','br']:
 status,h,b=request('/large.json',headers={'Accept-Encoding':encoding});assert status==200
 if encoding=='gzip':assert h['content-encoding']=='gzip' and gzip.decompress(b)==payload and len(b)<len(payload)
 else:assert 'content-encoding' not in h and b==payload
 assert h['vary']=='Accept-Encoding'
 results[encoding]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b)}
 for path,encoded in [('/tiny.json',False),('/other.bin',False),('/page.html',True),('/disabled.json',False),('/novary.json',True),('/stream',True)]:
 status,h,b=request(path,headers={'Accept-Encoding':'gzip'});assert status==200
 assert (h.get('content-encoding')=='gzip')==encoded,(path,h)
 decoded=gzip.decompress(b) if encoded else b
 assert decoded==(files['tiny.json'] if path=='/stream' else files[path[1:]])
 if path=='/novary.json':assert 'vary' not in h
 results[path]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b),'vary':h.get('vary')}
 results['decoded_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

The large synthetic JSON representation is 28,015 bytes. With Accept-Encoding: gzip, its transferred response body is 246 bytes in the recorded run, and Python’s gzip decoder reproduces the original bytes exactly. This intentionally repetitive payload demonstrates operation and integrity; its compression ratio is not a prediction for production JSON, JavaScript, or arbitrary text.

Requests accepting identity, setting gzip;q=0, or advertising only br receive the original bytes without a Content-Encoding field. Zero quality disallows gzip. Advertising Brotli does not enable a Brotli compressor in this nginx configuration, and identity remains acceptable in that request. The eligible large responses carry Vary: Accept-Encoding, including the uncompressed variants.

The same synthetic payload served as an ineligible binary type remains uncompressed, while the HTML type is eligible without appearing in gzip_types. A location explicitly setting gzip off also remains uncompressed despite listing JSON. These controls separate type eligibility from the enable switch, rather than treating every absent coding as evidence that negotiation failed.

The 12-byte static JSON response stays uncompressed because its known length is below the floor. The backend returns the same 12 bytes without Content-Length, ending the response by closing its connection. nginx compresses that response into 32 bytes. The floor therefore does not guarantee that all tiny responses avoid compression, and this particular tiny payload actually grows.

A final location keeps gzip active but turns gzip_vary off. Its body still arrives gzip encoded, with no Vary field. This makes the missing-cache-dimension failure observable without requiring a real shared cache to misdeliver content. The fixture checks the header policy; a deployed cache’s representation selection should also be tested through that cache.

Tune the policy using representative responses

Select content types whose actual bytes compress well. Already compressed media or archives usually offer little benefit from another coding layer, while repetitive text may shrink substantially. Do not infer CPU cost from this byte-count experiment. Compare representative sizes, compression settings, server utilization, and client latency before choosing a level for a busy service.

Keep the response metadata honest through proxies. Content-Encoding tells the recipient how to decode the representation, while Vary tells caches which request fields affect selection. If an application already sends an encoded response, review that path separately rather than adding a misleading header to unencoded bytes. The decisive check remains negotiated headers plus a successful byte-for-byte decode.

Sources

nginx gzip module, enabling gzip, MIME eligibility, Content-Length thresholds, and Vary, checked 2026-09-12.
RFC 9110 HTTP Semantics, Accept-Encoding, Content-Encoding, and representation selection, checked 2026-09-12.

A request limit protects the budget named by its key

Sat, 28 Aug 2027 00:00:00 +0000

A request-rate limit applies to the identity expressed by its key, not automatically to a person, account, or endpoint. limit_req_zone stores shared state for those key values, and limit_req applies the zone while handling a request. Two locations using the same zone and key can consume the same budget. Choosing a variable therefore defines a real fairness and enforcement boundary.

When it breaks

A client-controlled identifier can turn one apparent limit into many independent allowances. If changing a query value changes the key, an untrusted client can select another budget. An empty key is more direct: nginx does not account for requests whose key evaluates to an empty value. A missing identity variable can therefore silently leave requests outside the intended limit.

An IP key measures an address, which may represent many users behind NAT or an intermediary. Forwarded address headers need an explicit trust policy before they become identity input. Trusting arbitrary X-Forwarded-For lets callers manufacture identities; ignoring a real trusted proxy’s address chain may instead put every user under the proxy’s own budget. Neither outcome is fixed by increasing the rate.

Shared memory scope matters too. A zone is shared among workers of the nginx instance; that does not create a fleet-wide counter across unrelated processes or machines. Compatible graceful reloads can retain zone state. Assuming that every configuration reload resets all allowances can make a test or recovery procedure misread continued rejections as a broken deployment.

Check it quickly

Save the script as check-limit-keys.py and run it with Python, Docker, and the pinned images. The recorded setup uses nginx 1.28.0 with two workers and a disposable HTTP backend. A deliberately slow allowance of one request per minute keeps each observation within the same budget interval; distinct fixture keys isolate the cases:

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 do_GET(self):
 body=json.dumps({'path':self.path,'method':self.command}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
from concurrent.futures import ThreadPoolExecutor
extra='''
limit_req_zone $arg_client zone=identity:1m rate=1r/m;
limit_req_zone $binary_remote_addr zone=address:1m rate=1r/m;
limit_req_status 429;
add_header X-Limit $limit_req_status always; add_header X-Worker $pid always;
'''
locations='''
location /a { limit_req zone=identity; proxy_pass http://backend:8081; }
location /b { limit_req zone=identity; proxy_pass http://backend:8081; }
location /dry { limit_req zone=identity; limit_req_dry_run on; proxy_pass http://backend:8081; }
location /ip { limit_req zone=address; proxy_pass http://backend:8081; }
location /open { proxy_pass http://backend:8081; }
'''
configuration=config(locations,extra).replace('worker_processes 1;','worker_processes 2;')
with lab(configuration,backend=backend) as (proxy,request):
 results={}
 assert request('/a?client=one')[0]==200 and request('/b?client=one')[0]==429
 assert request('/a?client=two')[0]==200
 results['same_zone_cross_location']=[200,429];results['changed_untrusted_key']=200
 empty=[request('/a') for _ in range(2)];assert all(r[0]==200 for r in empty)
 assert all(r[1].get('x-limit') is None for r in empty)
 results['empty_keys']=[{'status':r[0],'limit':r[1].get('x-limit')} for r in empty]
 first=request('/ip',headers={'X-Forwarded-For':'192.0.2.1'})
 second=request('/ip',headers={'X-Forwarded-For':'192.0.2.2'})
 assert first[0]==200 and second[0]==429;results['forged_forwarding_header']=[200,429]
 first=request('/dry?client=dry');second=request('/dry?client=dry')
 assert first[0]==second[0]==200 and second[1]['x-limit']=='REJECTED_DRY_RUN'
 results['dry_run']={'status':second[0],'limit':second[1]['x-limit']}
 first=request('/a?client=shared');assert first[0]==200;workers={first[1]['x-worker']}
 deadline=time.monotonic()+8
 while time.monotonic()<deadline and len(workers)<2:
 with ThreadPoolExecutor(max_workers=8) as pool:
 replies=list(pool.map(lambda _:request('/b?client=shared'),range(8)))
 assert all(r[0]==429 for r in replies);workers.update(r[1]['x-worker'] for r in replies)
 assert len(workers)==2,workers
 results['shared_budget_worker_ids']=sorted(workers)
 docker('exec',proxy,'nginx','-s','reload')
 wait(lambda:request('/open')[1]['x-worker'] not in workers)
 reply=request('/a?client=shared');assert reply[0]==429 and reply[1]['x-worker'] not in workers
 results['graceful_reload']={'status':reply[0],'worker':reply[1]['x-worker']}
 print(json.dumps(results,sort_keys=True))

/a?client=one succeeds, while /b?client=one returns 429 because both locations use the same zone. Changing the query identity to two gives a new successful request. This is useful as a controlled demonstration, but it is precisely why an unverified query parameter is unsuitable as the sole production identity for an abuse-resistant limit.

Two requests without the client argument both succeed and have no X-Limit decision value. The empty key was not accounted for. This control is important when a deployment derives identity from an optional header or an authentication result: normal traffic with a populated variable can look correctly limited while missing-variable traffic bypasses the intended accounting.

The IP-based location receives two requests with different fabricated X-Forwarded-For values. The first succeeds and the second returns 429. No real-IP trust configuration is installed, so the socket peer still supplies the address key. This verifies that merely sending a different forwarding header does not alter the configured identity in this setup; it does not authenticate any original internet user.

The dry-run location returns 200 on a request that would have been rejected, with REJECTED_DRY_RUN in the decision header. Accounting still occurs, but enforcement is disabled there. A successful response alone would hide this distinction. Use the dry-run decision variable when assessing a proposed policy instead of counting only client-visible rejections.

For a fresh shared key, the first request succeeds and subsequent requests return 429 from both observed worker process IDs. nginx then performs a graceful reload with the same zone configuration. A new worker serves the still-rejected key, demonstrating retained budget state rather than a reset. The test waits for a new worker identity before attributing the result to the reload.

Define identity, scope, and observation together

Decide whether the intended budget belongs to an address, authenticated account, route, or combination. Verify that its inputs exist and are trustworthy at the limiting phase. Sharing a zone across locations can intentionally create one service-wide budget, while separate zones create distinct accounting. Avoid assuming a location name itself becomes part of a key that never includes it.

Size zone memory for key cardinality as well as request volume. The documentation describes architecture-dependent state sizes; a 64-bit state is not the smaller 32-bit entry assumed by some estimates. Storage exhaustion can evict old state and, if allocation still fails, reject requests. This experiment checks enforcement semantics, not a measured maximum key capacity.

Finally, inspect effective configuration and decision telemetry after changes. Distinguish empty-key bypass, dry-run allowance, actual rejection, and preserved reload state. A working per-instance limiter does not prove a global tenant quota, and a request returning 429 does not by itself identify which intended user or route budget was consumed.

Sources

nginx request limit module, shared key state, empty keys, dry run, memory sizing, and decision variables, checked 2026-09-12.
nginx real IP module, trusted proxy boundaries when deriving a client address, checked 2026-09-12.
RFC 6585 additional HTTP status codes, 429 and identification of the rate-limited subject, 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 matches normalized paths and can select a location again

Thu, 26 Aug 2027 00:00:00 +0000

nginx location matching uses a normalized URI path rather than the untouched request-target text. Percent-encoded characters are decoded, relative path components are resolved, and adjacent slashes can be merged according to configuration. Later processing can change the current URI again and trigger another location search. Understanding both transformations is necessary when a request appears to enter a different handler than its original spelling suggests.

When it breaks

A path filter that reasons only about the raw request text can disagree with nginx’s routing view. An encoded slash can become a path separator, and a dot segment can remove an earlier component. A backend might apply its own decoding rules as well. Security and routing decisions need an agreed interpretation at each boundary, rather than assuming that every component sees an identical path string.

Logging only $uri can also obscure the incoming request. That variable represents the current normalized URI and may change during request processing. $request_uri retains the full original URI, including its original query. Neither is a universal replacement for the other: one explains current routing, while the other helps reconstruct what the client actually requested.

Index handling and try_files introduce another transition. A request for a directory can internally become a request for its index file. A failed file lookup can redirect internally to a fallback URI, causing a different location and different query arguments to apply. The first prefix match therefore does not necessarily identify the configuration that produces the final response.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image. It was executed with nginx 1.28.0 on Linux arm64 and Docker 29.3.1. It builds and syntax-checks a temporary configuration, publishes only a host-loopback port, sends request targets without client-side path normalization, and removes its own image, 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'

locations=r'''
location / { return 200 "$uri|$request_uri|$args"; }
location /protected/ { return 403 "blocked"; }
location /docs/ { try_files $uri $uri/ /fallback?reason=missing; }
location = /docs/index.html { return 200 "$uri|$request_uri|$args"; }
location = /fallback { return 200 "$uri|$request_uri|$args"; }
'''
with lab(config(locations),{'docs/index.html':'stored-index'}) as (container,request):
 cases={
 '/a//b/../c?x=1':'/a/c|/a//b/../c?x=1|x=1',
 '/a%2Fb/%2e%2e/c?x=1':'/a/c|/a%2Fb/%2e%2e/c?x=1|x=1',
 '/Protected/item':'/Protected/item|/Protected/item|',
 '/docs/':'/docs/index.html|/docs/|',
 '/docs/missing?x=1':'/fallback|/docs/missing?x=1|reason=missing'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 for path in ['/protected/item','/protected%2Fitem','/a/../protected/item']:assert request(path)[0]==403,path
 assert request('/bad%ZZ')[0]==400
 print('matching uses normalized paths: percent-decoding, dot segments, and merged slashes differ from the original request URI')
 print('index and try_files internal redirects choose another location; request_uri remains original while uri and args can change')

The request /a//b/../c?x=1 produces current URI /a/c, while the original request URI remains /a//b/../c?x=1 and the arguments remain x=1. This demonstrates slash merging and dot-segment resolution in the tested default configuration. The response includes all three fields so their meanings can be compared directly.

The encoded request /a%2Fb/%2e%2e/c?x=1 reaches the same current path /a/c. Its original encoded spelling is still preserved in request_uri. This case shows that percent-decoding participates in normalization before routing. The test does not infer behavior from a browser address bar, which may already have rewritten a path before sending it.

The protected prefix returns 403 for /protected/item, /protected%2Fitem, and /a/../protected/item. All normalize into the protected path family. In this Linux environment, /Protected/item instead reaches the ordinary fallback because the case differs. An invalid percent escape such as %ZZ is rejected with HTTP 400 rather than treated as a successful route to arbitrary content.

The fixture includes a real /srv/docs/index.html. Requesting /docs/ reaches the exact /docs/index.html location after index processing, which returns a diagnostic marker instead of the stored file’s body. The original request_uri remains /docs/. This makes the internal location change visible even though the client receives no redirect response.

For /docs/missing?x=1, try_files cannot find the requested file or directory and internally selects /fallback?reason=missing. The response reports current URI /fallback, original request URI /docs/missing?x=1, and current arguments reason=missing. The fallback’s explicit query replaces the earlier arguments in this example; preserving arguments would require an intentional configuration choice.

Verify the path contract across the full request chain

Test representative encoded forms, repeated slashes, dot segments, missing files, and directory requests when changing routing. Include the actual client, proxy, and application in integration tests if they normalize differently. The small fixture establishes nginx behavior for its chosen configuration; it does not prove every upstream framework or security filter interprets the same bytes identically.

Use original and current URI fields deliberately in diagnostics, while recognizing that query strings can contain sensitive data. Log only the request information the operational task needs. An internal redirect can change the final handler and logging context, so verify where the event is ultimately recorded as well as which initial location matched.

Keep fallback behavior explicit. A missing asset should not accidentally become a successful application page if that masks deployment errors, and protected routes should not escape into an unrelated fallback after rewriting. Syntax validation catches malformed configuration; requests with asserted statuses, fields, and bodies establish the behavior users actually receive.

Sources

nginx core location, try_files, and variables, URI normalization, internal redirects, and original versus current URI, checked 2026-09-12.
How nginx processes a request, index processing and subsequent location selection, checked 2026-09-12.
nginx 1.28.0 core implementation, the tested version’s location search and internal-redirection behavior, checked 2026-09-12.

Structured nginx logs need escaping and a value-type contract

Thu, 15 Jul 2027 00:00:00 +0000

A log_format that resembles JSON is not necessarily a reliable structured event format. nginx substitutes variable values into the text, and those values can contain quotes, backslashes, control characters, or no data at all. Correct string escaping and correct value types are separate requirements. Testing emitted records with a real parser catches failures that a visually convincing configuration or successful nginx -t cannot establish.

When it breaks

Raw interpolation of a User-Agent into a quoted JSON field fails when the header contains a quote. Disabling escaping does not make the field safer; it allows the request’s characters to alter the surrounding record syntax. nginx’s default log escaping has a different problem for JSON: it can use hexadecimal \xXX sequences, which are not valid JSON string escapes.

Adding escape=json handles JSON string escaping, but it does not automatically add quotes, supply null, or convert a variable into a number. An upstream timing can be unavailable for a locally generated response. Emitting that optional value without a defined representation can leave the field syntactically incomplete, even though every character that was present was escaped correctly.

Missing-value representation also depends on the escape path in the tested version. nginx 1.28.0’s default escaping writes a dash for a variable it cannot find. Its JSON escaping writes no variable text, so a surrounding pair of quotes becomes an empty string. A parser must distinguish that case from a real variable value that itself contains a dash or a list of upstream attempts.

Check it quickly

Run the script with host Python, Docker, and the pinned nginx image. The recorded environment used nginx 1.28.0 on Linux arm64 and Docker 29.3.1. It builds a temporary configuration with four log formats, validates syntax, makes two real HTTP requests, parses the resulting files, and removes its own container, image tags, and network. All header values are public test strings:

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'

extra=r'''
log_format default_escape '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time"}';
log_format raw escape=none '{"agent":"$http_user_agent"}';
log_format numeric escape=json '{"upstream_time":$upstream_response_time}';
log_format structured escape=json '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time","status":$status,"request_id":"$request_id"}';
'''
locations=r'''
access_log /tmp/default.json default_escape;
access_log /tmp/raw.json raw;
access_log /tmp/numeric.json numeric;
access_log /tmp/structured.json structured;
location / { return 204; }
'''
with lab(config(locations,extra)) as (container,request):
 agent='reader "quoted" '+chr(92)+' path'+chr(9)+'tab'
 assert request('/local',headers={'User-Agent':agent})[0]==204
 assert request('/local',headers={'User-Agent':'plain'})[0]==204
 def lines(path):return docker('exec',container,'cat',path).stdout.splitlines()
 wait(lambda:len(lines('/tmp/structured.json'))==2)
 default=lines('/tmp/default.json');raw=lines('/tmp/raw.json');numeric=lines('/tmp/numeric.json');structured=list(map(json.loads,lines('/tmp/structured.json')))
 for line in [default[0],raw[0]]:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('non-JSON escaping unexpectedly formed valid JSON')
 assert r'\x22' in default[0]
 assert json.loads(default[1])=={'agent':'plain','upstream_time':'-'}
 assert json.loads(raw[1])=={'agent':'plain'}
 for line in numeric:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('unquoted missing timing unexpectedly formed valid JSON')
 assert [row['agent'] for row in structured]==[agent,'plain']
 assert all(row['status']==204 and row['upstream_time']=='' for row in structured)
 identifiers=[row['request_id'] for row in structured]
 assert len(set(identifiers))==2 and all(len(value)==32 and int(value,16)>=0 for value in identifiers)
 print('escape=json preserves quotes, backslashes and tabs as valid JSON strings; both default and no escaping break JSON on the same public header')
 print('default escaping writes a dash for the absent timing, while JSON escaping writes an empty string in the quoted field')
 print('an unavailable upstream timing is empty under JSON escaping, so emitting it unquoted still creates invalid JSON')
 print('structured records parse with a numeric status, explicit empty timing string and distinct nginx-generated request IDs')

The first request carries a User-Agent containing quotes, one backslash, and a tab. The second carries plain. Both receive a local 204 response without an upstream request. This deliberately combines challenging string content with an absent timing, allowing the experiment to test escaping and optional-value handling independently rather than relying only on ordinary alphanumeric headers.

The default-escaping record for the first request contains \x22 and fails JSON parsing. The no-escaping record fails too because its raw quote breaks the surrounding string. Their plain-header controls show that a format can appear correct under normal inputs while still failing for another valid header value. A few readable sample lines are therefore weak validation.

The default format’s plain record parses with a dash as its quoted missing timing. Under JSON escaping, the structured format instead produces an empty timing string. These actual observations agree with the version-specific logging code. The difference matters when a collector assumes all nginx missing values use one universal sentinel regardless of format options.

The deliberately unquoted timing format is invalid for both requests. JSON escaping cannot turn the absent variable into a numeric value, so the record lacks a value after the colon. Quoting the optional timing in the structured format keeps the record valid without pretending that a missing measurement equals zero seconds.

Both structured records parse successfully. Their decoded User-Agent values exactly match the supplied strings, status is the numeric value 204, and the optional timing is an empty string. The two nginx-generated request IDs are distinct 32-character hexadecimal strings. The test checks parsed meaning, not just whether a line happens to contain opening and closing braces.

Define what collectors should accept

Choose stable field names and types, and document missing values. Upstream measurements can contain multiple attempt values, so preserving their string form may be more accurate than forcing a scalar number. If a collector converts them into structured attempts, give that conversion an explicit grammar and error policy rather than silently coercing unusual records to zero.

Validate text encoding as well as JSON escaping at the collection boundary. This fixture covers ordinary text with special ASCII characters; it does not claim arbitrary invalid byte sequences become valid Unicode JSON. Keep parser failures observable so malformed records do not silently disappear during an incident.

Record only necessary request data, with appropriate retention and access controls. A correctly escaped field can still contain sensitive information or an untrusted identity claim. Test the complete shipping and querying path separately: local JSON validity establishes a useful contract, but does not prove that rotation, collection, delivery, and retention preserve every event.

Sources

nginx HTTP log module, log formats, escape modes, and request-completion records, checked 2026-09-12.
nginx 1.28.0 log implementation, different missing-variable behavior for default and JSON escaping, checked 2026-09-12.
nginx core variables, request identifiers and HTTP request variables, 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.

Choose an nginx balancing method by the decision it actually makes

Tue, 18 May 2027 00:00:00 +0000

An upstream group names candidate backend endpoints, and its balancing method chooses among eligible peers. Round robin distributes selections by weight; least connections considers active connections and weights; hash methods use a selected key for affinity. These decisions describe routing policy. They do not automatically measure CPU utilization, guarantee equal response times, or make local session state durable when a peer disappears.

When it breaks

A common measurement error is inspecting the wrong address. curl’s remote IP identifies the server that curl connected to, which is usually the proxy in this architecture. An access log’s client-address field is likewise not a backend distribution report. To assess peer selection, inspect actual upstream addresses or a controlled backend identity, and retain attempt details when retries can contact several peers.

Even request counts do not imply even work. A long report and a tiny cached response each count as a request but can occupy very different resources. A configured weight expresses an intended relative share; it is not an automatic measurement of machine capacity. Doubling a weight does not prove that per-core load or latency became equal across different backends.

Affinity has different failure modes. Many users can share one source address, so IP hashing can concentrate traffic rather than distribute individual users. A failed or changed peer set can alter placement, and local session state does not move merely because requests do. ip_hash should not be described as nginx’s configurable consistent hash ring; the explicit hash ... consistent method is separate.

Check it quickly

Save this as check-balancing.py and run it with Python, Docker, and the pinned images. The recorded setup uses one nginx 1.28.0 worker and two identifiable HTTP peers on separate ports inside one disposable backend container. The shared machine is intentional: the test measures selection, not comparative hardware capacity. All client access uses 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,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
from urllib.parse import urlsplit,parse_qs
import itertools,json,threading
lock=threading.Lock();ids=itertools.count(1);counts={'A':0,'B':0};active={'A':0,'B':0};faults={'A':200,'B':200};gates={}
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def setup(self):super().setup();self.ident=next(ids)
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path);label=self.server.label;code=200
 if label=='control':
 query=parse_qs(parsed.query)
 with lock:
 if parsed.path=='/fail':faults[query['peer'][0]]=int(query['status'][0])
 if parsed.path=='/release':gates[query['path'][0]].set()
 data={'counts':dict(counts),'active':dict(active),'faults':dict(faults),'held':list(gates)}
 else:
 with lock:
 counts[label]+=1;active[label]+=1;code=faults[label]
 if parsed.path.startswith('/hold/'):gates[parsed.path]=threading.Event()
 if parsed.path.startswith('/hold/'):assert gates[parsed.path].wait(20)
 data={'peer':label,'path':self.path,'connection':self.ident}
 body=json.dumps(data,sort_keys=True).encode();self.send_response(code)
 self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)))
 self.end_headers();self.wfile.write(body)
 if label!='control':
 with lock:active[label]-=1
for port,label in [(8081,'A'),(8082,'B'),(8083,'control')]:
 server=ThreadingHTTPServer(('0.0.0.0',port),Handler);server.label=label
 threading.Thread(target=server.serve_forever,daemon=True).start()
threading.Event().wait()
'''
from collections import Counter
extra='''
upstream round { server backend:8081; server backend:8082; }
upstream weighted { server backend:8081 weight=2; server backend:8082; }
upstream by_ip { ip_hash; server backend:8081; server backend:8082; }
upstream by_key { hash $arg_key consistent; server backend:8081; server backend:8082; }
add_header X-Upstream $upstream_addr always; add_header X-Peer $remote_addr always;
'''
locations='\n'.join(f'location /{path}/ {{ proxy_pass http://{group}/; }}' for path,group in
 [('round','round'),('weighted','weighted'),('sticky','by_ip'),('key','by_key')])
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path,headers=None):
 status,h,b=request(path,headers=headers);assert status==200;data=json.loads(b)
 assert h['x-upstream'].endswith(':8081' if data['peer']=='A' else ':8082')
 return data['peer'],h
 results={}
 for mode,expected in [('round',{'A':6,'B':6}),('weighted',{'A':8,'B':4})]:
 chosen=[get('/'+mode+'/item')[0] for _ in range(12)]
 assert dict(Counter(chosen))==expected,chosen;results[mode]={'sequence':chosen,'counts':dict(Counter(chosen))}
 sticky=[get('/sticky/item',{'X-Forwarded-For':'192.0.2.'+str(i)}) for i in range(1,9)]
 assert len({r[0] for r in sticky})==len({r[1]['x-peer'] for r in sticky})==1
 results['ip_hash']={'peers':[r[0] for r in sticky],'socket_peer':sticky[0][1]['x-peer']}
 groups={}
 for key in ['alpha','beta','gamma','delta','epsilon','zeta']:
 pair=[get('/key/item?key='+key)[0] for _ in range(2)];assert pair[0]==pair[1];groups[key]=pair[0]
 assert set(groups.values())=={'A','B'},groups;results['consistent_key_hash']=groups
 print(json.dumps(results,sort_keys=True))

Twelve sequential requests through the equally weighted round-robin group produce six responses from A and six from B. In this controlled run, they alternate. Each response’s backend marker is checked against the port in nginx’s upstream-address header, so the distribution is observed at the selected peer rather than inferred from the client’s connection to nginx.

With A assigned weight two and B weight one, twelve requests produce eight A responses and four B responses. This demonstrates the configured relative share for healthy peers under these serial requests. It does not promise that every arbitrary prefix of a traffic stream, a retried request set, or a fleet with unavailable peers will have exactly that ratio.

The IP-hash group receives eight requests from the same actual socket peer. Their fabricated X-Forwarded-For values vary, but every response still comes from one backend. No real-IP trust configuration converts those untrusted headers into the client address. The observed socket-peer field stays constant, making clear which identity the method is actually using in this setup.

The separate consistent-hash group uses a public query key. Each of six keys is requested twice, and both requests for a key choose the same backend; the chosen keys cover both peers. This checks stable placement for the current group. It does not test membership changes or prove that an arbitrary client-controlled key is an authenticated user identity.

Match the method to the workload and its identity

For similar independent requests, weighted round robin offers a simple relative distribution. For variable connection occupancy, least connections can steer around peers with more active connections, subject to its own metric limitations. For affinity, select a stable, appropriate key and decide what should happen when placement changes. Routing stickiness cannot replace replication, shared state, or an explicit session-loss policy.

nginx IP hashing uses the first three octets of an IPv4 address or the full IPv6 address. That documented granularity matters when estimating distribution; it is not always a full-address hash with one independent outcome per IPv4 host. Proxy address handling and NAT can further change how many distinct identities the balancer actually observes.

Finally, evaluate selection together with eligibility, retries, and per-peer response behavior. Compare upstream attempt addresses and timing with returned content, rather than assuming a slower peer proves the algorithm is wrong. A method change can redistribute work, but it does not repair a broken backend or make an unsafe request safe to retry on another node.

Sources

nginx upstream module, weights, ip_hash, consistent key hashing, and peer selection, checked 2026-09-12.
nginx HTTP load balancing guide, round robin, least connections, affinity, and passive failure handling, checked 2026-09-12.
nginx proxy module, upstream forwarding and retry conditions, checked 2026-09-12.

Request buffering controls when the backend receives an upload

Tue, 13 Apr 2027 00:00:00 +0000

An upload has two separate connections: client to nginx and nginx to the application. proxy_request_buffering on reads the complete client request body before sending that request upstream. Turning it off lets nginx forward body bytes as they arrive. This changes when the application becomes occupied; it does not create unlimited capacity or make a slow sender disappear.

When it breaks

Disabling the wrong directive is a common mistake. proxy_buffering controls responses, while proxy_request_buffering controls uploads. A streaming upload can still wait at the proxy when only response buffering was disabled. Conversely, an application that should receive complete small submissions can become tied to slow clients when request buffering is disabled globally without considering backend concurrency.

Buffering transfers resource use to nginx. A request body that exceeds the configured memory buffer can use client body temporary storage. Many simultaneous uploads therefore consume proxy connections and potentially disk space or I/O. Increasing a buffer is not a substitute for choosing acceptable body sizes, upload timeouts, concurrency limits, and a temporary filesystem with enough capacity.

Streaming also changes failure handling. Once nginx has begun sending the request body upstream, it cannot simply pass that streamed request to the next server. An application may already have processed a prefix or produced side effects. Buffering can preserve body bytes for some retry paths, but it cannot make an unsafe application operation safe to replay.

Check it quickly

Save this as check-upload.py and run it with host Python and Docker after obtaining the pinned images. The recorded setup used nginx 1.28.0 and Python 3.11.16 containers on Linux arm64. The script creates a private backend network, publishes nginx only on host loopback, and cleans up its own containers, image tags, 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_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
import hashlib,json,threading
state={};lock=threading.Lock()
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def reply(self,data):
 data=json.dumps(data).encode();self.send_response(200)
 self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data)
 def do_GET(self):
 with lock:self.reply(dict(state))
 def do_POST(self):
 length=int(self.headers['Content-Length'])
 with lock:state[self.path]={'entered':True,'bytes':0}
 first=self.rfile.read(1)
 with lock:state[self.path]['bytes']=len(first)
 body=first+self.rfile.read(length-1)
 with lock:state[self.path]['bytes']=len(body)
 self.reply({'length':len(body),'sha256':hashlib.sha256(body).hexdigest()})
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /on { proxy_request_buffering on; proxy_pass http://backend:8081; }
location /off { proxy_request_buffering off; proxy_pass http://backend:8081; }
location /state { proxy_pass http://backend:8081; }
'''
with lab(config(locations,'client_max_body_size 1m; proxy_http_version 1.1;'),backend=backend) as (_,request):
 payload=b'x'*65536;results={}
 def state():return json.loads(request('/state')[2])
 for mode in ('on','off'):
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=10)
 connection.putrequest('POST','/'+mode);connection.putheader('Content-Length',str(len(payload)))
 connection.endheaders();connection.send(payload[:1024])
 if mode=='off':wait(lambda:state().get('/off',{}).get('bytes')==1)
 else:
 until=time.monotonic()+1
 while time.monotonic()<until:
 assert '/on' not in state();time.sleep(.05)
 before=state().get('/'+mode)
 connection.send(payload[1024:]);response=connection.getresponse();data=json.loads(response.read());connection.close()
 assert response.status==200 and data=={'length':65536,'sha256':hashlib.sha256(payload).hexdigest()}
 results[mode]={'before_completion':before,'result':data}
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=5)
 connection.putrequest('POST','/off-too-large');connection.putheader('Content-Length',str(2*1024*1024))
 connection.endheaders();response=connection.getresponse();response.read();connection.close()
 assert response.status==413 and '/off-too-large' not in state()
 results['oversize_status']=response.status
 print(json.dumps(results,sort_keys=True))

The client declares a 65,536-byte body but initially sends only 1,024 bytes. With buffering enabled, repeated backend state checks show that the upload handler has not been entered during the controlled pause. The client has started transmitting, yet the application has not been asked to consume the incomplete body. Observing backend state makes this distinction clearer than comparing total request durations.

With buffering disabled, the backend enters its handler and records reading the first byte before the client sends the remainder. It then waits for the rest of the declared body. This demonstrates actual forwarding during the upload, rather than merely confirming that nginx accepts the directive. The backend’s deliberately simple read sequence makes that intermediate state visible.

After the remaining bytes arrive, both modes return length 65,536 and the same expected SHA-256 digest. The buffered and streamed paths therefore preserve this request body despite different timing. These assertions check received bytes, not just a successful status. They do not claim that every application parser, storage operation, or disconnect recovery policy has been exercised.

A separate request announces a two-megabyte body against a one-megabyte limit. nginx returns 413 before the client sends that body, and no matching backend handler appears. This is a size policy applied at the proxy; disabling request buffering does not disable it. The example deliberately uses known Content-Length framing so the admission decision is directly observable.

Choose the upload contract before tuning buffers

Use buffered uploads when keeping slow senders away from scarce application workers is useful and proxy storage is acceptable. Use streaming where the application must process incoming data progressively, while accounting for occupied backend resources and incomplete submissions. Neither mode promises that writers can never be slowed by downstream capacity.

Keep request and response policies independent. An endpoint might accept a buffered upload and stream progress afterward, or stream an upload and return a small buffered result. X-Accel-Buffering is an upstream response control; it does not replace the request-body policy demonstrated here.

Finally, inspect framing and the upstream protocol when extending the experiment. In nginx 1.28.0, an HTTP/1.1 chunked client upload still requires HTTP/1.1 proxying to avoid mandatory buffering in that path. This fixture explicitly selects upstream HTTP/1.1 but tests fixed-length bodies. Validate chunked bodies and disconnect behavior separately when those are part of the endpoint’s real contract.

Sources

nginx proxy module, request buffering, streamed request replay limits, and upstream HTTP version, checked 2026-09-12.
nginx HTTP core module, client body size limits, memory buffers, and temporary storage, checked 2026-09-12.
RFC 9110 HTTP Semantics, Content-Length and the meaning of a 413 response, checked 2026-09-12.

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.