| |
| """Round-count circuit breaker of the remote drafter (CONTRACT 10). torch-free. |
| |
| closed every round may use the network; consecutive failed attempts are counted. |
| open after ``trip`` consecutive failed attempts: the next ``cooldown`` rounds do not |
| use the network. They fail fast exactly like a round without a connection |
| (capacity: zero drafts; resilience: the local drafter; shadow: no comparison). |
| half_open after the cooldown: the next round that sends a STEP is a probe. Success |
| closes the breaker; failure opens it again for another ``cooldown`` rounds. |
| |
| Outcomes come only from rounds that sent a STEP: a failed attempt is a STEP that failed |
| (timeout, transport error, refused or frame-error reply) or whose requests that needed |
| drafts all failed. Rounds without a connection, or with nothing to send, are neutral. |
| Transport failures also keep the client's wall-clock reconnect backoff (client.py); the |
| breaker bounds what a worker that answers but keeps failing costs (one RTT, or one |
| deadline, per engine round otherwise). ``trip`` 0 turns the breaker off. |
| |
| One instance per rank-0 round; touched only by the thread that runs the rounds. |
| """ |
|
|
| from __future__ import annotations |
|
|
|
|
| class CircuitBreaker: |
| def __init__(self, trip: int, cooldown: int): |
| if trip < 0 or cooldown < 1: |
| raise ValueError(f"trip {trip} must be >= 0 and cooldown {cooldown} >= 1") |
| self.trip = trip |
| self.cooldown = cooldown |
| self.state = "closed" |
| self.failures = 0 |
| self.left = 0 |
| self.trips = 0 |
|
|
| def allow(self) -> bool: |
| """Once per round, before any network use: may this round send a STEP?""" |
| if self.state != "open": |
| return True |
| self.left -= 1 |
| if self.left <= 0: |
| self.state = "half_open" |
| return False |
|
|
| def record(self, ok: bool) -> str | None: |
| """Outcome of a round that sent a STEP. Returns "tripped" or "recovered" on a |
| transition, else None.""" |
| if self.trip == 0: |
| return None |
| if ok: |
| was = self.state |
| self.state, self.failures = "closed", 0 |
| return "recovered" if was == "half_open" else None |
| self.failures += 1 |
| if self.state == "half_open" or self.failures >= self.trip: |
| self.state, self.left = "open", self.cooldown |
| self.trips += 1 |
| return "tripped" |
| return None |
|
|
| def snapshot(self) -> dict: |
| return {"state": self.state, "consecutive_failures": self.failures, |
| "cooldown_left": self.left if self.state == "open" else 0, |
| "trips": self.trips, "trip": self.trip, "cooldown": self.cooldown} |
|
|
