tonutils 2.0.1b1__py3-none-any.whl → 2.0.1b3__py3-none-any.whl

tonutils/clients/http/{toncenter/client.py → clients/toncenter.py}

@@ -7,11 +7,20 @@ from aiohttp import ClientSession
 from pytoniq_core import Cell, Slice, Transaction
 
 from tonutils.clients.base import BaseClient
-from tonutils.clients.http.toncenter.models import SendBocPayload, RunGetMethodPayload
-from tonutils.clients.http.toncenter.provider import ToncenterHttpProvider
-from tonutils.clients.http.toncenter.stack import decode_stack, encode_stack
-from tonutils.exceptions import ClientError, ClientNotConnectedError
-from tonutils.types import ClientType, ContractState, ContractStateInfo, NetworkGlobalID
+from tonutils.clients.http.providers.toncenter.models import (
+    SendBocPayload,
+    RunGetMethodPayload,
+)
+from tonutils.clients.http.providers.toncenter.provider import ToncenterHttpProvider
+from tonutils.clients.http.utils import decode_toncenter_stack, encode_toncenter_stack
+from tonutils.exceptions import ClientError, RunGetMethodError
+from tonutils.types import (
+    ClientType,
+    ContractState,
+    ContractStateInfo,
+    NetworkGlobalID,
+    RetryPolicy,
+)
 from tonutils.utils import cell_to_hex, parse_stack_config
 
 
@@ -26,11 +35,13 @@ class ToncenterHttpClient(BaseClient):
         network: NetworkGlobalID = NetworkGlobalID.MAINNET,
         api_key: t.Optional[str] = None,
         base_url: t.Optional[str] = None,
-        timeout: int = 10,
+        timeout: float = 10.0,
         session: t.Optional[ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
         rps_limit: t.Optional[int] = None,
         rps_period: float = 1.0,
-        rps_retries: int = 2,
+        retry_policy: t.Optional[RetryPolicy] = None,
     ) -> None:
         """
         Initialize Toncenter HTTP client.
@@ -39,11 +50,13 @@ class ToncenterHttpClient(BaseClient):
         :param api_key: Optional Toncenter API key
             You can get an API key on the Toncenter telegram bot: https://t.me/toncenter
         :param base_url: Custom Toncenter endpoint base URL
-        :param timeout: HTTP request timeout in seconds
-        :param session: Optional externally managed aiohttp.ClientSession
-        :param rps_limit: Optional requests-per-second limit for rate limiting
-        :param rps_period: Time window in seconds for RPS limit
-        :param rps_retries: Number of retries on rate limiting
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
         """
         self.network: NetworkGlobalID = network
         self._provider: ToncenterHttpProvider = ToncenterHttpProvider(
@@ -52,34 +65,24 @@ class ToncenterHttpClient(BaseClient):
             base_url=base_url,
             timeout=timeout,
             session=session,
+            headers=headers,
+            cookies=cookies,
             rps_limit=rps_limit,
             rps_period=rps_period,
-            rps_retries=rps_retries,
+            retry_policy=retry_policy,
         )
 
     @property
     def provider(self) -> ToncenterHttpProvider:
-        """
-        Underlying Toncenter HTTP provider.
-
-        :return: ToncenterHttpProvider instance used for all HTTP requests
-        """
-        if not self.is_connected:
-            raise ClientNotConnectedError(self)
         return self._provider
 
     @property
     def is_connected(self) -> bool:
-        """
-        Check whether HTTP session is initialized and open.
-
-        :return: True if session exists and is not closed, False otherwise
-        """
         session = self._provider.session
         return session is not None and not session.closed
 
     async def __aenter__(self) -> ToncenterHttpClient:
-        await self._provider.__aenter__()
+        await self._provider.connect()
         return self
 
     async def __aexit__(
@@ -88,7 +91,7 @@ class ToncenterHttpClient(BaseClient):
         exc_value: t.Optional[BaseException],
         traceback: t.Optional[t.Any],
     ) -> None:
-        await self._provider.__aexit__(exc_type, exc_value, traceback)
+        await self._provider.close()
 
     async def _send_boc(self, boc: str) -> None:
         payload = SendBocPayload(boc=boc)
@@ -131,19 +134,25 @@ class ToncenterHttpClient(BaseClient):
 
         last_transaction_lt = last_transaction_hash = None
 
-        if request.result.last_transaction_id:
+        tx_id = request.result.last_transaction_id
+        if tx_id is not None:
             try:
