reach_commons 0.18.35__py3-none-any.whl → 0.18.37__py3-none-any.whl

reach_commons/app_logging/logging_utils.py

@@ -1,17 +1,17 @@
-import logging
-import os
-
-
-def init_logger(name: str):
-    logging.basicConfig(
-        level=getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO),
-        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-        force=True,
-    )
-    for noisy in ("botocore", "boto3", "urllib3"):
-        logging.getLogger(noisy).setLevel(logging.WARNING)
-    return logging.getLogger(name)
-
-
-def log_with_event(level_fn, msg, event):
-    level_fn(f"{msg} | event={event}")
+import logging
+import os
+
+
+def init_logger(name: str):
+    logging.basicConfig(
+        level=getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        force=True,
+    )
+    for noisy in ("botocore", "boto3", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+    return logging.getLogger(name)
+
+
+def log_with_event(level_fn, msg, event):
+    level_fn(f"{msg} | event={event}")

reach_commons/reach_aws/reach_rate_limiter.py

@@ -0,0 +1,228 @@
+import random
+import time
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from reach_commons.redis_manager import RedisManager
+
+# Atomic fixed-window limiter (safe under high concurrency).
+_LUA_WINDOW_LIMITER = """
+-- KEYS[1] = window_counter_key
+-- ARGV[1] = tokens_to_consume
+-- ARGV[2] = ttl_seconds
+-- ARGV[3] = limit_per_window
+
+local tokens = tonumber(ARGV[1])
+local ttl = tonumber(ARGV[2])
+local limit = tonumber(ARGV[3])
+
+local current = redis.call('INCRBY', KEYS[1], tokens)
+
+-- If this is the first increment for this window, set TTL
+if current == tokens then
+  redis.call('EXPIRE', KEYS[1], ttl)
+end
+
+if current <= limit then
+  return 1
+else
+  return 0
+end
+"""
+
+
+@dataclass(frozen=True)
+class AcquireResult:
+    allowed: bool
+    retry_after_seconds: int
+
+
+class ReachRateLimiter:
+    """
+    ReachRateLimiter (fixed-window limiter) backed by Redis.
+
+    Configurable live via Redis (no redeploy needed).
+    Atomic under heavy concurrency (Lua runs inside Redis).
+    Returns retry_after_seconds (use it to ChangeMessageVisibility / Delay).
+
+    Redis keys used:
+      - Config hash:
+          {key_prefix}:cfg:{bucket_key}
+        Fields (all optional):
+          - limit_per_window (int)
+          - interval_seconds (int)
+          - jitter_seconds (int)
+
+      - Per-window counter:
+          {key_prefix}:{bucket_key}:{window_start}
+
+    Suggested defaults:
+      interval_seconds=2
+      limit_per_window=2000 (=> ~1000/s)
+      jitter_seconds=2 or 3
+    """
+
+    def __init__(
+        self,
+        redis_manager: RedisManager,
+        bucket_key: str,
+        key_prefix: str = "rate_limiter",
+        default_limit_per_window: int = 2000,
+        default_interval_seconds: int = 2,
+        default_jitter_seconds: Optional[int] = None,
+        # Cache config in-memory per Lambda container (to reduce Redis reads):
+        config_cache_seconds: int = 2,
+        # if Redis is down, deny by default to avoid stampede downstream
+        deny_on_redis_error: bool = True,
+    ):
+        self.redis = redis_manager
+        self.bucket_key = bucket_key
+        self.key_prefix = key_prefix
+
+        self.default_limit = int(default_limit_per_window)
+        self.default_interval = int(default_interval_seconds)
+        self.default_jitter = (
+            int(default_jitter_seconds)
+            if default_jitter_seconds is not None
+            else int(default_interval_seconds)
+        )
+
+        self.config_cache_seconds = max(0, int(config_cache_seconds))
+        self.deny_on_redis_error = bool(deny_on_redis_error)
+
+        self._lua = _LUA_WINDOW_LIMITER
+
+        # Per-container cache (each Lambda container caches for a short time)
+        self._cached_cfg: Optional[Tuple[int, int, int]] = None
+        self._cached_cfg_ts: float = 0.0
+
+    # -------------------------
+    # Redis key helpers
+    # -------------------------
+    def _cfg_key(self) -> str:
+        return f"{self.key_prefix}:cfg:{self.bucket_key}"
+
+    def _counter_key(self, window_start: int) -> str:
+        return f"{self.key_prefix}:{self.bucket_key}:{window_start}"
+
+    # -------------------------
+    # Time helpers
+    # -------------------------
+    def _now(self) -> float:
+        return time.time()
+
+    def _window_start(self, now: float, interval_seconds: int) -> int:
+        return int(now // interval_seconds) * interval_seconds
+
+    # -------------------------
+    # Config loading (from Redis hash)
+    # -------------------------
+    @staticmethod
+    def _parse_int(value, fallback: int) -> int:
+        try:
+            if value is None:
+                return fallback
+            if isinstance(value, (bytes, bytearray)):
+                value = value.decode("utf-8", errors="ignore")
+            return int(value)
+        except Exception:
+            return fallback
+
+    def _load_config(self) -> Tuple[int, int, int]:
+        """
+        Loads config from Redis hash:
+          limit_per_window, interval_seconds, jitter_seconds
+
+        Uses short in-memory cache to avoid hammering Redis under high throughput.
+        """
+        now = self._now()
+
+        if (
+            self._cached_cfg is not None
+            and self.config_cache_seconds > 0
+            and (now - self._cached_cfg_ts) < self.config_cache_seconds
+        ):
+            return self._cached_cfg
+
+        limit = self.default_limit
+        interval = self.default_interval
+        jitter = self.default_jitter
+
+        try:
+            raw = self.redis.hgetall(self._cfg_key()) or {}
+
+            # raw typically has bytes keys/values
+            limit = self._parse_int(
+                raw.get(b"limit_per_window") or raw.get("limit_per_window"), limit
+            )
+            interval = self._parse_int(
+                raw.get(b"interval_seconds") or raw.get("interval_seconds"), interval
+            )
+            jitter = self._parse_int(
+                raw.get(b"jitter_seconds") or raw.get("jitter_seconds"), jitter
+            )
+
+            # Guard rails
+            if limit <= 0:
+                limit = self.default_limit
+            if interval <= 0:
+                interval = self.default_interval
+            if jitter < 0:
+                jitter = 0
+
+        except Exception:
+            # Redis issue: keep defaults
+            limit = self.default_limit
+            interval = self.default_interval
+            jitter = self.default_jitter
+
+        cfg = (int(limit), int(interval), int(jitter))
+        self._cached_cfg = cfg
+        self._cached_cfg_ts = now
+        return cfg
+
+    # -------------------------
+    # Public API
+    # -------------------------
+    def acquire(self, tokens: int = 1) -> AcquireResult:
+        """
+        Attempt to acquire tokens (default 1).
+        If denied, returns retry_after_seconds.
+        """
+        tokens = int(tokens)
+        if tokens <= 0:
+            return AcquireResult(allowed=True, retry_after_seconds=0)
+
+        now = self._now()
+        limit, interval, jitter_max = self._load_config()
+
+        window_start = self._window_start(now, interval)
+        window_end = window_start + interval
+        counter_key = self._counter_key(window_start)
+
+        # TTL slightly larger than interval so old window keys expire
+        ttl_seconds = max(interval * 2, 5)
+
+        try:
+            allowed = self.redis.eval(
+                self._lua,
+                numkeys=1,
+                keys=[counter_key],
+                args=[str(tokens), str(ttl_seconds), str(limit)],
+            )
+        except Exception:
+            if self.deny_on_redis_error:
+                # safest for protecting downstream (Mongo/API)
+                retry_after = int(max(1.0, float(interval)))
+                return AcquireResult(allowed=False, retry_after_seconds=retry_after)
+            return AcquireResult(allowed=True, retry_after_seconds=0)
+
+        if allowed == 1:
+            return AcquireResult(allowed=True, retry_after_seconds=0)
+
+        # Denied: retry after next window + jitter to avoid waves
+        base = max(0.0, window_end - now)
+        jitter = random.uniform(0.0, float(jitter_max))
+        retry_after = int(max(1.0, base + jitter))
+
+        return AcquireResult(allowed=False, retry_after_seconds=retry_after)

reach_commons/redis_manager.py

@@ -80,3 +80,23 @@ class RedisManager:
             name=key, value="1", ex=expire_seconds, nx=True
         )
         return result is True
+
+    def incrby(self, key: str, amount: int = 1) -> int:
+        return int(self.redis_connection.incrby(key, amount))
+
+    def expire(self, key: str, seconds: int) -> bool:
+        return bool(self.redis_connection.expire(key, seconds))
+
+    def eval(self, script: str, numkeys: int, keys=None, args=None):
+        keys = keys or []
+        args = args or []
+        return self.redis_connection.eval(script, numkeys, *(keys + args))
+
+    def hgetall(self, key):
+        return self.redis_connection.hgetall(key)
+
+    def hget(self, key, field):
+        return self.redis_connection.hget(key, field)
+
+    def hset(self, key, field, value):
+        return self.redis_connection.hset(key, field, value)

{reach_commons-0.18.35.dist-info → reach_commons-0.18.37.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: reach_commons
-Version: 0.18.35
+Version: 0.18.37
 Summary: Reach Commons is a versatile utility library designed to streamline and enhance development workflows within the Reach ecosystem.
 License: MIT
 Author: Engineering
@@ -14,8 +14,6 @@ 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: Programming Language :: Python :: 3.14
 Requires-Dist: curlify (==3.0.0)
 Requires-Dist: fastapi (>=0.115.5)
 Requires-Dist: pydantic (>=2.9.2)

{reach_commons-0.18.35.dist-info → reach_commons-0.18.37.dist-info}/RECORD

@@ -1,12 +1,10 @@
-reach_commons/.DS_Store,sha256=M7WbC5LcTvuTEuj3k7z3tqzMSVGgu87auq6UOLoSv2M,6148
 reach_commons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 reach_commons/app_logging/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 reach_commons/app_logging/http_logger.py,sha256=mljQCdmsmtD2HsC_gsFwZAxPlAiLPYVirVrCjXFxitY,2541
 reach_commons/app_logging/log_deprecated_endpoints.py,sha256=yXs9Jh7V0_0cMnzwXV9WRgCdFXe_tybcFE1eQl2KNC4,2020
 reach_commons/app_logging/logger.py,sha256=Iq2XTl1zLgHDmVsTMdlFadcYJOqQNhBcFSscacKs_Xs,2295
 reach_commons/app_logging/logging_config.py,sha256=Y1JaZOoQBWgQjkOqYmeDRIm0p2eCOl3yTzgsgqyqm8I,1539
-reach_commons/app_logging/logging_utils.py,sha256=zeDRm3DugbuqMIDstTsVyH5xU_ZV-WAcCINxb6qYdJY,491
-reach_commons/clients/.DS_Store,sha256=1lFlJ5EFymdzGAUAaI30vcaaLHt3F1LwpG7xILf9jsM,6148
+reach_commons/app_logging/logging_utils.py,sha256=-QQ4l9CTYs-lCL-VNxGdWvPquRQtrnXWqzNfxOLO9ys,508
 reach_commons/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 reach_commons/clients/event_processor.py,sha256=KmYF0kuZxLmHQjJASXMr5jz2D_D3WNHB0c4QOlZo1_E,2024
 reach_commons/clients/hubspot.py,sha256=ntAzvwoaq78MkKaVoZ7geND-AafAzccNnJogfJDahVA,5497
@@ -23,13 +21,14 @@ reach_commons/reach_aws/dynamo_db.py,sha256=BL3QcKzx4uZic-Ui12tln_GMSKe297FdfyIz
 reach_commons/reach_aws/exceptions.py,sha256=x0RL5ktNtzxg0KykhEVWReBq_dEtciK6B2vMs_s4C9k,915
 reach_commons/reach_aws/firehose.py,sha256=1xFKLWMv3bNo3PPW5gtaL6NqzUDyVil6B768slj2wbY,5674
 reach_commons/reach_aws/kms.py,sha256=ZOfyJMQUgxJEojRoB7-aCxtATpNx1Ig522IUYH11NZ4,4678
+reach_commons/reach_aws/reach_rate_limiter.py,sha256=Z3gldy_EkkgVVl9rmc3t5xciccNPcRAiBY1stvr7YLw,7448
 reach_commons/reach_aws/s3.py,sha256=2MLlDNFx0SROJBpE_KjJefyrB7lMqTlrYuRhSZx4iKs,3945
 reach_commons/reach_aws/sqs.py,sha256=IKKWrd-qbhMMVYUvGbaq1ouVRdx-0u-SqwYaTcp0tWY,21645
 reach_commons/reach_base_model.py,sha256=vgdGDcZr3iXMmyRhmBhOf_LKWB_6QzT3r_Yiyo6OmEk,3009
-reach_commons/redis_manager.py,sha256=SgUtdtt0eV4bUwsWDankIa9Bjfgcm2DKcmVMQT6ptF0,2946
+reach_commons/redis_manager.py,sha256=yRed53ZKlbIb6rZnL53D1F_aB-xWT3nbeUP2cqYzhoc,3668
 reach_commons/sms_smart_encoding.py,sha256=92y0RmZ0l4ONHpC9qeO5KfViSNq64yE2rc7lhNDSZqE,1241
 reach_commons/utils.py,sha256=dMgKIGqTgoSItuBI8oz81gKtW3qi21Jkljv9leS_V88,8475
 reach_commons/validations.py,sha256=x_lkrtlrCAJC_f7mZb19JjfKFbYlPFv-P84K_lbZyYs,1056
-reach_commons-0.18.35.dist-info/METADATA,sha256=gD0kZHrRs6H0VzzuUYrxs4EFOju-ubt9hdnB4AdLMLM,1965
-reach_commons-0.18.35.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-reach_commons-0.18.35.dist-info/RECORD,,
+reach_commons-0.18.37.dist-info/METADATA,sha256=k2xckMxe857fXHo3p-lUKT0eWFwHmXTumKIqcI5M2GM,1863
+reach_commons-0.18.37.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+reach_commons-0.18.37.dist-info/RECORD,,

{reach_commons-0.18.35.dist-info → reach_commons-0.18.37.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.2.1
+Generator: poetry-core 1.8.1
 Root-Is-Purelib: true
 Tag: py3-none-any