smartinno 1.0.0__py3-none-any.whl

redis_sdk/__init__.py

@@ -0,0 +1,15 @@
+from .factory import RedisClientFactory
+from .config import Architecture, UseCase, RedisConfig
+from .clients.base import CircuitBreaker, CircuitState
+from .communication_service import CommunicationService, communication_service
+
+__all__ = [
+    "RedisClientFactory",
+    "Architecture",
+    "UseCase",
+    "RedisConfig",
+    "CircuitBreaker",
+    "CircuitState",
+    "CommunicationService",
+    "communication_service",
+]

redis_sdk/clients/base.py

@@ -0,0 +1,405 @@
+import time
+import json
+import logging
+import uuid
+from datetime import datetime
+import functools
+from enum import Enum
+from typing import Any, List
+from redis_sdk.interfaces import IRedisClient
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    CLOSED = "closed"       # Normal operation — requests pass through
+    OPEN = "open"           # Failing — all requests are rejected immediately
+    HALF_OPEN = "half_open" # Recovery probe — one request allowed to test
+
+
+class CircuitBreaker:
+    """
+    Built-in circuit breaker for Redis operations.
+
+    Tracks consecutive failures. When the failure threshold is exceeded the circuit
+    opens and all subsequent calls are rejected immediately for `recovery_timeout`
+    seconds. After that window a single probe request is allowed through; if it
+    succeeds the circuit closes again, otherwise it re-opens.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        name: str = "redis",
+    ):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.name = name
+
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time: float = 0.0
+
+    @property
+    def state(self) -> CircuitState:
+        if self._state == CircuitState.OPEN:
+            # Check if enough time has passed to move to HALF_OPEN
+            if time.monotonic() - self._last_failure_time >= self.recovery_timeout:
+                self._state = CircuitState.HALF_OPEN
+                logger.info(
+                    f"Circuit breaker [{self.name}] transitioning OPEN -> HALF_OPEN"
+                )
+        return self._state
+
+    def record_success(self) -> None:
+        self._failure_count = 0
+        if self._state != CircuitState.CLOSED:
+            logger.info(f"Circuit breaker [{self.name}] closing (recovered)")
+        self._state = CircuitState.CLOSED
+
+    def record_failure(self) -> None:
+        self._failure_count += 1
+        self._last_failure_time = time.monotonic()
+        if self._failure_count >= self.failure_threshold:
+            self._state = CircuitState.OPEN
+            logger.warning(
+                f"Circuit breaker [{self.name}] OPEN after "
+                f"{self._failure_count} consecutive failures"
+            )
+
+    def allow_request(self) -> bool:
+        current = self.state
+        if current == CircuitState.CLOSED:
+            return True
+        if current == CircuitState.HALF_OPEN:
+            return True  # Allow one probe
+        return False
+
+
+def _circuit_protected(method):
+    """Decorator that wraps a Redis command with circuit breaker logic."""
+
+    @functools.wraps(method)
+    def wrapper(self, *args, **kwargs):
+        if not self._circuit_breaker.allow_request():
+            raise ConnectionError(
+                f"Circuit breaker [{self._circuit_breaker.name}] is OPEN — "
+                f"request rejected. Will retry after "
+                f"{self._circuit_breaker.recovery_timeout}s."
+            )
+        try:
+            result = method(self, *args, **kwargs)
+            self._circuit_breaker.record_success()
+            return result
+        except Exception:
+            self._circuit_breaker.record_failure()
+            raise
+
+    return wrapper
+
+
+class BaseRedisAdapter(IRedisClient):
+    """
+    Base implementation that wraps standard redis commands with an integrated
+    circuit breaker.  Requires self.client to be initialized by subclasses.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        breaker_name: str = "redis",
+        service_name: str = "safari_pro",
+    ):
+        self.client = None
+        self.service_name = service_name
+        self._circuit_breaker = CircuitBreaker(
+            failure_threshold=failure_threshold,
+            recovery_timeout=recovery_timeout,
+            name=breaker_name,
+        )
+
+    # --- Data Standardization Utilities ---
+
+    def _format_key(self, key: str, action: str = "data") -> str:
+        """Enforces a standardized key naming convention: {service}:{action}:{key}"""
+        if not isinstance(key, str):
+            return key
+        if key.startswith(f"{self.service_name}:"):
+            return key
+        return f"{self.service_name}:{action}:{key}"
+
+    def _wrap_payload(self, payload: Any, event: str = "update", type_action: str = "cache") -> str:
+        """Wraps a payload into a standardized JSON envelope."""
+        data = {
+            "request_id": str(uuid.uuid4()),
+            "event": event,
+            "type": type_action,
+            "service": self.service_name,
+            "payload": payload,
+            "timestamp": datetime.utcnow().isoformat()
+        }
+        return json.dumps(data)
+
+    def _unwrap_payload(self, data: Any) -> Any:
+        """Unwraps a standardized JSON envelope, returning the original payload."""
+        if data is None:
+            return None
+            
+        data_str = data
+        if isinstance(data, bytes):
+            try:
+                data_str = data.decode('utf-8')
+            except UnicodeDecodeError:
+                return data
+
+        if not isinstance(data_str, str):
+            return data
+
+        try:
+            obj = json.loads(data_str)
+            if isinstance(obj, dict) and "payload" in obj and "service" in obj:
+                return obj["payload"]
+        except json.JSONDecodeError:
+            pass
+            
+        return data
+
+    # --- Explicitly wrapped commands (circuit-protected) ---
+
+    def _apply_ttl(self, key: str, ttl: int = None):
+        """Helper to apply the TTL to collections if explicitly requested."""
+        if ttl is not None:
+            try:
+                self.client.expire(key, ttl)
+            except Exception as e:
+                logger.warning(f"Failed to apply TTL to {key}: {e}")
+
+    @_circuit_protected
+    def set(self, key: str, value: Any, ex: int = None, **kwargs) -> bool:
+        if ex is None:
+            ex = 259200  # Default 3 days
+        f_key = self._format_key(key, "cache")
+        wrapped_val = self._wrap_payload(value, "set", "cache")
+        return self.client.set(f_key, wrapped_val, ex=ex, **kwargs)
+
+    @_circuit_protected
+    def get(self, key: str) -> Any:
+        f_key = self._format_key(key, "cache")
+        val = self.client.get(f_key)
+        return self._unwrap_payload(val)
+
+    @_circuit_protected
+    def mget(self, keys: List[str]) -> List[Any]:
+        f_keys = [self._format_key(k, "cache") for k in keys]
+        vals = self.client.mget(f_keys)
+        return [self._unwrap_payload(v) for v in vals]
+
+    @_circuit_protected
+    def publish(self, channel: str, message: Any) -> int:
+        f_channel = self._format_key(channel, "pubsub")
+        wrapped_msg = self._wrap_payload(message, "publish", "pubsub")
+        return self.client.publish(f_channel, wrapped_msg)
+
+    @_circuit_protected
+    def pipeline(self, transaction: bool = True) -> Any:
+        # Pipeline requires special handling at the caller level to wrap/unwrap
+        # since it queues commands. For now we return the native pipeline.
+        return self.client.pipeline(transaction=transaction)
+
+    @_circuit_protected
+    def xadd(self, name: str, fields: dict, maxlen: int = 10000, approximate: bool = True) -> str:
+        """
+        Adds a message to a stream. Ensures the stream is created if it does not exist.
+        Caps the stream length using maxlen (defaults to 10000) to prevent OOM.
+        """
+        f_name = self._format_key(name, "stream")
+        # For streams, wrap the entire fields dict into a payload field
+        wrapped_fields = {
+            "request_id": str(uuid.uuid4()),
+            "event": "update",
+            "type": "stream",
+            "service": self.service_name,
+            "payload": json.dumps(fields),
+            "timestamp": datetime.utcnow().isoformat()
+        }
+        res = self.client.xadd(
+            f_name, 
+            wrapped_fields, 
+            maxlen=maxlen, 
+            approximate=approximate, 
+            nomkstream=False  # Ensures stream is created if it doesn't exist
+        )
+        return res
+
+    @_circuit_protected
+    def xread(self, streams: dict, count: int = None, block: int = None) -> List:
+        f_streams = {self._format_key(k, "stream"): v for k, v in streams.items()}
+        result = self.client.xread(f_streams, count=count, block=block)
+        
+        # Unwrap
+        unwrapped = []
+        for stream_name, messages in result:
+            u_messages = []
+            for msg_id, fields in messages:
+                payload_val = fields.get(b"payload") or fields.get("payload")
+                if payload_val:
+                    try:
+                        u_fields = json.loads(payload_val)
+                    except Exception:
+                        u_fields = fields
+                else:
+                    u_fields = fields
+                u_messages.append((msg_id, u_fields))
+            
+            # Restore original stream name from input
+            original_stream_name = stream_name
+            prefix_b = f"{self.service_name}:stream:".encode('utf-8')
+            prefix_s = f"{self.service_name}:stream:"
+            if isinstance(stream_name, bytes) and stream_name.startswith(prefix_b):
+                original_stream_name = stream_name[len(prefix_b):].decode('utf-8')
+            elif isinstance(stream_name, str) and stream_name.startswith(prefix_s):
+                original_stream_name = stream_name[len(prefix_s):]
+            
+            unwrapped.append((original_stream_name, u_messages))
+        return unwrapped
+
+    # --- Hashes ---
+    @_circuit_protected
+    def hset(self, name: str, key: str = None, value: str = None, mapping: dict = None, ttl: int = None) -> int:
+        f_name = self._format_key(name, "hash")
+        
+        if mapping:
+            # Wrap all values in the mapping
+            wrapped_mapping = {k: self._wrap_payload(v, "hset", "hash") for k, v in mapping.items()}
+            res = self.client.hset(f_name, mapping=wrapped_mapping)
+        else:
+            wrapped_value = self._wrap_payload(value, "hset", "hash")
+            res = self.client.hset(f_name, key=key, value=wrapped_value)
+            
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def hget(self, name: str, key: str) -> Any:
+        f_name = self._format_key(name, "hash")
+        val = self.client.hget(f_name, key)
+        return self._unwrap_payload(val)
+
+    # --- Lists ---
+    @_circuit_protected
+    def lpush(self, name: str, *values, ttl: int = None) -> int:
+        f_name = self._format_key(name, "list")
+        wrapped_values = [self._wrap_payload(v, "lpush", "list") for v in values]
+        res = self.client.lpush(f_name, *wrapped_values)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def rpop(self, name: str) -> Any:
+        f_name = self._format_key(name, "list")
+        val = self.client.rpop(f_name)
+        return self._unwrap_payload(val)
+
+    # --- Sets ---
+    @_circuit_protected
+    def sadd(self, name: str, *values, ttl: int = None) -> int:
+        f_name = self._format_key(name, "set")
+        wrapped_values = [self._wrap_payload(v, "sadd", "set") for v in values]
+        res = self.client.sadd(f_name, *wrapped_values)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def smembers(self, name: str) -> set:
+        f_name = self._format_key(name, "set")
+        members = self.client.smembers(f_name)
+        return {self._unwrap_payload(m) for m in members}
+
+    # --- Sorted Sets ---
+    @_circuit_protected
+    def zadd(self, name: str, mapping: dict, ttl: int = None) -> int:
+        f_name = self._format_key(name, "zset")
+        # mapping is {member: score}
+        wrapped_mapping = {self._wrap_payload(k, "zadd", "zset"): v for k, v in mapping.items()}
+        res = self.client.zadd(f_name, wrapped_mapping)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def zrange(self, name: str, start: int, end: int, desc: bool = False, withscores: bool = False) -> List:
+        f_name = self._format_key(name, "zset")
+        res = self.client.zrange(f_name, start, end, desc=desc, withscores=withscores)
+        if withscores:
+            return [(self._unwrap_payload(member), score) for member, score in res]
+        return [self._unwrap_payload(member) for member in res]
+
+    # --- Geospatial ---
+    @_circuit_protected
+    def geoadd(self, name: str, values: tuple, ttl: int = None) -> int:
+        f_name = self._format_key(name, "geo")
+        # values is typically (longitude, latitude, member)
+        # We will format the key but NOT wrap the member to preserve geo exactness
+        res = self.client.geoadd(f_name, values)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def geosearch(self, name: str, longitude: float, latitude: float, radius: float, unit: str = 'km') -> List:
+        f_name = self._format_key(name, "geo")
+        return self.client.geosearch(f_name, longitude=longitude, latitude=latitude, radius=radius, unit=unit)
+
+    # --- Bitmaps & HyperLogLog ---
+    @_circuit_protected
+    def setbit(self, name: str, offset: int, value: int, ttl: int = None) -> int:
+        f_name = self._format_key(name, "bitmap")
+        res = self.client.setbit(f_name, offset, value)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def pfadd(self, name: str, *values, ttl: int = None) -> int:
+        f_name = self._format_key(name, "hll")
+        wrapped_values = [self._wrap_payload(v, "pfadd", "hll") for v in values]
+        res = self.client.pfadd(f_name, *wrapped_values)
+        self._apply_ttl(f_name, ttl)
+        return res
+
+    @_circuit_protected
+    def close(self) -> None:
+        self.client.close()
+
+    # --- Health / Status helpers ---
+
+    def get_circuit_state(self) -> str:
+        """Return the current circuit breaker state as a string."""
+        return self._circuit_breaker.state.value
+
+    def __getattr__(self, item):
+        """
+        Proxy any unknown method calls to the underlying Redis client.
+        This allows the adapter to seamlessly support all native Redis commands
+        (like hset, publish, expire, etc.) without having to explicitly wrap them.
+        Proxied calls are also circuit-breaker protected.
+        """
+        if hasattr(self, 'client') and self.client is not None and hasattr(self.client, item):
+            attr = getattr(self.client, item)
+            if callable(attr):
+                @functools.wraps(attr)
+                def _protected_proxy(*args, **kwargs):
+                    if not self._circuit_breaker.allow_request():
+                        raise ConnectionError(
+                            f"Circuit breaker [{self._circuit_breaker.name}] is OPEN — "
+                            f"request rejected."
+                        )
+                    try:
+                        result = attr(*args, **kwargs)
+                        self._circuit_breaker.record_success()
+                        return result
+                    except Exception:
+                        self._circuit_breaker.record_failure()
+                        raise
+                return _protected_proxy
+            return attr
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{item}'")

