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

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,3 @@
+from .nonce_service import NonceService
+
+__all__ = ["NonceService"]

cledar/nonce/nonce_service.py

@@ -0,0 +1,36 @@
+"""
+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):
+        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"""
+        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)"""
+
+        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,
+    )