pace-python 1.0.1__cp38-abi3-win_amd64.whl

pace_sdk/__init__.py

@@ -0,0 +1,20 @@
+# pace_sdk/__init__.py
+
+# 1. Export the Core Engine
+from .core import Pace
+
+# 2. Export the Types
+from .types import PaceConfig, ProtectionMode, Algorithm
+
+# 3. Export the Framework Helpers
+from .helpers import PaceFastAPI, pace_django
+
+# Define exactly what gets imported when someone uses `from pace_sdk import *`
+__all__ = [
+    "Pace",
+    "PaceConfig",
+    "ProtectionMode",
+    "Algorithm",
+    "PaceFastAPI",
+    "pace_django"
+]

pace_sdk/client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+import os
+from .pace_native import RustEngine
+from .logger import log_decision
+from .types import CheckResult, PaceConfig, CanonicalDecision, TrafficDecision, DecisionReason, Algorithm
+
+class Pace:
+    def __init__(self, config: PaceConfig):
+        self.config = config
+        self.log_mode = config.debug        
+        if os.environ.get("PACE_DEBUG") == "true":
+            print("[Pace] ⚡ Rust engine loaded")
+
+        debug_str = config.debug if isinstance(config.debug, str) else ("compact" if config.debug else None)
+        
+        self._native_engine = RustEngine(
+            config.algorithm.value,
+            config.mode.value,
+            float(config.capacity),
+            float(config.refill_rate),
+            config.api_key,
+            debug_str,
+            config.backend_url
+        )
+
+    def check(self, ip: str, route: str = "/", key: Optional[str] = None) -> CheckResult:
+        # Pass everything to Rust. No Python math, no locks, no state dicts!
+        res = self._native_engine.check(ip, route, key)
+        
+        dec_data = res.get("decision", {})
+        decision = CanonicalDecision(
+            decision=TrafficDecision(dec_data.get("decision", "allow")),
+            reason=DecisionReason(dec_data.get("reason", "within_limit")),
+            algorithm=Algorithm(dec_data.get("algorithm", "token_bucket")),
+            route=dec_data.get("route", route),
+            ip=ip,
+            key=key or ip,
+            remaining=dec_data.get("remaining"),
+            latency_ms=dec_data.get("latency_ms", 0),
+            mode=self.config.mode
+        )
+        
+        result = CheckResult(
+            allowed=res.get("allowed", True),
+            would_block=res.get("would_block", False),
+            reason=res.get("reason"),
+            decision=decision
+        )
+
+        log_decision(self.log_mode, decision)
+        return result
+
+    def check_detailed(self, ip: str, route: str = "/", key: Optional[str] = None) -> CheckResult:
+        return self.check(ip, route, key)
+
+    def check_with_key(self, key: str, ip: str, route: str = "/") -> CheckResult:
+        return self.check(ip, route, key)

pace_sdk/core.py

@@ -0,0 +1,62 @@
+# sdk-python/pace_sdk/core.py
+from __future__ import annotations
+import os
+import threading
+from typing import Optional
+from .pace_native import RustEngine
+from .logger import log_decision
+from .types import CheckResult, PaceConfig, CanonicalDecision, TrafficDecision, DecisionReason, Algorithm
+
+class Pace:
+    def __init__(self, config: PaceConfig):
+        self.config = config
+        self._lock = threading.Lock()
+        self.log_mode = config.debug        
+        if os.environ.get("PACE_DEBUG") == "true":
+            print("[Pace] ⚡ Rust engine loaded")
+
+        debug_str = config.debug if isinstance(config.debug, str) else ("compact" if config.debug else None)
+        
+        self._native_engine = RustEngine(
+            config.algorithm.value,
+            config.mode.value,
+            float(config.capacity),
+            float(config.refill_rate),
+            config.api_key,
+            debug_str,
+            config.backend_url
+        )
+
+    def check(self, ip: str, route: str = "/", key: Optional[str] = None) -> CheckResult:
+        with self._lock:
+            # Pass everything to Rust. No Python math, no locks, no state dicts!
+            res = self._native_engine.check(ip, route, key)
+        
+        dec_data = res.get("decision", {})
+        decision = CanonicalDecision(
+            decision=TrafficDecision(dec_data.get("decision", "allow")),
+            reason=DecisionReason(dec_data.get("reason", "within_limit")),
+            algorithm=Algorithm(dec_data.get("algorithm", "token_bucket")),
+            route=dec_data.get("route", route),
+            ip=ip,
+            key=key or ip,
+            remaining=dec_data.get("remaining"),
+            latency_ms=dec_data.get("latency_ms", 0),
+            mode=self.config.mode
+        )
+        
+        result = CheckResult(
+            allowed=res.get("allowed", True),
+            would_block=res.get("would_block", False),
+            reason=res.get("reason"),
+            decision=decision
+        )
+
+        log_decision(self.log_mode, decision)
+        return result
+
+    def check_detailed(self, ip: str, route: str = "/", key: Optional[str] = None) -> CheckResult:
+        return self.check(ip, route, key)
+
+    def check_with_key(self, key: str, ip: str, route: str = "/") -> CheckResult:
+        return self.check(ip, route, key)

