tonutils 2.0.1b2__py3-none-any.whl → 2.0.1b4__py3-none-any.whl

tonutils/exceptions.py

@@ -1,294 +1,212 @@
+import asyncio
 import typing as t
 
-from pytoniq_core import Address
-
 __all__ = [
-    "TonutilsException",
-    "ClientNotConnectedError",
-    "NotRefreshedError",
-    "ContractError",
+    "TonutilsError",
+    "TransportError",
+    "ProviderError",
     "ClientError",
-    "AdnlServerError",
-    "AdnlProviderError",
-    "AdnlProviderConnectError",
-    "AdnlProviderClosedError",
-    "AdnlProviderResponseError",
-    "AdnlProviderMissingBlockError",
-    "AdnlBalancerConnectionError",
-    "RateLimitExceededError",
+    "ContractError",
+    "BalancerError",
+    "NotConnectedError",
+    "ProviderTimeoutError",
+    "ProviderResponseError",
+    "RetryLimitError",
     "RunGetMethodError",
-    "AdnlHandshakeError",
-    "AdnlTransportError",
-    "AdnlTransportStateError",
-    "AdnlTransportCipherError",
-    "AdnlTransportFrameError",
+    "StateNotLoadedError",
+    "CDN_CHALLENGE_MARKERS",
 ]
 
 
-class TonutilsException(Exception):
-    """Base exception for all tonutils-specific errors."""
+class TonutilsError(Exception):
+    """Base exception for tonutils."""
 
-    @classmethod
-    def _obj_name(cls, obj: t.Union[object, type, str]) -> str:
-        """
-        Resolve a human-readable class name from an object or type.
 
-        :param obj: Instance, class or string name
-        :return: Resolved name used in error messages
-        """
-        if isinstance(obj, type):
-            return obj.__name__
-        if isinstance(obj, str):
-            return obj
-        return obj.__class__.__name__
+class TransportError(TonutilsError):
+    """Transport-level failure with structured context.
 
+    Covers: TCP connect, ADNL handshake, send/recv, crypto failures.
 
-class ClientNotConnectedError(TonutilsException):
+    :param endpoint: Server address as "host:port"
+    :param operation: What was attempted ("connect", "handshake", "send", "recv")
+    :param reason: Why it failed ("timeout 2.0s", "connection refused", etc.)
     """
-    Raised when a client method is called without an active connection.
 
-    This usually indicates that connect() or an async context manager
-    was not used before making network requests.
-    """
+    endpoint: str
+    operation: str
+    reason: str
 
-    def __init__(self, obj: t.Union[object, type, str]) -> None:
-        name = self._obj_name(obj)
-        super().__init__(
-            f"`{name}` is not connected.\n"
-            f"Use `async with {name}(...) as client:` "
-            f"or call `await {name}(...).connect()` before making requests."
-        )
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        operation: str,
+        reason: str,
+    ) -> None:
+        self.endpoint = endpoint
+        self.operation = operation
+        self.reason = reason
+        super().__init__(f"{operation} failed at {endpoint}: {reason}")
 
 
-class NotRefreshedError(TonutilsException):
-    """
-    Raised when accessing derived state before an explicit refresh.
+class ProviderError(TonutilsError):
+    """Raise on provider-level failures (protocol, parsing, session/state)."""
 
-    Typical usage is for contract wrappers that require refresh()
-    to be called before accessing state_info or derived properties.
-    """
 
-    def __init__(self, obj: t.Union[object, type, str], attr: str) -> None:
-        name = self._obj_name(obj)
-        super().__init__(
-            f"Access to `{attr}` is not allowed.\n"
-            f"Call `await {name}.refresh()` before accessing `{attr}`."
-        )
+class ClientError(TonutilsError):
+    """Raise on client misuse, validation errors, or unsupported operations."""
 
 
-class ContractError(TonutilsException):
-    """
-    Generic error related to smart contract helpers.
+class BalancerError(TonutilsError):
+    """Raise on balancer failures (no alive backends, failover exhausted)."""
 
