Faithful model of httpware, not httpware running in your browser. Pick a scenario above to begin.
+
+
+
+
+
+
+
+
Step 1 of 1
+
+
+
`;
+ }
+
+ function mount(selector, config) {
+ const container = document.querySelector(selector);
+ if (!container) return;
+ container.classList.add('hw-demo');
+ container.innerHTML = template(config);
+
+ const $ = (key) => container.querySelector('[data-el="' + key + '"]');
+ const els = {
+ scenarios: $('scenarios'), play: $('play'), replay: $('replay'), scenLabel: $('scenLabel'),
+ timeline: $('timeline'), outage: $('outage'), outageLabel: $('outageLabel'), playhead: $('playhead'),
+ laneA: $('laneA'), badgeA: $('badgeA'), srvA: $('srvA'), trackA: $('trackA'),
+ ifA: $('ifA'), okA: $('okA'), badA: $('badA'), latA: $('latA'),
+ laneB: $('laneB'), badgeB: $('badgeB'), srvB: $('srvB'), trackB: $('trackB'), brkB: $('brkB'),
+ ifB: $('ifB'), okB: $('okB'), badB: $('badB'), rejB: $('rejB'), latB: $('latB'),
+ poolWrap: $('poolWrap'), poolB: $('poolB'),
+ elapsedWrap: $('elapsedWrap'), elapsedB: $('elapsedB'),
+ note: $('note'),
+ dimT: $('dimT'), dimB: $('dimB'), dimL: $('dimL'), dimR: $('dimR'), ring: $('ring'),
+ coach: $('coach'), cArrow: $('cArrow'), cStep: $('cStep'), cTitle: $('cTitle'), cBody: $('cBody'), cGo: $('cGo'),
+ };
+ const ELS = { ifA: els.ifA, latA: els.latA, ifB: els.ifB, latB: els.latB, brkB: els.brkB, poolB: els.poolB, elapsedB: els.elapsedB };
+
+ // Built fresh inside run() from the selected scenario (STOPS is never read before a
+ // scenario is played, so it's safe to leave empty until then) — pages with one
+ // shared stop list across scenarios (buildStops ignoring its arg) keep working
+ // unchanged. Must NOT call config.buildStops() here at mount time: retry.md's
+ // buildStops dereferences its scenario argument, so calling it with no scenario
+ // selected yet would throw and abort mount() before the Play/scenario listeners
+ // are wired up.
+ let STOPS = [];
+
+ let timer = null, paused = false, tick = 0, stopIdx = 0;
+ let dotsA = [], dotsB = [];
+ let A = { ok: 0, bad: 0, if: 0, pend: [] };
+ let B = { ok: 0, bad: 0, rej: 0, if: 0, pend: [] };
+ let brk = null;
+ let bulk = null;
+ let retryCfg = null, budget = null, budgetExhausted = false;
+ let tmoCfg = null, timedOutCount = 0;
+ let rnd = mulberry(SEED);
+ let selectedScenario = null;
+
+ function spawnDot(arr, track, kind) {
+ const node = document.createElement('div');
+ node.className = 'dot ' + kind;
+ track.appendChild(node);
+ if (prefersReduced) {
+ node.style.transition = 'none';
+ node.style.left = '96%';
+ setTimeout(() => node.remove(), 200);
+ return;
+ }
+ arr.push({ node, x: 0 });
+ }
+ function advDots(arr) {
+ if (prefersReduced) return;
+ for (let i = arr.length - 1; i >= 0; i--) {
+ const d = arr[i];
+ d.x += ADV;
+ if (d.x >= 96) { d.node.style.opacity = '0'; setTimeout(() => d.node.remove(), 200); arr.splice(i, 1); }
+ else d.node.style.left = d.x + '%';
+ }
+ }
+
+ // ---- spotlight: 4 dim panels leave a bright hole over the union of targets ----
+ function spotlight(nodes) {
+ const rs = nodes.map((n) => n.getBoundingClientRect());
+ const pad = 6;
+ const x0 = Math.min(...rs.map((r) => r.left)) - pad, y0 = Math.min(...rs.map((r) => r.top)) - pad;
+ const x1 = Math.max(...rs.map((r) => r.right)) + pad, y1 = Math.max(...rs.map((r) => r.bottom)) + pad;
+ const W = window.innerWidth, H = window.innerHeight;
+ const set = (node, l, t, w, h) => {
+ node.style.left = l + 'px'; node.style.top = t + 'px';
+ node.style.width = Math.max(0, w) + 'px'; node.style.height = Math.max(0, h) + 'px';
+ node.classList.add('show');
+ };
+ set(els.dimT, 0, 0, W, y0);
+ set(els.dimB, 0, y1, W, H - y1);
+ set(els.dimL, 0, y0, x0, y1 - y0);
+ set(els.dimR, x1, y0, W - x1, y1 - y0);
+ els.ring.style.left = x0 + 'px'; els.ring.style.top = y0 + 'px';
+ els.ring.style.width = (x1 - x0) + 'px'; els.ring.style.height = (y1 - y0) + 'px';
+ els.ring.classList.add('show');
+ return { x0, y0, x1, y1 };
+ }
+ function hideSpot() {
+ [els.dimT, els.dimB, els.dimL, els.dimR, els.ring].forEach((n) => n.classList.remove('show'));
+ }
+
+ // ---- place coach on the side with the most room; arrow points at target ----
+ function placeCoach(hole) {
+ const c = els.coach;
+ c.classList.add('show');
+ const cw = c.offsetWidth, ch = c.offsetHeight, gap = 16;
+ const W = window.innerWidth, H = window.innerHeight, cy = (hole.y0 + hole.y1) / 2, cx = (hole.x0 + hole.x1) / 2;
+ const room = { right: W - hole.x1, left: hole.x0, bottom: H - hole.y1, top: hole.y0 };
+ let side, left, top;
+ if (room.right >= cw + gap) { side = 'right'; left = hole.x1 + gap; top = cy - ch / 2; }
+ else if (room.left >= cw + gap) { side = 'left'; left = hole.x0 - gap - cw; top = cy - ch / 2; }
+ else if (room.bottom >= ch + gap) { side = 'bottom'; top = hole.y1 + gap; left = cx - cw / 2; }
+ else { side = 'top'; top = hole.y0 - gap - ch; left = cx - cw / 2; }
+ left = Math.min(Math.max(10, left), W - cw - 10);
+ top = Math.min(Math.max(10, top), H - ch - 10);
+ c.style.left = left + 'px'; c.style.top = top + 'px';
+ const a = els.cArrow;
+ a.style.transform = 'rotate(45deg)';
+ if (side === 'right') { a.style.left = '-7px'; a.style.top = (cy - top - 6) + 'px'; a.style.borderTop = 'none'; a.style.borderRight = 'none'; a.style.borderLeft = '1px solid var(--hw-line)'; a.style.borderBottom = '1px solid var(--hw-line)'; }
+ else if (side === 'left') { a.style.left = (cw - 7) + 'px'; a.style.top = (cy - top - 6) + 'px'; a.style.borderBottom = 'none'; a.style.borderLeft = 'none'; a.style.borderTop = '1px solid var(--hw-line)'; a.style.borderRight = '1px solid var(--hw-line)'; }
+ else if (side === 'bottom') { a.style.top = '-7px'; a.style.left = (cx - left - 6) + 'px'; a.style.borderBottom = 'none'; a.style.borderRight = 'none'; }
+ else { a.style.top = (ch - 7) + 'px'; a.style.left = (cx - left - 6) + 'px'; a.style.borderTop = 'none'; a.style.borderLeft = 'none'; }
+ }
+
+ function showStop(s) {
+ paused = true;
+ const nodes = s.spot.map((key) => ELS[key]).filter(Boolean);
+ const hole = spotlight(nodes);
+ els.cStep.textContent = `Step ${stopIdx + 1} of ${STOPS.length}`;
+ els.cTitle.textContent = s.title;
+ els.cBody.textContent = s.body;
+ placeCoach(hole);
+ }
+ els.cGo.addEventListener('click', () => {
+ els.coach.classList.remove('show');
+ hideSpot();
+ paused = false;
+ stopIdx++;
+ });
+
+ function setupOutageBar(scenario) {
+ const win = computeOutageWindow(scenario);
+ if (win) {
+ els.outage.style.display = '';
+ els.outage.style.left = (win.from / scenario.dur * 100) + '%';
+ els.outage.style.width = ((win.to - win.from) / scenario.dur * 100) + '%';
+ els.outageLabel.textContent = 'backend ' + win.label;
+ } else {
+ els.outage.style.display = 'none';
+ }
+ }
+
+ function resetVisual() {
+ clearInterval(timer);
+ els.trackA.innerHTML = ''; els.trackB.innerHTML = '';
+ dotsA = []; dotsB = [];
+ tick = 0; stopIdx = 0; paused = false;
+ A = { ok: 0, bad: 0, if: 0, pend: [] };
+ B = { ok: 0, bad: 0, rej: 0, if: 0, pend: [] };
+ els.ifA.textContent = '0'; els.okA.textContent = '0'; els.badA.textContent = '0';
+ els.ifB.textContent = '0'; els.okB.textContent = '0'; els.badB.textContent = '0'; els.rejB.textContent = '0';
+ els.latA.textContent = '40ms'; els.latB.textContent = '40ms';
+ [els.latA, els.latB, els.ifA, els.ifB].forEach((n) => { n.style.color = ''; });
+ // Flow-diagram boxes reflect the selected scenario's CHAIN config, not the runtime
+ // middleware objects (which aren't constructed until run()). Otherwise the breaker
+ // box reads "no breaker" on a circuit-breaker page until the first Play.
+ const cfgB = selectedScenario ? selectedScenario.chainB : {};
+ els.brkB.className = 'box'; els.brkB.textContent = cfgB.circuitBreaker ? 'breaker CLOSED' : 'no breaker';
+ els.poolWrap.style.display = cfgB.bulkhead ? '' : 'none';
+ els.poolB.textContent = cfgB.bulkhead ? ('0/' + cfgB.bulkhead.maxConcurrent) : '—';
+ els.elapsedWrap.style.display = cfgB.timeout ? '' : 'none';
+ els.elapsedB.textContent = cfgB.timeout ? ('0.0s / ' + cfgB.timeout.timeout.toFixed(1) + 's') : '—';
+ els.srvA.className = 'box'; els.srvA.textContent = 'server ✓';
+ els.srvB.className = 'box'; els.srvB.textContent = 'server ✓';
+ els.laneA.className = 'lane'; els.laneB.className = 'lane';
+ els.playhead.style.left = '0%';
+ els.badgeA.className = 'badge'; els.badgeA.textContent = 'no protection';
+ els.badgeB.className = 'badge'; els.badgeB.textContent = selectedScenario ? chainLabel(selectedScenario.chainB) : 'CircuitBreaker';
+ els.coach.classList.remove('show'); hideSpot();
+ }
+
+ function updateUI(now, lastFault) {
+ els.ifA.textContent = A.if; els.okA.textContent = A.ok; els.badA.textContent = A.bad;
+ els.ifB.textContent = B.if; els.okB.textContent = B.ok; els.badB.textContent = B.bad; els.rejB.textContent = B.rej;
+ els.ifA.style.color = A.if > 10 ? 'var(--hw-bad)' : '';
+ els.ifB.style.color = B.if <= 6 ? 'var(--hw-ok)' : '';
+ if (bulk) els.poolB.textContent = bulk.inUse + '/' + bulk.max;
+ let maxElapsed = 0;
+ if (tmoCfg) {
+ maxElapsed = B.pend.reduce((m, p) => Math.max(m, now - p.start), 0);
+ els.elapsedB.textContent = maxElapsed.toFixed(1) + 's / ' + tmoCfg.timeout.toFixed(1) + 's';
+ }
+ // "Stress" covers two distinct fault shapes: outright failure (down) and a
+ // high-latency-but-ok fault (slow, e.g. bulkhead.md's 5s dependency) — both must
+ // read as backend trouble even though only `down` implies an error response.
+ const down = !!(lastFault && !lastFault.ok);
+ const slow = !!(lastFault && lastFault.ok && lastFault.ms >= 1.0);
+ const stressed = down || slow;
+ // latA is the plain client's p99: reflect the ACTUAL in-flight latency tail, not
+ // the last request. In a brownout (mixed fast successes + slow failures) the last
+ // sample flickers, so a last-request p99 drops to 40ms whenever the last request
+ // was a fast success — contradicting the "p99 blown" narration while slow requests
+ // are still piled up in flight. The in-flight max is stable and honest.
+ const aTailMs = A.pend.length ? A.pend.reduce((m, p) => Math.max(m, p.ms), 0) : 0.04;
+ const plainStress = aTailMs >= 1.0 || A.if > 4;
+ els.latA.textContent = plainStress ? (A.if > 4 ? '12s+' : formatMs(aTailMs)) : '40ms';
+ els.latA.style.color = plainStress ? 'var(--hw-bad)' : '';
+ // On timeout pages, AsyncTimeout bounds every lane-B attempt at the deadline —
+ // p99 must reflect that ACTUAL bounded latency, not the constant 40ms, or it
+ // visually contradicts elapsedB as it climbs toward the same deadline. Pages
+ // with no timeout configured keep the untouched 40ms constant.
+ els.latB.textContent = tmoCfg ? formatMs(Math.min(maxElapsed, tmoCfg.timeout)) : '40ms';
+ els.latB.style.color = (down && brk && brk.state === 'OPEN') ? 'var(--hw-ok)' : '';
+ const st = brk ? brk.state : 'CLOSED';
+ els.brkB.className = 'box ' + (st === 'OPEN' ? 'open' : st === 'HALF_OPEN' ? 'half' : '');
+ els.brkB.textContent = brk ? ('breaker ' + st) : 'no breaker';
+ els.srvA.className = 'box' + (stressed ? ' down' : '');
+ els.srvA.textContent = down ? ('server ✗' + (lastFault.label ? ' ' + lastFault.label : ''))
+ : slow ? ('server ' + (lastFault.label || 'slow')) : 'server ✓';
+ els.srvB.className = 'box' + (stressed ? ' down' : '');
+ els.srvB.textContent = down ? 'server ✗' : slow ? 'server slow' : 'server ✓';
+ els.laneA.classList.toggle('hot', plainStress && A.if > 8);
+ els.laneB.classList.toggle('safe', st === 'CLOSED' && !stressed);
+ els.badgeA.className = 'badge' + (plainStress ? ' bad' : '');
+ els.badgeA.textContent = plainStress ? 'drowning' : 'no protection';
+ const okBadge = st === 'CLOSED' && brk && !stressed;
+ els.badgeB.className = 'badge ' + (st === 'OPEN' ? 'warn' : okBadge ? 'ok' : '');
+ els.badgeB.textContent = st === 'OPEN' ? 'fast-failing' : st === 'HALF_OPEN' ? 'probing' : chainLabel(selectedScenario.chainB);
+ }
+
+ function run() {
+ if (!selectedScenario) return;
+ const scenario = selectedScenario;
+ STOPS = config.buildStops(scenario);
+ brk = scenario.chainB && scenario.chainB.circuitBreaker
+ ? makeCircuitBreaker(scenario.chainB.circuitBreaker) : null;
+ bulk = scenario.chainB && scenario.chainB.bulkhead
+ ? makeBulkhead(scenario.chainB.bulkhead) : null;
+ retryCfg = scenario.chainB && scenario.chainB.retry ? scenario.chainB.retry : null;
+ // retry.py: Retry(budget=None) defaults to RetryBudget() — a retry config with no
+ // explicit budget must still retry (real defaults), never silently go unbudgeted.
+ budget = retryCfg
+ ? makeRetryBudget(scenario.chainB.budget || REAL.retryBudget)
+ : null;
+ budgetExhausted = false;
+ tmoCfg = scenario.chainB && scenario.chainB.timeout ? scenario.chainB.timeout : null;
+ timedOutCount = 0;
+ rnd = mulberry(SEED);
+ resetVisual();
+
+ timer = setInterval(() => {
+ if (paused) return;
+ const now = tick * TICK / 1000;
+ const mw = { state: brk ? brk.state : 'CLOSED', recovered: brk ? brk.recovered : false,
+ budgetExhausted, rejected: B.rej, cb: brk, timedOut: timedOutCount };
+ const state = { now, A, B, mw };
+ if (stopIdx < STOPS.length && STOPS[stopIdx].when(state)) { showStop(STOPS[stopIdx]); return; }
+
+ advDots(dotsA); advDots(dotsB);
+ els.playhead.style.left = (Math.min(now, scenario.dur) / scenario.dur * 100) + '%';
+
+ for (const L of [A, B]) {
+ for (let i = L.pend.length - 1; i >= 0; i--) {
+ if (L.pend[i].land <= tick) {
+ const p = L.pend[i]; L.pend.splice(i, 1);
+ let retried = false;
+ // AsyncTimeout bounds the WHOLE operation (outermost: timeout ->
+ // circuitBreaker -> bulkhead -> retry -> terminal). An entry clamped
+ // to its deadline (see clampToDeadline) lands as a TimeoutError
+ // failure here, regardless of what the untimed outcome would have
+ // been, and is never retried.
+ if (L === B && p.timedOut) {
+ timedOutCount++;
+ // Retry decision happens at landing time: a failed lane-B attempt gets
+ // one more shot if maxAttempts allows it AND the budget grants a token;
+ // otherwise (or with no budget at all) it counts as a final failure.
+ } else if (L === B && retryCfg && !p.ok && (p.attempt + 1) < retryCfg.maxAttempts) {
+ if (budget && budget.tryWithdraw(now)) {
+ const nextAttempt = p.attempt + 1;
+ // Full-jitter backoff (demo seconds); the retry is a NEW attempt
+ // against the backend, so its outcome is sampled at the later time.
+ const backoffSec = rnd() * Math.min(retryCfg.maxDelay, retryCfg.baseDelay * Math.pow(2, p.attempt));
+ const f2 = scenario.fault(now + backoffSec, rnd);
+ const landTicks = Math.max(1, Math.round((backoffSec + f2.ms) * 1000 / TICK));
+ // Composition order is timeout -> circuitBreaker -> bulkhead -> retry ->
+ // terminal: the bulkhead sits OUTSIDE retry, so one slot is acquired
+ // once and held for the WHOLE operation (all attempts), released only
+ // when the operation finally lands. Carry `bh` forward on every retry
+ // push, or a retried request leaks its slot forever. The deadline (and
+ // start) is likewise carried forward unchanged — it bounds the WHOLE
+ // operation, set once at the first attempt, not reset per retry — and
+ // clamped again here in case the backoff + this attempt would cross it.
+ const { land, timedOut } = clampToDeadline(tick, landTicks, p.deadline);
+ L.pend.push({ land, ok: f2.ok, attempt: nextAttempt, bh: p.bh, start: p.start, deadline: p.deadline, timedOut });
+ spawnDot(dotsB, els.trackB, f2.ok ? 'ok' : 'bad');
+ retried = true;
+ } else if (budget) {
+ budgetExhausted = true;
+ }
+ }
+ // Release the bulkhead slot only once the attempt truly finishes (not on
+ // a retry re-push) — `p.bh` marks entries that actually acquired a slot,
+ // so a null/absent bulkhead or a rejected (never-pushed) request is a no-op.
+ // Breaker records ONCE per fully-exhausted retry sequence (not per attempt):
+ // brk.res is called here, only on the terminal (non-retried) landing. A
+ // timed-out entry is an outer-timeout cancellation: AsyncTimeout is
+ // OUTERMOST, so the inner breaker's `except BaseException` clause does see
+ // the CancelledError (it releases the in-flight probe slot) but does not
+ // count it as a success/failure outcome — only the outer TimeoutError
+ // surfaces to the caller.
+ if (!retried) {
+ L.if--;
+ if (L === B && p.timedOut) { L.bad++; }
+ else { if (L === B && brk) brk.res(p.ok, now); if (p.ok) L.ok++; else L.bad++; }
+ if (L === B && bulk && p.bh) bulk.release();
+ }
+ }
+ }
+ }
+
+ const n = Math.round(RPS * TICK / 1000);
+ let lastFault = null;
+ for (let i = 0; i < n; i++) {
+ const f = scenario.fault(now, rnd);
+ lastFault = f;
+ const landTicks = Math.max(1, Math.round(f.ms * 1000 / TICK));
+ A.if++; A.pend.push({ land: tick + landTicks, ok: f.ok, attempt: 0, ms: f.ms });
+ spawnDot(dotsA, els.trackA, f.ok ? 'ok' : 'bad');
+ if (brk && !brk.allow(now)) {
+ B.rej++; spawnDot(dotsB, els.trackB, 'rej');
+ } else if (bulk && !bulk.tryAcquire()) {
+ // Pool is full: fail fast (BulkheadFullError) rather than queue — the
+ // demo's acquireTimeout=0 choice (see makeBulkhead).
+ B.rej++; spawnDot(dotsB, els.trackB, 'rej');
+ } else {
+ if (budget) budget.deposit(now);
+ // Total deadline set once at the first attempt (Infinity when no
+ // AsyncTimeout is configured, so the clamp below is always a no-op).
+ const deadline = tmoCfg ? now + tmoCfg.timeout : Infinity;
+ const { land, timedOut } = clampToDeadline(tick, landTicks, deadline);
+ B.if++; B.pend.push({ land, ok: f.ok, attempt: 0, bh: !!bulk, start: now, deadline, timedOut });
+ spawnDot(dotsB, els.trackB, f.ok ? 'ok' : 'bad');
+ }
+ }
+ updateUI(now, lastFault);
+ tick++;
+ if (now >= scenario.dur) clearInterval(timer);
+ }, TICK);
+ }
+
+ els.scenarios.querySelectorAll('.scenario-btn').forEach((btn) => {
+ btn.addEventListener('click', () => {
+ els.scenarios.querySelectorAll('.scenario-btn').forEach((b) => b.classList.remove('active'));
+ btn.classList.add('active');
+ selectedScenario = config.scenarios.find((s) => s.id === btn.dataset.scenario);
+ els.play.disabled = false;
+ els.scenLabel.textContent = 'Scenario: ' + selectedScenario.label;
+ els.note.textContent = "Faithful model of httpware's " + describeChain(selectedScenario.chainB) +
+ ' — not httpware running in your browser.';
+ brk = null; bulk = null; retryCfg = null; budget = null; budgetExhausted = false;
+ tmoCfg = null; timedOutCount = 0;
+ setupOutageBar(selectedScenario);
+ resetVisual();
+ });
+ });
+ els.play.addEventListener('click', run);
+ els.replay.addEventListener('click', run);
+ // Auto-select the first scenario so first paint shows a coherent ready-to-play
+ // state (correct flow-diagram boxes, Play enabled) instead of bare "—" placeholders.
+ const firstScenarioBtn = els.scenarios.querySelector('.scenario-btn');
+ if (firstScenarioBtn) firstScenarioBtn.click();
+ }
+
+ return { mount, _models: { makeCircuitBreaker, makeRetryBudget, makeBulkhead }, _util: { mulberry }, REAL, TICK, ADV };
+})();
diff --git a/docs/demos/full-stack.md b/docs/demos/full-stack.md
new file mode 100644
index 0000000..77aab6a
--- /dev/null
+++ b/docs/demos/full-stack.md
@@ -0,0 +1,39 @@
+# Full stack: composing the patterns
+
+Real clients don't use one pattern — they compose. The recommended order is
+`AsyncTimeout -> AsyncCircuitBreaker -> AsyncBulkhead -> AsyncRetry -> terminal`.
+Here a nasty multi-phase incident hits both clients; watch the layers interlock.
+
+
+
+
diff --git a/docs/demos/index.md b/docs/demos/index.md
new file mode 100644
index 0000000..0add4a5
--- /dev/null
+++ b/docs/demos/index.md
@@ -0,0 +1,15 @@
+# Resilience demos
+
+Interactive, self-contained walk-throughs of each resilience pattern under load.
+Each runs a plain client and an httpware client through the **same** outage, side by
+side, and pauses to point out exactly what changes.
+
+- [Circuit Breaker](circuit-breaker.md) — stop hammering a dead backend
+- [Retry + Budget](retry.md) — rescue blips without causing a storm
+- [Bulkhead](bulkhead.md) — contain one slow dependency
+- [Timeout](timeout.md) — bound total latency across retries
+- [Full stack](full-stack.md) — how they compose
+
+!!! note
+ These are a faithful **model** of httpware's behavior for teaching, not httpware
+ running in your browser. See [Resilience](../resilience.md) for the real API.
diff --git a/docs/demos/retry.md b/docs/demos/retry.md
new file mode 100644
index 0000000..c58eb30
--- /dev/null
+++ b/docs/demos/retry.md
@@ -0,0 +1,44 @@
+# Retry + Retry Budget
+
+A transient blip should be retried — but a *sustained* outage retried blindly turns
+one failure into a retry storm that amplifies the outage. httpware retries with
+full-jitter backoff, and a **budget** caps the share of traffic spent on retries so
+a dead backend can't be amplified.
+
+
+
+
diff --git a/docs/demos/timeout.md b/docs/demos/timeout.md
new file mode 100644
index 0000000..486888a
--- /dev/null
+++ b/docs/demos/timeout.md
@@ -0,0 +1,33 @@
+# Timeout (total deadline)
+
+`httpx2`'s per-call timeouts bound a single request — but a retry loop with backoff
+can still run for many seconds in total. `AsyncTimeout` bounds the **whole** operation,
+including every retry and every backoff sleep, so one call can't blow your latency SLA.
+
+
+
+
diff --git a/docs/resilience.md b/docs/resilience.md
index e631046..40602a5 100644
--- a/docs/resilience.md
+++ b/docs/resilience.md
@@ -8,6 +8,10 @@
A key ordering constraint: `AsyncBulkhead` must sit outside `AsyncRetry` (before it in `middleware=`) so one slot covers all retry attempts of a single call. For the full recommended ordering across all four primitives, see [Composition](#composition). Reach for the [Middleware guide](middleware.md) when you want to write your own resilience policy.
+!!! tip "See it under load"
+ New to these patterns? The [interactive demos](demos/index.md) show each one
+ surviving an outage side by side with an unprotected client.
+
- [`AsyncRetry`](#asyncretry)
- [`RetryBudget`](#retrybudget)
- [`AsyncBulkhead`](#asyncbulkhead)
diff --git a/mkdocs.yml b/mkdocs.yml
index 93782a5..a932049 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,6 +7,13 @@ edit_uri: edit/main/docs/
nav:
- Quick-Start: index.md
- Resilience: resilience.md
+ - Demos:
+ - Overview: demos/index.md
+ - Retry: demos/retry.md
+ - Circuit Breaker: demos/circuit-breaker.md
+ - Bulkhead: demos/bulkhead.md
+ - Timeout: demos/timeout.md
+ - Full stack: demos/full-stack.md
- Errors: errors.md
- Observability: observability.md
- Decoders: decoders.md
@@ -49,6 +56,10 @@ theme:
extra_css:
- css/brand.css
+ - demos/demos.css
+
+extra_javascript:
+ - demos/engine.js
validation:
omitted_files: warn
diff --git a/planning/changes/2026-07-18.02-resilience-demo-pages.md b/planning/changes/2026-07-18.02-resilience-demo-pages.md
new file mode 100644
index 0000000..921a9c9
--- /dev/null
+++ b/planning/changes/2026-07-18.02-resilience-demo-pages.md
@@ -0,0 +1,87 @@
+---
+summary: Shipped five interactive browser demo pages (circuit breaker, retry+budget, bulkhead, timeout, full-stack) plus a shared vanilla-JS engine modeling httpware's resilience patterns under load, in the docs Demos section.
+---
+
+# Design: Interactive resilience demo pages
+
+## Summary
+
+Add a **Demos** section to the docs site: five self-contained, browser-based pages
+that animate httpware's resilience patterns under a load/failure scenario, so a
+reader viscerally sees the failure each pattern prevents. One page per pattern
+(Retry + RetryBudget, Bulkhead, CircuitBreaker, AsyncTimeout) plus a composed
+full-stack page. Each is a guided walk-through: two clients (plain vs httpware)
+run the same seeded outage side by side; the animation freezes at key beats and a
+spotlight callout points at the exact number to watch. Pure static assets — no new
+Python dependency, no JS toolchain.
+
+## Motivation
+
+The resilience suite is httpware's flagship capability, but `docs/resilience.md`
+explains it in prose. Prose is weak at conveying *why* — that a dead backend drowns
+an unprotected client in hanging requests, that unbounded retries amplify an outage
+into a storm, that a bulkhead rejects rather than queues. A short animated
+before/after makes the motivation immediate in a way text cannot.
+
+## Design
+
+**Shared engine, thin pages.** One vanilla-JS `docs/demos/engine.js` owns everything:
+a fixed-step virtual clock, a seeded PRNG, a backend/fault model, one small model
+class per pattern (mirroring httpware's real semantics), the flow-diagram + counters
+renderer, and the guided-tour driver (spotlight cutout + side-placed callout with
+auto-flip and an arrow). Each page is a markdown file holding a mount `
` and a
+small config object — which middleware are in the chain, the scenario's fault
+schedule, the ordered tour stops, and which numbers each stop highlights. `engine.js`
+loads via `extra_javascript` in `mkdocs.yml`; a **Demos** nav section lists the five
+pages and `resilience.md` cross-links them.
+
+**Interaction (validated via prototype).** Side-by-side lanes: a plain client and an
+httpware client driven by the *same* seeded fault timeline, so the difference is the
+pattern, not luck. Requests render as tick-driven dots (green/red/grey) that truly
+freeze when paused. Press-play runs to the first stop; each stop dims the page except
+the element(s) to watch, anchors a callout in the adjacent open space, and resumes on
+Continue. Themes off mkdocs-material's CSS variables + `brand.css` (light/dark).
+`prefers-reduced-motion` falls back to stepped updates; outcomes never rely on color
+alone.
+
+**Per-page scenarios:** Retry blip/brownout (budget caps the retry storm); Bulkhead
+slow-dependency (semaphore rejects fast vs unbounded starvation); CircuitBreaker
+hard-down 6s (trip → fast-fail → single-probe recovery); AsyncTimeout stacked
+retry+backoff (total deadline bounds wall-clock); Full-stack multi-phase incident
+composed `Timeout → CircuitBreaker → Bulkhead → Retry`.
+
+**Two settled decisions.** Coach-marks are **hand-rolled** (~60 lines, proven in the
+prototype) rather than vendoring driver.js — zero third-party asset in a Python repo,
+fully in our control. Fidelity to httpware's real defaults is kept by a
+**source-of-truth comment** at the top of `engine.js` (citing
+`architecture/resilience.md`) plus PR review — the pattern constants (budget ratio,
+`window_seconds=30`, `minimum_calls=20`, 500–599 failure range, thresholds) live in
+one block so review has a single place to check. No automated drift guard (see Risk).
+
+## Non-goals
+
+- Not running real httpware in the browser — the engine is a faithful *model*, and
+ every page says so.
+- No sandbox sliders — guided on/off + preset scenarios only, to keep the point sharp.
+- No JS test runner — a JS toolchain is out of scope for a pure-Python repo.
+- `architecture/` is unchanged: this adds docs, not a capability. Only
+ `docs/resilience.md` gains cross-links.
+
+## Testing
+
+`mkdocs build --strict` passes (pages resolve, nav valid, no broken links). Manual
+check: each page loads under mkdocs-material light and dark, the walk-through steps
+through every stop with the callout beside (never over) the highlighted element, and
+`prefers-reduced-motion` degrades gracefully.
+
+## Risk
+
+- **Fidelity drift (medium likelihood, medium impact).** With no automated guard, a
+ future change to a resilience default won't fail any demo test. Mitigation: the
+ single constants block + citing comment; revisit and add the Python parity test if
+ drift is observed.
+- **Maintenance of hand-rolled coach-marks (low × low).** We own edge cases (resize,
+ odd viewports, focus handling). Mitigation: the logic is small and centralized;
+ driver.js remains a drop-in fallback if it proves fragile.
+- **Scope creep on the full-stack page (low × medium).** Composing four patterns can
+ get busy. Mitigation: same template, reuse the four validated single-pattern stops.