fix!: errors and redaction (pickling, query masking, DecodeError message, read-only STATUS_TO_EXCEPTION) (#166)

* fix: keep notes and attributes when pickling or copying any ClientError

One __reduce__ on ClientError rebuilds from args without calling __init__
and restores __dict__, replacing _KeywordReduceMixin and the StatusError
reconstructor. add_note() notes and user-set attributes now survive pickle,
copy.copy and copy.deepcopy for every error class.

* fix!: make STATUS_TO_EXCEPTION read-only

STATUS_TO_EXCEPTION is now a types.MappingProxyType. Code that assigned to
it to remap a status now gets TypeError; catch the error in a middleware
and raise your own class instead.

* fix: mask every query value in error messages and events

redact_url now replaces the value of every query and fragment parameter
with REDACTED and keeps the keys, instead of masking an allowlist of
sensitive names, so presigned-URL signatures and other unlisted secrets
no longer reach messages, reprs, log records or span events. Userinfo is
cut at the last @ so a raw password containing @ is stripped whole.

* fix: keep body content out of the DecodeError message

The message is now 'failed to decode response into <model>: <type>' with
the error count appended when the original exception has error_count().
A non-class model such as X | None is shown by repr, which stops the
AttributeError on Python 3.11 to 3.13. exc.original is unchanged.

* fix: let phase decorator reprs handle callables without __qualname__

repr() of a middleware built by before_request, after_response, on_error
or their async siblings no longer raises AttributeError for a
functools.partial or a callable instance; it falls back to repr(f).

* docs: describe redaction as masking every query value

Author: lesnik512

AGENTS.md

@@ -36,9 +36,11 @@ Every module under `src/httpware/` is named for what it does; read it. What a si
   sibling).
 - `errors.py` owns the tree and both construction rules. Status-keyed `StatusError` subclasses take
   a single positional `response` and never define `__init__`; the six non-status subclasses are
-  keyword-only and inherit `__reduce__` from `_KeywordReduceMixin`, whose precondition is enforced
-  by `tests/test_errors.py::test_keyword_reduce_classes_dict_mirrors_their_init_parameters`. Adding
-  a class means picking a side, and both sides are checked.
+  keyword-only. Pickling and copying go through one `__reduce__` on `ClientError`: it rebuilds the
+  instance from `args` without calling `__init__` and restores `__dict__`, so a new class needs no
+  pickling code, only picklable attributes. Adding a class means picking a construction side and
+  adding a case to `_ERROR_FACTORIES` in `tests/test_errors.py`, which an invariant test enforces
+  for every exported error class.
 - `decoders/_resolver.py` is the **single dispatch path** for Seam B: `_DecoderResolver.resolve`
   walks the frozen decoder tuple, raises `MissingDecoderError` *before* the HTTP call when nothing
   claims the model, and returns a `_BoundDecoder` whose `decode` wraps any decoder-side failure as

docs/errors.md

@@ -49,7 +49,7 @@ ClientError                          (catch-all for anything httpware raises)
 
 Only statuses from 400 to 599 raise. Any other status returns the response unchanged.
 
-The numbered rows are exported as `STATUS_TO_EXCEPTION`, a `Mapping[int, type[StatusError]]`, so you can look up a class in code with `STATUS_TO_EXCEPTION.get(404)`. The two fallback rows are not in the mapping.
+The numbered rows are exported as `STATUS_TO_EXCEPTION`, a `Mapping[int, type[StatusError]]`, so you can look up a class in code with `STATUS_TO_EXCEPTION.get(404)`. The two fallback rows are not in the mapping. The mapping is read-only, and assigning to it raises `TypeError`. To raise your own class for a status, catch the httpware error in a middleware and raise yours from it.
 
 ## Catching strategies
 
@@ -112,7 +112,7 @@ exc.response.request.url  # the failing URL (httpx2.URL)
 exc.response.request.method  # the HTTP method
 ```
 
-The exception's `repr` and message strip `user:pass@` userinfo and mask the values of known-sensitive query and URL-fragment parameters (`api_key`, `apikey`, `access_token`, `refresh_token`, `token`, `secret`, `client_secret`, `password`, `passwd`, `pwd`, `auth`, `authorization`, `sig`, `signature`, `key`, `private_key`, `session`, `sessionid`, `x-api-key`) as `REDACTED`, keeping the keys. Values under other names are left as they are, so avoid putting other secrets in query strings. Request headers such as `Authorization` and `Cookie` are never redacted, and `exc.response.request.headers` returns them in full.
+The exception's `repr` and message strip `user:pass@` userinfo and replace every query-parameter value with `REDACTED`, keeping the keys, so `?page=2&X-Amz-Signature=abc` shows as `?page=REDACTED&X-Amz-Signature=REDACTED`. Fragment values get the same treatment, and a fragment without `=`, like `#section-3`, is kept. The unredacted URL is still on `exc.response.request.url`. Request headers such as `Authorization` and `Cookie` are never redacted, and `exc.response.request.headers` returns them in full.
 
 ## Resilience-error payloads
 