pace_sdk/helpers.py

@@ -0,0 +1,32 @@
+# pace_sdk/helpers.py
+from typing import Callable
+from functools import wraps
+
+class PaceFastAPI:
+    def __init__(self, pace_engine):
+        self.pace = pace_engine
+
+    def limit(self, route: str = "/"):
+        from fastapi import Request, HTTPException
+        def _dependency(request: Request):
+            client_ip = request.client.host if request.client else "127.0.0.1"
+            result = self.pace.check(ip=client_ip, route=route)
+            if not result.allowed:
+                raise HTTPException(status_code=429, detail="Rate limit exceeded")
+        return _dependency
+
+def pace_django(pace_engine, route: str = "/"):
+    def decorator(view_func: Callable) -> Callable:
+        @wraps(view_func)
+        def _wrapped_view(request, *args, **kwargs):
+            from django.http import JsonResponse
+            
+            x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
+            client_ip = x_forwarded_for.split(',')[0].strip() if x_forwarded_for else request.META.get('REMOTE_ADDR', '127.0.0.1')
+                
+            result = pace_engine.check(ip=client_ip, route=route)
+            if not result.allowed:
+                return JsonResponse({"error": "Rate limit exceeded"}, status=429)
+            return view_func(request, *args, **kwargs)
+        return _wrapped_view
+    return decorator

pace_sdk/logger.py

@@ -0,0 +1,64 @@
+from typing import Union
+from .types import CanonicalDecision, TrafficDecision
+
+# Global Color Definitions
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+RESET = "\033[0m"
+
+def should_ignore_route(route: str) -> bool:
+    return route in {"/favicon.ico", "/health", "/api/health", "/healthz", "/ping", "/api/ping"} or route.startswith("/_next")
+
+def _format_duration_ms(ms: int) -> str:
+    if ms <= 0: return "0ms"
+    if ms % 3_600_000 == 0: return f"{ms // 3_600_000}h"
+    if ms % 60_000 == 0: return f"{ms // 60_000}m"
+    if ms % 1000 == 0: return f"{ms // 1000}s"
+    return f"{ms}ms"
+
+def log_decision(debug_mode: Union[bool, str], decision: CanonicalDecision) -> None:
+    if not debug_mode or should_ignore_route(decision.route):
+        return
+
+    # 1. COMPACT MODE
+    if debug_mode == "compact" or debug_mode is True:
+        if decision.decision == TrafficDecision.ALLOW:
+            headline = f"{GREEN}ALLOW{RESET}"
+        else:
+            headline = f"{RED}BLOCK{RESET}"
+            
+        parts = [f"[Pace] {headline}", f"route={decision.route}"]
+        if decision.remaining is not None: parts.append(f"remaining={decision.remaining}")
+        if decision.latency_ms is not None: parts.append(f"latency={decision.latency_ms}ms")
+        print(" ".join(parts))
+        return
+
+    # 2. PRETTY MODE
+    if debug_mode == "pretty":
+        if decision.decision == TrafficDecision.ALLOW:
+            print(f"{GREEN}[Pace] 🟢 ALLOWED{RESET}")
+            print(f"│ Route:     {decision.route}")
+            if decision.remaining is not None:
+                print(f"│ Remaining: {decision.remaining}")
+            if decision.latency_ms is not None:
+                print(f"│ Latency:   {decision.latency_ms}ms")
+            print(f"└────────────────────────────────────────")
+        else:
+            headline = "🔴 BLOCKED" if decision.decision == TrafficDecision.BLOCK else "🟡 WOULD BLOCK"
+            color = RED if decision.decision == TrafficDecision.BLOCK else YELLOW
+            
+            print(f"{color}[Pace] {headline}{RESET}")
+            print(f"│ Route:     {decision.route}")
+            print(f"│ IP:        {decision.ip or 'unknown'}")
+            print(f"│ Algorithm: {decision.algorithm.value}")
+            print(f"│ Reason:    {decision.reason.value}")
+            if decision.mode:
+                print(f"│ Mode:      {decision.mode.value}")
+            if decision.remaining is not None:
+                print(f"│ Remaining: {decision.remaining}")
+            if decision.refill_ms:
+                print(f"│ Refill:    {_format_duration_ms(decision.refill_ms)}")
+            if decision.latency_ms is not None:
+                print(f"│ Latency:   {decision.latency_ms}ms")
+            print(f"└────────────────────────────────────────")

