grass-redis 0.1.0__tar.gz

grass_redis-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: grass-redis
+Version: 0.1.0
+Summary: Redis Sentinel client with mandatory mutual TLS for high-availability Redis clusters
+Author: Alex
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# grass-redis
+
+Redis Sentinel client with mandatory mutual TLS.
+
+## Features
+
+- Automatic failover via Sentinel
+- Connection pooling and caching
+- Read replicas for load distribution
+- Mandatory TLS with client certificates
+
+## Installation
+
+```bash
+pip install -e libs/python/grass-redis
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from grass_redis import (
+    RedisSentinelClient,
+    SentinelConfig,
+    load_passwords_from_env,
+    load_sentinel_hosts_from_env,
+)
+
+# Load from environment (never hardcode)
+sentinel_hosts = load_sentinel_hosts_from_env()  # $REDIS_SENTINEL_HOSTS
+passwords = load_passwords_from_env()            # /etc/redis/certs/passwords.env
+
+config = SentinelConfig(
+    sentinel_hosts=sentinel_hosts,
+    databases=passwords,
+    certs_dir=Path("/etc/redis/certs"),
+)
+
+with RedisSentinelClient(config) as client:
+    primary = client.get_primary("db1")
+    primary.set("key", "value")
+    
+    replica = client.get_replica("db1")
+    value = replica.get("key")
+```
+
+## Configuration
+
+**Environment (optional):**
+```bash
+export REDIS_SENTINEL_HOSTS="host1:26379,host2:26379,host3:26379"
+```
+
+**Deploy certs via Ansible to `/etc/redis/certs/`:**
+- `client.crt` - Client certificate (644)
+- `client.key` - Private key (600)
+- `ca.crt` - CA certificate (644)
+- `passwords.env` - Passwords (600)
+
+**`passwords.env` format:**
+```bash
+REDIS_SCRAPER_DB1_PASSWORD=xxx
+REDIS_SCRAPER_DB2_PASSWORD=yyy
+```
+
+Names are converted: `REDIS_SCRAPER_DB1_PASSWORD` → database `scraper-db1`
+
+## API
+
+**SentinelConfig:**
+- `sentinel_hosts` - List[(host, port)]
+- `databases` - Dict[db_name, password]
+- `certs_dir` - Path (default: /etc/redis/certs)
+
+**RedisSentinelClient:**
+- `get_primary(db)` - Connection for writes
+- `get_replica(db)` - Connection for reads
+- `discover_primary(db)` - Get current primary address
+- `test_connection(db)` - PING test
+
+See `grass-platform/reference_implementation/python/redis/` for examples.

grass_redis-0.1.0/README.md

@@ -0,0 +1,81 @@
+# grass-redis
+
+Redis Sentinel client with mandatory mutual TLS.
+
+## Features
+
+- Automatic failover via Sentinel
+- Connection pooling and caching
+- Read replicas for load distribution
+- Mandatory TLS with client certificates
+
+## Installation
+
+```bash
+pip install -e libs/python/grass-redis
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from grass_redis import (
+    RedisSentinelClient,
+    SentinelConfig,
+    load_passwords_from_env,
+    load_sentinel_hosts_from_env,
+)
+
+# Load from environment (never hardcode)
+sentinel_hosts = load_sentinel_hosts_from_env()  # $REDIS_SENTINEL_HOSTS
+passwords = load_passwords_from_env()            # /etc/redis/certs/passwords.env
+
+config = SentinelConfig(
+    sentinel_hosts=sentinel_hosts,
+    databases=passwords,
+    certs_dir=Path("/etc/redis/certs"),
+)
+
+with RedisSentinelClient(config) as client:
+    primary = client.get_primary("db1")
+    primary.set("key", "value")
+    
+    replica = client.get_replica("db1")
+    value = replica.get("key")
+```
+
+## Configuration
+
+**Environment (optional):**
+```bash
+export REDIS_SENTINEL_HOSTS="host1:26379,host2:26379,host3:26379"
+```
+
+**Deploy certs via Ansible to `/etc/redis/certs/`:**
+- `client.crt` - Client certificate (644)
+- `client.key` - Private key (600)
+- `ca.crt` - CA certificate (644)
+- `passwords.env` - Passwords (600)
+
+**`passwords.env` format:**
+```bash
+REDIS_SCRAPER_DB1_PASSWORD=xxx
+REDIS_SCRAPER_DB2_PASSWORD=yyy
+```
+
+Names are converted: `REDIS_SCRAPER_DB1_PASSWORD` → database `scraper-db1`
+
+## API
+
+**SentinelConfig:**
+- `sentinel_hosts` - List[(host, port)]
+- `databases` - Dict[db_name, password]
+- `certs_dir` - Path (default: /etc/redis/certs)
+
+**RedisSentinelClient:**
+- `get_primary(db)` - Connection for writes
+- `get_replica(db)` - Connection for reads
+- `discover_primary(db)` - Get current primary address
+- `test_connection(db)` - PING test
+
+See `grass-platform/reference_implementation/python/redis/` for examples.