redis_sdk/clients/cluster.py

@@ -0,0 +1,65 @@
+from redis.cluster import RedisCluster, ClusterNode
+from redis.backoff import ExponentialBackoff
+from redis.retry import Retry
+from redis_sdk.clients.base import BaseRedisAdapter
+from redis_sdk.config import RedisConfig
+
+class ClusterClientAdapter(BaseRedisAdapter):
+    """
+    Adapter for Native Redis Cluster Architecture.
+    """
+    def __init__(self, config: RedisConfig):
+        super().__init__(breaker_name="cluster", service_name=config.service_name)
+        
+        nodes = []
+        if config.startup_nodes:
+            nodes = [ClusterNode(host=n['host'], port=n['port']) for n in config.startup_nodes]
+        else:
+            nodes = [ClusterNode(host=config.host, port=config.port)]
+
+        # Transparently remap internal Docker hostnames to Windows localhost with mapped ports
+        def remap_host_port(host, port):
+            node_map = {
+                'redis-node-1': ('127.0.0.1', 7001),
+                'redis-node-2': ('127.0.0.1', 7002),
+                'redis-node-3': ('127.0.0.1', 7003),
+                'redis-node-4': ('127.0.0.1', 7004),
+                'redis-node-5': ('127.0.0.1', 7005),
+                'redis-node-6': ('127.0.0.1', 7006),
+                'redis-cluster-node-1': ('127.0.0.1', 7001),
+                'redis-cluster-node-2': ('127.0.0.1', 7002),
+                'redis-cluster-node-3': ('127.0.0.1', 7003),
+                'redis-cluster-node-4': ('127.0.0.1', 7004),
+                'redis-cluster-node-5': ('127.0.0.1', 7005),
+                'redis-cluster-node-6': ('127.0.0.1', 7006),
+            }
+            return node_map.get(host, (host, port))
+
+        retry_strategy = None
+        if config.retry_backoff:
+            retry_strategy = Retry(
+                ExponentialBackoff(cap=config.retry_backoff_max, base=config.retry_backoff_min),
+                config.retry_backoff_retries
+            )
+
+        self.client = RedisCluster(
+            startup_nodes=nodes,
+            password=config.password,
+            decode_responses=True,
+            host_port_remap=remap_host_port,
+            ssl=config.ssl,
+            ssl_cert_reqs=config.ssl_cert_reqs if config.ssl else None,
+            max_connections=config.max_connections,
+            socket_timeout=config.socket_timeout,
+            socket_connect_timeout=config.socket_connect_timeout,
+            socket_keepalive=config.socket_keepalive,
+            health_check_interval=config.health_check_interval,
+            retry_on_timeout=config.retry_on_timeout,
+            retry=retry_strategy
+        )
+
+    def pipeline(self, transaction: bool = False):
+        """
+        Native Cluster supports pipelines, but cross-slot transactions are complex.
+        """
+        return self.client.pipeline(transaction=transaction)

