UGOS 1.0.0__py3-none-any.whl

ugos/_codec.py

@@ -0,0 +1,528 @@
+"""Response decoding and API error mapping."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._redaction import redact_text
+from .exceptions import (
+    AccessDeniedError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    CSRFError,
+    DecodeError,
+    DuplicateError,
+    HTTPStatusError,
+    NotFoundError,
+    ProtocolError,
+    ReadOnlyListError,
+    ServerError,
+    SessionExpiredError,
+    UGOSError,
+    ValidationError,
+)
+
+SESSION_EXPIRED_CODES = frozenset({4, 104, 22000})
+ACCESS_DENIED_CODES = frozenset({102, 10007})
+AUTHENTICATION_CODES = frozenset({109, 10002, 7004, 7009, 10001, 10010, 20002})
+VALIDATION_CODES = frozenset({10, 11, 14, 107, 110, 111, 601, 603, 618})
+PROTOCOL_CODES = frozenset({3, 112, 616})
+SERVER_CODES = frozenset({2, 500, 608})
+NOT_FOUND_CODES = frozenset({105, 404, 3056, 3057, 5001, 5005})
+DUPLICATE_CODES = frozenset({9, 409, 1019, 2001, 5002, 8001, 21003, 21004, 21005})
+CONFLICT_CODES = frozenset({502, 3003, 4002, 4003, 7012, 7013})
+READ_ONLY_LIST_CODES = frozenset({2010})
+_SUCCESS_CODES = frozenset({200, 201, 202, 204})
+
+_ERROR_CLASSES = (
+    (SESSION_EXPIRED_CODES, SessionExpiredError),
+    (ACCESS_DENIED_CODES, AccessDeniedError),
+    (AUTHENTICATION_CODES, AuthenticationError),
+    (VALIDATION_CODES, ValidationError),
+    (PROTOCOL_CODES, ProtocolError),
+    (SERVER_CODES, ServerError),
+    (READ_ONLY_LIST_CODES, ReadOnlyListError),
+    (NOT_FOUND_CODES, NotFoundError),
+    (DUPLICATE_CODES, DuplicateError),
+)
+
+_EXPECT_VALUES = frozenset({"auto", "json", "text", "bytes", "list", "object", "scalar"})
+
+
+def _body_snippet(response: httpx.Response, limit: int = 2048) -> str:
+    # Redact before truncating: a secret longer than the limit would otherwise
+    # be cut in the middle and escape the redaction regexes.
+    return redact_text(response.text)[:limit]
+
+
+def _is_error_code_value(value: Any) -> bool:
+    return value not in (None, 0, "0") and _as_int(value) not in _SUCCESS_CODES
+
+
+def _has_error_code(payload: Mapping[str, Any]) -> bool:
+    return any(_is_error_code_value(payload.get(key)) for key in ("errorCode", "error_code"))
+
+
+def _has_error_message(payload: Mapping[str, Any]) -> bool:
+    code = _as_int(payload.get("code"))
+    if code in (None, 0, *_SUCCESS_CODES):
+        return False
+    return bool(payload.get("error") or payload.get("error_description") or payload.get("message"))
+
+
+def is_error_payload(payload: Any) -> bool:
+    if not isinstance(payload, Mapping):
+        return False
+    if payload.get("success") is False:
+        return True
+    if _has_error_code(payload):
+        return True
+    return _has_error_message(payload)
+
+
+def _as_int(value: Any) -> int | None:
+    try:
+        if value is None or value == "":
+            return None
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _conflict_exception(status_code: int | None) -> type[UGOSError]:
+    if status_code is not None and status_code >= 500:
+        return ServerError
+    return ConflictError
+
+
+def _exception_for_code(
+    code: int | None,
+    status_code: int | None,
+) -> type[UGOSError]:
+    if code in CONFLICT_CODES:
+        return _conflict_exception(status_code)
+    for codes, exception in _ERROR_CLASSES:
+        if code in codes:
+            return exception
+    return APIError
+
+
+def error_from_payload(
+    payload: Mapping[str, Any],
+    *,
+    status_code: int | None = None,
+    controller: str | None = None,
+    action: str | None = None,
+) -> UGOSError:
+    code = _as_int(payload.get("errorCode") or payload.get("error_code") or payload.get("code"))
+    message = redact_text(str(payload.get("error") or payload.get("message") or "API error"))
+    exception = _exception_for_code(code, status_code)
+    return exception(
+        message,
+        code=code,
+        status_code=status_code,
+        payload=payload,
+        controller=controller,
+        action=action,
+    )
+
+
+_TEXT_FALLBACK = object()
+
+
+def _raise_redirect(response: httpx.Response, controller: str | None, action: str | None) -> None:
+    location = response.headers.get("location", "")
+    if "utm/login" in location or location.rstrip("/").endswith("/login"):
+        raise SessionExpiredError(
+            "session expired or login required",
+            status_code=response.status_code,
+            controller=controller,
+            action=action,
+        )
+    raise HTTPStatusError(
+        f"unexpected redirect: HTTP {response.status_code}",
+        status_code=response.status_code,
+        payload=_body_snippet(response),
+        controller=controller,
+        action=action,
+    )
+
+
+def _is_csrf_failure(status_code: int, text: str) -> bool:
+    if status_code not in {400, 403}:
+        return False
+    lowered = text.lower()
+    return any(
+        phrase in lowered
+        for phrase in (
+            "csrf verification failed",
+            "csrf token missing",
+            "csrf token incorrect",
+            "csrf token invalid",
+            "csrf token not found",
+            "csrf cookie not set",
+            "csrf failed",
+        )
+    )
+
+
+def _raise_server_response(
+    response: httpx.Response,
+    text: str,
+    controller: str | None,
+    action: str | None,
+) -> None:
+    payload = _try_json(text)
+    if is_error_payload(payload):
+        raise error_from_payload(
+            payload,
+            status_code=response.status_code,
+            controller=controller,
+            action=action,
+        )
+    raise ServerError(
+        f"HTTP {response.status_code}",
+        status_code=response.status_code,
+        payload=_body_snippet(response),
+        controller=controller,
+        action=action,
+    )
+
+
+def _raise_client_response(
+    response: httpx.Response,
+    text: str,
+    controller: str | None,
+    action: str | None,
+) -> None:
+    payload = _try_json(text)
+    if is_error_payload(payload):
+        raise error_from_payload(
+            payload,
+            status_code=response.status_code,
+            controller=controller,
+            action=action,
+        )
+    raise HTTPStatusError(
+        f"HTTP {response.status_code}",
+        status_code=response.status_code,
+        payload=_body_snippet(response),
+        controller=controller,
+        action=action,
+    )
+
+
+def _raise_redirect_or_unauthorized(
+    response: httpx.Response,
+    controller: str | None,
+    action: str | None,
+) -> None:
+    status = response.status_code
+    if 300 <= status < 400:
+        _raise_redirect(response, controller, action)
+    if status == 401:
+        raise SessionExpiredError(
+            "unauthorized",
+            status_code=status,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+
+
+def _raise_csrf_or_status(
+    response: httpx.Response,
+    text: str,
+    controller: str | None,
+    action: str | None,
+) -> None:
+    status = response.status_code
+    if _is_csrf_failure(status, text):
+        raise CSRFError(
+            "CSRF validation failed",
+            status_code=status,
+            payload=text,
+            controller=controller,
+            action=action,
+        )
+    if status >= 500:
+        _raise_server_response(response, text, controller, action)
+    if status >= 400:
+        _raise_client_response(response, text, controller, action)
+
+
+def _raise_for_http_status(
+    response: httpx.Response,
+    text: str,
+    controller: str | None,
+    action: str | None,
+) -> None:
+    _raise_redirect_or_unauthorized(response, controller, action)
+    _raise_csrf_or_status(response, text, controller, action)
+
+
+def _empty_response(
+    response: httpx.Response,
+    expect: str,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    if expect == "auto":
+        return None
+    raise DecodeError(
+        f"expected a {expect} response, got an empty body",
+        status_code=response.status_code,
+        payload=_body_snippet(response),
+        controller=controller,
+        action=action,
+    )
+
+
+def _decode_json_response(
+    response: httpx.Response,
+    text: str,
+    expect: str,
+    is_json_content: bool,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        if expect == "json" or is_json_content:
+            raise DecodeError(
+                f"invalid JSON response: {exc}",
+                status_code=response.status_code,
+                payload=_body_snippet(response),
+                controller=controller,
+                action=action,
+            ) from exc
+        return _TEXT_FALLBACK
+    if is_error_payload(payload):
+        raise error_from_payload(
+            payload,
+            status_code=response.status_code,
+            controller=controller,
+            action=action,
+        )
+    return _check_shape(
+        payload,
+        expect,
+        response=response,
+        controller=controller,
+        action=action,
+    )
+
+
+def _raise_or_return_text(
+    response: httpx.Response,
+    text: str,
+    expect: str,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    if _looks_like_login_html(text):
+        raise SessionExpiredError(
+            "session expired or a login page was returned",
+            status_code=response.status_code,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+    if _looks_like_html(response.headers.get("content-type", "").lower(), text):
+        raise ProtocolError(
+            "expected a JSON API response, got HTML",
+            status_code=response.status_code,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+    if expect == "json":
+        raise DecodeError(
+            "expected JSON response",
+            status_code=response.status_code,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+    if expect in {"list", "object", "scalar"}:
+        raise DecodeError(
+            f"expected a {expect} response",
+            status_code=response.status_code,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+    return text
+
+
+def _decode_body(
+    response: httpx.Response,
+    text: str,
+    expect: str,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    content_type = response.headers.get("content-type", "").lower()
+    is_json_content = "json" in content_type
+    if not is_json_content and _is_numeric_error_body(text):
+        raise ServerError(
+            f"upstream returned error code {text.strip()}",
+            status_code=response.status_code,
+            payload=_body_snippet(response),
+            controller=controller,
+            action=action,
+        )
+    if is_json_content or _looks_like_json(text):
+        return _decode_json_or_text(
+            response,
+            text,
+            expect,
+            is_json_content,
+            controller,
+            action,
+        )
+    return _raise_or_return_text(response, text, expect, controller, action)
+
+
+def _decode_json_or_text(
+    response: httpx.Response,
+    text: str,
+    expect: str,
+    is_json_content: bool,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    result = _decode_json_response(
+        response,
+        text,
+        expect,
+        is_json_content,
+        controller,
+        action,
+    )
+    if result is _TEXT_FALLBACK:
+        return _raise_or_return_text(response, text, expect, controller, action)
+    return result
+
+
+def _decode_success(
+    response: httpx.Response,
+    text: str,
+    expect: str,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    if expect == "bytes":
+        return response.content
+    if expect == "text":
+        return text
+    if not response.content or response.status_code == 204:
+        return _empty_response(response, expect, controller, action)
+    return _decode_body(response, text, expect, controller, action)
+
+
+def parse_response(
+    response: httpx.Response,
+    *,
+    expect: str = "auto",
+    controller: str | None = None,
+    action: str | None = None,
+) -> Any:
+    """Decode a response or raise a mapped exception."""
+
+    if expect not in _EXPECT_VALUES:
+        raise ValueError(f"unsupported expect value: {expect!r}")
+    text = response.text
+    _raise_for_http_status(response, text, controller, action)
+    return _decode_success(response, text, expect, controller, action)
+
+
+def _is_list_payload(payload: Any) -> bool:
+    if isinstance(payload, list):
+        return True
+    return isinstance(payload, Mapping) and isinstance(payload.get("items"), list)
+
+
+def _matches_expect(payload: Any, expect: str) -> bool:
+    if expect == "object":
+        return isinstance(payload, Mapping)
+    if expect == "list":
+        return _is_list_payload(payload)
+    if expect == "scalar":
+        return not isinstance(payload, (Mapping, list, tuple))
+    return False
+
+
+def _check_shape(
+    payload: Any,
+    expect: str,
+    *,
+    response: httpx.Response,
+    controller: str | None,
+    action: str | None,
+) -> Any:
+    if expect in {"auto", "json"}:
+        return payload
+    if _matches_expect(payload, expect):
+        return payload
+    raise DecodeError(
+        f"expected a {expect} response",
+        status_code=response.status_code,
+        payload=_body_snippet(response),
+        controller=controller,
+        action=action,
+    )
+
+
+def _is_numeric_error_body(text: str) -> bool:
+    stripped = text.strip()
+    return stripped.isdigit() and len(stripped) == 3 and 400 <= int(stripped) <= 599
+
+
+def _looks_like_html(content_type: str, text: str) -> bool:
+    if "html" in content_type:
+        return True
+    head = text.lstrip()[:128].lower()
+    return head.startswith("<!doctype html") or head.startswith("<html")
+
+
+def _looks_like_login_html(text: str) -> bool:
+    lowered = text.lower()
+    if not _looks_like_html("", text):
+        return False
+    if "utm/login" in lowered:
+        return True
+    return any(
+        marker in lowered
+        for marker in (
+            'name="csrfmiddlewaretoken"',
+            "name='csrfmiddlewaretoken'",
+            'action="/utm/login',
+            "action='/utm/login",
+            "<title>login",
+        )
+    )
+
+
+def _try_json(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return None
+
+
+def _looks_like_json(text: str) -> bool:
+    stripped = text.lstrip()
+    if not stripped:
+        return False
+    if stripped[0] in '[{"':
+        return True
+    return (
+        stripped in {"true", "false", "null"} or stripped.replace(".", "", 1).lstrip("-").isdigit()
+    )

ugos/_config.py

@@ -0,0 +1,183 @@
+"""Client configuration and URL normalization."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+
+from .__about__ import __version__
+from .exceptions import ConfigurationError
+
+DEFAULT_PORT = 8001
+DEFAULT_TIMEOUT = 30.0
+
+
+def _validate_base_args(base_url: str | None, host: str | None) -> None:
+    if base_url and host:
+        raise ConfigurationError("pass either base_url or host, not both")
+    if not base_url and not host:
+        raise ConfigurationError("base_url or host is required")
+
+
+def _host_base_url(host: str, port: int, scheme: str) -> str:
+    if "://" in host:
+        raise ConfigurationError("host must not contain a scheme")
+    return f"{scheme}://{host}:{port}"
+
+
+def _with_scheme(raw: str) -> str:
+    if "://" not in raw:
+        return f"https://{raw}"
+    return raw
+
+
+def _raw_base_url(
+    base_url: str | None,
+    host: str | None,
+    port: int,
+    scheme: str,
+) -> str:
+    _validate_base_args(base_url, host)
+    if host:
+        return _host_base_url(host, port, scheme)
+    if base_url is None:  # pragma: no cover - guarded by _validate_base_args
+        raise ConfigurationError("base_url is required")
+    return base_url.strip()
+
+
+def _validate_credentials(parts: Any) -> None:
+    if parts.username or parts.password:
+        raise ConfigurationError("credentials in the URL are not allowed")
+
+
+def _validate_scheme_host(parts: Any) -> None:
+    if parts.scheme not in {"http", "https"}:
+        raise ConfigurationError(f"unsupported URL scheme: {parts.scheme}")
+    if not parts.hostname:
+        raise ConfigurationError("base_url has no host")
+
+
+def _validate_query_fragment(parts: Any) -> None:
+    if parts.query or parts.fragment:
+        raise ConfigurationError("base_url must not contain query or fragment")
+
+
+def _validate_url_parts(parts: Any) -> None:
+    _validate_credentials(parts)
+    _validate_scheme_host(parts)
+    _validate_query_fragment(parts)
+
+
+def _default_netloc(hostname: str) -> str:
+    if ":" in hostname and not hostname.startswith("["):
+        return f"[{hostname}]:{DEFAULT_PORT}"
+    return f"{hostname}:{DEFAULT_PORT}"
+
+
+def _netloc(parts: Any) -> str:
+    try:
+        port = parts.port
+    except ValueError as exc:
+        raise ConfigurationError(f"invalid port in base_url: {exc}") from exc
+    if port is None:
+        return _default_netloc(parts.hostname)
+    return parts.netloc
+
+
+def _path_with_slash(path: str) -> str:
+    if not path:
+        return "/"
+    if path.endswith("/"):
+        return path
+    return f"{path}/"
+
+
+def normalize_base_url(
+    base_url: str | None = None,
+    *,
+    host: str | None = None,
+    port: int = DEFAULT_PORT,
+    scheme: str = "https",
+) -> str:
+    """Return a normalized ``https://host:port/`` base URL."""
+
+    raw = _with_scheme(_raw_base_url(base_url, host, port, scheme))
+    parts = urlsplit(raw)
+    _validate_url_parts(parts)
+    return urlunsplit((parts.scheme, _netloc(parts), _path_with_slash(parts.path), "", ""))
+
+
+@dataclasses.dataclass(frozen=True)
+class ClientConfig:
+    base_url: str
+    verify: bool | str | Path = True
+    timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT
+    headers: Mapping[str, str] = dataclasses.field(default_factory=dict, repr=False)
+    user_agent: str = f"ugos/{__version__}"
+    trust_env: bool = False
+    follow_redirects: bool = False
+    max_retries: int = 2
+    retry_backoff: float = 0.25
+    thread_safe: bool = True
+    max_download_bytes: int | None = 64 * 1024 * 1024
+    max_response_bytes: int | None = 16 * 1024 * 1024
+    allow_insecure_http: bool = False
+
+    @staticmethod
+    def _validate_transport(base_url: str, allow_insecure_http: bool) -> None:
+        if base_url.startswith("http://") and not allow_insecure_http:
+            raise ConfigurationError(
+                "plain HTTP is disabled; pass allow_insecure_http=True for a trusted test environment"
+            )
+
+    @staticmethod
+    def _validate_limits(max_download_bytes: int | None, max_response_bytes: int | None) -> None:
+        if max_download_bytes is not None and max_download_bytes < 0:
+            raise ConfigurationError("max_download_bytes must be non-negative")
+        if max_response_bytes is not None and max_response_bytes < 0:
+            raise ConfigurationError("max_response_bytes must be non-negative")
+
+    @classmethod
+    def build(
+        cls,
+        base_url: str | None = None,
+        *,
+        host: str | None = None,
+        port: int = DEFAULT_PORT,
+        scheme: str = "https",
+        verify: bool | str | Path = True,
+        timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
+        headers: Mapping[str, str] | None = None,
+        user_agent: str | None = None,
+        trust_env: bool = False,
+        follow_redirects: bool = False,
+        max_retries: int = 2,
+        retry_backoff: float = 0.25,
+        thread_safe: bool = True,
+        max_download_bytes: int | None = 64 * 1024 * 1024,
+        max_response_bytes: int | None = 16 * 1024 * 1024,
+        allow_insecure_http: bool = False,
+    ) -> ClientConfig:
+        normalized = normalize_base_url(base_url, host=host, port=port, scheme=scheme)
+        cls._validate_transport(normalized, allow_insecure_http)
+        cls._validate_limits(max_download_bytes, max_response_bytes)
+        return cls(
+            base_url=normalized,
+            verify=verify,
+            timeout=timeout,
+            headers=dict(headers or {}),
+            user_agent=user_agent or f"ugos/{__version__}",
+            trust_env=trust_env,
+            follow_redirects=follow_redirects,
+            max_retries=max(0, max_retries),
+            retry_backoff=max(0.0, retry_backoff),
+            thread_safe=thread_safe,
+            max_download_bytes=max_download_bytes,
+            max_response_bytes=max_response_bytes,
+            allow_insecure_http=allow_insecure_http,
+        )

ugos/_data/__init__.py

@@ -0,0 +1 @@
+"""Generated package data."""