Debugging · XB Field Notes

git bisect narrows the first bad commit

Sun, 24 Oct 2027 00:00:00 +0000

Bisection answers a precise historical question: within selected history, where does a reproducible observation change from good to bad? It does not identify a root cause merely by naming a commit. The search depends on correct endpoint labels and consistent intermediate decisions. Treat the reported boundary as evidence to inspect, then confirm the behavior on both sides and explain the change that accounts for it.

The stable accepts(10) fixture narrows an ancestry boundary to revision 3; its parent accepts ten and revision 3 rejects it. A skipped transition can leave {3, 4}. Replay restores prior decisions without testing again, so confirm the boundary and inspect the patch before explaining causality.

Choose endpoints by observation, not date

At least one known-good and one known-bad commit establish the search. More good revisions can further constrain a graph. A recently verified good commit usually reduces the range better than an unnecessarily ancient baseline. Dates are not the search order: Git uses ancestry, and a commit’s author timestamp need not describe where it sits in the graph.

Run the same reproduction at both endpoints before assigning labels. Define what counts as the symptom, including boundary inputs and relevant configuration. A test that simply checks whether any command fails can confuse the product regression with a missing interpreter, unavailable service, or incompatible build environment. An untestable revision has an unknown result, not an automatic bad verdict.

Use a clean disposable checkout or a dedicated worktree. Bisect normally changes HEAD to selected revisions and updates checked-out files. Preserve unfinished work beforehand without assuming that the search itself creates a backup. Keep the probe and required evidence outside files that disappear or change as historical revisions are checked out.

Make each decision about the same property

After inspecting the selected revision, record git bisect good or git bisect bad according to the reproduction. Use git bisect skip when a specific revision cannot be classified for a reason unrelated to the symptom. Skips near the transition may prevent a unique answer, so report the remaining candidate set instead of pretending the first displayed object is proven responsible.

Simple binary-search intuition assumes a reasonably stable transition in the selected history. A bug introduced, fixed, and later reintroduced is not a single monotonic timeline for that predicate. Nondeterministic tests create the same kind of misleading labels. Refine the question or the interval when the observations contradict the assumed transition; do not force them into a convenient story.

For a merge-heavy history, deciding whether to search all ancestry or only the first-parent integration line changes the question. A first-parent search can locate the merge where an integration branch acquired the failure rather than the original topic commit. Similarly, limiting paths can exclude a relevant configuration or caller change. Apply those restrictions only when they match the investigation.

Automated git bisect run uses exit codes: zero means good, 125 skips, and 1–127 otherwise mean bad. Other statuses abort. Missing commands can return 127, so a wrapper must distinguish unavailable tooling from the target regression rather than blindly forwarding every failure.

When it breaks

One mistaken label can exclude the true boundary. Save git bisect log before abandoning the session. If a decision was wrong, retain the original evidence, correct the decision record, reset, and replay the corrected log. Replay reconstructs decisions; it does not rerun tests or prove their old environment is still valid.

When a candidate is found, rerun the exact reproduction there and on the relevant parent. For a normal linear boundary, the candidate should be bad and its parent good. A merge may require examining several parents and the combined behavior. Read the patch and affected call chain; a candidate that only exposes a preexisting issue still needs a causal explanation.

Avoid immediately reverting the candidate in a shared or dirty branch as a diagnostic shortcut. Any corrective experiment belongs in a controlled checkout with its own review and tests. After recording the findings, git bisect reset ends the session and normally restores the original checkout. Confirm the active branch and revision rather than assuming the final diagnostic checkout is the development branch.

Check it quickly

Run this on a POSIX system with Python 3 and Git 2.28 or newer. The temporary repository uses synthetic identity, disables hooks and signing, excludes personal Git configuration and routing variables, and has no remote. Seven revisions change a numerical limit from inclusive to exclusive at revision three. The probe checks the exact boundary input, ten.

