Unify the PRO API request path for the metadata and data helpers (#397)

Author: akolotov

SPEC.md

@@ -567,18 +567,22 @@ Credit-exhaustion and rate-limit responses from the PRO API are currently not sp
 
 7. **HTTP Request Robustness**
 
-   Blockscout HTTP requests are centralized via the helper `make_blockscout_request`. To improve resilience against transient, transport-level issues observed in real-world usage (for example, incomplete chunked reads), the helper employs a small and conservative retry policy:
+   Blockscout PRO API requests are centralized through a single shared low-level core, `_make_blockscout_http_request`, which backs every PRO API request helper: `make_blockscout_request` (GET), `make_blockscout_post_request` (POST), and `make_metadata_request` (the non-chain-scoped address-metadata GET). To improve resilience against transient, transport-level issues observed in real-world usage (for example, incomplete chunked reads), this core employs a small and conservative retry policy:
 
-   - Applies only to idempotent GETs (this function is GET-only)
-   - Retries up to 3 attempts on `httpx.RequestError` (transport errors)
-   - Does not retry on `httpx.HTTPStatusError` (4xx/5xx responses)
+   - The retry **exception set is selected by each helper**, because idempotency differs by HTTP method:
+     - The idempotent GET helpers `make_blockscout_request` and `make_metadata_request` retry on `httpx.RequestError` (transport errors, which include `httpx.TimeoutException`).
+     - The non-idempotent `make_blockscout_post_request` deliberately narrows its retry set to connection-establishment failures only (`httpx.ConnectError`, `httpx.ConnectTimeout`), so a POST that may already have reached the server is never silently re-sent.
+   - Retries up to 3 attempts (configurable; see below)
+   - Never retries on `httpx.HTTPStatusError` (4xx/5xx responses), for any helper
    - Uses short exponential backoff between attempts (0.5s, then 1.0s)
 
    Configuration:
    - The maximum number of retry attempts is configurable via the environment variable `BLOCKSCOUT_BS_REQUEST_MAX_RETRIES` (default: `3`).
 
    This keeps API semantics intact, avoids masking persistent upstream problems, and improves reliability for both MCP tools and the REST API endpoints that proxy through the same business logic.
 
+   Because all PRO API helpers share this core, their HTTP-status-error enrichment and JSON-`null`-body normalization are identical, and they share the same retry orchestration (attempt count and backoff schedule); only the set of exceptions treated as retryable differs by helper, as detailed in the bullets above. In particular, `make_metadata_request` — used by `get_address_info` — now inherits the shared GET retry policy (retrying `httpx.RequestError`, which includes `httpx.TimeoutException`), the same `"<code> <reason> - Details: …"` error enrichment, and the same normalization of a JSON `null` body to an empty object that the primary data path already provides.
+
    Exhausted internal retries surface differently per access mode:
    - **REST clients** see `500 Internal Server Error` for generic transport failures, or `504 Gateway Timeout` for `httpx.TimeoutException`. Because the server has already retried internally, downstream retry policies that also retry on `5xx` should stay conservative on `500`/`504` from this server to avoid multiplicative attempt cascades.
    - **Native MCP clients** see a `tools/call` result with `isError: true` and a text content of the form `"Error executing tool <name>: <exception message>"`. There is no HTTP-status indicator in MCP mode — an exhausted-retry transport failure is structurally indistinguishable from an honest upstream `5xx` (the latter carries a `"<code> <reason> - Details: …"` prefix in the text; the former carries the bare `httpx` exception message).

blockscout_mcp_server/__init__.py

@@ -1,4 +1,4 @@
 # SPDX-License-Identifier: LicenseRef-Blockscout
 """Blockscout MCP Server package."""
 
-__version__ = "0.16.0.dev13"
+__version__ = "0.16.0.dev14"

blockscout_mcp_server/tools/common.py

@@ -378,27 +378,43 @@ async def make_metadata_request(api_path: str, params: dict | None = None) -> di
     PRO API is guaranteed to reject. Callers treat this like any other
     metadata failure (the ``metadata`` field is null with an explanatory note).
 
+    This helper routes through the shared ``_make_blockscout_http_request`` core
+    and therefore inherits the same conservative GET retry policy
+    (``httpx.RequestError`` retries) and ``"<code> <reason> - Details: …"``
+    error enrichment as ``make_blockscout_request``.  The metadata endpoint is
+    not chain-scoped, so this helper calls the low-level core directly with
+    ``base_url=config.pro_api_base_url`` — bypassing ``ensure_chain_supported``
+    and the ``/{chain_id}`` segment that ``make_blockscout_request`` would add.
+
     Args:
         api_path: The API path to request
         params: Optional query parameters
 
     Returns:
-        The JSON response as a dictionary
+        The JSON response as a dictionary.  A JSON ``null`` response body is
+        normalized to ``{}``.
 
     Raises:
         ValueError: If ``BLOCKSCOUT_PRO_API_KEY`` is not configured
         httpx.HTTPStatusError: If the HTTP request returns an error status code
-        httpx.TimeoutException: If the request times out
+        httpx.TimeoutException: If the request times out (retried as a subclass
+            of ``httpx.RequestError`` before being surfaced)
+        httpx.RequestError: For transport-level errors surfaced after the final
+            retry
     """
     if not config.pro_api_key:
         raise ValueError(
             "Blockscout PRO API key is not configured (set BLOCKSCOUT_PRO_API_KEY); address metadata is disabled."
         )
-    async with _create_httpx_client(timeout=config.metadata_timeout) as client:
-        url = f"{config.pro_api_base_url}{api_path}"
-        response = await client.get(url, params=params, headers=_pro_api_headers())
-        response.raise_for_status()
-        return response.json()
+    return await _make_blockscout_http_request(
+        method="GET",
+        base_url=config.pro_api_base_url,
+        api_path=api_path,
+        retry_exceptions=(httpx.RequestError,),
+        headers=_pro_api_headers(),
+        params=params,
+        timeout=config.metadata_timeout,
+    )
 
 
 async def make_request_with_periodic_progress(

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "blockscout-mcp-server"
-version = "0.16.0.dev13"
+version = "0.16.0.dev14"
 description = "MCP server for Blockscout"
 requires-python = ">=3.11"
 dependencies = [

server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.blockscout/mcp-server",
   "description": "MCP server for Blockscout",
-  "version": "0.16.0.dev13",
+  "version": "0.16.0.dev14",
   "websiteUrl": "https://blockscout.com",
   "repository": {
     "url": "https://github.com/blockscout/mcp-server",

tests/tools/test_common_metadata.py

@@ -140,6 +140,190 @@ def _fail_create_client(*args, **kwargs):
             await make_metadata_request("/services/metadata/api/v1/metadata", {"addresses": "0xabc"})
 
 
+# ---------------------------------------------------------------------------
+# New behaviors acquired by routing through _make_blockscout_http_request
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_make_metadata_request_uses_metadata_timeout(monkeypatch):
+    """make_metadata_request creates the HTTP client with config.metadata_timeout.
+
+    This guards the most likely silent regression: an implementation that forgets
+    the explicit timeout= argument and lets the core fall back to config.bs_timeout
+    (120s), silently widening the metadata budget from 30s to 120s.
+    """
+    monkeypatch.setattr(config, "pro_api_key", "api_key_12345")
+    api_path = "/api/v1/metadata/address"
+
+    request = httpx.Request("GET", f"{config.pro_api_base_url}{api_path}")
+    ok_resp = httpx.Response(200, json={"result": "ok"}, request=request)
+
+    class _MockClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def get(self, url, **kwargs):
+            return ok_resp
+
+    with patch(
+        "blockscout_mcp_server.tools.common._create_httpx_client",
+        return_value=_MockClient(),
+    ) as mock_create_client:
+        await make_metadata_request(api_path)
+
+    mock_create_client.assert_called_once_with(timeout=config.metadata_timeout)
+
+
+@pytest.mark.asyncio
+async def test_make_metadata_request_retries_then_succeeds(monkeypatch):
+    """make_metadata_request retries on httpx.RequestError and returns result on success.
+
+    Simulates two transient failures followed by a successful response.
+    Asserts that .get() is called exactly 3 times and anyio.sleep is awaited twice
+    (once per backoff between attempts).
+    The retry cap is pinned to 3 via monkeypatch so the assertion is deterministic.
+    """
+    monkeypatch.setattr(config, "pro_api_key", "api_key_12345")
+    monkeypatch.setattr(config, "bs_request_max_retries", 3)
+    api_path = "/api/v1/metadata/address"
+
+    attempt_count = {"n": 0}
+
+    request = httpx.Request("GET", f"{config.pro_api_base_url}{api_path}")
+    ok_resp = httpx.Response(200, json={"data": "value"}, request=request)
+
+    class _TransientClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def get(self, url, **kwargs):
+            attempt_count["n"] += 1
+            if attempt_count["n"] < 3:
+                raise httpx.RequestError("transient error")
+            return ok_resp
+
+    with (
+        patch("blockscout_mcp_server.tools.common._create_httpx_client", return_value=_TransientClient()),
+        patch("blockscout_mcp_server.tools.common.anyio.sleep") as mock_sleep,
+    ):
+        result = await make_metadata_request(api_path)
+
+    assert result == {"data": "value"}
+    assert attempt_count["n"] == 3
+    assert mock_sleep.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_make_metadata_request_retry_exhaustion_raises(monkeypatch):
+    """make_metadata_request re-raises httpx.RequestError after all retries are exhausted.
+
+    With the retry cap pinned to 3, the client's .get() should be called exactly 3
+    times before the error surfaces, and anyio.sleep should be awaited exactly twice.
+    """
+    monkeypatch.setattr(config, "pro_api_key", "api_key_12345")
+    monkeypatch.setattr(config, "bs_request_max_retries", 3)
+    api_path = "/api/v1/metadata/address"
+
+    attempt_count = {"n": 0}
+
+    class _AlwaysFailingClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def get(self, url, **kwargs):
+            attempt_count["n"] += 1
+            raise httpx.RequestError("persistent error")
+
+    with (
+        patch("blockscout_mcp_server.tools.common._create_httpx_client", return_value=_AlwaysFailingClient()),
+        patch("blockscout_mcp_server.tools.common.anyio.sleep") as mock_sleep,
+    ):
+        with pytest.raises(httpx.RequestError):
+            await make_metadata_request(api_path)
+
+    assert attempt_count["n"] == 3
+    assert mock_sleep.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_make_metadata_request_null_body_normalized_to_empty_dict(monkeypatch):
+    """A JSON null response body is normalized to {} instead of None.
+
+    This prevents a latent AttributeError in the caller (get_address_info calls
+    .get("addresses") on the result, which would fail on None).
+    """
+    monkeypatch.setattr(config, "pro_api_key", "api_key_12345")
+    api_path = "/api/v1/metadata/address"
+
+    request = httpx.Request("GET", f"{config.pro_api_base_url}{api_path}")
+    # Use content=b"null" so httpx.Response.json() returns Python None (not an empty body).
+    null_resp = httpx.Response(200, content=b"null", headers={"content-type": "application/json"}, request=request)
+
+    class _NullBodyClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def get(self, url, **kwargs):
+            return null_resp
+
+    with patch("blockscout_mcp_server.tools.common._create_httpx_client", return_value=_NullBodyClient()):
+        result = await make_metadata_request(api_path)
+
+    assert result == {}
+
+
+@pytest.mark.asyncio
+async def test_make_metadata_request_enriched_error_message_and_no_retry_on_http_error(monkeypatch):
+    """HTTP error status raises HTTPStatusError with enriched message and is not retried.
+
+    Asserts:
+    - The error message contains the status code and 'Details:' segment.
+    - The client's .get() is called exactly once (HTTP errors are not retried).
+    """
+    monkeypatch.setattr(config, "pro_api_key", "bad_key")
+    monkeypatch.setattr(config, "bs_request_max_retries", 3)
+    api_path = "/api/v1/metadata/address"
+
+    attempt_count = {"n": 0}
+
+    class _UnauthorizedClient:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return None
+
+        async def get(self, url, **kwargs):
+            attempt_count["n"] += 1
+            request = httpx.Request("GET", url)
+            return httpx.Response(401, content=b"Unauthorized", request=request)
+
+    with (
+        patch("blockscout_mcp_server.tools.common._create_httpx_client", return_value=_UnauthorizedClient()),
+        patch("blockscout_mcp_server.tools.common.anyio.sleep") as mock_sleep,
+    ):
+        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+            await make_metadata_request(api_path)
+
+    assert "401" in str(exc_info.value)
+    assert "Details:" in str(exc_info.value)
+    assert attempt_count["n"] == 1
+    mock_sleep.assert_not_called()
+
+
 # ---------------------------------------------------------------------------
 # Security: PRO API key MUST be sent to the PRO API host via make_blockscout_request
 # ---------------------------------------------------------------------------