requestflow 0.1.0__py3-none-any.whl

requestflow/__init__.py

@@ -0,0 +1,15 @@
+from requestflow.deduplication import InFlightDeduplicator, ResultCache
+from requestflow.exceptions import IntegrationError, OperationCancelledError, QueueFullError, RateLimitExceededError, RequestFlowError, RequestTimeoutError, SchedulerClosedError, SchedulerNotStartedError, UnsupportedDiscordVersionError
+from requestflow.executor import RequestExecutor
+from requestflow.flow import RequestFlow
+from requestflow.integrations.discord_py import DiscordHTTPAdapter, attach_to_bot
+from requestflow.metrics import RequestMetrics
+from requestflow.models import MetricsSnapshot, RequestItem
+from requestflow.policies import OverloadPolicy, PacingStrategy, RetryPolicy
+from requestflow.priorities import Priority
+from requestflow.queue import RequestQueue
+from requestflow.ratelimit import GlobalRateLimiter, RateLimitCoordinator, RouteBucketCoordinator
+from requestflow.scheduler import RequestScheduler
+__version__ = '0.1.0'
+__all__ = ['__version__', 'requestflow', 'priority', 'overloadpolicy', 'pacingstrategy', 'retrypolicy', 'requestmetrics', 'metricssnapshot', 'requestitem', 'requestscheduler', 'requestqueue', 'requestexecutor', 'ratelimitcoordinator', 'globalratelimiter', 'routebucketcoordinator',
+           'inflightdeduplicator', 'resultcache', 'discordhttpadapter', 'attach_to_bot', 'requestflowerror', 'queuefullerror', 'schedulerclosederror', 'schedulernotstartederror', 'requesttimeouterror', 'ratelimitexceedederror', 'integrationerror', 'unsupporteddiscordversionerror', 'operationcancellederror']

requestflow/deduplication.py

@@ -0,0 +1,104 @@
+import asyncio
+import collections
+import time
+from typing import Any, Callable, Coroutine, Dict, Generic, List, Optional, Tuple, TypeVar
+T = TypeVar('t')
+
+
+class InFlightDeduplicator:
+    def __init__(self) -> None:
+        self._waiters: Dict[str, List[asyncio.Future]] = {}
+        self._tasks: Dict[str, asyncio.Task] = {}
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+    async def execute_or_join(self, dedup_key: str, runner: Callable[[], Coroutine[Any, Any, T]]) -> T:
+        loop = asyncio.get_running_loop()
+        caller_future: asyncio.Future = loop.create_future()
+        async with self._lock:
+            if dedup_key in self._waiters:
+                self._waiters[dedup_key].append(caller_future)
+                is_leader = False
+            else:
+                self._waiters[dedup_key] = [caller_future]
+                is_leader = True
+                task = asyncio.create_task(self._run_leader(dedup_key, runner))
+                self._tasks[dedup_key] = task
+        try:
+            return await caller_future
+        except asyncio.CancelledError:
+            async with self._lock:
+                if dedup_key in self._waiters:
+                    waiters = self._waiters[dedup_key]
+                    if caller_future in waiters:
+                        waiters.remove(caller_future)
+                    if len(waiters) == 0 and dedup_key in self._tasks:
+                        task = self._tasks.pop(dedup_key, None)
+                        if task and (not task.done()):
+                            task.cancel()
+                        self._waiters.pop(dedup_key, None)
+            raise
+
+    async def _run_leader(self, dedup_key: str, runner: Callable[[], Coroutine[Any, Any, T]]) -> None:
+        result: Any = None
+        error: Optional[BaseException] = None
+        try:
+            result = await runner()
+        except asyncio.CancelledError as exc:
+            error = exc
+        except BaseException as exc:
+            error = exc
+        async with self._lock:
+            waiters = self._waiters.pop(dedup_key, [])
+            self._tasks.pop(dedup_key, None)
+        for fut in waiters:
+            if not fut.done():
+                if error is not None:
+                    if isinstance(error, asyncio.CancelledError):
+                        fut.cancel()
+                    else:
+                        fut.set_exception(error)
+                else:
+                    fut.set_result(result)
+
+
+class ResultCache(Generic[T]):
+    def __init__(self, max_capacity: int = 1000, default_ttl_seconds: float = 60.0) -> None:
+        if max_capacity <= 0:
+            raise ValueError('max_capacity must be > 0')
+        self._max_capacity: int = max_capacity
+        self._default_ttl: float = default_ttl_seconds
+        self._entries: collections.OrderedDict[str,
+                                               Tuple[T, float]] = collections.OrderedDict()
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+    async def get(self, key: str) -> Optional[T]:
+        async with self._lock:
+            if key not in self._entries:
+                return None
+            val, expiry = self._entries[key]
+            if time.monotonic() > expiry:
+                del self._entries[key]
+                return None
+            self._entries.move_to_end(key)
+            return val
+
+    async def set(self, key: str, value: T, ttl_seconds: Optional[float] = None) -> None:
+        ttl = ttl_seconds if ttl_seconds is not None else self._default_ttl
+        expiry = time.monotonic() + ttl
+        async with self._lock:
+            if key in self._entries:
+                del self._entries[key]
+            elif len(self._entries) >= self._max_capacity:
+                self._entries.popitem(last=False)
+            self._entries[key] = (value, expiry)
+
+    async def invalidate(self, key: str) -> bool:
+        async with self._lock:
+            if key in self._entries:
+                del self._entries[key]
+                return True
+            return False
+
+    async def clear(self) -> None:
+        async with self._lock:
+            self._entries.clear()