import os
import subprocess
import sys
import tempfile
from pathlib import Path

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-bisect-boundary-") as directory:
 root = Path(directory)
 repo, log = root / "repo", root / "bisect.log"
 repo.mkdir()
 def git(*args):
 return subprocess.run(
 ["git", "-c", "user.name=Boundary Example",
 "-c", "user.email=boundary@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", *args],
 cwd=repo, env=env, text=True, capture_output=True, check=True,
 )
 def verdict():
 result = subprocess.run([sys.executable, "-B", "-c",
 "from limit import accepts; print(int(accepts(10)))"],
 cwd=repo, text=True, capture_output=True, check=True)
 assert result.stdout in ("0\n", "1\n"), result
 return "good" if result.stdout == "1\n" else "bad"
 git("init", "-q", "-b", "main")
 commits = []
 for number in range(7):
 operator = "<" if number >= 3 else "<="
 (repo / "limit.py").write_text(f"def accepts(n):\n return n {operator} 10\n")
 (repo / "revision.txt").write_text(f"{number}\n")
 git("add", "limit.py", "revision.txt")
 git("commit", "-qm", f"revision {number}")
 commits.append(git("rev-parse", "HEAD").stdout.strip())
 endpoints = []
 for revision in (commits[0], "main"):
 git("switch", "-q", "--detach", revision)
 endpoints.append(verdict())
 git("switch", "-q", "main")
 print("endpoints-confirmed:", endpoints == ["good", "bad"])
 git("bisect", "start", commits[-1], commits[0])
 try:
 while len(git("rev-list", "refs/bisect/bad", "--not",
 "--glob=refs/bisect/good-*").stdout.splitlines()) > 1:
 git("bisect", verdict())
 found = git("rev-parse", "refs/bisect/bad").stdout.strip()
 log.write_text(git("bisect", "log").stdout)
 print("boundary-identified:", found == commits[3])
 finally:
 git("bisect", "reset")
 checks = []
 for revision in (found, f"{found}^"):
 git("switch", "-q", "--detach", revision)
 checks.append(verdict())
 git("switch", "-q", "main")
 print("candidate-and-parent-retested:", checks == ["bad", "good"])
 try:
 git("bisect", "replay", str(log))
 print("log-replays-boundary:", git("rev-parse", "refs/bisect/bad").stdout.strip() == found)
 finally:
 git("bisect", "reset")
 print("original-branch-restored:", git("symbolic-ref", "--short", "HEAD").stdout.strip() == "main"
 and git("rev-parse", "HEAD").stdout.strip() == commits[-1]
 and not git("status", "--porcelain").stdout)

All five checks should print True. The loop uses explicit good/bad decisions until one candidate remains in this linear, skip-free fixture. Revision three is found, and independent retests show its boundary behavior fails while its parent succeeds. Replaying the saved log reaches the same result without repeating the probe, then reset restores main. The observed patch explains the regression: equality at the limit was removed.

Sources

Git bisect reference, labels, skips, ancestry restrictions, logging, and replay, checked 2026-10-15.
Pro Git: debugging with Git, testing historical endpoints and inspecting the discovered boundary, checked 2026-10-15.

curl is your first HTTP probe

Fri, 11 Dec 2026 00:00:00 +0000

A command-line HTTP request gives a small, inspectable view of a service. It can show the response status, headers, body, and timing without a browser’s rendering layer. Start with a concrete question: whether the original URL redirects correctly, whether the final representation is available, or whether a particular method is accepted. Those questions require different probes. One successful curl invocation does not establish that every part of a website works.

Choose the question before the options. These observed synthetic local fixture outcomes do not validate TLS, browser behavior or production services.

Validation note, 17 October 2026: This revised local exercise was run on macOS 26.5.1 (arm64) with Python 3.14.4 and curl 8.7.1. Both language copies passed six baseline probes. Separate checks tested refused connections and truncated responses, each with absent and stale capture files: all four produced the expected transfer failures (exit 7 or 18), with no stale capture data, and the transfer-exit assertion rejected them. The refusal check releases its reserved port before connecting, so another process could reuse it in that interval. These recorded results cover this synthetic loopback fixture; they do not validate TLS, browser behavior, production services, load or downstream dependencies.

Separate four kinds of evidence

By default, curl writes the response body and can exit successfully even when HTTP reports an error. The process exit status describes curl’s transfer outcome, while the HTTP status describes the received response. Keep both. A body that says “missing” with status 404 differs from a connection failure that produced no HTTP response at all. A monitoring script should test its intended response contract explicitly.

Use -D to capture response headers, -o to choose where transfer output goes, and -w to print selected metadata separately. -sS hides the progress meter while retaining error messages. --max-time bounds the transfer, and redirect-following probes should also bound the number of hops. Record the options alongside results so a later comparison uses the same method, URL, and request headers.

Timing fields depend on connection reuse, proxy routing, and redirects. A reused connection can avoid a fresh DNS lookup. Compare equivalent conditions before treating a lower lookup time as evidence that the DNS service improved.

When it breaks

Adding -L immediately can hide a wrong first hop behind a healthy final page. Inspect the original status and Location when debugging routing, then follow deliberately when testing the destination. A redirect loop, an unexpected host, or a method change can matter even when some later page returns 200. Following a chain is not universally the right definition of success.

-I sends HEAD; it is not a GET whose body curl merely discards. A server, proxy, or authorization rule may handle HEAD differently. If a HEAD probe fails while GET works, inspect that method difference before declaring the resource unavailable. Likewise, changing a User-Agent header does not turn curl into a browser: JavaScript, layout, browser cookie rules, and CORS enforcement require their own checks.

Verbose output can contain credentials and private request details. Capture only the diagnostic fields needed and keep secrets out of commands and saved traces. Disabling certificate verification changes the question being tested; it cannot establish that a normal HTTPS client trusts the server. Inherited proxy settings and curl configuration can also change a probe’s route or behavior, so control them when reproducibility matters.

Check it quickly

Save this as curl-probe.py and run python3 curl-probe.py with curl installed. It was checked with curl 8.7.1. The script runs a temporary loopback HTTP server and launches the real curl command. Its first option disables the default curl configuration, and the local requests bypass proxies. No external site or TLS service is involved.

