Testing · XB Field Notes

Loopback returns to the caller’s network namespace

Tue, 17 Nov 2026 00:00:00 +0000

Loopback addresses let a process communicate through its local IP stack without sending the exchange over a physical network link. IPv4 reserves 127.0.0.0/8 for loopback; 127.0.0.1 is the familiar member. IPv6 uses ::1. On Linux, the relevant local networking context is a network namespace. Two processes on the same physical machine can therefore have different answers to what counts as their own loopback service.

When it breaks

A client inside a container often fails when configured with 127.0.0.1 for a database running on the host or in another container. The client has asked for its own namespace’s listener. The spelling is correct but the topology is wrong. A published host port, a container interface address, and another process’s loopback are different destinations that must be selected according to the deployment.

Loopback is not a guarantee that every probe succeeds. The target port still needs a listener, the intended address family must be available, and local networking policy can affect delivery. A successful IPv4 request does not prove that a service also listens on ::1. Conversely, a refused connection can simply mean there is no listener at that address and port in the caller’s namespace.

Local delivery also does not eliminate the IP stack. Loopback traffic still uses sockets, protocol processing, and local routing decisions; it merely avoids a physical trip through the external network. Timing a request to loopback cannot validate switch configuration, remote routing, an internet firewall, or the public service name’s certificate. Keep those paths separate when interpreting a health check.

Same address, separate local worlds. IPv4-only intended exercise; IPv6 requires separate setup. No reproduced run or technical acceptance is claimed.

Check it quickly

Source review, 2026-10-19: this revised exercise uses IPv4 only. Docker’s none driver omits ::1; a separate IPv6 experiment must establish and verify that configuration first. Technical and execution acceptance remain on hold pending an authorized complete run. Results below are expectations, not reproduced measurements.

Save as check-loopback.py and run python3 check-loopback.py on a permitted Linux Docker host with the pinned image already present. Its claimed Python version remains unverified. The script forbids image pulls and publishes no ports. A serves IPv4 port 19091; B initially has no listener:

import json,re,subprocess,sys,tempfile,time
from pathlib import Path

image='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
server=r'''
import json,os,socket,sys,time
deadline=time.monotonic()+120
with socket.socket(socket.AF_INET,socket.SOCK_STREAM) as listener:
 listener.bind(('127.0.0.1',19091));listener.listen(8);listener.settimeout(.25)
 while time.monotonic()<deadline:
 try:connection,peer=listener.accept()
 except TimeoutError:continue
 with connection:
 connection.settimeout(1)
 connection.sendall(json.dumps({'service':sys.argv[1],'netns':os.readlink('/proc/self/ns/net')}).encode())
'''
probe=r'''
import json,os,socket,time
try:
 deadline=time.monotonic()+2
 with socket.create_connection(('127.0.0.1',19091),timeout=1) as stream:
 payload=b''
 while True:
 remaining=deadline-time.monotonic()
 if remaining<=0:raise TimeoutError('response deadline')
 stream.settimeout(min(1,remaining))
 piece=stream.recv(1024)
 if not piece:break
 payload+=piece;assert len(payload)<=4096,'oversize response'
 answer=json.loads(payload)
except ConnectionRefusedError:answer={'error':'ECONNREFUSED'}
print(json.dumps({'netns':os.readlink('/proc/self/ns/net'),'interfaces':socket.if_nameindex(),
 'answers':{'127.0.0.1':answer}}))
'''
def docker(*args,timeout=30):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=timeout)
 assert result.returncode==0,result.stderr
 return result.stdout
def owned_id(path):
 value=path.read_text().strip()
 assert re.fullmatch('[0-9a-f]{64}',value),'missing or invalid owned container ID'
 return value
def remove_owned(paths):
 errors=[]
 for path in paths:
 try:
 cid=owned_id(path)
 print('Cleanup target: '+cid,file=sys.stderr)
 docker('rm','-f',cid,timeout=10)
 except Exception as error:
 errors.append(f'{path.name}: {error}')
 if errors:raise RuntimeError('Cleanup not confirmed; inspect the recorded IDs: '+'; '.join(errors))
