HTTP · XB Field Notes

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.

The article describes a pinned nginx 1.28.0 counterexample: equal mtime and length preserve an ETag across different bytes. The fixture was not rerun in this review.

When it breaks

Calling every ETag a body hash hides an important nginx detail. In the pinned 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

The outcomes below are retained source-reported results, not a new Docker or nginx run. 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. This agrees with RFC 9110 for that combination but does not prove general precedence. The pinned filter checks the date first: a date judged modified can return 200 before a matching tag is examined. That reverse combination is a source-code finding, not an executed case in this fixture. 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.
nginx 1.28.0 conditional filter, date-check ordering and weak versus strong tag comparison, checked 2026-10-18.

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 actual protocol, coding and decoded equality independently. The byte counts are historical article reports with current integration still held.

Check it quickly

These are historical article reports, not a rerun; raw integration logs were not recovered in the retained validation files. Use locally available pinned images with assertions enabled; cleanup is best-effort.

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. The generated test key is copied into an image layer and may remain in Docker build cache after tag removal. Never substitute production keys. Cleanup attempts to remove containers, image tags, network, and temporary files; it does not verify cache erasure.

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-10-15.
nginx HTTP/2 module, HTTP/2 enablement and TLS ALPN requirements, checked 2026-10-15.
Google ngx_brotli module README, the separate Brotli filter/static modules and build requirements, checked 2026-10-15.
RFC 9110 HTTP Semantics, content-coding negotiation and identity acceptability, checked 2026-10-15.
Docker build garbage collection, build-cache lifetime separate from image-tag cleanup, checked 2026-10-18.

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.

A new request or an internal move. Static illustration of the source and its limits. Reported fixture outcomes were not rerun for this graphic.

Check it quickly

The integration results below are historical observations; this revision did not rerun the fixture.

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-10-15.
RFC 9110 HTTP semantics, redirect status meanings and method-preservation requirements, checked 2026-10-15.
RFC 9111 HTTP caching, cacheability depending on response semantics and cache controls, checked 2026-10-15.

Cache-Control is a contract between cache and origin

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

A cache policy needs a behavioral test, not just a header-presence check. Two responses can both contain max-age yet behave differently because one also requires validation or prohibits storage. The request matters too: a browser can bypass an otherwise reusable copy without changing the origin’s response policy or deleting an older cached entry.

Fetch no-store obtains version two while the stored version one remains; reload obtains and stores version three. Response Cache-Control policy and Fetch cache mode are distinct. Source illustration only; no new fixture execution.

Both sides must agree

Cache-Control directives are directional. A request directive is not automatically copied into the response, and RFC 9111 describes request directives as advisory. Response directives impose requirements on conforming caches. Intermediaries must forward applicable cache directives even when they do not implement a cache themselves. Deployment-specific overrides need inspection; they are not evidence that the origin’s declared policy was followed.

Separate three questions. May this response be stored? Is its current age within the applicable freshness lifetime? Does this request permit reuse without validation? Here, no-store prohibits HTTP cache storage; unqualified no-cache permits storage but requires successful validation before reuse. These examples omit the special must-understand interaction that can override no-store. Max-age sets freshness, while must-revalidate prohibits unvalidated reuse after the response becomes stale. Must-revalidate does not require a round trip while the response is still fresh.

Unqualified private restricts storage to single-user caches; public explicitly permits caching subject to other requirements and is not mandatory on every cacheable response. S-maxage overrides freshness for shared caches and requires validation after staleness; it does not govern private browser caches. Vary supplies request-matching dimensions. None of these mechanisms identifies the current application account or makes personal data safe merely because its lifetime is short.

When it breaks

Testing with a new query parameter on every request changes the cache key and can hide reuse entirely. Disabling the browser cache in developer tools can create the same misleading result. Some automation interception mechanisms also disable caching. A useful test repeats the same URL in one isolated context and counts requests at the origin, while asserting the returned body as well.

Fetch’s cache option is a browser API, not a response header. Its no-store mode bypasses lookup and avoids updating the HTTP cache; reload bypasses lookup but can update it. Neither should be confused with erasing all previous copies. Likewise, changing origin headers cannot force an already-fresh entry to contact the origin immediately. History restoration and service-worker storage introduce additional behavior outside this test.

No-cache does not promise a 304. A validator and an unchanged representation are needed for that optimization. Without ETag or Last-Modified, repeated requests can transfer complete 200 responses. Count both origin visits and transferred bodies before concluding that validation is saving work.

Check it quickly

The author recorded a macOS run with Node 26.0.0, Playwright 1.63.0, and Chromium 153.0.8010.12 headless shell. That browser run was not reproduced in this review. Install into a temporary directory; Linux also needs Playwright’s documented browser system dependencies. The download needs network access. Run the JavaScript block using NODE_PATH="$cache_browser_lab/node_modules" PLAYWRIGHT_BROWSERS_PATH="$cache_browser_lab/browsers" node. Test requests use only an automatically allocated loopback port, with no existing browser profile.

cache_browser_lab=$(mktemp -d)
npm install --prefix "$cache_browser_lab" --ignore-scripts --no-audit --no-fund --package-lock=false playwright@1.63.0
PLAYWRIGHT_BROWSERS_PATH="$cache_browser_lab/browsers" node "$cache_browser_lab/node_modules/playwright/cli.js" install chromium --only-shell --no-remove

const assert = require("node:assert/strict");
const http = require("node:http");
const { once } = require("node:events");
const { chromium } = require("playwright");

const policies = new Map([
 ["/fresh", "max-age=3600"],
 ["/must", "max-age=3600, must-revalidate"],
 ["/validate", "no-cache, max-age=3600"],
 ["/discard", "no-store, max-age=3600"],
]);
const hits = new Map();
const server = http.createServer((request, response) => {
 const route = new URL(request.url, "http://127.0.0.1").pathname;
 if (route === "/") {
 response.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
 response.end("<!doctype html><title>Cache experiment</title>");
 } else if (policies.has(route)) {
 const count = (hits.get(route) || 0) + 1;
 hits.set(route, count);
 response.writeHead(200, {
 "Content-Type": "text/plain", "Cache-Control": policies.get(route),
 });
 response.end(`${route}:${count}`);
 } else {
 response.writeHead(404, { "Cache-Control": "no-store" });
 response.end();
 }
});

async function main() {
 server.listen(0, "127.0.0.1");
 await once(server, "listening");
 let browser;
 try {
 browser = await chromium.launch();
 console.log("Chromium", browser.version());
 const context = await browser.newContext({ serviceWorkers: "block" });
 try {
 const page = await context.newPage();
 await page.goto(`http://127.0.0.1:${server.address().port}/`);
 const read = (route, cache = "default") => page.evaluate(async ({ route, cache }) => {
 const response = await fetch(route, { cache });
 if (!response.ok) throw new Error(`HTTP ${response.status}`);
 return response.text();
 }, { route, cache });
 for (const [route, expectedHits] of [
 ["/fresh", 1], ["/must", 1], ["/validate", 2], ["/discard", 2],
 ]) {
 const first = await read(route);
 const second = await read(route);
 assert.equal(first, `${route}:1`);
 assert.equal(second, `${route}:${expectedHits}`);
 assert.equal(hits.get(route), expectedHits);
 console.log(route, "origin requests:", hits.get(route));
 }
 assert.equal(await read("/fresh", "no-store"), "/fresh:2");
 assert.equal(await read("/fresh"), "/fresh:1");
 assert.equal(hits.get("/fresh"), 2);
 assert.equal(await read("/fresh", "reload"), "/fresh:3");
 assert.equal(await read("/fresh"), "/fresh:3");
 assert.equal(hits.get("/fresh"), 3);
 console.log("no-store bypass retained version 1; reload stored version 3");
 } finally {
 await context.close();
 }
 } finally {
 if (browser) await browser.close();
 await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve()));
 }
}

main().catch(error => { console.error(error); process.exitCode = 1; });

The initial origin counts are one, one, two, and two. Both fresh policies reuse the first body. The no-cache and no-store responses reach the origin again despite their large max-age. This fixture intentionally has no validators, so those visits return full bodies; it does not distinguish their storage eligibility by counts alone.

The later no-store fetch obtains version two, but an ordinary fetch still returns the previously cached version one. Reload obtains and stores version three, which the next ordinary fetch reuses. Origin counters ensure these are actual cache decisions, not coincidentally identical response strings. The server and isolated browser context are closed afterward.

These observations cover this Chromium HTTP cache and these exact requests. They do not verify a shared CDN, persistence across browser restarts, stale delivery, or user-account isolation. Keep those separate acceptance tests rather than extending a successful local cache experiment into a broader claim.

Sources

RFC 9111: Cache-Control, directional directives and storage/reuse requirements, checked 2026-09-07.
MDN: Request.cache, default, no-store, and reload behavior, checked 2026-09-07.
Playwright browser contexts, isolated non-persistent contexts, checked 2026-09-07.
Playwright browser installation, version-matched headless shell and system dependencies, checked 2026-09-07.
Fetch Standard: cache modes, no-store bypass versus reload cache update, checked 2026-10-15.

The CONNECT method opens a raw tunnel

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

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

Switch protocols at the right boundary

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

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

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

Opaque content still consumes resources

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

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

When it breaks

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

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

CONNECT admits a bidirectional relay; TLS verifies the destination separately. The proxy remains responsible for sockets and cleanup. The historical local exercise is not a deployable public proxy.

Check it quickly

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

package main

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

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

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

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

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

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

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

The author recorded all assertions passing on macOS with Go 1.27.0; this review did not reproduce that live run. Requests have two-second timeouts, dialing has a one-second timeout, and tunnel sockets have a three-second absolute deadline. This is an isolated protocol exercise, not a deployable public proxy. Authentication, DNS policy, interception, buffered early-data injection, traffic shaping, sustained load, and HTTP/2 or HTTP/3 CONNECT mappings are not tested.

Sources

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

Cache freshness is judged against a clock

Fri, 03 Dec 2027 00:00:00 +0000

A cache does not receive a new freshness allowance every time another cache forwards a response. It must account for age already accumulated along the delivery path, then add its own residence time. Otherwise a chain of individually plausible sixty-second caches can keep old content reusable much longer than the origin intended.

A received Age of 20 reaches the shared freshness boundary at 30 and the private boundary at 60. A separate stale window permits a response with asynchronous validation, not fresh reuse. Source illustration only; no new fixture execution.

Count the age

Age estimates seconds since generation or successful validation, including time in caches and transit. The received Age field is therefore an input to current age, not a counter that stays frozen while the response sits locally. Date supplies the response’s origination timestamp. Clock synchronization and measured request/response timing matter when relating those values.

RFC 9111 describes an apparent age from response receipt minus Date, clamped at zero, and a corrected age value from received Age plus response delay. Its conservative calculation takes the larger value, then adds residence time. For request time 100, receipt 102, Date 95, received Age 10, and current time 107, those values are 7, 12, and finally 17 seconds. Reading only the original Age would miss seven seconds.

Freshness lifetime has a precedence order: shared caches use s-maxage when present; otherwise max-age takes precedence over Expires minus Date. Private caches ignore s-maxage. Without explicit expiration, a permitted heuristic might apply, but its duration is not universally fixed. A response is fresh only while its applicable lifetime is greater than current age; equality is already the stale boundary.

When it breaks

Fresh does not mean usable for every request. Storage permission, URL and Vary matching, and validation requirements still apply. No-cache requires validation before reuse even when an explicit lifetime looks generous. An ETag supplies a validator, not permission to skip validation. Successfully revalidating can update stored metadata without transferring the body; simply receiving a cached response cannot reset its age.

Stale delivery is a separate permission, not an automatic response to an outage. Must-revalidate prohibits reuse once stale until validation succeeds, including when disconnected. Stale-while-revalidate permits a bounded stale interval while validation proceeds, subject to applicable restrictions. It does not turn stale content fresh. RFC 9111 also obsoletes Warning, so absence of the old Warning: 110 field is not evidence of freshness.

Do not confuse storage retention with freshness. Keeping bytes after expiration can be useful for validation or an allowed stale window. A backend’s eviction TTL may therefore exceed the direct-reuse lifetime. If the caller treats that TTL as permission to serve, it can deliver stale responses outside the intended policy.

Check it quickly

Use Node.js and npm; the tested versions are Node 26.0.0 and http-cache-semantics 4.2.0. Install the library below, then execute the JavaScript with NODE_PATH="$freshness_lab/node_modules" node. The test overrides the library’s clock, not the system clock. It uses synthetic metadata, performs no requests, and needs no sleeping; only installation requires the network.

freshness_lab=$(mktemp -d)
npm install --prefix "$freshness_lab" --ignore-scripts --no-audit --no-fund --package-lock=false http-cache-semantics@4.2.0

const assert = require("node:assert/strict");
const CachePolicy = require("http-cache-semantics");

const start = Date.parse("2026-09-07T00:00:00Z");
let clock = start;
class TestPolicy extends CachePolicy {
 now() { return clock; }
}
const request = { url: "https://example.test/news", method: "GET", headers: {} };
const headers = {
 date: new Date(start).toUTCString(),
 age: "20",
 expires: new Date(start + 3600000).toUTCString(),
 "cache-control": "public, max-age=60, s-maxage=30",
};
const shared = new TestPolicy(request, { headers }, { shared: true });
const single = new TestPolicy(request, { headers }, { shared: false });
assert.equal(shared.maxAge(), 30);
assert.equal(single.maxAge(), 60);
for (const [elapsed, sharedHit, privateHit] of [
 [0, true, true], [9, true, true], [10, false, true], [40, false, false],
]) {
 clock = start + elapsed * 1000;
 assert.equal(shared.age(), 20 + elapsed);
 assert.equal(shared.responseHeaders().age, String(20 + elapsed));
 assert.equal(shared.satisfiesWithoutRevalidation(request), sharedHit);
 assert.equal(single.satisfiesWithoutRevalidation(request), privateHit);
 console.log("elapsed:", elapsed, "age:", shared.age(), "reuse:", sharedHit, privateHit);
}