from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Thread
import json
import subprocess


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 status = 302 if self.path == '/move' else 200 if self.path == '/ok' else 404
 data = b'healthy\n' if status == 200 else b'missing\n' if status == 404 else b''
 self.send_response(status)
 if status == 302:
 self.send_header('Location', '/ok')
 self.send_header('Content-Length', str(len(data)))
 self.end_headers()
 self.wfile.write(data)

 def do_HEAD(self):
 self.send_response(405)
 self.send_header('Allow', 'GET')
 self.end_headers()

 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}'
 with TemporaryDirectory() as directory:
 root = Path(directory)

 def probe(path, *options):
 body, headers = root / 'body', root / 'headers'
 body.unlink(missing_ok=True)
 headers.unlink(missing_ok=True)
 result = subprocess.run([
 'curl', '-q', '--noproxy', '*', '--max-time', '5', '-sS',
 '-o', str(body), '-D', str(headers), '-w', '%{http_code} %{num_redirects}',
 *options, origin + path], capture_output=True, text=True, timeout=10)
 status, redirects = map(int, result.stdout.split())
 return {'exit': result.returncode, 'status': status, 'redirects': redirects,
 'output': body.read_text() if body.exists() else '',
 'allow_get': headers.exists() and 'Allow: GET' in headers.read_text()}

 results = {'missing_default': probe('/missing'),
 'missing_fail': probe('/missing', '--fail-with-body'),
 'redirect_inspect': probe('/move'),
 'redirect_follow': probe('/move', '--location', '--max-redirs', '2'),
 'head': probe('/ok', '--head'), 'get': probe('/ok')}
 assert (results['missing_default']['exit'], results['missing_default']['status']) == (0, 404)
 assert (results['missing_fail']['exit'], results['missing_fail']['status']) == (22, 404)
 assert results['missing_fail']['output'] == 'missing\n'
 assert all(results[name]['exit'] == 0 for name in ('redirect_inspect', 'redirect_follow', 'head', 'get'))
 assert (results['redirect_inspect']['status'], results['redirect_inspect']['redirects']) == (302, 0)
 assert (results['redirect_follow']['status'], results['redirect_follow']['redirects']) == (200, 1)
 assert results['head']['status'] == 405 and results['head']['allow_get']
 assert results['get']['status'] == 200 and results['get']['output'] == 'healthy\n'
 print(json.dumps(results))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

The ordinary missing-page transfer returns HTTP 404 with process exit zero. Adding --fail-with-body changes the exit to 22 while preserving the diagnostic body. This directly demonstrates why checking only the process status misses some HTTP failures. The option requires a curl version that supports it; inspect the installed manual when adapting the command.

The redirect inspection reports 302 with zero followed hops. Explicit following reaches 200 after one hop. The same /ok resource returns 405 with Allow: GET to HEAD and 200 with healthy to GET. For HEAD, curl’s captured output contains headers rather than a representation body, which is why the result field is named output.

These cases verify transfer classification, redirect choice, and method differences. They do not test TLS, browser behavior, latency under load, or the application’s downstream dependencies. Turn a useful manual probe into an automated check only after specifying the expected status, relevant headers, body condition, and timeout. Otherwise automation simply repeats an ambiguous question more frequently.

Sources

curl manual, exit behavior, headers, redirects, and bounded transfers, checked 2026-09-13.
RFC 9110: HTTP Semantics, methods and response semantics interpreted by the probe, checked 2026-09-13.

Read a live edge the way a client does

Fri, 07 Aug 2026 00:00:00 +0000

The HTTP-foundations notes each take one contract and show single pieces of evidence. This tutorial walks the whole path a single client request touches, in order, using only read-only commands. The aim is to distinguish protocol requirements from choices made by a particular server, rather than demand the same status and headers from every endpoint.

We use www.xbcatm.com throughout. Replace it with the host you are inspecting. The requests use safe HTTP methods; they can still create access logs or consume rate limits. Inspect only endpoints you are permitted to query. Output blocks below are illustrative, not current production measurements. Run shell snippets in a disposable working directory, keep failures visible, and record time and client version.

Keep the selected representation consistent, and interpret each observed response within its own contract. No live edge was queried for this illustration.

1. Start with what a method may ask

Before you read a response body, pin down what the server will allow you to ask. A static handler often supports GET and HEAD, while a proxy may also implement OPTIONS. Ask the edge about the target resource:

$ curl -sS --max-time 20 -D - -o /dev/null -w 'OPTIONS -> HTTP %{http_code}\n' -X OPTIONS https://www.xbcatm.com/
HTTP/2 405
allow: GET, HEAD

OPTIONS -> HTTP 405

405 Method Not Allowed is valid when OPTIONS is recognized but not supported for this resource, and a 405 must include Allow. A successful 200 or 204 OPTIONS response can also be correct. 501 means the method is not implemented by the server. An OPTIONS result is not proof that every other method behaves correctly. Do not send POST merely to test rejection on an unfamiliar live service: it is not a safe method, and a 200 alone does not describe its side effects.

2. Read the representation line

The first line tells you the negotiated exchange; the headers then tell you what kind of bytes are coming. Capture them exactly as a client sees them, discarding the body:

