Deployed dfd6f55 with MkDocs version: 1.6.1

index.html

@@ -1028,18 +1028,47 @@ <h2 id="errors">Errors<a class="headerlink" href="#errors" title="Permanent link
 <ul>
 <li><strong>Status errors</strong> (4xx/5xx responses) — raised automatically, no <code>raise_for_status()</code> needed: <code>NotFoundError</code>, <code>RateLimitedError</code>, <code>ServiceUnavailableError</code>, and the rest. All subclass <code>StatusError</code>.</li>
 <li><strong>Transport errors</strong> — connection / network / protocol failures before a response arrived. <code>NetworkError</code> (transient) subclasses <code>TransportError</code>.</li>
-<li><strong>Resilience refusals</strong> — <code>RetryBudgetExhaustedError</code> and <code>BulkheadFullError</code>, raised by the resilience middleware.</li>
+<li><strong>Resilience refusals</strong> — <code>RetryBudgetExhaustedError</code>, <code>BulkheadFullError</code>, and <code>CircuitOpenError</code>, raised by the resilience middleware.</li>
 <li><strong>Decode errors</strong> — <code>DecodeError</code>, raised when <code>response_model=</code> decoding fails (HTTP call itself succeeded). <code>MissingDecoderError</code>, raised when no registered decoder claims the <code>response_model=</code> type — fires <em>before</em> the HTTP call.</li>
 </ul>
 <p>See the <a href="errors/">Errors reference</a> for the full tree and catching strategies.</p>
 <h2 id="observability">Observability<a class="headerlink" href="#observability" title="Permanent link">&para;</a></h2>
-<p><code>AsyncRetry</code>/<code>Retry</code> and <code>AsyncBulkhead</code>/<code>Bulkhead</code> emit operational events via two channels — stdlib <code>logging</code> records (always on) and OpenTelemetry span events (when <code>opentelemetry-api</code> is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.</p>
-<p>Logger names (<code>httpware.retry</code>, <code>httpware.bulkhead</code>) and event names (<code>retry.giving_up</code>, <code>retry.budget_refused</code>, <code>retry.streaming_refused</code>, <code>bulkhead.rejected</code>) are the stable public contract.</p>
+<p>All resilience middleware emit operational events via two channels — stdlib <code>logging</code> records (always on) and OpenTelemetry span events (when <code>opentelemetry-api</code> is installed). Event names and payloads are identical across sync and async; dashboards built against one class apply unchanged to the other.</p>
+<p>Logger names and event names are the stable public contract:</p>
+<table>
+<thead>
+<tr>
+<th>Logger</th>
+<th>Events</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>httpware.retry</code></td>
+<td><code>retry.giving_up</code>, <code>retry.budget_refused</code>, <code>retry.streaming_refused</code></td>
+</tr>
+<tr>
+<td><code>httpware.bulkhead</code></td>
+<td><code>bulkhead.rejected</code></td>
+</tr>
+<tr>
+<td><code>httpware.circuit_breaker</code></td>
+<td><code>circuit.opened</code> (WARNING), <code>circuit.rejected</code> (WARNING), <code>circuit.half_open</code> (INFO), <code>circuit.closed</code> (INFO)</td>
+</tr>
+<tr>
+<td><code>httpware.timeout</code></td>
+<td><code>timeout.exceeded</code> (WARNING)</td>
+</tr>
+</tbody>
+</table>
+<p>Each log record carries an <code>event</code> field with the event-name string (e.g. <code>event="circuit.opened"</code>), usable for log-aggregator filtering. See <a href="resilience/">resilience.md</a> for the full event tables per middleware.</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-8-1" name="__codelineno-8-1" href="#__codelineno-8-1"></a><span class="kn">import</span><span class="w"> </span><span class="nn">logging</span>
 <a id="__codelineno-8-2" name="__codelineno-8-2" href="#__codelineno-8-2"></a>
-<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="c1"># Enable visibility into retry / bulkhead operational events</span>
+<a id="__codelineno-8-3" name="__codelineno-8-3" href="#__codelineno-8-3"></a><span class="c1"># Enable visibility into resilience operational events</span>
 <a id="__codelineno-8-4" name="__codelineno-8-4" href="#__codelineno-8-4"></a><span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;httpware.retry&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">)</span>
 <a id="__codelineno-8-5" name="__codelineno-8-5" href="#__codelineno-8-5"></a><span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;httpware.bulkhead&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">)</span>
+<a id="__codelineno-8-6" name="__codelineno-8-6" href="#__codelineno-8-6"></a><span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;httpware.circuit_breaker&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>  <span class="c1"># INFO for recovery events</span>
+<a id="__codelineno-8-7" name="__codelineno-8-7" href="#__codelineno-8-7"></a><span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s2">&quot;httpware.timeout&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">WARNING</span><span class="p">)</span>
 </code></pre></div>
 <p>For OTel attribute enrichment on the active span — install the extra:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-9-1" name="__codelineno-9-1" href="#__codelineno-9-1"></a>pip<span class="w"> </span>install<span class="w"> </span>httpware<span class="o">[</span>otel<span class="o">]</span>

