mywebapi-sdk 0.3.0__py3-none-any.whl

cplugin_webapi_sdk/discovery.py

@@ -0,0 +1,109 @@
+"""OIDC discovery — fetches ``.well-known/openid-configuration`` once and
+caches the parsed document for the lifetime of the process.
+
+Sync and async paths share the same cache: the first caller to populate it
+wins, all subsequent callers (sync or async) get the cached document with no
+further network IO. Locks guard only the *first* fetch — once cached, reads
+are lock-free.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any
+
+import httpx
+
+
+class OidcDiscovery:
+    """Single-flight OIDC discovery document fetcher."""
+
+    def __init__(
+        self,
+        identity_url: str,
+        http_sync: httpx.Client | None = None,
+        http_async: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._identity_url = identity_url.rstrip("/")
+        self._http_sync = http_sync
+        self._http_async = http_async
+        self._cached: dict[str, Any] | None = None
+        self._lock_sync = threading.Lock()
+        self._lock_async = asyncio.Lock()
+
+    @property
+    def discovery_url(self) -> str:
+        return f"{self._identity_url}/.well-known/openid-configuration"
+
+    def get_sync(self) -> dict[str, Any]:
+        # Fast path — lock-free read once populated.
+        if self._cached is not None:
+            return self._cached
+        with self._lock_sync:
+            if self._cached is not None:
+                return self._cached
+            client = self._http_sync or httpx.Client()
+            owns_client = self._http_sync is None
+            try:
+                r = client.get(self.discovery_url)
+            finally:
+                if owns_client:
+                    client.close()
+            self._cached = self._validate_doc(self._parse_response(r))
+            return self._cached
+
+    async def get_async(self) -> dict[str, Any]:
+        if self._cached is not None:
+            return self._cached
+        async with self._lock_async:
+            if self._cached is not None:
+                return self._cached
+            client = self._http_async or httpx.AsyncClient()
+            owns_client = self._http_async is None
+            try:
+                r = await client.get(self.discovery_url)
+            finally:
+                if owns_client:
+                    await client.aclose()
+            self._cached = self._validate_doc(self._parse_response(r))
+            return self._cached
+
+    @staticmethod
+    def _parse_response(r: httpx.Response) -> dict[str, Any]:
+        # Defer import to avoid circular dependency at module import time.
+        from .auth import OAuth2TokenError
+
+        if r.status_code < 200 or r.status_code >= 300:
+            raise OAuth2TokenError(
+                status_code=r.status_code,
+                error="discovery_failed",
+                error_description=f"OIDC discovery returned HTTP {r.status_code}",
+            )
+        try:
+            doc = r.json()
+        except Exception as e:  # noqa: BLE001
+            raise OAuth2TokenError(
+                status_code=r.status_code,
+                error="discovery_failed",
+                error_description=f"OIDC discovery response was not JSON: {e}",
+            ) from e
+        if not isinstance(doc, dict):
+            raise OAuth2TokenError(
+                status_code=r.status_code,
+                error="discovery_failed",
+                error_description="OIDC discovery document was not a JSON object",
+            )
+        return doc
+
+    @staticmethod
+    def _validate_doc(doc: dict[str, Any]) -> dict[str, Any]:
+        from .auth import OAuth2TokenError
+
+        endpoint = doc.get("token_endpoint")
+        if not isinstance(endpoint, str) or not endpoint:
+            raise OAuth2TokenError(
+                status_code=0,
+                error="discovery_invalid",
+                error_description="OIDC discovery document missing token_endpoint",
+            )
+        return doc

cplugin_webapi_sdk/envelope.py

@@ -0,0 +1,77 @@
+"""v2 response envelope: {data, error, meta}.
+
+Mirrors the TS SDK's ApiEnvelope[T] / ApiErrorBody / ApiMeta / PagingMeta.
+The server always returns HTTP 200 and signals failure in-envelope via a
+non-null ``error``. Field aliases map the server's camelCase JSON to
+snake_case Python attributes.
+
+Schema reference: spec/v2.json components.schemas.{ApiError,ApiMeta,PagingMeta}.
+"""
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+T = TypeVar("T")
+
+# * Stable transport-level error codes (WebApiErrorCode). Kept as a plain str
+#   so unknown future codes never raise on parse. The spec defines a fixed enum
+#   (Ok, NoConnect, Validation, …, Timeout, OutcomeUnknown, Busy, Internal) but the
+#   wire type is a string — new codes would otherwise be rejected by a Literal union.
+#   Named constants: timeouts.ErrorCode.
+WebApiErrorCode = str
+
+
+class PagingMeta(BaseModel):
+    """Pagination cursor returned on list endpoints."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    # * nextCursor is the opaque page token; pass it back as ?cursor=.
+    next_cursor: str | None = Field(default=None, alias="nextCursor")
+    # * hasMore is the explicit boolean sentinel so callers avoid null-string checks.
+    has_more: bool = Field(default=False, alias="hasMore")
+
+
+class ApiMeta(BaseModel):
+    """Response metadata present on every v2 response."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    # * W3C trace id — correlate this response in Seq/SigNoz logs.
+    activity_id: str | None = Field(default=None, alias="activityId")
+    # * Pagination info; null for non-list endpoints.
+    paging: PagingMeta | None = None
+
+
+class ApiErrorBody(BaseModel):
+    """Parsed representation of the ``error`` field in a v2 envelope.
+
+    ``code`` is the stable transport-level error code (WebApiErrorCode).
+    ``manager_code`` is the raw MT4/MT5 ResultCode: a string for named enum
+    members, an integer for unrecognised numeric codes.
+    ``message`` is the human-readable description.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    code: WebApiErrorCode
+    # ! Raw MT4/MT5 ResultCode: a string for a named member, a number otherwise.
+    manager_code: str | int | None = Field(default=None, alias="managerCode")
+    message: str | None = None
+
+
+class ApiEnvelope(BaseModel, Generic[T]):
+    """Top-level v2 envelope: {data, error, meta}.
+
+    ``data`` carries the typed payload on success (non-null).
+    ``error`` is non-null on failure; the transport raises ApiError in that case.
+    ``meta`` carries correlation and pagination metadata.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    data: T | None = None
+    error: ApiErrorBody | None = None
+    meta: ApiMeta | None = None

cplugin_webapi_sdk/environments.py

@@ -0,0 +1,45 @@
+"""Environment presets for the v2 SDK. Presets carry only customer-facing
+base URLs — no internal hosts, tokens, or credentials.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+EnvironmentName = Literal["prod", "staging", "custom"]
+
+
+@dataclass(frozen=True)
+class ResolvedEnvironment:
+    api_base_url: str
+    authority: str
+
+
+_PRESETS: dict[str, ResolvedEnvironment] = {
+    "prod": ResolvedEnvironment("https://cloud.mywebapi.com", "https://auth.cplugin.net"),
+    "staging": ResolvedEnvironment("https://pre.mywebapi.com", "https://pre.auth.cplugin.net"),
+}
+
+
+def _strip(u: str) -> str:
+    # * Strip trailing slashes from URLs to normalize custom environment inputs.
+    return u.rstrip("/")
+
+
+def resolve_environment(
+    env: EnvironmentName,
+    *,
+    api_base_url: str | None = None,
+    authority: str | None = None,
+) -> ResolvedEnvironment:
+    # * Resolve environment configuration by name (preset) or custom URLs.
+    # * For custom env, both api_base_url and authority are required and trailing slashes
+    # * are stripped to normalize the URLs.
+    if env == "custom":
+        if not api_base_url or not authority:
+            raise ValueError("custom environment requires both api_base_url and authority")
+        return ResolvedEnvironment(_strip(api_base_url), _strip(authority))
+    preset = _PRESETS.get(env)
+    if preset is None:
+        raise ValueError(f"unknown environment: {env!r}")
+    return preset