$ curl -sS --max-time 20 -D - -o /dev/null https://www.xbcatm.com/
HTTP/2 200
accept-ranges: bytes
content-length: 15890
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
content-type: text/html; charset=utf-8
etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff

Three headers deserve a pause. content-type: text/html; charset=utf-8 names the media type, and content-type-and-nosniff shows why it must describe the actual bytes you send. etag: "dkx84jwth7nkc9e" hands you a strong validator. x-content-type-options: nosniff constrains browser MIME handling, notably for script and stylesheet fetches; it does not validate the body as HTML. Each is evidence, not decoration, and together they say: this response advertises metadata to compare with its body and intended policy. A syntactically strong ETag is a server assertion, not independent proof of a content hash.

3. Compare HEAD and GET for the same representation

HEAD has GET semantics without a response body. Servers should return the same header fields but may omit fields whose values are determined only while generating content. Content-Length is optional; if sent on HEAD, it must equal the size of the content a corresponding GET would send. Compare stable requests with the same encoding and other selection headers:

$ curl -sSI --max-time 20 -H 'Accept-Encoding: identity' https://www.xbcatm.com/ | grep -i content-length
content-length: 15890
$ curl -sS --max-time 20 -H 'Accept-Encoding: identity' https://www.xbcatm.com/ | wc -c
15890

They match: 15890 on both. That is the head-request-parity contract. An absent HEAD length alone is not a protocol violation. A mismatched value needs investigation, including a deployment between the requests or different selected representations. A pipeline to wc can hide curl failure in shells without pipefail; for an automated gate, save the body only after curl succeeds and count that file.

4. Ask for precise bytes with a range

Because the origin knows its representation, it can serve part of it. A range request asks for a byte span and gets only that span:

$ curl -sS --max-time 20 -D - -o /dev/null -H 'Accept-Encoding: identity' -H 'Range: bytes=0-99' -w 'HTTP %{http_code} bytes=%{size_download}\n' https://www.xbcatm.com/
HTTP/2 206
content-range: bytes 0-99/15890
content-length: 100

HTTP 206 bytes=100

For a representation at least 100 bytes long, a successful single-range response should have 206, a matching Content-Range: bytes 0-99/…, and 100 content bytes. A server may legally ignore Range and return a full 200; that does not imply it lacks validators. An unsatisfiable range can return 416. A plain Range request does not require an ETag. Resuming a particular representation with If-Range, or safely combining partial responses, needs the relevant strong-validator rules. Ranges refer to the selected encoded bytes, hence the explicit identity encoding here.

5. Let the cache revalidate with a validator

Now combine method, representation, and byte selection through caching. A fresh stored response may be reusable without checking a validator. To test revalidation, capture the current response and replay its actual ETag using the same representation selection. Do not copy an old tag from an article:

set -eu
url=https://www.xbcatm.com/
work=$(mktemp -d)
status=$(curl -sS --max-time 20 -H 'Accept-Encoding: identity' \
 -D "$work/headers" -o "$work/body" -w '%{http_code}' "$url")
test "$status" = 200
etag=$(awk 'tolower($1)=="etag:" {sub(/\r$/, ""); sub(/^[^:]*:[ \t]*/, ""); print; exit}' "$work/headers")
test -n "$etag" || { echo 'No ETag: inspect Last-Modified instead' >&2; exit 1; }
curl -sS --max-time 20 -H 'Accept-Encoding: identity' \
 -H "If-None-Match: $etag" -D - -o /dev/null \
 -w 'HTTP %{http_code}\n' "$url"

Run this fragment as a standalone shell script. It must finish the initial transfer and require status 200 before storing a usable response; an error representation can also have an ETag. If the selected representation still matches and normal processing succeeds, expect 304 and reuse that complete stored body with updated metadata. A changed representation can correctly return 200. Keep the temporary directory while inspecting the result, then remove only that generated directory when finished. If-None-Match uses weak comparison, so a 304 need not prove byte identity. Freshness lifetime and current age decide reuse without validation; a validator answers a different question and does not itself set that lifetime.

6. Negotiate a smaller representation when you can

The same content can travel in fewer bytes when the client says it can decompress. Offer gzip and watch the body shrink while the meaning stays identical:

$ curl -sS --max-time 20 -H 'Accept-Encoding: identity' -o /dev/null -w 'no-enc: %{size_download} bytes\n' https://www.xbcatm.com/
$ curl -sS --max-time 20 -o /dev/null -H 'Accept-Encoding: gzip' -w 'gzip: %{size_download} bytes\n' https://www.xbcatm.com/
no-enc: 15890 bytes
gzip: 4368 bytes

These example sizes illustrate a possible reduction; the server may choose identity instead. That is the http-compression-negotiation note’s core idea: changing the selected representation changes the bytes on the wire, and the metadata (content-length, encoding) changes with it. A client that requests compression and a cache that stores the encoded form must agree on which representation they selected, otherwise the cache can serve a mismatch. Inspect Content-Encoding and Vary: Accept-Encoding, not just the byte count. A manually supplied Accept-Encoding does not make curl automatically decompress; --compressed requests supported encodings and decodes the response. Compare decoded bodies to establish equal content, and do not assume strong ETags remain identical across encodings.

