kiba-core 0.5.3.dev71__tar.gz → 0.5.3.dev72__tar.gz

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- [MAJOR] Updated `RestEthClient` to raise `RpcServerException` (a `ServerException` keeping the original status code and message, with the original exception as its cause) when the node responds with a 5xx, so callers can tell node failures apart from other server errors; `RequesterTimeoutException` is still raised unchanged. Code catching `InternalServerErrorException` (or `BadGatewayException`, `ServiceUnavailableException`, …) around `RestEthClient` calls must catch `RpcServerException` instead
+- [MINOR] Added `RestEthClient.get_code`
+- [MINOR] Added optional `maxConcurrentRequestCount` and `semaphore` to `RestEthClient` to limit concurrent requests; pass the same `semaphore` to several clients to limit them together (it takes precedence over `maxConcurrentRequestCount`)
+- [MINOR] Added `EthClientRegistry` to register regular, archive and paymaster `RestEthClient`s per chain and pick the archive client for dates older than `archiveThresholdDays` (default 15)
 - [PATCH] Fixed log records from `logging.info`, `warning`, `error`, `critical`, `debug`, `exception`, `stat` and `api` recording their location as `core/logging.py` instead of the calling code; this was only visible in `init_logging`'s text format, since the JSON and basic formats don't output the location
 - [MINOR] Updated `init_logging`, `init_json_logging` and `init_basic_logging` to set the loggers of the third-party libraries core uses (`DEFAULT_EXTERNAL_LOGGER_NAMES`: httpx2, httpcore2, sqlalchemy, aiosqlite, asyncpg, botocore, aiobotocore, azure, apscheduler, web3) to `WARNING`; pass `extraLoggerNames` to quieten more loggers on top of these, or `loggerNames` to replace them (`loggerNames=[]` keeps the previous behaviour). `init_external_loggers` takes the same arguments and now defaults to the same list
 - [MINOR] Added `core.cron` (install with the `cron` extra): `CronJob` schedules (interval with jitter, or crontab) that declare a `jobType`, `CronJobProcessor`s that declare the `jobTypes` they process, and `CronExecutor`, which takes a list of processors, routes each job to the processor for its type (failing at startup if a job type has no processor or more than one), runs jobs on an APScheduler scheduler, logs each run as a `CRON` api log with its status and duration, and keeps running when a job fails; also added `ApiRequestCronJob` with `ApiRequestCronJobProcessor` (needs the `requester` extra) for jobs that call a URL

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev71
+Version: 0.5.3.dev72
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/core/web3/eth_client.py

@@ -1,4 +1,5 @@
 import asyncio
+import contextlib
 import typing
 from typing import Any
 
@@ -24,8 +25,11 @@ from core.exceptions import BadRequestException
 from core.exceptions import ClientException
 from core.exceptions import KibaException
 from core.exceptions import NotFoundException
+from core.exceptions import ServerException
 from core.exceptions import TooManyRequestsException
 from core.requester import Requester
+from core.requester.requester import RequesterTimeoutException
+from core.requester.requester import ResponseException
 from core.util import chain_util
 from core.util import json_util
 from core.util.typing_util import JsonObject
@@ -61,6 +65,11 @@ class TransactionFailedException(KibaException):
         return output
 
 
+class RpcServerException(ServerException):
+    def __init__(self, message: str | None = None, statusCode: int = 500) -> None:
+        super().__init__(message=message or 'RPC Server Error', statusCode=statusCode)
+
+
 class EthClientInterface:
     def __init__(self, web3Connection: Web3, chainId: int, isTestnet: bool = False) -> None:
         self.w3 = web3Connection
@@ -297,12 +306,26 @@ class Web3EthClient(EthClientInterface):
 
 class RestEthClient(EthClientInterface):
     # NOTE(krishan711): find docs at https://eth.wiki/json-rpc/API
-    def __init__(self, url: str, requester: Requester, chainId: int, isTestnet: bool = False, shouldBackoffRetryOnRateLimit: bool = True, retryLimit: int = 10) -> None:
+    def __init__(
+        self,
+        url: str,
+        requester: Requester,
+        chainId: int,
+        isTestnet: bool = False,
+        shouldBackoffRetryOnRateLimit: bool = True,
+        retryLimit: int = 10,
+        maxConcurrentRequestCount: int | None = None,
+        semaphore: asyncio.Semaphore | None = None,
+    ) -> None:
         super().__init__(web3Connection=Web3(), chainId=chainId, isTestnet=isTestnet)
         self.url = url
         self.requester = requester
         self.shouldBackoffRetryOnRateLimit = shouldBackoffRetryOnRateLimit
         self.retryLimit = retryLimit