clock = start;
const background = new TestPolicy(request, { headers: {
 age: "20", "cache-control": "public, max-age=30, stale-while-revalidate=20",
} });
clock += 15000;
const decision = background.evaluateRequest(request);
assert.equal(background.timeToLive(), 15000);
assert.equal(background.satisfiesWithoutRevalidation(request), false);
assert(decision.response);
assert.equal(decision.revalidation.synchronous, false);
console.log("stale window: retain 15000 ms, serve and revalidate");
clock += 15000;
assert.equal(background.evaluateRequest(request).response, undefined);
assert.equal(background.evaluateRequest(request).revalidation.synchronous, true);

clock = start;
const oldDate = new TestPolicy(request, { headers: {
 date: new Date(start - 3600000).toUTCString(),
 "cache-control": "public, max-age=60",
} });
assert.equal(oldDate.age(), 0);
assert.equal(oldDate.satisfiesWithoutRevalidation(request), true);
console.log("library limitation: old Date alone does not increase age");

At elapsed times zero, nine, ten, and forty seconds, the calculated ages are twenty, twenty-nine, thirty, and sixty. Both modes initially reuse the response. Shared reuse stops exactly at age thirty; private reuse stops at sixty. The future Expires date does not override either explicit lifetime. Updated outgoing Age is checked as well as the reuse decision.

The separate stale-window fixture reaches age thirty-five, five seconds beyond freshness. Its remaining retention allowance is fifteen thousand milliseconds, but validation is still required. The library permits a response together with asynchronous revalidation; it does not perform that network operation itself. At age fifty, that permission ends and validation becomes synchronous.

The final check exposes an important implementation limit: this library deliberately ignores server Date when calculating age. An hour-old Date with no Age still starts at zero here. Its documented model adds received Age and local residence, not measured response delay or the conservative apparent-age branch above. Consequently, these passing assertions establish the pinned library’s decisions, not complete RFC age-calculation conformance. Test actual intermediary timing and header propagation separately before using a measured cache lifetime as a delivery guarantee.

Sources

RFC 9111: freshness, lifetime precedence, current age, and stale-response restrictions, checked 2026-09-07.
MDN: Cache-Control, freshness and stale-while-revalidate directives, checked 2026-09-07.
http-cache-semantics 4.2.0, retention TTL, revalidation decisions, and the documented server-Date limitation, checked 2026-09-07.

A token bucket bounds admission and allows bursts

Wed, 01 Dec 2027 00:00:00 +0000

A token bucket bounds admitted work while allowing accumulated credit to be spent in a burst. It does not automatically space requests evenly, guarantee completed throughput, or cap the number of operations still running. Those are separate scheduling and capacity questions. The bucket’s two parameters describe a budget, not a promise that the service can perform it.

The selected event ledger reproduces the source’s injected-time, exact-arithmetic, single-threaded model. Admitted cost over an interval of duration Δt is bounded by B + rΔt in this ideal strict model; departures need separate pacing. Historical scoped execution remains passed, but this artwork adds no runtime result, distributed atomicity or cloud-service guarantee.

Refill credit, then charge work

Let capacity B be the maximum stored tokens and rate r be tokens added per second. At each arrival, update credit to min(B, previous_credit + r × elapsed). Admit work only if its cost fits, then subtract that cost. Under the strict rule used here, rejected work does not consume credit.

The bucket can refill lazily when requests arrive; a background timer is unnecessary for this calculation. Idle time cannot accumulate unlimited credit because capacity clips the result. Initial credit is a policy choice: the example starts full, allowing an immediate burst, while an empty initialization would behave differently.

A burst allowance is not a peak rate

For this ideal strict bucket, admitted cost over an interval of duration t is at most B + r × t. As the interval grows, the burst contribution becomes relatively smaller. That bound does not mean every one-second window admits at most r requests, nor does it establish a separate instantaneous peak-rate ceiling.

For capacity three and rate two, three unit-cost requests can pass at the same timestamp. A fourth is denied. Half a second later one token is available. A real scheduler, bounded queue, or additional pacing rule is needed if permitted work must depart at evenly spaced times.

Rate limiting admission also does not bound concurrent execution: slow requests can remain active while more tokens refill. Protect scarce worker or database capacity with an appropriate concurrency limit and timeout policy. Likewise, an accepted request may still fail downstream, so refill rate is not guaranteed successful throughput.

Match the budget to its scope

A token need not mean one request. Weighted costs can represent bytes or estimated work, provided refill rate and capacity use the same units. A request costing more than B can never fit this strict bucket, even after a long idle period. Handle that case explicitly instead of promising an eventual retry time.

Choose the identity and ownership of the budget carefully. Four independent full buckets each holding three tokens can admit twelve requests at once. They are not one global three-token bucket. A shared limiter must make refill, comparison, and deduction an atomic decision; merely sharing a counter without coordinating those steps is insufficient.

Use an elapsed-time clock for local refill calculations. Wall-clock adjustments must not mint credit or move the accounting backward. Python’s monotonic clock is designed for elapsed differences; its reference point is not a portable timestamp to exchange between unrelated machines. Distributed clock and state ownership need their own contract.

When it breaks

A full bucket can release a burst that overwhelms a fragile dependency even when the long-run allowance looks conservative. Unbounded waiting queues turn excess demand into memory growth and latency. Denial and delayed shaping are different outcomes, so document which one callers receive.

Observe admitted and denied cost, queueing, concurrency, and downstream latency together. Retries should respect the limiting policy instead of immediately recreating rejected load. Charging attempted work versus completed work is another explicit choice; refunding failures changes the model and requires careful accounting.

Managed implementations can provide weaker ceilings than the ideal algorithm. Amazon API Gateway documents throttling and quotas as best-effort targets that can be exceeded. Do not present the mathematical bound as a verified guarantee for that service, a billing cap, or any other untested deployment.

Check it quickly

Save the block as bucket_check.py and run python3 bucket_check.py with Python 3.10 or newer. The original article reports Python 3.14.4; the complete unchanged program passed this review on 2026-10-19 with Python 3.12.14. The standard-library Fraction type and injected nondecreasing timestamps make boundaries exact without sleeping. This is a single-threaded admission model, not a network limiter or distributed store.

from fractions import Fraction


class Bucket:
 def __init__(self, capacity, rate):
 assert capacity > 0 and rate > 0
 self.capacity, self.rate = capacity, rate
 self.tokens, self.updated = Fraction(capacity), Fraction(0)

 def take(self, now, cost=1):
 assert now >= self.updated and cost > 0
 self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
 self.updated = now
 if self.tokens < cost:
 return False
 self.tokens -= cost
 return True


bucket = Bucket(capacity=3, rate=2)
events = ([(Fraction(0), 1)] * 4 + [(Fraction(1, 4), 1), (Fraction(1, 2), 1),
 (Fraction(3, 2), 2)] + [(Fraction(100), 1)] * 4)
results = [(now, cost, bucket.take(now, cost)) for now, cost in events]
assert [allowed for _, _, allowed in results] == [
 True, True, True, False, False, True, True, True, True, True, False,
]
for now, cost, allowed in results:
 print(f"t={str(now):>3} cost={cost} {'allow' if allowed else 'deny'}")
assert bucket.tokens == 0
marks = sorted({now for now, _ in events})
for start in marks:
 for end in marks:
 if end >= start:
 consumed = sum(cost for now, cost, allowed in results if allowed and start <= now <= end)
 assert consumed <= bucket.capacity + bucket.rate * (end - start)
print("every event-bounded interval obeys admitted cost <= B + r * elapsed")

assert not bucket.take(Fraction(200), cost=4)
assert bucket.tokens == 3
assert bucket.take(Fraction(200), cost=3)
print("cost above capacity never fits; rejection does not consume tokens")

workers = [Bucket(capacity=3, rate=2) for _ in range(4)]
local_admitted = sum(worker.take(Fraction(0)) for worker in workers for _ in range(4))
shared = Bucket(capacity=3, rate=2)
shared_admitted = sum(shared.take(Fraction(0)) for _ in range(16))
assert local_admitted == 12 and shared_admitted == 3
print("four independent full buckets admit", local_admitted, "at once; one shared bucket admits", shared_admitted)

The trace allows three simultaneous requests, rejects the fourth and the quarter-second request, then allows one at half a second and cost two at one-and-a-half seconds. After long idle time it permits only another three-token burst. Assertions check every interval bounded by event timestamps against the cost envelope.

An oversized request is denied without spending credit. Finally, four independent buckets admit twelve simultaneous requests while one shared sequential model admits three. No concurrency races, real clock adjustments, queue scheduling, cloud throttling, network partitions, or production performance are tested.

Sources

RFC 3290, Appendix A’s token-bucket envelope and strict conformance calculation, checked 2026-09-08.
Amazon API Gateway throttling, request budgets, bursts, and best-effort limits, checked 2026-09-08.
Python time, monotonic elapsed-time clocks and their reference-point limits, checked 2026-09-08.

Accept headers let the server negotiate a reply

Tue, 23 Nov 2027 00:00:00 +0000

Negotiation selects among representations the server can actually produce. Request preferences are inputs to that decision, not evidence that the response will satisfy them. A client still needs to inspect the selected representation. Vary records the request dimensions relevant to reuse; it does not identify the chosen format, language, or compression method.

Keep the dimensions separate

Request preference	Selected representation metadata
Accept	Content-Type
Accept-Language	Content-Language
Accept-Encoding	Content-Encoding, when a content coding is applied

These dimensions are independent. Requesting JSON does not request English or gzip. Content-Language describes the intended audience’s language, not a guarantee that every character belongs to one language. A server offering English HTML and Chinese JSON cannot combine the independently preferred format and language into Chinese HTML unless that complete representation exists. Define the available combinations before deciding how to rank them.

A quality value ranges from zero to one, defaults to one, and permits at most three fractional digits. Zero means unacceptable, not merely less desirable. For media types, the most specific matching range determines a candidate’s quality. An explicit text/html;q=0 is not rescued by */*;q=1. Looking for the largest number anywhere in the field, or choosing the first comma-separated item, loses this relationship between range and candidate.

When it breaks

A missing preference field generally expresses no preference on that dimension. It is not the same input as an explicit exclusion. RFC 9110 permits a server with no acceptable representation to send 406 or disregard the field; a default response might therefore be unusable to the client. An API promising strict negotiation must define that policy itself. An exclusion communicates a constraint but does not force every deployed server to enforce it.

Different fields also have different matching rules. Accept uses media ranges; language negotiation needs a documented language-tag matching scheme; Accept-Encoding has special rules for identity, absence, and an empty value. A generic list parser cannot supply all those policies. Do not silently equate an absent field with an empty parsed collection, then conclude that the client rejected everything.

Equal weights do not establish a universal ordering rule across all servers. Make the application’s tie policy deterministic, and test it. Detailed language preferences can also expose identifying information, so neither logging complete preference profiles nor adding every possible field to Vary is automatically justified. Vary affects matching, while storage eligibility, freshness, and authorization still require their own rules.

Specificity, exclusions, and offered order determine the parser results; an endpoint must separately decide how no match becomes an HTTP response.

Check it quickly

Use Python 3.11 or newer and a POSIX shell. Install the tested parser in a temporary environment, then run the Python block with "$accept_lab/venv/bin/python". Installation needs the network; the experiment itself does not send requests or start a server. It checks selection behavior in Werkzeug 3.1.8 rather than claiming to reproduce an arbitrary browser or CDN.

accept_lab=$(mktemp -d)
python3 -m venv "$accept_lab/venv"
"$accept_lab/venv/bin/python" -m pip install Werkzeug==3.1.8

from werkzeug.datastructures import Accept, LanguageAccept, MIMEAccept
from werkzeug.http import parse_accept_header

offers = ["text/html", "application/json"]
cases = [
 (None, "text/html"),
 ("", None),
 ("application/json;q=0.9, text/html;q=0.2", "application/json"),
 ("text/*;q=0.9, text/html;q=0, application/json;q=0.5", "application/json"),
 ("application/json;q=0, text/*;q=0.4, */*;q=1", "text/html"),
 ("application/xml", None),
 ("*/*;q=0", None),
]
for header, expected in cases:
 parsed = parse_accept_header(header, MIMEAccept)
 selected = offers[0] if header is None else parsed.best_match(offers)
 assert selected == expected
 print(repr(header), "->", selected)

denied = parse_accept_header("text/html;q=0, */*;q=1", MIMEAccept)
assert denied.quality("text/html") == 0
assert denied.quality("application/json") == 1
print("specific exclusion:", denied.quality("text/html"), denied.quality("application/json"))

tied = parse_accept_header("application/json, text/html", MIMEAccept)
assert tied.best_match(offers) == "text/html"
assert tied.best_match(list(reversed(offers))) == "application/json"
print("tie: server offer order decides")

languages = parse_accept_header("fr;q=1, zh;q=0.8, en;q=0.5", LanguageAccept)
codings = parse_accept_header("gzip;q=0, br;q=1", Accept)
assert languages.best_match(["en", "zh"]) == "zh"
assert codings.best_match(["gzip", "br"]) == "br"
print("independent axes:", languages.best_match(["en", "zh"]), codings.best_match(["gzip", "br"]))

The seven media results are HTML, no match, JSON, JSON, HTML, no match, and no match. The caller supplies the missing-field HTML default; an explicitly empty Accept field gets no such default. The two exclusion cases prove that a broader range does not override the specific candidate’s quality. The unavailable XML and universal zero cases return None; translating that result into 406 belongs to an HTTP endpoint, not this parser.

The tie test reverses the server’s offered list while leaving the request unchanged. Werkzeug follows that list when quality and specificity tie. The final checks independently select Chinese and Brotli from declared candidates; they neither create a combined representation nor perform compression. These language cases use direct tags and do not validate regional fallback. The coding check deliberately does not implement identity or missing-header semantics.

For a real integration, preserve these negative cases and inspect the actual outgoing request, returned metadata, and body. Test the default, supported alternatives, explicit exclusions, and unavailable combinations through the deployed path. Only then decide which request fields belong in Vary. A passing parser test establishes a useful component contract, not the correctness of the complete negotiation and caching pipeline.

Sources

RFC 9110: content negotiation, absence, quality values, field-specific matching, and Vary, checked 2026-09-07.
Werkzeug Accept data structures, specificity, quality, and tie behavior, checked 2026-09-07.
Werkzeug header parsing, the parser and its type-specific classes, checked 2026-09-07.

Webhooks push events instead of polling

Thu, 18 Nov 2027 00:00:00 +0000

