Architecture · XB Field Notes

Graceful degradation keeps partial value

Thu, 22 Apr 2027 00:00:00 +0000

Graceful degradation preserves a deliberately supported subset of a service when another part fails. An article page might omit recommendations while still showing the requested article. The important word is supported: a partial answer must remain useful and truthful under its product contract. Returning something is not automatically safer than returning an explicit failure.

Choose what may be missing

Identify optional regions and required outcomes before writing fallback code. A missing sidebar can be acceptable; silently bypassing authorization, presenting an uncertain payment as successful, or substituting an unverified price can violate the core promise. Those cases require an explicit failure or a separate approved workflow rather than a generic “keep the page green” rule.

Keep the optional dependency outside the core response’s critical path where possible. Give its call a bounded budget, but remember that a caller timeout does not necessarily stop underlying work. Bound concurrency and queued work as well. A placeholder should name the missing capability without exposing internal errors, and should not imply that fresh data was obtained when it was not.

Make stale-data acceptance explicit

Last-known-good data is useful only within a declared scope and age policy. Record when the data was obtained, preserve its identity and authorization scope, and decide what happens when its age is unknown, excessive, or the cache is empty. A timestamp alone does not establish correctness: some data is unsafe to reuse even briefly after a relevant state change.

Serving stale after an upstream failure is not identical to stale-while-revalidate, which can serve an eligible stale response while validation proceeds. Either approach needs bounded freshness and resource behavior. Successful refresh should actually replace the stored value and its age. Otherwise a service can repeatedly claim to use its latest good result while returning an older snapshot forever.

When it breaks

Fallback may amplify an outage. AWS’s account of avoiding fallback describes a cache failure that redirected traffic into a database unable to absorb it. That source is a warning about difficult, rarely exercised alternate paths, not a blanket endorsement of partial answers. Prefer predictable primary behavior and regularly exercised recovery paths over a complicated fallback whose resource demands are unknown.

Synchronized cache expiry and simultaneous recovery probes can create bursts. Spread refresh work, limit retries and concurrency, and measure whether the fallback competes with the same exhausted resource. A circuit breaker decides whether to call a dependency; the degradation policy decides what acceptable answer remains. An open breaker does not itself prove that a cached response is valid or that a static answer meets the contract.

A failed recovery probe must leave normal admission blocked. Closing a breaker before testing recovery can release traffic too early. Production implementations also need synchronization, probe scheduling, and bounded recovery concurrency; a serial example cannot establish those properties. Degraded responses should have their own count and age observations so that an HTTP 200 does not hide persistent loss of functionality.

Only the optional recommendation contract permits this fallback. Ages 0–120 seconds may reuse the latest cache; otherwise the model returns a labeled static simplification, and a failed probe keeps normal calls blocked.

Check it quickly

Save this as degrade_probe.py and run python3 degrade_probe.py. The standard-library fixture models one optional recommendation region. It performs no network or filesystem operations. Cache age and dependency failure are injected inputs, and the 120-second limit is an illustrative product decision. Probe calls are explicit and synchronous; no timer or concurrent request admission is implemented.

class DependencyDown(Exception):
 pass

class PageService:
 def __init__(self):
 self.cached_recs = ["cached-pick"]
 self.cached_age_s = 90 # Injected age, not a running clock.
 self.max_age_s = 120
 self.failures, self.threshold = 0, 3
 self.open = False
 self.live_calls = 0

 def live_recs(self, fail):
 self.live_calls += 1
 if fail:
 raise DependencyDown("recs down")
 return ["fresh-pick"]

 def fresh(self, data):
 self.cached_recs, self.cached_age_s = list(data), 0
 self.failures, self.open = 0, False
 return {"mode": "fresh", "data": data}

 def fallback(self, reason):
 if self.cached_recs and 0 <= self.cached_age_s <= self.max_age_s:
 return {"mode": "cached", "data": list(self.cached_recs),
 "age_s": self.cached_age_s, "reason": reason}
 return {"mode": "simplified", "data": ["popular-picks"], "reason": reason}

 def get_recs(self, fail=False):
 if self.open:
 return self.fallback("breaker-open")
 try:
 return self.fresh(self.live_recs(fail))
 except DependencyDown:
 self.failures += 1
 self.open = self.failures >= self.threshold
 return self.fallback("dependency-failed")

 def half_open_probe(self, fail=False):
 # Explicit synchronous trial; not a concurrent admission controller.
 assert self.open, "probe requires an open breaker"
 try:
 data = self.live_recs(fail)
 except DependencyDown:
 return self.fallback("probe-failed") # Leave the breaker open.
 return self.fresh(data) # Close only after success.