grass_redis-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grass-redis"
+version = "0.1.0"
+description = "Redis Sentinel client with mandatory mutual TLS for high-availability Redis clusters"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    { name = "Alex" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "redis>=5.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+# Update these URLs when publishing
+[project.urls]
+# Homepage = "https://github.com/your-org/grass-platform/tree/main/libs/python/grass-redis"
+# Repository = "https://github.com/your-org/grass-platform"
+# Issues = "https://github.com/your-org/grass-platform/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

grass_redis-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grass_redis-0.1.0/src/grass_redis/__init__.py

@@ -0,0 +1,22 @@
+"""
+grass-redis: Production-ready Redis Sentinel client with mandatory mutual TLS.
+
+This library provides a clean abstraction for connecting to Redis through Sentinel
+with automatic failover, connection pooling, and mandatory TLS security.
+"""
+
+from grass_redis.client import (
+    RedisSentinelClient,
+    SentinelConfig,
+    load_passwords_from_env,
+    load_sentinel_hosts_from_env,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RedisSentinelClient",
+    "SentinelConfig",
+    "load_passwords_from_env",
+    "load_sentinel_hosts_from_env",
+]

grass_redis-0.1.0/src/grass_redis/client.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Redis Sentinel client with mandatory mutual TLS.
+
+SECURITY: All connections require client certificates (client.crt, client.key, ca.crt).
+TLS cannot be disabled - this is a security-first design.
+
+Basic usage:
+    config = SentinelConfig(
+        sentinel_hosts=[("host1", 26379), ("host2", 26379)],
+        databases={"db1": "password1"},
+        certs_dir=Path("/etc/redis/certs"),
+    )
+    
+    with RedisSentinelClient(config) as client:
+        primary = client.get_primary("db1")
+        primary.set("key", "value")
+"""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import redis
+from redis.sentinel import Sentinel
+
+
+@dataclass
+class SentinelConfig:
+    """
+    Configuration for Redis Sentinel cluster.
+    
+    Required:
+        sentinel_hosts: List of (host, port) tuples
+        databases: Dict mapping database names to passwords
+    
+    Optional:
+        certs_dir: Certificate directory (default: /etc/redis/certs)
+        socket_timeout: Socket operation timeout in seconds (default: 5)
+        socket_connect_timeout: Connection timeout in seconds (default: 5)
+        decode_responses: Decode responses as UTF-8 (default: True)
+    """
+    sentinel_hosts: List[Tuple[str, int]]
+    databases: Dict[str, str]
+    certs_dir: Path = Path("/etc/redis/certs")
+    socket_timeout: int = 5
+    socket_connect_timeout: int = 5
+    decode_responses: bool = True
+    client_cert_name: str = "client.crt"
+    client_key_name: str = "client.key"
+    ca_cert_name: str = "ca.crt"
+    
+    def __post_init__(self):
+        if not self.sentinel_hosts:
+            raise ValueError("At least one Sentinel host is required")
+        if not self.databases:
+            raise ValueError("At least one database is required")
+    
+    @property
+    def client_cert_path(self) -> str:
+        return str(self.certs_dir / self.client_cert_name)
+    
+    @property
+    def client_key_path(self) -> str:
+        return str(self.certs_dir / self.client_key_name)
+    
+    @property
+    def ca_cert_path(self) -> str:
+        return str(self.certs_dir / self.ca_cert_name)
+    
+    def verify_certificates(self) -> Tuple[bool, List[str]]:
+        """Check that all required certificate files exist."""
+        missing = []
+        for path in [self.client_cert_path, self.client_key_path, self.ca_cert_path]:
+            if not Path(path).exists():
+                missing.append(path)
+        return len(missing) == 0, missing
+    
+    def build_connection_kwargs(self, database: str, max_connections: Optional[int] = None) -> Dict:
+        """Build redis connection kwargs with TLS configuration."""
+        kwargs = {
+            "password": self.databases[database],
+            "decode_responses": self.decode_responses,
+            "socket_timeout": self.socket_timeout,
+            "socket_connect_timeout": self.socket_connect_timeout,
+            "ssl": True,
+            "ssl_certfile": self.client_cert_path,
+            "ssl_keyfile": self.client_key_path,
+            "ssl_ca_certs": self.ca_cert_path,
+        }
+        if max_connections:
+            kwargs["max_connections"] = max_connections
+        return kwargs
+
+
+class RedisSentinelClient:
+    """
+    Redis Sentinel client with automatic failover and connection pooling.
+    
+    Features:
+        - Automatic primary discovery through Sentinel
+        - Connection pooling with caching
+        - Read replicas for load distribution
+        - Mandatory mutual TLS
+    """
+    
+    def __init__(self, config: SentinelConfig):
+        self.config = config
+        self._sentinel: Optional[Sentinel] = None
+        self._primary_clients: Dict[str, redis.Redis] = {}
+        self._replica_clients: Dict[str, redis.Redis] = {}
+        
+        # Verify certificates exist
+        success, missing = self.config.verify_certificates()
+        if not success:
+            raise FileNotFoundError(f"Missing certificates: {', '.join(missing)}")
+    
+    @property
+    def sentinel(self) -> Sentinel:
+        """Get or create Sentinel connection (lazy initialization)."""
+        if self._sentinel is None:
+            self._sentinel = Sentinel(
+                self.config.sentinel_hosts,
+                sentinel_kwargs={
+                    "socket_timeout": self.config.socket_timeout,
+                    "socket_connect_timeout": self.config.socket_connect_timeout,
+                    "ssl": True,
+                    "ssl_certfile": self.config.client_cert_path,
+                    "ssl_keyfile": self.config.client_key_path,
+                    "ssl_ca_certs": self.config.ca_cert_path,
+                },
+            )
+        return self._sentinel
+    
+    def get_primary(self, database: str, max_connections: Optional[int] = None) -> redis.Redis:
+        """Get primary connection for writes."""
+        if database not in self.config.databases:
+            raise KeyError(f"Database '{database}' not in config")
+        
+        if database in self._primary_clients:
+            return self._primary_clients[database]
+        
+        kwargs = self.config.build_connection_kwargs(database, max_connections)
+        primary = self.sentinel.master_for(database, **kwargs)
+        self._primary_clients[database] = primary
+        return primary
+    
+    def get_replica(self, database: str, max_connections: Optional[int] = None) -> redis.Redis:
+        """Get replica connection for reads."""
+        if database not in self.config.databases:
+            raise KeyError(f"Database '{database}' not in config")
+        
+        if database in self._replica_clients:
+            return self._replica_clients[database]
+        
+        kwargs = self.config.build_connection_kwargs(database, max_connections)
+        replica = self.sentinel.slave_for(database, **kwargs)
+        self._replica_clients[database] = replica
+        return replica
+    
+    def discover_primary(self, database: str) -> Tuple[str, int]:
+        """Get current primary address."""
+        return self.sentinel.discover_master(database)
+    
+    def discover_replicas(self, database: str) -> List[Tuple[str, int]]:
+        """Get all replica addresses."""
+        return self.sentinel.discover_slaves(database)
+    
+    def test_connection(self, database: str, use_replica: bool = False) -> bool:
+        """Test connection with PING."""
+        try:
+            client = self.get_replica(database) if use_replica else self.get_primary(database)
+            return client.ping()
+        except Exception:
+            return False
+    
+    def close(self):
+        """Close all connections."""
+        for client in self._primary_clients.values():
+            try:
+                client.close()
+            except Exception:
+                pass
+        for client in self._replica_clients.values():
+            try:
+                client.close()
+            except Exception:
+                pass
+        self._primary_clients.clear()
+        self._replica_clients.clear()
+        self._sentinel = None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+    
+    def __repr__(self) -> str:
+        return (
+            f"RedisSentinelClient("
+            f"sentinels={len(self.config.sentinel_hosts)}, "
+            f"databases={list(self.config.databases.keys())})"
+        )
+
+
+# Credential loading utilities
+
+def load_passwords_from_env(password_file: Path = Path("/etc/redis/certs/passwords.env")) -> Dict[str, str]:
+    """
+    Load Redis passwords from shell-style env file.
+    
+    Format: REDIS_DBNAME_PASSWORD=xxx
+    Returns: {"dbname": "xxx"}
+    """
+    if not password_file.exists():
+        raise FileNotFoundError(
+            f"Password file not found: {password_file}. "
+            "Deploy credentials via Ansible first."
+        )
+    
+    passwords = {}
+    with open(password_file) as f:
+        for line in f:
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, value = line.split("=", 1)
+                if key.startswith("REDIS_") and key.endswith("_PASSWORD"):
+                    db_name = key[6:-9].lower().replace("_", "-")
+                    passwords[db_name] = value.strip('"').strip("'")
+    return passwords
+
+
+def load_sentinel_hosts_from_env(env_var: str = "REDIS_SENTINEL_HOSTS") -> List[Tuple[str, int]]:
+    """
+    Load Sentinel hosts from environment variable.
+    
+    Format: host1:26379,host2:26379,host3:26379
+    Returns: [("host1", 26379), ("host2", 26379), ("host3", 26379)]
+    """
+    hosts_str = os.environ.get(env_var)
+    if not hosts_str:
+        raise ValueError(
+            f"Environment variable {env_var} not set. "
+            "Set it to: host1:26379,host2:26379,host3:26379"
+        )
+    
+    hosts = []
+    for entry in hosts_str.split(","):
+        entry = entry.strip()
+        if ":" not in entry:
+            raise ValueError(f"Invalid format '{entry}'. Expected 'host:port'")
+        host, port_str = entry.rsplit(":", 1)
+        try:
+            port = int(port_str)
+        except ValueError:
+            raise ValueError(f"Invalid port '{port_str}' for host '{host}'")
+        hosts.append((host, port))
+    
+    if not hosts:
+        raise ValueError(f"No hosts found in {env_var}")
+    
+    return hosts

grass_redis-0.1.0/src/grass_redis.egg-info/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: grass-redis
+Version: 0.1.0
+Summary: Redis Sentinel client with mandatory mutual TLS for high-availability Redis clusters
+Author: Alex
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: redis>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# grass-redis
+
+Redis Sentinel client with mandatory mutual TLS.
+
+## Features
+
+- Automatic failover via Sentinel
+- Connection pooling and caching
+- Read replicas for load distribution
+- Mandatory TLS with client certificates
+
+## Installation
+
+```bash
+pip install -e libs/python/grass-redis
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from grass_redis import (
+    RedisSentinelClient,
+    SentinelConfig,
+    load_passwords_from_env,
+    load_sentinel_hosts_from_env,
+)
+
+# Load from environment (never hardcode)
+sentinel_hosts = load_sentinel_hosts_from_env()  # $REDIS_SENTINEL_HOSTS
+passwords = load_passwords_from_env()            # /etc/redis/certs/passwords.env
+
+config = SentinelConfig(
+    sentinel_hosts=sentinel_hosts,
+    databases=passwords,
+    certs_dir=Path("/etc/redis/certs"),
+)
+
+with RedisSentinelClient(config) as client:
+    primary = client.get_primary("db1")
+    primary.set("key", "value")
+    
+    replica = client.get_replica("db1")
+    value = replica.get("key")
+```
+
+## Configuration
+
+**Environment (optional):**
+```bash
+export REDIS_SENTINEL_HOSTS="host1:26379,host2:26379,host3:26379"
+```
+
+**Deploy certs via Ansible to `/etc/redis/certs/`:**
+- `client.crt` - Client certificate (644)
+- `client.key` - Private key (600)
+- `ca.crt` - CA certificate (644)
+- `passwords.env` - Passwords (600)
+
+**`passwords.env` format:**
+```bash
+REDIS_SCRAPER_DB1_PASSWORD=xxx
+REDIS_SCRAPER_DB2_PASSWORD=yyy
+```
+
+Names are converted: `REDIS_SCRAPER_DB1_PASSWORD` → database `scraper-db1`
+
+## API
+
+**SentinelConfig:**
+- `sentinel_hosts` - List[(host, port)]
+- `databases` - Dict[db_name, password]
+- `certs_dir` - Path (default: /etc/redis/certs)
+
+**RedisSentinelClient:**
+- `get_primary(db)` - Connection for writes
+- `get_replica(db)` - Connection for reads
+- `discover_primary(db)` - Get current primary address
+- `test_connection(db)` - PING test
+
+See `grass-platform/reference_implementation/python/redis/` for examples.

grass_redis-0.1.0/src/grass_redis.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/grass_redis/__init__.py
+src/grass_redis/client.py
+src/grass_redis.egg-info/PKG-INFO
+src/grass_redis.egg-info/SOURCES.txt
+src/grass_redis.egg-info/dependency_links.txt
+src/grass_redis.egg-info/requires.txt
+src/grass_redis.egg-info/top_level.txt

grass_redis-0.1.0/src/grass_redis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

grass_redis-0.1.0/src/grass_redis.egg-info/requires.txt

@@ -0,0 +1,4 @@
+redis>=5.0.0
+
+[dev]
+pytest>=7.0

grass_redis-0.1.0/src/grass_redis.egg-info/top_level.txt

@@ -0,0 +1 @@
+grass_redis