mywebapi-sdk 0.3.0__py3-none-any.whl

cplugin_webapi_sdk/realtime.py

@@ -0,0 +1,408 @@
+"""Real-time SignalR clients for the MT4/MT5 v2 hubs.
+
+! EXPERIMENTAL. There is no official Python SignalR client; this wraps the
+  community library ``signalrcore``, which is an OPTIONAL dependency. Install with::
+
+      pip install "mywebapi-sdk[signalr]"
+
+  The REST surface of this SDK works without it — only these realtime clients
+  require it, and they raise ``SignalRNotInstalledError`` with an install hint if
+  it is missing.
+
+! ``signalrcore`` is callback-first (synchronous observer model), unlike the
+  TypeScript ``@microsoft/signalr`` async-iterable surface. Streams therefore
+  take a callback via ``.subscribe()`` and return a subscription handle, rather
+  than yielding via ``async for``.
+
+Usage::
+
+    from cplugin_webapi_sdk import CPluginWebApiClient
+
+    with CPluginWebApiClient(env="staging", client_id=..., client_secret=...) as c:
+        rt = c.realtime.mt4("my-trade-platform-id")
+        rt.on_connection_status(lambda *args: print("status", args))
+        rt.on_tick(lambda *args: print("tick", args))
+
+        with rt:  # calls start() / stop()
+            rt.subscribe_to_ticks("EURUSD")
+            import time; time.sleep(5)
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+from urllib.parse import quote
+
+
+# ---------------------------------------------------------------------------
+# Error surface
+# ---------------------------------------------------------------------------
+
+
+class SignalRNotInstalledError(RuntimeError):
+    """Raised when a realtime client is constructed but ``signalrcore`` is absent.
+
+    The ``signalrcore`` package is an optional dependency of this SDK. Install it
+    with the ``[signalr]`` extra::
+
+        pip install "mywebapi-sdk[signalr]"
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Real-time streaming requires the optional 'signalrcore' dependency. "
+            'Install it with:  pip install "mywebapi-sdk[signalr]"'
+        )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _import_signalr():
+    """Return ``HubConnectionBuilder`` from ``signalrcore``.
+
+    * Lazy import isolated in a helper so tests can monkeypatch it and so the
+    *   package imports cleanly when the extra is not installed.
+    """
+    try:
+        from signalrcore.hub_connection_builder import HubConnectionBuilder  # type: ignore
+    except ImportError as exc:  # ! callers convert this to SignalRNotInstalledError
+        raise ImportError("signalrcore not installed") from exc
+    return HubConnectionBuilder
+
+
+def _build_hub_url(base_url: str, platform: str, trade_platform: str) -> str:
+    """Build the fully-qualified hub WebSocket URL.
+
+    * Mirror the TS hub-URL construction exactly: strip trailing slashes off
+    *   the base, append ``/hubs/<platform>/v2``, then the URL-encoded
+    *   ``tradePlatform`` query parameter.
+
+    Args:
+        base_url:       Resolved API base URL (trailing slash stripped here).
+        platform:       Hub platform segment — ``"mt4"`` or ``"mt5"``.
+        trade_platform: Trade platform identifier (URL-encoded in output).
+
+    Returns:
+        Fully-qualified URL string for the hub negotiate endpoint.
+    """
+    base = base_url.rstrip("/")
+    return f"{base}/hubs/{platform}/v2?tradePlatform={quote(trade_platform, safe='')}"
+
+
+# ---------------------------------------------------------------------------
+# Base connection lifecycle
+# ---------------------------------------------------------------------------
+
+
+class _BaseRealtimeClient:
+    """Shared connection lifecycle for the MT4/MT5 realtime clients.
+
+    ! EXPERIMENTAL — see module docstring for caveats on ``signalrcore``.
+
+    Subclasses set ``_PLATFORM`` to ``"mt4"`` or ``"mt5"`` and expose
+    platform-specific callback and stream methods on top.
+    """
+
+    # * Overridden by MT4RealtimeClient / MT5RealtimeClient.
+    _PLATFORM: str = ""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token_factory: Callable[[], str],
+        trade_platform: str,
+    ) -> None:
+        """Construct and wire the hub connection.
+
+        Args:
+            base_url:       Resolved API base URL (e.g. ``https://pre.mywebapi.com``).
+            token_factory:  Zero-arg callable returning the current bearer token
+                            string. ``signalrcore`` calls this at negotiate time
+                            and attaches the result as ``?access_token=…`` on the
+                            WebSocket handshake.
+            trade_platform: Platform identifier appended as ``?tradePlatform=…``
+                            on the hub URL.
+
+        Raises:
+            ValueError:              If ``trade_platform`` is empty.
+            SignalRNotInstalledError: If ``signalrcore`` is not installed.
+        """
+        if not trade_platform:
+            raise ValueError("trade_platform is required")
+
+        try:
+            builder_cls = _import_signalr()
+        except ImportError:
+            raise SignalRNotInstalledError() from None
+
+        self.hub_url: str = _build_hub_url(base_url, self._PLATFORM, trade_platform)
+        self._token_factory: Callable[[], str] = token_factory
+
+        # * access_token_factory lets signalrcore fetch a fresh token at negotiate
+        # *   time and append it as ?access_token=… for the WebSocket handshake.
+        self._conn = (
+            builder_cls()
+            .with_url(
+                self.hub_url,
+                options={"access_token_factory": token_factory},
+            )
+            .build()
+        )
+        self._started: bool = False
+
+    # * --- lifecycle ---------------------------------------------------------
+
+    def on_connection_status(self, handler: Callable[[Any], None]) -> None:
+        """Register a callback for ``OnConnectionStatus`` events from the hub.
+
+        ! Register all callbacks BEFORE ``start()`` — ``signalrcore`` may drop
+        !   handlers registered after the connection is already open. Same race
+        !   the TS client guards against with a pending-handler queue.
+
+        Args:
+            handler: Callable invoked with the raw event payload when the hub
+                     broadcasts a connection status change.
+        """
+        # ! Register before start() — signalrcore may drop late handlers.
+        self._conn.on("OnConnectionStatus", handler)
+
+    def start(self) -> None:
+        """Open the WebSocket connection to the hub.
+
+        ! Register all callbacks BEFORE calling ``start()`` — see the class
+        !   docstring for the handler-registration ordering requirement.
+        """
+        self._conn.start()
+        self._started = True
+
+    def stop(self) -> None:
+        """Close the WebSocket connection to the hub."""
+        if self._started:
+            self._conn.stop()
+            self._started = False
+
+    def __enter__(self) -> "_BaseRealtimeClient":
+        self.start()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.stop()
+
+    def _stream(self, method: str, args: Optional[list] = None):
+        """Return a ``StreamHandler`` for the named server-streaming method.
+
+        * ``signalrcore`` stream() returns an observable; call ``.subscribe(observer)``
+        *   on the result to wire ``next`` / ``complete`` / ``error`` callbacks::
+        *
+        *     rt.stream_trades().subscribe({
+        *         "next": lambda item: print(item),
+        *         "complete": lambda: print("done"),
+        *         "error": lambda err: print("err", err),
+        *     })
+
+        Args:
+            method: Server-streaming method name (e.g. ``"StreamTrades"``).
+            args:   Optional positional arguments passed to the server method.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()`` on it.
+        """
+        return self._conn.stream(method, args or [])
+
+
+# ---------------------------------------------------------------------------
+# MT4 realtime client
+# ---------------------------------------------------------------------------
+
+
+class MT4RealtimeClient(_BaseRealtimeClient):
+    """Real-time client for the MT4 v2 hub (``/hubs/mt4/v2``).
+
+    ! EXPERIMENTAL — see module docstring.
+
+    Obtain via ``client.realtime.mt4(trade_platform)``; do NOT instantiate
+    directly unless you manage the ``base_url`` and ``token_factory`` yourself.
+
+    Server method names mirror the TypeScript SDK verbatim::
+
+        Callbacks:  OnTick, OnConnectionStatus
+        Invokes:    SubscribeToTicks, UnsubscribeFromTicks
+        Streams:    StreamTicks, StreamTrades, StreamUserUpdates,
+                    StreamSymbolUpdates, StreamMarginCallUpdates
+    """
+
+    _PLATFORM = "mt4"
+
+    # * --- callbacks --------------------------------------------------------
+
+    def on_tick(self, handler: Callable[[Any], None]) -> None:
+        """Register a callback for ``OnTick`` events broadcast by the hub.
+
+        ! Register before ``start()`` — see lifecycle ordering note.
+
+        Args:
+            handler: Callable invoked with the raw tick payload per event.
+        """
+        # ! Register before start() — signalrcore may drop late handlers.
+        self._conn.on("OnTick", handler)
+
+    # * --- invocations ------------------------------------------------------
+
+    def subscribe_to_ticks(self, symbol: str) -> None:
+        """Ask the server to start pushing ``OnTick`` events for ``symbol``.
+
+        Args:
+            symbol: Instrument name (e.g. ``"EURUSD"``).
+        """
+        self._conn.send("SubscribeToTicks", [symbol])
+
+    def unsubscribe_from_ticks(self, symbol: str) -> None:
+        """Ask the server to stop pushing ``OnTick`` events for ``symbol``.
+
+        Args:
+            symbol: Instrument name (e.g. ``"EURUSD"``).
+        """
+        self._conn.send("UnsubscribeFromTicks", [symbol])
+
+    # * --- server-streaming methods -----------------------------------------
+    # * Call .subscribe({"next": cb, "complete": cb, "error": cb}) on each.
+
+    def stream_ticks(self, symbol: str):
+        """Stream server-side tick data for a single symbol.
+
+        Args:
+            symbol: Instrument name (e.g. ``"EURUSD"``).
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamTicks", [symbol])
+
+    def stream_trades(self):
+        """Stream open trade updates.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamTrades")
+
+    def stream_user_updates(self):
+        """Stream user account change events.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamUserUpdates")
+
+    def stream_symbol_updates(self):
+        """Stream symbol configuration change events.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamSymbolUpdates")
+
+    def stream_margin_call_updates(self):
+        """Stream margin-call status events.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamMarginCallUpdates")
+
+
+# ---------------------------------------------------------------------------
+# MT5 realtime client
+# ---------------------------------------------------------------------------
+
+
+class MT5RealtimeClient(_BaseRealtimeClient):
+    """Real-time client for the MT5 v2 hub (``/hubs/mt5/v2``).
+
+    ! EXPERIMENTAL — see module docstring.
+
+    Obtain via ``client.realtime.mt5(trade_platform)``; do NOT instantiate
+    directly unless you manage the ``base_url`` and ``token_factory`` yourself.
+
+    Server method names mirror the TypeScript SDK verbatim::
+
+        Callbacks:  OnConnectionStatus
+        Streams:    StreamMarginCallUpdates
+    """
+
+    _PLATFORM = "mt5"
+
+    # * --- server-streaming methods -----------------------------------------
+
+    def stream_margin_call_updates(self):
+        """Stream margin-call status events from the MT5 hub.
+
+        Returns:
+            ``signalrcore.hub.handlers.StreamHandler`` — call ``.subscribe()``.
+        """
+        return self._stream("StreamMarginCallUpdates")
+
+
+# ---------------------------------------------------------------------------
+# Namespace factory
+# ---------------------------------------------------------------------------
+
+
+class RealtimeNamespace:
+    """Factory bound to a client's base URL and token provider.
+
+    Exposed as ``client.realtime``; call ``.mt4(tp)`` / ``.mt5(tp)`` to create
+    a hub client for a specific trade platform.
+
+    ! Requires the optional ``signalrcore`` extra — see module docstring.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token_factory: Callable[[], str],
+    ) -> None:
+        self._base_url = base_url
+        self._token_factory = token_factory
+
+    def mt4(self, trade_platform: str) -> MT4RealtimeClient:
+        """Create an MT4 realtime hub client for the given trade platform.
+
+        Args:
+            trade_platform: Trade platform identifier (UUID string or slug).
+
+        Returns:
+            A new :class:`MT4RealtimeClient` — call ``start()`` / ``stop()``
+            or use it as a context manager.
+
+        Raises:
+            SignalRNotInstalledError: If ``signalrcore`` is not installed.
+        """
+        return MT4RealtimeClient(
+            base_url=self._base_url,
+            token_factory=self._token_factory,
+            trade_platform=trade_platform,
+        )
+
+    def mt5(self, trade_platform: str) -> MT5RealtimeClient:
+        """Create an MT5 realtime hub client for the given trade platform.
+
+        Args:
+            trade_platform: Trade platform identifier (UUID string or slug).
+
+        Returns:
+            A new :class:`MT5RealtimeClient` — call ``start()`` / ``stop()``
+            or use it as a context manager.
+
+        Raises:
+            SignalRNotInstalledError: If ``signalrcore`` is not installed.
+        """
+        return MT5RealtimeClient(
+            base_url=self._base_url,
+            token_factory=self._token_factory,
+            trade_platform=trade_platform,
+        )