svc = PageService()
assert svc.get_recs() == {"mode": "fresh", "data": ["fresh-pick"]}
assert svc.cached_recs == ["fresh-pick"] and svc.cached_age_s == 0
svc.cached_age_s = 120
cached = svc.get_recs(fail=True)
assert cached["mode"] == "cached" and cached["age_s"] == 120
assert cached["data"] == ["fresh-pick"]
svc.cached_age_s = 121
assert svc.get_recs(fail=True)["mode"] == "simplified"
svc.get_recs(fail=True)
assert svc.open
calls = svc.live_calls
assert svc.get_recs()["reason"] == "breaker-open" and svc.live_calls == calls
assert svc.half_open_probe(fail=True)["reason"] == "probe-failed"
assert svc.open and svc.live_calls == calls + 1
calls = svc.live_calls
svc.get_recs()
assert svc.live_calls == calls # A failed probe must not reopen normal admission.
assert svc.half_open_probe()["mode"] == "fresh" and not svc.open
assert svc.cached_age_s == 0
svc.cached_recs = []
assert svc.get_recs(fail=True)["mode"] == "simplified"
svc.cached_recs, svc.cached_age_s = ["unknown-age"], -1
assert svc.get_recs(fail=True)["mode"] == "simplified"
print("PASS: fresh refresh, bounded cache, empty/invalid cache, open gate, failed/successful probe")

A successful call refreshes the cache. The next failure serves that actual latest value when its injected age is exactly 120 seconds. At 121 seconds it uses a clearly simplified answer instead. Three consecutive failures open the call gate, and another ordinary request returns fallback without incrementing the live-call count. These checks distinguish acceptable stale data from merely available stale data.

The failed probe performs one live attempt but leaves the breaker open; a subsequent ordinary request still makes no live call. A successful probe then closes the gate and refreshes the cache. Separate empty-cache and invalid-negative-age controls also choose the simplified response. The final PASS line covers these deterministic decisions, not production availability.

Before deployment, exercise the chosen contract against real dependency failures and recovery under controlled load. Verify deadlines, cancellation, authorization scope, cache aging, and visible degradation metrics independently. The example’s static recommendation fallback is intentionally cheap; it does not demonstrate that an alternate remote service would remain healthy during a correlated outage.

Sources

AWS: Avoiding fallback in distributed systems, risks of infrequent fallback paths and amplified outages, checked 2026-10-15.
Google SRE: graceful degradation, shedding to keep the useful parts, checked 2026-10-15.
Martin Fowler: CircuitBreaker, open-state rejection and controlled recovery probes, checked 2026-10-15.

Circuit breakers stop storming a down service

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

A circuit breaker decides whether a new call should reach a dependency that appears unhealthy. It can reject promptly instead of spending resources on another likely failure. It does not repair that dependency, cancel calls already running, or prove that rejected work would have failed. Its value depends on the failure signals and recovery policy it actually implements.

Name the policy, not just the states

Closed means calls may proceed, not that every call will succeed. Open means new calls are refused under the breaker’s policy. Half-open admits limited trial work to gather evidence before deciding whether ordinary traffic can resume.

The detection rule is not universally a sliding-window failure percentage. Fowler’s example counts failures and resets on success; other implementations use time windows, failure ratios, slow-call thresholds, or minimum sample counts. Specify the actual rule rather than borrowing a diagram and assuming its thresholds.

The fixture uses two consecutive classified failures in completion order, a five-second cooldown, and one half-open probe. One success resets the consecutive counter. These numbers make transitions easy to verify; they are not suggested production settings.

