cledar-sdk 2.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

cledar/monitoring/tests/integration/test_monitoring_server_int.py

@@ -0,0 +1,162 @@
+# pylint: disable=redefined-outer-name, unreachable
+import logging
+from collections.abc import Awaitable, Callable
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+
+from cledar.monitoring import EndpointFilter, MonitoringServer, MonitoringServerConfig
+
+# ------------------------------------------------------------------------------
+#  Fixtures
+# ------------------------------------------------------------------------------
+
+
+@pytest.fixture
+def test_app() -> FastAPI:
+    """Creates a FastAPI app with configured monitoring endpoints."""
+    app = FastAPI()
+    config = MonitoringServerConfig(
+        readiness_checks={"db": lambda: True},
+        liveness_checks={"heartbeat": lambda: True},
+    )
+    server = MonitoringServer("127.0.0.1", 8000, config)
+    server.add_paths(app)
+    return app
+
+
+ASGIClientFactory = Callable[[FastAPI], Awaitable[AsyncClient]]
+
+
+@pytest.fixture
+def asgi_client_factory() -> ASGIClientFactory:
+    """Factory to create an httpx.AsyncClient for ASGI apps (httpx>=0.28)."""
+
+    async def _make_client(app: FastAPI) -> AsyncClient:
+        transport = ASGITransport(app=app)
+        return AsyncClient(transport=transport, base_url="http://test")
+
+    return _make_client
+
+
+# ------------------------------------------------------------------------------
+#  Readiness & Liveness Endpoints
+# ------------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_readiness_ok(
+    test_app: FastAPI, asgi_client_factory: ASGIClientFactory
+) -> None:
+    """Readiness endpoint returns OK when all checks pass."""
+    async with await asgi_client_factory(test_app) as client:
+        response = await client.get("/healthz/readiness")
+
+    data = response.json()
+    assert response.status_code == 200
+    assert data["status"] == "ok"
+    assert data["checks"]["db"] is True
+
+
+@pytest.mark.asyncio
+async def test_liveness_ok(
+    test_app: FastAPI, asgi_client_factory: ASGIClientFactory
+) -> None:
+    """Liveness endpoint returns OK when all checks pass."""
+    async with await asgi_client_factory(test_app) as client:
+        response = await client.get("/healthz/liveness")
+
+    data = response.json()
+    assert response.status_code == 200
+    assert data["status"] == "ok"
+    assert data["checks"]["heartbeat"] is True
+
+
+@pytest.mark.asyncio
+async def test_readiness_failing_check(asgi_client_factory: ASGIClientFactory) -> None:
+    """Readiness endpoint returns 503 and error status if a check fails."""
+    app = FastAPI()
+    config = MonitoringServerConfig(readiness_checks={"db": lambda: False})
+    server = MonitoringServer("127.0.0.1", 8000, config)
+    server.add_paths(app)
+
+    async with await asgi_client_factory(app) as client:
+        response = await client.get("/healthz/readiness")
+
+    data = response.json()
+    assert response.status_code == 503
+    assert data["status"] == "error"
+    assert data["checks"]["db"] is False
+
+
+@pytest.mark.asyncio
+async def test_readiness_with_exception(asgi_client_factory: ASGIClientFactory) -> None:
+    """Readiness returns 503 if a check raises an exception."""
+
+    def failing_check() -> bool:
+        raise RuntimeError("DB not reachable")
+        return False
+
+    app = FastAPI()
+    config = MonitoringServerConfig(readiness_checks={"db": failing_check})
+    server = MonitoringServer("127.0.0.1", 8000, config)
+    server.add_paths(app)
+
+    async with await asgi_client_factory(app) as client:
+        response = await client.get("/healthz/readiness")
+
+    data = response.json()
+    assert response.status_code == 503
+    assert data["status"] == "error"
+    assert "DB not reachable" in data["message"]
+
+
+# ------------------------------------------------------------------------------
+#  Metrics Endpoint
+# ------------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_metrics_endpoint_returns_prometheus_format(
+    test_app: FastAPI, asgi_client_factory: ASGIClientFactory
+) -> None:
+    """Metrics endpoint should return valid Prometheus output."""
+    async with await asgi_client_factory(test_app) as client:
+        response = await client.get("/metrics")
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("text/plain")
+    assert "python_info" in response.text  # standard metric
+
+
+# ------------------------------------------------------------------------------
+#  Logging Filter
+# ------------------------------------------------------------------------------
+
+
+def test_endpoint_filter_excludes_health_paths() -> None:
+    """EndpointFilter should exclude healthz paths from logs."""
+    filter_ = EndpointFilter(["/healthz/readiness", "/healthz/liveness"])
+
+    record_excluded = logging.LogRecord(
+        name="uvicorn.access",
+        level=logging.INFO,
+        pathname="",
+        lineno=0,
+        msg="GET /healthz/readiness 200 OK",
+        args=(),
+        exc_info=None,
+    )
+    assert filter_.filter(record_excluded) is False
+
+    record_included = logging.LogRecord(
+        name="uvicorn.access",
+        level=logging.INFO,
+        pathname="",
+        lineno=0,
+        msg="GET /metrics 200 OK",
+        args=(),
+        exc_info=None,
+    )
+    assert filter_.filter(record_included) is True

