litewave-cache-lib 0.1.2__py3-none-any.whl

litewave_cache_lib-0.1.2.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: litewave-cache-lib
+Version: 0.1.2
+Summary: A lightweight Python library for Redis-backed tenant configuration storage
+Project-URL: Homepage, https://github.com/aiorch/litewave-cache-lib
+Project-URL: Repository, https://github.com/aiorch/litewave-cache-lib
+Author-email: Nagarjuna Sarvepalli <nagarjuna.s@litewave.ai>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# litewave-cache-lib
+
+A lightweight Python library that provides a connection-pooled, fault-tolerant Redis client with automatic retry logic and JSON-aware key lookup helpers for tenant configuration storage.
+
+---
+
+## Features
+
+- Connection-pooled Redis client with automatic retry on failure (5-minute cooldown)
+- Fetch values by raw Redis key, or by `(tenant_id, secret_name)` pair via `get_secret`
+- Automatic JSON deserialization of stored values
+- Attribute-level extraction from stored JSON objects via `get_attribute_value_by_key`
+- Standardised tenant key format: `tenant:{tenant_id}:secret:{secret_name}`
+- Fully configurable via environment variables
+- Zero-boilerplate logging setup
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/aiorch/litewave-cache-lib
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/aiorch/litewave-cache-lib.git
+cd litewave-cache-lib
+pip install .
+```
+
+---
+
+## Requirements
+
+- Python >= 3.10
+- redis >= 5.0.0
+- python-dotenv >= 1.0.0
+
+---
+
+## Configuration
+
+All settings are read from environment variables at import time. `REDIS_HOST`, `REDIS_PORT`, and `REDIS_PASSWORD` are **required** — the library raises a `ValueError` at startup if any of them are missing.
+
+| Environment Variable           | Default | Description                                   |
+|--------------------------------|---------|-----------------------------------------------|
+| `REDIS_HOST`                   | **(required)** | Redis server hostname                |
+| `REDIS_PORT`                   | **(required)** | Redis server port                    |
+| `REDIS_PASSWORD`               | **(required)** | Redis password                       |
+| `REDIS_DB`                     | `0`     | Default Redis database index                  |
+| `REDIS_COORDINATION_DB`        | `1`     | Redis DB reserved for coordination workloads  |
+| `REDIS_TENANT_CONFIG_DB`       | `2`     | Redis DB used for tenant configuration        |
+| `REDIS_MAX_CONNECTIONS`        | `50`    | Connection pool size                          |
+| `REDIS_SOCKET_CONNECT_TIMEOUT` | `2`     | Socket connect timeout in seconds             |
+| `REDIS_SOCKET_TIMEOUT`         | `2`     | Socket read/write timeout in seconds          |
+| `LOG_LEVEL`                    | `INFO`  | Logging level (`DEBUG`, `INFO`, `WARNING`, …) |
+
+A `.env` file is supported via `python-dotenv`. Load it before importing the library:
+
+```python
+from dotenv import load_dotenv
+load_dotenv(".env", override=True)
+
+from tenant_mgr_cache import get_redis_client
+```
+
+---
+
+## Usage
+
+### Get the Redis client
+
+Returns the shared, connection-pooled Redis client. Returns `None` if the connection is unavailable. A failed connection is retried automatically after a 5-minute cooldown; subsequent calls reuse the existing client.
+
+```python
+from tenant_mgr_cache import get_redis_client
+
+client = get_redis_client()
+if client:
+    client.set("tenant:15:secret:satoken", "abc123")
+    print(client.get("tenant:15:secret:satoken"))  # "abc123"
+```
+
+---
+
+### `get_secret` — fetch by tenant ID and secret name
+
+Builds the canonical key `tenant:{tenant_id}:secret:{secret_name}` internally and returns the stored value. JSON values are deserialized automatically; plain strings are returned as-is.
+
+```python
+from tenant_mgr_cache import get_secret
+
+# JSON object stored → returned as dict
+config = get_secret("15", "db_config")
+if isinstance(config, dict):
+    print(config["host"])   # e.g. "db.prod.internal"
+    print(config["port"])   # e.g. 5432
+
+# Plain string stored → returned as-is
+token = get_secret("15", "satoken")
+print(token)                # e.g. "abc123"
+
+# Key does not exist → None
+missing = get_secret("15", "nonexistent")
+print(missing)              # None
+```
+
+
+### `get_secret(tenant_id: str, secret_name: str) -> Optional[Any]`
+
+Builds the canonical key `tenant:{tenant_id}:secret:{secret_name}` and returns the stored value. JSON is deserialized automatically. Returns `None` if the key does not exist, Redis is unavailable, or any error occurs.
+
+---
+
+### `get_value_by_key(key: str) -> Optional[Any]`
+
+Fetches the value stored at `key` and JSON-decodes it if possible. Returns `None` when the key does not exist, Redis is unavailable, or any error occurs.
+
+---
+
+### `get_attribute_value_by_key(tenant_id: str, secret_name: str, attribute_name: str) -> Optional[Any]`
+
+Builds the canonical key for `tenant_id` + `secret_name`, fetches the stored JSON object, and returns `data.get(attribute_name)`. Falls back to `getattr` for non-dict objects. Returns `None` if the key is missing, the value is not dict-like, or the attribute is absent.
+
+---
+
+### `prepare_key(tenant_id: str, secret_name: str) -> str`
+
+Builds the canonical Redis key for a tenant secret:
+
+```python
+from tenant_mgr_cache.cache_client import prepare_key
+
+key = prepare_key("15", "satoken")
+print(key)  # "tenant:15:secret:satoken"
+```
+
+---
+
+### `settings` — `CacheSettings`
+
+A dataclass instance holding all resolved configuration values. Import it to inspect or override settings programmatically:
+
+```python
+from tenant_mgr_cache import settings
+
+print(settings.REDIS_HOST)
+print(settings.REDIS_PORT)
+print(settings.REDIS_TENANT_CONFIG_DB)
+```
+
+---
+
+### `logger` — `logging.Logger`
+
+A pre-configured logger (`litewave_cache`) that respects the `LOG_LEVEL` environment variable. Import it to emit log messages consistent with the library's format:
+
+```python
+from tenant_mgr_cache import logger
+
+logger.info("Custom message from application code")
+```
+
+---
+
+## Development
+
+### Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=tenant_mgr_cache --cov-report=term-missing
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

litewave_cache_lib-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+tenant_mgr_cache/__init__.py,sha256=3OFuIBaDEDrKZy8HnqX8XIYyP8cpUdctn6SufbJjkU0,427
+tenant_mgr_cache/cache_client.py,sha256=HCkG1Tu-k9cFtGU2BizpHdnaPNxRHLO2jmqgysSWTvs,4323
+tenant_mgr_cache/config.py,sha256=hyZOs5L0Lvgqy0AJVHGNfXAVGGrqcgDwEeAr65l1pYQ,1694
+litewave_cache_lib-0.1.2.dist-info/METADATA,sha256=S5TlgTzO9kY25laHHLFh1s2ZuHQAftT6kGvDNZiAFyY,6416
+litewave_cache_lib-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+litewave_cache_lib-0.1.2.dist-info/RECORD,,

litewave_cache_lib-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tenant_mgr_cache/__init__.py

@@ -0,0 +1,21 @@
+"""
+litewave-cache-lib: A lightweight cache library
+for tenant configuration storage.
+"""
+
+from tenant_mgr_cache.cache_client import (
+    get_redis_client,
+    get_secret,
+    get_value_by_key,
+    get_attribute_value_by_key,
+)
+from tenant_mgr_cache.config import settings, logger
+
+__all__ = [
+    "get_redis_client",
+    "get_secret",
+    "get_value_by_key",
+    "get_attribute_value_by_key",
+    "settings",
+    "logger",
+]

tenant_mgr_cache/cache_client.py

@@ -0,0 +1,139 @@
+"""
+Redis client utilities for tenant configuration storage with 48-hour TTL.
+"""
+
+import json
+import time
+from typing import Any, Optional
+
+import redis
+
+from tenant_mgr_cache.config import logger, settings
+
+REDIS_RETRY_INTERVAL: int = 300  # Seconds between retry attempts (5 min)
+
+
+class _ConnectionState:  # pylint: disable=too-few-public-methods
+    """Holds mutable Redis connection state to avoid module-level globals."""
+
+    def __init__(self) -> None:
+        self.client: Optional[redis.Redis] = None
+        self.connection_failed: bool = False
+        self.last_connection_attempt: float = 0
+
+
+_state = _ConnectionState()
+
+
+def get_redis_client() -> Optional[redis.Redis]:
+    """
+    Returns a singleton Redis client for tenant configuration storage,
+    utilizing redis-py connection pooling.
+    Reattempts connection only every REDIS_RETRY_INTERVAL seconds
+    after a failure.
+
+    Returns:
+        redis.Redis or None if connection cannot be established
+    """
+    if _state.connection_failed:
+        since_last = time.time() - _state.last_connection_attempt
+        if since_last < REDIS_RETRY_INTERVAL:
+            return None
+        logger.info(
+            "Retrying Redis connection for tenant config "
+            "after %.0fs (interval %ds)",
+            since_last, REDIS_RETRY_INTERVAL,
+        )
+        _state.connection_failed = False
+        _state.client = None
+
+    if _state.client is not None:
+        return _state.client
+
+    try:
+        pool = redis.ConnectionPool(
+            host=settings.REDIS_HOST,
+            port=settings.REDIS_PORT,
+            db=settings.REDIS_TENANT_CONFIG_DB,
+            password=settings.REDIS_PASSWORD or None,
+            decode_responses=True,
+            max_connections=settings.REDIS_MAX_CONNECTIONS,
+            socket_connect_timeout=settings.REDIS_SOCKET_CONNECT_TIMEOUT,
+            socket_timeout=settings.REDIS_SOCKET_TIMEOUT,
+        )
+        client = redis.Redis(connection_pool=pool)
+        client.ping()
+        _state.client = client
+        logger.info(
+            "Initialized Redis client for tenant configuration (DB: %s)",
+            settings.REDIS_TENANT_CONFIG_DB
+        )
+        return _state.client
+    except redis.RedisError as exc:
+        logger.warning("Failed to connect to Redis for tenant config: %s", exc)
+        _state.connection_failed = True
+        _state.last_connection_attempt = time.time()
+        return None
+
+
+def prepare_key(tenant_id: str, secret_name: str) -> str:
+    """Build the standardized Redis key for a tenant's secret."""
+    return f"tenant:{tenant_id}:secret:{secret_name}"
+
+
+def get_secret(tenant_id: str, secret_name: str) -> Optional[Any]:
+    """
+    Flexible interface for retrieving values from Redis:
+      - If only tenant_id and secret_name are provided:
+        treat as tenant_id and secret_name, fetch object.
+    """
+
+    key = prepare_key(tenant_id, secret_name)
+    return get_value_by_key(key)
+
+
+def get_value_by_key(key: str) -> Optional[Any]:
+    """
+    Fetch a (possibly JSON) value from Redis by key, parsing if possible.
+    """
+    redis_client = get_redis_client()
+    if not redis_client:
+        logger.warning(
+            "Redis client not available, cannot read value for key: %s",
+            key,
+        )
+        return None
+    try:
+        raw = redis_client.get(key)
+        if raw is None:
+            logger.debug("Key not found in Redis: %s", key)
+            return None
+
+        try:
+            return json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            return raw
+    except redis.RedisError as exc:
+        logger.error("Error reading key '%s' from Redis: %s", key, exc)
+        return None
+
+
+def get_attribute_value_by_key(
+    tenant_id: str,
+    secret_name: str,
+    attribute_name: str,
+) -> Optional[Any]:
+    """
+    Fetches an object from Redis by key and retrieves the specified
+    attribute (dict key or attr).
+    Returns None on error or if attribute is missing.
+    """
+    key = prepare_key(tenant_id, secret_name)
+    data = get_value_by_key(key)
+    if data is None:
+        return None
+    if isinstance(data, dict):
+        return data[secret_name].get(attribute_name)
+    if hasattr(data, attribute_name):  # fallback—rare
+        return getattr(data, attribute_name, None)
+    return None

tenant_mgr_cache/config.py

@@ -0,0 +1,64 @@
+"""
+Configuration and logging setup for litewave-cache-lib.
+"""
+
+import logging
+import os
+from dataclasses import dataclass, field
+
+
+def _get_log_level() -> int:
+    level = os.environ.get("LOG_LEVEL", "INFO").upper()
+    return getattr(logging, level, logging.INFO)
+
+
+logging.basicConfig(
+    level=_get_log_level(),
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger("litewave_cache")
+
+
+def _require_env(name: str) -> str:
+    val = os.environ.get(name)
+    if val is None:
+        raise ValueError(f"{name} environment variable is required")
+    return val
+
+
+@dataclass
+class CacheSettings:  # pylint: disable=invalid-name
+    """Redis connection settings, populated from environment variables."""
+
+    REDIS_HOST: str = field(
+        default_factory=lambda: _require_env("REDIS_HOST")
+    )
+    REDIS_PORT: int = field(
+        default_factory=lambda: int(_require_env("REDIS_PORT"))
+    )
+    REDIS_PASSWORD: str = field(
+        default_factory=lambda: _require_env("REDIS_PASSWORD")
+    )
+    REDIS_TENANT_CONFIG_DB: int = field(
+        default_factory=lambda: int(
+            os.environ.get("REDIS_TENANT_CONFIG_DB", "0")
+        )
+    )
+    REDIS_MAX_CONNECTIONS: int = field(
+        default_factory=lambda: int(
+            os.environ.get("REDIS_MAX_CONNECTIONS", "50")
+        )
+    )
+    REDIS_SOCKET_CONNECT_TIMEOUT: float = field(
+        default_factory=lambda: float(
+            os.environ.get("REDIS_SOCKET_CONNECT_TIMEOUT", "2")
+        )
+    )
+    REDIS_SOCKET_TIMEOUT: float = field(
+        default_factory=lambda: float(
+            os.environ.get("REDIS_SOCKET_TIMEOUT", "2")
+        )
+    )
+
+
+settings = CacheSettings()