Classify and scope failures

A malformed caller request does not necessarily mean a dependency is down. Decide which exceptions, statuses, and slow outcomes should influence the breaker. A locally refused call is also different from a request that reached the dependency and failed. Mixing those observations can make the breaker reinforce its own refusal state.

Scope state to the failure domain you intend to protect. One unavailable shard or operation need not justify blocking a healthy independent provider. Conversely, thousands of independent process-local breakers can each allow a probe, so “one half-open request” may mean one per instance, not one globally.

Timeouts remain necessary. A call that never finishes might hold a connection or worker without ever producing the failure observation needed to open the breaker. The admission decision does not replace a deadline, a concurrency limit, or resource cleanup.

Recovery is a controlled experiment

After cooldown, reserve probe admission atomically. If several threads all observe that trial work is allowed before any claims the permit, the supposed single probe becomes a burst. The example protects its small state transition with a lock; it does not hold that lock while a dependency operation runs.

An old in-flight result also needs an explicit interpretation. Here, opening creates a new local generation, and results from older permits cannot close that newer open state. The generation is bookkeeping inside this model, not a distributed fencing token or a way to undo remote work.

A failed probe starts another cooldown. A successful probe closes this fixture’s breaker, but one successful trial does not prove capacity for all returning traffic. If gradual recovery is required, validate the actual traffic-admission policy instead of assuming the word half-open guarantees a ramp.

When it breaks

Aggressive thresholds can deny healthy requests; long cooldowns can keep refusing after recovery. Overly broad scopes hide partial health. A retry loop that repeatedly catches an open-circuit refusal can waste resources even though it sends no new dependency requests.

Observe forwarded calls, classified outcomes, local refusals, state transitions, and probe results separately. Test sustained failures, occasional successes, concurrent trial admission, and late completions. A green unit test for a counter is not evidence that a live dependency recovers safely.

The model uses two consecutive classified failures, a five-second cooldown and one atomic trial permit. Old-generation results cannot close a newer opening; no production recovery throughput is established.

Check it quickly

Save the block as breaker_check.py and run python3 breaker_check.py with Python 3.10 or newer. It ran with Python 3.14.4 using only the standard library. The script models outcomes and injects monotonic-time values without sleeping or contacting a service. Eight real threads contend for a half-open permit.

from concurrent.futures import ThreadPoolExecutor
from threading import Barrier, Lock


class OpenCircuit(Exception):
 pass


class Breaker:
 # Explicit fixture policy: two consecutive classified failures, five-second cooldown.
 def __init__(self):
 self.state, self.failures, self.until = "closed", 0, 0
 self.epoch, self.probe_busy = 0, False
 self.lock = Lock()

 def acquire(self, now):
 with self.lock:
 if self.state == "open":
 if now < self.until:
 raise OpenCircuit
 self.state = "half-open"
 if self.state == "half-open":
 if self.probe_busy:
 raise OpenCircuit
 self.probe_busy = True
 return self.epoch, True
 return self.epoch, False

 def complete(self, permit, succeeded, now):
 epoch, probe = permit
 with self.lock:
 if epoch != self.epoch:
 return # This outcome belongs to an earlier breaker generation.
 if probe:
 self.probe_busy = False
 self.epoch += 1
 self.failures = 0
 self.state = "closed" if succeeded else "open"
 if not succeeded:
 self.until = now + 5
 elif self.state == "closed":
 self.failures = 0 if succeeded else self.failures + 1
 if self.failures >= 2:
 self.state, self.until = "open", now + 5
 self.epoch += 1


breaker = Breaker()
other_dependency = Breaker()
forwarded = []


def invoke(succeeded, now):
 permit = breaker.acquire(now)
 forwarded.append(now) # A modeled dependency invocation, not a network call.
 breaker.complete(permit, succeeded, now)


invoke(False, 0)
assert breaker.failures == 1
invoke(True, 1)
assert breaker.failures == 0
late = breaker.acquire(1)
invoke(False, 2)
invoke(False, 3)
assert breaker.state == "open" and breaker.until == 8
other_permit = other_dependency.acquire(4)
other_dependency.complete(other_permit, True, 4)
assert other_dependency.state == "closed"
before = len(forwarded)
try:
 invoke(True, 7.99)
