UGOS 1.0.0__py3-none-any.whl

ugos/_transport.py

@@ -0,0 +1,446 @@
+"""Synchronous HTTP transport."""
+
+from __future__ import annotations
+
+import contextlib
+import time
+import warnings
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any
+
+import httpx
+
+from ._config import ClientConfig
+from ._encoding import encode_params
+from .exceptions import ConfigurationError, ProtocolError, RequestTimeoutError, TransportError
+
+FORM_HEADERS = {
+    "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+    "Accept": "application/json, text/plain, */*",
+    "X-Requested-With": "XMLHttpRequest",
+}
+
+HTML_HEADERS = {
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+}
+
+UNSET = object()
+_UNSET = UNSET
+
+
+class HttpTransport:
+    """Thin wrapper around :class:`httpx.Client`."""
+
+    @staticmethod
+    def _warn_insecure(verify: Any) -> None:
+        if verify is not False:
+            return
+        warnings.warn(
+            "TLS verification is disabled; use verify=False only in a trusted test environment",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+
+    @staticmethod
+    def _coerce_verify(verify: Any) -> Any:
+        if hasattr(verify, "__fspath__"):
+            return str(verify)
+        return verify
+
+    def _use_custom_client(self, http_client: httpx.Client) -> None:
+        client_base = str(http_client.base_url).rstrip("/")
+        config_base = self._config.base_url.rstrip("/")
+        if client_base != config_base:
+            raise ConfigurationError("http_client.base_url does not match the configured base_url")
+        self._warn_insecure(self._config.verify)
+        if http_client.follow_redirects:
+            warnings.warn(
+                "custom http_client has follow_redirects=True; "
+                "configured headers may be forwarded on cross-origin redirects",
+                RuntimeWarning,
+                stacklevel=3,
+            )
+        self._client = http_client
+        self._owns_client = False
+
+    def _create_client(self) -> None:
+        self._warn_insecure(self._config.verify)
+        timeout: float | httpx.Timeout | None = self._config.timeout
+        self._client = httpx.Client(
+            base_url=self._config.base_url,
+            verify=self._coerce_verify(self._config.verify),
+            timeout=timeout if timeout is not None else httpx.Timeout(None),
+            follow_redirects=self._config.follow_redirects,
+            trust_env=self._config.trust_env,
+            headers={
+                "User-Agent": self._config.user_agent,
+                **dict(self._config.headers),
+            },
+        )
+        self._owns_client = True
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = config
+        if http_client is not None:
+            self._use_custom_client(http_client)
+        else:
+            self._create_client()
+
+    @property
+    def client(self) -> httpx.Client:
+        return self._client
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._config
+
+    def _request_once(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any,
+        content: Any,
+        form_data: Any,
+        files: Any,
+        headers: Mapping[str, str] | None,
+        timeout: Any,
+        follow_redirects: bool | None,
+    ) -> httpx.Response:
+        try:
+            return self._client.request(
+                method,
+                path,
+                params=params,
+                content=content,
+                data=form_data,
+                files=files,
+                headers={**dict(self._config.headers), **dict(headers or {})},
+                timeout=timeout,
+                follow_redirects=(
+                    follow_redirects
+                    if follow_redirects is not None
+                    else self._config.follow_redirects
+                ),
+            )
+        except httpx.TimeoutException as exc:
+            raise RequestTimeoutError(str(exc)) from exc
+        except (httpx.RequestError, httpx.InvalidURL) as exc:
+            raise TransportError(str(exc)) from exc
+
+    @staticmethod
+    def _can_retry(idempotent: bool, attempt: int, attempts: int) -> bool:
+        return idempotent and attempt + 1 < attempts
+
+    @staticmethod
+    def _is_retryable_status(status_code: int) -> bool:
+        return status_code in {429, 502, 503, 504}
+
+    def _check_response_size(self, response: httpx.Response) -> None:
+        limit = self._config.max_response_bytes
+        if limit is None:
+            return
+        if len(response.content) <= limit:
+            return
+        response.close()
+        raise ProtocolError(
+            f"response exceeds {limit} bytes",
+            status_code=response.status_code,
+        )
+
+    def _handle_response(
+        self,
+        response: httpx.Response,
+        *,
+        idempotent: bool,
+        attempt: int,
+        attempts: int,
+    ) -> httpx.Response | None:
+        self._check_response_size(response)
+        if not self._is_retryable_status(response.status_code):
+            return response
+        if not self._can_retry(idempotent, attempt, attempts):
+            return response
+        response.close()
+        self._sleep(attempt, response.headers.get("retry-after"))
+        return None
+
+    def _request_attempt(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any,
+        content: Any,
+        form_data: Any,
+        files: Any,
+        headers: Mapping[str, str] | None,
+        idempotent: bool,
+        timeout: Any,
+        follow_redirects: bool | None,
+        attempt: int,
+        attempts: int,
+    ) -> httpx.Response | None:
+        try:
+            response = self._request_once(
+                method,
+                path,
+                params=params,
+                content=content,
+                form_data=form_data,
+                files=files,
+                headers=headers,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+            )
+        except RuntimeError as exc:
+            raise TransportError(str(exc)) from exc
+        except (RequestTimeoutError, TransportError):
+            if not self._can_retry(idempotent, attempt, attempts):
+                raise
+            self._sleep(attempt)
+            return None
+        return self._handle_response(
+            response,
+            idempotent=idempotent,
+            attempt=attempt,
+            attempts=attempts,
+        )
+
+    def _request_loop(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any,
+        content: Any,
+        form_data: Any,
+        files: Any,
+        headers: Mapping[str, str] | None,
+        idempotent: bool,
+        timeout: Any,
+        follow_redirects: bool | None,
+    ) -> httpx.Response:
+        attempts = self._config.max_retries + 1
+        for attempt in range(attempts):
+            response = self._request_attempt(
+                method,
+                path,
+                params=params,
+                content=content,
+                form_data=form_data,
+                files=files,
+                headers=headers,
+                idempotent=idempotent,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+                attempt=attempt,
+                attempts=attempts,
+            )
+            if response is not None:
+                return response
+        raise TransportError("transport failed")  # pragma: no cover
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        data: Any = None,
+        files: Any = None,
+        headers: Mapping[str, str] | None = None,
+        idempotent: bool = False,
+        timeout: Any = _UNSET,
+        follow_redirects: bool | None = None,
+    ) -> httpx.Response:
+        method = method.upper()
+        clean_path = _normalize_path(path)
+        request_timeout = self._config.timeout if timeout is _UNSET else timeout
+        content = data if isinstance(data, (str, bytes)) else None
+        form_data = None if content is not None else data
+        return self._request_loop(
+            method,
+            clean_path,
+            params=params,
+            content=content,
+            form_data=form_data,
+            files=files,
+            headers=headers,
+            idempotent=idempotent,
+            timeout=request_timeout,
+            follow_redirects=follow_redirects,
+        )
+
+    @staticmethod
+    def _raise_stream_timeout(
+        exc: httpx.TimeoutException,
+        started: bool,
+        attempt: int,
+        attempts: int,
+    ) -> None:
+        if started or attempt + 1 >= attempts:
+            raise RequestTimeoutError(str(exc)) from exc
+
+    @staticmethod
+    def _raise_stream_request_error(
+        exc: httpx.RequestError | httpx.InvalidURL,
+        started: bool,
+        attempt: int,
+        attempts: int,
+    ) -> None:
+        if started or attempt + 1 >= attempts:
+            raise TransportError(str(exc)) from exc
+
+    def _stream_setup(
+        self,
+        method: str,
+        path: str,
+        data: Any,
+        timeout: Any,
+        idempotent: bool,
+    ) -> tuple[str, str, Any, Any, Any, int]:
+        content = data if isinstance(data, (str, bytes)) else None
+        return (
+            method.upper(),
+            _normalize_path(path),
+            self._config.timeout if timeout is _UNSET else timeout,
+            content,
+            None if content is not None else data,
+            self._config.max_retries + 1 if idempotent else 1,
+        )
+
+    @staticmethod
+    def _handle_stream_exception(
+        exc: Exception,
+        started: bool,
+        attempt: int,
+        attempts: int,
+    ) -> None:
+        if isinstance(exc, httpx.TimeoutException):
+            HttpTransport._raise_stream_timeout(exc, started, attempt, attempts)
+        elif isinstance(exc, (httpx.RequestError, httpx.InvalidURL)):
+            HttpTransport._raise_stream_request_error(exc, started, attempt, attempts)
+        else:
+            raise TransportError(str(exc)) from exc
+
+    def _stream_loop(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any,
+        content: Any,
+        form_data: Any,
+        headers: Mapping[str, str] | None,
+        timeout: Any,
+        attempts: int,
+    ) -> Iterator[httpx.Response]:
+        started = False
+        for attempt in range(attempts):
+            try:
+                with self._client.stream(
+                    method,
+                    path,
+                    params=params,
+                    content=content,
+                    data=form_data,
+                    headers={**dict(self._config.headers), **dict(headers or {})},
+                    timeout=timeout,
+                ) as response:
+                    started = True
+                    yield response
+                    return
+            except (
+                httpx.TimeoutException,
+                httpx.RequestError,
+                httpx.InvalidURL,
+                RuntimeError,
+            ) as exc:
+                self._handle_stream_exception(exc, started, attempt, attempts)
+            self._sleep(attempt)
+        raise TransportError("stream failed")  # pragma: no cover - loop always returns or raises
+
+    @contextlib.contextmanager
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Any = None,
+        data: Any = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: Any = _UNSET,
+        idempotent: bool = True,
+    ) -> Iterator[httpx.Response]:
+        method, clean_path, request_timeout, content, form_data, attempts = self._stream_setup(
+            method, path, data, timeout, idempotent
+        )
+        yield from self._stream_loop(
+            method,
+            clean_path,
+            params=params,
+            content=content,
+            form_data=form_data,
+            headers=headers,
+            timeout=request_timeout,
+            attempts=attempts,
+        )
+
+    def get_cookie(self, name: str) -> str | None:
+        return self._client.cookies.get(name)
+
+    def clear_cookies(self, names: Iterable[str] | None = None) -> None:
+        if names is None:
+            self._client.cookies.clear()
+            return
+        for name in names:
+            self._client.cookies.delete(name)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def _sleep(self, attempt: int, retry_after: str | None = None) -> None:
+        if retry_after:
+            try:
+                delay = min(float(retry_after), 30.0)
+            except ValueError:
+                delay = self._config.retry_backoff * (2**attempt)
+        else:
+            delay = self._config.retry_backoff * (2**attempt)
+        if delay > 0:
+            time.sleep(delay)
+
+
+def _validate_path_origin(clean: str) -> None:
+    if not clean:
+        raise ConfigurationError("empty request path")
+    if "://" in clean or clean.startswith("//"):
+        raise ConfigurationError("absolute URLs are not allowed")
+
+
+def _validate_path_segments(clean: str) -> None:
+    parts = clean.split("/")
+    if any(part in {"..", "."} for part in parts):
+        raise ConfigurationError("path traversal is not allowed")
+    if "?" in clean or "#" in clean:
+        raise ConfigurationError("put query parameters in params=")
+
+
+def _normalize_path(path: str) -> str:
+    clean = path.strip()
+    _validate_path_origin(clean)
+    _validate_path_segments(clean)
+    return clean.lstrip("/")
+
+
+def build_form(
+    params: Mapping[str, Any] | Iterable[tuple[str, Any]] | None = None, **kwargs: Any
+) -> str:
+    return encode_params(params, **kwargs)

ugos/catalog.py

@@ -0,0 +1,184 @@
+"""API action catalog."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from collections.abc import Mapping
+from importlib import resources
+from typing import Any
+
+from .exceptions import CatalogError, UnknownActionError, UnknownControllerError
+
+_CONTRACT_METHODS = frozenset({"GET", "POST", "HEAD", "OPTIONS", "PUT", "PATCH", "DELETE"})
+_CONTRACT_ID_LOCATIONS = frozenset({"param", "data", "data_list"})
+_CONTRACT_RESPONSE_KINDS = frozenset({"auto", "json", "text", "bytes", "list", "object", "scalar"})
+
+
+@dataclasses.dataclass(frozen=True)
+class ActionContract:
+    """Request/response contract for one controller action."""
+
+    method: str = "POST"
+    id_param: str = "id"
+    id_location: str = "data"
+    response_kind: str = "auto"
+    json_fields: tuple[str, ...] = ()
+    idempotent: bool | None = None
+
+
+def _catalog_version(data: Mapping[str, Any]) -> str | None:
+    product = data.get("product", {})
+    if not isinstance(product, Mapping):
+        return None
+    return product.get("version")
+
+
+def _parse_controllers(raw: Mapping[str, Any]) -> dict[str, frozenset[str]]:
+    return {
+        str(name): frozenset(str(action) for action in actions if str(action) != "_routes")
+        for name, actions in raw.items()
+    }
+
+
+class Catalog:
+    """Read-only controller/action catalog."""
+
+    def __init__(
+        self,
+        data: Mapping[str, Any],
+        *,
+        contracts: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._data = dict(data)
+        self.version = _catalog_version(self._data)
+        self._controllers = _parse_controllers(self._data.get("controllers", {}))
+        self._contracts = _parse_contracts(contracts or {})
+        self._check_contracts()
+
+    def _check_contracts(self) -> None:
+        unknown = sorted(
+            f"{controller}/{action}"
+            for controller, action in self._contracts
+            if not self.has_action(controller, action)
+        )
+        if unknown:
+            raise CatalogError(f"contracts reference unknown actions: {', '.join(unknown)}")
+
+    @property
+    def controllers(self) -> frozenset[str]:
+        return frozenset(self._controllers)
+
+    @property
+    def action_count(self) -> int:
+        return sum(len(actions) for actions in self._controllers.values())
+
+    def has_controller(self, controller: str) -> bool:
+        return controller in self._controllers
+
+    def has_action(self, controller: str, action: str) -> bool:
+        return action in self._controllers.get(controller, frozenset())
+
+    def actions(self, controller: str) -> frozenset[str]:
+        if controller not in self._controllers:
+            raise UnknownControllerError(f"unknown controller: {controller}")
+        return self._controllers[controller]
+
+    def check(self, controller: str, action: str) -> None:
+        if controller not in self._controllers:
+            raise UnknownControllerError(f"unknown controller: {controller}")
+        if action not in self._controllers[controller]:
+            raise UnknownActionError(f"unknown action: {controller}/{action}")
+
+    def action_contract(self, controller: str, action: str) -> ActionContract | None:
+        return self._contracts.get((controller, action))
+
+    @property
+    def contract_count(self) -> int:
+        return len(self._contracts)
+
+
+def _validate_contract_schema(data: Mapping[str, Any]) -> None:
+    if data.get("schema_version") not in (None, 1):
+        raise CatalogError(f"unsupported action contract schema: {data.get('schema_version')!r}")
+
+
+def _contracts_mapping(data: Mapping[str, Any]) -> Mapping[str, Any]:
+    raw = data.get("contracts", data)
+    if not isinstance(raw, Mapping):
+        raise CatalogError("action contracts must be a mapping")
+    return raw
+
+
+def _validate_contract_fields(
+    controller: str,
+    action: str,
+    method: str,
+    id_location: str,
+    response_kind: str,
+) -> None:
+    if method not in _CONTRACT_METHODS:
+        raise CatalogError(f"invalid method in contract {controller}/{action}: {method!r}")
+    if id_location not in _CONTRACT_ID_LOCATIONS:
+        raise CatalogError(
+            f"invalid id_location in contract {controller}/{action}: {id_location!r}"
+        )
+    if response_kind not in _CONTRACT_RESPONSE_KINDS:
+        raise CatalogError(
+            f"invalid response_kind in contract {controller}/{action}: {response_kind!r}"
+        )
+
+
+def _parse_contract(controller: str, action: str, spec: Mapping[str, Any]) -> ActionContract:
+    method = str(spec.get("method", "POST")).upper()
+    id_location = str(spec.get("id_location", "data"))
+    response_kind = str(spec.get("response_kind", "auto"))
+    _validate_contract_fields(controller, action, method, id_location, response_kind)
+    idempotent = spec.get("idempotent")
+    return ActionContract(
+        method=method,
+        id_param=str(spec.get("id_param", "id")),
+        id_location=id_location,
+        response_kind=response_kind,
+        json_fields=tuple(str(field) for field in spec.get("json_fields", ())),
+        idempotent=idempotent if isinstance(idempotent, bool) else None,
+    )
+
+
+def _parse_controller_contracts(
+    controller: str,
+    actions: Mapping[str, Any],
+) -> dict[tuple[str, str], ActionContract]:
+    result: dict[tuple[str, str], ActionContract] = {}
+    for action, spec in actions.items():
+        if not isinstance(spec, Mapping):
+            raise CatalogError(f"contract {controller}/{action} must be a mapping")
+        result[(str(controller), str(action))] = _parse_contract(str(controller), str(action), spec)
+    return result
+
+
+def _parse_contracts(data: Mapping[str, Any]) -> dict[tuple[str, str], ActionContract]:
+    _validate_contract_schema(data)
+    raw = _contracts_mapping(data)
+    result: dict[tuple[str, str], ActionContract] = {}
+    for controller, actions in raw.items():
+        if controller == "schema_version":
+            continue
+        if not isinstance(actions, Mapping):
+            raise CatalogError(f"contracts for {controller!r} must be a mapping")
+        result.update(_parse_controller_contracts(str(controller), actions))
+    return result
+
+
+def load_catalog() -> Catalog:
+    root = resources.files("ugos._data")
+    data_file = root.joinpath("catalog.json")
+    with data_file.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    contracts_file = root.joinpath("action_contracts.json")
+    try:
+        with contracts_file.open("r", encoding="utf-8") as handle:
+            contracts = json.load(handle)
+    except FileNotFoundError as exc:
+        raise CatalogError("action_contracts.json is missing from the package") from exc
+    return Catalog(data, contracts=contracts)