A webhook lets a provider notify a registered receiver when something changes. It reverses who initiates the HTTP request, but that alone does not guarantee delivery, immediacy, ordering, or exactly-once processing. The operational contract comes from the provider and the receiver’s handling of acknowledgment and state.

Delivery policy belongs to the provider

Providers differ. GitHub does not automatically redeliver failed webhook deliveries; a receiver needs an appropriate redelivery or reconciliation process. Stripe retries live-mode deliveries for up to three days with exponential backoff, while sandbox retry behavior differs. Neither policy means an unavailable endpoint can remain offline indefinitely without missing work. Record the actual retry window and how an operator discovers exhausted deliveries.

An event is not necessarily a complete current object. Some payloads describe a historical snapshot or contain identifiers requiring another API read. Events can arrive out of order, and two different event IDs can concern the same business transition. Decide whether to apply an event, fetch current state, or reconcile a version before making irreversible business changes. Delivery deduplication and business-operation idempotency solve related but different problems.

Authenticate, retain, then acknowledge

Verify the provider’s signature according to its exact format, using the original request bytes when required. Re-encoding parsed JSON can change whitespace or ordering and break a genuine signature. TLS protects the transport to the endpoint; ordinary server-authenticated HTTPS does not prove which provider sent the request. Keep signing secrets out of logs, compare signatures safely, and use the provider’s rotation procedure.

Timestamp protection is provider-specific. Stripe signs a delivery timestamp and its libraries enforce a tolerance. GitHub’s documented HMAC body signature does not add the same signed timestamp, so one cannot demand an equivalent header universally. A retry can have a fresh delivery signature while representing the same old event. Validate freshness according to the provider, and deduplicate according to the event’s stable identity.

Before returning success for new work, retain it durably in a queue or transactional inbox. Acknowledging first and enqueueing afterward leaves a crash window in which the sender stops retrying but the receiver loses the event. Keep the request path short, but do not remove authentication or durable handoff from it. A valid duplicate already retained can receive the provider’s normal success response without repeating the effect.

When it breaks

An in-memory seen set disappears on restart and races across workers. Recording an ID before its effect without a recoverable pending state can lose work; recording it afterward can repeat the effect after a crash. Use a uniqueness constraint and transaction where possible, then make downstream effects retry-safe with their own operation identifiers. A database transaction cannot atomically cover an unrelated external shipment or payment request by itself.

A rotation applied to only some verifier instances rejects genuine requests intermittently. Permit overlapping valid keys only for the intended transition, monitor rejection reasons, and remove retired keys according to policy. Also bound request sizes and queue growth. A fast 2xx hides trouble if retained events accumulate without progress; delivery health and completed business work need separate observations.

Webhook signed delivery: mechanism and evidence boundaries.

Check it quickly

Save this as webhook_verify_demo.py and run python3 webhook_verify_demo.py. It tests an explicitly invented HMAC format with public fixture keys and a fixed clock. It uses only the standard library and in-memory state; it does not contact a payment service or implement a production receiver.

import hashlib
import hmac
import re

SECRET = b"public-demo-key-not-a-real-credential"
OLD_SECRET = b"public-retired-demo-key"
TOLERANCE_SECONDS = 300
seen_ids = set()


def sign(event_id, timestamp, payload, key=SECRET):
 message = f"{event_id}.{timestamp}.".encode("ascii") + payload
 return hmac.new(key, message, hashlib.sha256).hexdigest()


def accept(event_id, timestamp, payload, signature, now):
 # This is an invented wire format, not a Stripe or GitHub verifier.
 if not re.fullmatch(r"evt_[0-9]+", event_id):
 return "rejected"
 if abs(now - timestamp) > TOLERANCE_SECONDS:
 return "rejected"
 if not re.fullmatch(r"[0-9a-f]{64}", signature):
 return "rejected"
 expected = sign(event_id, timestamp, payload)
 if not hmac.compare_digest(expected, signature):
 return "rejected"
 if event_id in seen_ids:
 return "duplicate"
 seen_ids.add(event_id) # Process-local demonstration, NOT durable acceptance.
 return "accepted"


now = 1_800_000_000
payload = b'{"type":"order.paid","order":"42"}'
fresh = sign("evt_1", now, payload)
assert accept("evt_1", now, payload, fresh, now) == "accepted"
assert accept("evt_1", now, payload, fresh, now) == "duplicate"
# Authenticate even a claimed duplicate before calling it harmless.
assert accept("evt_1", now, payload, "0" * 64, now) == "rejected"
# Change only the body: id and timestamp still match the signed message.
second = sign("evt_2", now, payload)
assert accept("evt_2", now, payload + b" ", second, now) == "rejected"
# Change only the id, leaving body and timestamp intact.
assert accept("evt_3", now, payload, second, now) == "rejected"
for timestamp in (now - 301, now + 301):
 assert accept("evt_4", timestamp, payload,
 sign("evt_4", timestamp, payload), now) == "rejected"
assert accept("evt_5", now, payload,
 sign("evt_5", now, payload, OLD_SECRET), now) == "rejected"
assert accept("evt_6", now, payload, "not-a-digest", now) == "rejected"
assert seen_ids == {"evt_1"}
assert accept("evt_2", now, payload, second, now) == "accepted"
assert seen_ids == {"evt_1", "evt_2"}
print("PASS: authenticated duplicate, independent body/id tampering, stale/future, retired key, malformed digest")

On 2026-10-19, both complete bilingual fences ran unchanged under Python 3.12.14 with assertions enabled: exit 0, the displayed PASS line and empty stderr. Keep assertions enabled, without -O or PYTHONOPTIMIZE; otherwise the accept calls disappear while PASS still prints. The exact fence covers authenticated repeats, forged duplicates, independent body/ID tampering, ±301 seconds, a retired key and a malformed digest. Separate supplemental tests accepted the inclusive ±300 boundary and rejected seven malformed event IDs; those extra tests are not inside this fence. Five deliberate mutations per language, disabling signature, body, ID, freshness or dedup protection, each failed an assertion before PASS.

Only authenticated new events enter the set; rejected damage does not prevent a later valid delivery. These are local, fixed-clock results with public fixture keys. They establish neither durable acceptance nor cross-process uniqueness, HTTP responses, queue recovery, provider compatibility or end-to-end exactly-once effects. Test those properties at the chosen provider and storage boundary before deployment.

Sources

Python assert statement, optimization omits assertions and any calls inside them, checked 2026-10-18.
GitHub: Failed webhook deliveries, no automatic redelivery, checked 2026-10-15.
GitHub: Validating webhook deliveries, body HMAC and signature comparison, checked 2026-10-15.
Stripe webhooks, retry windows, raw-body verification, timestamps, duplicates and ordering, checked 2026-10-15.

Least connections measures occupied connections, not every kind of load

Thu, 11 Nov 2027 00:00:00 +0000

Least-connections balancing chooses a peer using active connection counts, with the implementation’s weighting and tie rules. In nginx, least_conn accounts for server weights and uses weighted round robin among equally suitable peers. This can help when requests occupy connections for different durations. It is still a connection-based measurement, not direct knowledge of CPU, memory pressure, queued jobs, or database contention.

When it breaks

Calling the selected peer the “emptiest server” overstates the signal. One connection may carry an expensive operation while another carries a cheap wait. Background work can continue after an HTTP response closes, and multiplexed protocols can place several operations on one connection. A low connection count therefore does not prove that the backend has spare capacity for the next costly request.

The count is also the balancer’s observed upstream state, not an omniscient census of every backend client. Work arriving through another proxy or a direct internal path may be outside that view. In nginx, worker scope and upstream shared-zone configuration affect which runtime state is shared. Independent balancers do not automatically merge their observations into one global least-connections decision.

Weights make raw-count comparisons insufficient. A peer with weight two can appropriately carry more active connections than one with weight one. Changing a weight expresses a capacity assumption; it does not measure whether that assumption is true. An idle keepalive cache is another different quantity and should not be confused with the active connections used for this selection.

least_conn observes weighted active connections, not global resource load. Held requests must be released before their own five-second read deadline; current execution remains held.

Check it quickly

Save this as check-least-connections.py and run it with Python, Docker, and the pinned images. The recorded setup uses one nginx 1.28.0 worker with no upstream keepalive cache and two HTTP peers on separate ports. The backend provides controlled response gates and active counters, making held work visible without a guessed sleep duration. Each held request must still be released before its five-second HTTP read timeout:

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 concurrent.futures import ThreadPoolExecutor
extra='''
upstream least { least_conn; server backend:8081; server backend:8082; }
upstream weighted_least { least_conn; server backend:8081 weight=2; server backend:8082; }
'''
locations='''
location /least/ { proxy_pass http://least/; }
location /weighted/ { proxy_pass http://weighted_least/; }
location /control/ { proxy_pass http://backend:8083/; }
'''
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path):
 status,_,body=request(path);assert status==200;return json.loads(body)
 def state():return get('/control/state')
 results={}
 with ThreadPoolExecutor(max_workers=3) as pool:
 held=pool.submit(get,'/least/hold/first');wait(lambda:sum(state()['active'].values())==1)
 occupied=next(peer for peer,value in state()['active'].items() if value==1)
 quick=[get('/least/quick')['peer'] for _ in range(6)]
 assert all(peer!=occupied for peer in quick),quick
 get('/control/release?path=/hold/first');assert held.result()['peer']==occupied
 wait(lambda:sum(state()['active'].values())==0)
 results['held_peer']=occupied;results['quick_while_held']=quick
 futures=[]
 for index in range(3):
 futures.append(pool.submit(get,'/weighted/hold/w'+str(index)))
 wait(lambda:sum(state()['active'].values())==index+1)
 snapshot=state()['active'];assert snapshot=={'A':2,'B':1},snapshot
 for index in range(3):get('/control/release?path=/hold/w'+str(index))
 results['weighted_active']=snapshot;results['weighted_completed']=[f.result()['peer'] for f in futures]
 wait(lambda:sum(state()['active'].values())==0)
 print(json.dumps(results,sort_keys=True))

The first request enters the equally weighted least-connections group and waits inside one backend handler. The controller observes exactly one active request and identifies the occupied peer before sending anything else. Which peer wins the initial tie is not the important assertion; the fixture discovers that identity from the backend’s actual state.

Six short requests then complete through the same upstream group. All choose the other peer while the first request remains held. Only afterward does the controller release the original response and verify that it completes on its original peer. This demonstrates selection based on ongoing occupancy, rather than merely counting how many requests each server has answered over its lifetime.

The second group assigns weight two to A and weight one to B. Three requests are started one at a time, with each left unfinished and its arrival observed before the next starts. The active snapshot becomes A=2 and B=1. All three are then released and complete successfully, showing how weights alter the effective comparison instead of always preferring the smallest raw number.

The experiment’s HTTP exchanges keep one active request on each selected upstream connection. The two peer endpoints share a disposable container, so their names do not represent separate hardware capacity. The gates demonstrate occupancy and placement; they do not create a CPU benchmark or validate a particular weight for production machines.

Compare the observed metric with the resource you need to protect

Ask what keeps an upstream connection active in the real path. A slow client may hold it longer when response buffering is disabled, while a buffered proxy can sometimes finish reading upstream before that client finishes downloading. Changing buffering can therefore change the count seen by least connections without changing the application’s intrinsic computational cost.

Measure per-peer latency, errors, queueing, and resource use alongside connection counts. If one peer is slow because a dependency is failing, directing fewer new connections there can reduce pressure but does not repair it. Health eligibility and retry policy remain separate decisions. Least connections is not an active health probe or a gradual recovery ramp for a newly returned peer.

Finally, validate the scope and protocol of the deployed implementation. A method named least connections in another product can have different weighting, persistence, and state-sharing rules. Test a held request, release, and weighted competition through the actual balancer, and use the results to justify the selected metric rather than treating the algorithm’s name as a general capacity guarantee.

Sources

nginx upstream module, least_conn weighting, ties, shared zones, and active connection state, checked 2026-09-12.
nginx HTTP load balancing guide, least-connected selection and its workload rationale, checked 2026-09-12.

A multipart boundary splits the body into parts

Wed, 10 Nov 2027 00:00:00 +0000

Multipart/form-data is one HTTP representation containing several independently described parts. A client chooses a boundary parameter, places that value in the Content-Type header, and writes matching delimiter lines into the body. The arrangement lets one request carry text fields and binary files without pretending that all bytes share one JSON or text grammar. The boundary is framing metadata, not a security decision or a file-type detector.

Preserve wire order and raw bytes. Count the epilogue in the HTTP-body budget, and commit only after complete validation.

A boundary frames the parts

Each delimiter begins with two hyphens and the declared boundary value. A closing delimiter adds two more hyphens. The boundary parameter is required for multipart media types, may need quoting, and must be one to seventy permitted characters without trailing whitespace. RFC 7578 requires that the delimiter not occur inside an encapsulated part. A long, unpredictable value makes accidental collisions unlikely, but a generator should still follow the grammar and not claim that randomness is an absolute guarantee.

The bytes before the first delimiter are a preamble and bytes after the closing delimiter are an epilogue. MIME readers ignore those areas as content; an application must not treat them as another form field. They are nevertheless part of the HTTP request body and should count toward an overall request budget. A parser reaching multipart EOF has not necessarily consumed the entire HTTP body.

Parts carry their own headers

Every form-data part needs Content-Disposition with a name parameter. File parts commonly add filename and Content-Type, but a filename is untrusted input: do not use directory components or write it directly into a filesystem path. Repeated field names are meaningful and must remain in wire order; coalescing them into one map can silently change the submitted form. Part headers are not a replacement for validating the decoded file, extension, size, or content.

Use a standards-aware parser instead of splitting the entire body on a string. It needs to recognize CRLF rules, quoted boundary parameters, the final delimiter, duplicate names, malformed headers, and binary bytes. Read each part with a per-part limit, bound the total body, cap the part count, and wait for complete validation before committing a database row or moving an upload. Streaming reduces buffering, but bounded resource use still requires limits on reading and temporary storage. Clean up staged files when later parsing fails.

A MIME parser can deliberately accept compatibility forms. For example, Go’s multipart reader accepts LF-only delimiter lines after detecting that form on the first part. Successful parsing therefore does not establish strict RFC syntax compliance. This fixture checks the listed errors and limits, not every malformed header or boundary grammar violation.