except OpenCircuit:
 pass
else:
 raise AssertionError("open circuit must reject before dispatch")
assert len(forwarded) == before
breaker.complete(late, True, 7.99)
assert breaker.state == "open"
print("success resets consecutive failures; two later failures open until time 8")
print("open calls are not dispatched; an older in-flight success does not close a newer open generation")

gate = Barrier(8)


def probe_attempt(_):
 gate.wait(timeout=5)
 try:
 return breaker.acquire(8)
 except OpenCircuit:
 return None


with ThreadPoolExecutor(max_workers=8) as pool:
 permits = list(pool.map(probe_attempt, range(8)))
admitted = [permit for permit in permits if permit is not None]
assert len(admitted) == 1 and admitted[0][1] is True
assert breaker.state == "half-open" and breaker.probe_busy
breaker.complete(admitted[0], False, 8)
assert breaker.state == "open" and breaker.until == 13
print("eight simultaneous half-open candidates receive one probe permit and seven refusals")
print("failed probe opens a new cooldown ending at time 13")

try:
 breaker.acquire(12.99)
except OpenCircuit:
 pass
else:
 raise AssertionError("second cooldown must still apply")
probe = breaker.acquire(13)
breaker.complete(probe, True, 13)
assert breaker.state == "closed" and not breaker.probe_busy
invoke(True, 14)
assert other_dependency.state == "closed" and other_dependency.failures == 0
print("a successful later probe closes this breaker; another dependency has separate state")

An initial success resets the failure count. Two later failures open the breaker until time eight, and an attempted call before that boundary adds no modeled dispatch. A previously admitted success cannot close the newer generation. A second dependency’s already existing breaker remains usable.

At time eight, eight simultaneous candidates obtain one permit and seven refusals. Failure of that probe opens another interval ending at thirteen. A later successful probe closes the breaker and permits ordinary work again.

Each granted permit in this model receives one completion with an already classified outcome. Real transport timeouts, cancellation, automatic failure classification, distributed probe coordination, library integration, and recovery throughput are not tested. Use an established implementation where appropriate and verify its precise contracts against the real workload.

Sources

Martin Fowler: Circuit breaker, failure counting, success reset, and trial recovery, checked 2026-09-08.
Azure architecture: Circuit breaker, state semantics, exception classification, concurrency, and failure-domain scope, checked 2026-09-08.
Python threading, locks and barriers used by the concurrent permit experiment, checked 2026-09-08.

Object and block storage expose different update contracts

Wed, 17 Mar 2027 00:00:00 +0000

Block storage exposes addressable blocks through a device interface. Object storage exposes named objects through an API. Neither label alone specifies durability, consistency, sharing, or price. Start with the application’s required operations, then check the particular service’s contract. A filesystem, database, or compatibility layer can add behavior, but it cannot make every underlying interface interchangeable.

Compare the actual operations

A block volume can be formatted with a filesystem or used directly by software that manages its own layout. The service does not necessarily supply a filesystem. Small overwrites are possible without replacing the whole volume, but safe shared access still needs coordination. Attaching one volume to multiple machines does not turn an ordinary single-host filesystem into a clustered filesystem. Database recovery also depends on write ordering and durability guarantees above the block interface.

An object is addressed within a bucket or another service-defined namespace. Ordinary S3 general-purpose bucket writes replace an entire object; reads can request byte ranges, so “object storage always reads everything” is wrong. Multipart upload assembles a completed object from uploaded parts; it is not a general filesystem’s random-write contract. Specialized products can offer additional append or update operations. Check the selected bucket type and API rather than treating one simple model as a universal rule.

Object storage commonly suits media, exports, and backup artifacts accessed by many clients. Block storage commonly suits database files and virtual-machine disks. These are workload patterns, not exclusive categories: databases can be designed around object storage, and shared filesystems can sit above block devices. Measure request sizes, concurrency, recovery behavior, and total request and transfer charges before choosing.

