| 1 | <!-- Parent: ../AGENTS.md --> |
| 2 | <!-- Generated: 2026-03-27 | Updated: 2026-03-27 --> |
| 3 | |
| 4 | # control |
| 5 | |
| 6 | ## Purpose |
| 7 | Concurrency and reliability primitives — rate limiting, retry with backoff, and async queue-based worker pool for parallel downloads. |
| 8 | |
| 9 | ## Key Files |
| 10 | |
| 11 | | File | Description | |
| 12 | |------|-------------| |
| 13 | | `__init__.py` | Exports `RateLimiter`, `RetryHandler`, `QueueManager` | |
| 14 | | `rate_limiter.py` | Token-bucket rate limiter with configurable requests/second | |
| 15 | | `retry_handler.py` | Exponential backoff retry with max attempts | |
| 16 | | `queue_manager.py` | Async queue with configurable worker count for concurrent downloads | |
| 17 | |
| 18 | ## For AI Agents |
| 19 | |
| 20 | ### Working In This Directory |
| 21 | - All three classes are instantiated in `cli/main.py` per download session |
| 22 | - `RateLimiter.acquire()` is awaited before every API call in strategies and downloaders |
| 23 | - `RetryHandler` wraps download operations with configurable `max_retries` |
| 24 | - `QueueManager` manages the worker pool (`max_workers` from `thread` config) |
| 25 | |
| 26 | ### Testing Requirements |
| 27 | - Tests: `tests/test_rate_limiter.py`, `tests/test_retry_handler.py` |
| 28 | |
| 29 | ### Common Patterns |
| 30 | - All classes are async-first (use `asyncio` primitives) |
| 31 | - Config values come from `ConfigLoader`: `rate_limit`, `retry_times`, `thread` |
| 32 | |
| 33 | ## Dependencies |
| 34 | |
| 35 | ### Internal |
| 36 | - None — self-contained async primitives |
| 37 | |
| 38 | ### External |
| 39 | - `asyncio` (stdlib) |
| 40 | |
| 41 | <!-- MANUAL: --> |
| 42 |