-    Used for configuration issues, invalid versions and similar
-    contract wrapper problems.
-    """
 
-    def __init__(self, obj: t.Union[object, type, str], message: str) -> None:
-        super().__init__(f"{self._obj_name(obj)}: {message}.")
+class NotConnectedError(TonutilsError, RuntimeError):
+    """Raise when an operation requires an active connection."""
 
+    endpoint: t.Optional[str]
 
-class ClientError(TonutilsException):
-    """
-    Base error for client-side failures.
+    def __init__(self, endpoint: t.Optional[str] = None) -> None:
+        self.endpoint = endpoint
+        if endpoint:
+            super().__init__(f"not connected to {endpoint}")
+        else:
+            super().__init__("not connected")
 
-    Used for issues related to specific client implementations
-    (HTTP, ADNL, balancers, etc.).
-    """
 
+class ProviderTimeoutError(ProviderError, asyncio.TimeoutError):
+    """Raise when a provider operation exceeds its timeout.
 
-class AdnlServerError(ClientError):
+    :param timeout: Timeout in seconds.
+    :param endpoint: Endpoint identifier (URL or host:port).
+    :param operation: Operation label (e.g. "request", "connect").
     """
-    Lite-server reported an internal error while processing a request.
 
-    Wraps lite-server error code and message as returned by ADNL.
-    """
+    timeout: float
+    endpoint: str
+    operation: str
 
-    def __init__(self, code: int, message: str) -> None:
-        """
-        :param code: Lite-server error code
-        :param message: Lite-server error message
-        """
-        super().__init__(f"Lite-server crashed with `{code}` code. Message: {message}.")
-        self.message = message
-        self.code = code
+    def __init__(self, *, timeout: float, endpoint: str, operation: str) -> None:
+        self.timeout = timeout
+        self.endpoint = endpoint
+        self.operation = operation
+        super().__init__(f"{operation} timed out after {timeout}s at {endpoint}")
 
 
-class AdnlProviderError(ClientError):
-    """
-    Base error for ADNL provider failures.
+class ProviderResponseError(ProviderError):
+    """Raise when a backend returns an error response.
 
-    Includes additional context about the lite-server host and port.
+    :param code: Backend code (HTTP status or lite-server code).
+    :param message: Backend error description.
+    :param endpoint: Endpoint identifier (URL or host:port).
     """
 
-    def __init__(self, message: str, host: str, port: int) -> None:
-        """
-        :param message: Error description
-        :param host: Lite-server host
-        :param port: Lite-server port
-        """
-        full_message = f"{message} ({host}:{port})."
-        super().__init__(full_message)
-        self.host = host
-        self.port = port
-
-
-class AdnlProviderConnectError(AdnlProviderError):
-    """
-    Failed to establish an ADNL connection to the lite-server.
+    code: int
+    message: str
+    endpoint: str
 
-    Wraps network or handshake errors that occur during connect().
-    """
-
-    def __init__(self, host: str, port: int, message: str) -> None:
-        super().__init__(
-            f"Failed to connect: {message}.",
-            host=host,
-            port=port,
-        )
+    def __init__(self, *, code: int, message: str, endpoint: str) -> None:
+        self.code = code
+        self.message = message
+        self.endpoint = endpoint
+        super().__init__(f"request failed with code {code} at {endpoint}: {message}")
 
 
-class AdnlProviderClosedError(AdnlProviderError):
-    """
-    ADNL provider was closed while waiting for a response.
+class RetryLimitError(ProviderError):
+    """Raise when retry policy is exhausted for a matched rule.
 
-    Typically raised when transport is torn down during an in-flight
-    request or when the remote peer closes connection unexpectedly.
+    :param attempts: Attempts already performed for the matched rule.
+    :param max_attempts: Maximum attempts allowed by the matched rule.
+    :param last_error: Last provider error that triggered a retry.
     """
 
-    def __init__(self, host: str, port: int) -> None:
-        super().__init__(
-            "Provider closed while waiting response.",
-            host=host,
-            port=port,
-        )
-
+    attempts: int
+    max_attempts: int
+    last_error: ProviderError
 
-class AdnlProviderResponseError(AdnlProviderError):
-    """
-    Received an invalid or malformed response from lite-server.
-
-    Raised when the ADNL response payload does not match the expected
-    structure or type.
-    """
+    def __init__(
+        self,
+        *,
+        attempts: int,
+        max_attempts: int,
+        last_error: ProviderError,
+    ) -> None:
+        self.attempts = attempts
+        self.max_attempts = max_attempts
+        self.last_error = last_error
+        super().__init__(f"retry exhausted ({attempts}/{max_attempts}): {last_error}")
 