redis_sdk/clients/hybrid.py

@@ -0,0 +1,51 @@
+import redis
+from redis.backoff import ExponentialBackoff
+from redis.retry import Retry
+from redis_sdk.clients.base import BaseRedisAdapter
+from redis_sdk.config import RedisConfig
+
+class HybridClientAdapter(BaseRedisAdapter):
+    """
+    Adapter for Hybrid (Predixy Proxy + Cluster) Architecture.
+    Acts as a standard Redis client, but overrides pipeline behavior.
+    """
+    def __init__(self, config: RedisConfig):
+        super().__init__(breaker_name="hybrid", service_name=config.service_name)
+        
+        retry_strategy = None
+        if config.retry_backoff:
+            retry_strategy = Retry(
+                ExponentialBackoff(cap=config.retry_backoff_max, base=config.retry_backoff_min),
+                config.retry_backoff_retries
+            )
+
+        self.client = redis.Redis(
+            host=config.host,
+            port=config.port,
+            password=config.password,
+            decode_responses=True,
+            protocol=2,  # Predixy operates reliably on RESP2
+            ssl=config.ssl,
+            ssl_cert_reqs=config.ssl_cert_reqs if config.ssl else None,
+            max_connections=config.max_connections,
+            socket_timeout=config.socket_timeout,
+            socket_connect_timeout=config.socket_connect_timeout,
+            socket_keepalive=config.socket_keepalive,
+            health_check_interval=config.health_check_interval,
+            retry_on_timeout=config.retry_on_timeout,
+            retry=retry_strategy
+        )
+
+    def pipeline(self, transaction: bool = False):
+        """
+        Predixy Proxy DOES NOT support MULTI/EXEC transactions efficiently across a cluster via python pipelines.
+        We MUST force transaction=False to ensure Predixy routes pipelines sequentially based on hash tags.
+        """
+        original_pipeline = self.client.pipeline
+
+        def predixy_pipeline(transaction=False, shard_hint=None):
+            if transaction:
+                print("Notice: Hybrid Predixy Proxy does not support transactions in pipelines. Forcing transaction=False.")
+            return original_pipeline(transaction=False, shard_hint=shard_hint)
+        
+        return predixy_pipeline(transaction=transaction)