@@ -149,19 +149,20 @@ Fields:
 - `model: type`: the type passed as `response_model=`.
 - `original: BaseException`: the decoder's own exception, such as `pydantic.ValidationError`, `msgspec.ValidationError` or `msgspec.DecodeError`. It is also `exc.__cause__`.
 
+The message names the model and the type of `original`, and adds the error count when `original` has an `error_count()` method, as `pydantic.ValidationError` does:
+
+    failed to decode response into User: ValidationError (2 errors)
+
+A model that is not a class, such as `User | None` or `list[User]`, appears as its `repr`. The message never quotes the body. `str(exc.original)` can: a pydantic `ValidationError` echoes the input values it rejected, so check what it holds before you log it.
+
 ```python
 from httpware import AsyncClient, DecodeError
 
 
 try:
     user = await client.get("/users/1", response_model=User)
 except DecodeError as exc:
-    _LOGGER.error(
-        "decode failed for %s into %s: %s",
-        exc.response.request.url,
-        exc.model.__name__,
-        exc.original,
-    )
+    _LOGGER.error("%s", exc)
     raise
 ```
 

docs/middleware.md

@@ -13,7 +13,7 @@ Middleware is for behavior that applies to every call through a client. Other ca
 - Side effects that don't need httpware's exceptions or chain order, including on post-redirect hops: use `event_hooks` on an `httpx2` client you build yourself and pass as `httpx2_client=`. Middleware and phase decorators run in the httpware chain, see httpware exceptions, and compose with `AsyncRetry` and `AsyncBulkhead`. `event_hooks` run a layer below, on every transport attempt. That is also why `httpware` refuses `event_hooks=` as a client option: an `httpx2.HTTPStatusError` raised in a hook (say, by `raise_for_status()`) reaches the chain as a plain `TransportError` instead of a `StatusError`, so `AsyncRetry` never retries it and the circuit breaker never counts it.
 - URL or header validation: `httpx2` already does it.
 - Creating HTTP spans for tracing: install `opentelemetry-instrumentation-httpx`, which already traces every transport call. See [Observability](observability.md).