-    def __init__(self, host: str, port: int) -> None:
-        super().__init__(
-            "Invalid response from provider.",
-            host=host,
-            port=port,
-        )
 
+class ContractError(ClientError):
+    """Raise when a contract wrapper operation fails.
 
-class AdnlProviderMissingBlockError(AdnlProviderError):
+    :param target: Contract instance or contract class related to the failure.
+    :param message: Human-readable error message.
     """
-    Lite-server reported that a requested block is missing.
 
-    Used for specific lite-server error codes that indicate
-    absence of the requested block.
-    """
+    target: t.Any
+    message: str
 
-    def __init__(self, attempts: int, host: str, port: int, message: str) -> None:
-        super().__init__(
-            f"Cannot load block after {attempts} attempts: {message}.",
-            host=host,
-            port=port,
+    def __init__(self, target: t.Any, message: str) -> None:
+        self.target = target
+        self.message = message
+        name = (
+            target.__name__ if isinstance(target, type) else target.__class__.__name__
         )
-        self.attempts = attempts
+        super().__init__(f"{name}: {message}")
 
 
-class AdnlBalancerConnectionError(ClientError):
-    """
-    All ADNL lite-server providers failed to connect or process a request.
+class StateNotLoadedError(ContractError):
+    """Raise when a contract wrapper requires state that is not loaded.
 
-    Raised by AdnlBalancer when no healthy providers remain.
+    :param contract: Contract instance related to the failure.
+    :param missing: Missing field name (e.g. "state_info", "state_data").
     """
 
+    missing: str
 
-class RateLimitExceededError(ClientError):
-    """
-    Request was retried multiple times but rate limits could not be bypassed.
-
-    Raised after exhausting configured retry attempts.
-    """
-
-    def __init__(self, attempts: int) -> None:
-        """
-        :param attempts: Number of attempts performed before giving up
-        """
-        super().__init__(f"Rate limit exceeded after `{attempts}` attempts.")
-        self.attempts = attempts
+    def __init__(self, contract: t.Any, *, missing: str) -> None:
+        self.missing = missing
+        name = contract.__class__.__name__
+        super().__init__(contract, f"{missing} is not loaded. Call {name}.refresh().")
 
 
 class RunGetMethodError(ClientError):
-    """
-    get-method execution failed with a non-zero exit code.
+    """Raise when a contract get-method returns a non-zero TVM exit code.
 
-    Raised when lite-server returns exit_code != 0 for a runSmcMethod call.
+    :param address: Contract address (string form).
+    :param method_name: Get-method name.
+    :param exit_code: TVM exit code.
     """
 
-    def __init__(self, address: Address, method_name: str, exit_code: int) -> None:
-        """
-        :param address: Contract address on which get-method was executed
-        :param method_name: Name of the get-method
-        :param exit_code: Non-zero TVM exit code returned by the method
-        """
-        super().__init__(
-            f"Get method `{method_name}` on `{address.to_str()}` "
-            f"failed with `{exit_code}` exit code."
-        )
+    address: str
+    method_name: str
+    exit_code: int
+
+    def __init__(self, *, address: str, method_name: str, exit_code: int) -> None:
+        self.address = address
         self.method_name = method_name
         self.exit_code = exit_code
-        self.address = address
-
-
-class AdnlTransportError(TonutilsException):
-    """
-    Base error for raw ADNL transport failures.
-
-    Covers handshake, cipher initialization, framing and state issues.
-    """
-
-
-class AdnlHandshakeError(AdnlTransportError):
-    """
-    ADNL handshake failed during initial connection.
-
-    Raised when the remote side closes the connection or does not
-    respond within the expected timeout.
-    """
-
-
-class AdnlTransportStateError(AdnlTransportError):
-    """
-    Invalid internal state of the ADNL transport.
-
-    Raised when required transport components (reader, writer, cipher, etc.)
-    are not initialized or used incorrectly.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(f"ADNL transport state error: {message}.")
-
-
-class AdnlTransportCipherError(AdnlTransportError):
-    """
-    ADNL cipher was used before being initialized.
-
-    Raised when trying to encrypt or decrypt frames without
-    a valid session cipher.
-    """
-
-    def __init__(self, direction: str) -> None:
-        super().__init__(f"ADNL {direction} cipher is not initialized.")
-
-
-class AdnlTransportFrameError(AdnlTransportError):
-    """
-    Malformed or invalid ADNL frame was received.
+        super().__init__(
+            f"get-method '{method_name}' failed for {address} with exit code {exit_code}"
+        )
 
-    Raised when frame length, structure or checksum validation fails.
-    """
 
