httpware 0.1.0__py3-none-any.whl

httpware/decoders/pydantic.py

@@ -0,0 +1,29 @@
+"""PydanticDecoder — module-level cached TypeAdapter adapter for ResponseDecoder."""
+
+import functools
+from typing import TypeVar
+
+from pydantic import TypeAdapter
+
+
+T = TypeVar("T")
+
+
+@functools.lru_cache(maxsize=1024)
+def _get_adapter(model: type[T]) -> TypeAdapter[T]:
+    return TypeAdapter(model)
+
+
+class PydanticDecoder:
+    """Decode raw response bytes into `model` via a cached `pydantic.TypeAdapter`."""
+
+    def decode(self, content: bytes, model: type[T]) -> T:
+        """Validate `content` as JSON against `model` in a single parse pass."""
+        try:
+            adapter = _get_adapter(model)
+        except TypeError:
+            adapter = TypeAdapter(model)
+        return adapter.validate_json(content)
+
+
+__all__ = ["PydanticDecoder"]

httpware/errors.py

@@ -0,0 +1,194 @@
+"""Status-keyed exception hierarchy with plain typed fields.
+
+Fallback rule: unknown 4xx statuses fall back to ``ClientStatusError``;
+unknown 5xx fall back to ``ServerStatusError``. The fallback assumes
+``400 <= status < 600`` — callers must guard against non-error statuses
+(1xx informational, 2xx success, 3xx redirect) before consulting
+``STATUS_TO_EXCEPTION``. The resolution logic lives at the transport
+seam (Story 1.4); this module only ships the classes and the lookup dict.
+
+``__repr__`` and the summary message passed to ``Exception.__init__``
+strip ``user:pass@`` userinfo from ``request_url`` to avoid leaking
+credentials in tracebacks, log lines, and exception reporters.
+Query-string secrets (e.g. ``?api_key=...``) are NOT stripped here —
+full redaction is the responsibility of the ``Redactor`` middleware
+(Story 5.3).
+"""
+
+import builtins
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+
+def _strip_userinfo(url: str) -> str:
+    """Drop the ``user:pass@`` portion of ``url`` if present."""
+    if "@" not in url or "://" not in url:
+        return url
+    parts = urlsplit(url)
+    if parts.username is None and parts.password is None:
+        return url
+    netloc = parts.hostname or ""
+    if parts.port is not None:
+        netloc = f"{netloc}:{parts.port}"
+    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))
+
+
+def _reconstruct_status_error(
+    cls: "type[StatusError]",
+    status: int,
+    body: bytes,
+    headers: Mapping[str, str],
+    json: Any,  # noqa: ANN401
+    request_method: str,
+    request_url: str,
+) -> "StatusError":
+    """Pickle / copy reconstructor for ``StatusError`` subclasses."""
+    return cls(
+        status=status,
+        body=body,
+        headers=headers,
+        json=json,
+        request_method=request_method,
+        request_url=request_url,
+    )
+
+
+class ClientError(Exception):
+    """Root of the httpware exception tree."""
+
+
+class TransportError(ClientError):
+    """Connection / network / protocol failure raised before a response was received."""
+
+
+class TimeoutError(ClientError, builtins.TimeoutError):  # noqa: A001
+    """Client-side timeout (connect / read / write / pool).
+
+    Inherits from both ``httpware.ClientError`` and ``builtins.TimeoutError``
+    so ``except httpware.TimeoutError`` catches httpware-raised timeouts AND
+    ``except builtins.TimeoutError`` / ``except OSError`` (the form
+    ``asyncio.wait_for`` uses) also catches them. Deliberately shadows
+    ``builtins.TimeoutError``; see Decision 3 in ``docs/architecture.md``.
+    Do not "fix" this name.
+    """
+
+
+class StatusError(ClientError):
+    """Base for HTTP-status-keyed errors with plain typed fields."""
+
+    status: int
+    body: bytes
+    headers: Mapping[str, str]
+    json: Any
+    request_method: str
+    request_url: str
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        body: bytes,
+        headers: Mapping[str, str],
+        json: Any | None,  # noqa: ANN401
+        request_method: str,
+        request_url: str,
+    ) -> None:
+        """Store all six fields and emit a short summary message to ``Exception.__init__``.
+
+        Subclasses overriding ``__init__`` MUST call
+        ``super().__init__(status=..., body=..., headers=..., json=...,
+        request_method=..., request_url=...)`` to register ``args`` and the
+        summary message; otherwise ``str(exc)`` is silently empty.
+        ``headers`` is defensively copied into a read-only ``MappingProxyType``
+        so caller mutations after ``raise`` do not bleed into the exception.
+        """
+        self.status = status
+        self.body = body
+        self.headers = MappingProxyType(dict(headers))
+        self.json = json
+        self.request_method = request_method
+        self.request_url = request_url
+        super().__init__(f"{status} {request_method} {_strip_userinfo(request_url)}")
+
+    def __repr__(self) -> str:
+        cls_name = type(self).__name__
+        safe_url = _strip_userinfo(self.request_url)
+        return f"<{cls_name} status={self.status} method={self.request_method} url={safe_url}>"
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        return (
+            _reconstruct_status_error,
+            (
+                type(self),
+                self.status,
+                self.body,
+                dict(self.headers),
+                self.json,
+                self.request_method,
+                self.request_url,
+            ),
+        )
+
+
+class ClientStatusError(StatusError):
+    """Base for 4xx HTTP status errors."""
+
+
+class ServerStatusError(StatusError):
+    """Base for 5xx HTTP status errors."""
+
+
+class BadRequestError(ClientStatusError):
+    """HTTP 400 Bad Request."""
+
+
+class UnauthorizedError(ClientStatusError):
+    """HTTP 401 Unauthorized."""
+
+
+class ForbiddenError(ClientStatusError):
+    """HTTP 403 Forbidden."""
+
+
+class NotFoundError(ClientStatusError):
+    """HTTP 404 Not Found."""
+
+
+class ConflictError(ClientStatusError):
+    """HTTP 409 Conflict."""
+
+
+class UnprocessableEntityError(ClientStatusError):
+    """HTTP 422 Unprocessable Entity."""
+
+
+class RateLimitedError(ClientStatusError):
+    """HTTP 429 Too Many Requests."""
+
+
+class InternalServerError(ServerStatusError):
+    """HTTP 500 Internal Server Error."""
+
+
+class ServiceUnavailableError(ServerStatusError):
+    """HTTP 503 Service Unavailable."""
+
+
+# Unknown 4xx → ``ClientStatusError``; unknown 5xx → ``ServerStatusError``.
+# Fallback assumes ``400 <= status < 600`` — callers must guard against
+# non-error codes (1xx/2xx/3xx) before consulting this dict. The fallback
+# resolution lives at the call site (Story 1.4 inlines it at the transport
+# seam).
+STATUS_TO_EXCEPTION: Mapping[int, type[StatusError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitedError,
+    500: InternalServerError,
+    503: ServiceUnavailableError,
+}

httpware/middleware/__init__.py

@@ -0,0 +1,89 @@
+"""Middleware protocol — the AsyncClient ↔ Middleware seam (Seam 2)."""
+
+from collections.abc import Awaitable, Callable
+from typing import Protocol, TypeAlias, runtime_checkable
+
+from httpware.request import Request
+from httpware.response import Response
+
+
+Next: TypeAlias = Callable[[Request], Awaitable[Response]]
+
+
+@runtime_checkable
+class Middleware(Protocol):
+    """Structural protocol every middleware satisfies.
+
+    A middleware receives the incoming `Request` and a `Next` callable. It may
+    inspect/transform the request, await `next(request)` to forward to the rest
+    of the chain (eventually the transport), inspect/transform the returned
+    `Response`, short-circuit by returning a `Response` without calling `next`,
+    or raise.
+    """
+
+    async def __call__(self, request: Request, next: Next) -> Response:  # noqa: A002
+        """Process `request`; call `next(request)` to forward, or synthesize a Response."""
+        ...
+
+
+def before_request(f: Callable[[Request], Awaitable[Request]]) -> Middleware:
+    """Wrap an async request transform into a Middleware.
+
+    The decorated function receives the incoming Request and returns a
+    (possibly modified) Request, which is then forwarded down the chain.
+    """
+
+    class _BeforeRequestMiddleware:
+        async def __call__(self, request: Request, next: Next) -> Response:  # noqa: A002
+            return await next(await f(request))
+
+        def __repr__(self) -> str:
+            return f"<before_request({f.__qualname__})>"  # ty: ignore[unresolved-attribute]
+
+    return _BeforeRequestMiddleware()
+
+
+def after_response(f: Callable[[Request, Response], Awaitable[Response]]) -> Middleware:
+    """Wrap an async response transform into a Middleware.
+
+    The decorated function receives the original Request and the Response
+    returned by the chain, and returns a (possibly modified) Response.
+    """
+
+    class _AfterResponseMiddleware:
+        async def __call__(self, request: Request, next: Next) -> Response:  # noqa: A002
+            response = await next(request)
+            return await f(request, response)
+
+        def __repr__(self) -> str:
+            return f"<after_response({f.__qualname__})>"  # ty: ignore[unresolved-attribute]
+
+    return _AfterResponseMiddleware()
+
+
+def on_error(f: Callable[[Request, Exception], Awaitable[Response | None]]) -> Middleware:
+    """Wrap an async error handler into a Middleware.
+
+    Catches Exception (not BaseException, so asyncio.CancelledError
+    propagates). If the handler returns a Response, that Response is
+    returned to the caller. If the handler returns None, the original
+    exception is re-raised.
+    """
+
+    class _OnErrorMiddleware:
+        async def __call__(self, request: Request, next: Next) -> Response:  # noqa: A002
+            try:
+                return await next(request)
+            except Exception as exc:
+                result = await f(request, exc)
+                if result is None:
+                    raise
+                return result
+
+        def __repr__(self) -> str:
+            return f"<on_error({f.__qualname__})>"  # ty: ignore[unresolved-attribute]
+
+    return _OnErrorMiddleware()
+
+
+__all__ = ["Middleware", "Next", "after_response", "before_request", "on_error"]

httpware/request.py

@@ -0,0 +1,55 @@
+"""Immutable request value type."""
+
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Self
+
+
+@dataclass(frozen=True, slots=True)
+class Request:
+    """Immutable HTTP request value type."""
+
+    method: str
+    url: str
+    headers: Mapping[str, str] = field(default_factory=dict)
+    params: Mapping[str, str] = field(default_factory=dict)
+    cookies: Mapping[str, str] = field(default_factory=dict)
+    body: bytes | None = None
+    extensions: Mapping[str, Any] = field(default_factory=dict)
+
+    def with_header(self, name: str, value: str) -> Self:
+        """Return a copy with the given header added or replaced."""
+        return dataclasses.replace(self, headers={**self.headers, name: value})
+
+    def with_url(self, url: str) -> Self:
+        """Return a copy with the given URL."""
+        return dataclasses.replace(self, url=url)
+
+    def with_body(self, body: bytes | None) -> Self:
+        """Return a copy with the given body."""
+        return dataclasses.replace(self, body=body)
+
+    def with_query(self, params: Mapping[str, str]) -> Self:
+        """Return a copy with the given query params replacing the existing ones."""
+        return dataclasses.replace(self, params=params)
+
+    def with_headers(self, headers: Mapping[str, str]) -> Self:
+        """Return a copy with the given headers merged in (incoming keys override existing)."""
+        return dataclasses.replace(self, headers={**self.headers, **headers})
+
+    def with_cookie(self, name: str, value: str) -> Self:
+        """Return a copy with the given cookie added or replaced."""
+        return dataclasses.replace(self, cookies={**self.cookies, name: value})
+
+    def with_cookies(self, cookies: Mapping[str, str]) -> Self:
+        """Return a copy with the given cookies merged in (incoming keys override existing)."""
+        return dataclasses.replace(self, cookies={**self.cookies, **cookies})
+
+    def with_extension(self, name: str, value: Any) -> Self:  # noqa: ANN401
+        """Return a copy with the given extension entry added or replaced."""
+        return dataclasses.replace(self, extensions={**self.extensions, name: value})
+
+    def with_extensions(self, extensions: Mapping[str, Any]) -> Self:
+        """Return a copy with the given extensions merged in (incoming keys override existing)."""
+        return dataclasses.replace(self, extensions={**self.extensions, **extensions})

httpware/response.py

@@ -0,0 +1,69 @@
+"""Immutable response value type."""
+
+import dataclasses
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Self
+
+
+_CHARSET_PREFIX = "charset="
+
+
+def _get_content_type(headers: Mapping[str, str]) -> str:
+    for key, value in headers.items():
+        if key.lower() == "content-type":
+            return value
+    return ""
+
+
+def _parse_charset(content_type: str) -> str | None:
+    for raw in content_type.split(";"):
+        part = raw.strip()
+        if part.lower().startswith(_CHARSET_PREFIX):
+            return part[len(_CHARSET_PREFIX) :].strip().strip('"').strip("'")
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    """Immutable HTTP response value type.
+
+    `elapsed` is wall-clock seconds from request send to response receipt.
+    """
+
+    status: int
+    headers: Mapping[str, str]
+    content: bytes
+    url: str
+    elapsed: float
+
+    @property
+    def text(self) -> str:
+        """Decode `content` using the response's declared charset (default UTF-8)."""
+        charset = _parse_charset(_get_content_type(self.headers)) or "utf-8"
+        try:
+            return self.content.decode(charset)
+        except LookupError:
+            return self.content.decode("utf-8")
+
+    def json(self) -> Any:  # noqa: ANN401
+        """Parse `content` as JSON."""
+        return json.loads(self.content)
+
+    def with_headers(self, headers: Mapping[str, str]) -> Self:
+        """Return a copy with the given headers merged in (incoming keys override existing)."""
+        return dataclasses.replace(self, headers={**self.headers, **headers})
+
+    def with_status(self, status: int) -> Self:
+        """Return a copy with the given status code."""
+        return dataclasses.replace(self, status=status)
+
+
+@dataclass(frozen=True, slots=True)
+class StreamResponse:
+    """Placeholder for the streaming response type — fleshed out in Story 4.1."""
+
+    status: int
+    headers: Mapping[str, str]
+    url: str

httpware/transports/__init__.py

@@ -0,0 +1,27 @@
+"""Transport protocol — the middleware ↔ transport seam (Seam 1)."""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol, runtime_checkable
+
+from httpware.request import Request
+from httpware.response import Response, StreamResponse
+
+
+@runtime_checkable
+class Transport(Protocol):
+    """Structural protocol every transport adapter satisfies."""
+
+    async def __call__(self, request: Request) -> Response:
+        """Send `request` and return the buffered response."""
+        ...
+
+    def stream(self, request: Request) -> AbstractAsyncContextManager[StreamResponse]:
+        """Open a streaming response for `request` as an async context manager."""
+        ...
+
+    async def aclose(self) -> None:
+        """Release any resources held by the transport."""
+        ...
+
+
+__all__ = ["Transport"]

httpware/transports/httpx2.py

@@ -0,0 +1,180 @@
+"""Httpx2Transport — adapts the httpx2 AsyncClient to the Transport protocol.
+
+This is the only file in `httpware` that imports `httpx2`. The v0
+method / header / multi-valued-header contracts are documented on the
+`Httpx2Transport` class.
+"""
+
+import asyncio
+import dataclasses
+import json
+import time
+from contextlib import AbstractAsyncContextManager
+from typing import Any
+
+import httpx2
+
+from httpware.config import Limits, Timeout
+from httpware.errors import (
+    STATUS_TO_EXCEPTION,
+    ClientStatusError,
+    ServerStatusError,
+    TimeoutError,  # noqa: A004
+    TransportError,
+)
+from httpware.request import Request
+from httpware.response import Response, StreamResponse
+
+
+def _try_decode_json(resp: httpx2.Response) -> Any | None:  # noqa: ANN401
+    """Best-effort JSON decode of `resp.content`; never raises."""
+    content_type = ""
+    for key, value in resp.headers.items():
+        if key.lower() == "content-type":
+            content_type = value
+            break
+    # Strict match on the bare media type: ``application/json`` only.
+    # Splitting on ``;`` strips parameters (e.g. ``; charset=utf-8``) and
+    # avoids ``application/jsonpatch`` false-positives that ``startswith``
+    # would accept. ``+json`` variants (``application/problem+json``,
+    # ``application/vnd.api+json``) are deferred per Open Question (a).
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    if media_type != "application/json":
+        return None
+    if not resp.content:
+        return None
+    try:
+        return json.loads(resp.content)
+    except json.JSONDecodeError:
+        return None
+
+
+class Httpx2Transport:
+    """Default `Transport` implementation backed by `httpx2.AsyncClient`.
+
+    This is the only place in ``httpware`` that imports ``httpx2``. It owns
+    three v0 contracts the rest of the library relies on:
+
+    * The wire ``method`` is uppercased at this seam; the
+      ``httpware.Request.method`` itself is left untouched.
+    * ``headers`` returned to callers (and stored on ``StatusError``) use
+      the lowercase ASCII keys that ``httpx2.Response.headers`` already
+      emits. A case-insensitive header type is deferred until middleware
+      needs it.
+    * ``Mapping[str, str]`` is single-valued. ``dict(resp.headers)``
+      collapses duplicate-key headers (``Set-Cookie``, ``Via``, ``Link``)
+      to the last value only; the multi-valued contract widens together
+      with the case-insensitive type in a later story.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: httpx2.AsyncClient | None = None,
+        limits: Limits | None = None,
+        timeout: Timeout | None = None,
+    ) -> None:
+        """Store the (optionally user-supplied) client and lazy-init config."""
+        if client is not None and (limits is not None or timeout is not None):
+            msg = "Pass limits/timeout only when client is None."
+            raise ValueError(msg)
+        self._client: httpx2.AsyncClient | None = client
+        self._limits: Limits | None = limits
+        self._timeout: Timeout | None = timeout
+        self._closed: bool = False
+        self._init_lock: asyncio.Lock | None = None
+
+    async def _get_client(self) -> httpx2.AsyncClient:
+        if self._closed:
+            msg = "Httpx2Transport is closed."
+            raise TransportError(msg)
+        if self._client is not None:
+            return self._client
+        if self._init_lock is None:
+            self._init_lock = asyncio.Lock()
+        async with self._init_lock:
+            if self._client is None:
+                limits = self._limits or Limits()
+                timeout = self._timeout or Timeout()
+                httpx2_limits = httpx2.Limits(**dataclasses.asdict(limits))
+                httpx2_timeout = httpx2.Timeout(
+                    connect=timeout.connect,
+                    read=timeout.read,
+                    write=timeout.write,
+                    pool=timeout.pool,
+                )
+                self._client = httpx2.AsyncClient(limits=httpx2_limits, timeout=httpx2_timeout)
+        return self._client
+
+    async def __call__(self, request: Request) -> Response:
+        """Send `request` and return a `Response`, raising on 4xx/5xx."""
+        client = await self._get_client()
+        method = request.method.upper()
+        try:
+            httpx2_req = httpx2.Request(
+                method=method,
+                url=request.url,
+                headers=dict(request.headers),
+                params=dict(request.params),
+                cookies=dict(request.cookies),
+                content=request.body,
+                extensions=dict(request.extensions),
+            )
+            start = time.monotonic()
+            resp = await client.send(httpx2_req)
+        except httpx2.TimeoutException as exc:
+            raise TimeoutError(str(exc)) from exc
+        except httpx2.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+            raise TransportError(str(exc)) from exc
+        except RuntimeError as exc:
+            # ``httpx2.AsyncClient.send`` raises a bare RuntimeError when
+            # the client has been closed externally; there is no public
+            # attribute we can interrogate ahead of time.
+            if "closed" in str(exc):
+                raise TransportError(str(exc)) from exc
+            raise
+        elapsed = time.monotonic() - start
+        status = resp.status_code
+        # ``dict(...)`` collapses duplicate-key headers (Set-Cookie etc.)
+        # to the last value — see class docstring; widens with the
+        # multi-valued header contract in a later story.
+        headers = dict(resp.headers)
+        if 400 <= status < 600:  # noqa: PLR2004
+            exc_class = STATUS_TO_EXCEPTION.get(
+                status,
+                ClientStatusError if status < 500 else ServerStatusError,  # noqa: PLR2004
+            )
+            raise exc_class(
+                status=status,
+                body=resp.content,
+                headers=headers,
+                json=_try_decode_json(resp),
+                request_method=method,
+                request_url=request.url,
+            )
+        return Response(
+            status=status,
+            headers=headers,
+            content=resp.content,
+            url=str(resp.url),
+            elapsed=elapsed,
+        )
+
+    def stream(self, request: Request) -> AbstractAsyncContextManager[StreamResponse]:  # noqa: ARG002
+        """Open a streaming response — not yet implemented (Story 4.1)."""
+        if self._closed:
+            msg = "Httpx2Transport is closed."
+            raise TransportError(msg)
+        msg = "Streaming arrives in Epic 4 (Story 4.1)."
+        raise NotImplementedError(msg)
+
+    async def aclose(self) -> None:
+        """Close the underlying client; safe to call repeatedly."""
+        if self._closed:
+            return
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+        self._closed = True