When it breaks

A common bug is hand-setting Content-Type: multipart/form-data in browser code. FormData then has a boundary in its body but no matching parameter in the header, leaving the server unable to parse it. Another is a copied boundary whose delimiter line also occurs inside a file; the parser sees a false part boundary and truncates the upload. A missing closing delimiter must be an error, not an invitation to accept a prefix.

Large fields can exhaust memory even when each part looks harmless. A request can also contain many small parts, a huge filename, an unsupported transfer-encoding header, or an epilogue large enough to cross the request limit. Do not infer that a successful NextPart means the entire message is valid. Reject malformed input before side effects, and log counts and sizes without logging file contents or credentials.

Check it quickly

The unchanged historical loopback integration has not been rerun for this source review. The earlier restricted-environment attempt stopped at listener creation; this is a historical result, not a new capability test. Compilation alone does not establish HTTP behavior.

Save this as multipart_probe.go and run go run multipart_probe.go with Go 1.23 or newer. The loopback fixture uses a quoted boundary, repeated names, a binary byte sequence, an epilogue, a total limit, per-part limits, and an acceptance counter. The counter is only a simulated commit; no file or database is modified. It requires nonempty names and rejects Content-Transfer-Encoding, using NextRawPart to avoid implicit quoted-printable decoding.

package main

import (
 "bytes"
 "encoding/json"
 "errors"
 "fmt"
 "io"
 "mime"
 "mime/multipart"
 "net/http"
 "net/http/httptest"
 "reflect"
 "runtime"
 "sync/atomic"
 "time"
)

const boundary = "probe:2026"
const totalLimit int64 = 2048
const partLimit int64 = 32
const maxParts = 3

type item struct {
 Name, Filename string
 Body []byte
}

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

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

func build(items []item) ([]byte, string) {
 var body bytes.Buffer
 writer := multipart.NewWriter(&body)
 must(writer.SetBoundary(boundary)) // Deterministic fixture, not a production boundary policy.
 for _, entry := range items {
 var part io.Writer
 var err error
 if entry.Filename == "" {
 part, err = writer.CreateFormField(entry.Name)
 } else {
 part, err = writer.CreateFormFile(entry.Name, entry.Filename)
 }
 must(err)
 _, err = part.Write(entry.Body)
 must(err)
 }
 must(writer.Close())
 return body.Bytes(), writer.FormDataContentType()
}

func main() {
 want := []item{
 {Name: "tag", Body: []byte("first")},
 {Name: "tag", Body: []byte("second")},
 {Name: "upload", Filename: "sample.bin", Body: append([]byte("inline--probe:2026-marker"), 0, 255)},
 }
 valid, contentType := build(want)
 check(contentType == "multipart/form-data; boundary=\"probe:2026\"", "boundary must be quoted")
 var committed, handled atomic.Int64
 server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 defer r.Body.Close()
 if r.Method != http.MethodPost {
 w.Header().Set("Allow", "POST")
 http.Error(w, "POST required", 405)
 return
 }
 media, parameters, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
 if err != nil || (media == "multipart/form-data" && parameters["boundary"] == "") {
 http.Error(w, "invalid multipart declaration", 400)
 return
 }
 if media != "multipart/form-data" {
 http.Error(w, "multipart/form-data required", 415)
 return
 }
 fail := func(err error) {
 var oversized *http.MaxBytesError
 if errors.As(err, &oversized) {
 http.Error(w, "total body limit", 413)
 } else {
 http.Error(w, "invalid multipart body", 400)
 }
 }
 limited := http.MaxBytesReader(w, r.Body, totalLimit)
 reader := multipart.NewReader(limited, parameters["boundary"])
 var received []item
 for {
 part, err := reader.NextRawPart()
 if err == io.EOF {
 break
 }
 if err != nil {
 fail(err)
 return
 }
 if len(received) == maxParts {
 http.Error(w, "part count limit", 413)
 return
 }
 if part.FormName() == "" || part.Header.Get("Content-Transfer-Encoding") != "" {
 http.Error(w, "named unencoded form part required", 400)
 return
 }
 data, err := io.ReadAll(io.LimitReader(part, partLimit+1))
 if err != nil {
 fail(err)
 return
 }
 if int64(len(data)) > partLimit {
 http.Error(w, "part size limit", 413)
 return
 }
 must(part.Close())
 received = append(received, item{part.FormName(), part.FileName(), data})
 }
 // Multipart EOF need not be HTTP-body EOF: epilogue bytes still count.
 if _, err := io.Copy(io.Discard, limited); err != nil {
 fail(err)
 return
 }
 committed.Add(1) // Simulated acceptance; no files or database writes.
 w.Header().Set("Content-Type", "application/json")
 must(json.NewEncoder(w).Encode(received))
 }))
 server.Config.ReadHeaderTimeout = time.Second
 server.Config.ReadTimeout = 2 * time.Second
 server.Start()
 defer server.Close()
 transport := &http.Transport{}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 3 * time.Second}
 probe := func(label, media string, payload []byte, status int) {
 before := committed.Load()
 response, err := client.Post(server.URL, media, bytes.NewReader(payload))
 must(err)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.Proto == "HTTP/1.1" && response.StatusCode == status, label+": wrong status/protocol")
 delta := int64(0)
 if status == 200 {
 var received []item
 must(json.Unmarshal(body, &received))
 check(reflect.DeepEqual(received, want), label+": names, order, or binary bytes changed")
 delta = 1
 }
 check(committed.Load() == before+delta, label+": rejected body was accepted")
 fmt.Printf("%s: status=%d accepted=%d\n", label, status, committed.Load())
 }
 truncated := bytes.TrimSuffix(valid, []byte("\r\n--"+boundary+"--\r\n"))
 check(len(truncated) < len(valid), "fixture must remove the closing delimiter")
 many, _ := build(append(append([]item(nil), want...), item{Name: "extra", Body: []byte("x")}))
 large := append([]item(nil), want...)
 large[2].Body = bytes.Repeat([]byte("x"), int(partLimit+1))
 largePart, _ := build(large)
 withEpilogue := func(extra []byte) []byte { return append(append([]byte(nil), valid...), extra...) }
 probe("valid quoted boundary", contentType, valid, 200)
 probe("small epilogue", contentType, withEpilogue([]byte("ignored epilogue")), 200)
 probe("missing boundary", "multipart/form-data", valid, 400)
 probe("wrong boundary", "multipart/form-data; boundary=other", valid, 400)
 probe("truncated delimiter", contentType, truncated, 400)
 probe("wrong media type", "application/octet-stream", valid, 415)
 probe("too many parts", contentType, many, 413)
 probe("part too large", contentType, largePart, 413)
 probe("total with epilogue", contentType, withEpilogue(bytes.Repeat([]byte("x"), int(totalLimit))), 413)
 probe("recovery", contentType, valid, 200)
 check(handled.Load() == 10 && committed.Load() == 3, "ten requests must yield three acceptances")
 fmt.Println(runtime.Version())
}

The ten requests produce three acceptances. The first keeps duplicate tag fields in order and preserves the zero and 255 bytes in the upload. A small epilogue is ignored by the multipart parser but remains part of the HTTP body. Missing or wrong boundaries, a truncated closing delimiter, the wrong media type, too many parts, an oversized part, and a total-limit breach are rejected without increasing the commit counter. The final valid request demonstrates recovery after failures. The historical author report records all assertions passing on macOS with Go 1.27.0, including race and vet checks; that report is not a new run of this revision. The fixture does not test browser FormData, disk cleanup, malformed part headers, collision injection, or production load.

Sources

RFC 7578: multipart/form-data, boundary grammar, form names, filenames, and ordering, checked 2026-09-09.
RFC 2046: Media Types, delimiter collision, length, preamble, and epilogue rules, checked 2026-09-09.
Go mime/multipart, streaming readers, raw parts, and writer boundaries, checked 2026-09-09.
Go mime, media-type parameter parsing and boundary extraction, checked 2026-09-09.
Go net/http, total-body limits, timeouts, and request lifecycle, checked 2026-09-09.
MDN: FormData, browser boundary-header behavior, checked 2026-09-09.
Go multipart reader source, first-part LF compatibility in isBoundaryDelimiterLine, checked 2026-10-19.

Server-Sent Events stream one way

Tue, 09 Nov 2027 00:00:00 +0000

Server-Sent Events carry server-to-client updates in a streaming HTTP response. They do not turn HTTP into a bidirectional socket, and automatic reconnection does not make delivery durable. Treat event framing, connection lifetime, retained history, and application acknowledgment as separate contracts.

A response contains framed text events

An SSE response uses text/event-stream and UTF-8. Fields are line-based, and a blank line ends a block. Multiple data lines within one event are joined with newline characters. A colon-prefixed comment is ignored as event data, so it can carry a heartbeat without triggering an application message.

The event field selects a named event type. Without it, the default type is message; an update event needs an update listener rather than only an onmessage handler. An unfinished event at EOF is not dispatched merely because the connection ended. Correct network delivery of bytes therefore does not prove correct event framing or listener registration.

The id field is a string, not a protocol-mandated monotonic integer. Applications may choose sequence numbers, but they must define the ordering and retention policy themselves. An empty id resets the retained ID; it is not an acknowledgment that all business work has completed.

Reconnection needs retained history

On reconnection, a browser can send its retained ID in Last-Event-ID. This is a cursor hint, not a transaction acknowledgment. The server needs an authorized, retained history and a defined way to resume after that cursor. Reopening a connection cannot reconstruct events that were never recorded or have already expired.

Define behavior when the cursor is no longer usable: obtain a fresh snapshot, reject the resume request, or follow another explicit application contract. Silently continuing from the latest event hides a gap. Consumers may also need deduplication; receiving an event does not prove that a downstream action completed exactly once.

EventSource reconnects after recoverable disconnections, while HTTP 204 explicitly stops reconnection. Other terminal failures exist, so not every error is retried forever. A retry field supplies a reconnection delay in milliseconds, but reconnection timing is not an application delivery deadline.

When it breaks

Handlers and intermediaries can buffer output even after the application has produced an event. Flush at the origin, then verify delivery across the actual proxy path. A heartbeat can help with some inactivity timers, but it does not override a fixed total request deadline. Bound subscriber queues and define what happens when a consumer cannot keep up.

Authentication and CORS still apply. Native EventSource exposes a credentials mode, not arbitrary request-header configuration. Do not assume it accepts the same authorization options as fetch. HTTP/1.x connection limits and HTTP/2 stream limits also matter when many tabs subscribe; multiplexing does not remove connection-level resource budgets.

Blank-line framing, a named listener, and retained authorized history are separate requirements. The source Go client explicitly requests replay; it does not establish automatic browser reconnection or durable delivery.

Check it quickly

Save this as sse_probe.go and run go run sse_probe.go with Go 1.23 or newer. A local server flushes a comment plus a complete named event, then keeps the response open. The client checks the exact bytes before canceling that request. The server must observe the disconnect before subsequent checks proceed.

package main

import (
 "context"
 "fmt"
 "io"
 "net/http"
 "net/http/httptest"
 "runtime"
 "sync/atomic"
 "time"
)

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

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

func main() {
 const firstFrame = ": heartbeat\n\nid: cursor-A\nevent: update\ndata: hello\ndata: world\n\n"
 const replayFrame = "id: cursor-B\nevent: update\ndata: resumed\n\n"
 disconnected, stop := make(chan struct{}), make(chan struct{})
 var handled atomic.Int64
 var firstEnded atomic.Bool
 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 handled.Add(1)
 cursor := r.Header.Get("Last-Event-ID")
 w.Header().Set("X-Received-Cursor", cursor)
 switch cursor {
 case "cursor-B":
 w.WriteHeader(http.StatusNoContent)
 return
 case "", "cursor-A":
 default:
 http.Error(w, "cursor expired; fetch a fresh snapshot", http.StatusGone)
 return
 }
 w.Header().Set("Content-Type", "text/event-stream")
 w.Header().Set("Cache-Control", "no-cache")
 frame := replayFrame
 if cursor == "" {
 frame = firstFrame
 }
 _, err := io.WriteString(w, frame)
 must(err)
 must(http.NewResponseController(w).Flush())
 if cursor == "" {
 defer firstEnded.Store(true)
 select {
 case <-r.Context().Done():
 close(disconnected)
 case <-stop:
 }
 }
 }))
 defer server.Close()
 defer close(stop)
 transport := &http.Transport{}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 2 * time.Second}
 open := func(ctx context.Context, cursor string) *http.Response {
 request, err := http.NewRequestWithContext(ctx, http.MethodGet, server.URL, nil)
 must(err)
 if cursor != "" {
 request.Header.Set("Last-Event-ID", cursor)
 }
 response, err := client.Do(request)
 must(err)
 check(response.Header.Get("X-Received-Cursor") == cursor, "server must receive the exact cursor")
 return response
 }
 ctx, cancel := context.WithCancel(context.Background())
 defer cancel()
 first := open(ctx, "")
 check(first.StatusCode == 200 && first.Header.Get("Content-Type") == "text/event-stream", "SSE response required")
 buffer := make([]byte, len(firstFrame))
 _, err := io.ReadFull(first.Body, buffer)
 must(err)
 check(string(buffer) == firstFrame && !firstEnded.Load(), "frame must arrive before handler completion")
 cancel()
 must(first.Body.Close())
 select {
 case <-disconnected:
 case <-time.After(2 * time.Second):
 panic("server did not observe disconnect")
 }
 fmt.Println("initial: comment and complete cursor-A frame arrive while response remains open")
 complete := func(cursor string, wantStatus int, wantBody string) {
 response := open(context.Background(), cursor)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.StatusCode == wantStatus && string(body) == wantBody, "wrong replay/status response")
 if wantStatus == 200 {
 check(response.Header.Get("Content-Type") == "text/event-stream", "replay must keep the SSE media type")
 }
 fmt.Printf("cursor=%s status=%d\n", cursor, response.StatusCode)
 }
 complete("cursor-A", 200, replayFrame)
 complete("expired", 410, "cursor expired; fetch a fresh snapshot\n")
 complete("cursor-B", 204, "")
 check(handled.Load() == 4, "expected four HTTP requests")
 fmt.Println("explicit replay requests; no browser reconnection or durability claim")
 fmt.Println(runtime.Version())
}