When it breaks

Do not assume object storage is eventually consistent. Amazon S3 documents strong read-after-write consistency for object PUTs and DELETEs and corresponding reads and listings. A client retaining an old downloaded value can still be stale, but that is not evidence that a fresh service read returns an obsolete value. CDN caches, cross-region replication, and multi-object application updates introduce separate boundaries that need their own guarantees.

Successful S3 PUT does not expose a partially uploaded object. A failed or ambiguous request requires checking the actual result, not inventing a truncated replacement. Atomic replacement of one object also does not prevent lost updates: two clients can read the same version and replace it independently. Conditional requests compare a validator before accepting an update. The model’s integer generation is synthetic; S3 If-Match uses an ETag, not that counter or a version ID. Use the service’s documented conditions; an ETag is not universally a content checksum or a transaction spanning several keys.

Lifecycle deletion and version retention need deliberate recovery tests. Enabling versioning is not the same as maintaining an independent backup, and retaining a local version number is not the same as preserving old payloads. Small-object workloads can be dominated by request overhead even when stored bytes are inexpensive. A mount adapter that accepts a database filename also needs the database’s locking, ordering, and failure semantics before it is a suitable home.

Two update contracts — mechanism diagram.

Check it quickly

Save this as storage_semantics.py and run python3 storage_semantics.py with Python 3.9 or newer. It is a standalone in-memory API model using synthetic bytes. No service, filesystem durability, network latency, or billing behavior is exercised.

"""In-memory API model, not an implementation of a storage service."""
class BlockVolume:
 def __init__(self, data):
 self.data = bytearray(data)
 def write(self, offset, chunk):
 if offset < 0 or offset + len(chunk) > len(self.data):
 raise ValueError("write outside fixed volume")
 self.data[offset:offset + len(chunk)] = chunk

class ObjectStore:
 def __init__(self):
 self.current = {}
 def put(self, key, data, expected=None):
 old = self.current.get(key)
 version = old[1] if old else 0
 if expected is not None and expected != version:
 raise ValueError("version conflict")
 self.current[key] = (bytes(data), version + 1)
 return version + 1
 def get(self, key):
 return self.current[key]

block = BlockVolume(b"ABCDEF")
block.write(2, b"XX")
assert block.data == b"ABXXEF"
try:
 block.write(5, b"too long")
except ValueError:
 pass
else:
 raise AssertionError("out-of-range write accepted")
assert block.data == b"ABXXEF"
store = ObjectStore()
assert store.put("report", b"ABCDEF", expected=0) == 1
cached = store.get("report")
assert store.put("report", b"XYZ", expected=1) == 2
assert store.get("report") == (b"XYZ", 2)
assert cached == (b"ABCDEF", 1)
try:
 store.put("report", b"stale overwrite", expected=cached[1])
except ValueError:
 pass
else:
 raise AssertionError("stale conditional update accepted")
assert store.get("report") == (b"XYZ", 2)
assert store.get("report")[0][1:3] == b"YZ"
print("PASS: bounded overwrite; complete replacement; cached copy differs; stale condition rejected")

The block starts with six bytes. Writing two bytes preserves its neighbors, while an out-of-range write is rejected without changing the volume. The object starts at version one and is completely replaced by the three-byte value at version two. A fresh get immediately returns that replacement. The separately retained tuple still contains version one because the application kept a copy.

The conditional update using that old version fails, and the final assertion confirms that the current object remains unchanged. Slicing the retrieved bytes illustrates a selected range only; it is not a network Range-request test. The PASS line proves these explicit model rules. It does not prove a provider’s implementation, concurrency control, historical-version retention, crash atomicity, or recoverability. Before deployment, repeat the relevant operations against the chosen service with its real SDK and failure handling.

Sources

Amazon S3 data model, object operations and strong consistency, checked 2026-10-15.
S3 PutObject, complete-object writes and conditional requests, checked 2026-10-15.
Amazon EBS, block volumes and application-managed filesystems, checked 2026-10-15.

The advantage of small systems

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

Small does not mean unfinished. It means each component has a clear job, dependencies are deliberate, and the path from request to result remains visible.