redis_sdk/clients/sentinel.py

@@ -0,0 +1,59 @@
+from redis.sentinel import Sentinel
+from redis.backoff import ExponentialBackoff
+from redis.retry import Retry
+from redis_sdk.clients.base import BaseRedisAdapter
+from redis_sdk.config import RedisConfig
+
+class SentinelClientAdapter(BaseRedisAdapter):
+    """
+    Adapter for Redis Sentinel Architecture.
+    """
+    def __init__(self, config: RedisConfig):
+        super().__init__(breaker_name="sentinel", service_name=config.service_name)
+        
+        retry_strategy = None
+        if config.retry_backoff:
+            retry_strategy = Retry(
+                ExponentialBackoff(cap=config.retry_backoff_max, base=config.retry_backoff_min),
+                config.retry_backoff_retries
+            )
+
+        if config.sentinel_nodes:
+            # Traditional Sentinel connection (connects to individuals to find master)
+            master_name = config.sentinel_master_name or 'mymaster'
+            self.sentinel = Sentinel(
+                config.sentinel_nodes, 
+                socket_timeout=config.socket_timeout,
+                password=config.password,
+                sentinel_kwargs={'password': config.password}
+            )
+            self.client = self.sentinel.master_for(
+                master_name, 
+                decode_responses=True,
+                ssl=config.ssl,
+                ssl_cert_reqs=config.ssl_cert_reqs if config.ssl else None,
+                max_connections=config.max_connections,
+                socket_connect_timeout=config.socket_connect_timeout,
+                socket_keepalive=config.socket_keepalive,
+                health_check_interval=config.health_check_interval,
+                retry_on_timeout=config.retry_on_timeout,
+                retry=retry_strategy
+            )
+        else:
+            # Connect via HAProxy Load Balancer directly
+            import redis
+            self.client = redis.Redis(
+                host=config.host,
+                port=config.port,
+                password=config.password,
+                decode_responses=True,
+                ssl=config.ssl,
+                ssl_cert_reqs=config.ssl_cert_reqs if config.ssl else None,
+                max_connections=config.max_connections,
+                socket_timeout=config.socket_timeout,
+                socket_connect_timeout=config.socket_connect_timeout,
+                socket_keepalive=config.socket_keepalive,
+                health_check_interval=config.health_check_interval,
+                retry_on_timeout=config.retry_on_timeout,
+                retry=retry_strategy
+            )