refactor(errors): collapse per-exception reconstruct/reduce boilerplate with _KeywordReduceMixin

Replace six hand-repeated _reconstruct_X functions and __reduce__ methods
with a single _KeywordReduceMixin that pickles via self.__dict__. Updates
architecture/errors.md with the pickling invariant. Pure refactor, no
behavior change; all 775 tests pass with 100% coverage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: lesnik512

architecture/errors.md

@@ -18,6 +18,8 @@ The error-mapping table (what `httpx2` exception maps to which `httpware` except
 
 The "no `__init__` override" rule scopes only to `StatusError` subclasses. Non-status `ClientError` subclasses — `DecodeError`, `MissingDecoderError`, `BulkheadFullError`, `RetryBudgetExhaustedError`, `CircuitOpenError`, `ResponseTooLargeError` — deliberately define `__init__` with keyword-only fields.
 
+These six non-status `ClientError` subclasses inherit `__reduce__` from `_KeywordReduceMixin`, which pickles via `self.__dict__`. This requires `self.__dict__` to exactly mirror the `__init__` keyword parameters — do not store any additional derived attribute on these classes without also updating `__init__`'s parameters, or pickling will silently drop it.
+
 `ResponseTooLargeError` is raised when `max_response_body_bytes` is set and a response body would exceed the cap — status-agnostic (a `200` can trip it), counting **decoded** bytes. It fires from the non-streaming terminal (`send()`) and from `stream()`'s internal error pre-read; user-driven `stream()` iteration is never capped. The `reason` field discriminates the two trip modes: `"declared"` (the declared `Content-Length` already exceeds the cap, rejected before any byte is read — `content_length` holds it) and `"streamed"` (the decoded body crossed the cap mid-read, the chunked or compression-bomb case, where the true size is unknown by design). It is a non-status `ClientError`; it does not carry a `StatusError`-style positional `response` and is not in `STATUS_TO_EXCEPTION`. Because it is neither a `StatusError`, `NetworkError`, nor `TimeoutError`, it is not retried and does not count toward the circuit breaker.
 
 ## Security: request headers are reachable via `exc.response.request`

src/httpware/errors.py

@@ -136,16 +136,26 @@ class ServiceUnavailableError(ServerStatusError):
 }
 
 
-def _reconstruct_budget_exhausted(
-    cls: "type[RetryBudgetExhaustedError]",
-    last_response: httpx2.Response | None,
-    last_exception: BaseException | None,
-    attempts: int,
-) -> "RetryBudgetExhaustedError":
-    return cls(last_response=last_response, last_exception=last_exception, attempts=attempts)
+def _reconstruct_kwonly(cls: type, kwargs: dict[str, Any]) -> Any:  # noqa: ANN401
+    return cls(**kwargs)
 
 
-class RetryBudgetExhaustedError(ClientError):
+class _KeywordReduceMixin:
+    """Shared __reduce__ for keyword-only ClientError subclasses.
+
+    For subclasses whose __init__ is keyword-only and whose instance
+    __dict__ exactly mirrors it. Do not add this mixin to a class that
+    stores any attribute beyond its __init__'s keyword parameters —
+    reconstruction replays self.__dict__ as keyword arguments, so an
+    extra/derived attribute would either be silently dropped or raise a
+    TypeError on unpickle.
+    """
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (_reconstruct_kwonly, (type(self), self.__dict__))
+
+
+class RetryBudgetExhaustedError(_KeywordReduceMixin, ClientError):
     """Raised when a retry was needed but the RetryBudget refused to permit it.
 
     Carries the last response and/or exception observed before the budget refused,
@@ -168,22 +178,8 @@ def __init__(
         self.attempts = attempts
         super().__init__(f"retry budget exhausted after {attempts} attempt(s)")
 
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (
-            _reconstruct_budget_exhausted,
-            (type(self), self.last_response, self.last_exception, self.attempts),
-        )
-
-
-def _reconstruct_bulkhead_full(
-    cls: "type[BulkheadFullError]",
-    max_concurrent: int,
-    acquire_timeout: float | None,
-) -> "BulkheadFullError":
-    return cls(max_concurrent=max_concurrent, acquire_timeout=acquire_timeout)
 
-
-class BulkheadFullError(ClientError):
+class BulkheadFullError(_KeywordReduceMixin, ClientError):
     """Raised when ``acquire_timeout`` elapses before an AsyncBulkhead slot becomes available.
 
     Carries the configured caps for caller logging/alerting.