cplugin_webapi_sdk/errors.py

@@ -0,0 +1,79 @@
+"""ApiError — raised when a v2 envelope carries a non-null ``error``.
+
+Public surface mirrors the TS SDK: {code, description, activity_id}.
+``manager_code`` and ``status`` are retained as extras for diagnostics;
+``outcome``, ``applied_timeout`` and ``headers`` come from the response headers
+and say what a timeout means for the operation (see ``timeouts``).
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from .envelope import ApiErrorBody, ApiMeta, WebApiErrorCode
+from .timeouts import (
+    APPLIED_TIMEOUT_HEADER,
+    OUTCOME_HEADER,
+    is_outcome_unknown,
+    is_safe_to_retry,
+)
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    # * httpx.Headers is case-insensitive; a plain dict (tests, custom shims) may not be.
+    value = headers.get(name)
+    if value is None:
+        lowered = name.lower()
+        value = next((v for k, v in headers.items() if k.lower() == lowered), None)
+    return value
+
+
+class ApiError(Exception):
+    """Raised by the transport when an envelope's ``error`` field is non-null.
+
+    Attributes:
+        code:            Stable error code (``ErrorCode``), e.g. ``"OutcomeUnknown"``.
+        description:     Human-readable message from the server.
+        activity_id:     Trace id to quote when reporting the problem.
+        manager_code:    Raw trade-platform result code, when there is one.
+        status:          HTTP status (v2 answers 200 even on errors).
+        outcome:         ``X-Request-Outcome`` header (``RequestOutcome``): ``"timeout"``,
+                         ``"unknown"``, ``"not-started"``, ``"in-progress"``, or ``None``.
+        applied_timeout: ``X-Request-Timeout-Applied`` header — the deadline the server
+                         used, in seconds — or ``None``.
+        headers:         All response headers.
+    """
+
+    def __init__(
+        self,
+        body: ApiErrorBody,
+        meta: ApiMeta | None,
+        status: int,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.code: WebApiErrorCode = body.code
+        self.description: str | None = body.message
+        self.activity_id: str | None = meta.activity_id if meta is not None else None
+        self.manager_code: str | int | None = body.manager_code
+        self.status: int = status
+        self.headers: Mapping[str, str] = headers if headers is not None else {}
+
+        outcome = _header(self.headers, OUTCOME_HEADER)
+        self.outcome: str | None = outcome.strip().lower() if outcome and outcome.strip() else None
+
+        applied = _header(self.headers, APPLIED_TIMEOUT_HEADER)
+        try:
+            self.applied_timeout: float | None = float(applied) if applied else None
+        except ValueError:
+            self.applied_timeout = None
+
+        super().__init__(self.description or f"v2 error: {body.code}")
+
+    @property
+    def outcome_unknown(self) -> bool:
+        """The operation may still be applied — check before repeating (see ``is_outcome_unknown``)."""
+        return is_outcome_unknown(self)
+
+    @property
+    def safe_to_retry(self) -> bool:
+        """Repeating the request cannot apply the operation twice (see ``is_safe_to_retry``)."""
+        return is_safe_to_retry(self)

cplugin_webapi_sdk/flags.py

@@ -0,0 +1,36 @@
+"""Flag fields — user rights, group permissions, symbol flags, …
+
+They travel as the names of the set bits joined by ", ": ``"Enabled, Password"``. No bit set is ``"None"``; a
+set bit the API has no name for is ``"Bit<n>"`` — keep it when writing the value back, the trading platform may
+rely on it. The names and bit values of every flag type are in the OpenAPI spec (``x-enum-varnames`` /
+``x-enum-values``).
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def parse_flags(value: str | None) -> list[str]:
+    """Names of the set bits; ``"None"``, an empty string and ``None`` give an empty list."""
+    if not value:
+        return []
+    return [n for n in (part.strip() for part in value.split(",")) if n and n.lower() != "none"]
+
+
+def format_flags(names: Iterable[str]) -> str:
+    """The wire form of a set of bit names; no names give ``"None"``. Duplicates are dropped, order is kept."""
+    unique = list(dict.fromkeys(n.strip() for n in names if n.strip() and n.strip().lower() != "none"))
+    return ", ".join(unique) if unique else "None"
+
+
+def has_flag(value: str | None, name: str) -> bool:
+    """Whether the bit ``name`` is set (names compare case-insensitively, as the API reads them)."""
+    wanted = name.lower()
+    return any(n.lower() == wanted for n in parse_flags(value))
+
+
+def with_flag(value: str | None, name: str, on: bool = True) -> str:
+    """``value`` with the bit ``name`` set (``on=True``) or cleared; every other bit, unnamed ones included, is kept."""
+    wanted = name.lower()
+    rest = [n for n in parse_flags(value) if n.lower() != wanted]
+    return format_flags([*rest, name] if on else rest)