cledar/monitoring/tests/test_monitoring_server.py

@@ -0,0 +1,59 @@
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from cledar.monitoring import MonitoringServer, MonitoringServerConfig
+
+HOST = "localhost"
+PORT = 9999
+
+
+class ReadinessFlag:
+    def __init__(self) -> None:
+        self.is_ready = False
+
+    def mark_ready(self) -> None:
+        self.is_ready = True
+
+    def check_if_ready(self) -> bool:
+        return self.is_ready
+
+
+@pytest.fixture
+def readiness_flag() -> ReadinessFlag:
+    _readiness_flag = ReadinessFlag()
+    return _readiness_flag
+
+
+@pytest.fixture
+def app(readiness_flag: ReadinessFlag) -> FastAPI:
+    _app = FastAPI()
+    default_readiness_checks = dict({"is_ready": readiness_flag.check_if_ready})
+    config = MonitoringServerConfig(default_readiness_checks)
+    monitoring_server = MonitoringServer(HOST, PORT, config)
+    monitoring_server.add_paths(_app)
+    return _app
+
+
+@pytest.fixture
+def client(app: FastAPI) -> TestClient:
+    _client = TestClient(app)
+    return _client
+
+
+def test_liveness(client: TestClient) -> None:
+    response = client.get("/healthz/liveness")
+    assert response.status_code == 200
+    assert response.text == '{"status": "ok", "checks": {}}'
+
+
+def test_readiness(client: TestClient, readiness_flag: ReadinessFlag) -> None:
+    response = client.get("/healthz/readiness")
+    assert response.status_code == 503
+    assert response.text == '{"status": "error", "checks": {"is_ready": false}}'
+
+    readiness_flag.mark_ready()
+
+    response = client.get("/healthz/readiness")
+    assert response.status_code == 200
+    assert response.text == '{"status": "ok", "checks": {"is_ready": true}}'

cledar/nonce/README.md

