diff --git a/.cursor/plans/network-disk-optimizations-1658c482.plan.md b/.cursor/plans/network-disk-optimizations-1658c482.plan.md deleted file mode 100644 index 84e5fb5..0000000 --- a/.cursor/plans/network-disk-optimizations-1658c482.plan.md +++ /dev/null @@ -1,393 +0,0 @@ - -# Network and Disk I/O Optimization Implementation Plan - -## Analysis Summary - -### Network Bottlenecks Identified - -1. **Connection Management**: No effective reuse of peer connections; frequent connection establishment overhead -2. **HTTP Session Management**: aiohttp session not optimally configured for tracker requests -3. **Request Pipelining**: Limited pipeline depth (16) may not fully utilize high-bandwidth connections -4. **Socket Buffer Sizes**: Fixed sizes (256KB) may be suboptimal for modern high-speed networks -5. **DNS Resolution**: No DNS caching, causing repeated lookups for same trackers -6. **Write Buffer Management**: Ring buffer usage could be optimized -7. **Connection Pooling**: Connection pools exist but not fully utilized in async peer connections - -### Disk I/O Bottlenecks Identified - -1. **Write Batching**: 5ms timeout threshold too short; may flush prematurely on fast storage -2. **MMap Cache**: 128MB default may be too small for large torrents; eviction strategy too aggressive -3. **Checkpoint Frequency**: Saving on every piece completion creates I/O overhead -4. **Read-Ahead**: 64KB read-ahead may be insufficient for sequential reads -5. **I/O Queue Depth**: Default 200 may bottleneck on NVMe drives -6. **Hash Verification**: Parallel hash workers (4) may be insufficient for fast SSDs -7. **Direct I/O**: Not enabled by default; could improve performance on high-speed storage - -## Implementation Tasks - -### Phase 1: Network Optimizations - -#### Task 1.1: Enhance Connection Pooling and Reuse - -**File**: `ccbt/peer/connection_pool.py`, `ccbt/peer/async_peer_connection.py` - -- **Sub-Task 1.1.1**: Improve connection validation and health checks - - **Location**: `ccbt/peer/connection_pool.py:140-146` - - **Change**: Add connection liveness check using socket getsockopt(SO_ERROR) - - **Implementation**: - ```python - def _is_connection_valid(self, connection: Any) -> bool: - # Check socket state via getsockopt(SO_ERROR) - # Check if reader/writer are still valid - # Verify connection hasn't exceeded max idle time - ``` - -- **Sub-Task 1.1.2**: Implement connection warmup strategy - - **Location**: `ccbt/peer/connection_pool.py:234-256` - - **Change**: Pre-establish connections to frequently accessed peers - - **Implementation**: Add `warmup_connections()` method that creates connections for top N peers - -- **Sub-Task 1.1.3**: Add connection reuse metrics - - **Location**: `ccbt/peer/connection_pool.py:207-232` - - **Change**: Track reuse rate, average connection lifetime - - **Implementation**: Extend `get_pool_stats()` with reuse statistics - -- **Sub-Task 1.1.4**: Integrate connection pool with AsyncPeerConnectionManager - - **Location**: `ccbt/peer/async_peer_connection.py:387-451` - - **Change**: Use PeerConnectionPool in `_connect_to_peer()` before creating new connection - - **Implementation**: Check pool first, only create new connection if pool miss - -#### Task 1.2: Optimize HTTP Session Configuration for Trackers - -**File**: `ccbt/discovery/tracker.py:81-98` - -- **Sub-Task 1.2.1**: Configure connection limits and keepalive - - **Location**: `ccbt/discovery/tracker.py:81-98` - - **Change**: Set connector limits and enable connection pooling - - **Implementation**: - ```python - connector = aiohttp.TCPConnector( - limit=self.config.network.tracker_connection_limit, - limit_per_host=self.config.network.tracker_connections_per_host, - ttl_dns_cache=self.config.network.dns_cache_ttl, - keepalive_timeout=300, - enable_cleanup_closed=True - ) - ``` - -- **Sub-Task 1.2.2**: Implement DNS caching with TTL support - - **Location**: `ccbt/discovery/tracker.py:100-123` (new method) - - **Change**: Add DNS cache with TTL-based expiration - - **Implementation**: Create `DNSCache` class with asyncio-based caching - -- **Sub-Task 1.2.3**: Add HTTP session metrics - - **Location**: `ccbt/discovery/tracker.py:499-518` (extend existing method) - - **Change**: Track request/response times, connection reuse - - **Implementation**: Add metrics collection to `_make_request_async()` - -#### Task 1.3: Enhance Socket Buffer Management - -**File**: `ccbt/utils/network_optimizer.py:66-189` - -- **Sub-Task 1.3.1**: Implement adaptive buffer sizing - - **Location**: `ccbt/utils/network_optimizer.py:71-113` - - **Change**: Dynamically adjust buffer sizes based on network conditions - - **Implementation**: Add `_calculate_optimal_buffer_size()` method using BDP (Bandwidth-Delay Product) - -- **Sub-Task 1.3.2**: Add platform-specific buffer optimizations - - **Location**: `ccbt/utils/network_optimizer.py:116-189` - - **Change**: Use platform-specific maximum buffer sizes - - **Implementation**: Query system limits and set buffers accordingly (Linux: /proc/sys/net/core/rmem_max) - -- **Sub-Task 1.3.3**: Enable TCP window scaling - - **Location**: `ccbt/utils/network_optimizer.py:116-189` - - **Change**: Enable TCP window scaling for high-speed connections - - **Implementation**: Check and enable TCP window scaling option - -#### Task 1.4: Optimize Request Pipelining - -**File**: `ccbt/peer/async_peer_connection.py:145-198` - -- **Sub-Task 1.4.1**: Implement adaptive pipeline depth - - **Location**: `ccbt/peer/async_peer_connection.py:149` - - **Change**: Dynamically adjust `max_pipeline_depth` based on connection latency and bandwidth - - **Implementation**: Add `_calculate_pipeline_depth()` method using latency measurements - -- **Sub-Task 1.4.2**: Add request prioritization - - **Location**: `ccbt/peer/async_peer_connection.py:148` (request_queue) - - **Change**: Use priority queue instead of deque for request ordering - - **Implementation**: Replace `deque` with `heapq`-based priority queue, prioritize rarest pieces - -- **Sub-Task 1.4.3**: Implement request coalescing - - **Location**: `ccbt/peer/async_peer_connection.py:1454-1488` - - **Change**: Combine adjacent requests into single larger requests when possible - - **Implementation**: Add `_coalesce_requests()` method before sending - -#### Task 1.5: Improve Timeout and Retry Logic - -**File**: `ccbt/discovery/tracker.py:510-518`, `ccbt/peer/async_peer_connection.py:487-490` - -- **Sub-Task 1.5.1**: Implement exponential backoff with jitter - - **Location**: `ccbt/discovery/tracker.py:510-518` - - **Change**: Replace fixed backoff with exponential backoff + jitter - - **Implementation**: - ```python - backoff_delay = min(base_delay * (2 ** failure_count) + random.uniform(0, base_delay), max_delay) - ``` - -- **Sub-Task 1.5.2**: Add adaptive timeout calculation - - **Location**: `ccbt/peer/async_peer_connection.py:487-490` - - **Change**: Calculate timeout based on measured RTT - - **Implementation**: Use RTT * 3 for timeout calculation, with min/max bounds - -- **Sub-Task 1.5.3**: Implement circuit breaker pattern - - **Location**: `ccbt/utils/resilience.py` (new class) - - **Change**: Add CircuitBreaker for peer connections that repeatedly fail - - **Implementation**: Create `CircuitBreaker` class with open/half-open/closed states - -### Phase 2: Disk I/O Optimizations - -#### Task 2.1: Optimize Write Batching Strategy - -**File**: `ccbt/storage/disk_io.py:628-691` - -- **Sub-Task 2.1.1**: Implement adaptive batching timeout - - **Location**: `ccbt/storage/disk_io.py:654` - - **Change**: Adjust timeout based on storage device performance characteristics - - **Implementation**: Detect storage type (SSD/NVMe/HDD) and set timeout accordingly (NVMe: 0.1ms, SSD: 5ms, HDD: 50ms) - -- **Sub-Task 2.1.2**: Improve contiguous write detection - - **Location**: `ccbt/storage/disk_io.py:785-792` - - **Change**: More aggressive coalescing of near-contiguous writes - - **Implementation**: Extend `_combine_contiguous_writes()` to merge writes within threshold distance (e.g., 4KB) - -- **Sub-Task 2.1.3**: Add write-back caching awareness - - **Location**: `ccbt/storage/disk_io.py:794-898` - - **Change**: Detect if write-back cache is enabled and adjust flush strategy - - **Implementation**: Query OS for cache mode and optimize flush frequency - -- **Sub-Task 2.1.4**: Implement write queue prioritization - - **Location**: `ccbt/storage/disk_io.py:125` - - **Change**: Use priority queue for critical writes (checkpoints, metadata) - - **Implementation**: Replace `asyncio.Queue` with priority queue, prioritize by write type - -#### Task 2.2: Enhance MMap Cache Management - -**File**: `ccbt/storage/disk_io.py:129-131, 900-985` - -- **Sub-Task 2.2.1**: Implement LRU eviction with size awareness - - **Location**: `ccbt/storage/disk_io.py:912-940` - - **Change**: Replace simple LRU with size-aware eviction (evict large files first if needed) - - **Implementation**: Modify `_cache_cleaner()` to prefer evicting large, less-frequently-accessed files - -- **Sub-Task 2.2.2**: Add cache warmup on torrent start - - **Location**: `ccbt/storage/disk_io.py:950-985` (new method) - - **Change**: Pre-load frequently accessed files into mmap cache - - **Implementation**: Add `warmup_cache()` method that loads files in background - -- **Sub-Task 2.2.3**: Implement cache hit rate monitoring - - **Location**: `ccbt/storage/disk_io.py:605-613` - - **Change**: Track detailed cache statistics (hit rate, eviction rate, average access time) - - **Implementation**: Extend `get_cache_stats()` with comprehensive metrics - -- **Sub-Task 2.2.4**: Add adaptive cache size adjustment - - **Location**: `ccbt/storage/disk_io.py:130-132` - - **Change**: Dynamically adjust cache size based on available memory - - **Implementation**: Monitor system memory and adjust cache_size_bytes accordingly - -#### Task 2.3: Optimize Checkpoint I/O Operations - -**File**: `ccbt/storage/checkpoint.py:108-213` - -- **Sub-Task 2.3.1**: Implement incremental checkpoint saves - - **Location**: `ccbt/storage/checkpoint.py:108-152` - - **Change**: Only save changed pieces, not full checkpoint every time - - **Implementation**: Add diff calculation between current and last checkpoint state - -- **Sub-Task 2.3.2**: Optimize checkpoint compression - - **Location**: `ccbt/storage/checkpoint.py:274-310` - - **Change**: Use faster compression algorithm or compress in background thread - - **Implementation**: Use zstd instead of gzip for faster compression, or compress asynchronously - -- **Sub-Task 2.3.3**: Batch checkpoint writes - - **Location**: `ccbt/storage/checkpoint.py:204-213` - - **Change**: Batch multiple checkpoint updates into single write - - **Implementation**: Queue checkpoint saves and flush periodically (e.g., every 10 pieces or 5 seconds) - -- **Sub-Task 2.3.4**: Add checkpoint write deduplication - - **Location**: `ccbt/storage/checkpoint.py:154-213` - - **Change**: Skip checkpoint save if no meaningful changes since last save - - **Implementation**: Compare current state hash with last saved state hash - -#### Task 2.4: Enhance Read Operations - -**File**: `ccbt/storage/disk_io.py:534-604` - -- **Sub-Task 2.4.1**: Implement intelligent read-ahead - - **Location**: `ccbt/storage/disk_io.py:534-565` - - **Change**: Adaptive read-ahead size based on access pattern (sequential vs random) - - **Implementation**: Detect sequential access and increase read-ahead dynamically (up to 1MB for sequential) - -- **Sub-Task 2.4.2**: Add read prefetching for likely-next blocks - - **Location**: `ccbt/storage/disk_io.py:534-565` (new method) - - **Change**: Prefetch blocks that are likely to be requested next - - **Implementation**: Track access patterns and prefetch predicted blocks in background - -- **Sub-Task 2.4.3**: Optimize multi-file torrent reads - - **Location**: `ccbt/storage/file_assembler.py:547-589` - - **Change**: Parallelize reads across multiple file segments - - **Implementation**: Use `asyncio.gather()` to read multiple segments concurrently - -- **Sub-Task 2.4.4**: Add read buffer pooling - - **Location**: `ccbt/storage/disk_io.py:534-565` - - **Change**: Reuse read buffers to reduce allocations - - **Implementation**: Add buffer pool for read operations, similar to write staging buffers - -#### Task 2.5: Optimize I/O Queue and Worker Configuration - -**File**: `ccbt/storage/disk_io.py:99-122, 718-898` - -- **Sub-Task 2.5.1**: Implement adaptive worker count - - **Location**: `ccbt/storage/disk_io.py:119-122` - - **Change**: Dynamically adjust worker count based on I/O queue depth and system load - - **Implementation**: Monitor queue depth and spawn/remove workers as needed - -- **Sub-Task 2.5.2**: Add I/O priority management - - **Location**: `ccbt/storage/disk_io.py:772-898` - - **Change**: Set I/O priority for disk operations (Linux: ioprio_set) - - **Implementation**: Set real-time I/O class for critical operations on Linux - -- **Sub-Task 2.5.3**: Implement I/O scheduling optimization - - **Location**: `ccbt/storage/disk_io.py:728-771` - - **Change**: Sort writes by LBA (Logical Block Address) for optimal disk access - - **Implementation**: Add LBA calculation and sort writes by physical location before flushing - -- **Sub-Task 2.5.4**: Add NVMe-specific optimizations - - **Location**: `ccbt/storage/disk_io.py:213-236` - - **Change**: Detect NVMe and enable optimal settings (larger queue depth, multiple queues) - - **Implementation**: Extend `_detect_platform_capabilities()` to detect NVMe and configure accordingly - -#### Task 2.6: Enhance Hash Verification Performance - -**File**: `ccbt/models.py:736-758` (config), hash verification locations - -- **Sub-Task 2.6.1**: Implement parallel hash verification with work-stealing - - **Location**: Hash verification code (to be located) - - **Change**: Use thread pool with work-stealing for better load balancing - - **Implementation**: Replace fixed worker pool with dynamic work-stealing queue - -- **Sub-Task 2.6.2**: Add hash verification batching - - **Location**: Hash verification code - - **Change**: Batch multiple pieces for verification to reduce overhead - - **Implementation**: Group pieces and verify in batches using vectorized operations where possible - -- **Sub-Task 2.6.3**: Optimize hash chunk size - - **Location**: `ccbt/models.py:748-752` - - **Change**: Use larger chunks (1MB) for hash verification on fast storage - - **Implementation**: Detect storage speed and adjust chunk size dynamically - -### Phase 3: Configuration and Monitoring Enhancements - -#### Task 3.1: Add Performance Monitoring - -**File**: `ccbt/monitoring/metrics_collector.py` (existing), new metrics locations - -- **Sub-Task 3.1.1**: Add network performance metrics - - **Location**: Network components - - **Change**: Track connection establishment time, RTT, throughput per connection - - **Implementation**: Add metrics collection points in `AsyncPeerConnectionManager` - -- **Sub-Task 3.1.2**: Add disk I/O performance metrics - - **Location**: `ccbt/storage/disk_io.py:168-179` - - **Change**: Track I/O latency percentiles, queue depth, cache efficiency - - **Implementation**: Extend stats dictionary with detailed performance metrics - -- **Sub-Task 3.1.3**: Implement performance alerts - - **Location**: `ccbt/monitoring/alert_manager.py` (if exists) - - **Change**: Alert on performance degradation (high latency, low throughput) - - **Implementation**: Add thresholds and alert triggers for performance issues - -#### Task 3.2: Auto-Tuning Configuration - -**File**: `ccbt/config/config.py`, `ccbt/models.py` - -- **Sub-Task 3.2.1**: Add automatic buffer size tuning - - **Location**: Configuration initialization - - **Change**: Detect system capabilities and set optimal buffer sizes - - **Implementation**: Query system limits and set buffers to optimal values - -- **Sub-Task 3.2.2**: Implement storage device detection and tuning - - **Location**: `ccbt/storage/disk_io.py:210-236` - - **Change**: Detect storage type and apply optimal settings automatically - - **Implementation**: Extend detection to identify HDD/SSD/NVMe and configure accordingly - -- **Sub-Task 3.2.3**: Add adaptive configuration based on system resources - - **Location**: Configuration loading - - **Change**: Adjust worker counts, queue sizes based on CPU cores, RAM, storage speed - - **Implementation**: Query system resources and calculate optimal defaults - -### Phase 4: Advanced Optimizations - -#### Task 4.1: Implement Zero-Copy I/O Where Possible - -**File**: `ccbt/storage/disk_io.py:794-898` - -- **Sub-Task 4.1.1**: Use sendfile() for reading pieces to network - - **Location**: Piece serving code - - **Change**: Use OS-level zero-copy when sending data from disk to network - - **Implementation**: Use `os.sendfile()` on Linux/FreeBSD, `TransmitFile()` on Windows - -- **Sub-Task 4.1.2**: Optimize memoryview usage - - **Location**: `ccbt/storage/file_assembler.py:458-493` - - **Change**: Minimize copies by using memoryview consistently - - **Implementation**: Ensure all data operations use memoryview where possible - -#### Task 4.2: Implement io_uring Support (Linux) - -**File**: `ccbt/storage/disk_io.py:814-817` (config), new io_uring module - -- **Sub-Task 4.2.1**: Add io_uring backend - - **Location**: New file `ccbt/storage/io_uring_backend.py` - - **Change**: Implement async I/O using io_uring for Linux - - **Implementation**: Create io_uring-based I/O backend with submission/completion queues - -- **Sub-Task 4.2.2**: Integrate io_uring with DiskIOManager - - **Location**: `ccbt/storage/disk_io.py:794-898` - - **Change**: Use io_uring when available and enabled - - **Implementation**: Add fallback mechanism to thread pool if io_uring unavailable - -#### Task 4.3: Optimize Ring Buffer Usage - -**File**: `ccbt/storage/disk_io.py:133-145, 731-770` - -- **Sub-Task 4.3.1**: Improve ring buffer staging efficiency - - **Location**: `ccbt/storage/disk_io.py:731-770` - - **Change**: Better integration of ring buffer with write batching - - **Implementation**: Ensure ring buffer data is properly staged before flush - -- **Sub-Task 4.3.2**: Add ring buffer size tuning - - **Location**: `ccbt/storage/disk_io.py:134-145` - - **Change**: Dynamically size ring buffer based on write patterns - - **Implementation**: Monitor write sizes and adjust ring buffer accordingly - -## Implementation Order and Dependencies - -1. **Phase 1, Task 1.1-1.2** (Connection pooling, HTTP sessions) - Foundation for network optimizations -2. **Phase 2, Task 2.1-2.2** (Write batching, MMap cache) - High-impact disk optimizations -3. **Phase 1, Task 1.3-1.4** (Socket buffers, pipelining) - Performance improvements -4. **Phase 2, Task 2.3-2.4** (Checkpoints, reads) - Additional disk optimizations -5. **Phase 3** (Monitoring, auto-tuning) - Validation and fine-tuning -6. **Phase 4** (Advanced) - Cutting-edge optimizations - -## Testing Strategy - -- Performance benchmarks for each optimization -- Integration tests with real torrents -- Resource usage monitoring (CPU, memory, I/O) -- Regression testing to ensure no functionality loss - -## Estimated Impact - -- **Network**: 20-40% improvement in connection establishment, 15-30% throughput increase -- **Disk I/O**: 30-50% improvement in write throughput, 20-35% reduction in read latency -- **Overall**: 25-40% improvement in download speeds on fast connections \ No newline at end of file diff --git a/.cursor/rules/development-patterns.mdc b/.cursor/rules/development-patterns.mdc index 1d85da3..4d3f7dd 100644 --- a/.cursor/rules/development-patterns.mdc +++ b/.cursor/rules/development-patterns.mdc @@ -34,11 +34,22 @@ description: Development patterns and coding standards for ccBitTorrent - **Orchestration modules**: [`ccbt/cli/downloads.py`](mdc:ccbt/cli/downloads.py), [`ccbt/cli/status.py`](mdc:ccbt/cli/status.py), [`ccbt/cli/resume.py`](mdc:ccbt/cli/resume.py) bridge CLI→Session. ### Session Delegation Pattern -- `AsyncSessionManager` orchestrates; delegates to controllers: - - [`ccbt/session/announce.py`](mdc:ccbt/session/announce.py): Tracker announces - - [`ccbt/session/checkpointing.py`](mdc:ccbt/session/checkpointing.py): Checkpoint operations +- `AsyncTorrentSession` orchestrates; delegates to controllers: + - [`ccbt/session/lifecycle.py`](mdc:ccbt/session/lifecycle.py): Lifecycle sequencing (start/pause/resume/stop/cancel) + - [`ccbt/session/checkpointing.py`](mdc:ccbt/session/checkpointing.py): Checkpoint operations with fast resume support + - [`ccbt/session/status_aggregation.py`](mdc:ccbt/session/status_aggregation.py): Status collection and aggregation + - [`ccbt/session/announce.py`](mdc:ccbt/session/announce.py): Tracker announces (AnnounceLoop, AnnounceController) + - [`ccbt/session/metrics_status.py`](mdc:ccbt/session/metrics_status.py): Status monitoring loop (StatusLoop) + - [`ccbt/session/peers.py`](mdc:ccbt/session/peers.py): Peer management (PeerManagerInitializer, PeerConnectionHelper, PexBinder) + - [`ccbt/session/peer_events.py`](mdc:ccbt/session/peer_events.py): Peer event binding (PeerEventsBinder) + - [`ccbt/session/magnet_handling.py`](mdc:ccbt/session/magnet_handling.py): Magnet file selection (MagnetHandler) + - [`ccbt/session/dht_setup.py`](mdc:ccbt/session/dht_setup.py): DHT discovery setup (DiscoveryController) - [`ccbt/session/download_startup.py`](mdc:ccbt/session/download_startup.py): Download initialization - - [`ccbt/session/torrent_addition.py`](mdc:ccbt/session/torrent_addition.py): Torrent addition flow +- `AsyncSessionManager` orchestrates; delegates to managers: + - [`ccbt/session/torrent_addition.py`](mdc:ccbt/session/torrent_addition.py): Torrent addition flow (TorrentAdditionHandler) + - [`ccbt/session/manager_background.py`](mdc:ccbt/session/manager_background.py): Background tasks (ManagerBackgroundTasks) + - [`ccbt/session/scrape.py`](mdc:ccbt/session/scrape.py): Tracker scraping (ScrapeManager) + - [`ccbt/session/checkpoint_operations.py`](mdc:ccbt/session/checkpoint_operations.py): Manager-level checkpoint operations (CheckpointOperations) - [`ccbt/session/manager_startup.py`](mdc:ccbt/session/manager_startup.py): Component startup sequence ### Dependency Injection @@ -87,6 +98,14 @@ description: Development patterns and coding standards for ccBitTorrent - **Encryption support** for sensitive data - **IP filtering** via [`ccbt/security/security_manager.py`](mdc:ccbt/security/security_manager.py) +### Windows Path Resolution +- **CRITICAL**: Use `_get_daemon_home_dir()` helper from `ccbt/daemon/daemon_manager.py` for all daemon-related paths +- **Why**: Windows can resolve `Path.home()` or `os.path.expanduser("~")` differently in different processes, especially with spaces in usernames +- **Pattern**: Helper tries multiple methods (`expanduser`, `USERPROFILE`, `HOME`, `Path.home()`) and uses `Path.resolve()` for canonical path +- **Usage**: Always use helper instead of direct `Path.home()` or `os.path.expanduser("~")` for daemon PID files, state directories, config files +- **Files affected**: `DaemonManager`, `StateManager`, `IPCClient`, any code that reads/writes daemon PID file or state +- **Result**: Ensures daemon and CLI use same canonical path, preventing detection failures + ## Testing Patterns - **Markers**: Use pytest markers (`@pytest.mark.unit`, `@pytest.mark.integration`, etc.) defined in [`dev/pytest.ini`](mdc:dev/pytest.ini) - **Coverage target**: 99% project-wide, 90% patch (see [`dev/.codecov.yml`](mdc:dev/.codecov.yml)) diff --git a/.cursor/rules/documentation-standards.mdc b/.cursor/rules/documentation-standards.mdc index dc1b4eb..e539f9f 100644 --- a/.cursor/rules/documentation-standards.mdc +++ b/.cursor/rules/documentation-standards.mdc @@ -1,50 +1,137 @@ --- -description: Documentation standards and structure for ccBitTorrent (MkDocs, reports embedding) +description: Documentation standards and structure for ccBitTorrent (MkDocs, reports embedding, blog, multilingual) globs: "docs/**/*.md" --- # Documentation Standards ## Structure - Documentation in [`docs/`](mdc:docs/); site built with MkDocs using [`dev/mkdocs.yml`](mdc:dev/mkdocs.yml). -- Add new pages under `docs/`; update navigation in `dev/mkdocs.yml`. +- **Multilingual Structure**: Documentation organized by language in `docs//` directories (e.g., `docs/en/`, `docs/es/`, `docs/fr/`). +- **Default Language**: English content is in `docs/en/` (migrated from root `docs/`). +- Add new pages under appropriate language directory; update navigation in `dev/mkdocs.yml`. +- **Blog**: Blog posts located in `docs/blog/` with format `YYYY-MM-DD-slug.md`. + +## Multilingual Documentation + +### Language Support +- **Supported Languages**: English (en), Spanish (es), French (fr), Japanese (ja), Korean (ko), Hindi (hi), Urdu (ur), Persian (fa), Thai (th), Chinese (zh) +- **Default**: English (`docs/en/`) +- **Plugin**: Uses `mkdocs-static-i18n` plugin configured in [`dev/mkdocs.yml`](mdc:dev/mkdocs.yml) +- **Translation Guide**: See [`docs/en/i18n/translation-guide.md`](mdc:docs/en/i18n/translation-guide.md) for translation workflow + +### Creating Translations +1. Copy English version from `docs/en/` to target language directory +2. Translate content while preserving: + - Markdown formatting + - Code examples (keep in original language) + - File structure and organization + - Internal links (update paths to translated versions) +3. Test build: `uv run mkdocs build --strict -f dev/mkdocs.yml` +4. Verify language switcher functionality + +## Blog Functionality + +### Blog Structure +- **Location**: `docs/blog/` +- **Index**: `docs/blog/index.md` - Blog landing page +- **Posts**: Format `YYYY-MM-DD-slug.md` (e.g., `2024-01-01-welcome.md`) +- **Plugin**: `mkdocs-blog-plugin` configured in [`dev/mkdocs.yml`](mdc:dev/mkdocs.yml) + +### Creating Blog Posts +1. Create markdown file in `docs/blog/` with date prefix +2. Include frontmatter: + ```yaml + --- + title: Your Post Title + date: YYYY-MM-DD + author: Your Name + tags: + - tag1 + - tag2 + --- + ``` +3. Use `` to separate excerpt from full content +4. Follow existing blog post style +5. Test in documentation build + +### Blog Guidelines +- Keep posts relevant to ccBitTorrent +- Use clear, engaging language +- Include code examples where appropriate +- Add relevant tags for discoverability +- Link to related documentation ## Reports in Docs -- Coverage HTML must be placed under `docs/reports/coverage/` so it can be linked as `reports/coverage/index.html` in nav. -- Bandit JSON must be written to `docs/reports/bandit/bandit-report.json`. Render it in [`docs/reports/bandit/index.md`](mdc:docs/reports/bandit/index.md) using a fenced include: +- **Coverage HTML**: Must be placed under `docs/en/reports/coverage/` so it can be linked as `en/reports/coverage/index.html` in nav. +- **Bandit JSON**: Must be written to `docs/en/reports/bandit/bandit-report.json`. Render it in [`docs/en/reports/bandit/index.md`](mdc:docs/en/reports/bandit/index.md) using a fenced include: ```json --8<-- "reports/bandit/bandit-report.json" ``` ## Build -- Build docs: `uv run mkdocs build --strict -f dev/mkdocs.yml`. +- **Build Command**: `uv run mkdocs build --strict -f dev/mkdocs.yml` +- **Local Serve**: `uv run mkdocs serve -f dev/mkdocs.yml` +- **Pre-commit**: Documentation build runs automatically on markdown file changes +- **CI/CD**: Built in `.github/workflows/docs.yml` and deployed to GitHub Pages and Read the Docs -## Writing -- Use clear headers and short sections. -- Use relative links for internal pages. -- Provide bash/toml/python code blocks with syntax highlighting where appropriate. +## MkDocs Configuration ---- -globs: docs/**/*.md,*.md -description: Documentation standards and requirements ---- +### Plugins +- **i18n**: `mkdocs-static-i18n` for multilingual support +- **blog**: `mkdocs-blog-plugin` for blog functionality +- **mkdocstrings**: Python API documentation +- **git-revision-date-localized**: Last updated dates +- **codeinclude**: Include code snippets +- **coverage**: Coverage report integration -# Documentation Standards +### Material Theme Features +- Navigation: tabs, sections, expand, path, indexes, top, tracking +- Search: highlight, share, suggest +- Content: code copy, annotate, select, tabs.link, tooltips +- Language switcher: Automatic via i18n plugin + +### Navigation +- All navigation paths use language prefix (e.g., `en/index.md`, `en/getting-started.md`) +- Blog appears in main navigation as `blog/index.md` +- Update navigation in [`dev/mkdocs.yml`](mdc:dev/mkdocs.yml) `nav` section + +## Writing Standards + +### Markdown Formatting +- Use clear headers and short sections +- Use relative links for internal pages (within same language) +- Provide bash/toml/python code blocks with syntax highlighting +- Use Material theme features (admonitions, tabs, etc.) + +### Links +- **Internal Links**: Use relative paths within language directory + - `[Getting Started](getting-started.md)` (same directory) + - `[API Reference](../API.md)` (parent directory) +- **Cross-Language Links**: Use language prefix when linking to other languages + - `[English Version](../en/getting-started.md)` +- **Blog Links**: Use `../blog/` prefix from language directories + - `[Blog](../blog/index.md)` -## Documentation Structure -Located in [docs/](mdc:docs/) directory: +### Code Examples +- Keep code examples in original language (usually English) +- Translate comments in code examples if appropriate +- Preserve syntax highlighting +- Include working, tested examples -### Main Documentation -- **README**: [docs/README.md](mdc:docs/README.md) - Project overview and quick start -- **API Reference**: [docs/API.md](mdc:docs/API.md) - Complete API documentation -- **Migration Guide**: [MIGRATION.md](mdc:MIGRATION.md) - Migration from v1 to v2 +## Code Documentation Standards -### Code Documentation -- **Docstrings**: All public functions must have comprehensive docstrings +### Docstrings +- **All public functions** must have comprehensive docstrings - **Type Hints**: All functions must have complete type annotations - **Examples**: Include usage examples in docstrings - **API Documentation**: Document all public APIs +### Main Documentation Files +- **Index**: [`docs/en/index.md`](mdc:docs/en/index.md) - Project overview and quick start +- **API Reference**: [`docs/en/API.md`](mdc:docs/en/API.md) - Complete API documentation +- **Getting Started**: [`docs/en/getting-started.md`](mdc:docs/en/getting-started.md) - Installation and first steps + ## Documentation Requirements ### Function Documentation @@ -132,6 +219,13 @@ Functions: - **Data Flow**: Document data flow through the system - **Integration Points**: Document external integrations +## Documentation Maintenance +- **Keep Updated**: Update documentation with code changes +- **Version Control**: Track documentation changes +- **Review Process**: Review documentation changes +- **User Feedback**: Incorporate user feedback +- **Multilingual Sync**: Keep translations synchronized with English source +- **Blog Updates**: Regularly update blog with project news and features ## Code Examples ### Basic Usage @@ -182,4 +276,47 @@ async def main(): - **Keep Updated**: Update documentation with code changes - **Version Control**: Track documentation changes - **Review Process**: Review documentation changes -- **User Feedback**: Incorporate user feedback \ No newline at end of file +- **User Feedback**: Incorporate user feedback + +This module provides classes and functions for managing peer connections +in the BitTorrent protocol. It handles peer discovery, connection +establishment, message exchange, and connection lifecycle management. + +Classes: + Peer: Represents a peer connection + PeerConnection: Manages peer communication + PeerManager: Manages multiple peer connections + +Functions: + connect_to_peer: Establish connection to a peer + discover_peers: Discover peers via DHT or trackers +""" +``` + +## Documentation Standards + +### Markdown Formatting +- **Headers**: Use proper header hierarchy (H1, H2, H3) +- **Code Blocks**: Use syntax highlighting for code examples +- **Links**: Use relative links for internal documentation +- **Tables**: Use markdown tables for structured data + +### API Documentation +- **Complete Coverage**: Document all public APIs +- **Type Information**: Include parameter and return types +- **Examples**: Provide working code examples +- **Error Handling**: Document possible exceptions + +### Architecture Documentation +- **System Overview**: High-level system architecture +- **Component Diagrams**: Visual representation of components +- **Data Flow**: Document data flow through the system +- **Integration Points**: Document external integrations + +## Documentation Maintenance +- **Keep Updated**: Update documentation with code changes +- **Version Control**: Track documentation changes +- **Review Process**: Review documentation changes +- **User Feedback**: Incorporate user feedback +- **Multilingual Sync**: Keep translations synchronized with English source +- **Blog Updates**: Regularly update blog with project news and features \ No newline at end of file diff --git a/.cursor/rules/monitoring-observability.mdc b/.cursor/rules/monitoring-observability.mdc index b33e8dd..0fd1919 100644 --- a/.cursor/rules/monitoring-observability.mdc +++ b/.cursor/rules/monitoring-observability.mdc @@ -13,6 +13,18 @@ Located in [ccbt/monitoring/](mdc:ccbt/monitoring/) directory: - **System Metrics**: CPU, memory, disk, network I/O tracking - **Performance Metrics**: Download/upload speeds, piece completion, peer connections - **Real-time Collection**: Automatic metrics collection with configurable intervals +- **Connection Success Rate Tracking**: Tracks connection attempts and successes per peer and globally via `record_connection_attempt()` and `record_connection_success()`. Calculate success rate via `get_connection_success_rate(peer_key)`. +- **Enhanced Peer Metrics**: Per-peer metrics include: + - Piece-level performance: `piece_download_speeds`, `piece_download_times`, `pieces_per_second` + - Efficiency metrics: `bytes_per_connection`, `efficiency_score`, `bandwidth_utilization` + - Connection quality: `connection_quality_score`, `error_rate`, `success_rate`, `average_block_latency` + - Historical performance: `peak_download_rate`, `peak_upload_rate`, `performance_trend` +- **Enhanced Torrent Metrics**: Per-torrent metrics include: + - Swarm health: `piece_availability_distribution`, `average_piece_availability`, `rarest_piece_availability`, `swarm_health_score` + - Peer performance: `peer_performance_distribution`, `peer_download_speeds`, `average_peer_download_speed`, `median_peer_download_speed` + - Completion metrics: `piece_completion_rate`, `estimated_time_remaining`, `pieces_per_second_history` + - Swarm efficiency: `swarm_efficiency`, `peer_contribution_balance` +- **Global Metrics Aggregation**: `get_system_wide_efficiency()` calculates overall system efficiency, bandwidth utilization, connection efficiency, and resource utilization. `get_global_peer_metrics()` aggregates peer metrics across all torrents. ### Alert Management - **Alert Rules**: Rule-based alert system with conditions @@ -88,6 +100,17 @@ async def download_piece(piece_index: int): # ... implementation ... ``` +## IPC Integration + +**Metrics Endpoints**: IPC server exposes metrics via REST API: +- `GET /api/v1/metrics/peers` - Global peer metrics across all torrents +- `GET /api/v1/metrics/peers/{peer_key}` - Detailed metrics for specific peer +- `GET /api/v1/metrics/torrents/{info_hash}/detailed` - Detailed torrent metrics +- `GET /api/v1/metrics/global/detailed` - Detailed global metrics including connection success rate +- `GET /api/v1/peers/list` - Global list of all peers with comprehensive metrics + +**Metrics Exposure**: All enhanced metrics (peer performance, efficiency, connection quality, swarm health) are exposed via IPC endpoints for client monitoring and analysis. + ## Event Integration All monitoring components emit events for integration: - `MONITORING_STARTED` - Monitoring system started diff --git a/.cursor/rules/performance-optimization.mdc b/.cursor/rules/performance-optimization.mdc index 78c1375..a2c8ef2 100644 --- a/.cursor/rules/performance-optimization.mdc +++ b/.cursor/rules/performance-optimization.mdc @@ -34,6 +34,23 @@ Located in [ccbt/network_optimizer.py](mdc:ccbt/network_optimizer.py): - **Buffer Sizing**: Optimize socket buffer sizes based on BDP - **Connection Pooling**: Reuse connections for efficiency +### Adaptive Connection Limits +Located in [ccbt/peer/connection_pool.py](mdc:ccbt/peer/connection_pool.py): +- **Adaptive Limit Calculation**: `_calculate_adaptive_limit()` dynamically adjusts max connections based on: + - CPU usage (reduce if > threshold, default 80%) + - Memory usage (reduce if > threshold, default 80%) + - Peer performance (increase if peers performing well) + - Formula: `base_limit * cpu_factor * memory_factor * performance_factor` + - Bounded by `connection_pool_adaptive_limit_min` and `connection_pool_adaptive_limit_max` +- **Performance-Based Recycling**: Low-performing connections are recycled when: + - Performance score < threshold (default 0.3) + - Consecutive failures > max (default 5) + - Idle time > max_idle_time (default 300s) AND new peer available + - Bandwidth below minimum thresholds +- **Bandwidth Measurement**: Tracks download/upload bandwidth per connection with periodic updates (default 5s interval) +- **Progressive Health Degradation**: Connection health levels (HEALTHY, DEGRADED, UNHEALTHY) based on idle time, usage, errors, and bandwidth +- **Connection Quality Scoring**: `_calculate_connection_quality()` scores connections (0.0-1.0) based on bandwidth, latency, and error rate. Used to prefer high-quality connections in `acquire()`. + ```python class NetworkOptimizer: def optimize_socket(self, sock: socket.socket) -> None: @@ -96,11 +113,45 @@ class HashVerifier: - **Weak References**: Use weak references where appropriate - **Memory Profiling**: Profile memory usage for optimization +## Adaptive Algorithms + +### Adaptive Intervals +- **DHT Adaptive Intervals**: Located in [ccbt/discovery/dht.py](mdc:ccbt/discovery/dht.py). `_calculate_adaptive_interval()` adjusts DHT refresh intervals based on: + - Base interval from config + - Node quality and reachability + - Network conditions + - Bounded by `dht_adaptive_interval_min` and `dht_adaptive_interval_max` +- **Tracker Adaptive Intervals**: Located in [ccbt/discovery/tracker.py](mdc:ccbt/discovery/tracker.py). `_calculate_adaptive_interval()` adjusts announce intervals based on: + - Tracker performance (response time, success rate) + - Peer count from tracker + - Swarm health + - Bounded by `tracker_adaptive_interval_min` and `tracker_adaptive_interval_max` +- **Tracker Performance Ranking**: `rank_trackers()` sorts trackers by performance score considering: + - Response time (lower = better) + - Success rate (higher = better) + - Peer quality (average peer download rate) + - Recent failures + +### Bandwidth-Aware Optimizations +- **Request Prioritization**: Located in [ccbt/peer/async_peer_connection.py](mdc:ccbt/peer/async_peer_connection.py). `_calculate_request_priority()` incorporates peer download rate into priority calculation. `RequestInfo.bandwidth_estimate` stores estimated bandwidth for load balancing. +- **Request Load Balancing**: `_balance_requests_across_peers()` distributes requests proportionally based on peer bandwidth: + - Calculates total available bandwidth + - Distributes requests proportionally to each peer's share + - Considers peer pipeline capacity + - Handles edge cases gracefully +- **Bandwidth-Weighted Piece Selection**: Located in [ccbt/piece/async_piece_manager.py](mdc:ccbt/piece/async_piece_manager.py). Piece selection strategies consider peer download speeds when scoring pieces. + +### Performance-Based Peer Management +- **Peer Ranking**: `_rank_peers_for_connection()` ranks peers before connection based on historical performance, reputation, connection success rate, and source quality. +- **Peer Performance Evaluation**: `_evaluate_peer_performance()` calculates performance scores (0.0-1.0) from download rate, upload rate, latency, error rate, and connection stability. +- **Peer Recycling**: Low-performing peers are automatically recycled when better peers are available, improving overall swarm efficiency. + ## Performance Targets - **50% improvement** in download speed - **30% reduction** in memory usage - **40% improvement** in disk I/O throughput - **Sub-100ms** peer connection establishment +- **Adaptive algorithms** dynamically optimize based on real-time conditions ## Benchmarking - **Performance Tests**: Regular performance regression testing diff --git a/.cursor/rules/terminal_dashboard.mdc b/.cursor/rules/terminal_dashboard.mdc index a61bbd3..1dfc1ee 100644 --- a/.cursor/rules/terminal_dashboard.mdc +++ b/.cursor/rules/terminal_dashboard.mdc @@ -181,8 +181,57 @@ class Overview(Static): # type: ignore[misc] - Use `update()` method to change widget content - Use Rich library for formatting (Table, Panel, etc.) +- Use Rich `Text` for colored segments and complex formatting - Keep widgets focused on single responsibility - Export widgets through `widgets/__init__.py` +- **Always wrap user-facing strings** with `_()` for i18n + +### Health Bar Widgets + +For health monitoring widgets (e.g., piece availability), use colored segments: + +```python +from textual.widgets import Static +from rich.text import Text +from ccbt.i18n import _ + +class PieceAvailabilityHealthBar(Static): # type: ignore[misc] + """Widget to display piece availability as a colored health bar.""" + + DEFAULT_CSS = """ + PieceAvailabilityHealthBar { + height: 1; + width: 1fr; + } + """ + + def update_availability(self, availability: list[int], max_peers: int | None = None) -> None: + """Update health bar with piece availability data.""" + # Build colored bar with thin segments + bar_text = Text() + for peer_count in availability: + color = self._get_color_for_availability(peer_count) + bar_text.append("▌", style=color) # Thin bar character + + # Add summary label + label = Text() + label.append(f" {_('Health')}: ", style="cyan") + label.append(f"{availability_pct:.1f}%", style="green") + + full_text = Text() + full_text.append(bar_text) + full_text.append(" ") + full_text.append(label) + self.update(full_text) +``` + +### Color Coding Patterns + +- **Green**: High availability/health (≥70% or high value) +- **Yellow**: Medium availability/health (40-70%) +- **Orange**: Low availability/health (20-40%) +- **Red**: Very low availability/health (<20% or critical) +- **Gray**: Not available or no data ## Configuration Screens @@ -203,26 +252,64 @@ class SSLConfigScreen(ConfigScreen): # type: ignore[misc] # ccbt/interface/screens/config/widgets.py ``` -## Command Execution +## Data Access Pattern + +**CRITICAL**: The interface must use `DataProvider` for all read operations and `CommandExecutor` for all write operations. Never access session internals directly. -Use `CommandExecutor` from [ccbt/interface/commands/executor.py](mdc:ccbt/interface/commands/executor.py) to execute CLI commands: +### DataProvider Pattern + +Use `DataProvider` from [ccbt/interface/data_provider.py](mdc:ccbt/interface/data_provider.py) to access torrent data: + +```python +from ccbt.interface.data_provider import DataProvider + +class MyScreen(Screen): + def __init__(self, data_provider: DataProvider, *args, **kwargs): + super().__init__(*args, **kwargs) + self._data_provider = data_provider + + async def refresh_data(self): + """Refresh data using DataProvider.""" + # Read operations use DataProvider + stats = await self._data_provider.get_global_stats() + torrents = await self._data_provider.list_torrents() + status = await self._data_provider.get_torrent_status(info_hash) + peers = await self._data_provider.get_torrent_peers(info_hash) + files = await self._data_provider.get_torrent_files(info_hash) + trackers = await self._data_provider.get_torrent_trackers(info_hash) + availability = await self._data_provider.get_torrent_piece_availability(info_hash) + metrics = await self._data_provider.get_metrics() +``` + +### CommandExecutor Pattern + +Use `CommandExecutor` from [ccbt/interface/commands/executor.py](mdc:ccbt/interface/commands/executor.py) for all write operations: ```python from ccbt.interface.commands.executor import CommandExecutor class MyScreen(Screen): - def __init__(self, session, *args, **kwargs): + def __init__(self, data_provider: DataProvider, command_executor: CommandExecutor, *args, **kwargs): super().__init__(*args, **kwargs) - self.session = session - self._command_executor = CommandExecutor(session) + self._data_provider = data_provider + self._command_executor = command_executor - async def action_some_command(self): - """Execute a CLI command.""" + async def action_pause_torrent(self): + """Pause torrent using executor.""" result = await self._command_executor.execute_command( - "download", ["--torrent", "path/to/file.torrent"] + "torrent.pause", info_hash=info_hash ) + if result and hasattr(result, "success") and result.success: + self.app.notify("Torrent paused", severity="success") ``` +### Daemon Access Rules + +- **Read operations**: Always use `DataProvider` methods (never direct IPC client calls) +- **Write operations**: Always use `CommandExecutor.execute_command()` (never direct session calls) +- **Never access**: `self.session` internals directly when using daemon +- **Exception**: Local sessions can access `self.session` directly, but prefer DataProvider/Executor for consistency + ## Module Exports ### Widgets Module @@ -310,9 +397,65 @@ content.update(Panel(table, title="System Resources")) - Test fallback behavior when Textual is unavailable +## i18n Integration + +### String Wrapping + +All user-facing strings must be wrapped with `_()`: + +```python +from ccbt.i18n import _ + +# In bindings +BINDINGS: ClassVar[list[tuple[str, str, str]]] = [ + ("p", "pause", _("Pause")), + ("r", "resume", _("Resume")), +] + +# In notifications +self.app.notify(_("Torrent paused"), severity="success") + +# In table headers +table.add_column(_("Name"), style="cyan") + +# In widget labels +label.append(f" {_('Health')}: ", style="cyan") +``` + +### Language Selector + +Use `LanguageSelectorWidget` from [ccbt/interface/widgets/language_selector.py](mdc:ccbt/interface/widgets/language_selector.py) to allow users to change interface language: + +```python +from ccbt.interface.widgets.language_selector import LanguageSelectorWidget + +def compose(self) -> ComposeResult: + with Vertical(): + yield LanguageSelectorWidget(data_provider, command_executor) +``` + +## Tabbed Interface Structure + +The interface uses a tabbed structure with nested tabs: + +### Main Tabs + +1. **Torrents Tab**: Lists all torrents with nested sub-tabs (global, downloading, seeding, completed, active, inactive) +2. **Per-Torrent Tab**: Detailed view for selected torrent with sub-tabs (files, info, peers, trackers, graphs, config) +3. **Graphs Tab**: Global statistics and graphs (always visible in top half) +4. **Preferences Tab**: Configuration with nested sub-tabs + +### Container vs Screen + +- **Container widgets**: Used for tab content (e.g., `TorrentsTabContent`, `PerTorrentTabContent`) +- **Screen classes**: Used for full-screen overlays (e.g., `AddTorrentScreen`, `ConfigScreen`) +- **Never embed Screen in Container**: Use wrapper widgets (`MonitoringScreenWrapper`, `ConfigScreenWrapper`) to extract data from screens + ## References - Main dashboard: [ccbt/interface/terminal_dashboard.py](mdc:ccbt/interface/terminal_dashboard.py) +- Data provider: [ccbt/interface/data_provider.py](mdc:ccbt/interface/data_provider.py) +- Command executor: [ccbt/interface/commands/executor.py](mdc:ccbt/interface/commands/executor.py) - Base screens: [ccbt/interface/screens/base.py](mdc:ccbt/interface/screens/base.py) - Widgets: [ccbt/interface/widgets/](mdc:ccbt/interface/widgets/) - Textual docs: https://textual.textualize.io/ diff --git a/.env copy b/.env copy new file mode 100644 index 0000000..471d3b6 --- /dev/null +++ b/.env copy @@ -0,0 +1,469 @@ +# ccBitTorrent Environment Variables Configuration +# Copy this file to .env and modify values as needed +# All variables are prefixed with CCBT_ to avoid conflicts + +# ============================================================================= +# NETWORK CONFIGURATION +# ============================================================================= + +# Connection limits +CCBT_MAX_PEERS=200 # Maximum global peers (1-10000) +CCBT_MAX_PEERS_PER_TORRENT=50 # Maximum peers per torrent (1-1000) +CCBT_MAX_CONNECTIONS_PER_PEER=1 # Max parallel connections per peer (1-8) + +# Request pipeline settings +CCBT_PIPELINE_DEPTH=16 # Request pipeline depth (1-128) +CCBT_BLOCK_SIZE_KIB=16 # Block size in KiB (1-64) +CCBT_MIN_BLOCK_SIZE_KIB=4 # Minimum block size in KiB (1-64) +CCBT_MAX_BLOCK_SIZE_KIB=64 # Maximum block size in KiB (1-1024) + +# Socket tuning +CCBT_SOCKET_RCVBUF_KIB=256 # Socket receive buffer size in KiB (1-65536) +CCBT_SOCKET_SNDBUF_KIB=256 # Socket send buffer size in KiB (1-65536) +CCBT_TCP_NODELAY=true # Enable TCP_NODELAY (true/false) + +# Timeouts (seconds) +CCBT_CONNECTION_TIMEOUT=30.0 # Connection timeout (1.0-300.0) +CCBT_HANDSHAKE_TIMEOUT=10.0 # Handshake timeout (1.0-60.0) +CCBT_KEEP_ALIVE_INTERVAL=120.0 # Keep alive interval (30.0-600.0) +CCBT_PEER_TIMEOUT=60.0 # Peer inactivity timeout (5.0-600.0) +CCBT_DHT_TIMEOUT=2.0 # DHT request timeout (1.0-60.0) + +# Listen settings +CCBT_LISTEN_PORT=6881 # Listen port (1024-65535) +CCBT_LISTEN_INTERFACE=0.0.0.0 # Listen interface +CCBT_ENABLE_IPV6=true # Enable IPv6 support (true/false) +CCBT_XET_PORT= # XET protocol port (uses listen_port_udp if not set) (1024-65535) +CCBT_XET_MULTICAST_ADDRESS=239.255.255.250 # XET multicast address for local network discovery +CCBT_XET_MULTICAST_PORT=6882 # XET multicast port (1024-65535) + +# Transport protocols +CCBT_ENABLE_TCP=true # Enable TCP transport (true/false) +CCBT_ENABLE_UTP=false # Enable uTP transport (true/false) +CCBT_ENABLE_ENCRYPTION=false # Enable protocol encryption (true/false) + +# uTP (uTorrent Transport Protocol) Configuration (BEP 29) +CCBT_UTP_PREFER_OVER_TCP=true # Prefer uTP over TCP when both are supported (true/false) +CCBT_UTP_CONNECTION_TIMEOUT=30.0 # uTP connection timeout in seconds (5.0-300.0) +CCBT_UTP_MAX_WINDOW_SIZE=65535 # Maximum uTP receive window size in bytes (8192-65535) +CCBT_UTP_MTU=1200 # uTP MTU size (maximum UDP packet size) (576-65507) +CCBT_UTP_INITIAL_RATE=1500 # Initial send rate in bytes/second (1024-100000) +CCBT_UTP_MIN_RATE=512 # Minimum send rate in bytes/second (256-10000) +CCBT_UTP_MAX_RATE=1000000 # Maximum send rate in bytes/second (10000-10000000) +CCBT_UTP_ACK_INTERVAL=0.1 # ACK packet send interval in seconds (0.01-1.0) +CCBT_UTP_RETRANSMIT_TIMEOUT_FACTOR=4.0 # RTT multiplier for retransmit timeout (2.0-10.0) +CCBT_UTP_MAX_RETRANSMITS=10 # Maximum retransmission attempts before connection failure (3-50) + +# Choking strategy +CCBT_MAX_UPLOAD_SLOTS=4 # Maximum upload slots (1-20) +CCBT_OPTIMISTIC_UNCHOKE_INTERVAL=30.0 # Optimistic unchoke interval (1.0-600.0) +CCBT_UNCHOKE_INTERVAL=10.0 # Unchoke interval (1.0-600.0) + +# IMPROVEMENT: Choking optimization weights +CCBT_CHOKING_UPLOAD_RATE_WEIGHT=0.6 # Weight for upload rate in choking/unchoking decisions (0.0-1.0) +CCBT_CHOKING_DOWNLOAD_RATE_WEIGHT=0.4 # Weight for download rate in choking/unchoking decisions (0.0-1.0) +CCBT_CHOKING_PERFORMANCE_SCORE_WEIGHT=0.2 # Weight for performance score in choking/unchoking decisions (0.0-1.0) + +# IMPROVEMENT: Peer quality ranking weights +CCBT_PEER_QUALITY_PERFORMANCE_WEIGHT=0.4 # Weight for historical performance in peer quality ranking (0.0-1.0) +CCBT_PEER_QUALITY_SUCCESS_RATE_WEIGHT=0.2 # Weight for connection success rate in peer quality ranking (0.0-1.0) +CCBT_PEER_QUALITY_SOURCE_WEIGHT=0.2 # Weight for source quality in peer quality ranking (0.0-1.0) +CCBT_PEER_QUALITY_PROXIMITY_WEIGHT=0.2 # Weight for geographic proximity in peer quality ranking (0.0-1.0) + +# Rate limiting (KiB/s, 0 = unlimited) +CCBT_GLOBAL_DOWN_KIB=0 # Global download limit (0+) +CCBT_GLOBAL_UP_KIB=0 # Global upload limit (0+) +CCBT_PER_PEER_DOWN_KIB=0 # Per-peer download limit (0+) +CCBT_PER_PEER_UP_KIB=0 # Per-peer upload limit (0+) + +# Tracker settings +CCBT_TRACKER_TIMEOUT=30.0 # Tracker request timeout (5.0-120.0) +CCBT_TRACKER_CONNECT_TIMEOUT=10.0 # Tracker connection timeout (1.0-60.0) +CCBT_TRACKER_CONNECTION_LIMIT=50 # Maximum tracker connections (1-200) +CCBT_TRACKER_CONNECTIONS_PER_HOST=10 # Max connections per tracker host (1-50) +CCBT_DNS_CACHE_TTL=300 # DNS cache TTL in seconds (60-3600) + +# Connection pool settings +CCBT_CONNECTION_POOL_GRACE_PERIOD=60.0 # Grace period in seconds for new connections before quality checks (allows time for bandwidth establishment) (0.0-600.0) + +# Connection health and failure management (BitTorrent spec compliant) +CCBT_MAX_CONCURRENT_CONNECTION_ATTEMPTS=20 # Maximum concurrent connection attempts to prevent OS socket exhaustion (5-100) +CCBT_CONNECTION_FAILURE_THRESHOLD=3 # Number of consecutive failures before applying backoff to a peer (1-10) +CCBT_CONNECTION_FAILURE_BACKOFF_BASE=2.0 # Exponential backoff base multiplier for connection failures (1.0-10.0) +CCBT_CONNECTION_FAILURE_BACKOFF_MAX=300.0 # Maximum backoff delay in seconds for failed connection attempts (60.0-3600.0) +CCBT_ENABLE_FAIL_FAST_DHT=true # Enable fail-fast DHT trigger when active_peers == 0 for >30s (allows DHT even if <50 peers) +CCBT_FAIL_FAST_DHT_TIMEOUT=30.0 # Timeout in seconds before triggering fail-fast DHT when active_peers == 0 (10.0-120.0) + +# BitTorrent Protocol v2 (BEP 52) settings +CCBT_PROTOCOL_V2_ENABLE=true # Enable BitTorrent Protocol v2 support (BEP 52) (true/false) +CCBT_PROTOCOL_V2_PREFER=false # Prefer v2 protocol when both v1 and v2 are available (true/false) +CCBT_PROTOCOL_V2_SUPPORT_HYBRID=true # Support hybrid torrents (both v1 and v2 metadata) (true/false) +CCBT_PROTOCOL_V2_HANDSHAKE_TIMEOUT=30.0 # v2 handshake timeout in seconds (5.0-300.0) + +# ============================================================================= +# DISK CONFIGURATION +# ============================================================================= + +# Preallocation strategy: none, sparse, full, fallocate +CCBT_PREALLOCATE=full # Preallocation strategy +CCBT_SPARSE_FILES=false # Use sparse files if supported (true/false) + +# Write optimization +CCBT_WRITE_BATCH_KIB=64 # Write batch size in KiB (1-1024) +CCBT_WRITE_BUFFER_KIB=1024 # Write buffer size in KiB (0-65536) +CCBT_USE_MMAP=true # Use memory mapping (true/false) +CCBT_MMAP_CACHE_MB=128 # Memory-mapped cache size in MB (16-2048) +CCBT_MMAP_CACHE_CLEANUP_INTERVAL=30.0 # MMap cache cleanup interval (1.0-300.0) + +# Hash verification +CCBT_HASH_WORKERS=4 # Number of hash verification workers (1-32) +CCBT_HASH_CHUNK_SIZE=65536 # Chunk size for hash verification (1024-1048576) +CCBT_HASH_BATCH_SIZE=4 # Number of pieces to verify in parallel batches (1-64) +CCBT_HASH_QUEUE_SIZE=100 # Hash verification queue size (10-500) + +# I/O threading +CCBT_DISK_WORKERS=2 # Number of disk I/O workers (1-16) +CCBT_DISK_QUEUE_SIZE=200 # Disk I/O queue size (10-1000) +CCBT_CACHE_SIZE_MB=256 # Cache size in MB (16-4096) + +# Advanced settings +CCBT_DIRECT_IO=false # Use direct I/O (true/false) +CCBT_SYNC_WRITES=false # Synchronize writes (true/false) +CCBT_READ_AHEAD_KIB=64 # Read ahead size in KiB (0-1024) +CCBT_ENABLE_IO_URING=false # Enable io_uring on Linux if available (true/false) +CCBT_DOWNLOAD_PATH= # Default download path + +# Checkpoint settings +CCBT_CHECKPOINT_ENABLED=true # Enable download checkpointing (true/false) +CCBT_CHECKPOINT_FORMAT=both # Checkpoint file format (json/binary/both) +CCBT_CHECKPOINT_DIR= # Checkpoint directory (defaults to download_dir/.ccbt/checkpoints) +CCBT_CHECKPOINT_INTERVAL=30.0 # Checkpoint save interval in seconds (1.0-3600.0) +CCBT_CHECKPOINT_ON_PIECE=true # Save checkpoint after each verified piece (true/false) +CCBT_AUTO_RESUME=true # Automatically resume from checkpoint on startup (true/false) +CCBT_CHECKPOINT_COMPRESSION=true # Compress binary checkpoint files (true/false) +CCBT_AUTO_DELETE_CHECKPOINT_ON_COMPLETE=true # Auto-delete checkpoint when download completes (true/false) +CCBT_CHECKPOINT_RETENTION_DAYS=30 # Days to retain checkpoints before cleanup (1-365) + +# Fast Resume settings +CCBT_FAST_RESUME_ENABLED=true # Enable fast resume support (true/false) +CCBT_RESUME_SAVE_INTERVAL=30.0 # Interval to save resume data in seconds (1.0-3600.0) +CCBT_RESUME_VERIFY_ON_LOAD=true # Verify resume data integrity on load (true/false) +CCBT_RESUME_VERIFY_PIECES=10 # Number of pieces to verify on resume (0-100, 0 = disable) +CCBT_RESUME_DATA_FORMAT_VERSION=1 # Resume data format version (1-100) + +# BEP 47: File Attributes Configuration +CCBT_ATTRIBUTES_PRESERVE_ATTRIBUTES=true # Preserve file attributes (executable, hidden, symlinks) (true/false) +CCBT_ATTRIBUTES_SKIP_PADDING_FILES=true # Skip downloading padding files (BEP 47) (true/false) +CCBT_ATTRIBUTES_VERIFY_FILE_SHA1=false # Verify file SHA-1 hashes when provided (BEP 47) (true/false) +CCBT_ATTRIBUTES_APPLY_SYMLINKS=true # Create symlinks for files with attr='l' (true/false) +CCBT_ATTRIBUTES_APPLY_EXECUTABLE_BIT=true # Set executable bit for files with attr='x' (true/false) +CCBT_ATTRIBUTES_APPLY_HIDDEN_ATTR=true # Apply hidden attribute for files with attr='h' (Windows) (true/false) + +# XET Protocol Configuration +CCBT_XET_ENABLED=false # Enable Xet protocol for content-defined chunking and deduplication (true/false) +CCBT_XET_CHUNK_MIN_SIZE=8192 # Minimum Xet chunk size in bytes +CCBT_XET_CHUNK_MAX_SIZE=131072 # Maximum Xet chunk size in bytes +CCBT_XET_CHUNK_TARGET_SIZE=16384 # Target Xet chunk size in bytes +CCBT_XET_DEDUPLICATION_ENABLED=true # Enable chunk-level deduplication (true/false) +CCBT_XET_CACHE_DB_PATH= # Path to Xet deduplication cache database +CCBT_XET_CHUNK_STORE_PATH= # Path to Xet chunk storage directory +CCBT_XET_USE_P2P_CAS=true # Use peer-to-peer Content Addressable Storage (DHT-based) (true/false) +CCBT_XET_COMPRESSION_ENABLED=false # Enable LZ4 compression for stored chunks (true/false) + +# ============================================================================= +# STRATEGY CONFIGURATION +# ============================================================================= + +# Piece selection strategy: round_robin, rarest_first, sequential +CCBT_PIECE_SELECTION=rarest_first # Piece selection strategy +CCBT_ENDGAME_DUPLICATES=2 # Endgame duplicate requests (1-10) +CCBT_ENDGAME_THRESHOLD=0.95 # Endgame mode threshold (0.1-1.0) +CCBT_STREAMING_MODE=false # Enable streaming mode (true/false) + +# Advanced strategy settings +CCBT_RAREST_FIRST_THRESHOLD=0.1 # Rarest first threshold (0.0-1.0) +CCBT_SEQUENTIAL_WINDOW=10 # Sequential window size (1-100) +CCBT_SEQUENTIAL_PRIORITY_FILES= # File paths to prioritize in sequential mode (comma-separated, optional) +CCBT_SEQUENTIAL_FALLBACK_THRESHOLD=0.1 # Fallback to rarest-first if availability < threshold (0.0-1.0) +CCBT_PIPELINE_CAPACITY=4 # Request pipeline capacity (1-32) + +# Piece priorities +CCBT_FIRST_PIECE_PRIORITY=true # Prioritize first piece (true/false) +CCBT_LAST_PIECE_PRIORITY=false # Prioritize last piece (true/false) + +# ============================================================================= +# DISCOVERY CONFIGURATION +# ============================================================================= + +# DHT settings +CCBT_ENABLE_DHT=true # Enable DHT (true/false) +CCBT_DHT_PORT=6882 # DHT port (1024-65535) +# DHT bootstrap nodes (comma-separated) +CCBT_DHT_BOOTSTRAP_NODES=router.bittorrent.com:6881,dht.transmissionbt.com:6881,router.utorrent.com:6881,dht.libtorrent.org:25401,dht.aelitis.com:6881,router.silotis.us:6881,router.bitcomet.com:6881 + +# BEP 32: IPv6 Extension for DHT +CCBT_DHT_ENABLE_IPV6=true # Enable IPv6 DHT support (BEP 32) (true/false) +CCBT_DHT_PREFER_IPV6=true # Prefer IPv6 addresses over IPv4 when available (true/false) +# IPv6 DHT bootstrap nodes (comma-separated, format: [hostname:port or [IPv6]:port]) +CCBT_DHT_IPV6_BOOTSTRAP_NODES= + +# BEP 43: Read-only DHT Nodes +CCBT_DHT_READONLY_MODE=false # Enable read-only DHT mode (BEP 43) (true/false) + +# BEP 45: Multiple-Address Operation for DHT +CCBT_DHT_ENABLE_MULTIADDRESS=true # Enable multi-address support (BEP 45) (true/false) +CCBT_DHT_MAX_ADDRESSES_PER_NODE=4 # Maximum addresses to track per node (BEP 45) (1-16) + +# BEP 44: Storing Arbitrary Data in the DHT +CCBT_DHT_ENABLE_STORAGE=false # Enable DHT storage (BEP 44) (true/false) +CCBT_DHT_STORAGE_TTL=3600 # Storage TTL in seconds (BEP 44) (60-86400) +CCBT_DHT_MAX_STORAGE_SIZE=1000 # Maximum storage value size in bytes (BEP 44) (100-10000) + +# BEP 51: DHT Infohash Indexing +CCBT_DHT_ENABLE_INDEXING=true # Enable infohash indexing (BEP 51) (true/false) +CCBT_DHT_INDEX_SAMPLES_PER_KEY=8 # Maximum samples per index key (BEP 51) (1-100) + +# XET chunk discovery settings +CCBT_XET_CHUNK_QUERY_BATCH_SIZE=50 # Batch size for parallel chunk queries (1-200) +CCBT_XET_CHUNK_QUERY_MAX_CONCURRENT=50 # Maximum concurrent chunk queries (1-200) +CCBT_DISCOVERY_CACHE_TTL=60.0 # Discovery result cache TTL in seconds (1.0-3600.0) + +# PEX settings +CCBT_ENABLE_PEX=true # Enable Peer Exchange (true/false) +CCBT_PEX_INTERVAL=30.0 # Peer Exchange announce interval in seconds (5.0-3600.0) + +# Tracker settings +CCBT_ENABLE_HTTP_TRACKERS=true # Enable HTTP trackers (true/false) +CCBT_ENABLE_UDP_TRACKERS=true # Enable UDP trackers (true/false) +CCBT_TRACKER_ANNOUNCE_INTERVAL=1800.0 # Tracker announce interval in seconds (60.0-86400.0) +CCBT_TRACKER_SCRAPE_INTERVAL=3600.0 # Tracker scrape interval in seconds (60.0-86400.0) +CCBT_TRACKER_AUTO_SCRAPE=false # Automatically scrape trackers when adding torrents (true/false) +# Default trackers for magnet links without tr= parameters (comma-separated) +CCBT_DEFAULT_TRACKERS=https://tracker.opentrackr.org:443/announce,https://tracker.torrent.eu.org:443/announce,https://tracker.openbittorrent.com:443/announce,http://tracker.opentrackr.org:1337/announce,http://tracker.openbittorrent.com:80/announce,udp://tracker.opentrackr.org:1337/announce,udp://tracker.openbittorrent.com:80/announce + +# Private torrent settings (BEP 27) +CCBT_STRICT_PRIVATE_MODE=true # Enforce strict BEP 27 rules for private torrents (true/false) + +# IMPROVEMENT: Aggressive discovery for popular torrents +CCBT_AGGRESSIVE_DISCOVERY_POPULAR_THRESHOLD=20 # Minimum peer count to enable aggressive discovery mode (5-100) +CCBT_AGGRESSIVE_DISCOVERY_ACTIVE_THRESHOLD_KIB=1.0 # Minimum download rate (KB/s) to enable aggressive discovery mode (0.1-100.0) +CCBT_AGGRESSIVE_DISCOVERY_INTERVAL_POPULAR=10.0 # DHT query interval in seconds for popular torrents (20+ peers) (5.0-60.0) +CCBT_AGGRESSIVE_DISCOVERY_INTERVAL_ACTIVE=5.0 # DHT query interval in seconds for actively downloading torrents (>1KB/s) (2.0-30.0) +CCBT_AGGRESSIVE_DISCOVERY_MAX_PEERS_PER_QUERY=100 # Maximum peers to query per DHT query in aggressive mode (50-500) + +# DHT query parameters (Kademlia algorithm) +CCBT_DHT_NORMAL_ALPHA=5 # Number of parallel queries for normal DHT lookups (BEP 5 alpha parameter) (3-20) +CCBT_DHT_NORMAL_K=16 # Bucket size for normal DHT lookups (BEP 5 k parameter) (8-64) +CCBT_DHT_NORMAL_MAX_DEPTH=12 # Maximum depth for normal DHT iterative lookups (3-30) +CCBT_DHT_AGGRESSIVE_ALPHA=8 # Number of parallel queries for aggressive DHT lookups (BEP 5 alpha parameter) (5-30) +CCBT_DHT_AGGRESSIVE_K=32 # Bucket size for aggressive DHT lookups (BEP 5 k parameter) (16-128) +CCBT_DHT_AGGRESSIVE_MAX_DEPTH=15 # Maximum depth for aggressive DHT iterative lookups (5-50) + +# ============================================================================= +# OBSERVABILITY CONFIGURATION +# ============================================================================= + +# Logging +CCBT_LOG_LEVEL=INFO # Log level (DEBUG/INFO/WARNING/ERROR/CRITICAL) +CCBT_LOG_FILE= # Log file path (empty = stdout) +CCBT_LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s # Log format string +CCBT_STRUCTURED_LOGGING=true # Use structured logging (true/false) +CCBT_LOG_CORRELATION_ID=true # Include correlation IDs (true/false) + +# Metrics +CCBT_ENABLE_METRICS=true # Enable metrics collection (true/false) +CCBT_METRICS_PORT=9090 # Metrics port (1024-65535) +CCBT_METRICS_INTERVAL=5.0 # Metrics collection interval in seconds (0.5-3600.0) + +# Tracing +CCBT_ENABLE_PEER_TRACING=false # Enable peer tracing (true/false) +CCBT_TRACE_FILE= # Path to write traces (empty = disabled) +CCBT_ALERTS_RULES_PATH=.ccbt/alerts.json # Path to alert rules JSON file + +# Event bus configuration +CCBT_EVENT_BUS_MAX_QUEUE_SIZE=10000 # Maximum size of event queue (100-1000000) +CCBT_EVENT_BUS_BATCH_SIZE=50 # Maximum number of events to process per batch (1-1000) +CCBT_EVENT_BUS_BATCH_TIMEOUT=0.05 # Timeout in seconds to wait when collecting a batch (0.001-1.0) +CCBT_EVENT_BUS_EMIT_TIMEOUT=0.01 # Timeout in seconds when trying to emit to a full queue (0.001-1.0) +CCBT_EVENT_BUS_QUEUE_FULL_THRESHOLD=0.9 # Queue fullness threshold (0.0-1.0) for dropping low-priority events (0.1-1.0) +CCBT_EVENT_BUS_THROTTLE_DHT_NODE_FOUND=0.1 # Throttle interval for dht_node_found events in seconds (max 10/sec) (0.001-10.0) +CCBT_EVENT_BUS_THROTTLE_DHT_NODE_ADDED=0.1 # Throttle interval for dht_node_added events in seconds (max 10/sec) (0.001-10.0) +CCBT_EVENT_BUS_THROTTLE_MONITORING_HEARTBEAT=1.0 # Throttle interval for monitoring_heartbeat events in seconds (max 1/sec) (0.1-60.0) +CCBT_EVENT_BUS_THROTTLE_GLOBAL_METRICS_UPDATE=0.5 # Throttle interval for global_metrics_update events in seconds (max 2/sec) (0.1-10.0) + +# ============================================================================= +# LIMITS CONFIGURATION +# ============================================================================= + +# Global rate limits (KiB/s, 0 = unlimited) +CCBT_LIMITS_GLOBAL_DOWN_KIB=0 # Global download limit (0+) +CCBT_LIMITS_GLOBAL_UP_KIB=0 # Global upload limit (0+) + +# Per-torrent rate limits (KiB/s, 0 = unlimited) +CCBT_LIMITS_PER_TORRENT_DOWN_KIB=0 # Per-torrent download limit (0+) +CCBT_LIMITS_PER_TORRENT_UP_KIB=0 # Per-torrent upload limit (0+) + +# Per-peer rate limits (KiB/s, 0 = unlimited) +CCBT_LIMITS_PER_PEER_UP_KIB=0 # Per-peer upload limit (0+) + +# Scheduler settings +CCBT_SCHEDULER_SLICE_MS=100 # Scheduler time slice in ms (1-1000) + +# ============================================================================= +# SECURITY CONFIGURATION +# ============================================================================= + +CCBT_ENABLE_ENCRYPTION=false # Enable protocol encryption (true/false) +CCBT_ENCRYPTION_MODE=preferred # Encryption mode: disabled/preferred/required +CCBT_ENCRYPTION_DH_KEY_SIZE=768 # DH key size in bits: 768 or 1024 +CCBT_ENCRYPTION_PREFER_RC4=true # Prefer RC4 cipher for compatibility (true/false) +CCBT_ENCRYPTION_ALLOWED_CIPHERS=rc4,aes # Allowed ciphers (comma-separated: rc4,aes,chacha20) +CCBT_ENCRYPTION_ALLOW_PLAIN_FALLBACK=true # Allow fallback to plain connection (true/false) +CCBT_VALIDATE_PEERS=true # Validate peers before exchanging data (true/false) +CCBT_RATE_LIMIT_ENABLED=true # Enable security rate limiter (true/false) +CCBT_MAX_CONNECTIONS_PER_PEER=1 # Maximum parallel connections per peer (1-8) + +# IP Filter settings +CCBT_ENABLE_IP_FILTER=false # Enable IP filtering (true/false) +CCBT_FILTER_MODE=block # Filter mode: block or allow +CCBT_FILTER_FILES= # Comma-separated filter file paths +CCBT_FILTER_URLS= # Comma-separated filter list URLs +CCBT_FILTER_UPDATE_INTERVAL=86400.0 # Update interval in seconds (3600.0-604800.0) +CCBT_FILTER_CACHE_DIR=~/.ccbt/filters # Filter cache directory +CCBT_FILTER_LOG_BLOCKED=true # Log blocked connections (true/false) + +# Blacklist settings +CCBT_BLACKLIST_ENABLE_PERSISTENCE=true # Persist blacklist to disk (true/false) +CCBT_BLACKLIST_FILE=~/.ccbt/security/blacklist.json # Path to blacklist file +CCBT_BLACKLIST_AUTO_UPDATE_ENABLED=false # Enable automatic blacklist updates from external sources (true/false) +CCBT_BLACKLIST_AUTO_UPDATE_INTERVAL=3600.0 # Auto-update interval in seconds (5m-24h) +CCBT_BLACKLIST_AUTO_UPDATE_SOURCES= # URLs for automatic blacklist updates (comma-separated) +CCBT_BLACKLIST_DEFAULT_EXPIRATION_HOURS= # Default expiration time for auto-blacklisted IPs in hours (empty = permanent) + +# Local metric-based blacklist source +CCBT_BLACKLIST_LOCAL_SOURCE_ENABLED=true # Enable local metric-based blacklisting (true/false) +CCBT_BLACKLIST_LOCAL_SOURCE_EVALUATION_INTERVAL=300.0 # Evaluation interval in seconds (1m-1h) +CCBT_BLACKLIST_LOCAL_SOURCE_METRIC_WINDOW=3600.0 # Metric aggregation window in seconds (5m-24h) +CCBT_BLACKLIST_LOCAL_SOURCE_EXPIRATION_HOURS=24.0 # Expiration time for auto-blacklisted IPs (hours, empty = permanent) +CCBT_BLACKLIST_LOCAL_SOURCE_MIN_OBSERVATIONS=3 # Minimum observations before blacklisting + +# ============================================================================= +# SSL/TLS CONFIGURATION +# ============================================================================= + +# SSL/TLS settings +CCBT_ENABLE_SSL_TRACKERS=true # Enable SSL for tracker connections (true/false) +CCBT_ENABLE_SSL_PEERS=false # Enable SSL for peer connections (true/false) +CCBT_SSL_VERIFY_CERTIFICATES=true # Verify SSL certificates (true/false) +CCBT_SSL_CA_CERTIFICATES= # Path to CA certificates file or directory +CCBT_SSL_CLIENT_CERTIFICATE= # Path to client certificate file (PEM format) +CCBT_SSL_CLIENT_KEY= # Path to client private key file (PEM format) +CCBT_SSL_PROTOCOL_VERSION=TLSv1.2 # TLS protocol version (TLSv1.2, TLSv1.3, PROTOCOL_TLS) +CCBT_SSL_ALLOW_INSECURE_PEERS=true # Allow insecure peers for opportunistic encryption (true/false) + +# ============================================================================= +# PROXY CONFIGURATION +# ============================================================================= + +CCBT_PROXY_ENABLE_PROXY=false # Enable proxy support (true/false) +CCBT_PROXY_TYPE=http # Proxy type: http/socks4/socks5 +CCBT_PROXY_HOST= # Proxy server hostname or IP +CCBT_PROXY_PORT= # Proxy server port (1-65535) +CCBT_PROXY_USERNAME= # Proxy username for authentication +CCBT_PROXY_PASSWORD= # Proxy password (encrypted in storage) +CCBT_PROXY_FOR_TRACKERS=true # Use proxy for tracker requests (true/false) +CCBT_PROXY_FOR_PEERS=false # Use proxy for peer connections (true/false) +CCBT_PROXY_FOR_WEBSEEDS=true # Use proxy for WebSeed requests (true/false) +CCBT_PROXY_BYPASS_LIST= # Comma-separated list of hosts/IPs to bypass proxy + +# ============================================================================= +# MACHINE LEARNING CONFIGURATION +# ============================================================================= + +CCBT_ML_PEER_SELECTION_ENABLED=false # Enable ML-based peer selection (true/false) +CCBT_ML_PIECE_PREDICTION_ENABLED=false # Enable ML piece prediction (true/false) + +# ============================================================================= +# NAT CONFIGURATION +# ============================================================================= + +CCBT_NAT_ENABLE_NAT_PMP=true # Enable NAT-PMP protocol (true/false) +CCBT_NAT_ENABLE_UPNP=true # Enable UPnP IGD protocol (true/false) +CCBT_NAT_DISCOVERY_INTERVAL=300.0 # NAT device discovery interval in seconds (0.0-3600.0) +CCBT_NAT_PORT_MAPPING_LEASE_TIME=3600 # Port mapping lease time in seconds (60-86400) +CCBT_NAT_AUTO_MAP_PORTS=true # Automatically map ports on startup (true/false) +CCBT_NAT_MAP_TCP_PORT=true # Map TCP listen port (true/false) +CCBT_NAT_MAP_UDP_PORT=true # Map UDP listen port (true/false) +CCBT_NAT_MAP_DHT_PORT=true # Map DHT UDP port (true/false) +CCBT_NAT_MAP_XET_PORT=true # Map XET protocol UDP port (true/false) +CCBT_NAT_MAP_XET_MULTICAST_PORT=false # Map XET multicast UDP port (usually not needed for multicast) (true/false) + +# ============================================================================= +# UI/INTERNATIONALIZATION CONFIGURATION +# ============================================================================= + +CCBT_LOCALE=en # Language/locale code (e.g., 'en', 'es', 'fr', 'hi', 'ur', 'fa', 'ja', 'ko', 'zh', 'th', 'sw', 'ha', 'yo', 'eu', 'arc') +CCBT_UI_LOCALE= # UI-specific locale override (takes precedence over CCBT_LOCALE if set) + +# Locale precedence order (highest to lowest): +# 1. CCBT_UI_LOCALE environment variable +# 2. CCBT_LOCALE environment variable +# 3. LANG environment variable +# 4. Config file [ui] section (ccbt.toml) +# 5. System locale +# 6. Default locale ('en') + +# Available locales: en, es, fr, hi, ur, fa, arc, ja, ko, zh, th, sw, ha, yo, eu +# If an invalid locale is specified, the system will fall back to 'en' + +# ============================================================================= +# CLI-SPECIFIC OVERRIDES +# ============================================================================= +# These can be used to override any configuration value via environment variables +# Format: CCBT_
_