Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

added rate limiter for telegram to prevent flood wait

Alishahryar12a8482382579
diff --git a/.env.example b/.env.example
index c5f26bb4..e13e1797 100644
--- a/.env.example
+++ b/.env.example
@@ -54,4 +54,8 @@ ALLOWED_TELEGRAM_USER_ID="YOUR_TELEGRAM_USER_ID"
CLAUDE_WORKSPACE="./agent_workspace"
ALLOWED_DIR="C:/Users/YourName/projects/myproject"
MAX_CLI_SESSIONS=10 # Maximum parallel Claude CLI instances
-WRAPPER_WS_URL="ws://localhost:8083/ws"
\ No newline at end of file
+WRAPPER_WS_URL="ws://localhost:8083/ws"
+
+# Messaging Rate Limiting
+MESSAGING_RATE_LIMIT=1 # Number of requests
+MESSAGING_RATE_WINDOW=2 # Every N seconds (1 req / 2 sec)
\ No newline at end of file
diff --git a/messaging/base.py b/messaging/base.py
index bdbf034b..00b01bc2 100644
--- a/messaging/base.py
+++ b/messaging/base.py
@@ -65,6 +65,40 @@ class MessagingPlatform(ABC):
"""
pass
+ @abstractmethod
+ async def queue_send_message(
+ self,
+ chat_id: str,
+ text: str,
+ reply_to: Optional[str] = None,
+ parse_mode: Optional[str] = None,
+ fire_and_forget: bool = True,
+ ) -> Optional[str]:
+ """
+ Enqueue a message to be sent.
+
+ If fire_and_forget is True, returns None immediately.
+ Otherwise, waits for the rate limiter and returns message ID.
+ """
+ pass
+
+ @abstractmethod
+ async def queue_edit_message(
+ self,
+ chat_id: str,
+ message_id: str,
+ text: str,
+ parse_mode: Optional[str] = None,
+ fire_and_forget: bool = True,
+ ) -> None:
+ """
+ Enqueue a message edit.
+
+ If fire_and_forget is True, returns immediately.
+ Otherwise, waits for the rate limiter.
+ """
+ pass
+
@abstractmethod
def on_message(
self,
diff --git a/messaging/handler.py b/messaging/handler.py
index 9815a43b..94b964c4 100644
--- a/messaging/handler.py
+++ b/messaging/handler.py
@@ -96,7 +96,9 @@ class ClaudeMessageHandler:
status_msg_id = await self.platform.send_message(
incoming.chat_id,
status_text,
- reply_to=incoming.message_id if incoming.message_id != incoming.message_id else None,
+ reply_to=incoming.message_id
+ if incoming.message_id != incoming.message_id
+ else None,
)
# Create or extend tree
@@ -182,37 +184,19 @@ class ClaudeMessageHandler:
nonlocal last_ui_update
now = time.time()
- # Small 1s debounce for UI sanity (not a hard rate limit)
+ # Small 1s debounce for UI sanity - we still want to avoid
+ # spamming the queue with too many intermediate states
if not force and now - last_ui_update < 1.0:
return
- # Retry logic for flood wait errors
- max_retries = 3 if not force else 5
- for attempt in range(max_retries):
- try:
- display = self._build_message(components, status)
- if display:
- await self.platform.edit_message(
- chat_id, status_msg_id, display, parse_mode="markdown"
- )
- last_ui_update = now
- return # Success, exit retry loop
- except Exception as e:
- error_msg = str(e).lower()
- is_flood_error = "flood" in error_msg or "wait" in error_msg
-
- if is_flood_error and attempt < max_retries - 1:
- # Wait before retry on flood error
- wait_time = 2 ** attempt # Exponential backoff: 2s, 4s, 8s
- logger.warning(f"Flood wait on edit (attempt {attempt + 1}/{max_retries}), retrying in {wait_time}s...")
- await asyncio.sleep(wait_time)
- continue
- else:
- # Log and give up after retries or if not a flood error
- if is_flood_error:
- last_ui_update = now + 10 # Skip for 10s on persistent flood error
- logger.error(f"UI update failed after {attempt + 1} attempts: {e}")
- return
+ last_ui_update = now
+ display = self._build_message(components, status)
+ if display:
+ # Use queued edit for non-blocking, thread-safe UI updates
+ # Rate limiting and flood wait retries are handled by GlobalRateLimiter
+ await self.platform.queue_edit_message(
+ chat_id, status_msg_id, display, parse_mode="markdown"
+ )
try:
# Get or create CLI session
@@ -244,7 +228,9 @@ class ClaudeMessageHandler:
incoming.text, session_id=captured_session_id
):
if not isinstance(event_data, dict):
- logger.warning(f"HANDLER: Non-dict event received: {type(event_data)}")
+ logger.warning(
+ f"HANDLER: Non-dict event received: {type(event_data)}"
+ )
continue
event_count += 1
if event_count % 10 == 0:
@@ -302,7 +288,9 @@ class ClaudeMessageHandler:
elif parsed["type"] == "error":
error_msg = parsed.get("message", "Unknown error")
- logger.error(f"HANDLER: Error event received: {error_msg[:200]}")
+ logger.error(
+ f"HANDLER: Error event received: {error_msg[:200]}"
+ )
components["errors"].append(error_msg)
logger.info(f"HANDLER: Updating UI with error status")
# Always force error status to bypass flood wait
@@ -346,7 +334,9 @@ class ClaudeMessageHandler:
except Exception as e:
logger.error(f"Failed to update child status: {e}")
except Exception as e:
- logger.error(f"HANDLER: Task failed with exception: {type(e).__name__}: {e}")
+ logger.error(
+ f"HANDLER: Task failed with exception: {type(e).__name__}: {e}"
+ )
error_msg = str(e)[:200]
components["errors"].append(error_msg)
# Always force error status to bypass flood wait
@@ -368,7 +358,9 @@ class ClaudeMessageHandler:
except Exception as e:
logger.error(f"Failed to update child status: {e}")
finally:
- logger.info(f"HANDLER: _process_node completed for node {node_id}, errors={len(components['errors'])}")
+ logger.info(
+ f"HANDLER: _process_node completed for node {node_id}, errors={len(components['errors'])}"
+ )
def _build_message(
self,
diff --git a/messaging/limiter.py b/messaging/limiter.py
new file mode 100644
index 00000000..98ba9963
--- /dev/null
+++ b/messaging/limiter.py
@@ -0,0 +1,138 @@
+"""
+Global Rate Limiter for Messaging Platforms.
+
+Centralizes outgoing message requests and ensures compliance with rate limits
+using a leaky bucket algorithm (aiolimiter) and a task queue.
+"""
+
+import asyncio
+import logging
+import os
+from typing import Awaitable, Callable, Any, Optional
+from aiolimiter import AsyncLimiter
+
+logger = logging.getLogger(__name__)
+
+
+class GlobalRateLimiter:
+ """
+ A thread-safe global rate limiter for messaging.
+
+ Uses an asyncio.Queue to accept tasks and a background worker to
+ process them at a rate defined by MESSAGING_RATE_LIMIT and MESSAGING_RATE_WINDOW.
+ """
+
+ _instance: Optional["GlobalRateLimiter"] = None
+ _lock = asyncio.Lock()
+
+ def __new__(cls, *args, **kwargs):
+ if not cls._instance:
+ # Note: The actual initialization happens in __init__
+ # but we use a singleton pattern for the global limiter.
+ pass
+ return super(GlobalRateLimiter, cls).__new__(cls)
+
+ @classmethod
+ async def get_instance(cls) -> "GlobalRateLimiter":
+ """Get the singleton instance of the limiter."""
+ async with cls._lock:
+ if cls._instance is None:
+ cls._instance = cls()
+ # Start the background worker
+ asyncio.create_task(cls._instance._worker())
+ return cls._instance
+
+ def __init__(self):
+ # Prevent double initialization in singleton
+ if hasattr(self, "_initialized"):
+ return
+
+ rate_limit = int(os.getenv("MESSAGING_RATE_LIMIT", "1"))
+ rate_window = float(os.getenv("MESSAGING_RATE_WINDOW", "2.0"))
+
+ self.limiter = AsyncLimiter(rate_limit, rate_window)
+ self.queue: asyncio.Queue[
+ tuple[Callable[[], Awaitable[Any]], asyncio.Future]
+ ] = asyncio.Queue()
+ self._initialized = True
+ self._paused_until = 0
+
+ logger.info(
+ f"GlobalRateLimiter initialized ({rate_limit} req / {rate_window}s)"
+ )
+
+ async def _worker(self):
+ """Background worker that processes queued messaging tasks."""
+ logger.info("GlobalRateLimiter worker started")
+ while True:
+ try:
+ # Get a task from the queue
+ func, future = await self.queue.get()
+
+ # Check for manual pause (FloodWait)
+ now = asyncio.get_event_loop().time()
+ if self._paused_until > now:
+ wait_time = self._paused_until - now
+ logger.warning(
+ f"Limiter worker paused, waiting {wait_time:.1f}s more..."
+ )
+ await asyncio.sleep(wait_time)
+
+ # Wait for rate limit capacity
+ async with self.limiter:
+ try:
+ result = await func()
+ if not future.done():
+ future.set_result(result)
+ except Exception as e:
+ # Handle Telegram FloodWaitError specifically
+ error_msg = str(e).lower()
+ if "flood" in error_msg or "wait" in error_msg:
+ # Attempt to extract seconds if possible, else default to 30
+ seconds = 30
+ try:
+ # Telethon's FloodWaitError usually has .seconds
+ if hasattr(e, "seconds"):
+ seconds = e.seconds
+ except:
+ pass
+
+ logger.error(f"FloodWait detected! Pausing for {seconds}s")
+ self._paused_until = (
+ asyncio.get_event_loop().time() + seconds
+ )
+
+ # Re-queue the task at the front if possible,
+ # but simple approach is to retry after pause
+ await asyncio.sleep(seconds)
+ # Simple retry: put it back
+ await self.queue.put((func, future))
+ else:
+ if not future.done():
+ future.set_exception(e)
+ finally:
+ self.queue.task_done()
+ except asyncio.CancelledError:
+ break
+ except Exception as e:
+ logger.error(f"Error in limiter worker: {e}", exc_info=True)
+ await asyncio.sleep(1)
+
+ async def enqueue(self, func: Callable[[], Awaitable[Any]]) -> Any:
+ """
+ Enqueue a messaging task and return its future result.
+
+ This makes the call non-blocking for the caller if they don't await the result,
+ or they can await it to get the message_id/result.
+ """
+ future = asyncio.get_event_loop().create_future()
+ await self.queue.put((func, future))
+ return await future
+
+ def fire_and_forget(self, func: Callable[[], Awaitable[Any]]):
+ """Enqueue a task without waiting for the result."""
+ future = asyncio.get_event_loop().create_future()
+ # We don't await the put because we want it to be really fast
+ # but asyncio.Queue.put is a coroutine.
+ # However, in most cases it won't block unless queue is full.
+ asyncio.create_task(self.queue.put((func, future)))
diff --git a/messaging/telegram.py b/messaging/telegram.py
index b82b6861..0a6f98b8 100644
--- a/messaging/telegram.py
+++ b/messaging/telegram.py
@@ -60,6 +60,7 @@ class TelegramPlatform(MessagingPlatform):
self._connected = False
# Cache entity objects to avoid flood wait errors
self._entity_cache: Dict[str, Any] = {}
+ self._limiter: Optional[GlobalRateLimiter] = None
async def start(self) -> None:
"""Initialize and connect to Telegram."""
@@ -80,15 +81,18 @@ class TelegramPlatform(MessagingPlatform):
await self._client.start()
self._connected = True
+ # Initialize rate limiter
+ from .limiter import GlobalRateLimiter
+
+ self._limiter = await GlobalRateLimiter.get_instance()
+
# Run in background
asyncio.create_task(self._client.run_until_disconnected())
# Send startup notification
try:
me_entity = await self._client.get_input_entity("me")
- await self._client.send_message(
- me_entity, "🚀 **Claude Code Proxy is online!**"
- )
+ await self.send_message(me_entity, "🚀 **Claude Code Proxy is online!**")
except Exception as e:
logger.warning(f"Could not send startup message: {e}")
@@ -105,7 +109,7 @@ class TelegramPlatform(MessagingPlatform):
"""Get entity object for a chat_id, using cache to avoid flood wait errors."""
if chat_id in self._entity_cache:
return self._entity_cache[chat_id]
-
+
# Get entity and cache it
entity = await self._client.get_input_entity(peer=int(chat_id))
self._entity_cache[chat_id] = entity
@@ -161,6 +165,47 @@ class TelegramPlatform(MessagingPlatform):
# Message content unchanged, ignore
pass
+ async def queue_send_message(
+ self,
+ chat_id: str,
+ text: str,
+ reply_to: Optional[str] = None,
+ parse_mode: Optional[str] = None,
+ fire_and_forget: bool = True,
+ ) -> Optional[str]:
+ """Enqueue a message to be sent."""
+ if not self._limiter:
+ return await self.send_message(chat_id, text, reply_to, parse_mode)
+
+ async def _send():
+ return await self.send_message(chat_id, text, reply_to, parse_mode)
+
+ if fire_and_forget:
+ self._limiter.fire_and_forget(_send)
+ return None
+ else:
+ return await self._limiter.enqueue(_send)
+
+ async def queue_edit_message(
+ self,
+ chat_id: str,
+ message_id: str,
+ text: str,
+ parse_mode: Optional[str] = None,
+ fire_and_forget: bool = True,
+ ) -> None:
+ """Enqueue a message edit."""
+ if not self._limiter:
+ return await self.edit_message(chat_id, message_id, text, parse_mode)
+
+ async def _edit():
+ return await self.edit_message(chat_id, message_id, text, parse_mode)
+
+ if fire_and_forget:
+ self._limiter.fire_and_forget(_edit)
+ else:
+ await self._limiter.enqueue(_edit)
+
def on_message(
self,
handler: Callable[[IncomingMessage], Awaitable[None]],
diff --git a/tests/verify_limiter.py b/tests/verify_limiter.py
new file mode 100644
index 00000000..a178759a
--- /dev/null
+++ b/tests/verify_limiter.py
@@ -0,0 +1,97 @@
+import asyncio
+import os
+import sys
+import time
+from unittest.mock import AsyncMock, MagicMock
+
+# Add current directory to path
+sys.path.append(os.getcwd())
+
+from messaging.limiter import GlobalRateLimiter
+
+
+async def test_rate_limiting():
+ print("\n--- Testing Rate Limiting (1 req / 2 sec) ---")
+ os.environ["MESSAGING_RATE_LIMIT"] = "1"
+ os.environ["MESSAGING_RATE_WINDOW"] = "2.0"
+
+ limiter = await GlobalRateLimiter.get_instance()
+
+ start_time = time.time()
+ results = []
+
+ async def mock_task(i):
+ ts = time.time() - start_time
+ print(f"[{ts:.2f}s] Task {i} started")
+ await asyncio.sleep(0.1) # Simulate network latency
+ print(f"[{time.time() - start_time:.2f}s] Task {i} completed")
+ return i
+
+ # Enqueue 5 tasks simultaneously
+ tasks = [limiter.enqueue(lambda i=i: mock_task(i)) for i in range(5)]
+
+ print("Tasks enqueued, waiting for results...")
+ completed = await asyncio.gather(*tasks)
+
+ total_time = time.time() - start_time
+ print(f"All tasks completed in {total_time:.2f}s")
+ print(f"Results: {completed}")
+
+ # Check if timing is correct: 5 tasks at 1 req / 2 sec should take about 8 seconds
+ # T0: Task 0
+ # T2: Task 1
+ # T4: Task 2
+ # T6: Task 3
+ # T8: Task 4
+ if total_time >= 8.0:
+ print("[SUCCESS] Rate limiting working as expected!")
+ else:
+ print(f"[FAILURE] Rate limiting failed! Took only {total_time:.2f}s")
+
+
+async def test_flood_wait():
+ print("\n--- Testing FloodWait Recovery ---")
+ limiter = await GlobalRateLimiter.get_instance()
+
+ # Reset limiter for fresh test
+ limiter._paused_until = 0
+
+ start_time = time.time()
+
+ class FloodError(Exception):
+ def __init__(self, seconds):
+ self.seconds = seconds
+ super().__init__(f"FloodWait for {seconds}s")
+
+ attempt = 0
+
+ async def task_that_fails_once():
+ nonlocal attempt
+ ts = time.time() - start_time
+ attempt += 1
+ if attempt == 1:
+ print(f"[{ts:.1f}s] First attempt: Simulating FloodWait(5s)")
+ raise FloodError(5)
+ print(f"[{ts:.1f}s] Second attempt: Success!")
+ return "success"
+
+ result = await limiter.enqueue(task_that_fails_once)
+ total_time = time.time() - start_time
+ print(f"Task completed with result: {result} in {total_time:.1f}s")
+
+ if total_time >= 5.0:
+ print("[SUCCESS] FloodWait recovery working as expected!")
+ else:
+ print(f"[FAILURE] FloodWait recovery failed! Took only {total_time:.1f}s")
+
+
+async def main():
+ await test_rate_limiting()
+ await test_flood_wait()
+ print("\nVerification complete.")
+ # Exit script
+ os._exit(0)
+
+
+if __name__ == "__main__":
+ asyncio.run(main())