The first event contains cursor-A, the update type, and two data lines: a conforming SSE client would dispatch one update carrying hello followed by a newline and world. The comment is not another event. The fixture verifies that these complete wire blocks arrive while the initial handler is still waiting, rather than only after EOF.

A new request explicitly sends Last-Event-ID: cursor-A and receives the cursor-B frame. The server echoes the received cursor so the test can check exact transmission. An expired cursor returns 410 with a snapshot instruction; that status is this application’s policy, not an SSE-mandated cursor-expiry response. A cursor-B request receives 204 and an empty body.

All four requests passed on macOS with Go 1.27.0. Each client request has a two-second timeout, and disconnect observation has its own bound. These short deadlines are test safeguards, not universal settings for long-lived production subscriptions. Bodies, waiting handlers, and local resources are cleaned up.

The Go program checks literal framing and makes replay requests itself; it is not a browser EventSource implementation. It does not test automatic browser reconnection, proxy buffering, authentication, CORS, durable retention, exactly-once effects, or slow-consumer load. Those need separate verification beyond a successful local stream.

Sources

WHATWG: Server-sent events, framing, EventSource, event IDs, reconnection, and HTTP 204, checked 2026-09-09.
MDN: Using server-sent events, named listeners, streaming output, and connection considerations, checked 2026-09-09.
Go net/http, response flushing, cancellation, and timeout scope, checked 2026-09-09.

Request smuggling desyncs the proxy chain

Tue, 19 Oct 2027 00:00:00 +0000

Request smuggling occurs when components disagree about HTTP message boundaries and an attacker exploits the disagreement. In a proxy chain, bytes treated as one request’s body by the front end may become another request at the back end. The important evidence is inconsistent parsing and forwarding, not simply finding two HTTP status lines in a response capture.

One stream, incompatible boundaries

HTTP/1.1 framing follows explicit rules. A valid Content-Length can define the body length; chunked transfer coding ends with its terminating chunk and trailer section. A request with neither framing mechanism has no body. Transfer-Encoding takes precedence when both fields appear, but that combination is suspicious and requires special handling rather than casual acceptance.

RFC 9112 permits a server to reject a request containing both fields or process it according to Transfer-Encoding alone. Either way, it must close the connection after responding. An intermediary choosing to forward such a message must first remove the received Content-Length and process Transfer-Encoding before forwarding. Rejecting dual framing at an entry boundary is a useful strict policy, but it is not the only behavior described by the standard.

CL.TE names a front end using Content-Length and a back end using Transfer-Encoding; TE.CL reverses those choices. Other discrepancies involve conflicting lengths or inconsistent handling of transfer-coding syntax. These labels describe parser behavior, not two equally valid interpretations. Invalid input must not become a reason for different hops to guess independently.

Desynchronization has more than one impact

A complete hidden request may be processed immediately; it need not wait for a victim’s next request. Other attacks leave an incomplete prefix that combines with later traffic. Response-queue poisoning is one possible consequence, but route-filter bypass, cache poisoning, and unauthorized backend requests can matter without that exact sequence. Impact depends on connection reuse, routing, authentication, and the application’s behavior.

An extra backend request should therefore be traced to the actual bytes and connection. Counts alone are insufficient: retries, health checks, caching, and asynchronous logging can legitimately make layers disagree. A backend log entry lacking its expected edge counterpart is an investigation lead, not automatic proof. Use correlation data and a controlled fixture with identifiable synthetic requests.

When it breaks

A superficial header filter can miss ambiguity created during protocol conversion. HTTP/2 uses frames rather than HTTP/1.1 chunked delimiting, but downgrading to HTTP/1.1 creates a new serialization boundary that must be correct. For HTTP/2 requests, any Content-Length must agree with the content size; no-content responses have separate rules. It is incorrect to treat HTTP/2 as having no relevant length checks.

End-to-end HTTP/2 avoids some downgrade-specific problems, but is not a universal immunity claim. Validate protocol transitions, reject malformed messages consistently, and avoid reusing a connection after unrecoverable framing errors. A strict edge can block a specific attack even if another component is tolerant; assess each reachable path rather than asserting that hardening one hop can never help.

Client-side curl output showing HTTP/2 only establishes the protocol on that client connection. It cannot reveal the protocol used behind a CDN or reverse proxy. Similarly, two responses may simply answer two ordinary pipelined requests. A safe assessment must demonstrate which bytes each component classified and whether the result crossed an intended request boundary.

The same synthetic bytes expose incompatible boundary arithmetic. A two-request pipeline alone is not smuggling; live parser and connection behavior remain untested.

Check it quickly

Save as framing_demo.py and run python3 framing_demo.py. This offline model constructs a byte string in memory, computes the two deliberately incompatible boundaries, and checks a strict rejection policy. Nothing is sent to a server, no socket is opened, and the synthetic path identifies no real administrative endpoint. The declared length is calculated from the actual body rather than copied as a magic constant.

# An in-memory boundary model, not an HTTP parser or network probe.
followup = b'GET /synthetic-next HTTP/1.1\r\nHost: example.test\r\n\r\n'
body = b'0\r\n\r\n' + followup
head = (b'POST /upload HTTP/1.1\r\nHost: example.test\r\nContent-Length: '
 + str(len(body)).encode() + b'\r\nTransfer-Encoding: chunked\r\n\r\n')
wire = head + body
header_end = wire.index(b'\r\n\r\n') + 4
cl_boundary = header_end + len(body)
# This fixture has precisely one zero chunk and an empty trailer section.
te_boundary = header_end + len(b'0\r\n\r\n')
if wire[cl_boundary:] != b'' or wire[te_boundary:] != followup:
 raise RuntimeError('boundary expectations failed')
if cl_boundary == te_boundary:
 raise RuntimeError('the two interpretations must differ')


def reject_dual_framing(header):
 names = {line.split(b':', 1)[0].lower() for line in header.split(b'\r\n')[1:] if b':' in line}
 if {b'content-length', b'transfer-encoding'} <= names:
 raise ValueError('dual framing rejected')


try:
 reject_dual_framing(head)
except ValueError as error:
 print(error)
else:
 raise RuntimeError('ambiguous message accepted')

ordinary_first = b'GET /first HTTP/1.1\r\nHost: example.test\r\n\r\n'
ordinary_pipeline = ordinary_first + followup
first_boundary = ordinary_pipeline.index(b'\r\n\r\n') + 4
if ordinary_pipeline[first_boundary:] != followup:
 raise RuntimeError('ordinary pipeline example failed')
print('CL remaining bytes:', len(wire[cl_boundary:]))
print('TE remaining bytes:', len(wire[te_boundary:]))
print('ordinary pipeline: two intentionally separate requests')
print('PASS: different framing boundaries; dual framing rejected; pipelining distinguished')

The Content-Length interpretation leaves zero remaining bytes; the chunked interpretation leaves the complete fifty-two-byte synthetic request. The strict policy rejects the combination. A separate ordinary pipeline intentionally contains two requests and is not labeled smuggling merely because both are present. PASS confirms these limited relationships when run successfully. This source review checked the unchanged bytes and retained records without executing the model or contacting a proxy.

This is not a general HTTP parser. The chunked case contains only a zero chunk and an empty trailer section; the header check does not implement all field grammar, duplicate-header rules, or protocol conversion. It demonstrates why a boundary disagreement matters without claiming a live proxy is vulnerable. Integration testing needs an isolated, authorized chain, its actual parser versions, connection lifecycle observations, and negative cases proving ambiguous input cannot reach an unintended backend operation.

Sources

RFC 9112: HTTP/1.1, framing precedence, intermediary handling, errors, and persistent connections, checked 2026-10-15.
PortSwigger: HTTP request smuggling, parser disagreement classes and consequences, checked 2026-10-15.
RFC 9113: HTTP/2, framed content, malformed messages, and Content-Length consistency, checked 2026-10-15.

Cache invalidation is a push, not a prayer

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

Changing an origin does not notify every cache that already holds its response. Invalidation is about controlling which stored copies remain eligible for reuse, not merely updating a file. A reliable release distinguishes expiration, validation, targeted removal, and choosing a new URL. These mechanisms have different scopes, and none remotely erases every copy a reader has downloaded.

Two independent private caches make removal scope visible: changing one entry leaves the other usable. Publishing and requesting a new URL creates a separate entry; it does not erase the old URL or update every reader automatically.

Expiration is not a broadcast

A fresh response can remain usable after its source changes. Freshness is calculated from lifetime and current age, accounting for cache metadata and elapsed time; it is not simply a countdown from one origin Date header. Expiration makes direct reuse conditional on the applicable rules. It neither guarantees physical deletion nor automatically causes an idle cache to contact the origin.

Validators are consulted when a request requires validation, not pushed to clients when content changes. A correct ETag lets the origin confirm an unchanged representation or send its replacement. It cannot force a browser holding a still-fresh response to ask. Changing the origin to no-cache or no-store does not retroactively rewrite previously received caching instructions.

Identify the scope before invalidating

RFC 9111 requires a cache receiving a successful or redirect response to an unsafe method to invalidate the target URI. This affects caches on that request’s path; it is not global notification. Application database writes made through another route do not automatically invalidate every derived page, query variant, translated response, or search listing.

A CDN purge similarly controls the provider’s managed copies, not independent browser caches. Identify the affected host, paths, variants, and cache tags using the provider’s actual contract. Publish the replacement before invalidating, track completion, then compare response bodies as well as cache status. An accepted purge request alone proves neither propagation nor that the origin now serves the desired bytes.

When it breaks

Purging before the origin is updated can immediately repopulate an edge with the old response. An in-flight refill can also race with invalidation; its handling depends on the cache implementation. Repeating a broad purge is not evidence that either race is resolved. Prefer a narrowly identified object set, and account for the additional origin load when those objects become cold.

For static assets, publish a new content-fingerprinted filename before switching HTML or a manifest to reference it. Keep the old asset available while previously cached documents can still reference it. The new URL avoids confusion with the old cache entry, but readers must receive the updated document first. Updating only the asset filename without updating its referring document changes nothing for those readers.

Deletion for confidentiality is a different problem. Removing an origin object or purging a CDN cannot revoke bytes already downloaded, and a cache policy is not authorization. Prevent sensitive responses from entering inappropriate caches in the first place. For an urgent repair, define what “visible” means: a fresh visit, an existing tab, or every previously downloaded copy cannot share one guarantee.

Check it quickly

Use Python 3.10 or newer and a POSIX shell. The tested versions are Python 3.14.4, CacheControl 0.14.4, and Requests 2.34.2. Run the Python block with "$invalidation_lab/venv/bin/python" after installing the pinned dependencies. It starts one loopback HTTP server on an allocated port, uses two separate in-memory private caches, disables environment proxies, and closes its resources. Installation alone needs external network access.

invalidation_lab=$(mktemp -d)
python3 -m venv "$invalidation_lab/venv"
"$invalidation_lab/venv/bin/python" -m pip install CacheControl==0.14.4 requests==2.34.2

from collections import Counter
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Thread

import requests
from cachecontrol import CacheControl
from cachecontrol.cache import DictCache

assets = {"/manual.txt": b"A"}
counts = Counter()


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

 def do_GET(self):
 counts[self.path] += 1
 body = assets.get(self.path, b"missing")
 status = 200 if self.path in assets else 404
 self.send_response(status)
 self.send_header("Cache-Control", "max-age=600" if status == 200 else "no-store")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


server = HTTPServer(("127.0.0.1", 0), Origin)
worker = Thread(target=server.serve_forever)
worker.start()
base = f"http://127.0.0.1:{server.server_port}"
caches = [DictCache(), DictCache()]
clients = []
try:
 for cache in caches:
 client = CacheControl(requests.Session(), cache=cache)
 client.trust_env = False
 clients.append(client)

 def check(index, path, status, body, cached):
 response = clients[index].get(base + path, timeout=3)
 assert (response.status_code, response.content, response.from_cache) == (
 status, body, cached
 )

 for index in range(2):
 check(index, "/manual.txt", 200, b"A", False)
 check(index, "/manual.txt", 200, b"A", True)
 assert counts["/manual.txt"] == 2
 print("warm: two independent caches hold A; origin requests=2")

 assets["/manual.txt"] = b"B"
 caches[0].delete(base + "/manual.txt")
 check(0, "/manual.txt", 200, b"B", False)
 check(1, "/manual.txt", 200, b"A", True)
 assert counts["/manual.txt"] == 3
 print("targeted invalidation: cache 0=B; cache 1=A")

 check(1, "/manual.v2.txt", 404, b"missing", False)
 assets["/manual.v2.txt"] = b"B"
 for index in range(2):
 check(index, "/manual.v2.txt", 200, b"B", False)
 check(index, "/manual.v2.txt", 200, b"B", True)
 assert counts["/manual.v2.txt"] == 3
 check(1, "/manual.txt", 200, b"A", True)
 print("new URL: 404 before publication, then both caches=B")
 print("old URL: cache 1 still holds A")
finally:
 for client in clients:
 client.close()
 server.shutdown()
 worker.join()
 server.server_close()

Both clients first receive A from the origin, then hit their own cache. After the origin changes to B, deleting only cache zero’s exact URL makes that client retrieve B; cache one still returns A without another origin request. The old URL has reached the origin three times, demonstrating scoped removal rather than global convergence.

The new filename initially returns 404 with no-store, exposing incorrect publication order. CacheControl 0.14.4 also excludes 404 from its default cacheable statuses, so this fixture does not isolate no-store’s effect on negative caching. After publication, both clients obtain and cache B under that new URL; cache one still retains A at the original URL. This is a real HTTP and cache-storage experiment, not a CDN purge implementation or browser test. CacheControl is a private-cache library and must not be repurposed as a multi-user shared edge.

Sources

RFC 9111: invalidating stored responses, invalidation scope and unsafe methods, checked 2026-09-07.
CloudFront: invalidation and versioned filenames, edge removal does not clear independent caches, checked 2026-09-07.
CacheControl usage, sessions and separate cache stores, checked 2026-09-07.
CacheControl security model, private-cache restrictions, checked 2026-09-07.
CacheControl 0.14.4 controller, default cacheable statuses and storage checks, checked 2026-10-18.

CORS preflight checks a browser request before it is sent