@@ -197,21 +193,8 @@ def __init__(self, *, max_concurrent: int, acquire_timeout: float | None) -> Non
         self.acquire_timeout = acquire_timeout
         super().__init__(f"bulkhead full (max_concurrent={max_concurrent}, acquire_timeout={acquire_timeout})")
 
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (
-            _reconstruct_bulkhead_full,
-            (type(self), self.max_concurrent, self.acquire_timeout),
-        )
-
-
-def _reconstruct_circuit_open(
-    cls: "type[CircuitOpenError]",
-    retry_after: float | None,
-) -> "CircuitOpenError":
-    return cls(retry_after=retry_after)
-
 
-class CircuitOpenError(ClientError):
+class CircuitOpenError(_KeywordReduceMixin, ClientError):
     """Raised when a CircuitBreaker refuses a request because the circuit is not closed.
 
     Fires when the circuit is OPEN, or when it is HALF_OPEN and the single probe
@@ -229,20 +212,8 @@ def __init__(self, *, retry_after: float | None) -> None:
         else:
             super().__init__(f"circuit open (retry_after={retry_after:.3f}s)")
 
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (_reconstruct_circuit_open, (type(self), self.retry_after))
-
-
-def _reconstruct_decode_error(
-    cls: "type[DecodeError]",
-    response: httpx2.Response,
-    model: type,
-    original: BaseException,
-) -> "DecodeError":
-    return cls(response=response, model=model, original=original)
-
 
-class DecodeError(ClientError):
+class DecodeError(_KeywordReduceMixin, ClientError):
     """Raised when the active ResponseDecoder failed to decode response.content.
 
     The HTTP call itself succeeded — status was 2xx/3xx and the transport
@@ -268,12 +239,6 @@ def __init__(
         self.original = original
         super().__init__(f"failed to decode response into {model.__name__}: {original}")
 
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (
-            _reconstruct_decode_error,
-            (type(self), self.response, self.model, self.original),
-        )
-
 
 def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) -> str:
     if not registered_names:
@@ -287,15 +252,7 @@ def _missing_decoder_summary(model: type, registered_names: tuple[str, ...]) ->
     return f"no decoder for response_model={model!r}: {hint}"
 
 
-def _reconstruct_missing_decoder(
-    cls: "type[MissingDecoderError]",
-    model: type,
-    registered_names: tuple[str, ...],
-) -> "MissingDecoderError":
-    return cls(model=model, registered_names=registered_names)
-
-
-class MissingDecoderError(ClientError):
+class MissingDecoderError(_KeywordReduceMixin, ClientError):
     """Raised when response_model= is set but no registered decoder claims the model.
 
     Fires at .send() entry, BEFORE the HTTP call — no point sending a request
@@ -311,21 +268,8 @@ def __init__(self, *, model: type, registered_names: tuple[str, ...]) -> None:
         self.registered_names = registered_names
         super().__init__(_missing_decoder_summary(model, registered_names))
 
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (_reconstruct_missing_decoder, (type(self), self.model, self.registered_names))
-
-
-def _reconstruct_response_too_large(
-    cls: "type[ResponseTooLargeError]",
-    status_code: int,
-    limit: int,
-    content_length: int | None,
-    reason: 'Literal["declared", "streamed"]',
-) -> "ResponseTooLargeError":
-    return cls(status_code=status_code, limit=limit, content_length=content_length, reason=reason)
 
-
-class ResponseTooLargeError(ClientError):
+class ResponseTooLargeError(_KeywordReduceMixin, ClientError):
     """Raised when a response body exceeds the client's max_response_body_bytes cap.
 
     Status-agnostic: fires on any non-streaming send() and on stream()'s internal
@@ -362,9 +306,3 @@ def __init__(
         else:
             detail = f"decoded body exceeded max_response_body_bytes={limit}"
         super().__init__(f"response body too large: status={status_code} {detail}")
-
-    def __reduce__(self) -> tuple[Any, ...]:
-        return (
-            _reconstruct_response_too_large,
-            (type(self), self.status_code, self.limit, self.content_length, self.reason),
-        )