-- Redaction: httpware redacts URLs before they reach logs, telemetry, and error messages. It strips `user:pass@` userinfo and masks the values of sensitive query and fragment parameters ([Errors](errors.md#excresponse-access-pattern) lists them). It does not touch headers or bodies, so if your middleware logs those, redact them yourself, for example with a `logging.Filter`.
+- Redaction: httpware redacts URLs before they reach logs, telemetry, and error messages. It strips `user:pass@` userinfo and replaces every query and fragment parameter value with `REDACTED`, keeping the keys ([Errors](errors.md#excresponse-access-pattern) has an example). It does not touch headers or bodies, so if your middleware logs those, redact them yourself, for example with a `logging.Filter`.
 
 ## Writing your own
 

docs/observability.md

@@ -13,6 +13,8 @@ The logger and event names below are a stable public contract:
 
 Each log record has an `event` field holding the event name, such as `event="circuit.opened"`, which you can filter on in your log aggregator. Events from `AsyncKeyedCircuitBreaker` and `KeyedCircuitBreaker` also carry `circuit_key`, the circuit they belong to. [Resilience](resilience.md) describes when each event fires.
 
+Events that carry a `url` attribute get it redacted first: httpware strips `user:pass@` userinfo and replaces every query-parameter value with `REDACTED`, keeping the keys. A URL logged as `https://api.test/items?page=REDACTED&sort=REDACTED` came from `https://api.test/items?page=2&sort=name`.
+
 ```python
 import logging
 

src/httpware/_internal/observability.py

@@ -26,7 +26,7 @@ def _emit_event(
 
     The ``url`` attribute, when present, is run through
     ``redaction.redact_url`` here — at the single emission boundary — so a
-    request URL's userinfo and known-sensitive query/fragment secrets never
+    request URL's userinfo and query/fragment parameter values never
     reach a log record or span event, regardless of how a caller built the
     attributes dict.
 

src/httpware/_internal/redaction.py

@@ -1,50 +1,19 @@
 """URL sanitation for logs, telemetry, and error messages.
 
-Strips ``user:pass@`` userinfo and masks the values of known-sensitive query
-parameters so secrets embedded in URLs do not leak into observability output.
-Shared by ``errors.py`` (StatusError messages) and the resilience middleware
-(event attributes).
+Strips ``user:pass@`` userinfo and masks every query and fragment parameter
+value, keeping the keys, so secrets embedded in URLs do not leak into
+observability output. Shared by ``errors.py`` (StatusError messages) and
+``observability._emit_event`` (event attributes).
 """
 
-from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+from urllib.parse import urlsplit, urlunsplit
 
 
-SENSITIVE_QUERY_KEYS = frozenset(
-    {
-        "api_key",
-        "apikey",
-        "access_token",
-        "refresh_token",
-        "token",
-        "secret",
-        "client_secret",
-        "password",
-        "passwd",
-        "pwd",
-        "auth",
-        "authorization",
-        "sig",
-        "signature",
-        "key",
-        "private_key",
-        "session",
-        "sessionid",
-        "x-api-key",
-    }
-)
-
 _REDACTED = "REDACTED"
 
 
 def _reassemble(scheme: str, netloc: str, path: str, query: str, fragment: str) -> str:
-    """Like ``urlunsplit``, but avoid the spurious triple-slash for an empty authority.
-
-    ``urlunsplit(("http", "", "/path", ...))`` yields ``http:///path`` for a
-    netloc-using scheme. When userinfo stripping leaves no host (e.g.
-    ``http://user:pass@/path``) we want ``http:/path`` (scheme + path), not a
-    triple-slash. With a non-empty netloc this delegates to ``urlunsplit``, so
-    normal URLs are byte-identical.
-    """
+    """Like ``urlunsplit``, but return ``scheme:path`` rather than ``scheme:///path`` for an empty authority."""
     if netloc:
         return urlunsplit((scheme, netloc, path, query, fragment))
     tail = path
@@ -61,56 +30,32 @@ def _strip_userinfo(url: str) -> str:
     parts = urlsplit(url)
     if parts.username is None and parts.password is None:
         return url
-    # Strip the "user:pass@" prefix from the raw netloc to preserve host:port
-    # exactly (including IPv6 brackets), rather than reconstructing from parts.
-    netloc = parts.netloc.split("@", 1)[1] if "@" in parts.netloc else parts.netloc
+    netloc = parts.netloc.rpartition("@")[2]
     return _reassemble(parts.scheme, netloc, parts.path, parts.query, parts.fragment)
 
 
-def _mask_component(component: str) -> tuple[str, bool]:
-    """Mask sensitive key=value pairs in a query or fragment string.
-
-    Returns ``(masked_component, was_changed)``; when no sensitive key is
-    found the original string is returned unchanged (``was_changed=False``).
-    """
-    pairs = parse_qsl(component, keep_blank_values=True)
-    if not any(key.strip().lower() in SENSITIVE_QUERY_KEYS for key, _ in pairs):
-        return component, False
-    masked = [(key, _REDACTED if key.strip().lower() in SENSITIVE_QUERY_KEYS else value) for key, value in pairs]
-    return urlencode(masked), True
+def _mask_component(component: str) -> str:
+    """Replace the value of every ``key=value`` pair with ``REDACTED``; a component without ``=`` is kept."""
+    if "=" not in component:
+        return component
+    return "&".join(
+        key + "=" + _REDACTED if sep else key for key, sep, _ in (pair.partition("=") for pair in component.split("&"))
+    )
 
 
 def _mask_query(url: str) -> str:
-    parts = urlsplit(url)
-    has_query = bool(parts.query)
-    has_fragment = bool(parts.fragment)
-
-    if not has_query and not has_fragment:
+    if "=" not in url:
         return url
-
-    new_query = parts.query
-    new_fragment = parts.fragment
-    changed = False
-
-    if has_query:
-        new_query, q_changed = _mask_component(parts.query)
-        changed = changed or q_changed
-
-    if has_fragment:
-        new_fragment, f_changed = _mask_component(parts.fragment)
-        changed = changed or f_changed
-
-    if not changed:
-        return url  # common-path guard: nothing sensitive, leave bytes untouched
-
-    return _reassemble(parts.scheme, parts.netloc, parts.path, new_query, new_fragment)
+    rest, hash_sign, fragment = url.partition("#")
+    base, question_mark, query = rest.partition("?")
+    return base + question_mark + _mask_component(query) + hash_sign + _mask_component(fragment)
 
 
 def redact_url(url: str) -> str:
-    """Return ``url`` safe for logs/telemetry/errors.
+    """Return ``url`` safe for logs, telemetry and error messages.
 
-    Userinfo is stripped and the values of known-sensitive query parameters are
-    replaced with ``REDACTED`` (keys preserved). URLs with no sensitive query
-    key are returned byte-identical to the userinfo-stripped input.
+    Userinfo is stripped and every query and fragment parameter value is
+    replaced with ``REDACTED``, keeping the keys as written. A fragment with no
+    ``=`` in it, such as ``#section-3``, is kept as it is.
     """
     return _mask_query(_strip_userinfo(url))