-                lt = int(request.result.last_transaction_id.lt)
-                last_transaction_lt = lt if lt > 0 else None
-            except (TypeError, ValueError):
-                last_transaction_lt = None
-            try:
-                raw = request.result.last_transaction_id.hash
-                decoded = base64.b64decode(raw)
-                h = decoded.hex()
-                last_transaction_hash = None if h == "00" * 32 else h
-            except (Exception,):
-                last_transaction_hash = None
+                lt = int(tx_id.lt) if tx_id.lt is not None else 0
+            except (ValueError,):
+                pass
+            else:
+                if lt > 0:
+                    last_transaction_lt = lt
+
+            raw = tx_id.hash
+            if raw is not None:
+                try:
+                    h = base64.b64decode(raw).hex()
+                except (Exception,):
+                    pass
+                else:
+                    if h != "00" * 32:
+                        last_transaction_hash = h
 
         contract_info.last_transaction_lt = last_transaction_lt
         contract_info.last_transaction_hash = last_transaction_hash
@@ -191,21 +200,23 @@ class ToncenterHttpClient(BaseClient):
         payload = RunGetMethodPayload(
             address=address,
             method=method_name,
-            stack=encode_stack(stack or []),
+            stack=encode_toncenter_stack(stack or []),
         )
         request = await self.provider.run_get_method(payload=payload)
         if request.result is None:
             return []
-        return decode_stack(request.result.stack or [])
 
-    async def connect(self) -> None:
-        """
-        Ensure that HTTP session is initialized.
+        if request.result.exit_code != 0:
+            raise RunGetMethodError(
+                address=address,
+                method_name=method_name,
+                exit_code=request.result.exit_code,
+            )
 
-        Safe to call multiple times; underlying provider will reuse the session.
-        """
-        await self._provider.ensure_session()
+        return decode_toncenter_stack(request.result.stack or [])
+
+    async def connect(self) -> None:
+        await self._provider.connect()
 
     async def close(self) -> None:
-        """Close HTTP session if it is owned by the provider."""
         await self._provider.close()

tonutils/clients/http/providers/__init__.py

@@ -0,0 +1,4 @@
+from .tonapi import TonapiHttpProvider
+from .toncenter import ToncenterHttpProvider
+
+__all__ = ["TonapiHttpProvider", "ToncenterHttpProvider"]