Fri, 23 Jul 2027 00:00:00 +0000

A CORS preflight asks whether a browser may send a particular cross-origin request. It describes the requesting origin, intended method, and relevant header names. The browser evaluates the reply before sending that request, unless a valid preflight cache entry already grants permission. CORS also governs whether JavaScript can read the actual response. These are related checks, but neither replaces application authentication or authorization.

The trigger is the request shape

An origin consists of scheme, host, and port. Changing any of them can make a fetch cross-origin. The browser does not decide to preflight by guessing whether the server will modify data. A qualifying POST with Content-Type: text/plain can be sent without preflight, while a read-only request using an Authorization header normally needs one. Methods, header values, and other Fetch conditions determine whether the request qualifies for the safelist.

A JSON POST normally triggers preflight because application/json is not a safelisted content type. The browser sends OPTIONS to the target with Origin, Access-Control-Request-Method: POST, and an Access-Control-Request-Headers list containing content-type. It sends the header names, not their future secret values. The response must allow the origin, requested method, and relevant headers for the browser to proceed.

Apply the policy to both responses

For a restricted API, compare the origin against an exact allowlist and return one allowed origin in Access-Control-Allow-Origin. Do not return a comma-separated list or reflect arbitrary input. A public resource intended for any origin can use * for requests without credentials. Credentialed access instead requires the explicit origin and Access-Control-Allow-Credentials: true; browser cookie restrictions still apply independently.

The actual response also needs the applicable CORS fields, including on errors that the calling script is meant to read. A successful preflight does not authorize reading a later response missing those fields. When selection depends on Origin, include Vary: Origin so shared caches distinguish variants. Access-Control-Max-Age controls a dedicated preflight cache, subject to browser limits; ordinary HTTP cache behavior alone does not explain every missing OPTIONS request.

Allowing request headers and exposing response headers are separate permissions. For example, permitting a JSON POST does not automatically let JavaScript read a custom response header such as X-Request-ID; use Access-Control-Expose-Headers when that metadata is needed. Switching fetch to mode: "no-cors" is not a way to inspect a rejected response. It restricts the request and produces an opaque response whose status, headers, and body are unavailable to the calling script.

When it breaks

An authentication gateway may reject OPTIONS because the preflight lacks session cookies. Fetch preflights normally exclude those credentials, so evaluate the CORS policy before requiring the actual operation’s login. The subsequent request still needs normal authentication and permission checks. Opening the operation itself to anonymous users is not a fix for a rejected preflight.

A form-compatible POST can reach the server even when JavaScript cannot read its response. Treating a CORS error as proof that no write happened can cause duplicate submissions or leave CSRF vulnerabilities. Use the application’s CSRF defenses and idempotency rules for those concerns. Another common fault is two proxy layers adding duplicate allow-origin fields, which browsers reject even though each layer’s configuration appears plausible in isolation.

The failure boundary matters: denied preflight prevents this POST; a qualifying simple POST may run before response-read rejection. The Python fixture checks response fields and its request counter, not browser enforcement. The two browser paths require separate integration testing; the synthetic fixture is not a production API.

Check it quickly

Run this Python 3 fixture on loopback. It allows one origin, POST, and the content-type header during preflight, then tests a denied origin and a denied header. Its POST handler deliberately accepts a test body without authentication to demonstrate why response-read restrictions do not protect writes. It is not a production API.

The 204 response omits Content-Length as required by RFC 9110 §8.6, while each empty 403 explicitly sends Content-Length: 0; the assertions check both cases.

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread

ORIGIN = "https://reader.example"

class Handler(BaseHTTPRequestHandler):
 def do_OPTIONS(self):
 names = {s.strip().lower() for s in self.headers.get(
 "Access-Control-Request-Headers", "").split(",") if s.strip()}
 allowed = (self.headers.get("Origin") == ORIGIN
 and self.headers.get("Access-Control-Request-Method") == "POST"
 and names <= {"content-type"})
 self.send_response(204 if allowed else 403)
 if not allowed:
 self.send_header("Content-Length", "0")
 self.send_header("Vary", "Origin, Access-Control-Request-Method, Access-Control-Request-Headers")
 if allowed:
 self.send_header("Access-Control-Allow-Origin", ORIGIN)
 self.send_header("Access-Control-Allow-Methods", "POST")
 self.send_header("Access-Control-Allow-Headers", "content-type")
 self.end_headers()

 def do_POST(self):
 self.rfile.read(int(self.headers.get("Content-Length", "0")))
 self.server.posts += 1
 self.send_response(200)
 self.send_header("Content-Length", "2")
 self.end_headers()
 self.wfile.write(b"ok")

 def log_message(self, *args):
 pass

with ThreadingHTTPServer(("127.0.0.1", 0), Handler) as server:
 server.posts = 0
 worker = Thread(target=server.serve_forever, daemon=True)
 worker.start()
 client = HTTPConnection(*server.server_address, timeout=3)
 try:
 for origin, names, expected in [
 (ORIGIN, "content-type", 204),
 ("https://untrusted.example", "content-type", 403),
 (ORIGIN, "authorization", 403),
 ]:
 client.request("OPTIONS", "/", headers={"Origin": origin,
 "Access-Control-Request-Method": "POST",
 "Access-Control-Request-Headers": names})
 response = client.getresponse()
 response.read()
 assert response.status == expected
 assert response.getheader("Content-Length") == (
 None if expected == 204 else "0")
 assert response.getheader("Access-Control-Allow-Origin") == (
 ORIGIN if expected == 204 else None)
 print("preflight", expected)
 client.request("POST", "/", body="test", headers={
 "Origin": "https://untrusted.example", "Content-Type": "text/plain"})
 response = client.getresponse()
 assert response.read() == b"ok"
 assert response.getheader("Access-Control-Allow-Origin") is None
 assert server.posts == 1
 print("POST reached server without a readable CORS response")
 finally:
 client.close()
 server.shutdown()
 worker.join()

Expect statuses 204, 403, and 403, followed by confirmation that the POST reached the handler. This verifies the server-side decision and response fields. Python does not enforce CORS, so it cannot establish browser behavior. In a browser integration test, inspect OPTIONS and the subsequent request separately: a denied JSON preflight should suppress the POST, while a qualifying simple POST may execute and still reject the script’s read. Preserve server-side request evidence when interpreting that distinction.

Sources

Fetch Standard: CORS protocol, browser permission and response-sharing rules, checked 2026-09-06.
MDN: CORS, preflight examples, credentials, and safelisted requests, checked 2026-09-06.
MDN: Preflight request, preflight request fields and the dedicated cache, checked 2026-09-06.

A 404 page answers honestly

Sat, 03 Jul 2027 00:00:00 +0000

A 404 response has two audiences. Software needs an accurate status; a person needs a useful next step. A beautifully designed error page cannot compensate for a false 200, and a correct status does not excuse an inaccessible page. Keep both parts of the response truthful without turning a missing address into a business outage.

Choose the status before rendering

RFC 9110 says 404 means the origin found no current representation, or is unwilling to disclose that one exists. It does not establish whether the absence is permanent. Use 410 when removal is known to be likely permanent. For a documented move, redirect to the corresponding replacement; do not redirect every unknown URL to the homepage. That hides broken links and sends visitors somewhere unrelated.

A dependency outage is different from a missing resource. If a database failure prevents determining whether an object exists, preserve the appropriate server-error response instead of converting every exception into 404. Conversely, an authorization policy may deliberately conceal existence with 404. Document that decision without revealing identifiers, account membership, or permission details in the error body.

Google can classify a successful HTTP response containing an error message as a soft 404. A 200 does not guarantee indexing, and a 404 does not guarantee immediate disappearance from search results. The operational requirement is an honest status and useful content, not a promised crawler timetable.

Make the body independent and safe

Render a short explanation, a real home or index link, and enough context to recover. A static site need not add a search form or external widget just for this page. Keep its assets local and its operation independent of the database that may be failing. An API should return its documented machine-readable error format, not a successful HTML document.

Set the status before writing the body. In Go, the first body write implicitly selects 200 unless WriteHeader has already selected another status. HEAD should return the same status and applicable representation metadata as GET without transferring its content. Testing only a directly opened error-template file does not exercise the missing-resource route that invokes it.

When it breaks

A catch-all rewrite can serve the homepage for missing articles, JavaScript, or CSS files. A reverse proxy can replace the origin’s 404 with its own 200 error page. A custom handler can commit a successful header before discovering a missing file. Probe an invented path through the actual entry point, inspect the first response without following redirects, and separately check a known-good path.

Negative responses can also be cached: 404 is heuristically cacheable unless other rules or explicit controls prevent it. A long negative lifetime may hide a newly created or restored page. Choose the policy deliberately; no-store prevents new storage but is not a purge of an already stored response. Avoid echoing untrusted query strings into HTML or copying sensitive URLs into logs. Count normalized missing routes without creating unbounded metric labels.

One response, two audiences. Static illustration of the source and its limits. Reported fixture outcomes were not rerun for this graphic.

Check it quickly

Save the following as not_found_probe.go in a scratch directory and run go run not_found_probe.go. It starts one loopback HTTP/1.1 server, follows no redirects, and modifies only an in-memory restoration flag. The deliberate /soft-miss bug is a negative control, not a recommended route.

package main

import (
 "fmt"
 "io"
 "net/http"
 "net/http/httptest"
 "runtime"
 "strconv"
 "strings"
 "sync/atomic"
 "time"
)

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

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

func main() {
 const missing = `<!doctype html><title>Not found</title><h1>Page not found</h1><a href="/">Home</a>`
 var restored atomic.Bool
 server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 status, body, media := 404, missing, "text/html; charset=utf-8"
 switch r.URL.Path {
 case "/":
 status, body = 200, "<!doctype html><title>Home</title><h1>Home</h1>"
 case "/gone":
 status = 410
 case "/moved":
 status = 308
 w.Header().Set("Location", "/")
 case "/offline":
 status, body = 503, "Service temporarily unavailable"
 case "/soft-miss":
 status = 200 // Deliberate bug: the body alone cannot identify success.
 case "/restored":
 if restored.Load() {
 status, body = 200, "Restored resource"
 }
 default:
 if strings.HasPrefix(r.URL.Path, "/api/") {
 media, body = "application/json", `{"error":"not_found"}`
 }
 }
 if r.Method != "GET" && r.Method != "HEAD" {
 status, body = 405, "Method not allowed"
 w.Header().Set("Allow", "GET, HEAD")
 if media == "application/json" {
 body = `{"error":"method_not_allowed"}`
 }
 }
 w.Header().Set("Content-Type", media)
 w.Header().Set("Cache-Control", "no-store")
 w.Header().Set("Content-Length", strconv.Itoa(len(body)))
 w.WriteHeader(status) // Status must be committed before writing the body.
 if r.Method != "HEAD" {
 _, err := io.WriteString(w, body)
 must(err)
 }
 }))
 defer server.Close()
 transport := &http.Transport{}
 defer transport.CloseIdleConnections()
 client := &http.Client{Transport: transport, Timeout: 2 * time.Second,
 CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
 }
 probe := func(method, route string, status int, media string) (*http.Response, string) {
 request, err := http.NewRequest(method, server.URL+route, nil)
 must(err)
 response, err := client.Do(request)
 must(err)
 body, readError := io.ReadAll(response.Body)
 closeError := response.Body.Close()
 must(readError)
 must(closeError)
 check(response.StatusCode == status && response.Proto == "HTTP/1.1", "wrong status or protocol")
 check(response.Header.Get("Content-Type") == media, "wrong media type")
 check(response.Header.Get("Cache-Control") == "no-store", "fixture must not reuse negative responses")
 check(!strings.Contains(string(body), "do-not-echo"), "request query leaked into error page")
 fmt.Printf("%s %s: %d, body=%d bytes\n", method, request.URL.Path, status, len(body))
 return response, string(body)
 }
 const html = "text/html; charset=utf-8"
 probe("GET", "/", 200, html)
 get, body := probe("GET", "/missing?hint=do-not-echo", 404, html)
 check(body == missing && strings.Contains(body, `href="/"`), "missing page must offer a real home link")
 head, empty := probe("HEAD", "/missing", 404, html)
 check(empty == "" && head.ContentLength == get.ContentLength, "HEAD must preserve status and length without a body")
 probe("GET", "/assets/missing.css", 404, html)
 _, api := probe("GET", "/api/missing", 404, "application/json")
 check(api == `{"error":"not_found"}`, "API must not receive an HTML success page")
 probe("GET", "/gone", 410, html)
 move, _ := probe("GET", "/moved", 308, html)
 check(move.Header.Get("Location") == "/", "known move must name its target")
 probe("GET", "/offline", 503, html)
 soft, softBody := probe("GET", "/soft-miss", 200, html)
 check(softBody == missing && soft.StatusCode != get.StatusCode, "negative control must expose a soft 404")
 probe("GET", "/restored", 404, html)
 restored.Store(true)
 _, recovered := probe("GET", "/restored", 200, html)
 check(recovered == "Restored resource", "restored resource must no longer return 404")
 rejected, _ := probe("POST", "/missing", 405, html)
 check(rejected.Header.Get("Allow") == "GET, HEAD", "method rejection must describe allowed methods")
 apiRejected, apiError := probe("POST", "/api/missing", 405, "application/json")
 check(apiRejected.Header.Get("Allow") == "GET, HEAD" && apiError == `{"error":"method_not_allowed"}`, "API method errors must retain JSON")
 fmt.Println("PASS: thirteen requests; missing, moved, unavailable, and restored remain distinct")
 fmt.Println(runtime.Version())
}

The thirteen requests distinguish a healthy homepage, HTML and API misses, a missing asset, known removal, a known move, and temporary unavailability. GET and HEAD agree on the missing resource’s status and declared length, but HEAD has no body. The query marker never appears in the response. The soft-miss body is identical to the genuine error page while its 200 status exposes the defect. Restoring a resource changes its answer from 404 to 200; POST is rejected separately with 405 and Allow, and an API method error retains its JSON format.

The assertions passed with Go 1.27.0 on macOS. The fixture checks response construction, not crawler indexing, CDN negative-cache invalidation, or a production proxy configuration. Before deployment, repeat the good-path and invented-path checks against the built site’s real serving stack in both languages.

Sources