Name each request boundary, its evidence and its owner. Fewer components reduce the paths to understand; backups and recovery practice still carry the recovery promise.

Visibility is a feature

When operators can name every boundary, they can also identify which evidence is missing. Logs become more useful, alerts become more specific, and routine maintenance becomes less risky.

For a static website the important boundaries are usually easy to list:

DNS points the hostname to the intended edge.
TLS terminates at the intended proxy.
The proxy serves one known output directory.
The output contains only the files the site needs.
A 404 response is handled by the site, not by an accidental upstream.

Writing this list down is more valuable than adding a dashboard that does not answer any of those questions.

Complexity should earn its place

A new layer is worthwhile when it removes more uncertainty than it creates. A build step that fingerprints assets can be useful when caching is important. A database is useful when content needs transactions. Neither is automatically an improvement for a small, mostly static site.

The same rule applies to client-side JavaScript. If a page genuinely requires client-side scripting, choose the smallest implementation that meets the requirement and review its content security policy deliberately. For this site, that would first require revisiting the accepted zero-script architecture and its verification contract; it is not an exception to the current policy. If the page is a document, plain HTML is often easier to inspect and more resilient.

Make ownership explicit

Every file should have a reason to exist and a clear way to update it. A vendored theme should record its upstream version and license. A generated directory should be marked as generated. A resource download should say what it contains, when it was updated, and how its checksum was produced.

These small statements prevent future operators from treating an accidental artifact as a supported interface.

Leave room for the next change

The best small system is not the one with the fewest lines. It is the one where the next change has a visible place to go. A notes site can start with Markdown, a static generator, and a web server; if it later needs search or comments, the new requirement can be evaluated on its own rather than assumed from the beginning.

Small is not automatically fault-tolerant. A single edge, disk, or operator can still be a single point of failure. Choose acceptable recovery time and data loss, keep an independent backup, and rehearse recovery. The benefit of fewer components is a smaller set of failure paths to understand, not immunity to outages.

Sources

Hugo directory structure, directory conventions for content and assets, checked 2026-07-27.
Caddy file_server directive, static file serving defaults referenced by the design, checked 2026-07-27.

Why a small site can stay static

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

A static site serves documents prepared before their requests arrive. The important question is whether visitors need different server-generated representations, rather than how many pages the site contains. Hundreds of articles can share one publishing model: edit sources, build HTML and assets, validate the output, then expose those files through a web server or CDN.

Put document generation at the right boundary

When an article means the same thing for every reader, assembling it on every request often adds little value. Templates, navigation, translations, and indexes can be resolved during a build. The serving path then needs the published files, not the authoring database or generator. Requests can still be logged, encrypted, cached, and access-controlled; static delivery does not remove these responsibilities.

Static HTML can include JavaScript and interactive controls. A client-side search index may suit a modest public collection, whereas private search or personalized results need a service that enforces access. Forms, comments, payments, and authenticated mutations likewise require appropriate processing. Identify those boundaries separately: making the article static does not make a browser authoritative for permissions or durable state.

Build-time generation moves work rather than eliminating it. Large collections can have expensive rebuilds, dependencies can fail, and content freshness is limited by the publishing pipeline. A new source edit is not automatically visible. For time-sensitive material, measure edit-to-publication delay, keep build failures visible, and verify the released document instead of assuming a successful editor save reached readers.

When it breaks

A common failure is serving the repository root. Source data, build scripts, or private drafts may then become downloadable even though no navigation links mention them. Use a dedicated output directory containing only intended artifacts. Excluding a document from an index is different from excluding its file from publication. Inspect the actual release inventory, including copied assets and generated search data.

Another failure is updating files individually while requests arrive. An HTML page can reference an asset not yet uploaded, or an old page can lose a dependency deleted during cleanup. Prepare complete releases, preserve necessary old assets, and use the hosting platform’s supported switch mechanism. Restoring an old source commit alone does not restore dependencies, artifacts, cache state, or external services.