-    def __init__(self, reason: str) -> None:
-        super().__init__(f"Invalid ADNL frame: {reason}.")
+CDN_CHALLENGE_MARKERS: t.Dict[str, str] = {
+    # Cloudflare
+    "cloudflare": "Cloudflare protection triggered or blocked the request.",
+    "cf-ray": "Cloudflare intermediate error (cf-ray header detected).",
+    "just a moment": "Cloudflare browser verification page.",
+    "checking your browser": "Cloudflare browser verification page.",
+    "attention required": "Cloudflare challenge page.",
+    "captcha": "Cloudflare CAPTCHA challenge.",
+    # Other CDNs / proxies
+    "akamai": "Akamai CDN blocked or intercepted the request.",
+    "fastly": "Fastly CDN error response detected.",
+    "varnish": "Varnish cache/CDN interference.",
+    "nginx": "Reverse proxy (nginx) error response.",
+    # Upstream failures
+    "502 bad gateway": "Bad gateway from upstream or proxy.",
+    "503 service unavailable": "Service temporarily unavailable (proxy or CDN).",
+    "ddos": "Possible DDoS protection or mitigation page.",
+}

tonutils/tools/__init__.py

@@ -0,0 +1,6 @@
+from . import block_scanner, status_monitor
+
+__all__ = [
+    "block_scanner",
+    "status_monitor",
+]

tonutils/tools/block_scanner/__init__.py

@@ -0,0 +1,26 @@
+from .events import (
+    BlockEvent,
+    TransactionEvent,
+    TransactionsEvent,
+)
+from .scanner import BlockScanner
+from .where import (
+    Where,
+    comment,
+    destination,
+    opcode,
+    sender,
+)
+
+
+__all__ = [
+    "BlockScanner",
+    "BlockEvent",
+    "TransactionEvent",
+    "TransactionsEvent",
+    "Where",
+    "comment",
+    "destination",
+    "opcode",
+    "sender",
+]

tonutils/tools/block_scanner/annotations.py

@@ -0,0 +1,23 @@
+import typing as t
+
+from tonutils.tools.block_scanner.events import (
+    BlockEvent,
+    EventBase,
+    TransactionEvent,
+    TransactionsEvent,
+)
+
+TEvent = t.TypeVar("TEvent", bound=EventBase)
+
+Handler = t.Callable[[TEvent], t.Awaitable[None]]
+Where = t.Callable[[TEvent], t.Union[bool, t.Awaitable[bool]]]
+
+BlockWhere = t.Callable[[BlockEvent], t.Union[bool, t.Awaitable[bool]]]
+TransactionWhere = t.Callable[[TransactionEvent], t.Union[bool, t.Awaitable[bool]]]
+TransactionsWhere = t.Callable[[TransactionsEvent], t.Union[bool, t.Awaitable[bool]]]
+
+AnyHandler = t.Callable[[EventBase], t.Awaitable[None]]
+AnyWhere = t.Callable[[EventBase], t.Union[bool, t.Awaitable[bool]]]
+
+HandlerEntry = t.Tuple[AnyHandler, t.Optional[AnyWhere]]
+Decorator = t.Callable[[Handler[TEvent]], Handler[TEvent]]

tonutils/tools/block_scanner/dispatcher.py

