reach_commons 0.18.35__tar.gz → 0.18.37__tar.gz

{reach_commons-0.18.35 → reach_commons-0.18.37}/PKG-INFO

@@ -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 → reach_commons-0.18.37}/README.md

@@ -1,26 +1,26 @@
-# reach_commons
-
-## Description
-
-`reach_commons` is a Python library that provides various classes and utilities to assist developers in their projects. This library aims to simplify and streamline processes by offering reusable components that can be easily integrated into various Python applications.
-
-## Installation
-
-Install `reach_commons` using pip:
-
-```bash
-pip install reach_commons
-
-from reach_commons.api_client_v2 import ReachApiGatewayV2
-
-api_gateway = ReachApiGatewayV2(
-                        base_url=os.environ["api_gateway_v2_endpoint"],
-                        access_token=os.environ["event_processor_token"],
-                    )
-response = api_gateway.stripe_create_booking_guarantee(
-                        business_id=business_id, booking_price=booking_price
-                    )
-{
-            "statusCode": stripe_customer.status_code,
-            "body": json.dumps(response.json()),
+# reach_commons
+
+## Description
+
+`reach_commons` is a Python library that provides various classes and utilities to assist developers in their projects. This library aims to simplify and streamline processes by offering reusable components that can be easily integrated into various Python applications.
+
+## Installation
+
+Install `reach_commons` using pip:
+
+```bash
+pip install reach_commons
+
+from reach_commons.api_client_v2 import ReachApiGatewayV2
+
+api_gateway = ReachApiGatewayV2(
+                        base_url=os.environ["api_gateway_v2_endpoint"],
+                        access_token=os.environ["event_processor_token"],
+                    )
+response = api_gateway.stripe_create_booking_guarantee(
+                        business_id=business_id, booking_price=booking_price
+                    )
+{
+            "statusCode": stripe_customer.status_code,
+            "body": json.dumps(response.json()),
         }

{reach_commons-0.18.35 → reach_commons-0.18.37}/pyproject.toml

@@ -1,41 +1,41 @@
-# isort .; black .; poetry build; poetry publish
-[tool.poetry]
-name = "reach_commons"
-version = "0.18.35"
-description = "Reach Commons is a versatile utility library designed to streamline and enhance development workflows within the Reach ecosystem."
-authors = ["Engineering <engineering@getreach.ai>"]
-license = "MIT"
-readme = "README.md"
-
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-
-[tool.poetry.dependencies]
-python = "^3.8"
-#pip = "23.3.1"
-setuptools = "70.0.0"
-wheel = "0.41.2"
-twine = "4.0.2"
-curlify = "3.0.0"
-pydantic = ">=2.9.2"
-fastapi = ">=0.115.5"
-
-
-[tool.poetry.dev-dependencies]
-black = "23.10.0"
-isort = "5.12.0"
-requests = "2.31.0"
-boto3 = "1.28.68"
-botocore = "^1.31.68"
-redis = "^4.1.3"
-pydantic-settings = "2.3.1"
-jsonschema = "4.23.0"
-motor = "3.6.0"
-pymongo = "4.9.2"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
+# isort .; black .; poetry build; poetry publish
+[tool.poetry]
+name = "reach_commons"
+version = "0.18.37"
+description = "Reach Commons is a versatile utility library designed to streamline and enhance development workflows within the Reach ecosystem."
+authors = ["Engineering <engineering@getreach.ai>"]
+license = "MIT"
+readme = "README.md"
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+#pip = "23.3.1"
+setuptools = "70.0.0"
+wheel = "0.41.2"
+twine = "4.0.2"
+curlify = "3.0.0"
+pydantic = ">=2.9.2"
+fastapi = ">=0.115.5"
+
+
+[tool.poetry.dev-dependencies]
+black = "23.10.0"
+isort = "5.12.0"
+requests = "2.31.0"
+boto3 = "1.28.68"
+botocore = "^1.31.68"
+redis = "^4.1.3"
+pydantic-settings = "2.3.1"
+jsonschema = "4.23.0"
+motor = "3.6.0"
+pymongo = "4.9.2"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"

{reach_commons-0.18.35 → reach_commons-0.18.37}/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-0.18.37/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-0.18.35 → reach_commons-0.18.37}/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)