haveapi-client 0.30.0__py3-none-any.whl

haveapi_client/async_client.py

@@ -0,0 +1,209 @@
+"""Asynchronous dynamic HaveAPI client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self
+
+import httpx
+
+from haveapi_client._auth import (
+    AsyncAuthenticationChallenge,
+    Authenticated,
+    AuthProvider,
+    TokenAuth,
+)
+from haveapi_client._protocol import (
+    CallContext,
+    DecodedResponse,
+    Description,
+    InputParams,
+    RequestOptions,
+    decode_envelope,
+    decode_response,
+    parse_description,
+)
+from haveapi_client._resources.state import ClientState
+from haveapi_client._transport import AsyncTransport
+from haveapi_client.exceptions import AuthenticationError
+
+if TYPE_CHECKING:
+    from haveapi_client.response import Response
+
+
+class AsyncClient(ClientState):
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        version: str | None = None,
+        auth: AuthProvider | None = None,
+        timeout: float = 30.0,
+        language: str | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            base_url, version=version, auth=auth, language=language, asynchronous=True
+        )
+        self._transport = AsyncTransport(timeout=timeout, http_client=http_client)
+
+    async def _discover(
+        self,
+        description: Description | None = None,
+        auth: AuthProvider | None = None,
+    ) -> Description:
+        wire = await self._transport.send(self._discovery_request(description, auth))
+        return parse_description(decode_envelope(wire), api_version=self._version)
+
+    async def _load(self) -> Description:
+        public = await self._discover()
+        return (
+            await self._discover(public, self._auth)
+            if self._auth is not None
+            else public
+        )
+
+    async def connect(self) -> Self:
+        with self._mutation():
+            if self._description is None:
+                self._install(await self._load())
+        return self
+
+    async def refresh_description(self) -> Description:
+        with self._mutation():
+            self._invalidate()
+            description = await self._load()
+            self._install(description)
+            return description
+
+    async def set_auth(self, auth: AuthProvider | None) -> Self:
+        with self._mutation():
+            self._invalidate()
+            self._auth = auth
+            self._install(await self._load())
+        return self
+
+    async def logout(self) -> None:
+        await self.set_auth(None)
+
+    async def _invoke(
+        self,
+        description: Description,
+        context: CallContext,
+        *,
+        auth: AuthProvider | None,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> DecodedResponse:
+        request = self._action_request(
+            description, context, auth=auth, params=params, meta=meta
+        )
+        return decode_response(
+            description,
+            context.action,
+            await self._transport.send(request, options=options),
+        )
+
+    async def execute(
+        self,
+        context: CallContext,
+        *,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Response[Any]:
+        from haveapi_client.response import adapt_async_response
+
+        with self._request(context) as description:
+            decoded = await self._invoke(
+                description,
+                context,
+                auth=self._auth,
+                params=params,
+                meta=meta,
+                options=options,
+            )
+            return adapt_async_response(decoded, context, self)
+
+    async def begin_token_login(
+        self, params: Mapping[str, object]
+    ) -> Authenticated | AsyncAuthenticationChallenge:
+        with self._mutation():
+            self._invalidate()
+            self._auth = None
+            description = await self._discover()
+            return await self._login_step(description, "request", params)
+
+    async def _login_step(
+        self,
+        description: Description,
+        name: str,
+        params: Mapping[str, object],
+    ) -> Authenticated | AsyncAuthenticationChallenge:
+        action = self._token_action(description, name)
+        context = CallContext(action, (), {}, self.generation)
+        decoded = await self._invoke(description, context, auth=None, params=params)
+        complete, token, valid_to, next_action = self._login_result(decoded.data)
+        self._login = None
+        if complete:
+            auth = TokenAuth(token)
+            authorized = await self._discover(description, auth)
+            self._auth = auth
+            self._install(authorized)
+            return Authenticated(token, valid_to)
+        assert next_action is not None
+        fields, nonce = self._prepare_challenge(description, next_action)
+
+        async def submit(
+            values: Mapping[str, object],
+        ) -> Authenticated | AsyncAuthenticationChallenge:
+            with self._mutation():
+                params = self._continuation_params(nonce, token, values)
+                return await self._login_step(description, next_action, params)
+
+        return AsyncAuthenticationChallenge(next_action, fields, valid_to, submit)
+
+    async def renew_token(self) -> Response[Any]:
+        with self._mutation():
+            return await self._token_operation("renew")
+
+    async def revoke_token(self) -> Response[Any]:
+        with self._mutation():
+            response = await self._token_operation("revoke")
+            self._auth = None
+            self._invalidate()
+            self._install(await self._discover())
+            return response
+
+    async def _token_operation(self, name: str) -> Response[Any]:
+        from haveapi_client.response import adapt_async_response
+
+        if not isinstance(self._auth, TokenAuth):
+            raise AuthenticationError("A connected token identity is required")
+        description = self.description
+        context = CallContext(
+            self._token_action(description, name), (), {}, self.generation
+        )
+        return adapt_async_response(
+            await self._invoke(description, context, auth=self._auth), context, self
+        )
+
+    async def aclose(self) -> None:
+        if self._closed:
+            return
+        with self._mutation():
+            self._invalidate()
+            self._auth = None
+            self._closed = True
+            await self._transport.aclose()
+
+    async def __aenter__(self) -> Self:
+        try:
+            return await self.connect()
+        except BaseException:
+            await self.aclose()
+            raise
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

haveapi_client/client.py

@@ -0,0 +1,203 @@
+"""Synchronous dynamic HaveAPI client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self
+
+import httpx
+
+from haveapi_client._auth import (
+    Authenticated,
+    AuthenticationChallenge,
+    AuthProvider,
+    TokenAuth,
+)
+from haveapi_client._protocol import (
+    CallContext,
+    DecodedResponse,
+    Description,
+    InputParams,
+    RequestOptions,
+    decode_envelope,
+    decode_response,
+    parse_description,
+)
+from haveapi_client._resources.state import ClientState
+from haveapi_client._transport import SyncTransport
+from haveapi_client.exceptions import AuthenticationError
+
+if TYPE_CHECKING:
+    from haveapi_client.response import Response
+
+
+class Client(ClientState):
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        version: str | None = None,
+        auth: AuthProvider | None = None,
+        timeout: float = 30.0,
+        language: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            base_url, version=version, auth=auth, language=language, asynchronous=False
+        )
+        self._transport = SyncTransport(timeout=timeout, http_client=http_client)
+
+    def _discover(
+        self,
+        description: Description | None = None,
+        auth: AuthProvider | None = None,
+    ) -> Description:
+        wire = self._transport.send(self._discovery_request(description, auth))
+        return parse_description(decode_envelope(wire), api_version=self._version)
+
+    def _load(self) -> Description:
+        public = self._discover()
+        return self._discover(public, self._auth) if self._auth is not None else public
+
+    def connect(self) -> Self:
+        with self._mutation():
+            if self._description is None:
+                self._install(self._load())
+        return self
+
+    def refresh_description(self) -> Description:
+        with self._mutation():
+            self._invalidate()
+            description = self._load()
+            self._install(description)
+            return description
+
+    def set_auth(self, auth: AuthProvider | None) -> Self:
+        with self._mutation():
+            self._invalidate()
+            self._auth = auth
+            self._install(self._load())
+        return self
+
+    def logout(self) -> None:
+        self.set_auth(None)
+
+    def _invoke(
+        self,
+        description: Description,
+        context: CallContext,
+        *,
+        auth: AuthProvider | None,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> DecodedResponse:
+        request = self._action_request(
+            description, context, auth=auth, params=params, meta=meta
+        )
+        return decode_response(
+            description, context.action, self._transport.send(request, options=options)
+        )
+
+    def execute(
+        self,
+        context: CallContext,
+        *,
+        params: InputParams | None = None,
+        meta: Mapping[str, object] | None = None,
+        options: RequestOptions | None = None,
+    ) -> Response[Any]:
+        from haveapi_client.response import adapt_response
+
+        with self._request(context) as description:
+            decoded = self._invoke(
+                description,
+                context,
+                auth=self._auth,
+                params=params,
+                meta=meta,
+                options=options,
+            )
+            return adapt_response(decoded, context, self)
+
+    def begin_token_login(
+        self, params: Mapping[str, object]
+    ) -> Authenticated | AuthenticationChallenge:
+        with self._mutation():
+            self._invalidate()
+            self._auth = None
+            description = self._discover()
+            return self._login_step(description, "request", params)
+
+    def _login_step(
+        self,
+        description: Description,
+        name: str,
+        params: Mapping[str, object],
+    ) -> Authenticated | AuthenticationChallenge:
+        action = self._token_action(description, name)
+        context = CallContext(action, (), {}, self.generation)
+        decoded = self._invoke(description, context, auth=None, params=params)
+        complete, token, valid_to, next_action = self._login_result(decoded.data)
+        self._login = None
+        if complete:
+            auth = TokenAuth(token)
+            authorized = self._discover(description, auth)
+            self._auth = auth
+            self._install(authorized)
+            return Authenticated(token, valid_to)
+        assert next_action is not None
+        fields, nonce = self._prepare_challenge(description, next_action)
+
+        def submit(
+            values: Mapping[str, object],
+        ) -> Authenticated | AuthenticationChallenge:
+            with self._mutation():
+                params = self._continuation_params(nonce, token, values)
+                return self._login_step(description, next_action, params)
+
+        return AuthenticationChallenge(next_action, fields, valid_to, submit)
+
+    def renew_token(self) -> Response[Any]:
+        with self._mutation():
+            return self._token_operation("renew")
+
+    def revoke_token(self) -> Response[Any]:
+        with self._mutation():
+            response = self._token_operation("revoke")
+            self._auth = None
+            self._invalidate()
+            self._install(self._discover())
+            return response
+
+    def _token_operation(self, name: str) -> Response[Any]:
+        from haveapi_client.response import adapt_response
+
+        if not isinstance(self._auth, TokenAuth):
+            raise AuthenticationError("A connected token identity is required")
+        description = self.description
+        context = CallContext(
+            self._token_action(description, name), (), {}, self.generation
+        )
+        return adapt_response(
+            self._invoke(description, context, auth=self._auth), context, self
+        )
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        with self._mutation():
+            self._invalidate()
+            self._auth = None
+            self._closed = True
+            self._transport.close()
+
+    def __enter__(self) -> Self:
+        try:
+            return self.connect()
+        except BaseException:
+            self.close()
+            raise
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

haveapi_client/exceptions.py

@@ -0,0 +1,88 @@
+"""Public error categories with safe, inspectable protocol context."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+
+def _redact(value: object) -> object:
+    if isinstance(value, Mapping):
+        return MappingProxyType(
+            {
+                str(k): (
+                    "<redacted>"
+                    if any(s in str(k).lower() for s in ("token", "password", "secret"))
+                    else _redact(v)
+                )
+                for k, v in value.items()
+            }
+        )
+    if isinstance(value, (list, tuple)):
+        return tuple(_redact(v) for v in value)
+    return value
+
+
+class HaveAPIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        errors: Mapping[str, object] | None = None,
+        envelope: Mapping[str, object] | None = None,
+        operation_id: str | int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.errors = MappingProxyType(dict(errors or {}))
+        # Arbitrary protected parameter names cannot be inferred from an envelope.
+        # Retain its diagnostic shape, but never expose a failed response payload.
+        self.envelope = MappingProxyType(
+            {
+                k: "<redacted>" if k == "response" else _redact(v)
+                for k, v in (envelope or {}).items()
+            }
+        )
+        self.operation_id = operation_id
+
+
+class ProtocolError(HaveAPIError):
+    pass
+
+
+class TransportError(HaveAPIError):
+    pass
+
+
+class AuthenticationError(HaveAPIError):
+    pass
+
+
+class ValidationError(HaveAPIError):
+    pass
+
+
+class ActionError(HaveAPIError):
+    pass
+
+
+class NotConnectedError(HaveAPIError):
+    pass
+
+
+class StaleDescriptionError(HaveAPIError):
+    pass
+
+
+class PaginationError(HaveAPIError):
+    pass
+
+
+class OperationFailedError(HaveAPIError):
+    pass
+
+
+class OperationTimeoutError(HaveAPIError):
+    pass

haveapi_client/operations.py

@@ -0,0 +1,190 @@
+"""Explicit monitoring of HaveAPI action_state operations."""
+
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Mapping
+from typing import Any, cast
+
+import anyio
+
+from ._protocol import (
+    AsyncExecutor,
+    CallContext,
+    RequestOptions,
+    SyncExecutor,
+    lookup_action,
+)
+from .exceptions import (
+    OperationFailedError,
+    OperationTimeoutError,
+    ProtocolError,
+    StaleDescriptionError,
+    TransportError,
+)
+from .response import Response
+
+
+def _positive(value: float, name: str) -> None:
+    if isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be positive and finite")
+
+
+class _Operation:
+    def __init__(
+        self,
+        executor: SyncExecutor | AsyncExecutor,
+        generation: int,
+        action_state_id: str | int,
+    ) -> None:
+        if isinstance(action_state_id, bool) or not isinstance(
+            action_state_id, (str, int)
+        ):
+            raise ValueError("operation ID must be a string or integer")
+        self._executor = executor
+        self._generation = generation
+        self.action_state_id = action_state_id
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} id={self.action_state_id!r}>"
+
+    def _context(self, name: str) -> CallContext:
+        if self._generation != self._executor.generation:
+            raise StaleDescriptionError(
+                "operation belongs to an old description",
+                operation_id=self.action_state_id,
+            )
+        try:
+            action = lookup_action(self._executor.description, ("action_state",), name)
+        except KeyError as error:
+            raise ProtocolError(
+                f"operation action is unavailable: {name}",
+                operation_id=self.action_state_id,
+            ) from error
+        if len(action.path_parameters) != 1:
+            raise ProtocolError(
+                "operation action must have one ID path parameter",
+                operation_id=self.action_state_id,
+            )
+        return CallContext(action, (self.action_state_id,), {}, self._generation)
+
+    def _terminal(self, response: Response[Any]) -> bool:
+        state = response.data
+        if not isinstance(state, Mapping) or not isinstance(
+            state.get("finished"), bool
+        ):
+            raise ProtocolError(
+                "operation response has no boolean finished state",
+                operation_id=self.action_state_id,
+            )
+        if state["finished"] is False:
+            return False
+        if state.get("status") is False:
+            raise OperationFailedError(
+                "operation finished unsuccessfully",
+                status_code=response.status_code,
+                envelope=response.envelope,
+                operation_id=self.action_state_id,
+            )
+        if state.get("status") is not True:
+            raise ProtocolError(
+                "finished operation has no boolean result status",
+                operation_id=self.action_state_id,
+            )
+        return True
+
+    def _remaining(self, deadline: float) -> float:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise OperationTimeoutError(
+                "operation wait timed out", operation_id=self.action_state_id
+            )
+        return remaining
+
+    def _cancellable(self, response: Response[Any]) -> None:
+        if (
+            not isinstance(response.data, Mapping)
+            or response.data.get("can_cancel") is not True
+        ):
+            raise OperationFailedError(
+                "operation cannot be cancelled", operation_id=self.action_state_id
+            )
+
+
+class Operation(_Operation):
+    def show(self) -> Response[Any]:
+        return cast(SyncExecutor, self._executor).execute(self._context("show"))
+
+    def wait(self, *, timeout: float = 300.0, interval: float = 1.0) -> Response[Any]:
+        """Wait locally, leaving the server operation running on timeout.
+
+        HTTPX applies the remaining budget to individual transport phases. A
+        blocking request can return control after the overall deadline; classify
+        its result or failure against the monotonic deadline once it returns.
+        """
+        _positive(timeout, "timeout")
+        _positive(interval, "interval")
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = self._remaining(deadline)
+            try:
+                response = cast(SyncExecutor, self._executor).execute(
+                    self._context("show"), options=RequestOptions(timeout=remaining)
+                )
+            except TransportError as error:
+                try:
+                    self._remaining(deadline)
+                except OperationTimeoutError as expired:
+                    raise expired from error
+                raise
+            self._remaining(deadline)
+            if self._terminal(response):
+                return response
+            time.sleep(min(interval, self._remaining(deadline)))
+
+    def cancel(self) -> Response[Any]:
+        context = self._context("cancel")
+        self._cancellable(self.show())
+        return cast(SyncExecutor, self._executor).execute(context)
+
+
+class AsyncOperation(_Operation):
+    async def show(self) -> Response[Any]:
+        return await cast(AsyncExecutor, self._executor).execute(self._context("show"))
+
+    async def wait(
+        self, *, timeout: float = 300.0, interval: float = 1.0
+    ) -> Response[Any]:
+        _positive(timeout, "timeout")
+        _positive(interval, "interval")
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining = self._remaining(deadline)
+            scope = None
+            try:
+                with anyio.fail_after(remaining) as scope:
+                    response = await cast(AsyncExecutor, self._executor).execute(
+                        self._context("show"), options=RequestOptions(timeout=remaining)
+                    )
+            except TimeoutError as error:
+                if scope is not None and scope.cancelled_caught:
+                    raise OperationTimeoutError(
+                        "operation wait timed out", operation_id=self.action_state_id
+                    ) from error
+                raise
+            except TransportError as error:
+                try:
+                    self._remaining(deadline)
+                except OperationTimeoutError as expired:
+                    raise expired from error
+                raise
+            self._remaining(deadline)
+            if self._terminal(response):
+                return response
+            await anyio.sleep(min(interval, self._remaining(deadline)))
+
+    async def cancel(self) -> Response[Any]:
+        context = self._context("cancel")
+        self._cancellable(await self.show())
+        return await cast(AsyncExecutor, self._executor).execute(context)