refactor: rename request logging native extension

Signed-off-by: lucarlig <luca.carlig@ibm.com>

Author: lucarlig

mcpgateway/config.py

@@ -352,7 +352,7 @@ class Settings(BaseSettings):
     experimental_validate_io: bool = Field(default=False, description="Enable experimental input validation and output sanitization")
     experimental_rust_request_logging_masking_enabled: bool = Field(
         default=False,
-        description="Enable experimental Rust sidecar for request logging sensitive-data masking",
+        description="Enable experimental Rust native extension for request logging sensitive-data masking",
     )
     validation_middleware_enabled: bool = Field(default=False, description="Enable validation middleware for all requests")
     validation_strict: bool = Field(default=True, description="Strict validation mode - reject on violations")

mcpgateway/middleware/request_logging_middleware.py

@@ -76,6 +76,7 @@
 structured_logger = get_structured_logger("http_gateway")
 
 _RUST_REQUEST_LOGGING_MODULE = None
+_RUST_REQUEST_LOGGING_IMPORT_FAILED = False
 
 SENSITIVE_KEYS = frozenset(
     {
@@ -187,7 +188,9 @@ def mask_sensitive_data(data, max_depth: int = 10):
         {'level': '<nested too deep>'}
     """
     if getattr(settings, "experimental_rust_request_logging_masking_enabled", False) is True:
-        return _load_rust_request_logging_module().mask_sensitive_data(data, max_depth)
+        rust_module = _load_rust_request_logging_module()
+        if rust_module is not None:
+            return rust_module.mask_sensitive_data(data, max_depth)
 
     if max_depth <= 0:
         return "<nested too deep>"
@@ -269,7 +272,9 @@ def mask_sensitive_headers(headers):
         True
     """
     if getattr(settings, "experimental_rust_request_logging_masking_enabled", False) is True:
-        return _load_rust_request_logging_module().mask_sensitive_headers(headers)
+        rust_module = _load_rust_request_logging_module()
+        if rust_module is not None:
+            return rust_module.mask_sensitive_headers(headers)
 
     masked_headers = {}
     for key, value in headers.items():
@@ -285,11 +290,21 @@ def mask_sensitive_headers(headers):
 
 
 def _load_rust_request_logging_module():
-    """Load the experimental Rust masking sidecar on demand."""
-    global _RUST_REQUEST_LOGGING_MODULE
+    """Load the experimental Rust masking native extension on demand."""
+    global _RUST_REQUEST_LOGGING_IMPORT_FAILED, _RUST_REQUEST_LOGGING_MODULE
 
     if _RUST_REQUEST_LOGGING_MODULE is None:
-        _RUST_REQUEST_LOGGING_MODULE = importlib.import_module("request_logging_masking_sidecar")
+        if _RUST_REQUEST_LOGGING_IMPORT_FAILED:
+            return None
+        try:
+            _RUST_REQUEST_LOGGING_MODULE = importlib.import_module("request_logging_masking_native_extension")
+        except ImportError as exc:
+            _RUST_REQUEST_LOGGING_IMPORT_FAILED = True
+            logger.warning(
+                f"Experimental Rust request logging masking is enabled but the native extension is unavailable; "
+                f"falling back to Python masking. Install the request logging masking native extension first. ({exc})"
+            )
+            return None
     return _RUST_REQUEST_LOGGING_MODULE
 
 

…est_logging_masking_sidecar_benchmark.py …ng_masking_native_extension_benchmark.pytests/performance/test_request_logging_masking_sidecar_benchmark.py renamed to tests/performance/test_request_logging_masking_native_extension_benchmark.py tests/performance/test_request_logging_masking_sidecar_benchmark.py renamed to tests/performance/test_request_logging_masking_native_extension_benchmark.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""Benchmark the request-logging masking Rust sidecar against the Python path."""
+"""Benchmark the request-logging masking Rust native extension against the Python path."""
 
 # Standard
 from __future__ import annotations
@@ -16,12 +16,12 @@
 from mcpgateway.middleware.request_logging_middleware import mask_sensitive_data, mask_sensitive_headers
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
-SIDECAR_MANIFEST = REPO_ROOT / "tools_rust" / "request_logging_masking_sidecar" / "Cargo.toml"
+NATIVE_EXTENSION_MANIFEST = REPO_ROOT / "tools_rust" / "request_logging_masking_native_extension" / "Cargo.toml"
 
 
-def _ensure_sidecar_installed() -> Any:
-    subprocess.run(["uv", "run", "maturin", "develop", "--release", "--manifest-path", str(SIDECAR_MANIFEST)], check=True, cwd=REPO_ROOT)
-    return importlib.import_module("request_logging_masking_sidecar")
+def _ensure_native_extension_installed() -> Any:
+    subprocess.run(["uv", "run", "maturin", "develop", "--release", "--manifest-path", str(NATIVE_EXTENSION_MANIFEST)], check=True, cwd=REPO_ROOT)
+    return importlib.import_module("request_logging_masking_native_extension")
 
 
 def _measure(label: str, fn: Callable[[Any], Any], payload: Any, iterations: int) -> tuple[float, float]:
@@ -46,17 +46,17 @@ def _assert_parity(python_fn: Callable[[Any], Any], rust_fn: Callable[[Any], Any
 
 
 def main() -> None:
-    sidecar = _ensure_sidecar_installed()
+    native_extension = _ensure_native_extension_installed()
     settings.experimental_rust_request_logging_masking_enabled = False
 
     def python_data(payload: Any) -> Any:
         return mask_sensitive_data(payload, 12)
 
     def rust_data(payload: Any) -> Any:
-        return sidecar.mask_sensitive_data(payload, 12)
+        return native_extension.mask_sensitive_data(payload, 12)
 
     python_headers = mask_sensitive_headers
-    rust_headers = sidecar.mask_sensitive_headers
+    rust_headers = native_extension.mask_sensitive_headers
 
     _assert_parity(
         python_data,

tests/unit/mcpgateway/middleware/test_request_logging_middleware.py

@@ -65,6 +65,12 @@ async def _call_next(request):
     return _call_next
 
 
+@pytest.fixture(autouse=True)
+def reset_rust_request_logging_module_state(monkeypatch):
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware._RUST_REQUEST_LOGGING_MODULE", None)
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware._RUST_REQUEST_LOGGING_IMPORT_FAILED", False)
+
+
 def make_request(body: bytes = b"{}", headers=None, query_params=None):
     scope: Scope = {
         "type": "http",
@@ -125,16 +131,42 @@ def test_mask_sensitive_data_ignores_empty_normalized_keys():
     assert masked["password"] == "******"
 
 
-def test_mask_sensitive_data_uses_pyo3_module_when_enabled(monkeypatch):
-    rust_module = MagicMock()
-    rust_module.mask_sensitive_data.return_value = {"password": "******", "username": "user"}  # pragma: allowlist secret
+def test_mask_sensitive_data_uses_native_extension_when_enabled(monkeypatch):
+    native_extension = MagicMock()
+    native_extension.mask_sensitive_data.return_value = {"password": "******", "username": "user"}  # pragma: allowlist secret
     monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
 
-    with patch("mcpgateway.middleware.request_logging_middleware._load_rust_request_logging_module", return_value=rust_module):
+    with patch("mcpgateway.middleware.request_logging_middleware._load_rust_request_logging_module", return_value=native_extension):
         masked = mask_sensitive_data({"password": "secret", "username": "user"})  # pragma: allowlist secret
 
     assert masked == {"password": "******", "username": "user"}  # pragma: allowlist secret
-    rust_module.mask_sensitive_data.assert_called_once_with({"password": "secret", "username": "user"}, 10)  # pragma: allowlist secret
+    native_extension.mask_sensitive_data.assert_called_once_with({"password": "secret", "username": "user"}, 10)  # pragma: allowlist secret
+
+
+def test_mask_sensitive_data_falls_back_to_python_when_native_extension_import_fails(monkeypatch, dummy_logger):
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.importlib.import_module", MagicMock(side_effect=ImportError("boom")))
+
+    masked = mask_sensitive_data({"password": "secret", "username": "user"})  # pragma: allowlist secret
+
+    assert masked == {"password": "******", "username": "user"}  # pragma: allowlist secret
+    assert len(dummy_logger.warnings) == 1
+    assert "falling back to Python masking" in dummy_logger.warnings[0]
+    assert "native extension" in dummy_logger.warnings[0]
+
+
+def test_mask_sensitive_data_caches_failed_native_extension_import(monkeypatch, dummy_logger):
+    import_module = MagicMock(side_effect=ImportError("boom"))
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.importlib.import_module", import_module)
+
+    first = mask_sensitive_data({"password": "secret"})  # pragma: allowlist secret
+    second = mask_sensitive_data({"password": "secret"})  # pragma: allowlist secret
+
+    assert first == {"password": "******"}  # pragma: allowlist secret
+    assert second == {"password": "******"}  # pragma: allowlist secret
+    assert import_module.call_count == 1
+    assert len(dummy_logger.warnings) == 1
 
 
 # --- mask_jwt_in_cookies tests ---
@@ -196,16 +228,26 @@ def test_mask_sensitive_headers_respects_non_sensitive_suffixes():
     assert masked["X-JWT_Status_Count"] == "7"
 
 
-def test_mask_sensitive_headers_uses_pyo3_module_when_enabled(monkeypatch):
-    rust_module = MagicMock()
-    rust_module.mask_sensitive_headers.return_value = {"Authorization": "******"}
+def test_mask_sensitive_headers_uses_native_extension_when_enabled(monkeypatch):
+    native_extension = MagicMock()
+    native_extension.mask_sensitive_headers.return_value = {"Authorization": "******"}
     monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
 
-    with patch("mcpgateway.middleware.request_logging_middleware._load_rust_request_logging_module", return_value=rust_module):
+    with patch("mcpgateway.middleware.request_logging_middleware._load_rust_request_logging_module", return_value=native_extension):
         masked = mask_sensitive_headers({"Authorization": "Bearer abc"})
 
     assert masked == {"Authorization": "******"}
-    rust_module.mask_sensitive_headers.assert_called_once_with({"Authorization": "Bearer abc"})
+    native_extension.mask_sensitive_headers.assert_called_once_with({"Authorization": "Bearer abc"})
+
+
+def test_mask_sensitive_headers_fall_back_to_python_when_native_extension_import_fails(monkeypatch, dummy_logger):
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.importlib.import_module", MagicMock(side_effect=ImportError("boom")))
+
+    masked = mask_sensitive_headers({"Authorization": "Bearer abc", "X-Trace-Id": "123"})
+
+    assert masked == {"Authorization": "******", "X-Trace-Id": "123"}
+    assert len(dummy_logger.warnings) == 1
 
 
 # --- RequestLoggingMiddleware tests ---
@@ -222,6 +264,23 @@ async def test_dispatch_logs_json_body(dummy_logger, mock_structured_logger, dum
     assert "******" in dummy_logger.logged[0][1]
 
 
+@pytest.mark.asyncio
+async def test_dispatch_falls_back_to_python_masking_when_native_extension_import_fails(dummy_logger, mock_structured_logger, dummy_call_next, monkeypatch):
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.settings.experimental_rust_request_logging_masking_enabled", True, raising=False)
+    monkeypatch.setattr("mcpgateway.middleware.request_logging_middleware.importlib.import_module", MagicMock(side_effect=ImportError("boom")))
+
+    middleware = RequestLoggingMiddleware(app=None, enable_gateway_logging=False, log_detailed_requests=True)
+    body = orjson.dumps({"password": "123", "data": "ok"})
+    request = make_request(body=body, headers={"Authorization": "Bearer abc"})
+
+    response = await middleware.dispatch(request, dummy_call_next)
+
+    assert response.status_code == 200
+    assert any("📩 Incoming request" in msg for _, msg in dummy_logger.logged)
+    assert "******" in dummy_logger.logged[0][1]
+    assert any("falling back to Python masking" in warning for warning in dummy_logger.warnings)
+
+
 @pytest.mark.asyncio
 async def test_dispatch_logs_non_json_body(dummy_logger, mock_structured_logger, dummy_call_next):
     middleware = RequestLoggingMiddleware(app=None, enable_gateway_logging=False, log_detailed_requests=True)

…quest_logging_masking_sidecar/Cargo.lock …ging_masking_native_extension/Cargo.locktools_rust/request_logging_masking_sidecar/Cargo.lock renamed to tools_rust/request_logging_masking_native_extension/Cargo.lock tools_rust/request_logging_masking_sidecar/Cargo.lock renamed to tools_rust/request_logging_masking_native_extension/Cargo.lock

@@ -1,11 +1,11 @@
 [package]
-name = "request_logging_masking_sidecar"
+name = "request_logging_masking_native_extension"
 version = "0.1.0"
 edition = "2021"
 license = "Apache-2.0"
 
 [lib]
-name = "request_logging_masking_sidecar"
+name = "request_logging_masking_native_extension"
 crate-type = ["cdylib"]
 
 [dependencies]

…quest_logging_masking_sidecar/Cargo.toml …ging_masking_native_extension/Cargo.tomltools_rust/request_logging_masking_sidecar/Cargo.toml renamed to tools_rust/request_logging_masking_native_extension/Cargo.toml tools_rust/request_logging_masking_sidecar/Cargo.toml renamed to tools_rust/request_logging_masking_native_extension/Cargo.toml

@@ -3,10 +3,10 @@ requires = ["maturin>=1.8,<2.0"]
 build-backend = "maturin"
 
 [project]
-name = "request-logging-masking-sidecar"
+name = "request-logging-masking-native-extension"
 version = "0.1.0"
 requires-python = ">=3.11"
 
 [tool.maturin]
-module-name = "request_logging_masking_sidecar"
+module-name = "request_logging_masking_native_extension"
 bindings = "pyo3"

…t_logging_masking_sidecar/pyproject.toml …_masking_native_extension/pyproject.tomltools_rust/request_logging_masking_sidecar/pyproject.toml renamed to tools_rust/request_logging_masking_native_extension/pyproject.toml tools_rust/request_logging_masking_sidecar/pyproject.toml renamed to tools_rust/request_logging_masking_native_extension/pyproject.toml

@@ -224,7 +224,7 @@ fn mask_sensitive_headers(py: Python<'_>, headers: &Bound<'_, PyAny>) -> PyResul
 }
 
 #[pymodule]
-fn request_logging_masking_sidecar(module: &Bound<'_, PyModule>) -> PyResult<()> {
+fn request_logging_masking_native_extension(module: &Bound<'_, PyModule>) -> PyResult<()> {
     module.add_function(wrap_pyfunction!(mask_sensitive_data, module)?)?;
     module.add_function(wrap_pyfunction!(mask_sensitive_headers, module)?)?;
     Ok(())