def inspect(cid,timeout=5):
 result=json.loads(docker('exec',cid,'python3','-c',probe,timeout=timeout))
 assert set(result['answers'])=={'127.0.0.1'},'missing or extra probe address'
 assert re.fullmatch(r'net:\[\d+\]',result['netns']),'invalid namespace ID'
 assert any(interface[1]=='lo' for interface in result['interfaces']),'loopback missing'
 return result
def expected(result,identity):
 return {'127.0.0.1':{'service':identity,'netns':result['netns']}}
def wait_for(cid,identity):
 deadline=time.monotonic()+5
 while True:
 remaining=deadline-time.monotonic()
 if remaining<=0:raise AssertionError('listener did not become ready')
 result=inspect(cid,timeout=remaining)
 if time.monotonic()>deadline:raise AssertionError('readiness deadline exceeded')
 if result['answers']==expected(result,identity):return result
 assert result['answers']=={'127.0.0.1':{'error':'ECONNREFUSED'}},'unexpected service response'
 time.sleep(min(.05,max(0,deadline-time.monotonic())))
with tempfile.TemporaryDirectory(prefix='xbcatm-loop-') as work:
 paths=[];ids=[]
 try:
 for identity,command in [('A',['python3','-u','-c',server,'A']),
 ('B',['python3','-c','import time;time.sleep(120)'])]:
 path=Path(work)/(identity+'.cid');paths.append(path)
 docker('create','--cidfile',str(path),'--pull','never','--network','none',
 '--memory','128m','--pids-limit','64',image,*command)
 cid=owned_id(path);ids.append(cid)
 print('Owned container: '+cid,file=sys.stderr)
 docker('start',cid)
 a=wait_for(ids[0],'A');b_before=inspect(ids[1])
 assert a['netns']!=b_before['netns']
 assert b_before['answers']=={'127.0.0.1':{'error':'ECONNREFUSED'}}
 docker('exec','-d',ids[1],'python3','-u','-c',server,'B')
 b_after=wait_for(ids[1],'B');a_after=inspect(ids[0])
 assert b_after['netns']==b_before['netns']
 assert a_after['netns']==a['netns']
 assert a_after['answers']==expected(a_after,'A')
 report={'A':a,'B_before_listener':b_before,'B_after_listener':b_after,'A_still_A':a_after}
 finally:
 remove_owned(paths)
print(json.dumps(report,sort_keys=True))

A probe inside A should reach 127.0.0.1 and read identity A. The response carries the server’s network namespace identifier, which must match the probe’s own. The expected address key and full response are checked explicitly; an empty answer map cannot count as readiness. Wrong identities, malformed responses, timeouts, or unexpected errors fail rather than masquerading as success.

Inside B, the same probe should receive ECONNREFUSED while A remains available, and B’s namespace identifier must differ. Literal IPv4 avoids DNS and localhost resolution ambiguity. Only connection refusal counts as the intended negative result; other failures stop the exercise. Readiness retries only the expected refusal, with a five-second budget and each command limited to the remaining time.

After starting B’s listener on the identical address and port, B should return B, while A still returns A. Repeated probes must retain their namespace identities. The inventory checks for lo without requiring it to be the sole interface. No claim about a particular kernel’s extra interfaces is established here, and no IPv6 exchange is attempted.

Servers use a 120-second loop budget; responses have a two-second deadline and size limit. Docker calls have timeouts; process creation can delay them. Cleanup uses full IDs from private CID files, tries every recorded target, and must succeed before final JSON. Interrupted creation or daemon failure can leave cleanup uncertain: retain diagnostics and investigate, without deleting guessed names. Run ordinary Python without optimization that removes assertions.

Put probes in the context they claim to test

Run an application-local probe in the application’s namespace when the question is whether its listener responds. Run a separate probe from a representative client network when the question is whether users can reach the public endpoint. An internal success and an external failure can both be correct observations because the requests traverse different routing, forwarding, and authentication paths.