resilience/index.html

@@ -1469,9 +1469,7 @@ <h2 id="asyncretry"><code>AsyncRetry</code><a class="headerlink" href="#asyncret
 </tr>
 </tbody>
 </table>
-<p>For a whole-attempt wall-clock bound, use <code>httpx2.Timeout</code> on the client or
-pass <code>timeout=</code> per request. <code>httpware</code> does not own a structured-cancellation
-timeout knob.</p>
+<p>For a whole-operation wall-clock bound across all retry attempts, compose <code>AsyncTimeout</code> outermost — see <a href="#asynctimeout">AsyncTimeout</a> below. For a per-request bound, use <code>httpx2.Timeout</code> on the client or pass <code>timeout=</code> per request.</p>
 <h3 id="retry-after-parsing">Retry-After parsing<a class="headerlink" href="#retry-after-parsing" title="Permanent link">&para;</a></h3>
 <p><code>Retry-After</code> is parsed as either:
 - <strong>Integer seconds</strong> — <code>Retry-After: 30</code> → sleep 30s (clamped to <code>max_delay</code>)
@@ -1592,7 +1590,7 @@ <h2 id="asynccircuitbreaker-circuitbreaker"><code>AsyncCircuitBreaker</code> / <
 <h3 id="states">States<a class="headerlink" href="#states" title="Permanent link">&para;</a></h3>
 <ul>
 <li><strong>CLOSED</strong> — normal operation. Each counted failure increments the consecutive-failure counter. Once <code>failure_threshold</code> consecutive counted failures accumulate, the circuit opens.</li>
-<li><strong>OPEN</strong> — fast-fail. All requests are rejected immediately with <code>CircuitOpenError</code> (carrying <code>retry_after</code> seconds until the next probe window). After <code>reset_timeout</code> seconds the circuit moves to HALF_OPEN.</li>
+<li><strong>OPEN</strong> — fast-fail. While elapsed time is below <code>reset_timeout</code>, requests are rejected immediately with <code>CircuitOpenError</code> (carrying <code>retry_after</code> seconds until the next probe window). The first request after <code>reset_timeout</code> elapses transitions the circuit to HALF_OPEN and becomes the probe.</li>
 <li><strong>HALF_OPEN</strong> — exactly one probe is admitted. If <code>success_threshold</code> consecutive probe successes are observed, the circuit closes. A single probe failure re-opens the circuit.</li>
 </ul>
 <h3 id="constructor">Constructor<a class="headerlink" href="#constructor" title="Permanent link">&para;</a></h3>
@@ -1807,7 +1805,7 @@ <h3 id="retry"><code>Retry</code><a class="headerlink" href="#retry" title="Perm
 </tbody>
 </table>
 <p><code>Retry</code> uses <code>time.sleep</code> between attempts. <code>Retry-After</code>, streaming-body refusal, exhaustion behavior, and <code>RetryBudgetExhaustedError</code> semantics are identical to <code>AsyncRetry</code>.</p>
-<p>For a whole-attempt wall-clock bound, use <code>httpx2.Timeout</code> on the wrapped client or pass <code>timeout=</code> per request. <code>httpware</code> does not own a structured-cancellation timeout knob.</p>
+<p>For a whole-attempt wall-clock bound, use <code>httpx2.Timeout</code> on the wrapped client or pass <code>timeout=</code> per request. No sync <code>Timeout</code> middleware exists — sync Python has no cancellation primitive that can interrupt a blocking call mid-flight.</p>
 <h3 id="bulkhead"><code>Bulkhead</code><a class="headerlink" href="#bulkhead" title="Permanent link">&para;</a></h3>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-15-1" name="__codelineno-15-1" href="#__codelineno-15-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">httpware.middleware.resilience</span><span class="w"> </span><span class="kn">import</span> <span class="n">Bulkhead</span>
 </code></pre></div>