@@ -0,0 +1,99 @@
+# NonceService
+
+Simple nonce service for preventing duplicate request processing using Redis with TTL-based automatic cleanup.
+
+It is useful for implementing idempotency in APIs, background workers, and event processing pipelines where the same request/message may arrive more than once.
+
+## Features
+- Fast duplicate detection backed by Redis SET NX
+- Per-endpoint scoping (the same nonce can be used across different endpoints)
+- Automatic expiry via TTL (default 1 hour)
+- Tiny API surface and easy integration
+
+## Requirements
+- Redis server accessible from your application
+- Python dependencies:
+  - `redis` (redis-py)
+  - This repository/module (imports shown below)
+
+## Installation
+Make sure you have `redis` installed in your environment:
+
+```bash
+uv add redis
+```
+
+This module lives inside this repository. Import it directly from your code as shown in the examples below.
+
+## Quickstart
+
+```python
+import asyncio
+from cledar.redis.redis import RedisService, RedisServiceConfig
+from cledar.nonce import NonceService
+
+# 1) Create a Redis client
+config = RedisServiceConfig(redis_host="localhost", redis_port=6379, redis_db=0)
+redis_client = RedisService(config)
+
+# 2) Create the NonceService
+nonce_service = NonceService(redis_client)
+
+# Optional: override default TTL (seconds)
+nonce_service.default_ttl = 7200  # 2 hours
+
+async def main():
+    nonce = "request-id-123"
+    endpoint = "/api/payment"  # any string identifying the endpoint or operation
+
+    # First time: not a duplicate -> returns False
+    first = await nonce_service.is_duplicate(nonce, endpoint)
+    print(first)  # False
+
+    # Second time (same nonce + same endpoint): duplicate -> returns True
+    second = await nonce_service.is_duplicate(nonce, endpoint)
+    print(second)  # True
+
+    # Same nonce but a different endpoint is treated independently
+    third = await nonce_service.is_duplicate(nonce, "/api/other-endpoint")
+    print(third)  # False
+
+asyncio.run(main())
+```
+
+## How it works
+Under the hood, `NonceService.is_duplicate(nonce, endpoint)` performs a Redis `SET` with the flags `NX` (only set if not exists) and `EX=<TTL>`. If Redis returns that the key was set, this is the first time the nonce is seen for that endpoint (not a duplicate -> returns `False`). If the key already exists, Redis returns `None`, which the service treats as a duplicate -> returns `True`.
+
+- Redis key format: `nonce:{endpoint}:{nonce}`
+- Default TTL: `3600` seconds (1 hour); can be changed via `nonce_service.default_ttl`
+- Endpoint scoping: the same nonce value can be used across different endpoints without being considered a duplicate between them
+
+## API
+
+```python
+from cledar.redis.redis import RedisService
+
+class NonceService:
+    def __init__(self, redis_client: RedisService):
+        """Simple service for managing nonces to prevent duplicate requests."""
+        ...
+
+    async def is_duplicate(self, nonce: str, endpoint: str) -> bool:
+        """Return True if (nonce, endpoint) was already used within TTL."""
+        ...
+```
+
+### Errors
+- `RuntimeError("Redis client is not initialized")` — raised when `redis_client._client` is `None`.
+
+## Testing
+This module includes unit tests. To run them:
+
+```bash
+uv run pytest nonce_service/tests -q
+```
+
+## Best practices
+- Use a stable nonce that uniquely identifies an operation (e.g., request ID, message ID)
+- Choose a TTL that matches the maximum time window in which duplicates must be rejected
+- Scope by a meaningful `endpoint` string to separate distinct operations

cledar/nonce/__init__.py

@@ -0,0 +1,5 @@
+"""Nonce service module for managing unique request identifiers."""
+
+from .nonce_service import NonceService
+
+__all__ = ["NonceService"]

cledar/nonce/nonce_service.py

@@ -0,0 +1,62 @@
+"""Simple nonce service for preventing duplicate request processing.
+
+Uses Redis with TTL for automatic cleanup.
+"""
+
+from cledar.redis.redis import RedisService
+
+
+class NonceService:
+    """Simple service for managing nonces to prevent duplicate requests."""
+
+    def __init__(self, redis_client: RedisService):
+        """Initialize the nonce service.
+
+        Args:
+            redis_client: The Redis client service used for storage.
+
+        """
+        self.redis_client = redis_client
+        self.nonce_prefix = "nonce"
+        self.default_ttl = 3600  # 1 hour
+
+    def _get_nonce_key(self, nonce: str, endpoint: str) -> str:
+        """Generate Redis key for nonce.
+
+        Args:
+            nonce: The unique identifier for the request.
+            endpoint: The endpoint the request is directed at.
+
+        Returns:
+            str: The formatted Redis key.
+
+        """
+        return f"{self.nonce_prefix}:{endpoint}:{nonce}"
+
+    async def is_duplicate(self, nonce: str, endpoint: str) -> bool:
+        """Check if nonce was already used (returns True if duplicate).
+
+        Args:
+            nonce: The unique identifier for the request.
+            endpoint: The endpoint the request is directed at.
+
+        Returns:
+            bool: True if the nonce is a duplicate, False otherwise.
+
+        Raises:
+            RuntimeError: If the Redis client is not initialized.
+
+        """
+        nonce_key = self._get_nonce_key(nonce, endpoint)
+
+        if self.redis_client._client is None:
+            raise RuntimeError("Redis client is not initialized")
+
+        result = self.redis_client._client.set(
+            nonce_key,
+            "used",
+            nx=True,
+            ex=self.default_ttl,
+        )
+
+        return result is None

cledar/nonce/tests/test_nonce_service.py