Processes sharing a network namespace also share loopback, even if they otherwise have separate process or filesystem environments. Host networking and intentionally shared container networking change the boundary. Before replacing localhost in a connection string, identify where the client executes and which namespace owns the server. Avoid treating container names or machine ownership as substitutes for that information.

A loopback listener can also be exposed indirectly by a proxy or tunnel that forwards requests to it. Local address scope is therefore different from user authorization. Authenticate the service as its contract requires, including requests originating from another local process. Use loopback to express the intended local transport path, and verify the complete forwarding chain when remote access is deliberately provided.

Sources

RFC 1122 Internet host requirements, the reserved IPv4 loopback address block, checked 2026-10-19.
RFC 4291 IPv6 addressing, the IPv6 loopback address and its scope, checked 2026-10-19.
Linux network_namespaces(7), isolation of interfaces, routes and socket port numbers, checked 2026-10-19.
Linux ip(7), local IPv4 delivery and socket addressing, checked 2026-10-19.
Docker none network driver, no IPv6 loopback configured by the driver, checked 2026-10-19.
Docker create, separate creation and pull policy, checked 2026-10-19.
Docker run CID files, per-run identity capture, checked 2026-10-19.
Docker start, starting and attaching to an existing container, checked 2026-10-19.
Docker remove, removal by ID, checked 2026-10-19.
Python subprocess, timeout and return-code behavior, checked 2026-10-19.
Python 3.11 socket, stream reads and timeouts, checked 2026-10-19.

A release checklist for a static site

Thu, 30 Jul 2026 00:00:00 +0000

A static site is simple to publish, but simplicity does not remove the need for a release check. The useful checks are small enough to run on every release and specific enough to fail for a real reason.

The checks belong to the generated artifact. Clean output does not establish reproducibility; placeholder searches are review aids, with parser-based link checks as the gate. Serve the exact artifact before publishing, compare public GET bodies afterward in both languages, and keep the commit, generator version, and download checksums.

Build a clean artifact

Use a pinned generator version and build into a disposable output directory:

set -eu
hugo version
hugo --cleanDestinationDir --gc --minify --destination public

--gc collects unused build-cache resources; it does not clean stale published pages. --cleanDestinationDir removes stale destination files, so use it only on the disposable artifact directory, never a directory containing source or unrelated data. Compare the printed version with the project’s pin; printing a version does not enforce it. Record the build inputs and verify the resulting artifact. A clean destination does not establish byte-for-byte reproducibility: timestamps and other nondeterministic inputs need separate control and comparison. Do not edit generated HTML by hand after the build.

Check the artifact, not only the source

Inspect the generated tree and verify that expected entry points exist. Run this assertion block as a standalone shell script; it must stop before printing the inventory if any required file is missing or empty:

set -eu
test -s public/index.html
test -s public/404.html
test -s public/robots.txt
test -s public/sitemap.xml
find public -type f -print | sort

Then search for accidental placeholders, local paths, and development-only hosts:

rg -l 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '*.html'

This is a review aid, not an automatic release gate: examples like this checklist deliberately match, including in translated pages. This HTML-only scan does not cover XML feeds or JSON search output. rg exits 1 when there are no matches and 2 on an error. Review each listed file, distinguish fenced examples from active links or attributes, and use a parser-based link check for the actual gate. A private path in a published link is a release mistake.

Exercise the public routes

An isolated production-like server pointed at this exact artifact gives the strongest pre-release routing check. Hugo’s development server rebuilds content; the following is a separate source preview, not evidence that the already checked public/ bytes were served. Run the first command in one terminal and the requests in another:

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://127.0.0.1:1313/ \
 --disableFastRender --disableLiveReload --renderToMemory
curl -I http://127.0.0.1:1313/
curl -I http://127.0.0.1:1313/notes/
curl -I http://127.0.0.1:1313/resources/
curl -I http://127.0.0.1:1313/missing-page/

HEAD checks do not compare bodies. Repeat with GET against the staged server, then after publishing compare public bodies with the artifact and check both languages. Confirm that the missing route returns a 404 status in the production server. A pretty error page with a 200 status still breaks monitoring and caches.