RFC 9110: HTTP Semantics, 404, 410, HEAD, and representation semantics, checked 2026-09-09.
RFC 9111: HTTP Caching, negative response storage and cache controls, checked 2026-09-09.
MDN: 404 Not Found, missing resources and custom error pages, checked 2026-09-09.
Google Search: HTTP and network errors, soft 404s and indexing behavior, checked 2026-09-09.
Go net/http, response status commitment and redirect control, checked 2026-09-09.

Canonical URLs name a preferred representation

Sat, 26 Jun 2027 00:00:00 +0000

Several URLs can deliver the same document: a tracking parameter, alternate host, or trailing-slash variant may leave the meaningful content unchanged. A canonical link identifies the preferred representation among suitable duplicates. It helps consumers interpret that relationship, but it does not redirect an HTTP request or force a search engine to select the declared URL. The declaration is useful only when its target and surrounding signals describe the actual content relationship.

Choose identity before writing the tag

Decide which public URL should represent the document, then make internal links and relevant sitemap entries consistent with that choice. Do not strip every query parameter automatically. A tracking parameter may be redundant, while a language, page number, or product selection can materially change the representation. Collapsing those URLs without comparing their meaning can point distinct documents at the wrong preferred page.

In HTML, put a link element with rel="canonical" in a valid head and use a clear target URL. An HTTP Link header can express the relation for other representations, such as a PDF. Prefer an absolute public URL to avoid ambiguous resolution through a base URL or deployment prefix. Generate it from the site’s intended public configuration, rather than accidentally publishing an internal proxy host.

Canonicalization is not limited to a single origin by the link relation itself. Cross-domain declarations need careful content and ownership review; a canonical value does not prove control of the target. For translated pages, normally select an appropriate canonical in the same language when one exists. Language alternatives and canonical duplicates describe different relationships, so sending every translation to the English homepage erases meaningful distinctions.

When it breaks

A target can return an error, redirect somewhere else, or declare another canonical. Multiple conflicting declarations can also appear when a template, plugin, and response header each choose independently. Review the complete response rather than looking for the mere presence of one tag. Keep the preferred target usable and the declarations consistent with the actual representation.

An ordinary link relation leaves the original URL accessible unless routing separately changes it. If an old route should move for all clients, configure an appropriate HTTP redirect and verify its method behavior. If variants remain useful, a canonical declaration may coexist with successful responses at them. Do not equate the metadata signal with a redirect, an authorization rule, or an instruction that a crawler must obey.

Search engines combine signals and may choose another canonical. A correct tag therefore does not prove that indexing has converged. Distinguish what the origin serves from what a search service reports. Check for inconsistent internal links, sitemap entries, redirects, or language metadata before assuming that adding more copies of the same tag will solve disagreement.

Duplicates converge; languages stay distinct. Static illustration of the source and its limits. Reported fixture outcomes were not rerun for this graphic.

Check it quickly

Save this as canonical.py and run python3 canonical.py. The script creates a temporary loopback HTTP origin and reads actual HTML responses with Python’s HTML parser. It serves an English document, a tracking variant, a Chinese document, and two intentionally inconsistent metadata cases. The local URLs are demonstration identities, not search-engine submissions.

from html.parser import HTMLParser
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
import json


class Canonical(HTMLParser):
 def __init__(self):
 super().__init__()
 self.urls = []

 def handle_starttag(self, tag, attrs):
 values = dict(attrs)
 if tag == 'link' and 'canonical' in values.get('rel', '').split():
 self.urls.append(values.get('href'))


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 origin = f'http://127.0.0.1:{self.server.server_port}'
 chinese = self.path.startswith('/zh/')
 target = '/zh/article' if chinese else '/article'
 if self.path == '/zh/wrong':
 target = '/article'
 link = f'<link rel="canonical" href="{origin}{target}">'
 if self.path == '/conflict':
 link += f'<link rel="canonical" href="{origin}/another">'
 title = '中文文章' if chinese else 'English article'
 data = f'<!doctype html><html lang="{"zh" if chinese else "en"}"><head><meta charset="utf-8"><title>{title}</title>{link}</head><body><h1>{title}</h1></body></html>'.encode()
 self.send_response(200)
 self.send_header('Content-Type', 'text/html; charset=utf-8')
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 origin = f'http://127.0.0.1:{server.server_port}'

 def fetch(path):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 text = response.read().decode()
 parsed = Canonical()
 parsed.feed(text)
 return response.status, response.getheader('Location'), text, parsed.urls
 finally:
 connection.close()

 variant = fetch('/article?utm_source=example')
 primary = fetch('/article')
 translated = fetch('/zh/article')
 assert variant[:2] == (200, None) and variant[2] == primary[2]
 assert variant[3] == [origin + '/article']
 assert translated[3] == [origin + '/zh/article']
 wrong = fetch('/zh/wrong')
 conflict = fetch('/conflict')
 assert wrong[3] != [origin + '/zh/article']
 assert len(conflict[3]) == 2
 print(json.dumps({'variant_status': variant[0], 'variant_redirect': variant[1],
 'same_representation': variant[2] == primary[2],
 'english_target': variant[3], 'chinese_target': translated[3],
 'wrong_language_detected': True, 'conflicting_targets': len(conflict[3]),
 'search_engine_selection_tested': False}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

The tracking variant returns 200 without a Location header. Its bytes match the English primary page and its canonical points to /article. The Chinese page instead points to /zh/article. This verifies both the duplicate relationship in the fixture and the separation between the language representations.

The wrong-language case points a Chinese response at the English target, while the conflicting case emits two different canonical targets. Both still return 200, so a status-only check would miss the inconsistency. The assertions identify those specific errors by inspecting the metadata and the intended language mapping.

No crawler participates, and the small parser is not a complete canonicalization validator. The experiment establishes served declarations and response behavior, not Google’s selected canonical or ranking. Before changing production identity, review equivalent content, public targets, incoming routes, and language relationships together. Preserve existing URLs or their deliberate redirects so a metadata cleanup does not quietly break users’ saved links.

Sources

RFC 6596: canonical link relation, preferred representations and the scope of the link relation, checked 2026-09-13.
Google: consolidate duplicate URLs, canonical signals, consistent targets, and language handling, checked 2026-09-13.

Cookie flags constrain a supporting client

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

Secure, HttpOnly, and SameSite describe different restrictions that a supporting browser applies to cookies. The server receives the resulting name/value pairs, not a certificate that those restrictions were enforced. Keep browser behavior and server authorization separate: a cookie can be correctly delivered while the requested action is still forbidden.

Separate setting, sending, and script access

Secure restricts transmission to secure connections, normally HTTPS. Modern browser cookie rules also reject Secure cookies set from insecure contexts, with development exceptions such as localhost that must be checked in the target browser. This is more than a transmission flag. A redirect to HTTPS cannot retract a token already sent on an earlier plaintext request; deploy HTTPS and an appropriate HSTS policy as complementary protections.

HttpOnly prevents access through non-HTTP scripting APIs such as document.cookie. It does not prevent the browser from attaching that cookie to eligible requests initiated by script. Injected same-origin JavaScript can therefore still perform actions as the user even when it cannot read the token. Prevent and contain XSS independently; HttpOnly reduces one theft route rather than neutralizing the vulnerability.

SameSite adds request-context restrictions. Strict generally permits same-site requests; Lax also permits cross-site top-level navigations using safe methods. An explicit Lax cookie is not sent merely because a cross-site POST originated in a top-level page. None removes this particular restriction but requires Secure in supporting browsers. Third-party cookie blocking, storage partitioning, and the Fetch credentials mode can still prevent transmission.

A site is not an origin

For ordinary HTTPS domains, the scheme and registrable domain define the relevant schemeful site boundary. Two HTTPS sibling subdomains can be same-site while remaining different origins. Different ports also create different origins without necessarily changing the site. Consequently, Strict is not a promise to exclude every cross-origin request, and a compromised same-site sibling remains relevant to CSRF defenses.

Absent or invalid SameSite is also not a portable synonym for explicit Lax. The cookie specification permits a compatibility mode for recently created cookies with no explicit value, allowing some unsafe top-level requests. The often-mentioned two-minute window is an implementation-oriented compatibility limit, not a guarantee for every browser. Set the intended value and test supported browser versions.

When it breaks

A state-changing GET remains dangerous under Lax because a cross-site top-level safe-method navigation can carry the cookie. Make state changes require appropriate methods and server-side CSRF protection. Conversely, Strict can withhold a cookie required during a cross-site identity-provider callback. Trace the actual redirect chain and callback method; not every SSO flow fails, and a bookmark alone is not evidence of a cross-site redirect.

Use the identity library’s supported correlation and callback design rather than indiscriminately weakening the main session. Origin or Fetch Metadata checks can help when configured with explicit policies for missing headers and legitimate cross-site flows. Non-browser clients can forge these headers, so they are browser-context signals, not credentials. A client that already possesses a stolen session token needs authentication and revocation controls, not another SameSite check.

Check it quickly

Save this as cookie-flags.py and run python3 cookie-flags.py with Python 3.11 or newer. It uses the real standard-library CookieJar with synthetic response metadata, but performs no network requests. Its purpose is to expose the difference between this HTTP client’s cookie policy and a browser’s policy.

from email.message import Message
from http.cookiejar import CookieJar
from http.cookies import SimpleCookie
from urllib.request import Request


class Response:
 def info(self):
 headers = Message()
 for value in [
 "secure_sid=synthetic; Path=/; Secure; HttpOnly; SameSite=Lax",
 "strict_pref=synthetic; Path=/; SameSite=Strict",
 "insecure_none=synthetic; Path=/; SameSite=None",
 ]:
 headers.add_header("Set-Cookie", value)
 return headers


jar = CookieJar()
jar.extract_cookies(Response(), Request("https://app.example.com/login"))


def outgoing(url):
 request = Request(url)
 jar.add_cookie_header(request)
 header = request.get_header("Cookie", "")
 parsed = SimpleCookie()
 parsed.load(header)
 assert "SameSite" not in header and "HttpOnly" not in header
 return set(parsed)


assert outgoing("http://app.example.com/") == {"strict_pref", "insecure_none"}
assert outgoing("https://app.example.com/") == {
 "secure_sid", "strict_pref", "insecure_none"
}
manual = Request("http://app.example.com/",
 headers={"Cookie": "secure_sid=synthetic"})
assert manual.get_header("Cookie") == "secure_sid=synthetic"
print("PASS: CookieJar filters Secure; it does not enforce SameSite")
print("PASS: request headers omit attributes; a manual header bypasses the jar")

The jar withholds secure_sid over HTTP and includes it over HTTPS, even though it is HttpOnly. It accepts insecure_none and sends strict_pref without modeling a page’s same-site context. Those latter results demonstrate this client’s limitations; they are not browser expectations. Constructing a Cookie header manually also bypasses the jar completely. No server response or browser outcome is established by this test.

Secure, HttpOnly, and SameSite address different browser boundaries. The article’s CookieJar uses synthetic metadata with no network requests: it withholds secure_sid on HTTP, includes it on HTTPS, and does not enforce SameSite. Server authorization is separate.

For browser validation, use isolated same-site and cross-site test pages with synthetic values, checking cookie acceptance separately from outgoing requests. Cover top-level GET, POST callbacks, embedded fetches, and the application’s credentials mode. A curl request with a forged Sec-Fetch-Site header cannot establish SameSite enforcement, and an arbitrary HTTP status cannot prove that a cookie was accepted or an action authorized.

Sources

Cookie specification draft 22, storage, retrieval, SameSite and optional compatibility behavior, checked 2026-10-15.
Python CookieJar, client cookie processing and its documented protocol scope, checked 2026-10-15.
OWASP CSRF prevention, SameSite limitations, origin and Fetch Metadata defenses, checked 2026-10-15.

HTTP keep-alive reuses one TCP connection

Fri, 28 May 2027 00:00:00 +0000

HTTP persistence lets several request and response exchanges use one connection. That can avoid repeated TCP setup and, for HTTPS, repeated TLS negotiation. The benefit depends on latency, request size, and whether another usable connection already exists. Persistence does not make application work disappear, nor does it promise that a socket will remain open indefinitely.

In the source HTTP/1.1 exercise, /one, /two and /close share one socket; /four uses a new socket. All four responses are 200 with Content-Length: 2 and body ok, which is fully read before the next request. Connection: close on /close forces the later reconnect. This is an observed local sequential fixture result, not HTTP/2 or end-to-end proxy evidence. Unchanged exercise checked on 2026-10-17 with Python 3.14.4.

Reuse requires complete messages

HTTP/1.1 connections are persistent by default unless a participant signals Connection: close or closes the transport. Adding Connection: keep-alive is normally unnecessary. A client connection pool can retain an idle connection for another compatible request, subject to the client’s origin, proxy, certificate, and pool policies. Two separate command-line client processes generally do not share such a pool.

Both sides must know where each message ends. A response body can be delimited by an accurate Content-Length, chunked transfer coding, or the rules for responses without bodies. A response whose end is defined only by connection closure cannot leave that connection reusable. The client must consume the response body before reuse; the server must consume the request body or close. Otherwise leftover bytes could be mistaken for the following message.

HTTP persistence is also distinct from TCP keepalive. TCP keepalive probes a sufficiently idle transport to help detect an unreachable peer. It neither delimits HTTP messages nor overrides an application server’s idle timeout. Confusing the two can leave a client repeatedly trying connections that a proxy has already retired.

Sequential reuse also differs from pipelining: a client can wait for each response before sending the next request and still reuse the connection. HTTP/1.1 pipelining sends requests ahead but requires responses in order. Persistence alone therefore does not provide the independent response streams associated with HTTP/2 multiplexing.

Each hop owns its timeout

An idle timeout measures inactivity according to a particular implementation; a request deadline bounds an individual operation. Treat them as separate controls. A reverse proxy has a client-side connection and an upstream connection, with potentially different protocols and timeout policies. Reuse observed between a browser and the edge proves nothing about reuse between that edge and the origin.

An idle pool should retire connections with the server’s known limits in mind, but timing races still exist: the server may close just as the client sends again. Monitor connection creation, successful reuse, resets, and pool occupancy alongside latency. Longer retention saves handshakes while reserving descriptors and memory. There is no universal timeout that follows from a site being busy.

When it breaks

A response with an incorrect length can hang the reader or corrupt the boundary of the next exchange. Diagnose framing before increasing timeouts. A client that abandons streamed responses without consuming or closing them can also exhaust its pool; queued requests then wait even though the server has spare capacity.

A stale connection may fail after the request reached the server. Reconnecting and replaying a payment automatically can duplicate it. Retry according to method semantics and the application’s idempotency contract, since a transport error alone does not establish whether work committed. HTTP/2 multiplexes streams but forbids HTTP/1.x connection-specific headers such as Connection and Keep-Alive; copying these headers into an HTTP/2 configuration is not a reuse optimization.

Check it quickly

Run this complete Python 3 experiment. It binds an available loopback port, sends four sequential requests, and shuts down its test server. No external service is required; the HTTP server is a local fixture, not a deployment example.

Validation (2026-10-17): The unchanged exercise passed on Python 3.14.4 (macOS arm64), with assertions enabled and loopback-only guards. The scope limits below still apply.

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread

class Handler(BaseHTTPRequestHandler):
 protocol_version = "HTTP/1.1"

 def do_GET(self):
 self.server.connections.append(self.connection)
 self.send_response(200)
 self.send_header("Content-Length", "2")
 if self.path == "/close":
 self.send_header("Connection", "close")
 self.end_headers()
 self.wfile.write(b"ok")

 def log_message(self, *args):
 pass

with ThreadingHTTPServer(("127.0.0.1", 0), Handler) as server:
 server.connections = []
 worker = Thread(target=server.serve_forever, daemon=True)
 worker.start()
 client = HTTPConnection(*server.server_address, timeout=3)
 try:
 for path in ("/one", "/two", "/close", "/four"):
 client.request("GET", path)
 response = client.getresponse()
 assert response.status == 200
 assert response.read() == b"ok"
 sockets = server.connections
 print("reused:", sockets[0] is sockets[1] is sockets[2])
 print("new after close:", sockets[2] is not sockets[3])
 finally:
 client.close()
 server.shutdown()
 worker.join()

Expect reused: True and new after close: True. The complete body reads permit the first three exchanges to share a socket; the explicit close makes the fourth reconnect. These observations establish local HTTP/1.1 reuse, not TLS savings, browser pool behavior, or production proxy settings. Inspect connection identifiers on each real hop before extending that conclusion to a deployed service.

Sources

RFC 9112: HTTP/1.1 connection management, framing, persistence, retries, and closure, checked 2026-09-06.
MDN: Connection management in HTTP/1.x, persistent connections and their costs, checked 2026-09-06.
RFC 9113: HTTP/2 connection-specific fields, fields prohibited in HTTP/2 messages, checked 2026-09-06.

Retry-After tells when to try again

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

Retry-After tells a client how long it ought to wait before a follow-up request. It is a scheduling signal, not proof that the next attempt will succeed or that replaying the original operation is safe. A client still needs a deadline, an attempt policy, and a decision about which operations it can retry.

Interpret the value and its context

RFC 9110 permits either a nonnegative decimal integer number of seconds or an HTTP date. Delay-seconds are measured after receiving the response, not after sending the original request. An HTTP date names an absolute UTC time, so interpreting it depends on the client’s wall clock being reasonably accurate.

Senders generate the preferred IMF-fixdate form. Recipients parsing HTTP dates must accept the two obsolete forms as well; the two-digit year in the old RFC 850 form has a fifty-year interpretation rule. Negative numbers, fractional seconds, and arbitrary words are not valid delay-seconds. Zero and a date already in the past do not require additional server-directed waiting.

With 503, the field estimates how long the service is expected to be unavailable. With a 3xx response, it asks for a minimum wait before the redirected request. RFC 6585 separately permits Retry-After on 429 responses. It is optional there, not a header every throttling response is required to contain.

Respect the wait without waiting forever

A valid wait can exceed the caller’s remaining deadline. The client can stop retrying and report failure or arrange a separate authorized workflow. It should not shorten a server-requested wait and retry early merely to fit a convenient local cap. A long value is not automatically malformed.

After converting an absolute date into a delay, schedule and account for elapsed time with a monotonic clock. Recheck the deadline before the actual attempt, reserving time for that attempt to finish. Clock skew, response transit time, and scheduling delays are reasons to distinguish a plan from observed retry timing.

When the field is absent or unusable, a bounded client policy can use its own backoff. That is a client decision, not a server-supplied recovery estimate. Keep maximum attempts and total elapsed time explicit so that an optional field does not turn transient failure into unlimited retries.

The same delay can synchronize callers

If thousands of clients receive the same delay at about the same time, they can return together. Retry-After alone does not spread them across a recovery window. Add nonnegative jitter after respecting the requested delay, or otherwise schedule no earlier than that boundary.

Combining local backoff and server guidance requires preserving both constraints. The example takes the larger of its local backoff and parsed server delay, then adds positive jitter. Its injected offsets demonstrate the scheduling relationship; they are not measurements of real distributed traffic or a recommendation for a particular production jitter range.

When it breaks

Blindly replaying a write can duplicate side effects when the original outcome was uncertain. A 429 or 503 response and a Retry-After field do not grant an idempotency guarantee. Use the application’s retry contract, including any operation identifiers or deduplication rules, before repeating nonidempotent work.

Libraries also differ in automatic retries and redirect handling. Verify which statuses, methods, and fields the actual client honors. The fixture’s policy retries only GET and HEAD after 429 or 503; it deliberately does not follow redirects or replay POST. That is a bounded example policy, not the full set of methods HTTP considers idempotent.

Malformed values, huge waits, stale dates, exhausted deadlines, and attempt limits belong in tests. Observe actual attempts and delay rather than assuming that configuring a header caused clients to obey it. The service can remain unavailable after its estimate, so retries still need a terminal outcome.

Wait at least as long as both server guidance and local backoff require, then add nonnegative jitter. These are injected scheduling plans, not observed timed retries or a replay-safety guarantee.

Check it quickly

Save the block as retry_check.py and run python3 retry_check.py with Python 3.10 or newer. Only the standard library is required. The script makes real requests to its own loopback HTTP server, uses a fixed fixture date and injected clocks, then stops that server. It does not sleep until a retry or contact an external service.

Validation (2026-10-17): The unchanged exercise passed on Python 3.14.4 (macOS arm64), with assertions enabled and loopback-only guards. The scope limits below still apply.

from datetime import datetime, timedelta, timezone
from email.utils import format_datetime, parsedate_tz
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, HTTPServer
import re
from threading import Thread


UTC = timezone.utc
REFERENCE = datetime(2026, 9, 8, 12, 0, 0, tzinfo=UTC)


def delay_seconds(value, received_wall):
 if value is None:
 return None
 value = value.strip(" \t")
 if re.fullmatch(r"[0-9]+", value):
 # Huge decimal values become infinity and fail the bounded retry budget.
 return float(value)
 parts = parsedate_tz(value)
 if parts is None:
 return None
 year, month, day, hour, minute, second = parts[:6]
 old_date = re.fullmatch(r"[A-Za-z]+, [0-9]{2}-[A-Za-z]{3}-([0-9]{2}) [0-9:]{8} GMT", value)
 if old_date:
 now = datetime.fromtimestamp(received_wall, UTC)
 year = now.year // 100 * 100 + int(old_date[1])
 if (year, month, day, hour, minute, second) > (
 now.year + 50, now.month, now.day, now.hour, now.minute, now.second
 ):
 year -= 100
 if not 0 <= second <= 60:
 return None
 try:
 stamp = datetime(year, month, day, hour, minute, min(second, 59), tzinfo=UTC)
 stamp += timedelta(seconds=(second == 60) - parts[9])
 except (ValueError, OverflowError):
 return None
 return max(0.0, stamp.timestamp() - received_wall)


def retry_at(status, method, value, received_wall, monotonic_now, remaining, attempt, jitter=0.25):
 assert attempt >= 1 and jitter >= 0
 if status not in (429, 503) or method not in ("GET", "HEAD") or attempt >= 3:
 return None
 server_delay = delay_seconds(value, received_wall)
 wait = max(server_delay or 0.0, 2 ** (attempt - 1)) + jitter
 if wait >= remaining:
 return None
 return monotonic_now + wait


wall = REFERENCE.timestamp()
for value in ("Tue, 08 Sep 2026 12:00:07 GMT", "Tuesday, 08-Sep-26 12:00:07 GMT",
 "Tue Sep 8 12:00:07 2026"):
 assert delay_seconds(value, wall) == 7
assert delay_seconds("Sunday, 06-Nov-94 08:49:37 GMT", wall) == 0
assert delay_seconds("Monday, 08-Sep-70 12:00:00 GMT", wall) == (
 datetime(2070, 9, 8, 12, tzinfo=UTC).timestamp() - wall
)
assert delay_seconds("Sat, 31 Dec 2016 23:59:60 GMT",
 datetime(2016, 12, 31, 23, 59, 59, tzinfo=UTC).timestamp()) == 1
for invalid in ("-1", "1.5", "later", "", "٣", "Tue, 31 Feb 2026 12:00:00 GMT"):
 assert delay_seconds(invalid, wall) is None
assert delay_seconds(" 0003\t", wall) == 3
assert retry_at(503, "GET", "9" * 5000, wall, 100, 10, 1) is None
assert retry_at(503, "GET", "3", wall, 100, 2, 1) is None
assert retry_at(503, "POST", "3", wall, 100, 10, 1) is None
assert retry_at(503, "GET", "3", wall, 100, 10, 3) is None
print("both delay forms, obsolete dates, year interpretation, and invalid values are checked")
print("an oversized wait, exhausted deadline, POST, or attempt cap stops this retry policy")

cases = {
 "/seconds": (429, "3"),
 "/date": (503, format_datetime(REFERENCE + timedelta(seconds=7), usegmt=True)),
 "/invalid": (503, "later"),
 "/missing": (503, None),
 "/redirect": (307, "3"),
 "/ready": (200, None),
}
visited = []


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 visited.append(self.path)
 status, value = cases.get(self.path, (404, None))
 self.send_response_only(status)
 self.send_header("Date", format_datetime(REFERENCE, usegmt=True))
 if value is not None:
 self.send_header("Retry-After", value)
 if status == 307:
 self.send_header("Location", "/ready")
 self.send_header("Content-Length", "0")
 self.end_headers()

 def log_message(self, *_):
 pass


with HTTPServer(("127.0.0.1", 0), Handler) as server:
 thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.05})
 thread.start()
 try:
 for route, expected in (("/seconds", 103.25), ("/date", 107.25),
 ("/invalid", 101.25), ("/missing", 101.25), ("/redirect", None)):
 client = HTTPConnection(*server.server_address, timeout=2)
 try:
 client.request("GET", route)
 response = client.getresponse()
 response.read()
 planned = retry_at(response.status, "GET", response.getheader("Retry-After"),
 wall, 100, 10, 1)
 assert planned == expected
 print(route, "status", response.status, "planned monotonic time", planned)
 finally:
 client.close()
 assert "/ready" not in visited
 finally:
 server.shutdown()
 thread.join(timeout=2)
 assert not thread.is_alive()

