iwa 0.0.59__py3-none-any.whl → 0.0.61__py3-none-any.whl

tests/test_chainlist_enrichment.py

@@ -0,0 +1,354 @@
+"""Tests for ChainList RPC enrichment and quality probing."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+
+from iwa.core.chainlist import (
+    ChainlistRPC,
+    RPCNode,
+    _is_template_url,
+    _normalize_url,
+    probe_rpc,
+)
+
+
+@pytest.fixture(autouse=True)
+def mock_chainlist_enrichment():
+    """Override conftest — allow real enrichment calls in this test file."""
+    yield
+
+
+class TestNormalizeUrl:
+    """Test URL normalization for deduplication."""
+
+    def test_strips_trailing_slash(self):
+        assert _normalize_url("https://rpc.example.com/") == "https://rpc.example.com"
+
+    def test_lowercases(self):
+        assert _normalize_url("https://RPC.Example.COM") == "https://rpc.example.com"
+
+    def test_no_change_needed(self):
+        assert _normalize_url("https://rpc.example.com") == "https://rpc.example.com"
+
+
+class TestIsTemplateUrl:
+    """Test template URL detection."""
+
+    def test_dollar_brace(self):
+        assert _is_template_url("https://rpc.example.com/${API_KEY}") is True
+
+    def test_plain_brace(self):
+        assert _is_template_url("https://rpc.example.com/{api_key}") is True
+
+    def test_no_template(self):
+        assert _is_template_url("https://rpc.example.com") is False
+
+
+class TestProbeRpc:
+    """Test single RPC probing."""
+
+    @pytest.fixture
+    def mock_session(self):
+        """Create a mock session for probe_rpc tests."""
+        with patch("iwa.core.chainlist.requests.Session") as mock_session_cls:
+            mock_session = MagicMock()
+            mock_session_cls.return_value = mock_session
+            # Make it work as context manager too
+            mock_session.__enter__ = MagicMock(return_value=mock_session)
+            mock_session.__exit__ = MagicMock(return_value=False)
+            yield mock_session
+
+    def test_success(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x1A4B5C", "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+
+        assert result is not None
+        url, latency, block = result
+        assert url == "https://rpc.example.com"
+        assert latency > 0
+        assert block == 0x1A4B5C
+        # Verify session was closed
+        mock_session.close.assert_called_once()
+
+    def test_timeout_returns_none(self, mock_session):
+        mock_session.post.side_effect = requests.exceptions.Timeout("timed out")
+
+        result = probe_rpc("https://slow.example.com")
+        assert result is None
+        # Session still closed on error
+        mock_session.close.assert_called_once()
+
+    def test_connection_error_returns_none(self, mock_session):
+        mock_session.post.side_effect = requests.exceptions.ConnectionError("refused")
+
+        result = probe_rpc("https://dead.example.com")
+        assert result is None
+        mock_session.close.assert_called_once()
+
+    def test_zero_block_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x0", "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_null_result_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": None, "id": 1}
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_error_response_returns_none(self, mock_session):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {
+            "jsonrpc": "2.0",
+            "error": {"code": -32600, "message": "Invalid Request"},
+            "id": 1,
+        }
+        mock_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com")
+        assert result is None
+
+    def test_uses_provided_session(self):
+        """When a session is provided, use it instead of creating one."""
+        provided_session = MagicMock()
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"jsonrpc": "2.0", "result": "0x100", "id": 1}
+        provided_session.post.return_value = mock_resp
+
+        result = probe_rpc("https://rpc.example.com", session=provided_session)
+
+        assert result is not None
+        provided_session.post.assert_called_once()
+        # Should NOT close provided session (caller's responsibility)
+        provided_session.close.assert_not_called()
+
+
+class TestGetValidatedRpcs:
+    """Test ChainlistRPC.get_validated_rpcs()."""
+
+    def _make_node(self, url, tracking="none"):
+        return RPCNode(url=url, is_working=True, tracking=tracking)
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_template_urls(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://rpc.example.com/${API_KEY}"),
+            self._make_node("https://good.example.com"),
+        ]
+        mock_probe.return_value = ("https://good.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == ["https://good.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_non_https(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("http://insecure.example.com"),
+            self._make_node("wss://ws.example.com"),
+            self._make_node("https://good.example.com"),
+        ]
+        mock_probe.return_value = ("https://good.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == ["https://good.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_deduplicates_existing(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://already.configured.com"),
+            self._make_node("https://new.example.com"),
+        ]
+        mock_probe.return_value = ("https://new.example.com", 50.0, 1000)
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(
+            100, existing_rpcs=["https://already.configured.com/"]
+        )
+
+        assert result == ["https://new.example.com"]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_filters_stale_rpcs(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://fresh.example.com"),
+            self._make_node("https://stale.example.com"),
+            self._make_node("https://also-fresh.example.com"),
+        ]
+        # fresh=1000, stale=900 (100 blocks behind), also-fresh=999
+        mock_probe.side_effect = [
+            ("https://fresh.example.com", 50.0, 1000),
+            ("https://stale.example.com", 30.0, 900),
+            ("https://also-fresh.example.com", 60.0, 999),
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        # Stale RPC (900) is 100 blocks behind median (999) > MAX_BLOCK_LAG
+        assert "https://stale.example.com" not in result
+        assert "https://fresh.example.com" in result
+        assert "https://also-fresh.example.com" in result
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_sorts_by_latency(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://slow.example.com"),
+            self._make_node("https://fast.example.com"),
+            self._make_node("https://medium.example.com"),
+        ]
+        mock_probe.side_effect = [
+            ("https://slow.example.com", 200.0, 1000),
+            ("https://fast.example.com", 10.0, 1000),
+            ("https://medium.example.com", 80.0, 1000),
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == [
+            "https://fast.example.com",
+            "https://medium.example.com",
+            "https://slow.example.com",
+        ]
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_respects_max_results(self, mock_probe, mock_get_rpcs):
+        nodes = [self._make_node(f"https://rpc{i}.example.com") for i in range(10)]
+        mock_get_rpcs.return_value = nodes
+        mock_probe.side_effect = [
+            (f"https://rpc{i}.example.com", float(i * 10), 1000) for i in range(10)
+        ]
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[], max_results=3)
+
+        assert len(result) == 3
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    def test_returns_empty_on_no_rpcs(self, mock_get_rpcs):
+        mock_get_rpcs.return_value = []
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == []
+
+    @patch.object(ChainlistRPC, "get_rpcs")
+    @patch("iwa.core.chainlist.probe_rpc")
+    def test_returns_empty_when_all_probes_fail(self, mock_probe, mock_get_rpcs):
+        mock_get_rpcs.return_value = [
+            self._make_node("https://dead1.example.com"),
+            self._make_node("https://dead2.example.com"),
+        ]
+        mock_probe.return_value = None
+
+        cl = ChainlistRPC()
+        result = cl.get_validated_rpcs(100, existing_rpcs=[])
+
+        assert result == []
+
+
+class TestEnrichFromChainlist:
+    """Test ChainInterface._enrich_rpcs_from_chainlist().
+
+    The conftest fixture is overridden in this file so the real
+    enrichment method runs during __init__.
+    """
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_skipped_for_tenderly(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://virtual.tenderly.co/test"]
+        chain.rpc = "https://virtual.tenderly.co/test"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            ci = ChainInterface(chain)
+
+        # is_tenderly=True → enrichment skipped → ChainlistRPC never called
+        assert "tenderly" in ci.current_rpc.lower()
+        mock_cl_cls.assert_not_called()
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_enriches_non_tenderly(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://rpc1.example.com"]
+        chain.rpc = "https://rpc1.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            mock_cl = mock_cl_cls.return_value
+            mock_cl.get_validated_rpcs.return_value = [
+                "https://extra1.example.com",
+                "https://extra2.example.com",
+            ]
+            ChainInterface(chain)
+
+        assert len(chain.rpcs) == 3
+        assert "https://extra1.example.com" in chain.rpcs
+        assert "https://extra2.example.com" in chain.rpcs
+        # Original RPC stays first
+        assert chain.rpcs[0] == "https://rpc1.example.com"
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_survives_fetch_failure(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = ["https://rpc1.example.com"]
+        chain.rpc = "https://rpc1.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            mock_cl_cls.side_effect = Exception("network error")
+            ChainInterface(chain)
+
+        # Should still work with original RPCs
+        assert chain.rpcs == ["https://rpc1.example.com"]
+
+    @patch("iwa.core.chain.interface.Web3")
+    def test_respects_max_rpcs(self, mock_web3):
+        from iwa.core.chain.interface import ChainInterface
+        from iwa.core.chain.models import SupportedChain
+
+        chain = MagicMock(spec=SupportedChain)
+        chain.name = "TestChain"
+        chain.rpcs = [f"https://rpc{i}.example.com" for i in range(10)]
+        chain.rpc = "https://rpc0.example.com"
+        chain.chain_id = 100
+
+        with patch("iwa.core.chainlist.ChainlistRPC") as mock_cl_cls:
+            ChainInterface(chain)
+
+        # Already at MAX_RPCS=10, ChainlistRPC should not be called
+        mock_cl_cls.assert_not_called()

tests/test_rate_limiter.py

@@ -146,7 +146,7 @@ class TestRateLimitRotationInterplay:
     """Test interaction between rate limiting and RPC rotation."""
 
     def test_rate_limit_triggers_rotation_first(self):
-        """Test that rate limit error triggers RPC rotation before backoff."""
+        """Test that rate limit error triggers RPC rotation and global backoff."""
         from unittest.mock import MagicMock, PropertyMock
 
         from iwa.core.chain import ChainInterface, SupportedChain
@@ -171,8 +171,10 @@ class TestRateLimitRotationInterplay:
                 assert result["rotated"] is True
                 assert result["should_retry"] is True
                 assert ci._current_rpc_index != original_index
-                # Backoff should NOT be triggered since rotation succeeded
-                assert ci._rate_limiter.get_status()["in_backoff"] is False
+                # Global backoff IS triggered to slow other threads briefly
+                assert ci._rate_limiter.get_status()["in_backoff"] is True
+                # The old RPC should be marked in per-RPC backoff
+                assert not ci._is_rpc_healthy(original_index)
 
     def test_rate_limit_triggers_backoff_when_no_rotation(self):
         """Test that rate limit triggers backoff when no other RPCs available."""
@@ -193,7 +195,7 @@ class TestRateLimitRotationInterplay:
             rate_limit_error = Exception("Error 429: Too Many Requests")
             result = ci._handle_rpc_error(rate_limit_error)
 
-            # Should have triggered retry but NO backoff (skipped for single RPC)
+            # Should have triggered retry and global backoff
             assert result["should_retry"] is True
             assert result["rotated"] is False
-            assert ci._rate_limiter.get_status()["in_backoff"] is False
+            assert ci._rate_limiter.get_status()["in_backoff"] is True

tests/test_rate_limiter_retry.py

@@ -19,28 +19,39 @@ class TestRateLimitedEthRetry:
         chain_interface = MockChainInterface()
         return web3_eth, rate_limiter, chain_interface
 
-    def test_read_method_retries_on_failure(self, mock_deps):
-        """Verify that read methods automatically retry on failure."""
+    def test_read_method_retries_on_transient_failure(self, mock_deps):
+        """Verify that read methods retry on transient (connection) errors."""
         web3_eth, rate_limiter, chain_interface = mock_deps
         eth_wrapper = RateLimitedEth(web3_eth, rate_limiter, chain_interface)
 
-        # Mock get_balance to fail twice then succeed
+        # Mock get_balance to fail once with transient error then succeed
         web3_eth.get_balance.side_effect = [
-            ValueError("RPC error 1"),
-            ValueError("RPC error 2"),
+            ValueError("connection timeout"),
             100,  # Success
         ]
 
-        # Use patch to speed up sleep
         with patch("time.sleep") as mock_sleep:
             result = eth_wrapper.get_balance("0x123")
 
         assert result == 100
-        assert web3_eth.get_balance.call_count == 3
-        # Should have slept twice
-        assert mock_sleep.call_count == 2
-        # Verify handle_error was called
-        assert chain_interface._handle_rpc_error.call_count == 2
+        # 1 initial + 1 retry = 2 calls (DEFAULT_READ_RETRIES=1)
+        assert web3_eth.get_balance.call_count == 2
+        assert mock_sleep.call_count == 1
+        # RateLimitedEth no longer calls _handle_rpc_error (that's for with_retry)
+        assert chain_interface._handle_rpc_error.call_count == 0
+
+    def test_read_method_raises_non_transient_immediately(self, mock_deps):
+        """Verify non-transient errors (rate limit, quota) propagate immediately."""
+        web3_eth, rate_limiter, chain_interface = mock_deps
+        eth_wrapper = RateLimitedEth(web3_eth, rate_limiter, chain_interface)
+
+        web3_eth.get_balance.side_effect = ValueError("429 Too Many Requests")
+
+        with pytest.raises(ValueError, match="429"):
+            eth_wrapper.get_balance("0x123")
+
+        # Only 1 attempt, no retry for non-transient errors
+        assert web3_eth.get_balance.call_count == 1
 
     def test_write_method_no_auto_retry(self, mock_deps):
         """Verify that write methods (send_raw_transaction) DO NOT auto-retry."""
@@ -60,23 +71,21 @@ class TestRateLimitedEthRetry:
         # Should verify it was called only once
         assert web3_eth.send_raw_transaction.call_count == 1
         # Chain interface error handler should NOT be called by the wrapper itself
-        # (It might typically be called by the caller)
         assert chain_interface._handle_rpc_error.call_count == 0
 
     def test_retry_respects_max_attempts(self, mock_deps):
-        """Verify that retry logic respects maximum attempts."""
+        """Verify that retry logic respects maximum attempts for transient errors."""
         web3_eth, rate_limiter, chain_interface = mock_deps
         eth_wrapper = RateLimitedEth(web3_eth, rate_limiter, chain_interface)
 
-        # Override default retries for quicker test
-        # Use object.__setattr__ because RateLimitedEth overrides __setattr__
+        # Override default retries
         object.__setattr__(eth_wrapper, "DEFAULT_READ_RETRIES", 2)
 
-        # Mock always failing
-        web3_eth.get_code.side_effect = ValueError("Persistently failing")
+        # Mock always failing with transient error
+        web3_eth.get_code.side_effect = ValueError("connection reset by peer")
 
         with patch("time.sleep"):
-            with pytest.raises(ValueError, match="Persistently failing"):
+            with pytest.raises(ValueError, match="connection reset"):
                 eth_wrapper.get_code("0x123")
 
         # Attempts: initial + 2 retries = 3 total calls
@@ -87,17 +96,14 @@ class TestRateLimitedEthRetry:
         web3_eth, rate_limiter, chain_interface = mock_deps
         eth_wrapper = RateLimitedEth(web3_eth, rate_limiter, chain_interface)
 
-        # Mock property access: fail then succeed
-        # Note: PropertyMock is needed if we were mocking a property on the CLASS,
-        # but here we are mocking the instance attribute access which might be a method call or property.
-        # web3.eth.block_number is a property.
-
-        # We need to set side_effect on the PROPERTY of the mock
-        type(web3_eth).block_number = PropertyMock(side_effect=[ValueError("Fail 1"), 12345])
+        # block_number fails once with transient error then succeeds
+        type(web3_eth).block_number = PropertyMock(
+            side_effect=[ValueError("connection timeout"), 12345]
+        )
 
         with patch("time.sleep"):
             val = eth_wrapper.block_number
 
         assert val == 12345
-        # Verify handle_error called
-        assert chain_interface._handle_rpc_error.call_count == 1
+        # _handle_rpc_error is NOT called by RateLimitedEth anymore
+        assert chain_interface._handle_rpc_error.call_count == 0

tests/test_rpc_rate_limit.py

@@ -16,7 +16,7 @@ def clean_rate_limiters():
 
 
 def test_chain_interface_initializes_strict_limiter(clean_rate_limiters):
-    """Verify ChainInterface initializes with rate=1.0 and burst=1."""
+    """Verify ChainInterface initializes with rate=5.0 and burst=10."""
     # Create a dummy chain
     chain = MagicMock(spec=SupportedChain)
     chain.name = "TestSlowChain"
@@ -30,5 +30,5 @@ def test_chain_interface_initializes_strict_limiter(clean_rate_limiters):
     limiter = ci._rate_limiter
 
     # Assert correct configuration
-    assert limiter.rate == 1.0, f"Expected rate 1.0, got {limiter.rate}"
-    assert limiter.burst == 1, f"Expected burst 1, got {limiter.burst}"
+    assert limiter.rate == 5.0, f"Expected rate 5.0, got {limiter.rate}"
+    assert limiter.burst == 10, f"Expected burst 10, got {limiter.burst}"