cplugin_webapi_sdk/pagination.py

@@ -0,0 +1,141 @@
+"""Cursor pagination over the v2 envelope's ``meta.paging``.
+
+Mirrors the TS SDK's ``paginate()`` / ``collectAll()`` helpers with sync AND
+async symmetry.
+
+The ``fetch_page(cursor)`` callback contract
+-------------------------------------------
+- Accepts a cursor token (``str | None``; ``None`` means "first page").
+- Returns ``(items, meta)`` — the same tuple that namespace ``*_request``
+  methods produce via ``unwrap_with_meta``.  ``meta`` may be ``None`` on
+  non-paged endpoints; the helpers stop gracefully in that case.
+
+Continuation rule
+-----------------
+- Continue while ``meta.paging.has_more is True`` AND
+  ``meta.paging.next_cursor`` is non-empty.
+- Either sentinel alone stops iteration:
+  - ``has_more=False`` → stop (even if ``next_cursor`` happens to be set).
+  - ``next_cursor=None/""`` → stop (defensive guard against server omission).
+  - ``meta=None`` or ``meta.paging=None`` → treat as last page and stop.
+"""
+from __future__ import annotations
+
+from typing import Any, AsyncGenerator, Awaitable, Callable, Iterator
+
+from .envelope import ApiMeta
+
+# * Type aliases describing the callback contract.
+_PageResult = tuple[list[Any], ApiMeta | None]
+PageFetcherSync = Callable[[str | None], _PageResult]
+PageFetcherAsync = Callable[[str | None], Awaitable[_PageResult]]
+
+
+# ---------------------------------------------------------------------------
+# Internal helper
+# ---------------------------------------------------------------------------
+
+def _next_cursor(meta: ApiMeta | None) -> str | None:
+    """Extract the next cursor from a page's metadata, or ``None`` to stop.
+
+    Returns ``None`` when:
+    - ``meta`` is ``None`` (non-paged endpoint or server omission).
+    - ``meta.paging`` is ``None``.
+    - ``meta.paging.has_more`` is ``False``.
+    - ``meta.paging.next_cursor`` is ``None`` or empty string.
+    """
+    if meta is None or meta.paging is None:
+        return None
+    if not meta.paging.has_more:
+        return None
+    # * Treat empty string the same as None — defensive against server quirks.
+    return meta.paging.next_cursor or None
+
+
+# ---------------------------------------------------------------------------
+# Public sync API
+# ---------------------------------------------------------------------------
+
+def paginate_sync(fetch_page: PageFetcherSync) -> Iterator[list[Any]]:
+    """Yield successive pages from a cursor-paginated endpoint (sync).
+
+    ``fetch_page`` is called with the current cursor (``None`` for the first
+    page) and must return ``(items, meta)``.  Iteration stops when
+    ``meta.paging.has_more`` is ``False`` or ``next_cursor`` is absent.
+
+    Example::
+
+        for page in paginate_sync(lambda cur: client.mt4.users_request(tp, cursor=cur)):
+            for user in page:
+                process(user)
+    """
+    cursor: str | None = None
+    while True:
+        items, meta = fetch_page(cursor)
+        yield items
+        cursor = _next_cursor(meta)
+        if cursor is None:
+            return
+
+
+def collect_all_sync(fetch_page: PageFetcherSync) -> list[Any]:
+    """Drain all pages into a single flat list (sync).
+
+    Convenience wrapper around :func:`paginate_sync`.  For large collections
+    prefer :func:`paginate_sync` to avoid materialising all records in memory.
+
+    Example::
+
+        all_users = collect_all_sync(
+            lambda cur: client.mt4.users_request(tp, cursor=cur)
+        )
+    """
+    out: list[Any] = []
+    for page in paginate_sync(fetch_page):
+        out.extend(page)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Public async API
+# ---------------------------------------------------------------------------
+
+async def paginate_async(fetch_page: PageFetcherAsync) -> AsyncGenerator[list[Any], None]:
+    """Async generator yielding successive pages from a cursor-paginated endpoint.
+
+    ``fetch_page`` must be an async callable accepting a cursor and returning
+    ``(items, meta)``.  Mirrors :func:`paginate_sync` exactly.
+
+    Example::
+
+        async for page in paginate_async(
+            lambda cur: client.mt4.users_request(tp, cursor=cur)
+        ):
+            for user in page:
+                await process(user)
+    """
+    cursor: str | None = None
+    while True:
+        items, meta = await fetch_page(cursor)
+        yield items
+        cursor = _next_cursor(meta)
+        if cursor is None:
+            return
+
+
+async def collect_all_async(fetch_page: PageFetcherAsync) -> list[Any]:
+    """Drain all pages into a single flat list (async).
+
+    Convenience wrapper around :func:`paginate_async`.  For large collections
+    prefer :func:`paginate_async` to avoid materialising all records in memory.
+
+    Example::
+
+        all_users = await collect_all_async(
+            lambda cur: client.mt4.users_request(tp, cursor=cur)
+        )
+    """
+    out: list[Any] = []
+    async for page in paginate_async(fetch_page):
+        out.extend(page)
+    return out