Record the result

Keep the source commit, generator version, and checksum of each downloadable resource in the release record. This makes it possible to compare a live file with the source that produced it without relying on memory.

The downloadable version of this checklist is in the Resources section.

Sources

Hugo command reference, generator flags for a clean production build, checked 2026-07-30.
curl manual, HTTP verification and header inspection options, checked 2026-07-30.
Static-site release checklist, downloadable companion resource.
Hugo server command reference, development rebuilds, memory rendering, and live-reload controls, checked 2026-10-15.

A release manifest should name every published byte

Thu, 16 Jul 2026 00:00:00 +0000

A static artifact is a directory, not one executable. Recording only the source commit or homepage checksum leaves gaps: a missing image, stale alias, or changed download can survive unnoticed. Enumerate every regular file in a frozen artifact before transport.

Freeze writers, reject symlinks and special files, and keep both manifests outside the artifact trees. A listed-file check detects missing or changed bytes; recomputing and comparing the complete lists also detects extras. Hashing the trusted source manifest supplies a compact identifier, with separate controls for authenticity and metadata.

Generate a stable list

Run this in Bash with GNU findutils and coreutils, from the directory containing public/. Keep the manifest outside the measured tree. The release must contain only directories and regular files: inspect and reject symlinks or special files first, since they are outside this manifest’s contract.