pace_sdk/middleware.py

@@ -0,0 +1,49 @@
+from functools import wraps
+
+from .client import Pace
+from .types import PaceConfig
+
+
+def flask_middleware(pace: Pace):
+    """Flask decorator"""
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            from flask import jsonify, request
+
+            ip = request.headers.get("X-Forwarded-For", request.remote_addr)
+            identity = request.headers.get(pace.config.identity_header) if pace.config.identity_header else None
+            result = pace.check_with_key(identity or "", ip, request.path)
+            if not result.allowed:
+                return jsonify({"message": "Rate limit exceeded"}), 429
+            return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class FastAPIMiddleware:
+    """FastAPI middleware"""
+
+    def __init__(self, app, config: PaceConfig):
+        self.app = app
+        self.pace = Pace(config)
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            from starlette.requests import Request
+            from starlette.responses import JSONResponse
+
+            request = Request(scope, receive)
+            ip = request.headers.get(
+                "x-forwarded-for", request.client.host if request.client else "unknown"
+            )
+            identity = request.headers.get(self.pace.config.identity_header) if self.pace.config.identity_header else None
+            result = self.pace.check_with_key(identity or "", ip, request.url.path)
+            if not result.allowed:
+                response = JSONResponse({"message": "Rate limit exceeded"}, status_code=429)
+                await response(scope, receive, send)
+                return
+        await self.app(scope, receive, send)

pace_sdk/telemetry.py

@@ -0,0 +1,72 @@
+import threading
+import time
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+from typing import List
+
+import requests
+
+from .types import CanonicalTelemetryEvent
+
+
+class TelemetryQueue:
+    def __init__(self, api_key: str, backend_url: str, enabled: bool):
+        self.api_key = api_key
+        self.backend_url = backend_url
+        self.enabled = enabled
+        self.queue: List[CanonicalTelemetryEvent] = []
+        self.lock = threading.Lock()
+        self.MAX_SIZE = 10000
+        self.BATCH_SIZE = 500
+
+        if enabled:
+            t = threading.Thread(target=self._flush_loop, daemon=True)
+            t.start()
+
+    def push(self, event: CanonicalTelemetryEvent):
+        if not self.enabled:
+            return
+        with self.lock:
+            if len(self.queue) >= self.MAX_SIZE:
+                self.queue.pop(0)
+            self.queue.append(event)
+
+    def _flush_loop(self):
+        while True:
+            time.sleep(2)
+            self._flush()
+
+    def _flush(self):
+        with self.lock:
+            if not self.queue:
+                return
+            batch = self.queue[: self.BATCH_SIZE]
+            self.queue = self.queue[self.BATCH_SIZE :]
+
+        def encode(value):
+            if isinstance(value, Enum):
+                return value.value
+            if is_dataclass(value):
+                return {
+                    key: encode(inner)
+                    for key, inner in asdict(value).items()
+                    if inner is not None
+                }
+            if isinstance(value, list):
+                return [encode(item) for item in value]
+            if isinstance(value, dict):
+                return {
+                    key: encode(inner)
+                    for key, inner in value.items()
+                    if inner is not None
+                }
+            return value
+
+        try:
+            requests.post(
+                f"{self.backend_url}/api/ingest/request",
+                json={"events": [encode(event) for event in batch]},
+                timeout=5,
+            )
+        except Exception:
+            pass