7. Follow the story when a URL changes

When identity changes, the response should say where the story continues rather than guess the body:

$ curl -sS --max-time 20 -o /dev/null -w '%{http_code} -> %{redirect_url}\n' -I http://www.xbcatm.com/ | head -1
308 -> https://www.xbcatm.com/

308 Permanent Redirect keeps the method and preserves the story, which is the concern of redirects-and-status-codes. Whether it is a 301/308 for a permanent move, or a 404 handled by the site, the status line is the first sentence of the story and should be read before the body.

8. Let the crawler read the map last

The edge is also read by machines that do not request HTML at all. Discovery answers two different questions, as robots-and-sitemaps explains. Confirm discovery points at the real sitemap:

$ curl -sS --max-time 20 https://www.xbcatm.com/robots.txt
User-agent: *
Disallow:
Sitemap: https://www.xbcatm.com/sitemap.xml

Fetch the sitemap URL too and check canonical host and language URLs. robots.txt is crawler guidance, not access control; listing a URL in a sitemap does not guarantee crawling or indexing.

The whole path in one glance

Check	What to inspect	Note
`OPTIONS` status + Allow	observed method policy for this resource	http-method-semantics
`content-type` + body + `nosniff`	advertised type and MIME-handling policy	content-type-and-nosniff
HEAD/GET metadata	corresponding representation, with allowed omissions	head-parity
Range + Content-Range	observed partial-transfer support	http-range-requests
captured `ETag` -> 304	conditional representation match	conditional-requests
308 follows method	redirects preserve the story	redirects-and-status-codes
robots -> sitemap	discovery answers differ	robots-and-sitemaps

Each row was a note; now it is a command you can run against any edge. Read the linked note when you need the details, and keep this table as your re-check before you trust an endpoint.

Sources

WHATWG Fetch Standard, nosniff processing and request destinations, checked 2026-10-15.
RFC 9110 — HTTP Semantics, methods, validators, and status codes, checked 2026-10-15.
RFC 9111 — HTTP Caching, freshness and revalidation, checked 2026-10-15.
RFC 7538 — 308 Permanent Redirect, method-preserving redirect, checked 2026-10-15.
curl manual, read-only inspection flags, checked 2026-10-15.

Redirects and error codes should preserve the story

Tue, 14 Jul 2026 00:00:00 +0000

An HTTP status is part of the interface. A browser may render a friendly page, but a monitor, crawler, cache, and API client also need the status code and headers to tell the same story.

Choose relocation or absence deliberately. Preserve the required method, resolve Location, account for caching, and keep error-page status truthful.

Permanent moves are not all interchangeable

308 Permanent Redirect communicates that the resource has a new permanent URI while preserving the request method. That is important for a client that sends POST, PUT, or another non-GET method. A redirect from an old page to a new page is easy to test with GET; a migration of an endpoint must also be tested with the method that real callers use.

curl -sS -D - -o /dev/null https://old.example.test/api/item

Without --location, curl leaves the redirect unfollowed. Resolve Location against the original URI: an absolute URI, root-relative path, or other relative reference can be valid. Check the resolved host, path, and scheme. 301/302 permit changing POST to GET; 307/308 preserve the method. Test state-changing methods only against an isolated endpoint. 308 is heuristically cacheable, subject to method and cache controls, so a cached move can outlive a server configuration change.

If the intent is to show a result after a completed action, 303 See Other points to a separate resource that the client can retrieve with GET or HEAD. It does not ask the client to replay the original write at a new address; choose that behavior deliberately rather than treating every redirect as a relocation.

Distinguish missing from removed

Use 404 Not Found when the server cannot find a current representation and the absence may be temporary or unknown. 410 Gone is stronger: it says access is no longer available and the condition is likely permanent; it does not establish why the resource disappeared. Both should have a body that helps a human, but neither should return 200 just because a custom error page rendered successfully.

404 can also conceal whether a forbidden resource exists. Both 404 and 410 are heuristically cacheable, subject to method and cache controls. Choose an explicit policy for error responses: a cached missing-route result can remain visible after the route is repaired.

The check belongs at the edge:

curl -sS -D missing.headers -o missing.html -w '%{http_code} %{url_effective}\n' \
 https://www.example.test/a-route-that-does-not-exist

Keep the response headers on the error path. Security headers, a useful content type, and a correct status are more valuable than a decorative error animation.

Sources

RFC 9110 — HTTP Semantics, sections 15 and 13, checked 2026-07-14.
RFC 7538 — 308 Permanent Redirect, section 3, checked 2026-07-14.
curl manual, status and redirect inspection flags, checked 2026-07-14.

Read the public edge in two commands

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

A deployment is complete when public responses match the release contract, not when the last upload exits zero. Two read-only helpers from the operator kit expose useful evidence, but they do not prove the whole artifact was published correctly.

These are illustrative excerpts. Evaluate HTTP status and expiry separately; verify hostname, trust and body equality with the checks that actually test them.

Inspect the response headers