set -euo pipefail
manifest="$PWD/release.sha256"
(
 cd public
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$manifest"
test -s "$manifest"

Sort filenames before hashing. NUL-delimited paths preserve spaces, tabs, and embedded newlines between tools; GNU sha256sum escapes special names in its ordinary checkable output. Do not parse that output with awk '{print $2}': whitespace is legal in filenames. The separate assignment preserves a failed find exit status; testing only its output could mistake a failed scan for an empty result. Treat any failed scan or pipeline as an incomplete manifest and do not publish it. Stop writers while measuring; these commands do not create a filesystem snapshot.

Verify after transport

In one disposable Bash session on the destination, run the remaining fragments in order so the paths and set options stay in scope. Set the manifest and artifact paths to their actual locations:

set -euo pipefail
manifest=/path/to/release.sha256
artifact=/srv/www/site.new
(
 cd "$artifact"
 sha256sum -c "$manifest"
)

Checking listed files catches missing or changed bytes, but not extra files. Recompute the destination manifest with the same procedure and compare the complete records:

observed=$(mktemp "${manifest}.observed.XXXXXX")
trap 'rm -f "$observed"' EXIT
(
 cd "$artifact"
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$observed"
diff -u "$manifest" "$observed"

No diff and exit status zero means the regular-file paths and hashes agree. An extra stale file now fails too. The temporary output remains outside the artifact so the check never includes itself. Empty directories, permissions, ownership, and timestamps are not measured; validate those separately if deployment depends on them.

Add an aggregate digest for release records

Hash the manifest itself for a compact release identifier:

sha256sum "$manifest"

Its meaning depends on fixed rules: relative paths, sorting locale, algorithm, tool format, and included metadata. Keep the trusted manifest with the source commit and builder version.

Do not confuse integrity with authenticity

Matching SHA-256 digests are strong practical evidence of matching bytes, not proof of authorship. An attacker able to replace both artifact and manifest can make the check pass. Signing and trusted distribution are separate controls; verify only a manifest obtained through the intended trusted channel.

Sources

GNU Coreutils: sha2 utilities, checksum generation and verification; reviewed through the linked upstream manual source, checked 2026-10-15.
GNU Coreutils manual source, untagged checksum escaping, --check, and NUL-delimited sorting, checked 2026-10-15.
sha256sum(1), command behavior and output format, checked 2026-07-16.
GNU Bash: Simple Command Expansion, assignment-only commands retain command-substitution exit status, checked 2026-10-18.

A release is not complete until the public edge agrees

Thu, 09 Jul 2026 00:00:00 +0000

Static publishing removes application runtime complexity, but it does not remove the boundary between a generated directory and a public response. A release check should cover both.

Use the same artifact before and after selection. The download row refers to public/downloads/check-http-headers.sh in the article. Supported content codings are decoded before cmp; server transformations need a documented rule. Status and header checks are separate. Retain the previous directory for a deliberate rollback.

Start from a clean artifact

Build with the pinned generator into a clean destination. Record the source commit, generator version, output file list, and checksums of files that users download. A clean build catches stale files that a copy-over deployment can accidentally preserve.

set -eu
make verify
find public -type f -print | sort

The file list is evidence, not decoration. If a route disappears, the diff should explain whether the source was removed or the generator failed to emit it.

Exercise three response classes

Before publishing, test the staged artifact with the intended server configuration. After switching directories, repeat these checks at the public edge; probing the old live site cannot validate the new release. Request one HTML page, one static resource, and one missing path. Inspect status, content type, cache policy, and security headers:

set -eu
curl --compressed -fsS -D page.headers -o page.body https://www.example.test/
curl --compressed -fsS -D asset.headers -o asset.body \
 https://www.example.test/downloads/check-http-headers.sh
curl --compressed -sS -D missing.headers -o missing.body \
 https://www.example.test/does-not-exist

cmp public/index.html page.body
cmp public/downloads/check-http-headers.sh asset.body
cmp public/404.html missing.body

Run each fragment as a standalone shell script or in a disposable shell session. set -eu stops this sequential script after a failed build, transfer, or comparison, so a later successful command cannot hide an earlier failure. The missing-path request intentionally does not use -f: a 404 is expected and should still be captured. Check the final status in each header file: 200, 200, then 404; the byte comparisons do not automate that status check. No redirect is followed here. --compressed decodes supported content codings before comparison; a deliberate server-side HTML transformation needs its own documented comparison rule. cmp is silent on equality and returns nonzero on a difference. Repeat for /zh/ and its error page rather than assuming language parity.

Keep rollback simple

Do not delete the previous directory until the new one has passed the checks. A rollback should select a known-good directory, not reconstruct one from memory during an incident. The release checklist and HTTP header check are deliberately small enough to run from a clean shell.

Sources

RFC 9110 — HTTP Semantics, status and representation semantics, checked 2026-07-09.
curl manual, response inspection options, checked 2026-07-09.
Static-site release checklist, local companion resource.

Range requests should prove which bytes were selected

Mon, 06 Jul 2026 00:00:00 +0000

Range requests let a client ask for part of a representation. Media players, resumable download tools, and diagnostic clients use them, but a server that advertises or returns ranges incorrectly can produce silent corruption instead of a clean failure.

Keep the representation and content coding stable. Match interval, total size and actual body bytes; a complete 200 can be valid when Range is ignored. Resume only with an appropriate strong validator.

Establish the complete size

Use an immutable test download of at least 16 bytes. Run the fragments in the same disposable shell session so url and size remain available. Their explicit set -eu stops after a failed transfer, size check, or comparison; inspect the HTTP status and range fields separately. Save the complete body, headers, and validator in that temporary working directory:

set -eu
url=https://www.example.test/downloads/archive.tar.gz
curl -fsS -H 'Accept-Encoding: identity' -D full.headers -o full.body "$url"
size=$(wc -c < full.body)
test "$size" -ge 16
awk 'tolower($1) ~ /^(content-length:|content-encoding:|etag:|last-modified:|accept-ranges:)$/ { print }' full.headers

Check that the full response is 200 and has no unexpected content coding. The commands request the identity representation and do not use automatic decompression; byte ranges apply to the selected encoded representation, so changing encoding invalidates the comparison. Content-Length may be absent, which is why the complete body supplies the size.

Accept-Ranges: bytes is an explicit signal, but absence of the header does not by itself prove that range requests are unsupported. Exercise the request.

Request a known interval

Ask for the first 16 bytes and keep both headers and body:

set -eu
curl -sS -D range.headers -o range.body \
 -H 'Accept-Encoding: identity' -H 'Range: bytes=0-15' "$url"

wc -c range.body
head -c 16 full.body > expected.body
cmp expected.body range.body
awk 'tolower($1) ~ /^(content-range:|content-length:|etag:)$/ || /^HTTP\// { print }' range.headers

A successful byte-range response uses 206 Partial Content. Content-Range should identify 0-15 and the complete representation length, while the body should contain exactly 16 bytes.

The byte comparison deliberately tests the partial-body case. A valid full 200 larger than 16 bytes will fail it and stop this shell session; inspect the saved headers before calling that corruption. Conversely, a complete 16-byte file can pass cmp even with 200, so status and Content-Range still need checking.

Test an impossible range

Start at the complete byte count: for a file of size N, the last valid offset is N−1. Unlike a fixed large constant, this is outside the known representation:

set -eu
curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' -H "Range: bytes=${size}-" "$url"

When the server rejects an unsatisfiable byte range with 416 Range Not Satisfiable, it should include Content-Range, for example bytes */12345, to report the current size. A 200 response may be valid when the server ignores the range, but it must return the complete representation rather than a mislabeled fragment.

Keep validators in the story

Resumed downloads can use If-Range with a strong ETag. A weak ETag is forbidden; an HTTP date is allowed only when no ETag is available and the date qualifies as a strong validator. If the representation changed, the safe response is the full current representation, not bytes spliced from two versions. Test this behavior before calling a download resumable.

Sources

RFC 9110 — HTTP Semantics, range units, partial responses, and Content-Range, checked 2026-07-06.
curl manual, --range and header options, checked 2026-07-06.

HEAD should describe the same representation as GET

Mon, 22 Jun 2026 00:00:00 +0000

The HEAD method asks for the response a server would send to GET, without transferring the response content. It is useful for checks that need status, validators, type, or length, but only when the metadata remains aligned with the real GET path.

Match the URL, request headers, release, and content coding before comparing HEAD with GET. Permitted omissions are not automatic failures. Keep a small GET body or checksum check, because plausible metadata cannot prove that the payload is intact.

Compare a normalized header set

Dynamic headers such as Date will differ between requests. Compare the fields that describe the selected representation:

url=https://www.example.test/downloads/manual.pdf

curl -sS -I "$url" > head.headers
curl -sS -D get.headers -o /dev/null "$url"

for file in head.headers get.headers; do
 printf '== %s\n' "$file"
 awk '
 /^HTTP\// ||
 tolower($1) ~ /^(content-type:|content-length:|content-encoding:|cache-control:|etag:|last-modified:|vary:)$/ { print }
 ' "$file"
done

Run this in a disposable working directory; the two header files are overwritten. Match the URL, request headers, and release version. Compression negotiation belongs in the comparison: send the same Accept-Encoding value to both requests.

HEAD should describe the corresponding GET, but RFC 9110 permits omission of fields determined only while generating content. Missing Content-Length alone is not a failure. If present on HEAD, it must be the length the corresponding GET content would have, not zero just because HEAD has no body. Compare encoded lengths consistently and investigate changed validators or types rather than requiring byte-identical header lists.

Do not use HEAD as the only release check

A server can synthesize plausible headers while the file is missing, unreadable, or truncated. Keep one small GET in the smoke test and verify its body or checksum. HEAD reduces transfer cost; it does not prove the payload.

Check redirects explicitly

Without --location, curl -I reports the first response. That is useful when testing redirect policy. With --location, it prints header blocks for the followed responses, including intermediate redirects and the final destination. Record which question the command answers:

curl -sS -I --max-redirs 0 https://old.example.test/manual
curl -sS -I --location https://old.example.test/manual

Treat method-specific failures as configuration defects

A static page that returns 200 to GET and 405 or 404 to HEAD usually exposes a proxy or routing inconsistency. Fix the method handling instead of teaching monitors to ignore it, unless the endpoint contract deliberately disallows HEAD.

Sources

RFC 9110 — HTTP Semantics, HEAD method semantics, checked 2026-10-15.
curl manual, --head, --include, and redirect options, checked 2026-10-15.