same_delay = [retry_at(429, "GET", "3", wall, 100, 10, 1, jitter=0) for _ in range(4)]
spread = [retry_at(429, "GET", "3", wall, 100, 10, 1, jitter=j) for j in (0.1, 0.2, 0.3, 0.4)]
assert same_delay == [103] * 4
assert len(set(spread)) == 4 and min(spread) > 103
print("identical server delays synchronize plans; injected positive jitter spreads them:", spread)

Parser checks cover the listed dates and invalid values. email.utils also accepts non-HTTP date syntax: this is a permissive scheduling demonstration, not a strict RFC grammar validator. The bounded policy abandons a wait exceeding its deadline, POST replay, and attempts beyond its cap.

The local 429 with three seconds plans time 103.25 from injected monotonic time 100. The dated 503 plans 107.25. Missing or invalid fields use the stated local backoff, while the redirect is not followed. Identical delays produce four plans at 103; supplied positive jitter produces 103.1 through 103.4.

These are response and scheduling-decision tests. Actual timed retries, clock corrections, network partitions, proxy behavior, production jitter distributions, and business-operation deduplication remain untested.

Sources

RFC 9110, sections 5.6.7 and 10.2.3 define HTTP dates and Retry-After, checked 2026-10-15.
RFC 6585, optional Retry-After with 429 responses, checked 2026-10-15.
Python email utilities, date parsing, UTC offsets, and formatted timestamps, checked 2026-10-15.

HTTP · XB Field Notes

nginx validators are only as sound as their representation identity

When it breaks

Check it quickly

Make deployments preserve the validator contract

Sources

gzip, HTTP/2, and Brotli need separate verification

When it breaks

Check it quickly

Verify capabilities before comparing performance

Further reading

Sources

Choose whether nginx redirects the client or rewrites internally

When it breaks

Check it quickly

Test the transition the client actually receives

Further reading

Sources

Cache-Control is a contract between cache and origin

Both sides must agree

When it breaks

Check it quickly

Sources

The CONNECT method opens a raw tunnel

Switch protocols at the right boundary

Opaque content still consumes resources

When it breaks

Check it quickly

Further reading

Sources

Cache freshness is judged against a clock

Count the age

When it breaks

Check it quickly

Sources

A token bucket bounds admission and allows bursts

Refill credit, then charge work

A burst allowance is not a peak rate

Match the budget to its scope

When it breaks

Check it quickly

Further reading

Sources

Accept headers let the server negotiate a reply

Keep the dimensions separate

When it breaks

Check it quickly

Sources

Webhooks push events instead of polling

Delivery policy belongs to the provider

Authenticate, retain, then acknowledge

When it breaks

Check it quickly

Further reading

Sources

Least connections measures occupied connections, not every kind of load

When it breaks

Check it quickly

Compare the observed metric with the resource you need to protect

Sources

A multipart boundary splits the body into parts

A boundary frames the parts

Parts carry their own headers

When it breaks

Check it quickly

Further reading

Sources

Server-Sent Events stream one way

A response contains framed text events

Reconnection needs retained history

When it breaks

Check it quickly

Further reading

Sources

Request smuggling desyncs the proxy chain

One stream, incompatible boundaries

Desynchronization has more than one impact

When it breaks

Check it quickly

Sources