cplugin_webapi_sdk/timeouts.py

@@ -0,0 +1,197 @@
+"""Request timeouts, retry classification and idempotency keys.
+
+The server gives every call addressed to a trade platform a deadline. When the
+trade server does not answer in time the API still answers (v2: HTTP 200 with an
+error envelope), and the error code plus the ``X-Request-Outcome`` header say
+whether the operation may still be applied:
+
+- ``Timeout`` / ``timeout`` — a read did not finish; nothing changed. Safe to retry.
+- ``Busy`` / ``not-started`` — refused before it was sent. Safe to retry.
+- ``OutcomeUnknown`` / ``unknown`` — a trade or change did not finish and may still
+  be applied. Check the result; never retry blindly.
+- ``OutcomeUnknown`` / ``in-progress`` — a request with the same ``Idempotency-Key``
+  is still running; this one was not executed.
+
+Default deadlines per operation kind: trade 5 s, read 10 s, change 15 s,
+history 30 s, maintenance 60 s. A caller chooses its own with ``X-Request-Timeout``
+(seconds, 1–300); the applied value comes back in ``X-Request-Timeout-Applied``.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+# * Wire names.
+REQUEST_TIMEOUT_HEADER = "X-Request-Timeout"
+APPLIED_TIMEOUT_HEADER = "X-Request-Timeout-Applied"
+OUTCOME_HEADER = "X-Request-Outcome"
+IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+
+# * Bounds the server accepts for X-Request-Timeout; anything else answers Validation.
+MIN_REQUEST_TIMEOUT = 1.0
+MAX_REQUEST_TIMEOUT = 300.0
+
+# * Longest Idempotency-Key the server accepts (draft-ietf-httpapi-idempotency-key-header).
+MAX_IDEMPOTENCY_KEY_LENGTH = 255
+
+# * How much longer than the requested server deadline the HTTP client waits.
+# ! The server may extend its deadline by the time it spends opening the trade-platform
+# !   connection for this request — up to 20 s — so it can answer as late as
+# !   request_timeout + 20 s. 10 s more covers the network. A shorter margin makes the
+# !   client give up first and lose the answer that says whether a trade was applied.
+# ? Not a hard bound: the server's deadline starts after it has read the body and taken
+# ?   the idempotency key, and those steps have no deadline of their own.
+TRANSPORT_TIMEOUT_MARGIN = 30.0
+
+# * Default client-wide HTTP timeout. A call to a trade platform waits longer when its
+#   server deadline needs it (see transport_timeout); this is the floor.
+DEFAULT_TRANSPORT_TIMEOUT = 30.0
+
+# * Deadline assumed for an operation whose spec documents no X-Request-Timeout
+#   default: the longest server default, maintenance. Every operation of the
+#   current spec documents one; this covers a server that adds an operation
+#   before the SDK is regenerated.
+UNDOCUMENTED_OPERATION_TIMEOUT = 60.0
+
+
+class ErrorCode:
+    """Values of ``error.code`` (``ApiError.code``) in a v2 envelope.
+
+    The code is a plain string on the wire; unknown future codes arrive unchanged.
+    """
+
+    OK = "Ok"
+    NO_CONNECT = "NoConnect"
+    VALIDATION = "Validation"
+    MT4_ERROR = "MT4Error"
+    FORBIDDEN = "Forbidden"
+    NOT_FOUND = "NotFound"
+    MT5_ERROR = "MT5Error"
+    #: A read did not finish in time. Nothing changed; safe to retry.
+    TIMEOUT = "Timeout"
+    #: A trade or change did not finish in time and may still be applied, or a request
+    #: with the same idempotency key is still running. Check the result before retrying.
+    OUTCOME_UNKNOWN = "OutcomeUnknown"
+    #: Too many requests wait for this trade platform; not sent. Safe to retry.
+    BUSY = "Busy"
+    INTERNAL = "Internal"
+    #: Produced by the SDK, not the server: the body was not a v2 envelope
+    #: (e.g. an HTML 502/504 page from a proxy).
+    INVALID_RESPONSE = "InvalidResponse"
+
+
+class RequestOutcome:
+    """Values of the ``X-Request-Outcome`` response header (``ApiError.outcome``)."""
+
+    #: The operation did not finish in time and changed nothing.
+    TIMEOUT = "timeout"
+    #: A trade or change did not finish in time and may still be applied.
+    UNKNOWN = "unknown"
+    #: The request was refused before it reached the trade server.
+    NOT_STARTED = "not-started"
+    #: A request with the same idempotency key is still being processed; this one was not executed.
+    IN_PROGRESS = "in-progress"
+
+
+_SAFE_CODES = frozenset({ErrorCode.TIMEOUT, ErrorCode.BUSY})
+_SAFE_OUTCOMES = frozenset({RequestOutcome.TIMEOUT, RequestOutcome.NOT_STARTED})
+_UNKNOWN_OUTCOMES = frozenset({RequestOutcome.UNKNOWN, RequestOutcome.IN_PROGRESS})
+
+
+def validate_request_timeout(value: Any, *, name: str = "request_timeout") -> float | None:
+    """Return ``value`` as seconds, ``None`` for ``None``; raise ``ValueError``/``TypeError`` otherwise.
+
+    The server accepts 1 to 300 seconds, fractions included.
+    """
+    if value is None:
+        return None
+    # ! bool is an int subclass: True would silently mean one second.
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a number of seconds, got {type(value).__name__}")
+    seconds = float(value)
+    if math.isnan(seconds) or not MIN_REQUEST_TIMEOUT <= seconds <= MAX_REQUEST_TIMEOUT:
+        raise ValueError(
+            f"{name} must be from {MIN_REQUEST_TIMEOUT:g} to {MAX_REQUEST_TIMEOUT:g} seconds, got {value!r}"
+        )
+    return seconds
+
+
+def validate_idempotency_key(value: Any) -> str | None:
+    """Return the key unchanged, ``None`` for ``None``; reject empty, over-long or non-ASCII keys."""
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError(f"idempotency_key must be a str, got {type(value).__name__}")
+    if not value.strip():
+        raise ValueError("idempotency_key must not be empty")
+    if len(value) > MAX_IDEMPOTENCY_KEY_LENGTH:
+        raise ValueError(f"idempotency_key must be at most {MAX_IDEMPOTENCY_KEY_LENGTH} characters")
+    # ! An HTTP header value must be printable ASCII; httpx would otherwise fail
+    # !   with an encoding error far from the caller's line.
+    if not value.isascii() or not value.isprintable():
+        raise ValueError("idempotency_key must be printable ASCII")
+    return value
+
+
+def format_seconds(seconds: float) -> str:
+    """Seconds as the server writes them: invariant culture, up to three decimals (``10``, ``2.5``)."""
+    return f"{seconds:.3f}".rstrip("0").rstrip(".")
+
+
+def operation_default_timeout(op_module: object) -> float:
+    """Server default deadline of a generated operation, from the spec; 60 s when it documents none."""
+    from ._generated.operation_timeouts import DEFAULTS
+
+    name = getattr(op_module, "__name__", "")
+    key = ".".join(name.rsplit(".", 2)[-2:])
+    return DEFAULTS.get(key, UNDOCUMENTED_OPERATION_TIMEOUT)
+
+
+def transport_timeout(base: float | None, server_timeout: float) -> float | None:
+    """HTTP client timeout for one call: ``server_timeout`` + margin, never below ``base``.
+
+    ``server_timeout`` is the requested deadline, else the operation's default.
+    ``base`` is the client-wide timeout (``None`` = no limit, which already waits long enough).
+    """
+    if base is None:
+        return None
+    return max(base, server_timeout + TRANSPORT_TIMEOUT_MARGIN)
+
+
+def _code_and_outcome(error: BaseException) -> tuple[str | None, str | None]:
+    code = getattr(error, "code", None)
+    outcome = getattr(error, "outcome", None)
+    return (code if isinstance(code, str) else None, outcome if isinstance(outcome, str) else None)
+
+
+def is_outcome_unknown(error: BaseException) -> bool:
+    """Whether the failed operation may still be applied by the trade server.
+
+    True for ``OutcomeUnknown`` (``X-Request-Outcome: unknown`` or ``in-progress``).
+    Do not repeat such a request blindly — for a trade that means a second trade.
+    Check the result (orders, positions, balance, the changed record), or repeat it
+    with the **same** ``idempotency_key``: while the first one runs you get
+    ``in-progress`` again, once it has finished you get its real result without it
+    being executed twice.
+
+    Anything that is not an ``ApiError`` returns False: the SDK cannot tell from a
+    transport exception (``httpx.ReadTimeout``) whether the request was a write — for a
+    trade or change treat those as unknown too.
+    """
+    code, outcome = _code_and_outcome(error)
+    return code == ErrorCode.OUTCOME_UNKNOWN or outcome in _UNKNOWN_OUTCOMES
+
+
+def is_safe_to_retry(error: BaseException) -> bool:
+    """Whether repeating the request cannot apply the operation twice.
+
+    True for ``Timeout`` (a read that changed nothing) and ``Busy`` (refused before
+    it was sent), and for the matching ``X-Request-Outcome`` values ``timeout`` and
+    ``not-started``. False for everything else, ``OutcomeUnknown`` above all — other
+    codes (``Validation``, ``NotFound``, platform errors) will not succeed on a
+    plain retry either.
+    """
+    if is_outcome_unknown(error):
+        return False
+    code, outcome = _code_and_outcome(error)
+    return code in _SAFE_CODES or outcome in _SAFE_OUTCOMES