@@ -0,0 +1,136 @@
+# mypy: disable-error-code=no-untyped-def
+from unittest.mock import MagicMock
+
+import pytest
+
+from cledar.nonce import NonceService
+
+
+@pytest.fixture(name="redis_client")
+def fixture_redis_client():
+    """Mock Redis client"""
+    mock_redis = MagicMock()
+    mock_redis._client = MagicMock()
+    return mock_redis
+
+
+@pytest.fixture(name="nonce_service")
+def fixture_nonce_service(redis_client):
+    """Create NonceService with a mocked Redis client"""
+    return NonceService(redis_client)
+
+
+def test_init(redis_client):
+    """Test NonceService initialization"""
+    service = NonceService(redis_client)
+
+    assert service.redis_client == redis_client
+    assert service.nonce_prefix == "nonce"
+    assert service.default_ttl == 3600
+
+
+def test_get_nonce_key(nonce_service):
+    """Test nonce key generation"""
+    nonce = "test-nonce-123"
+    endpoint = "/api/payment"
+
+    key = nonce_service._get_nonce_key(nonce, endpoint)
+
+    assert key == "nonce:/api/payment:test-nonce-123"
+
+
+@pytest.mark.asyncio
+async def test_is_duplicate_first_time(nonce_service):
+    """Test that the first use of nonce returns False (not duplicate)"""
+    nonce = "unique-nonce-456"
+    endpoint = "/api/transaction"
+
+    # Mock Redis set to return True (key was set successfully)
+    nonce_service.redis_client._client.set.return_value = True
+
+    result = await nonce_service.is_duplicate(nonce, endpoint)
+
+    assert result is False
+    nonce_service.redis_client._client.set.assert_called_once_with(
+        "nonce:/api/transaction:unique-nonce-456",
+        "used",
+        nx=True,
+        ex=3600,
+    )
+
+
+@pytest.mark.asyncio
+async def test_is_duplicate_second_time(nonce_service):
+    """Test that second use of same nonce returns True (duplicate)"""
+    nonce = "duplicate-nonce-789"
+    endpoint = "/api/refund"
+
+    # Mock Redis set to return None (key already exists)
+    nonce_service.redis_client._client.set.return_value = None
+
+    result = await nonce_service.is_duplicate(nonce, endpoint)
+
+    assert result is True
+    nonce_service.redis_client._client.set.assert_called_once_with(
+        "nonce:/api/refund:duplicate-nonce-789",
+        "used",
+        nx=True,
+        ex=3600,
+    )
+
+
+@pytest.mark.asyncio
+async def test_is_duplicate_redis_not_initialized(nonce_service):
+    """Test that RuntimeError is raised when a Redis client is not initialized"""
+    nonce = "test-nonce"
+    endpoint = "/api/test"
+
+    # Simulate uninitialized Redis client
+    nonce_service.redis_client._client = None
+
+    with pytest.raises(RuntimeError, match="Redis client is not initialized"):
+        await nonce_service.is_duplicate(nonce, endpoint)
+
+
+@pytest.mark.asyncio
+async def test_is_duplicate_different_endpoints(nonce_service):
+    """Test that the same nonce is independent across different endpoints"""
+    nonce = "same-nonce"
+    endpoint1 = "/api/endpoint1"
+    endpoint2 = "/api/endpoint2"
+
+    # Both calls should treat the nonce as new (not duplicate)
+    nonce_service.redis_client._client.set.return_value = True
+
+    result1 = await nonce_service.is_duplicate(nonce, endpoint1)
+    result2 = await nonce_service.is_duplicate(nonce, endpoint2)
+
+    assert result1 is False
+    assert result2 is False
+
+    # Verify both keys were set with different endpoint prefixes
+    assert nonce_service.redis_client._client.set.call_count == 2
+    calls = nonce_service.redis_client._client.set.call_args_list
+    assert calls[0][0][0] == "nonce:/api/endpoint1:same-nonce"
+    assert calls[1][0][0] == "nonce:/api/endpoint2:same-nonce"
+
+
+@pytest.mark.asyncio
+async def test_is_duplicate_custom_ttl(redis_client):
+    """Test that custom TTL is used correctly"""
+    service = NonceService(redis_client)
+    service.default_ttl = 7200  # 2 hours
+
+    nonce = "test-nonce"
+    endpoint = "/api/test"
+
+    redis_client._client.set.return_value = True
+
+    await service.is_duplicate(nonce, endpoint)
+
+    redis_client._client.set.assert_called_once_with(
+        "nonce:/api/test:test-nonce",
+        "used",
+        nx=True,
+        ex=7200,
+    )