haveapi-client 0.30.0__py3-none-any.whl

haveapi_client/_resources/__init__.py

@@ -0,0 +1,196 @@
+"""Immutable resource and action navigation; only calls perform I/O."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Any
+
+from haveapi_client._protocol import (
+    CallContext,
+    InputParams,
+    RequestOptions,
+    lookup_action,
+    lookup_resource,
+)
+from haveapi_client.exceptions import StaleDescriptionError
+
+
+def _path_params(
+    old: Mapping[str, str | int], new: Mapping[str, str | int] | None
+) -> Mapping[str, str | int]:
+    result = dict(old)
+    for key, value in (new or {}).items():
+        if key in result and result[key] != value:
+            raise ValueError(f"Conflicting path parameter: {key}")
+        result[key] = value
+    return MappingProxyType(result)
+
+
+@dataclass(frozen=True)
+class Resource:
+    _executor: Any = field(repr=False, compare=False)
+    _path: tuple[str, ...]
+    _bound_args: tuple[str | int, ...] = field(default=(), repr=False)
+    _path_params: Mapping[str, str | int] = field(default_factory=dict, repr=False)
+    _generation: int = 0
+    _async: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_path", tuple(self._path))
+        object.__setattr__(self, "_bound_args", tuple(self._bound_args))
+        object.__setattr__(
+            self, "_path_params", MappingProxyType(dict(self._path_params))
+        )
+
+    def _check(self) -> None:
+        if self._executor.generation != self._generation:
+            raise StaleDescriptionError("Resource belongs to an old description")
+
+    @property
+    def resources(self) -> Mapping[str, Resource]:
+        self._check()
+        spec = lookup_resource(self._executor.description, self._path)
+        return MappingProxyType(
+            {
+                name: Resource(
+                    self._executor,
+                    child.resource_path,
+                    self._bound_args,
+                    self._path_params,
+                    self._generation,
+                    self._async,
+                )
+                for name, child in spec.resources.items()
+            }
+        )
+
+    @property
+    def actions(self) -> Mapping[str, Action]:
+        self._check()
+        spec = lookup_resource(self._executor.description, self._path)
+        return MappingProxyType({name: self._action(name) for name in spec.actions})
+
+    def _action(self, name: str) -> Action:
+        self._check()
+        spec = lookup_action(self._executor.description, self._path, name)
+        return Action(
+            self._executor,
+            CallContext(spec, self._bound_args, self._path_params, self._generation),
+            self._async,
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        self._check()
+        spec = lookup_resource(self._executor.description, self._path)
+        has_action = name in spec.actions or any(
+            name in a.aliases for a in spec.actions.values()
+        )
+        if name in spec.resources:
+            if has_action:
+                raise AttributeError(
+                    f"Ambiguous resource/action {name!r}; use exact-name maps"
+                )
+            return self.resources[name]
+        if has_action:
+            return self._action(name)
+        raise AttributeError(name)
+
+    def __getitem__(self, value: str | int) -> Resource:
+        self._check()
+        if isinstance(value, bool) or not isinstance(value, (str, int)):
+            raise TypeError("Path bindings must be strings or integers")
+        return Resource(
+            self._executor,
+            self._path,
+            (*self._bound_args, value),
+            self._path_params,
+            self._generation,
+            self._async,
+        )
+
+    def __dir__(self) -> list[str]:
+        self._check()
+        spec = lookup_resource(self._executor.description, self._path)
+        return sorted(set(super().__dir__()) | set(spec.resources) | set(spec.actions))
+
+
+@dataclass(frozen=True)
+class Action:
+    _executor: Any = field(repr=False, compare=False)
+    _context: CallContext = field(repr=False)
+    _async: bool = False
+
+    def _binding(self, path_params: Mapping[str, str | int] | None) -> CallContext:
+        if self._executor.generation != self._context.generation:
+            raise StaleDescriptionError("Action belongs to an old description")
+        return CallContext(
+            self._context.action,
+            self._context.bound_args,
+            _path_params(self._context.path_params, path_params),
+            self._context.generation,
+        )
+
+    def __call__(self, **params: object) -> Any:
+        return self.call(params=params)
+
+    def call(
+        self,
+        *,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        path_params: Mapping[str, str | int] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        return self._executor.execute(
+            self._binding(path_params), params=params, meta=meta, options=options
+        )
+
+    def iter_pages(
+        self,
+        *,
+        strategy: Any,
+        page_size: int = 100,
+        params: Mapping[str, object] | None = None,
+        meta: Mapping[str, object] | None = None,
+        path_params: Mapping[str, str | int] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        from haveapi_client.pagination import aiter_pages, iter_pages
+
+        function = aiter_pages if self._async else iter_pages
+        return function(
+            self._executor,
+            self._binding(path_params),
+            strategy=strategy,
+            page_size=page_size,
+            params=params,
+            meta=meta,
+            options=options,
+        )
+
+    def iter_all(
+        self,
+        *,
+        strategy: Any,
+        page_size: int = 100,
+        params: Mapping[str, object] | None = None,
+        meta: Mapping[str, object] | None = None,
+        path_params: Mapping[str, str | int] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Any:
+        from haveapi_client.pagination import aiter_all, iter_all
+
+        function = aiter_all if self._async else iter_all
+        return function(
+            self._executor,
+            self._binding(path_params),
+            strategy=strategy,
+            page_size=page_size,
+            params=params,
+            meta=meta,
+            options=options,
+        )

haveapi_client/_resources/state.py

@@ -0,0 +1,266 @@
+"""Shared pure connection state and concurrency gates for both client facades."""
+
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from haveapi_client._auth import AuthProvider, validate_headers
+from haveapi_client._protocol import (
+    ActionSpec,
+    CallContext,
+    Description,
+    InputParams,
+    ParameterSpec,
+    RequestSpec,
+    build_request,
+    lookup_resource,
+    parse_resources,
+)
+from haveapi_client._resources import Resource
+from haveapi_client._transport import normalize_base_url, validate_destination
+from haveapi_client.exceptions import (
+    AuthenticationError,
+    NotConnectedError,
+    ProtocolError,
+    StaleDescriptionError,
+)
+
+
+class ClientState:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        version: str | None,
+        auth: AuthProvider | None,
+        language: str | None,
+        asynchronous: bool,
+    ) -> None:
+        self._base_url = normalize_base_url(base_url)
+        if version is not None and (
+            not re.fullmatch(r"[A-Za-z0-9_-][A-Za-z0-9._-]*", version)
+        ):
+            raise ValueError("Invalid API version")
+        if language is not None and any(ord(c) < 32 or ord(c) > 126 for c in language):
+            raise ValueError("Invalid language header")
+        self._version = version
+        self._auth = auth
+        self._language = language
+        self._description: Description | None = None
+        self._generation = 0
+        self._asynchronous = asynchronous
+        self._lock = threading.RLock()
+        self._active = 0
+        self._mutating = False
+        self._closed = False
+        self._login: object | None = None
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(connected={self._description is not None})"
+
+    @property
+    def description(self) -> Description:
+        if self._description is None:
+            raise NotConnectedError("Call connect() before accessing API resources")
+        return self._description
+
+    @property
+    def generation(self) -> int:
+        return self._generation
+
+    @property
+    def resources(self) -> Mapping[str, Resource]:
+        from types import MappingProxyType
+
+        return MappingProxyType(
+            {name: self.resource((name,)) for name in self.description.resources}
+        )
+
+    def resource(
+        self,
+        path: tuple[str, ...],
+        *,
+        bound_args: tuple[str | int, ...] = (),
+        path_params: Mapping[str, str | int] | None = None,
+    ) -> Resource:
+        lookup_resource(self.description, path)
+        return Resource(
+            self,
+            path,
+            bound_args,
+            path_params or {},
+            self.generation,
+            self._asynchronous,
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if name in self.description.resources:
+            return self.resource((name,))
+        raise AttributeError(name)
+
+    def __dir__(self) -> list[str]:
+        return sorted(
+            set(super().__dir__())
+            | set(self._description.resources if self._description else ())
+        )
+
+    @contextmanager
+    def _mutation(self) -> Iterator[None]:
+        # Never hold a thread lock across network I/O or an await. The same
+        # short reservation gate handles threads and independently scheduled tasks.
+        with self._lock:
+            if self._closed:
+                raise NotConnectedError("Client is closed")
+            if self._active or self._mutating:
+                raise AuthenticationError(
+                    "Client state is in use; retry the explicit state change later"
+                )
+            self._mutating = True
+        try:
+            yield
+        finally:
+            with self._lock:
+                self._mutating = False
+
+    @contextmanager
+    def _request(self, context: CallContext) -> Iterator[Description]:
+        with self._lock:
+            if context.generation != self.generation:
+                raise StaleDescriptionError("Action belongs to an old description")
+            if self._mutating:
+                raise AuthenticationError(
+                    "Client authentication or description is changing"
+                )
+            description = self.description
+            self._active += 1
+        try:
+            yield description
+        finally:
+            with self._lock:
+                self._active -= 1
+
+    def _invalidate(self) -> None:
+        self._generation += 1
+        self._description = None
+        self._login = None
+
+    def _install(self, description: Description) -> None:
+        self._generation += 1
+        self._description = description
+        self._login = None
+
+    def _headers(
+        self, description: Description | None, auth: AuthProvider | None
+    ) -> dict[str, str]:
+        headers = {"Accept": "application/json", "User-Agent": "haveapi-client-python"}
+        if self._language:
+            headers["Accept-Language"] = self._language
+        if auth is not None:
+            if description is None or auth.method not in description.authentication:
+                raise AuthenticationError("Authentication method is not advertised")
+            headers.update(validate_headers(auth.headers(description)))
+        return headers
+
+    def _discovery_request(
+        self,
+        description: Description | None = None,
+        auth: AuthProvider | None = None,
+    ) -> RequestSpec:
+        url = self._base_url + (
+            f"v{self._version}/" if self._version is not None else ""
+        )
+        validate_destination(self._base_url, url)
+        query = () if self._version is not None else (("describe", "default"),)
+        return RequestSpec(
+            "OPTIONS", url, query, self._headers(description, auth), None
+        )
+
+    def _action_request(
+        self,
+        description: Description,
+        context: CallContext,
+        *,
+        auth: AuthProvider | None,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+    ) -> RequestSpec:
+        request = build_request(
+            description, context, base_url=self._base_url, params=params, meta=meta
+        )
+        validate_destination(self._base_url, request.url)
+        headers = dict(request.headers)
+        headers.update(self._headers(description, auth))
+        return RequestSpec(
+            request.method, request.url, request.query, headers, request.content
+        )
+
+    def _token_action(self, description: Description, name: str) -> ActionSpec:
+        provider = description.authentication.get("token")
+        raw = provider.get("resources") if provider is not None else None
+        if not isinstance(raw, Mapping):
+            raise AuthenticationError("Token authentication is not advertised")
+        resources = parse_resources(raw)
+        token = resources.get("token")
+        if token is None or name not in token.actions:
+            raise AuthenticationError("Token authentication action is not advertised")
+        return token.actions[name]
+
+    def _login_result(self, data: object) -> tuple[bool, str, str | None, str | None]:
+        if not isinstance(data, Mapping) or not isinstance(data.get("complete"), bool):
+            raise ProtocolError("Invalid token authentication result")
+        token = data.get("token")
+        valid_to = data.get("valid_to")
+        complete = data["complete"]
+        next_action = data.get("next_action")
+        if (
+            not isinstance(token, str)
+            or not token
+            or (valid_to is not None and not isinstance(valid_to, str))
+            or (not complete and (not isinstance(next_action, str) or not next_action))
+        ):
+            raise ProtocolError("Invalid token authentication result")
+        return (
+            complete,
+            token,
+            valid_to,
+            next_action if isinstance(next_action, str) else None,
+        )
+
+    def _prepare_challenge(
+        self,
+        description: Description,
+        next_action: str,
+    ) -> tuple[Mapping[str, ParameterSpec], object]:
+        """Validate a next step before installing its nonce under _mutation."""
+        action = self._token_action(description, next_action)
+        if action.input is None or "token" not in action.input.parameters:
+            raise ProtocolError(
+                "Authentication continuation must describe a token input"
+            )
+        fields = {
+            key: value
+            for key, value in action.input.parameters.items()
+            if key != "token"
+        }
+        nonce = object()
+        self._login = nonce
+        return fields, nonce
+
+    def _continuation_params(
+        self,
+        nonce: object,
+        token: str,
+        values: Mapping[str, object],
+    ) -> Mapping[str, object]:
+        """Check the current challenge and copy input without consuming retries."""
+        if self._login is not nonce:
+            raise AuthenticationError("Authentication challenge is no longer current")
+        if "token" in values:
+            raise AuthenticationError("Continuation token cannot be overridden")
+        return {**values, "token": token}

haveapi_client/_transport/__init__.py

@@ -0,0 +1,155 @@
+"""HTTPX adapters. Requests never inherit injected-client auth or cookies."""
+
+from __future__ import annotations
+
+import math
+from urllib.parse import unquote, urlencode, urlsplit
+
+import httpx
+
+from haveapi_client._protocol import (
+    RequestOptions,
+    RequestSpec,
+    WireResponse,
+    resolve_url,
+)
+from haveapi_client.exceptions import ProtocolError, TransportError
+
+
+def finite_timeout(value: float) -> float:
+    if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError("timeout must be positive and finite")
+    return value
+
+
+def normalize_base_url(value: str) -> str:
+    if any(ord(c) < 32 or ord(c) == 127 for c in value) or "\\" in value:
+        raise ValueError("base_url contains unsafe characters")
+    url = urlsplit(value)
+    if (
+        url.scheme not in {"https", "http"}
+        or not url.hostname
+        or url.username is not None
+        or url.password is not None
+        or url.query
+        or url.fragment
+    ):
+        raise ValueError(
+            "base_url must be an HTTP(S) URL without credentials, query or fragment"
+        )
+    try:
+        if url.port is not None and not 0 < url.port <= 65535:
+            raise ValueError("Invalid port")
+    except ValueError as exc:
+        raise ValueError("base_url has an invalid port") from exc
+    if any(segment in {".", ".."} for segment in unquote(url.path).split("/")):
+        raise ValueError("base_url must not contain path traversal")
+    try:
+        resolve_url(value, "")
+    except ProtocolError:
+        raise ValueError("base_url contains an unsafe path") from None
+    return value.rstrip("/") + "/"
+
+
+def validate_destination(base_url: str, destination: str) -> None:
+    base = urlsplit(base_url)
+    url = urlsplit(destination)
+    try:
+        same_origin = (
+            url.scheme.lower(),
+            url.hostname,
+            url.port or (443 if url.scheme == "https" else 80),
+        ) == (
+            base.scheme.lower(),
+            base.hostname,
+            base.port or (443 if base.scheme == "https" else 80),
+        )
+    except ValueError as exc:
+        raise ProtocolError("Invalid destination URL") from exc
+    if (
+        not same_origin
+        or url.username is not None
+        or url.password is not None
+        or url.fragment
+        or not url.path.startswith(base.path)
+    ):
+        raise ProtocolError("Request destination is outside the configured API")
+
+
+def _request(
+    spec: RequestSpec, timeout: float, options: RequestOptions | None
+) -> httpx.Request:
+    effective = (
+        timeout if options is None or options.timeout is None else options.timeout
+    )
+    finite_timeout(effective)
+    # HTTPX params groups duplicate names, which changes Rack's row boundaries
+    # for arrays of objects. Preserve the protocol core's complete pair order.
+    query = urlencode(spec.query).encode("ascii")
+    url = httpx.URL(spec.url).copy_with(query=query or None)
+    return httpx.Request(
+        spec.method,
+        url,
+        headers=spec.headers,
+        content=spec.content,
+        extensions={"timeout": httpx.Timeout(effective).as_dict()},
+    )
+
+
+class SyncTransport:
+    def __init__(
+        self, *, timeout: float, http_client: httpx.Client | None = None
+    ) -> None:
+        self.timeout = finite_timeout(timeout)
+        self.owned = http_client is None
+        self.client = (
+            http_client if http_client is not None else httpx.Client(timeout=timeout)
+        )
+
+    def send(
+        self, spec: RequestSpec, *, options: RequestOptions | None = None
+    ) -> WireResponse:
+        try:
+            response = self.client.send(
+                _request(spec, self.timeout, options), auth=None, follow_redirects=False
+            )
+        except httpx.HTTPError:
+            # HTTPX exception messages can include request URLs and credentials.
+            raise TransportError("HTTP request failed") from None
+        return WireResponse(
+            response.status_code, dict(response.headers), response.content
+        )
+
+    def close(self) -> None:
+        if self.owned:
+            self.client.close()
+
+
+class AsyncTransport:
+    def __init__(
+        self, *, timeout: float, http_client: httpx.AsyncClient | None = None
+    ) -> None:
+        self.timeout = finite_timeout(timeout)
+        self.owned = http_client is None
+        self.client = (
+            http_client
+            if http_client is not None
+            else httpx.AsyncClient(timeout=timeout)
+        )
+
+    async def send(
+        self, spec: RequestSpec, *, options: RequestOptions | None = None
+    ) -> WireResponse:
+        try:
+            response = await self.client.send(
+                _request(spec, self.timeout, options), auth=None, follow_redirects=False
+            )
+        except httpx.HTTPError:
+            raise TransportError("HTTP request failed") from None
+        return WireResponse(
+            response.status_code, dict(response.headers), response.content
+        )
+
+    async def aclose(self) -> None:
+        if self.owned:
+            await self.client.aclose()