+        # NOTE(krishan711): pass the same semaphore to several clients to cap their combined concurrent requests, or set maxConcurrentRequestCount to cap just this client
+        if semaphore is None and maxConcurrentRequestCount is not None:
+            semaphore = asyncio.Semaphore(maxConcurrentRequestCount)
+        self.semaphore = semaphore
         self.w3 = Web3()
 
     @staticmethod
@@ -310,39 +333,45 @@ class RestEthClient(EthClientInterface):
         return int(value, 16)
 
     async def _make_request(self, method: str, params: ListAny | None = None) -> DictStrAny:
-        retryCount = 0
-        initialBackoffSeconds = 1.0
-        responseDict: DictStrAny = {}
-        while True:
-            try:
-                response = await self.requester.post_json(
-                    url=self.url,
-                    dataDict={'jsonrpc': '2.0', 'method': method, 'params': params or [], 'id': None},
-                    timeout=10,
-                )
-                responseDict = response.json()
-                if responseDict.get('error'):
-                    errorMessage = responseDict['error'].get('message') or responseDict['error'].get('details') or json_util.dumps(responseDict['error'])
-                    raise BadRequestException(message=errorMessage)
-            except ClientException as exception:
-                # NOTE(krishan711): this is just here to debug 429s from coinbase, remove when done
-                logging.info(f'caught exception on _make_request: {exception!s}')
-                exceptionMessage = exception.message or ''
-                if (
-                    isinstance(exception, TooManyRequestsException)
-                    # NOTE(krishan711): sometimes coinbase returns an error message with 200 status
-                    or 'over rate limit' in exceptionMessage
-                    or '429 Too Many Requests' in exceptionMessage
-                ):
-                    if not self.shouldBackoffRetryOnRateLimit or retryCount >= self.retryLimit:
+        async with self.semaphore or contextlib.nullcontext():
+            retryCount = 0
+            initialBackoffSeconds = 1.0
+            responseDict: DictStrAny = {}
+            while True:
+                try:
+                    response = await self.requester.post_json(
+                        url=self.url,
+                        dataDict={'jsonrpc': '2.0', 'method': method, 'params': params or [], 'id': None},
+                        timeout=10,
+                    )
+                    responseDict = response.json()
+                    if responseDict.get('error'):
+                        errorMessage = responseDict['error'].get('message') or responseDict['error'].get('details') or json_util.dumps(responseDict['error'])
+                        raise BadRequestException(message=errorMessage)
+                except ClientException as exception:
+                    # NOTE(krishan711): this is just here to debug 429s from coinbase, remove when done
+                    logging.info(f'caught exception on _make_request: {exception!s}')
+                    exceptionMessage = exception.message or ''
+                    if (
+                        isinstance(exception, TooManyRequestsException)
+                        # NOTE(krishan711): sometimes coinbase returns an error message with 200 status
+                        or 'over rate limit' in exceptionMessage
+                        or '429 Too Many Requests' in exceptionMessage
+                    ):
+                        if not self.shouldBackoffRetryOnRateLimit or retryCount >= self.retryLimit:
+                            raise
+                        retryCount += 1
+                        exponentialBackoffSeconds = initialBackoffSeconds * (2 ** (retryCount - 1))
+                        logging.info(f'Retrying {method} after {exponentialBackoffSeconds} seconds due to rate limit exceeded: {exception!s}')
+                        await asyncio.sleep(exponentialBackoffSeconds)
+                        continue
+                    raise
+                except (ServerException, ResponseException) as exception:
+                    # NOTE(krishan711): timeouts are raised from the requester rather than the node so they keep their own type
+                    if isinstance(exception, RequesterTimeoutException) or exception.statusCode < 500:  # noqa: PLR2004
                         raise