requestflow/exceptions.py

@@ -0,0 +1,43 @@
+from typing import Optional
+
+
+class RequestFlowError(Exception):
+    pass
+
+
+class QueueFullError(RequestFlowError):
+    pass
+
+
+class SchedulerClosedError(RequestFlowError):
+    pass
+
+
+class SchedulerNotStartedError(RequestFlowError):
+    pass
+
+
+class RequestTimeoutError(RequestFlowError):
+    def __init__(self, message: str, *, timeout_seconds: float) -> None:
+        super().__init__(message)
+        self.timeout_seconds: float = timeout_seconds
+
+
+class RateLimitExceededError(RequestFlowError):
+    def __init__(self, message: str, *, retry_after: Optional[float] = None) -> None:
+        super().__init__(message)
+        self.retry_after: Optional[float] = retry_after
+
+
+class IntegrationError(RequestFlowError):
+    pass
+
+
+class UnsupportedDiscordVersionError(IntegrationError):
+    def __init__(self, message: str, *, detected_version: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.detected_version: Optional[str] = detected_version
+
+
+class OperationCancelledError(RequestFlowError):
+    pass

requestflow/executor.py

@@ -0,0 +1,89 @@
+import asyncio
+import inspect
+import time
+from typing import Any, Callable, Coroutine, Optional
+from requestflow.exceptions import OperationCancelledError, RequestTimeoutError
+from requestflow.models import RequestItem
+from requestflow.policies import RetryPolicy
+
+
+class RequestExecutor:
+    def __init__(self, max_concurrency: int = 16, default_timeout: Optional[float] = None, default_retry_policy: Optional[RetryPolicy] = None) -> None:
+        if max_concurrency <= 0:
+            raise ValueError(
+                f'max_concurrency must be > 0, got {max_concurrency}')
+        self._max_concurrency: int = max_concurrency
+        self._semaphore: asyncio.Semaphore = asyncio.Semaphore(max_concurrency)
+        self._default_timeout: Optional[float] = default_timeout
+        self._default_retry_policy: Optional[RetryPolicy] = default_retry_policy
+        self._currently_executing: int = 0
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+    @property
+    def max_concurrency(self) -> int:
+        return self._max_concurrency
+
+    @property
+    def currently_executing(self) -> int:
+        return self._currently_executing
+
+    async def execute(self, item: RequestItem, on_complete: Optional[Callable[[RequestItem, Optional[BaseException]], None]] = None) -> None:
+        if item.cancelled or (item.future and item.future.cancelled()):
+            if on_complete:
+                on_complete(item, OperationCancelledError(
+                    'operation cancelled before execution'))
+            return
+        async with self._semaphore:
+            async with self._lock:
+                self._currently_executing += 1
+            item.execution_start_time = time.monotonic()
+            error: Optional[BaseException] = None
+            retry_policy = self._default_retry_policy
+            timeout = item.timeout if item.timeout is not None else self._default_timeout
+            attempts = 0
+            try:
+                while True:
+                    attempts += 1
+                    try:
+                        res = item.operation(*item.args, **item.kwargs)
+                        if inspect.isawaitable(res):
+                            if timeout is not None and timeout > 0:
+                                result = await asyncio.wait_for(res, timeout=timeout)
+                            else:
+                                result = await res
+                        else:
+                            result = res
+                        item.completion_time = time.monotonic()
+                        if item.future and (not item.future.done()):
+                            item.future.set_result(result)
+                        break
+                    except asyncio.TimeoutError as exc:
+                        timeout_err = RequestTimeoutError(
+                            f'operation timed out after {timeout:.2f} seconds', timeout_seconds=float(timeout or 0.0))
+                        error = timeout_err
+                        item.completion_time = time.monotonic()
+                        if item.future and (not item.future.done()):
+                            item.future.set_exception(timeout_err)
+                        break
+                    except asyncio.CancelledError as exc:
+                        item.cancelled = True
+                        error = exc
+                        item.completion_time = time.monotonic()
+                        if item.future and (not item.future.done()):
+                            item.future.cancel()
+                        raise
+                    except BaseException as exc:
+                        error = exc
+                        if retry_policy and retry_policy.is_retryable(exc) and (attempts <= retry_policy.max_retries):
+                            delay = retry_policy.compute_delay(attempts - 1)
+                            await asyncio.sleep(delay)
+                            continue
+                        item.completion_time = time.monotonic()
+                        if item.future and (not item.future.done()):
+                            item.future.set_exception(exc)
+                        break
+            finally:
+                async with self._lock:
+                    self._currently_executing -= 1
+                if on_complete:
+                    on_complete(item, error)

requestflow/flow.py

@@ -0,0 +1,73 @@
+import asyncio
+from typing import Any, Callable, Coroutine, Optional, TypeVar, Union
+from requestflow.deduplication import InFlightDeduplicator, ResultCache
+from requestflow.exceptions import RequestFlowError
+from requestflow.integrations.discord_py import DiscordHTTPAdapter
+from requestflow.models import MetricsSnapshot
+from requestflow.policies import OverloadPolicy, RetryPolicy
+from requestflow.priorities import Priority
+from requestflow.scheduler import RequestScheduler
+T = TypeVar('T')
+
+
+class RequestFlow:
+    def __init__(self, bot: Optional[Any] = None, *, max_pending: int = 5000, max_concurrency: int = 16, global_rate_limit: float = 40.0, rate_limit_ceiling: float = 50.0, burst_allowance: float = 5.0, allow_custom_ceiling: bool = False, overload_policy: Union[OverloadPolicy, str] = OverloadPolicy.REJECT, aging_threshold_seconds: float = 2.0, guild_quantum: int = 3, default_timeout: Optional[float] = None, default_retry_policy: Optional[RetryPolicy] = None, auto_attach: bool = True) -> None:
+        if isinstance(overload_policy, str):
+            overload_policy = OverloadPolicy(overload_policy.lower())
+        self.scheduler = RequestScheduler(max_pending=max_pending, max_concurrency=max_concurrency, global_rate_limit=global_rate_limit, rate_limit_ceiling=rate_limit_ceiling, burst_allowance=burst_allowance,
+                                          allow_custom_ceiling=allow_custom_ceiling, overload_policy=overload_policy, aging_threshold_seconds=aging_threshold_seconds, guild_quantum=guild_quantum, default_timeout=default_timeout, default_retry_policy=default_retry_policy)
+        self._bot: Optional[Any] = bot
+        self._auto_attach: bool = auto_attach
+        self._adapter: DiscordHTTPAdapter = DiscordHTTPAdapter(self.scheduler)
+        self.deduplicator: InFlightDeduplicator = InFlightDeduplicator()
+        self.cache: ResultCache = ResultCache()
+
+    @property
+    def metrics(self):
+        return self.scheduler.metrics
+
+    @property
+    def stats(self) -> MetricsSnapshot:
+        return self.scheduler.metrics.snapshot()
+
+    @property
+    def is_started(self) -> bool:
+        return self.scheduler.is_started
+
+    @property
+    def is_closed(self) -> bool:
+        return self.scheduler.is_closed
+
+    async def start(self) -> 'RequestFlow':
+        await self.scheduler.start()
+        if self._bot is not None and self._auto_attach:
+            self.attach(self._bot)
+        return self
+
+    async def close(self, drain: bool = True, timeout: float = 5.0) -> None:
+        self._adapter.detach_all()
+        await self.scheduler.close(drain=drain, timeout=timeout)
+
+    async def __aenter__(self) -> 'RequestFlow':
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close(drain=True)
+
+    def attach(self, bot: Any) -> None:
+        self._adapter.attach(bot)
+
+    def detach(self, bot: Any) -> None:
+        self._adapter.detach(bot)
+
+    async def update_rate(self, new_rate: float) -> None:
+        await self.scheduler.rate_coordinator.global_limiter.update_rate(new_rate)
+
+    async def submit(self, operation: Callable[..., Coroutine[Any, Any, T]], *args: Any, priority: Union[Priority, str, int] = Priority.NORMAL, guild_id: Optional[int] = None, route_key: Optional[str] = None, is_interaction: bool = False, dedup_key: Optional[str] = None, timeout: Optional[float] = None, enqueue_timeout: Optional[float] = None, **kwargs: Any) -> T:
+        parsed_priority = Priority.from_value(priority)
+        if dedup_key is not None:
+            async def run_single() -> T:
+                return await self.scheduler.submit(operation, *args, priority=parsed_priority, guild_id=guild_id, route_key=route_key, is_interaction=is_interaction, dedup_key=dedup_key, timeout=timeout, enqueue_timeout=enqueue_timeout, **kwargs)
+            return await self.deduplicator.execute_or_join(dedup_key, run_single)
+        return await self.scheduler.submit(operation, *args, priority=parsed_priority, guild_id=guild_id, route_key=route_key, is_interaction=is_interaction, dedup_key=dedup_key, timeout=timeout, enqueue_timeout=enqueue_timeout, **kwargs)

requestflow/integrations/__init__.py

@@ -0,0 +1,2 @@
+from requestflow.integrations.discord_py import DiscordHTTPAdapter, attach_to_bot
+__all__ = ['discordhttpadapter', 'attach_to_bot']

requestflow/integrations/discord_py.py

@@ -0,0 +1,115 @@
+import functools
+import inspect
+from typing import Any, Callable, Optional, Sequence, Union
+try:
+    import discord
+    import discord.http
+    HAS_DISCORD = True
+except ImportError:
+    HAS_DISCORD = False
+from requestflow.exceptions import IntegrationError, UnsupportedDiscordVersionError
+from requestflow.priorities import Priority
+from requestflow.scheduler import RequestScheduler
+
+
+class DiscordHTTPAdapter:
+    MIN_SUPPORTED_DISCORD_VERSION = (2, 0, 0)
+
+    def __init__(self, scheduler: RequestScheduler) -> None:
+        self.scheduler: RequestScheduler = scheduler
+        self._attached_clients: set = set()
+        self._original_requests: dict = {}
+
+    @classmethod
+    def verify_compatibility(cls) -> None:
+        if not HAS_DISCORD:
+            raise IntegrationError(
+                'discord.py is not installed in the current environment.')
+        version_str = getattr(discord, '__version__', 'unknown')
+        try:
+            parts = version_str.split('.')
+            major = int(parts[0])
+            minor = int(parts[1].rstrip('abcdefghijklmnopqrstuvwxyz'))
+            if major < 2:
+                raise UnsupportedDiscordVersionError(
+                    f'requestflow requires discord.py >= 2.0.0, but found {version_str}.', detected_version=version_str)
+        except (ValueError, IndexError):
+            if not hasattr(discord.http, 'httpclient') or not hasattr(discord.http, 'route'):
+                raise UnsupportedDiscordVersionError(
+                    f'unsupported discord.py layout or version: {version_str}.', detected_version=version_str)
+
+    def attach(self, client: Any) -> None:
+        self.verify_compatibility()
+        http_client = getattr(client, 'http', None)
+        if http_client is None:
+            if isinstance(client, getattr(discord.http, 'httpclient', object)):
+                http_client = client
+            else:
+                raise IntegrationError(
+                    f"target object {type(client).__name__} does not have an 'http' attribute.")
+        if not hasattr(http_client, 'request') or not callable(http_client.request):
+            raise IntegrationError(
+                f"http client {type(http_client).__name__} has no callable 'request' method.")
+        if http_client in self._attached_clients:
+            return
+        original_request = http_client.request
+        self._original_requests[http_client] = original_request
+
+        @functools.wraps(original_request)
+        async def scheduled_request(route: Any, *args: Any, **kwargs: Any) -> Any:
+            guild_id = getattr(route, 'guild_id', None)
+            route_path = getattr(route, 'path', '')
+            route_key = getattr(
+                route, 'key', f"{getattr(route, 'method', 'GET')} {route_path}")
+            is_interaction = bool(
+                route_path and '/interactions/' in route_path)
+            if is_interaction:
+                priority = Priority.CRITICAL
+            elif getattr(route, 'method', '') == 'DELETE':
+                priority = Priority.HIGH
+            else:
+                priority = Priority.NORMAL
+
+            async def run_http() -> Any:
+                try:
+                    return await original_request(route, *args, **kwargs)
+                except getattr(discord, 'ratelimited', Exception) as exc:
+                    retry_after = getattr(exc, 'retry_after', 0.0)
+                    if retry_after > 0:
+                        self.scheduler.rate_coordinator.handle_429(
+                            retry_after, is_global=False, route_key=route_key)
+                        self.scheduler.metrics.record_429(is_global=False)
+                    raise
+                except getattr(discord, 'httpexception', Exception) as exc:
+                    if getattr(exc, 'status', None) == 429:
+                        retry_after = 1.0
+                        if hasattr(exc, 'response') and hasattr(exc.response, 'headers'):
+                            retry_after = float(
+                                exc.response.headers.get('Retry-After', 1.0))
+                        self.scheduler.rate_coordinator.handle_429(
+                            retry_after, is_global=False, route_key=route_key)
+                        self.scheduler.metrics.record_429(is_global=False)
+                    raise
+            return await self.scheduler.submit(run_http, priority=priority, guild_id=guild_id, route_key=route_key, is_interaction=is_interaction)
+        http_client.request = scheduled_request
+        self._attached_clients.add(http_client)
+
+    def detach(self, client: Any) -> None:
+        http_client = getattr(client, 'http', client)
+        if http_client in self._attached_clients:
+            original = self._original_requests.pop(http_client, None)
+            if original:
+                http_client.request = original
+            self._attached_clients.remove(http_client)
+
+    def detach_all(self) -> None:
+        for http_client, original in list(self._original_requests.items()):
+            http_client.request = original
+        self._attached_clients.clear()
+        self._original_requests.clear()
+
+
+def attach_to_bot(scheduler: RequestScheduler, bot: Any) -> DiscordHTTPAdapter:
+    adapter = DiscordHTTPAdapter(scheduler)
+    adapter.attach(bot)
+    return adapter

requestflow/metrics.py

@@ -0,0 +1,104 @@
+import collections
+import time
+from typing import Callable, Deque, Dict, List, Optional
+from requestflow.models import MetricsSnapshot
+
+
+class RequestMetrics:
+    def __init__(self, sample_buffer_size: int = 1000, throughput_window_seconds: float = 10.0) -> None:
+        self._buffer_size: int = sample_buffer_size
+        self._window_seconds: float = throughput_window_seconds
+        self.submitted: int = 0
+        self.completed: int = 0
+        self.failed: int = 0
+        self.cancelled: int = 0
+        self.rejected: int = 0
+        self.rate_limit_429_count: int = 0
+        self.cooldown_count_global: int = 0
+        self.cooldown_count_route: int = 0
+        self.retries_attempted: int = 0
+        self.total_rate_limit_wait_time: float = 0.0
+        self._queue_wait_samples: Deque[float] = collections.deque(
+            maxlen=sample_buffer_size)
+        self._exec_duration_samples: Deque[float] = collections.deque(
+            maxlen=sample_buffer_size)
+        self._completion_timestamps: Deque[float] = collections.deque()
+        self._get_currently_queued: Callable[[], int] = lambda: 0
+        self._get_currently_executing: Callable[[], int] = lambda: 0
+        self._get_high_water_mark: Callable[[], int] = lambda: 0
+        self._get_per_priority: Callable[[], Dict[str, int]] = lambda: {}
+        self._get_active_guilds: Callable[[], int] = lambda: 0
+
+    def register_providers(self, get_currently_queued: Callable[[], int], get_currently_executing: Callable[[], int], get_high_water_mark: Callable[[], int], get_per_priority: Callable[[], Dict[str, int]], get_active_guilds: Callable[[], int]) -> None:
+        self._get_currently_queued = get_currently_queued
+        self._get_currently_executing = get_currently_executing
+        self._get_high_water_mark = get_high_water_mark
+        self._get_per_priority = get_per_priority
+        self._get_active_guilds = get_active_guilds
+
+    def record_submit(self) -> None:
+        self.submitted += 1
+
+    def record_reject(self) -> None:
+        self.rejected += 1
+
+    def record_cancel(self) -> None:
+        self.cancelled += 1
+
+    def record_retry(self) -> None:
+        self.retries_attempted += 1
+
+    def record_rate_limit_wait(self, duration_seconds: float) -> None:
+        if duration_seconds > 0:
+            self.total_rate_limit_wait_time += duration_seconds
+
+    def record_429(self, *, is_global: bool = False) -> None:
+        self.rate_limit_429_count += 1
+        if is_global:
+            self.cooldown_count_global += 1
+        else:
+            self.cooldown_count_route += 1
+
+    def record_completion(self, queue_wait_seconds: float, exec_duration_seconds: float, error: Optional[BaseException] = None) -> None:
+        now = time.monotonic()
+        if error is not None:
+            self.failed += 1
+        else:
+            self.completed += 1
+        self._queue_wait_samples.append(queue_wait_seconds * 1000.0)
+        self._exec_duration_samples.append(exec_duration_seconds * 1000.0)
+        self._completion_timestamps.append(now)
+        self._prune_throughput_window(now)
+
+    def _prune_throughput_window(self, now: float) -> None:
+        cutoff = now - self._window_seconds
+        while self._completion_timestamps and self._completion_timestamps[0] < cutoff:
+            self._completion_timestamps.popleft()
+
+    def get_throughput_rps(self) -> float:
+        now = time.monotonic()
+        self._prune_throughput_window(now)
+        count = len(self._completion_timestamps)
+        if count == 0:
+            return 0.0
+        return count / self._window_seconds
+
+    @staticmethod
+    def _calculate_percentile(samples: List[float], percentile: float) -> float:
+        if not samples:
+            return 0.0
+        idx = int(len(samples) * (percentile / 100.0))
+        idx = min(idx, len(samples) - 1)
+        return samples[idx]
+
+    def snapshot(self) -> MetricsSnapshot:
+        now = time.monotonic()
+        sorted_wait = sorted(self._queue_wait_samples)
+        sorted_exec = sorted(self._exec_duration_samples)
+        p50_wait = self._calculate_percentile(sorted_wait, 50.0)
+        p95_wait = self._calculate_percentile(sorted_wait, 95.0)
+        p99_wait = self._calculate_percentile(sorted_wait, 99.0)
+        p50_exec = self._calculate_percentile(sorted_exec, 50.0)
+        p95_exec = self._calculate_percentile(sorted_exec, 95.0)
+        p99_exec = self._calculate_percentile(sorted_exec, 99.0)
+        return MetricsSnapshot(timestamp=now, submitted=self.submitted, completed=self.completed, failed=self.failed, cancelled=self.cancelled, rejected=self.rejected, currently_queued=self._get_currently_queued(), currently_executing=self._get_currently_executing(), queue_high_water_mark=self._get_high_water_mark(), p50_queue_wait_ms=round(p50_wait, 2), p95_queue_wait_ms=round(p95_wait, 2), p99_queue_wait_ms=round(p99_wait, 2), p50_exec_latency_ms=round(p50_exec, 2), p95_exec_latency_ms=round(p95_exec, 2), p99_exec_latency_ms=round(p99_exec, 2), throughput_window_rps=round(self.get_throughput_rps(), 2), rate_limit_429_count=self.rate_limit_429_count, cooldown_count_global=self.cooldown_count_global, cooldown_count_route=self.cooldown_count_route, retries_attempted=self.retries_attempted, active_guilds=self._get_active_guilds(), per_priority_queued=self._get_per_priority())

requestflow/models.py

@@ -0,0 +1,75 @@
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine, Dict, Generic, Optional, TypeVar
+from requestflow.priorities import Priority
+T = TypeVar('t')
+
+
+@dataclass
+class RequestItem(Generic[T]):
+    sequence: int
+    operation: Callable[..., Coroutine[Any, Any, T]]
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+    priority: Priority = Priority.NORMAL
+    effective_priority: Priority = Priority.NORMAL
+    guild_id: Optional[int] = None
+    route_key: Optional[str] = None
+    is_interaction: bool = False
+    dedup_key: Optional[str] = None
+    timeout: Optional[float] = None
+    future: Optional[asyncio.Future] = None
+    enqueue_time: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.future is None:
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = asyncio.get_event_loop()
+            self.future = loop.create_future()
+        if self.enqueue_time == 0.0:
+            self.enqueue_time = time.monotonic()
+    execution_start_time: Optional[float] = None
+    completion_time: Optional[float] = None
+    retries_left: int = 0
+    cancelled: bool = False
+
+    @property
+    def queue_wait_time(self) -> float:
+        if self.execution_start_time is None:
+            return time.monotonic() - self.enqueue_time
+        return self.execution_start_time - self.enqueue_time
+
+    @property
+    def execution_duration(self) -> float:
+        if self.execution_start_time is None or self.completion_time is None:
+            return 0.0
+        return self.completion_time - self.execution_start_time
+
+
+@dataclass(frozen=True)
+class MetricsSnapshot:
+    timestamp: float
+    submitted: int
+    completed: int
+    failed: int
+    cancelled: int
+    rejected: int
+    currently_queued: int
+    currently_executing: int
+    queue_high_water_mark: int
+    p50_queue_wait_ms: float
+    p95_queue_wait_ms: float
+    p99_queue_wait_ms: float
+    p50_exec_latency_ms: float
+    p95_exec_latency_ms: float
+    p99_exec_latency_ms: float
+    throughput_window_rps: float
+    rate_limit_429_count: int
+    cooldown_count_global: int
+    cooldown_count_route: int
+    retries_attempted: int
+    active_guilds: int
+    per_priority_queued: Dict[str, int] = field(default_factory=dict)

requestflow/policies.py

@@ -0,0 +1,39 @@
+import random
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional, Sequence, Tuple, Type
+
+
+class OverloadPolicy(str, Enum):
+    REJECT = 'reject'
+    WAIT = 'wait'
+    DROP_OLDEST = 'drop_oldest'
+
+
+class PacingStrategy(str, Enum):
+    GCRA = 'gcra'
+    LEAKY_BUCKET = 'leaky_bucket'
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    max_retries: int = 0
+    base_delay: float = 0.5
+    max_delay: float = 10.0
+    jitter: bool = True
+    retryable_exceptions: Tuple[Type[BaseException], ...] = ()
+
+    def is_retryable(self, exception: BaseException) -> bool:
+        if not self.retryable_exceptions:
+            return False
+        return isinstance(exception, self.retryable_exceptions)
+
+    def compute_delay(self, attempt: int, retry_after: Optional[float] = None) -> float:
+        if retry_after is not None and retry_after > 0:
+            return retry_after
+        delay = self.base_delay * 2 ** attempt
+        delay = min(delay, self.max_delay)
+        if self.jitter:
+            factor = 0.5 + random.random()
+            delay = delay * factor
+        return min(delay, self.max_delay)