web3 7.0.0b1__py3-none-any.whl → 7.7.0__py3-none-any.whl

web3/manager.py

@@ -5,6 +5,8 @@ from typing import (
     Any,
     AsyncGenerator,
     Callable,
+    Coroutine,
+    Dict,
     List,
     Optional,
     Sequence,
@@ -19,10 +21,10 @@ from eth_utils.toolz import (
 from hexbytes import (
     HexBytes,
 )
-from websockets.exceptions import (
-    ConnectionClosedOK,
-)
 
+from web3._utils.batching import (
+    RequestBatcher,
+)
 from web3._utils.caching import (
     generate_cache_key,
 )
@@ -36,6 +38,14 @@ from web3.exceptions import (
     BadResponseFormat,
     MethodUnavailable,
     ProviderConnectionError,
+    RequestTimedOut,
+    TaskNotRunning,
+    TransactionNotFound,
+    Web3RPCError,
+    Web3TypeError,
+)
+from web3.method import (
+    Method,
 )
 from web3.middleware import (
     AttributeDictMiddleware,
@@ -53,10 +63,16 @@ from web3.module import (
 )
 from web3.providers import (
     AutoProvider,
+    JSONBaseProvider,
     PersistentConnectionProvider,
 )
+from web3.providers.async_base import (
+    AsyncJSONBaseProvider,
+)
 from web3.types import (
+    FormattedEthSubscriptionResponse,
     RPCEndpoint,
+    RPCRequest,
     RPCResponse,
 )
 
@@ -78,6 +94,13 @@ if TYPE_CHECKING:
 
 
 NULL_RESPONSES = [None, HexBytes("0x"), "0x"]
+KNOWN_REQUEST_TIMEOUT_MESSAGING = {
+    # Note: It's important to be very explicit here and not too broad. We don't want
+    # to accidentally catch a message that is not for a request timeout. In the worst
+    # case, we raise something more generic like `Web3RPCError`. JSON-RPC unfortunately
+    # has not standardized error codes for request timeouts.
+    "request timed out",  # go-ethereum
+}
 METHOD_NOT_FOUND = -32601
 
 
@@ -86,6 +109,7 @@ def _raise_bad_response_format(response: RPCResponse, error: str = "") -> None:
     raw_response = f"The raw response is: {response}"
 
     if error is not None and error != "":
+        error = error[:-1] if error.endswith(".") else error
         message = f"{message} {error}. {raw_response}"
     else:
         message = f"{message} {raw_response}"
@@ -116,6 +140,132 @@ def apply_null_result_formatters(
         return response
 
 
+def _validate_subscription_fields(response: RPCResponse) -> None:
+    params = response["params"]
+    subscription = params["subscription"]
+    if not isinstance(subscription, str) and not len(subscription) == 34:
+        _raise_bad_response_format(
+            response, "eth_subscription 'params' must include a 'subscription' field."
+        )
+
+
+def _validate_response(
+    response: RPCResponse,
+    error_formatters: Optional[Callable[..., Any]],
+    is_subscription_response: bool = False,
+    logger: Optional[logging.Logger] = None,
+    params: Optional[Any] = None,
+) -> None:
+    if "jsonrpc" not in response or response["jsonrpc"] != "2.0":
+        _raise_bad_response_format(
+            response, 'The "jsonrpc" field must be present with a value of "2.0".'
+        )
+
+    response_id = response.get("id")
+    if "id" in response:
+        int_error_msg = (
+            '"id" must be an integer or a string representation of an integer.'
+        )
+        if response_id is None and "error" in response:
+            # errors can sometimes have null `id`, according to the JSON-RPC spec
+            pass
+        elif not isinstance(response_id, (str, int)):
+            _raise_bad_response_format(response, int_error_msg)
+        elif isinstance(response_id, str):
+            try:
+                int(response_id)
+            except ValueError:
+                _raise_bad_response_format(response, int_error_msg)
+    elif is_subscription_response:
+        # if `id` is not present, this must be a subscription response
+        _validate_subscription_fields(response)
+    else:
+        _raise_bad_response_format(
+            response,
+            'Response must include an "id" field or be formatted as an '
+            "`eth_subscription` response.",
+        )
+
+    if all(key in response for key in {"error", "result"}):
+        _raise_bad_response_format(
+            response, 'Response cannot include both "error" and "result".'
+        )
+    elif (
+        not any(key in response for key in {"error", "result"})
+        and not is_subscription_response
+    ):
+        _raise_bad_response_format(
+            response, 'Response must include either "error" or "result".'
+        )
+    elif "error" in response:
+        web3_rpc_error: Optional[Web3RPCError] = None
+        error = response["error"]
+
+        # raise the error when the value is a string
+        if error is None or not isinstance(error, dict):
+            _raise_bad_response_format(
+                response,
+                'response["error"] must be a valid object as defined by the '
+                "JSON-RPC 2.0 specification.",
+            )
+
+        # errors must include a message
+        error_message = error.get("message")
+        if not isinstance(error_message, str):
+            _raise_bad_response_format(
+                response, 'error["message"] is required and must be a string value.'
+            )
+        elif error_message == "transaction not found":
+            transaction_hash = params[0]
+            web3_rpc_error = TransactionNotFound(
+                repr(error),
+                rpc_response=response,
+                user_message=(f"Transaction with hash {transaction_hash!r} not found."),
+            )
+
+        # errors must include an integer code
+        code = error.get("code")
+        if not isinstance(code, int):
+            _raise_bad_response_format(
+                response, 'error["code"] is required and must be an integer value.'
+            )
+        elif code == METHOD_NOT_FOUND:
+            web3_rpc_error = MethodUnavailable(
+                repr(error),
+                rpc_response=response,
+                user_message=(
+                    "This method is not available. Check your node provider or your "
+                    "client's API docs to see what methods are supported and / or "
+                    "currently enabled."
+                ),
+            )
+        elif any(
+            # parse specific timeout messages
+            timeout_str in error_message.lower()
+            for timeout_str in KNOWN_REQUEST_TIMEOUT_MESSAGING
+        ):
+            web3_rpc_error = RequestTimedOut(
+                repr(error),
+                rpc_response=response,
+                user_message=(
+                    "The request timed out. Check the connection to your node and "
+                    "try again."
+                ),
+            )
+
+        if web3_rpc_error is None:
+            # if no condition was met above, raise a more generic `Web3RPCError`
+            web3_rpc_error = Web3RPCError(repr(error), rpc_response=response)
+
+        response = apply_error_formatters(error_formatters, response)
+        logger.debug(f"RPC error response: {response}")
+
+        raise web3_rpc_error
+
+    elif "result" not in response and not is_subscription_response:
+        _raise_bad_response_format(response)
+
+
 class RequestManager:
     logger = logging.getLogger("web3.manager.RequestManager")
 
@@ -125,7 +275,7 @@ class RequestManager:
         self,
         w3: Union["AsyncWeb3", "Web3"],
         provider: Optional[Union["BaseProvider", "AsyncBaseProvider"]] = None,
-        middlewares: Optional[Sequence[Tuple[Middleware, str]]] = None,
+        middleware: Optional[Sequence[Tuple[Middleware, str]]] = None,
     ) -> None:
         self.w3 = w3
 
@@ -134,10 +284,10 @@ class RequestManager:
         else:
             self.provider = provider
 
-        if middlewares is None:
-            middlewares = self.get_default_middlewares()
+        if middleware is None:
+            middleware = self.get_default_middleware()
 
-        self.middleware_onion = NamedElementOnion(middlewares)
+        self.middleware_onion = NamedElementOnion(middleware)
 
         if isinstance(provider, PersistentConnectionProvider):
             # set up the request processor to be able to properly process ordered
@@ -145,9 +295,6 @@ class RequestManager:
             provider = cast(PersistentConnectionProvider, self.provider)
             self._request_processor: RequestProcessor = provider._request_processor
 
-    w3: Union["AsyncWeb3", "Web3"] = None
-    _provider = None
-
     @property
     def provider(self) -> Union["BaseProvider", "AsyncBaseProvider"]:
         return self._provider
@@ -157,9 +304,9 @@ class RequestManager:
         self._provider = provider
 
     @staticmethod
-    def get_default_middlewares() -> List[Tuple[Middleware, str]]:
+    def get_default_middleware() -> List[Tuple[Middleware, str]]:
         """
-        List the default middlewares for the request manager.
+        List the default middleware for the request manager.
         Documentation should remain in sync with these defaults.
         """
         return [
@@ -202,86 +349,43 @@ class RequestManager:
     #
     # See also: https://www.jsonrpc.org/specification
     #
-    @staticmethod
     def formatted_response(
+        self,
         response: RPCResponse,
         params: Any,
         error_formatters: Optional[Callable[..., Any]] = None,
         null_result_formatters: Optional[Callable[..., Any]] = None,
     ) -> Any:
-        # jsonrpc is not enforced (as per the spec) but if present, it must be 2.0
-        if "jsonrpc" in response and response["jsonrpc"] != "2.0":
-            _raise_bad_response_format(
-                response, 'The "jsonrpc" field must be present with a value of "2.0"'
-            )
-
-        # id is not enforced (as per the spec) but if present, it must be a
-        # string or integer
-        # TODO: v7 - enforce id per the spec
-        if "id" in response:
-            response_id = response["id"]
-            # id is always None for errors
-            if response_id is None and "error" not in response:
-                _raise_bad_response_format(
-                    response, '"id" must be None when an error is present'
-                )
-            elif not isinstance(response_id, (str, int, type(None))):
-                _raise_bad_response_format(response, '"id" must be a string or integer')
-
-        # Response may not include both "error" and "result"
-        if "error" in response and "result" in response:
-            _raise_bad_response_format(
-                response, 'Response cannot include both "error" and "result"'
-            )
-
-        # Format and validate errors
-        elif "error" in response:
-            error = response.get("error")
-            # Raise the error when the value is a string
-            if error is None or isinstance(error, str):
-                raise ValueError(error)
-
-            # Errors must include an integer code
-            code = error.get("code")
-            if not isinstance(code, int):
-                _raise_bad_response_format(response, "error['code'] must be an integer")
-            elif code == METHOD_NOT_FOUND:
-                raise MethodUnavailable(error)
-
-            # Errors must include a message
-            if not isinstance(error.get("message"), str):
-                _raise_bad_response_format(
-                    response, "error['message'] must be a string"
-                )
-
-            apply_error_formatters(error_formatters, response)
+        is_subscription_response = (
+            response.get("method") == "eth_subscription"
+            and response.get("params") is not None
+            and response["params"].get("subscription") is not None
+            and response["params"].get("result") is not None
+        )
 
-            raise ValueError(error)
+        _validate_response(
+            response,
+            error_formatters,
+            is_subscription_response=is_subscription_response,
+            logger=self.logger,
+            params=params,
+        )
 
-        # Format and validate results
-        elif "result" in response:
+        # format results
+        if "result" in response:
             # Null values for result should apply null_result_formatters
             # Skip when result not present in the response (fallback to False)
             if response.get("result", False) in NULL_RESPONSES:
                 apply_null_result_formatters(null_result_formatters, response, params)
             return response.get("result")
 
-        # Response from eth_subscription includes response["params"]["result"]
-        elif (
-            response.get("method") == "eth_subscription"
-            and response.get("params") is not None
-            and response["params"].get("subscription") is not None
-            and response["params"].get("result") is not None
-        ):
+        # response from eth_subscription includes response["params"]["result"]
+        elif is_subscription_response:
             return {
                 "subscription": response["params"]["subscription"],
                 "result": response["params"]["result"],
             }
 
-        # Any other response type raises BadResponseFormat
-        else:
-            _raise_bad_response_format(response)
-
     def request_blocking(
         self,
         method: Union[RPCEndpoint, Callable[..., RPCEndpoint]],
@@ -312,32 +416,181 @@ class RequestManager:
             response, params, error_formatters, null_result_formatters
         )
 
+    # -- batch requests management -- #
+
+    def _batch_requests(self) -> RequestBatcher[Method[Callable[..., Any]]]:
+        """
+        Context manager for making batch requests
+        """
+        if not isinstance(self.provider, (AsyncJSONBaseProvider, JSONBaseProvider)):
+            raise Web3TypeError("Batch requests are not supported by this provider.")
+        return RequestBatcher(self.w3)
+
+    def _make_batch_request(
+        self, requests_info: List[Tuple[Tuple["RPCEndpoint", Any], Sequence[Any]]]
+    ) -> List[RPCResponse]:
+        """
+        Make a batch request using the provider
+        """
+        provider = cast(JSONBaseProvider, self.provider)
+        request_func = provider.batch_request_func(
+            cast("Web3", self.w3), cast("MiddlewareOnion", self.middleware_onion)
+        )
+        responses = request_func(
+            [
+                (method, params)
+                for (method, params), _response_formatters in requests_info
+            ]
+        )
+        formatted_responses = [
+            self._format_batched_response(info, resp)
+            for info, resp in zip(requests_info, responses)
+        ]
+        return list(formatted_responses)
+
+    async def _async_make_batch_request(
+        self,
+        requests_info: List[
+            Coroutine[Any, Any, Tuple[Tuple["RPCEndpoint", Any], Sequence[Any]]]
+        ],
+    ) -> List[RPCResponse]:
+        """
+        Make an asynchronous batch request using the provider
+        """
+        provider = cast(AsyncJSONBaseProvider, self.provider)
+        request_func = await provider.batch_request_func(
+            cast("AsyncWeb3", self.w3),
+            cast("MiddlewareOnion", self.middleware_onion),
+        )
+        # since we add items to the batch without awaiting, we unpack the coroutines
+        # and await them all here
+        unpacked_requests_info = await asyncio.gather(*requests_info)
+        responses = await request_func(
+            [
+                (method, params)
+                for (method, params), _response_formatters in unpacked_requests_info
+            ]
+        )
+
+        if isinstance(self.provider, PersistentConnectionProvider):
+            # call _process_response for each response in the batch
+            return [
+                cast(RPCResponse, await self._process_response(resp))
+                for resp in responses
+            ]
+
+        formatted_responses = [
+            self._format_batched_response(info, resp)
+            for info, resp in zip(unpacked_requests_info, responses)
+        ]
+        return list(formatted_responses)
+
+    def _format_batched_response(
+        self,
+        requests_info: Tuple[Tuple[RPCEndpoint, Any], Sequence[Any]],
+        response: RPCResponse,
+    ) -> RPCResponse:
+        result_formatters, error_formatters, null_result_formatters = requests_info[1]
+        return apply_result_formatters(
+            result_formatters,
+            self.formatted_response(
+                response,
+                requests_info[0][1],
+                error_formatters,
+                null_result_formatters,
+            ),
+        )
+
     # -- persistent connection -- #
 
-    async def send(self, method: RPCEndpoint, params: Any) -> RPCResponse:
+    async def socket_request(
+        self,
+        method: RPCEndpoint,
+        params: Any,
+        response_formatters: Optional[
+            Tuple[Dict[str, Callable[..., Any]], Callable[..., Any], Callable[..., Any]]
+        ] = None,
+    ) -> RPCResponse:
         provider = cast(PersistentConnectionProvider, self._provider)
-        request_func = await provider.request_func(
-            cast("AsyncWeb3", self.w3), cast("MiddlewareOnion", self.middleware_onion)
+        self.logger.debug(
+            "Making request to open socket connection and waiting for response: "
+            f"{provider.get_endpoint_uri_or_ipc_path()},\n    method: {method},\n"
+            f"    params: {params}"
+        )
+        rpc_request = await self.send(method, params)
+        provider._request_processor.cache_request_information(
+            rpc_request["id"],
+            rpc_request["method"],
+            rpc_request["params"],
+            response_formatters=response_formatters or ((), (), ()),
+        )
+        return await self.recv_for_request(rpc_request)
+
+    async def send(self, method: RPCEndpoint, params: Any) -> RPCRequest:
+        provider = cast(PersistentConnectionProvider, self._provider)
+        async_w3 = cast("AsyncWeb3", self.w3)
+        middleware_onion = cast("MiddlewareOnion", self.middleware_onion)
+        send_func = await provider.send_func(
+            async_w3,
+            middleware_onion,
         )
         self.logger.debug(
-            "Making request to open socket connection - "
-            f"uri: {provider.endpoint_uri}, method: {method}"
+            "Sending request to open socket connection: "
+            f"{provider.get_endpoint_uri_or_ipc_path()},\n    method: {method},\n"
+            f"    params: {params}"
+        )
+        return await send_func(method, params)
+
+    async def recv_for_request(self, rpc_request: RPCRequest) -> RPCResponse:
+        provider = cast(PersistentConnectionProvider, self._provider)
+        async_w3 = cast("AsyncWeb3", self.w3)
+        middleware_onion = cast("MiddlewareOnion", self.middleware_onion)
+        recv_func = await provider.recv_func(
+            async_w3,
+            middleware_onion,
+        )
+        self.logger.debug(
+            "Getting response for request from open socket connection:\n"
+            f"    request: {rpc_request}"
+        )
+        response = await recv_func(rpc_request)
+        try:
+            return cast(RPCResponse, await self._process_response(response))
+        except Exception:
+            response_id_key = generate_cache_key(response["id"])
+            provider._request_processor._request_information_cache.pop(response_id_key)
+            raise
+
+    async def recv(self) -> Union[RPCResponse, FormattedEthSubscriptionResponse]:
+        provider = cast(PersistentConnectionProvider, self._provider)
+        self.logger.debug(
+            "Getting next response from open socket connection: "
+            f"{provider.get_endpoint_uri_or_ipc_path()}"
+        )
+        # pop from the queue since the listener task is responsible for reading
+        # directly from the socket
+        request_response_cache = self._request_processor._request_response_cache
+        _key, response = await request_response_cache.async_await_and_popitem(
+            last=False,
+            timeout=provider.request_timeout,
         )
-        response = await request_func(method, params)
         return await self._process_response(response)
 
     def _persistent_message_stream(self) -> "_AsyncPersistentMessageStream":
         return _AsyncPersistentMessageStream(self)
 
-    async def _get_next_message(self) -> Any:
+    async def _get_next_message(self) -> FormattedEthSubscriptionResponse:
         return await self._message_stream().__anext__()
 
-    async def _message_stream(self) -> AsyncGenerator[RPCResponse, None]:
+    async def _message_stream(
+        self,
+    ) -> AsyncGenerator[FormattedEthSubscriptionResponse, None]:
         if not isinstance(self._provider, PersistentConnectionProvider):
-            raise TypeError(
+            raise Web3TypeError(
                 "Only providers that maintain an open, persistent connection "
                 "can listen to streams."
             )
+        async_w3 = cast("AsyncWeb3", self.w3)
 
         if self._provider._message_listener_task is None:
             raise ProviderConnectionError(
@@ -345,20 +598,37 @@ class RequestManager:
             )
 
         while True:
-            # sleep(0) here seems to be the most efficient way to yield control
-            # back to the event loop while waiting for the response in the queue.
-            await asyncio.sleep(0)
-
-            response = self._request_processor.pop_raw_response(subscription=True)
-            if (
-                response is not None
-                and response.get("params", {}).get("subscription")
-                in self._request_processor.active_subscriptions
-            ):
-                # if response is an active subscription response, process it
-                yield await self._process_response(response)
-
-    async def _process_response(self, response: RPCResponse) -> RPCResponse:
+            try:
+                response = await self._request_processor.pop_raw_response(
+                    subscription=True
+                )
+                # if the subscription was unsubscribed from, we won't have a formatted
+                # response because we lost the request information.
+                sub_id = response.get(
+                    "subscription", response.get("params", {}).get("subscription")
+                )
+                if async_w3.subscription_manager.get_by_id(sub_id):
+                    # if active subscription, process and yield the formatted response
+                    formatted_sub_response = cast(
+                        FormattedEthSubscriptionResponse,
+                        await self._process_response(response),
+                    )
+                    yield formatted_sub_response
+                else:
+                    # if not an active sub, skip processing and continue
+                    continue
+            except TaskNotRunning:
+                await asyncio.sleep(0)
+                self._provider._handle_listener_task_exceptions()
+                self.logger.error(
+                    "Message listener background task has stopped unexpectedly. "
+                    "Stopping message stream."
+                )
+                return
+
+    async def _process_response(
+        self, response: RPCResponse
+    ) -> Union[RPCResponse, FormattedEthSubscriptionResponse]:
         provider = cast(PersistentConnectionProvider, self._provider)
         request_info = self._request_processor.get_request_information_for_response(
             response
@@ -421,8 +691,5 @@ class _AsyncPersistentMessageStream:
     def __aiter__(self) -> Self:
         return self
 
-    async def __anext__(self) -> RPCResponse:
-        try:
-            return await self.manager._get_next_message()
-        except ConnectionClosedOK:
-            raise StopAsyncIteration
+    async def __anext__(self) -> FormattedEthSubscriptionResponse:
+        return await self.manager._get_next_message()