Static output also carries injection risks. Untrusted text needs context-appropriate escaping; inserting it directly into HTML can turn an article value into active markup. Escaping text does not validate arbitrary URLs, sanitize intentionally allowed HTML, or protect JavaScript contexts. Review the actual template positions and source trust instead of treating static generation as automatic security.

Editing a source does not publish it. Static illustration of the source and its limits. Reported fixture outcomes were not rerun for this graphic.

Check it quickly

Save the following as static-build.py and run python3 static-build.py with Python 3. It creates a temporary source outside a public directory, builds one HTML file, and serves only that directory over loopback. The script exercises publication with actual HTTP requests and removes its temporary files after closing the server.

from functools import partial
from hashlib import sha256
from html import escape
from http.client import HTTPConnection
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Thread
import json
import os


class Handler(SimpleHTTPRequestHandler):
 def log_message(self, *args):
 pass


with TemporaryDirectory() as directory:
 root = Path(directory)
 public = root / 'public'
 public.mkdir()
 source = root / 'source.json'
 source.write_text(json.dumps({'title': 'Version one', 'text': 'Published content'}))

 def build():
 content = json.loads(source.read_text())
 document = f'<!doctype html><html lang="en"><head><meta charset="utf-8"><title>{escape(content["title"])}</title></head><body><h1>{escape(content["title"])}</h1><p>{escape(content["text"])}</p></body></html>'
 pending = root / 'next.html'
 pending.write_text(document)
 os.replace(pending, public / 'index.html')
 return document.encode()

 first = build()
 server = ThreadingHTTPServer(('127.0.0.1', 0), partial(Handler, directory=str(public)))
 thread = Thread(target=server.serve_forever)
 thread.start()
 try:
 def fetch(path='/'):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request('GET', path)
 response = connection.getresponse()
 return response.status, response.read()
 finally:
 connection.close()

 source.unlink()
 assert fetch() == (200, first)
 source.write_text(json.dumps({'title': 'Version two', 'text': '<b>literal text</b>'}))
 assert fetch() == (200, first)
 second = build()
 assert fetch() == (200, second) and second != first
 assert b'&lt;b&gt;literal text&lt;/b&gt;' in second
 assert fetch('/source.json')[0] == 404
 print(json.dumps({'serves_without_source': True, 'edit_requires_rebuild': True,
 'published_sha256': [sha256(first).hexdigest(), sha256(second).hexdigest()],
 'source_not_published': True, 'text_escaped': True}))
 finally:
 server.shutdown()
 thread.join()
 server.server_close()

First, the program deletes the editable source and still receives the previously published bytes. It recreates a changed source but confirms that requests continue returning version one until build runs again. The second build changes the document digest and returns version two. Its literal <b>literal text</b> is escaped in the HTML, and a request for /source.json returns 404. Expect all four behavior flags true and two different published hashes.

These checks passed with Python 3.14.4. The replacement uses os.replace on the same filesystem for one complete file. It does not demonstrate atomic publication of a multi-resource site, crash durability, automatic rollback, or a particular hosting provider’s deployment mechanism. The experiment isolates the source-to-artifact boundary. For a real release, inspect all generated files, test representative links and missing paths, and verify caching alongside artifact availability. Choose static delivery when this boundary matches the product, then operate the build and serving layers with their own observable checks.

Sources

GitHub Docs: About GitHub Pages, static hosting from published HTML, CSS and JavaScript files, checked 2026-09-13.
MDN: Introduction to the server side, static and dynamic response generation, checked 2026-09-13.

Architecture · XB Field Notes

Graceful degradation keeps partial value

Choose what may be missing

Make stale-data acceptance explicit

When it breaks

Check it quickly

Further reading

Sources

Circuit breakers stop storming a down service

Name the policy, not just the states

Classify and scope failures

Recovery is a controlled experiment

When it breaks

Check it quickly

Further reading

Sources

Object and block storage expose different update contracts

Compare the actual operations

When it breaks

Check it quickly

Sources

The advantage of small systems

Visibility is a feature

Complexity should earn its place

Make ownership explicit

Leave room for the next change

Sources

Why a small site can stay static

Put document generation at the right boundary

When it breaks

Check it quickly

Further reading

Sources