@@ -0,0 +1,141 @@
+import asyncio
+import inspect
+import traceback
+import typing as t
+
+from tonutils.tools.block_scanner.annotations import (
+    AnyHandler,
+    AnyWhere,
+    Decorator,
+    Handler,
+    HandlerEntry,
+    TEvent,
+    Where,
+)
+from tonutils.tools.block_scanner.events import EventBase
+
+
+class EventDispatcher:
+    """Dispatches events to registered handlers asynchronously."""
+
+    def __init__(self, max_concurrency: int = 1000) -> None:
+        """
+        Initialize EventDispatcher.
+
+        :param max_concurrency: maximum number of concurrent handler tasks.
+        """
+        self._handlers: t.Dict[t.Type[EventBase], t.List[HandlerEntry]] = {}
+        self._sem = asyncio.Semaphore(max(1, max_concurrency))
+        self._tasks: t.Set[asyncio.Task[None]] = set()
+        self._closed = False
+
+    def register(
+        self,
+        event_type: t.Type[TEvent],
+        handler: Handler[TEvent],
+        *,
+        where: t.Optional[Where[TEvent]] = None,
+    ) -> None:
+        """
+        Register a handler for a specific event type.
+
+        :param event_type: subclass of EventBase to handle.
+        :param handler: callable receiving the event.
+        :param where: optional filter predicate. Handler is invoked only if predicate returns True.
+        """
+        if not callable(handler):
+            raise TypeError("handler must be callable")
+
+        entry: HandlerEntry = (
+            t.cast(AnyHandler, handler),
+            t.cast(t.Optional[AnyWhere], where),
+        )
+        self._handlers.setdefault(event_type, []).append(entry)
+
+    def on(
+        self,
+        event_type: t.Type[TEvent],
+        *,
+        where: t.Optional[Where[TEvent]] = None,
+    ) -> Decorator[TEvent]:
+        """
+        Decorator to register a handler for an event type.
+
+        :param event_type: event class to handle.
+        :param where: optional filter predicate.
+        :return: Decorator that registers the handler.
+        """
+
+        def decorator(fn: Handler[TEvent]) -> Handler[TEvent]:
+            self.register(event_type=event_type, handler=fn, where=where)
+            return fn
+
+        return decorator
+
+    def _iter_handlers(self, event: EventBase) -> t.Sequence[HandlerEntry]:
+        """Return all handlers matching the type of `event`."""
+        out: t.List[HandlerEntry] = []
+        for tp in type(event).mro():
+            if tp is EventBase:
+                break
+            entries = self._handlers.get(t.cast(t.Type[EventBase], tp))
+            if entries:
+                out.extend(entries)
+        return out
+
+    def _on_task_done(self, task: asyncio.Task[None]) -> None:
+        """Callback to handle task completion and print exceptions."""
+        self._tasks.discard(task)
+        try:
+            exc = task.exception()
+        except asyncio.CancelledError:
+            return
+        if exc is not None:
+            traceback.print_exception(type(exc), exc, exc.__traceback__)
+
+    async def _run_task(
+        self,
+        handler: AnyHandler,
+        event: EventBase,
+        where: t.Optional[AnyWhere] = None,
+    ) -> None:
+        """
+        Run a single handler task with optional 'where' filtering.
+
+        :param handler: async callable to execute.
+        :param event: event instance to pass.
+        :param where: optional predicate, skip handler if False.
+        """
+        async with self._sem:
+            if where is not None:
+                result = where(event)
+                if inspect.isawaitable(result):
+                    result = await result
+                if not result:
+                    return
+            await handler(event)
+
+    def emit(self, event: EventBase) -> None:
+        """
+        Emit an event to all matching handlers.
+
+        Handlers are executed asynchronously.
+        """
+        if self._closed:
+            return
+
+        for handler, where in self._iter_handlers(event):
+            task = asyncio.create_task(self._run_task(handler, event, where))
+            self._tasks.add(task)
+            task.add_done_callback(self._on_task_done)
+
+    async def aclose(self) -> None:
+        """
+        Close the dispatcher and wait for all running handler tasks.
+
+        After calling, no new events will be dispatched.
+        """
+        self._closed = True
+        if self._tasks:
+            await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()

tonutils/tools/block_scanner/events.py

@@ -0,0 +1,31 @@
+import typing as t
+from dataclasses import dataclass, field
+
+from pytoniq_core import Transaction
+from pytoniq_core.tl import BlockIdExt
+
+from tonutils.clients import LiteBalancer, LiteClient
+
+
+@dataclass(frozen=True, slots=True)
+class EventBase:
+    client: t.Union[LiteBalancer, LiteClient]
+    mc_block: BlockIdExt
+    context: t.Dict[str, t.Any]
+
+
+@dataclass(frozen=True, slots=True)
+class BlockEvent(EventBase):
+    block: BlockIdExt
+
+
+@dataclass(frozen=True, slots=True)
+class TransactionEvent(EventBase):
+    block: BlockIdExt
+    transaction: Transaction
+
+
+@dataclass(frozen=True, slots=True)
+class TransactionsEvent(EventBase):
+    block: BlockIdExt
+    transactions: t.List[Transaction] = field(default_factory=list)