check-http-headers.sh performs a GET, discards the body, follows redirects, and prints the response headers for each hop plus the final status and URL:

check-http-headers.sh https://www.xbcatm.com/

This illustrative output shows the fields to inspect. It is not a fresh production observation:

HTTP/2 200
accept-ranges: bytes
content-security-policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:
content-type: text/html; charset=utf-8
last-modified: Mon, 24 Aug 2026 11:20:54 GMT
permissions-policy: accelerometer=(), camera=(), geolocation=(), gyroscope=(), microphone=(), payment=(), usb=()
referrer-policy: strict-origin-when-cross-origin
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY

HTTP_STATUS 200
FINAL_URL https://www.xbcatm.com/

Check the expected status, final host and path, and the policy on the final response. The helper does not use curl’s --fail: an HTTP 404 or 500 can still leave the shell command successful. Treat its printed status as data to evaluate. A header mismatch warrants investigation of server, proxy, or cache configuration; it does not by itself prove the wrong output directory is live.

Inspect the certificate dates

check-tls-expiry.sh HOST [DAYS] extracts the certificate presented with SNI and checks whether its expiry is at least the requested number of seconds away:

check-tls-expiry.sh www.xbcatm.com 30

An illustrative excerpt, with the fingerprint line omitted:

subject=CN=www.xbcatm.com
issuer=C=US, O=Let's Encrypt, CN=YE1
notBefore=Aug 21 08:37:13 2026 GMT
notAfter=Nov 19 08:37:12 2026 GMT

certificate remains valid for at least 30 day(s)

The helper prints subject, issuer, dates, and SHA-256 fingerprint. It does not print the remaining day count. Its success message describes the expiry test only: the script does not enforce hostname or trust-chain validation, and -checkend does not validate notBefore. The subject CN is not sufficient hostname evidence; service identity is matched against the certificate’s subject alternative names. A valid wildcard may legitimately cover the host.

Use a separate verification when those properties matter:

openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com \
 -verify_hostname www.xbcatm.com -verify_return_error </dev/null

This uses the configured trust store and fails on certificate verification errors under OpenSSL’s matching rules. In OpenSSL 3.0, hostname verification can fall back to the subject CN when no suitable DNS subject alternative name is present. A successful command therefore does not by itself establish RFC 9525’s SAN-only identity policy: inspect the SAN extension and verify the intended client’s policy separately. Keep a job-level timeout around the TLS helper, which does not impose its own network deadline. Certificate inspection and automatic renewal configuration remain separate checks.

Use both around a release

Before: save the expected policy, final URL, validators, and certificate dates with a UTC collection time.
Deploy the already validated artifact.
After: repeat the probes and fetch representative bodies for comparison with that artifact.

Headers and certificate dates cannot establish byte equality. Last-Modified may stay unchanged or be rewritten during copying. The release smoke test saves bodies and compares them directly; a complete manifest extends that check beyond one page. Browser behavior, geographic edge differences, and load-dependent failures need separate tests. Record which paths and observation points were actually checked.

Sources

curl manual, GET, redirect, header output, and HTTP failure behavior, checked 2026-10-15.
OpenSSL s_client, SNI, explicit hostname checks, and failure on verification errors, checked 2026-10-15.
OpenSSL verification options, hostname matching and subject-CN fallback, checked 2026-10-15.
OpenSSL x509, certificate display and expiry-only -checkend behavior, checked 2026-10-15.
RFC 9525 — Service Identity in TLS, subject alternative names and wildcard identity matching, checked 2026-10-15.
Caddy Automatic HTTPS, automatic certificate management and renewal configuration, checked 2026-10-15.
MDN: Content Security Policy guide, CSP directive background, checked 2026-07-13.
RFC 9110 — HTTP Semantics, response metadata and validators do not establish a complete artifact match, checked 2026-10-15.

HTTP methods are a promise about side effects

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

A request method tells the server what the client is asking it to do. A read-only file origin has a narrow contract, but “static site” alone does not prove that proxies or imported handlers expose no write operations. Check the route actually serving the resource.

Separate requested state change from intended repeat effect, then inspect the actual route. The file-handler boundary is scoped; method support is separate from CORS permission.

Safe and idempotent answer different questions

GET and HEAD are safe: the client does not request a state-changing action. Incidental logging, metrics, or accounting can still change server state. PUT and DELETE are idempotent in their defined semantics, but are not safe: repeating the same request is intended to have the same effect as performing it once. That does not require identical response statuses, and it does not make every retry after a network failure appropriate.

For a read-only static origin:

GET retrieves a representation.
HEAD describes the corresponding GET without response content.
OPTIONS asks about the target’s communication options; a file handler may reject it.
POST / PUT / DELETE / PATCH should not fall through to successful file serving unless a separate, intended handler implements their semantics.

A Caddy file handler’s method boundary

Caddy v2.10.2’s file-serving path accepts GET and HEAD and rejects other methods with 405 and Allow: GET, HEAD. Redirects, missing paths, error handlers, and other configured routes can answer earlier or differently, so this is not a universal response for every static-site URL.

The earlier note recorded:

$ curl -s -o /dev/null -w 'OPTIONS -> HTTP %{http_code}\n' -X OPTIONS https://www.xbcatm.com/
OPTIONS -> HTTP 405

The original response log is not retained here, and this review did not reproduce that live result. The command reports only status; it does not establish that the required Allow field was present. Inspect that field separately. 405 means a known method is not supported for this target; 501 Not Implemented is the usual distinction when the server does not recognize or implement a method at all.

HEAD parity allows documented omissions

HEAD should describe the same selected representation as GET, while omitting content. Fields calculated only while generating the content may be omitted. If Content-Length is present, it must describe the corresponding GET content, using the same content coding.

The earlier note reported this comparison:

HEAD content-length: 15890
GET bytes read : 15890

Those historical numbers are not a fixed expected size or a current verification result. A missing HEAD length alone is legal; a wrong supplied length needs investigation. Follow the head-request-parity note for paired probes. The downloadable check-http-headers.sh helper inspects a GET response and does not perform this comparison automatically.

Reject unintended writes without hiding the contract

For a method recognized but disallowed on the target, return 405 with Allow listing the methods actually supported. The list is not necessarily restricted to safe methods on an application route. Do not return a plausible 200 page for an ignored write request.

If browser clients need CORS preflight, define that OPTIONS behavior explicitly; method support and CORS permission are separate decisions. Test write rejection only against an authorized disposable fixture rather than assuming a public endpoint is harmless because the site looks static.

Sources

RFC 9110 — HTTP Semantics, safe/idempotent methods and HEAD/405/501 semantics, checked 2026-10-15.
MDN: HTTP request methods, method overview, checked 2026-10-15.
curl manual, method and response-inspection options, checked 2026-10-15.
Caddy v2.10.2 file-server source, method rejection after file selection, checked 2026-10-15.
WHATWG Fetch Standard, CORS preflight processing, checked 2026-10-15.

Validators decide whether a cached copy is still the answer

Tue, 30 Jun 2026 00:00:00 +0000

A cache can ask whether its stored copy is still usable without always downloading the body again. It sends a validator; a matching conditional GET can receive 304 Not Modified, while a changed representation normally needs a new 200 response. Validation saves bytes on a hit, not on every request.

Illustrative tags; otherwise successful requests. GET/HEAD use weak comparison. HEAD has no body. Matching is neither byte identity nor freshness. Other methods normally return 412; If-Range cannot use weak ETags.

Validator type and strength are different questions

An ETag is an opaque, quoted value. It can be strong ("release-a") or explicitly weak (W/"release-a"). Strong comparison requires both tags to be strong and equal; weak comparison compares the opaque values regardless of the W/ marker. Weak tags can describe semantic equivalence even when bytes differ.

Last-Modified is a timestamp with one-second HTTP-date resolution. It is usually weak unless the conditions in RFC 9110 section 8.8.2.2 establish it as strong. Do not classify every ETag as strong or every timestamp as unconditionally weak.

The earlier site observation recorded:

etag: "dkx84jwth7nkc9e"
last-modified: Mon, 24 Aug 2026 13:55:23 GMT

These are historical values; the original response log is not retained here and the live result was not rechecked in this review. Caddy’s file server normally sets both fields, subject to file metadata and configuration.

Conditional GET uses weak comparison

Send the ETag exactly as received in If-None-Match, including its quotes and any W/. The original note reported HTTP 304 for the value above but printed an unquoted request value. That request text was not valid entity-tag syntax and should not be copied as a working probe. Obtain a current validator before testing a live endpoint.

This socket-free exercise illustrates the comparison for individual, already-parsed tags; it is not a complete HTTP header parser:

def weak_value(tag):
 return tag[2:] if tag.startswith('W/') else tag

def strong_equal(a, b):
 return not a.startswith('W/') and not b.startswith('W/') and a == b

stored = 'W/"release-a"'
current = '"release-a"'
assert weak_value(stored) == weak_value(current)
assert not strong_equal(stored, current)
assert weak_value(stored) != weak_value('"release-b"')
print("weak match: True; strong match: False; changed tag: no match")

For an otherwise successful GET or HEAD, a matching If-None-Match produces a body-free 304. The same false precondition on another method normally produces 412 Precondition Failed. If both If-None-Match and If-Modified-Since are present, the ETag condition takes precedence. Byte-range validation with If-Range cannot use a weak ETag.

Republish without preserving a misleading validator

An ETag is not necessarily a content hash. Caddy v2.10.2’s default file tag is derived from modification time and size; replacing bytes while preserving both can preserve the tag. Inspect the deployed version and any configured overrides, then make the release process update the validator’s inputs or use content-based versioning.

Keep byte checksums in the release manifest and test both unchanged and changed responses. A checksum does not automatically become the server’s ETag. A 304 also needs the applicable cache metadata so a cache can update its stored response; it is not merely an empty success status.

Sources