-                    retryCount += 1
-                    exponentialBackoffSeconds = initialBackoffSeconds * (2 ** (retryCount - 1))
-                    logging.info(f'Retrying {method} after {exponentialBackoffSeconds} seconds due to rate limit exceeded: {exception!s}')
-                    await asyncio.sleep(exponentialBackoffSeconds)
-                    continue
-                raise
-            return responseDict
+                    raise RpcServerException(message=exception.message, statusCode=exception.statusCode) from exception
+                return responseDict
 
     async def get_latest_block_number(self) -> int:
         response = await self._make_request(method='eth_blockNumber')
@@ -394,6 +423,10 @@ class RestEthClient(EthClientInterface):
             raise NotFoundException
         return typing.cast(TxReceipt, method_formatters.PYTHONIC_RESULT_FORMATTERS[RPC.eth_getTransactionReceipt](response['result']))
 
+    async def get_code(self, address: str, blockNumber: int | None = None) -> str:
+        response = await self._make_request(method='eth_getCode', params=[address, hex(blockNumber) if blockNumber is not None else 'latest'])
+        return str(response.get('result', '0x'))
+
     async def get_log_entries(
         self,
         topics: list[str] | None = None,
@@ -481,3 +514,4 @@ class RestEthClient(EthClientInterface):
             transactionData = '0x' + transactionData
         response = await self._make_request(method='eth_sendRawTransaction', params=[transactionData])
         return typing.cast(str, response['result'])
+

kiba_core-0.5.3.dev72/core/web3/eth_client_registry.py

@@ -0,0 +1,46 @@
+import datetime
+
+from core.exceptions import InternalServerErrorException
+from core.util import date_util
+from core.web3.eth_client import RestEthClient
+
+
+class EthClientRegistry:
+    def __init__(self, archiveThresholdDays: int = 15) -> None:
+        self.archiveThresholdDays = archiveThresholdDays
+        self.ethClientsByChainId: dict[int, RestEthClient] = {}
+        self.archiveEthClientsByChainId: dict[int, RestEthClient] = {}
+        self.paymasterEthClientsByChainId: dict[int, RestEthClient] = {}
+
+    def register_client(self, client: RestEthClient) -> None:
+        self.ethClientsByChainId[client.chainId] = client
+
+    def register_archive_client(self, client: RestEthClient) -> None:
+        self.archiveEthClientsByChainId[client.chainId] = client
+
+    def register_paymaster_client(self, client: RestEthClient) -> None:
+        self.paymasterEthClientsByChainId[client.chainId] = client
+
+    def get_client(self, chainId: int, date: datetime.date | None = None) -> RestEthClient:
+        # NOTE(krishan711): regular nodes may have pruned state older than the threshold so those reads go to the archive node
+        dateDiff = date_util.calculate_diff_days(startDate=date_util.datetime_from_date(date=date), endDate=date_util.datetime_from_now()) if date is not None else 0
+        if dateDiff > self.archiveThresholdDays:
+            return self.get_archive_client(chainId=chainId)
+        return self.get_regular_client(chainId=chainId)
+
+    def get_paymaster_client(self, chainId: int) -> RestEthClient:
+        if chainId not in self.paymasterEthClientsByChainId:
+            raise InternalServerErrorException(f'Chain {chainId} does not have a paymaster client')
+        return self.paymasterEthClientsByChainId[chainId]
+
+    def get_archive_client(self, chainId: int) -> RestEthClient:
+        if chainId not in self.archiveEthClientsByChainId:
+            raise InternalServerErrorException(f'Chain {chainId} does not have an archive client')
+        return self.archiveEthClientsByChainId[chainId]
+
+    def get_regular_client(self, chainId: int) -> RestEthClient:
+        if chainId in self.ethClientsByChainId:
+            return self.ethClientsByChainId[chainId]
+        if chainId in self.archiveEthClientsByChainId:
+            return self.archiveEthClientsByChainId[chainId]
+        raise InternalServerErrorException(f'Chain {chainId} does not have a regular client or an archive client')

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/kiba_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev71
+Version: 0.5.3.dev72
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/kiba_core.egg-info/SOURCES.txt

@@ -88,6 +88,7 @@ core/util/url_util.py
 core/util/value_holder.py
 core/web3/__init__.py
 core/web3/eth_client.py
+core/web3/eth_client_registry.py
 core/web3/multicall3.py
 kiba_core.egg-info/PKG-INFO
 kiba_core.egg-info/SOURCES.txt
@@ -132,4 +133,5 @@ tests/util/test_process_util.py
 tests/util/test_string_util.py
 tests/util/test_url_util.py
 tests/web3/__init__.py
+tests/web3/test_eth_client_registry.py
 tests/web3/test_rest_eth_client.py

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiba-core"
-version = "0.5.3.dev71"
+version = "0.5.3.dev72"
 description = "Kiba Labs' python utilities"
 readme = "README.md"
 requires-python = ">=3.12, <4"

kiba_core-0.5.3.dev72/tests/web3/test_eth_client_registry.py

@@ -0,0 +1,63 @@
+import datetime
+
+import pytest
+
+from core.exceptions import InternalServerErrorException
+from core.requester import Requester
+from core.util import date_util
+from core.web3.eth_client import RestEthClient
+from core.web3.eth_client_registry import EthClientRegistry
+
+
+def _client(chainId: int) -> RestEthClient:
+    return RestEthClient(url=f'https://rpc-{chainId}.test', requester=Requester(), chainId=chainId)
+
+
+def _days_ago(days: int) -> datetime.date:
+    return date_util.datetime_from_now(days=-days).date()
+
+
+def test_get_client_uses_regular_client_for_recent_dates():
+    registry = EthClientRegistry()
+    regularClient = _client(chainId=8453)
+    archiveClient = _client(chainId=8453)
+    registry.register_client(client=regularClient)
+    registry.register_archive_client(client=archiveClient)
+    assert registry.get_client(chainId=8453) is regularClient
+    assert registry.get_client(chainId=8453, date=_days_ago(days=15)) is regularClient
+    assert registry.get_client(chainId=8453, date=_days_ago(days=16)) is archiveClient
+
+
+def test_get_client_respects_archive_threshold():
+    registry = EthClientRegistry(archiveThresholdDays=2)
+    regularClient = _client(chainId=8453)
+    archiveClient = _client(chainId=8453)
+    registry.register_client(client=regularClient)
+    registry.register_archive_client(client=archiveClient)
+    assert registry.get_client(chainId=8453, date=_days_ago(days=2)) is regularClient
+    assert registry.get_client(chainId=8453, date=_days_ago(days=3)) is archiveClient
+
+
+def test_get_regular_client_falls_back_to_archive_client():
+    registry = EthClientRegistry()
+    archiveClient = _client(chainId=1)
+    registry.register_archive_client(client=archiveClient)
+    assert registry.get_regular_client(chainId=1) is archiveClient
+
+
+def test_missing_clients_raise():
+    registry = EthClientRegistry()
+    registry.register_client(client=_client(chainId=1))
+    with pytest.raises(InternalServerErrorException):
+        registry.get_regular_client(chainId=8453)
+    with pytest.raises(InternalServerErrorException):
+        registry.get_archive_client(chainId=1)
+    with pytest.raises(InternalServerErrorException):
+        registry.get_paymaster_client(chainId=1)
+
+
+def test_get_paymaster_client():
+    registry = EthClientRegistry()
+    paymasterClient = _client(chainId=8453)
+    registry.register_paymaster_client(client=paymasterClient)
+    assert registry.get_paymaster_client(chainId=8453) is paymasterClient

{kiba_core-0.5.3.dev71 → kiba_core-0.5.3.dev72}/tests/web3/test_rest_eth_client.py

@@ -3,9 +3,10 @@ import pytest
 from typing import Any
 from collections.abc import MutableMapping
 
-from core.exceptions import BadRequestException, NotFoundException, TooManyRequestsException
+from core.exceptions import BadRequestException, InternalServerErrorException, NotFoundException, ServerException, ServiceUnavailableException, TooManyRequestsException
 from core.requester import Requester, KibaResponse
-from core.web3.eth_client import RestEthClient
+from core.requester.requester import RequesterTimeoutException, ResponseException
+from core.web3.eth_client import RestEthClient, RpcServerException
 from core.util.typing_util import Json
 
 
@@ -493,6 +494,83 @@ class TestRestEthClient:
         with pytest.raises(TooManyRequestsException):
             await client.get_latest_block_number()
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize('exception', [
+        InternalServerErrorException(message='{"jsonrpc":"2.0","error":{"code":-32000,"message":"internal error"}}'),
+        ServiceUnavailableException(message='upstream connect error or disconnect/reset before headers'),
+        ResponseException(message='unknown', statusCode=599),
+    ])
+    async def test_server_error_raises_rpc_server_exception(self, client, mock_requester, exception):
+        call_count = 0
+        async def mock_post_json_server_error(*args, **kwargs):
+            nonlocal call_count
+            call_count += 1
+            raise exception
+        mock_requester.post_json = mock_post_json_server_error
+        with pytest.raises(RpcServerException) as exceptionInfo:
+            await client.get_latest_block_number()
+        assert exceptionInfo.value.statusCode == exception.statusCode
+        assert exceptionInfo.value.message == exception.message
+        assert exceptionInfo.value.__cause__ is exception
+        assert isinstance(exceptionInfo.value, ServerException)
+        assert call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_timeout_keeps_requester_timeout_exception(self, client, mock_requester):
+        async def mock_post_json_timeout(*args, **kwargs):
+            raise RequesterTimeoutException(method='POST', url='https://test-rpc-url.com', timeoutSeconds=10, durationSeconds=10, timeoutType='ReadTimeout')
+        mock_requester.post_json = mock_post_json_timeout
+        with pytest.raises(RequesterTimeoutException):
+            await client.get_latest_block_number()
+
+    @pytest.mark.asyncio
+    async def test_get_code_success(self, client, mock_requester):
+        mock_requester.responses['eth_getCode'] = {'jsonrpc': '2.0', 'result': '0x6080', 'id': None}
+        result = await client.get_code(address='0x1234567890123456789012345678901234567890', blockNumber=436)
+        assert result == '0x6080'
+        assert mock_requester.requests_made[0]['dataDict']['params'] == ['0x1234567890123456789012345678901234567890', hex(436)]
+
+    @pytest.mark.asyncio
+    async def test_get_code_defaults_to_latest(self, client, mock_requester):
+        mock_requester.responses['eth_getCode'] = {'jsonrpc': '2.0', 'result': '0x', 'id': None}
+        result = await client.get_code(address='0x1234567890123456789012345678901234567890')
+        assert result == '0x'
+        assert mock_requester.requests_made[0]['dataDict']['params'] == ['0x1234567890123456789012345678901234567890', 'latest']
+
+    @staticmethod
+    async def _max_concurrent_request_count(mock_requester, clients) -> int:
+        activeCount = 0
+        maxActiveCount = 0
+        async def mock_post_json_slow(*args, **kwargs):
+            nonlocal activeCount, maxActiveCount
+            activeCount += 1
+            maxActiveCount = max(maxActiveCount, activeCount)
+            await asyncio.sleep(0.01)
+            activeCount -= 1
+            return MockResponse({'jsonrpc': '2.0', 'result': hex(436), 'id': None})
+        mock_requester.post_json = mock_post_json_slow
+        results = await asyncio.gather(*[client.get_latest_block_number() for client in clients for _ in range(3)])
+        assert results == [436] * 3 * len(clients)
+        return maxActiveCount
+
+    @pytest.mark.asyncio
+    async def test_requests_are_not_limited_by_default(self, client, mock_requester):
+        assert client.semaphore is None
+        assert await self._max_concurrent_request_count(mock_requester=mock_requester, clients=[client]) == 3
+
+    @pytest.mark.asyncio
+    async def test_max_concurrent_request_count_limits_each_client(self, mock_requester):
+        clients = [RestEthClient(url='https://test-rpc-url.com', requester=mock_requester, chainId=chainId, maxConcurrentRequestCount=2) for chainId in (1, 8453)]
+        assert clients[0].semaphore is not clients[1].semaphore
+        assert await self._max_concurrent_request_count(mock_requester=mock_requester, clients=clients) == 4
+
+    @pytest.mark.asyncio
+    async def test_shared_semaphore_limits_clients_together(self, mock_requester):
+        semaphore = asyncio.Semaphore(2)
+        clients = [RestEthClient(url='https://test-rpc-url.com', requester=mock_requester, chainId=chainId, semaphore=semaphore, maxConcurrentRequestCount=5) for chainId in (1, 8453)]
+        assert all(client.semaphore is semaphore for client in clients)
+        assert await self._max_concurrent_request_count(mock_requester=mock_requester, clients=clients) == 2
+
     @pytest.mark.asyncio
     async def test_fill_transaction_params_all_provided(self, client, mock_requester):
         params = {