tonutils/clients/http/providers/base.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import asyncio
+import typing as t
+
+import aiohttp
+
+from tonutils.clients.http.providers.response import HttpResponse
+from tonutils.clients.limiter import RateLimiter
+from tonutils.exceptions import (
+    NotConnectedError,
+    ProviderResponseError,
+    ProviderTimeoutError,
+    RetryLimitError,
+)
+from tonutils.types import RetryPolicy
+
+
+class HttpProvider:
+    """HTTP-based provider for TON HTTP APIs."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        timeout: float = 10.0,
+        session: t.Optional[aiohttp.ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        """Initialize HTTP provider.
+
+        :param base_url: Base endpoint URL without trailing slash.
+        :param timeout: Total request timeout in seconds.
+        :param session: Optional external aiohttp session.
+        :param headers: Default headers for owned session.
+        :param cookies: Default cookies for owned session.
+        :param rps_limit: Optional requests-per-period limit.
+        :param rps_period: Rate limit period in seconds.
+        :param retry_policy: Optional retry policy that defines per-error-code retry rules
+        """
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = headers
+        self._cookies = cookies
+
+        self._session = session
+        self._owns_session = session is None
+
+        self._limiter = (
+            RateLimiter(max_rate=rps_limit, period=rps_period)
+            if rps_limit is not None
+            else None
+        )
+        self._retry_policy = retry_policy
+        self._connect_lock = asyncio.Lock()
+
+    @property
+    def session(self) -> t.Optional[aiohttp.ClientSession]:
+        """Underlying aiohttp session, or None if not connected."""
+        return self._session
+
+    @property
+    def is_connected(self) -> bool:
+        """Check whether the provider session is initialized and open."""
+        return self._session is not None and not self._session.closed
+
+    async def connect(self) -> None:
+        """Initialize HTTP session if not already connected."""
+        if self.is_connected:
+            return
+
+        async with self._connect_lock:
+            if self.is_connected:
+                return
+
+            self._session = aiohttp.ClientSession(
+                headers=self._headers,
+                cookies=self._cookies,
+                timeout=aiohttp.ClientTimeout(total=self._timeout),
+            )
+
+    async def close(self) -> None:
+        """Close owned HTTP session and release resources."""
+        async with self._connect_lock:
+            if self._owns_session and self._session and not self._session.closed:
+                await self._session.close()
+            self._session = None
+
+    async def _send_once(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: t.Any = None,
+        json_data: t.Any = None,
+    ) -> t.Any:
+        """Send a single HTTP request.
+
+        Performs exactly one request attempt:
+        - applies rate limiting if configured
+        - converts network and protocol errors into provider exceptions
+
+        :param method: HTTP method (GET, POST, etc.).
+        :param path: Endpoint path relative to base_url.
+        :param params: Optional query parameters.
+        :param json_data: Optional JSON body.
+        :return: Parsed response payload.
+        """
+        if not self.is_connected:
+            raise NotConnectedError()
+
+        assert self._session is not None
+        url = f"{self._base_url}/{path.lstrip('/')}"
+
+        try:
+            if self._limiter:
+                await self._limiter.acquire()
+
+            async with self._session.request(
+                method=method,
+                url=url,
+                params=params,
+                json=json_data,
+            ) as resp:
+                data = await HttpResponse.read(resp)
+                if resp.status >= 400:
+                    HttpResponse.raise_error(
+                        status=int(resp.status),
+                        url=url,
+                        data=data,
+                    )
+                return data
+
+        except asyncio.TimeoutError as exc:
+            raise ProviderTimeoutError(
+                timeout=self._timeout,
+                endpoint=url,
+                operation="http request",
+            ) from exc
+
+        except aiohttp.ClientError as exc:
+            raise ProviderResponseError(
+                code=0,
+                message=str(exc),
+                endpoint=url,
+            ) from exc
+
+    async def send_http_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: t.Any = None,
+        json_data: t.Any = None,
+    ) -> t.Any:
+        """Send an HTTP request with retry handling.
+
+        On provider error, retries the request according to the retry policy
+        matched by error code and message. If no rule matches, or retry attempts
+        are exhausted, the error is raised.
+
+        :param method: HTTP method.
+        :param path: Endpoint path relative to base_url.
+        :param params: Optional query parameters.
+        :param json_data: Optional JSON body.
+        :return: Parsed response payload.
+        """
+        attempts: t.Dict[int, int] = {}
+
+        while True:
+            try:
+                return await self._send_once(
+                    method,
+                    path,
+                    params=params,
+                    json_data=json_data,
+                )
+            except ProviderResponseError as e:
+                policy = self._retry_policy
+                if policy is None:
+                    raise
+
+                rule = policy.rule_for(e.code, e.message)
+                if rule is None:
+                    raise
+
+                key = id(rule)
+                attempts[key] = attempts.get(key, 0) + 1
+
+                if attempts[key] >= rule.attempts:
+                    raise RetryLimitError(
+                        attempts=attempts[key],
+                        max_attempts=rule.attempts,
+                        last_error=e,
+                    ) from e
+
+                await asyncio.sleep(rule.delay(attempts[key] - 1))

tonutils/clients/http/providers/response.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+import typing as t
+
+import aiohttp
+
+from tonutils.exceptions import ProviderResponseError, CDN_CHALLENGE_MARKERS
+
+
+class HttpResponse:
+
+    @classmethod
+    async def read(cls, resp: aiohttp.ClientResponse) -> t.Any:
+        body = await resp.read()
+        if not body:
+            return ""
+
+        data = body.decode("utf-8", errors="replace").strip()
+        if not data:
+            return ""
+
+        try:
+            return json.loads(data)
+        except (Exception,):
+            return data
+
+    @classmethod
+    def raise_error(
+        cls,
+        *,
+        status: int,
+        url: str,
+        data: t.Any,
+    ) -> None:
+        exc = cls._detect_proxy_error(data, status=status, url=url)
+        if exc is not None:
+            raise exc
+
+        message = cls._extract_error_message(data)
+        raise ProviderResponseError(
+            code=status,
+            message=message,
+            endpoint=url,
+        )
+
+    @classmethod
+    def _detect_proxy_error(
+        cls,
+        data: t.Any,
+        *,
+        status: int,
+        url: str,
+    ) -> t.Optional[ProviderResponseError]:
+        body = (
+            " ".join(str(v) for v in data.values())
+            if isinstance(data, dict)
+            else str(data)
+        ).lower()
+
+        for marker, message in CDN_CHALLENGE_MARKERS.items():
+            if marker in body:
+                return ProviderResponseError(
+                    code=status,
+                    message=message,
+                    endpoint=url,
+                )
+
+        return None
+
+    @staticmethod
+    def _extract_error_message(data: t.Any) -> str:
+        if isinstance(data, dict):
+            lowered = {k.lower(): v for k, v in data.items()}
+            for key in ("error", "message", "detail", "description"):
+                if key in lowered and isinstance(lowered[key], str):
+                    return lowered[key]
+            string_values = [str(v) for v in data.values() if isinstance(v, str)]
+            return "; ".join(string_values) if string_values else str(data)
+
+        if isinstance(data, list):
+            return "; ".join(map(str, data))
+        if isinstance(data, str):
+            return data
+        return repr(data)

tonutils/clients/http/providers/tonapi/__init__.py

@@ -0,0 +1,3 @@
+from .provider import TonapiHttpProvider
+
+__all__ = ["TonapiHttpProvider"]

tonutils/clients/http/{tonapi → providers/tonapi}/models.py

@@ -44,3 +44,4 @@ class BlockchainAccountMethodResult(BaseModel):
     """Result model for /blockchain/accounts/{address}/methods/{method_name}."""
 
     stack: t.Optional[t.List[t.Any]] = None
+    exit_code: int

tonutils/clients/http/providers/tonapi/provider.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import typing as t
+
+import aiohttp
+from pydantic import BaseModel
+
+from tonutils.clients.http.providers.base import HttpProvider
+from tonutils.clients.http.providers.tonapi.models import (
+    BlockchainAccountMethodResult,
+    BlockchainAccountResult,
+    BlockchainAccountTransactionsResult,
+    BlockchainConfigResult,
+    BlockchainMessagePayload,
+)
+from tonutils.types import NetworkGlobalID, RetryPolicy
+
+
+class TonapiHttpProvider(HttpProvider):
+
+    def __init__(
+        self,
+        network: NetworkGlobalID,
+        api_key: str,
+        base_url: t.Optional[str] = None,
+        timeout: float = 10.0,
+        session: t.Optional[aiohttp.ClientSession] = None,
+        headers: t.Optional[t.Dict[str, str]] = None,
+        cookies: t.Optional[t.Dict[str, str]] = None,
+        rps_limit: t.Optional[int] = None,
+        rps_period: float = 1.0,
+        retry_policy: t.Optional[RetryPolicy] = None,
+    ) -> None:
+        urls = {
+            NetworkGlobalID.MAINNET: "https://tonapi.io/v2",
+            NetworkGlobalID.TESTNET: "https://testnet.tonapi.io/v2",
+        }
+        base_url = base_url or urls[network]
+        headers = {**(headers or {}), "Authorization": f"Bearer {api_key}"}
+
+        super().__init__(
+            base_url=base_url,
+            session=session,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            rps_limit=rps_limit,
+            rps_period=rps_period,
+            retry_policy=retry_policy,
+        )
+
+    @staticmethod
+    def _model(model: t.Type[BaseModel], data: t.Any) -> t.Any:
+        return model.model_validate(data)
+
+    async def blockchain_message(
+        self,
+        payload: BlockchainMessagePayload,
+    ) -> None:
+        await self.send_http_request(
+            "POST",
+            "/blockchain/message",
+            json_data=payload.model_dump(),
+        )
+
+    async def blockchain_config(
+        self,
+    ) -> BlockchainConfigResult:
+        return self._model(
+            BlockchainConfigResult,
+            await self.send_http_request(
+                "GET",
+                "/blockchain/config",
+            ),
+        )
+
+    async def blockchain_account(
+        self,
+        address: str,
+    ) -> BlockchainAccountResult:
+        return self._model(
+            BlockchainAccountResult,
+            await self.send_http_request(
+                "GET",
+                f"/blockchain/accounts/{address}",
+            ),
+        )
+
+    async def blockchain_account_transactions(
+        self,
+        address: str,
+        limit: int = 100,
+        after_lt: t.Optional[int] = None,
+        before_lt: t.Optional[int] = None,
+        sort_order: str = "desc",
+    ) -> BlockchainAccountTransactionsResult:
+        params = {"limit": limit, "sort_order": sort_order}
+        if after_lt is not None:
+            params["after_lt"] = after_lt
+        if before_lt is not None and before_lt > 0:
+            params["before_lt"] = before_lt
+
+        return self._model(
+            BlockchainAccountTransactionsResult,
+            await self.send_http_request(
+                "GET",
+                f"/blockchain/accounts/{address}/transactions",
+                params=params,
+            ),
+        )
+
+    async def blockchain_account_method(
+        self,
+        address: str,
+        method_name: str,
+        args: t.List[t.Any],
+    ) -> BlockchainAccountMethodResult:
+        return self._model(
+            BlockchainAccountMethodResult,
+            await self.send_http_request(
+                "GET",
+                f"/blockchain/accounts/{address}/methods/{method_name}",
+                params={"args": args} if args else None,
+            ),
+        )

tonutils/clients/http/providers/toncenter/__init__.py

@@ -0,0 +1,3 @@
+from .provider import ToncenterHttpProvider
+
+__all__ = ["ToncenterHttpProvider"]

tonutils/clients/http/{toncenter → providers/toncenter}/models.py

@@ -87,6 +87,7 @@ class _GetMethod(BaseModel):
     """Container for TVM stack array."""
 
     stack: t.List[t.Any]
+    exit_code: int
 
 
 class RunGetMethodPayload(BaseModel):