RFC 9110 — HTTP Semantics, sections 8.8 and 13 on validator strength and preconditions, checked 2026-10-15.
RFC 9111 — HTTP Caching, section 4.3 on validation and updating stored responses, checked 2026-10-15.
MDN: HTTP conditional requests, conditional-request overview, checked 2026-10-15.
Caddy v2.10.2 file-server source, calculateEtag inputs and default response fields, checked 2026-10-15.

A certificate chain is a path you should be able to print

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

A TLS client must build a valid certificate path to an anchor it already trusts, and verify the requested hostname. Printing certificates is a useful diagnostic, but does not establish either result by itself.

The server supplies certificates; trust comes from the client’s anchor. Validate the path, requested hostname and validity period. Printed certificate counts cannot establish those results.

The leaf is not the whole story

The endpoint presents the leaf first. It contains the public key, validity period, and subject alternative names used for hostname checks. A public-CA deployment normally also sends the intermediates needed to build a path. Missing intermediates can break clients that do not already have them cached or cannot retrieve them.

The self-signed root normally need not be sent: trust comes from the client’s configured anchors, not from a server including a certificate. A cross-signed certificate whose subject says “Root” can instead be an intermediate in the selected path. Certificate count alone is therefore not a completeness or trust test.

Read the chain the edge actually sends

OpenSSL documents s_client -showcerts as the server’s certificate list, not a verified chain. The earlier version of this note recorded this site snapshot:

certificate 0: CN=www.xbcatm.com
 issuer : C=US, O=Let's Encrypt, CN=YE1
 notAfter : Nov 19 08:37:12 2026 GMT

certificate 1: CN=YE1 (intermediate)
 issuer : C=US, O=ISRG, CN=Root YE

certificate 2/3: Root YE / ISRG Root … (CA certificates)

The original report counted four blocks. Its raw handshake log is not retained here, and this review did not reproduce the live handshake; treat the values as a historical report, not current edge evidence. Let’s Encrypt’s chain documentation does describe YE1 and a cross-signed Root YE path, so those names alone are not evidence of an invalid chain. Which certificate terminates trust depends on the client’s trust store and path building.

Keep issuance authorization separate

Intermediates let a CA keep its root key offline and separate issuance operations. Revoking an intermediate can invalidate dependent leaf paths and may require replacement certificates; it does not preserve every leaf automatically.

CAA authorizes a CA’s documented issuer-domain identifier at issuance time. It does not pin an intermediate, change browser trust, or prove that an existing certificate complied with historical CAA. The dns-caa-records note covers that separate policy check.

Count for inventory, validate for trust

The earlier inventory command was:

$ echo | openssl s_client -connect www.xbcatm.com:443 -servername www.xbcatm.com -showcerts 2>/dev/null | grep 'BEGIN CERT' | wc -l
4

This is read-only network traffic, but it suppresses diagnostics and the final count can succeed even when an earlier command failed. Do not use 4, or any other fixed count, as a health threshold. A leaf-only result warrants checking the expected issuer path rather than declaring every one-certificate chain invalid.

For actual validation, configure hostname checking and failure on verification errors with OpenSSL’s -verify_hostname and -verify_return_error options, retain diagnostics, and record the trust store and client version. Also test the clients you support; one OpenSSL trust store cannot establish compatibility with all browsers.

Sources

RFC 8446 — TLS 1.3, section 4.4.2 certificate-list order and optional trust-anchor omission, checked 2026-10-15.
RFC 5280 — X.509 PKI, section 6 trust-anchor input and path validation, checked 2026-10-15.
Let’s Encrypt FAQ, certificate compatibility overview, checked 2026-10-15.
Let’s Encrypt: Chains of Trust, YE1 and cross-signed Root YE paths, checked 2026-10-15.
OpenSSL s_client, presented-list and verification options, checked 2026-10-15.
RFC 8659 — CAA, issuance authorization rather than client trust, checked 2026-10-15.

Debugging · XB Field Notes

git bisect narrows the first bad commit

Choose endpoints by observation, not date

Make each decision about the same property

When it breaks

Check it quickly

Further reading

Sources

curl is your first HTTP probe

Separate four kinds of evidence

When it breaks

Check it quickly

Further reading

Sources

Read a live edge the way a client does

1. Start with what a method may ask

2. Read the representation line

3. Compare HEAD and GET for the same representation

4. Ask for precise bytes with a range

5. Let the cache revalidate with a validator

6. Negotiate a smaller representation when you can

7. Follow the story when a URL changes

8. Let the crawler read the map last

The whole path in one glance

Sources

Redirects and error codes should preserve the story

Permanent moves are not all interchangeable

Distinguish missing from removed

Sources

Read the public edge in two commands

Inspect the response headers

Inspect the certificate dates

Use both around a release

Sources

HTTP methods are a promise about side effects

Safe and idempotent answer different questions

A Caddy file handler’s method boundary

HEAD parity allows documented omissions

Reject unintended writes without hiding the contract

Sources

Validators decide whether a cached copy is still the answer

Validator type and strength are different questions

Conditional GET uses weak comparison

Republish without preserving a misleading validator

Sources

A certificate chain is a path you should be able to print

The leaf is not the whole story

Read the chain the edge actually sends

Keep issuance authorization separate

Count for inventory, validate for trust

Sources