pace_sdk/types.py

@@ -0,0 +1,97 @@
+from dataclasses import dataclass, field
+from typing import Optional, Union
+from enum import Enum
+
+class ProtectionMode(str, Enum):
+    ACTIVE = "active"
+    SHADOW = "shadow"
+    DISABLED = "disabled"
+
+class Algorithm(str, Enum):
+    TOKEN_BUCKET = "token_bucket"
+    SLIDING_WINDOW = "sliding_window"
+    FIXED_WINDOW = "fixed_window"
+    LEAKY_BUCKET = "leaky_bucket"
+
+class TrafficDecision(str, Enum):
+    ALLOW = "allow"
+    BLOCK = "block"
+    WOULD_BLOCK = "would_block"
+
+class DecisionReason(str, Enum):
+    WITHIN_LIMIT = "within_limit"
+    LIMIT_EXCEEDED = "limit_exceeded"
+    TOKEN_EXHAUSTED = "token_exhausted"
+
+# REMOVED: LogMode Enum is no longer needed!
+
+@dataclass
+class CanonicalDecision:
+    decision: TrafficDecision
+    reason: DecisionReason
+    algorithm: Algorithm
+    route: str
+    key: Optional[str] = None
+    remaining: Optional[int] = None
+    reset_ms: Optional[int] = None
+    latency_ms: Optional[int] = None
+    mode: ProtectionMode = ProtectionMode.ACTIVE
+    timestamp: int = 0
+    ip: Optional[str] = None
+    window: Optional[str] = None
+    limit: Optional[int] = None
+    capacity: Optional[int] = None
+    refill_rate: Optional[float] = None
+    refill_ms: Optional[int] = None
+
+@dataclass
+class CanonicalTelemetryRequest:
+    route: str
+    ip: str
+    method: Optional[str] = None
+    status_code: Optional[int] = None
+    latency_ms: Optional[int] = None
+    user_agent: Optional[str] = None
+    key: Optional[str] = None
+    mode: ProtectionMode = ProtectionMode.ACTIVE
+
+@dataclass
+class CanonicalTelemetryEvent:
+    event_type: str
+    timestamp: int
+    decision: CanonicalDecision
+    request: CanonicalTelemetryRequest
+    api_key: Optional[str] = None
+    sdk_version: Optional[str] = None
+
+@dataclass
+class Rules:
+    requests_per_minute: Optional[int] = None
+    requests_per_second: Optional[int] = None
+    burst_limit: Optional[int] = None
+
+@dataclass
+class Thresholds:
+    burst: int = 20
+    block_duration_ms: int = 60000
+
+@dataclass
+class PaceConfig:
+    api_key: Optional[str] = None
+    mode: ProtectionMode = ProtectionMode.ACTIVE
+    algorithm: Algorithm = Algorithm.TOKEN_BUCKET
+    capacity: int = 100
+    refill_rate: int = 10
+    # Unified debug setting: False, True, "compact", or "pretty"
+    debug: Union[bool, str] = False
+    identity_header: Optional[str] = None
+    backend_url: str = "http://localhost:4000"
+    rules: Rules = field(default_factory=Rules)
+    thresholds: Thresholds = field(default_factory=Thresholds)
+
+@dataclass
+class CheckResult:
+    allowed: bool
+    would_block: bool
+    reason: Optional[str] = None
+    decision: Optional[CanonicalDecision] = None