[auth] Add custom header injection to JsonRpcBase (API key support)

.gitignore

@@ -135,3 +135,4 @@ dmypy.json
 
 # MacOS artifacts
 .DS_Store
+.jrb/ ..

tests/unit/asyn/clients/test_json_rpc_base.py

@@ -0,0 +1,77 @@
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from httpx import Response
+
+from xrpl.asyncio.clients.exceptions import XRPLAuthenticationException
+from xrpl.asyncio.clients.json_rpc_base import JsonRpcBase
+from xrpl.models.requests import ServerInfo
+
+
+@pytest.mark.asyncio
+async def test_global_headers_are_sent():
+    client = JsonRpcBase(
+        "https://xrpl.fake", headers={"Authorization": "Bearer testtoken"}
+    )
+
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+        mock_post.return_value = Response(
+            status_code=200,
+            json={"result": {"status": "success"}, "id": 1},
+        )
+
+        await client._request_impl(ServerInfo())
+
+        headers_sent = mock_post.call_args.kwargs["headers"]
+        assert headers_sent["Authorization"] == "Bearer testtoken"
+        assert headers_sent["Content-Type"] == "application/json"
+
+
+@pytest.mark.asyncio
+async def test_per_request_headers_override_global():
+    client = JsonRpcBase(
+        "https://xrpl.fake", headers={"Authorization": "Bearer default"}
+    )
+
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+        mock_post.return_value = Response(
+            status_code=200,
+            json={"result": {"status": "success"}, "id": 1},
+        )
+
+        await client._request_impl(
+            ServerInfo(), headers={"Authorization": "Bearer override"}
+        )
+
+        headers_sent = mock_post.call_args.kwargs["headers"]
+        assert headers_sent["Authorization"] == "Bearer override"
+
+
+@pytest.mark.asyncio
+async def test_no_headers_does_not_crash():
+    client = JsonRpcBase("https://xrpl.fake")
+
+    with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+        mock_post.return_value = Response(
+            status_code=200,
+            json={"result": {"status": "success"}, "id": 1},
+        )
+
+        await client._request_impl(ServerInfo())
+
+        headers_sent = mock_post.call_args.kwargs["headers"]
+        assert headers_sent["Content-Type"] == "application/json"
+
+
+@pytest.mark.asyncio
+async def test_raises_on_401_403():
+    client = JsonRpcBase("https://xrpl.fake")
+
+    for code in [401, 403]:
+        with patch("httpx.AsyncClient.post", new_callable=AsyncMock) as mock_post:
+            mock_post.return_value = Response(status_code=code, text="Unauthorized")
+
+            with pytest.raises(
+                XRPLAuthenticationException, match="Authentication failed"
+            ):
+                await client._request_impl(ServerInfo())

xrpl/asyncio/clients/client.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Optional
+from typing import Optional, Dict
 
 from typing_extensions import Final, Self
 
@@ -24,14 +24,24 @@ class Client(ABC):
     :meta private:
     """
 
-    def __init__(self: Self, url: str) -> None:
+    def __init__(
+        self: Self,
+        url: str,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
         """
         Initializes a client.
 
         Arguments:
-            url: The url to which this client will connect
+            url: The URL to which this client will connect.
+            headers: Optional dictionary of default headers to include with each request.
+                These can be used to authenticate with private XRPL nodes or pass
+                custom metadata, such as:
+                - {"Authorization": "Bearer <token>"}
         """
         self.url = url
+        self.headers = headers or {}
         self.network_id: Optional[int] = None
         self.build_version: Optional[str] = None
 
@@ -66,7 +76,6 @@ async def get_network_id_and_build_version(client: Client) -> None:
     Raises:
         XRPLRequestFailureException: if the rippled API call fails.
     """
-    # the required values are already present, no need for further processing
     if client.network_id and client.build_version:
         return
 

xrpl/asyncio/clients/exceptions.py

@@ -36,3 +36,9 @@ class XRPLWebsocketException(XRPLException):
     """
 
     pass
+
+
+class XRPLAuthenticationException(XRPLRequestFailureException):
+    """Raised when authentication with the XRPL node fails (401 or 403)."""
+
+    pass

xrpl/asyncio/clients/json_rpc_base.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from json import JSONDecodeError
+from typing import Optional, Dict
 
 from httpx import AsyncClient
 from typing_extensions import Self
@@ -21,16 +22,35 @@ class JsonRpcBase(Client):
     :meta private:
     """
 
+    def __init__(
+        self: Self,
+        url: str,
+        *,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        Initializes a new JsonRpcBase client.
+
+        Arguments:
+            url: The URL of the XRPL node to connect to.
+            headers: Optional default headers for all requests (e.g. API key or Dhali payment-claim).
+        """
+        super().__init__(url, headers=headers)
     async def _request_impl(
-        self: Self, request: Request, *, timeout: float = REQUEST_TIMEOUT
+        self: Self,
+        request: Request,
+        *,
+        timeout: float = REQUEST_TIMEOUT,
+        headers: Optional[Dict[str, str]] = None,
     ) -> Response:
         """
         Base ``_request_impl`` implementation for JSON RPC.
 
         Arguments:
             request: An object representing information about a rippled request.
             timeout: The duration within which we expect to hear a response from the
-            rippled validator.
+                rippled server.
+            headers: Optional additional headers to include for this request.
 
         Returns:
             The response from the server, as a Response object.
@@ -40,10 +60,18 @@ async def _request_impl(
 
         :meta private:
         """
+        # Merge global and per-request headers
+        merged_headers = {
+            "Content-Type": "application/json",
+            **self.headers,
+            **(headers or {}),
+        }
+
         async with AsyncClient(timeout=timeout) as http_client:
             response = await http_client.post(
                 self.url,
                 json=request_to_json_rpc(request),
+                headers=merged_headers,
             )
             try:
                 return json_to_response(response.json())
@@ -53,4 +81,4 @@ async def _request_impl(
                         "error": response.status_code,
                         "error_message": response.text,
                     }
-                )
+                ) from None