From 862dc936e28b5c54448b586719c41c05e5a3a37f Mon Sep 17 00:00:00 2001 From: Joseph Pollack Date: Tue, 9 Dec 2025 14:47:43 +0100 Subject: [PATCH 01/25] adds initial systems --- ...etwork-disk-optimizations-1658c482.plan.md | 393 - .cursor/rules/development-patterns.mdc | 8 + .cursor/rules/documentation-standards.mdc | 183 +- .cursor/rules/monitoring-observability.mdc | 23 + .cursor/rules/performance-optimization.mdc | 51 + .cursor/rules/terminal_dashboard.mdc | 159 +- .env copy | 469 + .github/README.md | 62 +- .github/workflows/ci.yml | 44 + .github/workflows/compatibility.yml | 47 + .github/workflows/publish-pypi-dev.yml | 113 + .github/workflows/publish-pypi.yml | 80 + .github/workflows/release-to-main.yml | 142 + .github/workflows/release.yml | 90 +- .github/workflows/test.yml | 8 +- .github/workflows/version-check.yml | 73 +- .gitignore | 2 +- ccbt.toml | 691 +- ccbt/__init__.py | 19 +- ccbt/cli/advanced_commands.py | 274 +- ccbt/cli/checkpoints.py | 188 +- ccbt/cli/config_commands.py | 8 +- ccbt/cli/config_commands_extended.py | 134 +- ccbt/cli/config_utils.py | 44 +- ccbt/cli/console.py | 26 +- ccbt/cli/create_torrent.py | 68 +- ccbt/cli/daemon_commands.py | 450 +- ccbt/cli/diagnostics.py | 101 +- ccbt/cli/downloads.py | 146 +- ccbt/cli/file_commands.py | 81 +- ccbt/cli/filter_commands.py | 145 +- ccbt/cli/interactive.py | 842 +- ccbt/cli/ipfs_commands.py | 62 +- ccbt/cli/main.py | 1366 ++- ccbt/cli/monitoring_commands.py | 145 +- ccbt/cli/monitoring_utils.py | 4 +- ccbt/cli/nat_commands.py | 141 +- ccbt/cli/overrides.py | 82 +- ccbt/cli/progress.py | 147 +- ccbt/cli/proxy_commands.py | 80 +- ccbt/cli/queue_commands.py | 121 +- ccbt/cli/resume.py | 24 +- ccbt/cli/scrape_commands.py | 35 +- ccbt/cli/ssl_commands.py | 100 +- ccbt/cli/status.py | 334 +- ccbt/cli/task_detector.py | 231 + ccbt/cli/tonic_commands.py | 614 ++ ccbt/cli/tonic_generator.py | 283 + ccbt/cli/torrent_commands.py | 636 ++ ccbt/cli/torrent_config_commands.py | 459 + ccbt/cli/utp_commands.py | 82 +- ccbt/cli/verbosity.py | 175 + ccbt/cli/xet_commands.py | 91 +- ccbt/config/config.py | 309 +- ccbt/config/config_capabilities.py | 2 +- ccbt/config/config_templates.py | 82 + ccbt/consensus/byzantine.py | 216 + ccbt/consensus/raft.py | 391 + ccbt/consensus/raft_state.py | 196 + ccbt/core/magnet.py | 188 +- ccbt/core/tonic.py | 577 ++ ccbt/core/tonic_link.py | 288 + ccbt/daemon/daemon_manager.py | 259 +- ccbt/daemon/ipc_client.py | 1290 ++- ccbt/daemon/ipc_protocol.py | 480 +- ccbt/daemon/ipc_server.py | 2774 ++++- ccbt/daemon/main.py | 546 +- ccbt/daemon/state_manager.py | 32 +- ccbt/daemon/state_models.py | 6 + ccbt/discovery/bloom_filter.py | 328 + ccbt/discovery/dht.py | 1184 ++- ccbt/discovery/dht_indexing.py | 18 +- ccbt/discovery/distributed_tracker.py | 201 + ccbt/discovery/flooding.py | 217 + ccbt/discovery/gossip.py | 275 + ccbt/discovery/lpd.py | 281 + ccbt/discovery/pex.py | 86 +- ccbt/discovery/tracker.py | 1046 +- ccbt/discovery/tracker_udp_client.py | 302 +- ccbt/discovery/xet_bloom.py | 152 + ccbt/discovery/xet_cas.py | 192 +- ccbt/discovery/xet_catalog.py | 305 + ccbt/discovery/xet_gossip.py | 178 + ccbt/discovery/xet_multicast.py | 302 + ccbt/executor/config_executor.py | 2 + ccbt/executor/executor.py | 4 + ccbt/executor/manager.py | 20 +- ccbt/executor/nat_executor.py | 3 + ccbt/executor/queue_executor.py | 2 + ccbt/executor/security_executor.py | 59 + ccbt/executor/session_adapter.py | 1716 +++- ccbt/executor/session_executor.py | 17 + ccbt/executor/torrent_executor.py | 359 +- ccbt/executor/xet_executor.py | 637 ++ ccbt/extensions/manager.py | 60 +- ccbt/extensions/pex.py | 79 + ccbt/extensions/protocol.py | 101 +- ccbt/extensions/xet.py | 317 +- ccbt/extensions/xet_handshake.py | 325 + ccbt/extensions/xet_metadata.py | 314 + ccbt/i18n/__init__.py | 85 +- ccbt/i18n/extract.py | 59 +- ccbt/i18n/locales/arc/LC_MESSAGES/ccbt.po | 4190 ++++++-- ccbt/i18n/locales/en/LC_MESSAGES/ccbt.po | 4049 +++++++- ccbt/i18n/locales/es/LC_MESSAGES/ccbt.po | 4051 +++++++- ccbt/i18n/locales/eu/LC_MESSAGES/ccbt.po | 4051 +++++++- ccbt/i18n/locales/fa/LC_MESSAGES/ccbt.po | 4190 ++++++-- ccbt/i18n/locales/fr/LC_MESSAGES/ccbt.po | 4050 +++++++- ccbt/i18n/locales/ha/LC_MESSAGES/ccbt.po | 4056 +++++++- ccbt/i18n/locales/hi/LC_MESSAGES/ccbt.po | 4155 +++++++- ccbt/i18n/locales/ja/LC_MESSAGES/ccbt.po | 4189 +++++++- ccbt/i18n/locales/ko/LC_MESSAGES/ccbt.po | 4065 +++++++- ccbt/i18n/locales/sw/LC_MESSAGES/ccbt.po | 4184 +++++++- ccbt/i18n/locales/th/LC_MESSAGES/ccbt.po | 4069 +++++++- ccbt/i18n/locales/ur/LC_MESSAGES/ccbt.po | 4121 +++++++- ccbt/i18n/locales/yo/LC_MESSAGES/ccbt.po | 4224 +++++++- ccbt/i18n/locales/zh/LC_MESSAGES/ccbt.po | 4234 +++++++- ccbt/i18n/manager.py | 46 +- ccbt/i18n/scripts/compile_all.py | 13 +- .../scripts/comprehensive_translations.py | 2 +- ccbt/i18n/scripts/extract.py | 143 +- .../scripts/generate_african_translations.py | 13 +- .../generate_hi_ur_fa_arc_translations.py | 2 +- ccbt/i18n/scripts/generate_translations.py | 4 +- ccbt/i18n/scripts/translation_workflow.py | 2 +- ccbt/i18n/scripts/validate_po.py | 18 +- ccbt/interface/__init__.py | 32 +- ccbt/interface/commands/executor.py | 30 +- ccbt/interface/daemon_session_adapter.py | 687 +- ccbt/interface/data_provider.py | 2357 +++++ ccbt/interface/metrics/__init__.py | 61 + ccbt/interface/metrics/graph_series.py | 604 ++ ccbt/interface/reactive_updates.py | 384 + ccbt/interface/screens/__init__.py | 12 + ccbt/interface/screens/base.py | 109 + .../interface/screens/config/global_config.py | 16 +- .../screens/config/torrent_config.py | 51 + .../screens/config/widget_factory.py | 257 + ccbt/interface/screens/config/widgets.py | 19 +- ccbt/interface/screens/dialogs.py | 1008 +- .../screens/file_selection_dialog.py | 202 + .../screens/language_selection_screen.py | 188 + ccbt/interface/screens/monitoring/__init__.py | 4 + .../screens/monitoring/dht_metrics.py | 268 + .../screens/monitoring/metrics_explorer.py | 2 +- ccbt/interface/screens/monitoring/network.py | 65 + ccbt/interface/screens/monitoring/scrape.py | 27 +- .../screens/monitoring/security_scan.py | 222 + .../screens/monitoring/xet_folder_sync.py | 803 ++ ccbt/interface/screens/per_peer_tab.py | 405 + ccbt/interface/screens/per_torrent_files.py | 437 + ccbt/interface/screens/per_torrent_info.py | 459 + ccbt/interface/screens/per_torrent_peers.py | 211 + ccbt/interface/screens/per_torrent_tab.py | 634 ++ .../interface/screens/per_torrent_trackers.py | 369 + ccbt/interface/screens/preferences_tab.py | 251 + ccbt/interface/screens/tabbed_base.py | 128 + .../screens/theme_selection_screen.py | 207 + ccbt/interface/screens/torrents_tab.py | 1130 +++ ccbt/interface/splash/README.md | 259 + ccbt/interface/splash/__init__.py | 76 + ccbt/interface/splash/animation_adapter.py | 233 + ccbt/interface/splash/animation_config.py | 324 + ccbt/interface/splash/animation_demo.py | 185 + ccbt/interface/splash/animation_executor.py | 453 + ccbt/interface/splash/animation_helpers.py | 5016 +++++++++ ccbt/interface/splash/animation_registry.py | 376 + ccbt/interface/splash/animations.py | 488 + ccbt/interface/splash/ascii_art.py | 184 + ccbt/interface/splash/ascii_art/README.md | 65 + ccbt/interface/splash/ascii_art/__init__.py | 101 + ccbt/interface/splash/ascii_art/logo_1.py | 54 + .../splash/ascii_art/nautical_ship.py | 36 + ccbt/interface/splash/ascii_art/row_boat.py | 23 + .../splash/ascii_art/sailing_ship.py | 30 + ccbt/interface/splash/backgrounds.py | 374 + ccbt/interface/splash/character_modifier.py | 334 + ccbt/interface/splash/color_matching.py | 299 + ccbt/interface/splash/color_themes.py | 77 + ccbt/interface/splash/message_overlay.py | 264 + ccbt/interface/splash/run_demo.py | 39 + ccbt/interface/splash/run_unified_demo.py | 21 + ccbt/interface/splash/sequence_generator.py | 272 + ccbt/interface/splash/splash_demo.py | 91 + ccbt/interface/splash/splash_manager.py | 291 + ccbt/interface/splash/splash_screen.py | 1092 ++ ccbt/interface/splash/standalone_demo.py | 115 + ccbt/interface/splash/templates.py | 269 + ccbt/interface/splash/textual_renderable.py | 194 + ccbt/interface/splash/transitions.py | 313 + ccbt/interface/splash/unified_demo.py | 412 + ccbt/interface/terminal_dashboard.py | 3609 +++++-- ccbt/interface/terminal_dashboard_dev.py | 423 + ccbt/interface/themes/__init__.py | 15 + ccbt/interface/themes/rainbow.py | 141 + ccbt/interface/widgets/__init__.py | 50 + ccbt/interface/widgets/button_selector.py | 120 + ccbt/interface/widgets/command_bars.py | 118 + ccbt/interface/widgets/config_wrapper.py | 1139 +++ ccbt/interface/widgets/core_widgets.py | 1050 +- ccbt/interface/widgets/dht_health_widget.py | 182 + ccbt/interface/widgets/file_browser.py | 392 + ccbt/interface/widgets/global_kpis_panel.py | 282 + ccbt/interface/widgets/graph_widget.py | 3049 ++++++ ccbt/interface/widgets/language_selector.py | 298 + ccbt/interface/widgets/monitoring_wrapper.py | 428 + .../peer_quality_distribution_widget.py | 312 + .../widgets/piece_availability_bar.py | 384 + .../widgets/piece_selection_widget.py | 309 + ccbt/interface/widgets/reusable_table.py | 130 + .../widgets/swarm_timeline_widget.py | 301 + ccbt/interface/widgets/tabbed_interface.py | 570 ++ ccbt/interface/widgets/torrent_controls.py | 551 + .../widgets/torrent_file_explorer.py | 541 + ccbt/interface/widgets/torrent_selector.py | 280 + ccbt/models.py | 1402 ++- ccbt/monitoring/__init__.py | 3 - ccbt/monitoring/metrics_collector.py | 350 +- ccbt/nat/manager.py | 222 +- ccbt/nat/natpmp.py | 2 +- ccbt/nat/upnp.py | 40 +- ccbt/peer/async_peer_connection.py | 9028 +++++++++++++++-- ccbt/peer/connection_pool.py | 512 +- ccbt/peer/peer.py | 20 +- ccbt/peer/tcp_server.py | 163 +- ccbt/piece/async_metadata_exchange.py | 96 +- ccbt/piece/async_piece_manager.py | 5224 +++++++++- ccbt/piece/file_selection.py | 60 + ccbt/protocols/ipfs.py | 8 +- ccbt/protocols/xet.py | 242 +- ccbt/proxy/client.py | 4 +- ccbt/queue/manager.py | 109 + ccbt/security/anomaly_detector.py | 4 +- ccbt/security/blacklist_updater.py | 285 + ccbt/security/local_blacklist_source.py | 435 + ccbt/security/security_manager.py | 427 +- ccbt/security/ssl_context.py | 54 +- ccbt/security/tls_certificates.py | 4 +- ccbt/security/xet_allowlist.py | 425 + ccbt/session/announce.py | 618 +- ccbt/session/async_main.py | 84 +- ccbt/session/checkpoint_operations.py | 167 + ccbt/session/checkpointing.py | 509 +- ccbt/session/dht_setup.py | 1008 +- ccbt/session/discovery.py | 237 +- ccbt/session/download_manager.py | 148 +- ccbt/session/download_startup.py | 448 - ccbt/session/incoming.py | 40 +- ccbt/session/magnet_handling.py | 18 +- ccbt/session/manager_startup.py | 940 -- ccbt/session/metrics_status.py | 5 +- ccbt/session/models.py | 1 + ccbt/session/peers.py | 236 +- ccbt/session/session.py | 4390 +++++++- ccbt/session/tasks.py | 7 +- ccbt/session/torrent_addition.py | 27 +- ccbt/session/torrent_utils.py | 1 + ccbt/session/xet_conflict.py | 395 + ccbt/session/xet_realtime_sync.py | 375 + ccbt/session/xet_sync_manager.py | 1189 +++ ccbt/storage/checkpoint.py | 343 +- ccbt/storage/disk_io.py | 997 +- ccbt/storage/disk_io_init.py | 1 + ccbt/storage/file_assembler.py | 530 +- ccbt/storage/folder_watcher.py | 323 + ccbt/storage/git_versioning.py | 368 + ccbt/storage/io_uring_wrapper.py | 249 + ccbt/storage/xet_data_aggregator.py | 269 + ccbt/storage/xet_deduplication.py | 431 +- ccbt/storage/xet_defrag_prevention.py | 251 + ccbt/storage/xet_file_deduplication.py | 263 + ccbt/storage/xet_folder_manager.py | 322 + ccbt/utils/backoff.py | 3 +- ccbt/utils/console_utils.py | 293 +- ccbt/utils/events.py | 280 +- ccbt/utils/logging_config.py | 316 +- ccbt/utils/metrics.py | 393 +- ccbt/utils/network_optimizer.py | 191 +- ccbt/utils/port_checker.py | 51 +- ccbt/utils/rich_logging.py | 180 +- ccbt/utils/rtt_measurement.py | 249 + ccbt/utils/shutdown.py | 60 + ccbt/utils/timeout_adapter.py | 252 + ccbt/utils/version.py | 169 + dev/CHANGELOG.md | 34 + {docs => dev}/README_PyPI.md | 49 +- {docs => dev}/RELEASE_CHECKLIST.md | 3 + dev/mkdocs.yml | 96 +- dev/pre-commit-config.yaml | 34 +- {docs => dev}/pypi-setup.md | 11 + dev/pytest.ini | 3 +- dev/requirements-rtd.txt | 32 + dev/ty.toml | 3 + docs/CLI_PROTOCOL_VIOLATIONS.md | 153 - docs/analysis/protocol-patterns-analysis.md | 168 - docs/arc/configuration.md | 742 ++ docs/arc/examples.md | 348 + docs/arc/getting-started.md | 466 + docs/arc/index.md | 392 + docs/arc/localization-status.md | 117 + docs/arc/rtl-guidelines.md | 145 + docs/blog/.gitkeep | 200 + docs/blog/2024-01-01-welcome.md | 0 docs/blog/2024-01-15-release-notes.md | 308 + docs/blog/2024-02-01-feature-highlight.md | 350 + docs/blog/index.md | 256 + docs/configuration.md | 273 - docs/contributing.md | 228 - docs/daemon-authentication-verification.md | 157 - docs/daemon-cli-authentication-flow.md | 246 - docs/daemon-implementation-plan.md | 545 - docs/debugging-daemon-exit.md | 125 - docs/{ => en}/API.md | 702 +- docs/{ => en}/CI_CD.md | 5 +- docs/en/RELEASE_CHECKLIST.md | 71 + docs/{ => en}/architecture.md | 36 +- .../extension-vs-protocol-separation.md | 209 + docs/{ => en}/bep52.md | 0 docs/{ => en}/bep_xet.md | 264 +- docs/en/bitonic.md | 2183 ++++ docs/{ => en}/btbt-cli.md | 78 + docs/{ => en}/ccBT-RAIL.md | 0 docs/en/configuration.md | 401 + docs/en/contributing.md | 538 + docs/{ => en}/developer/di.md | 0 docs/{ => en}/examples.md | 0 .../examples/bep52/create_hybrid_torrent.py | 0 .../examples/bep52/create_v2_torrent.py | 0 .../examples/bep52/parse_v2_torrent.py | 0 .../examples/bep52/protocol_v2_session.py | 0 .../examples/example-config-advanced.toml | 0 .../examples/example-config-basic.toml | 0 .../examples/example-config-performance.toml | 0 .../examples/example-config-security.toml | 0 docs/{ => en}/funding.md | 0 docs/{ => en}/getting-started.md | 46 +- docs/en/i18n/translation-guide.md | 466 + docs/{ => en}/includes/mkdocs.md | 0 docs/{ => en}/index.md | 54 +- docs/{ => en}/license.md | 0 docs/en/performance.md | 458 + .../encryption_benchmark_report.md | 0 .../runs/disk_io-20251112-191716-a9c4027.json | 0 .../runs/disk_io-20251112-191742-a9c4027.json | 0 .../runs/disk_io-20251112-191743-a9c4027.json | 0 .../encryption-20251112-191730-a9c4027.json | 0 .../encryption-20251112-191745-a9c4027.json | 0 .../encryption-20251112-191746-a9c4027.json | 0 .../encryption-20251112-191747-a9c4027.json | 0 .../encryption-20251112-191748-a9c4027.json | 0 .../encryption-20251112-191750-a9c4027.json | 0 .../encryption-20251112-191759-a9c4027.json | 0 .../encryption-20251112-191800-a9c4027.json | 0 .../hash_verify-20251112-191707-a9c4027.json | 0 .../hash_verify-20251112-191741-a9c4027.json | 0 .../hash_verify-20251112-191754-a9c4027.json | 0 .../hash_verify-20251112-191755-a9c4027.json | 0 .../hash_verify-20251112-191756-a9c4027.json | 0 .../hash_verify-20251112-191758-a9c4027.json | 0 .../hash_verify-20251112-191805-a9c4027.json | 0 .../hash_verify-20251112-191806-a9c4027.json | 0 ...ck_throughput-20251112-191721-a9c4027.json | 0 ...ck_throughput-20251112-191742-a9c4027.json | 0 ...ck_throughput-20251112-191749-a9c4027.json | 0 ...ck_throughput-20251112-191755-a9c4027.json | 0 ...ck_throughput-20251112-191756-a9c4027.json | 0 ...ck_throughput-20251112-191757-a9c4027.json | 0 ...ck_throughput-20251112-191800-a9c4027.json | 0 ...ck_throughput-20251112-191807-a9c4027.json | 0 ...ck_throughput-20251112-191808-a9c4027.json | 0 ...ck_throughput-20251113-165017-7cbe3b2.json | 0 ...iece_assembly-20251112-191719-a9c4027.json | 0 ...iece_assembly-20251112-191745-a9c4027.json | 0 ...iece_assembly-20251112-191751-a9c4027.json | 0 ...iece_assembly-20251112-191758-a9c4027.json | 0 ...iece_assembly-20251112-191759-a9c4027.json | 0 ...iece_assembly-20251112-191800-a9c4027.json | 0 ...iece_assembly-20251112-191802-a9c4027.json | 0 ...iece_assembly-20251112-191808-a9c4027.json | 0 ...iece_assembly-20251112-191809-a9c4027.json | 0 .../loopback_throughput_timeseries.json | 0 docs/{ => en}/reports/coverage.md | 0 docs/{ => en}/reports/junit.xml | 0 docs/es/architecture.md | 575 ++ docs/es/bep52.md | 564 + docs/es/bep_xet.md | 605 ++ docs/{ => es}/bitonic.md | 276 +- docs/es/btbt-cli.md | 1340 +++ docs/es/configuration.md | 401 + docs/es/examples.md | 78 + docs/es/getting-started.md | 165 + docs/es/index.md | 114 + docs/es/performance.md | 458 + docs/eu/configuration.md | 401 + docs/eu/examples.md | 78 + docs/eu/getting-started.md | 165 + docs/eu/index.md | 114 + docs/fa/API.md | 111 + docs/fa/architecture.md | 68 + docs/fa/configuration.md | 742 ++ docs/fa/examples.md | 348 + docs/fa/getting-started.md | 466 + docs/fa/index.md | 408 + docs/fixes/dht-download-start-loop-fix.md | 142 + .../empty-bitfield-peer-disconnect-fix.md | 154 + .../peer-discovery-piece-selection-fix.md | 204 + docs/fixes/peer-timeout-no-pieces-fix.md | 172 + docs/fr/architecture.md | 575 ++ docs/fr/bep52.md | 564 + docs/fr/bep_xet.md | 605 ++ docs/fr/bitonic.md | 2003 ++++ docs/fr/btbt-cli.md | 1492 +++ docs/fr/configuration.md | 401 + docs/fr/examples.md | 78 + docs/fr/getting-started.md | 165 + docs/fr/index.md | 114 + docs/fr/performance.md | 458 + docs/ha/configuration.md | 738 ++ docs/ha/examples.md | 344 + docs/ha/getting-started.md | 466 + docs/ha/index.md | 392 + docs/hi/API.md | 111 + docs/hi/architecture.md | 68 + docs/hi/configuration.md | 742 ++ docs/hi/examples.md | 348 + docs/hi/getting-started.md | 466 + docs/hi/index.md | 408 + docs/ja/API.md | 179 + docs/ja/CI_CD.md | 91 + docs/ja/architecture.md | 575 ++ docs/ja/bep52.md | 564 + docs/ja/bep_xet.md | 605 ++ docs/ja/bitonic.md | 2003 ++++ docs/ja/btbt-cli.md | 652 ++ docs/ja/configuration.md | 742 ++ docs/ja/contributing.md | 146 + docs/ja/examples.md | 348 + docs/ja/getting-started.md | 466 + docs/ja/index.md | 410 + docs/ja/performance.md | 458 + docs/ko/configuration.md | 742 ++ docs/ko/examples.md | 348 + docs/ko/getting-started.md | 466 + docs/ko/index.md | 408 + docs/performance.md | 458 - docs/readthedocs-setup.md | 156 - docs/sw/configuration.md | 738 ++ docs/sw/examples.md | 344 + docs/sw/getting-started.md | 462 + docs/sw/glossary.md | 145 + docs/sw/index.md | 392 + docs/sw/localization-status.md | 117 + docs/th/configuration.md | 742 ++ docs/th/examples.md | 348 + docs/th/getting-started.md | 466 + docs/th/index.md | 408 + docs/unimplemented-methods.md | 318 - docs/ur/configuration.md | 742 ++ docs/ur/examples.md | 348 + docs/ur/getting-started.md | 466 + docs/ur/index.md | 408 + docs/yo/configuration.md | 738 ++ docs/yo/examples.md | 344 + docs/yo/getting-started.md | 462 + docs/yo/glossary.md | 147 + docs/yo/index.md | 392 + docs/yo/localization-status.md | 117 + docs/zh/API.md | 314 + docs/zh/CI_CD.md | 226 + docs/zh/architecture.md | 575 ++ docs/zh/bep52.md | 564 + docs/zh/bep_xet.md | 605 ++ docs/zh/bitonic.md | 2003 ++++ docs/zh/btbt-cli.md | 652 ++ docs/zh/configuration.md | 742 ++ docs/zh/contributing.md | 273 + docs/zh/examples.md | 348 + docs/zh/getting-started.md | 466 + docs/zh/index.md | 408 + docs/zh/performance.md | 458 + env.example | 11 +- pyproject.toml | 14 +- scripts/socket_test.py | 22 - tests/chaos/test_fault_injection.py | 455 - tests/checkpoint/test_advanced_checkpoint.py | 29 - tests/checkpoint/test_checkpoint.py | 477 - tests/cli/test_config_commands_expanded.py | 1194 --- .../test_config_commands_expanded_coverage.py | 545 - .../test_config_commands_extended_coverage.py | 237 - .../test_config_commands_extended_simple.py | 388 - tests/cli/test_config_commands_safeguard.py | 342 - tests/cli/test_config_commands_simple.py | 352 - tests/cli/test_config_interactive_extended.py | 42 - tests/cli/test_file_commands.py | 939 -- tests/compatibility/README.md | 45 + tests/compatibility/__init__.py | 17 + tests/compatibility/trackers/README.md | 35 + tests/compatibility/trackers/__init__.py | 10 + tests/config/test_config_backup_expanded.py | 572 -- tests/config/test_config_capabilities.py | 972 -- tests/config/test_config_conditional.py | 668 -- tests/config/test_config_coverage.py | 210 - tests/config/test_config_edge_cases.py | 290 - tests/config/test_config_expanded.py | 483 - tests/config/test_config_migration.py | 887 -- tests/config/test_config_schema.py | 720 -- tests/config/test_config_templates.py | 473 - tests/config/test_config_validation.py | 446 - tests/config/test_dashboard_model.py | 14 - tests/conftest.py | 22 + tests/daemon/test_daemon_metrics.py | 244 - tests/daemon/test_executor_ipc_alignment.py | 450 - tests/daemon/test_ipc_metrics.py | 155 - tests/daemon/test_state_manager.py | 208 - tests/extensions/test_extensions_expanded.py | 728 -- .../test_extensions_final_coverage.py | 817 -- tests/extensions/test_pex_boost.py | 412 - .../integration/i18n/test_cli_translations.py | 45 + .../test_alert_manager_comprehensive.py | 0 .../monitoring/test_dashboard.py | 5 +- .../test_dashboard_comprehensive.py | 0 .../monitoring/test_dashboard_expanded.py | 0 .../test_metrics_collector_comprehensive.py | 0 .../test_metrics_collector_expanded.py | 0 .../monitoring/test_monitoring_cli.py | 0 .../monitoring/test_tracing_expanded.py | 0 .../observability/test_profiler.py | 0 tests/integration/test_end_to_end.py | 473 - tests/integration/test_per_torrent_config.py | 392 + tests/integration/test_xet_integration.py | 237 + tests/integration/test_xet_sync_workflow.py | 239 + tests/performance/bench_disk_io.py | 248 - .../test_disk_io_phase2_benchmarks.py | 278 - tests/scripts/fix_docs_links.py | 133 - tests/scripts/run_pytest_selective.py | 8 + tests/{ => unit}/checkpoint/__init__.py | 0 tests/{ => unit}/cli/__init__.py | 0 .../{ => unit}/cli/test_advanced_commands.py | 0 ...est_advanced_commands_expanded_coverage.py | 0 tests/{ => unit}/cli/test_bep52_cli.py | 0 tests/{ => unit}/cli/test_create_torrent.py | 0 tests/{ => unit}/cli/test_enhanced_options.py | 0 tests/{ => unit}/cli/test_entry_points.py | 44 +- tests/unit/cli/test_file_commands.py | 10 + .../cli/test_file_commands_coverage.py | 0 tests/{ => unit}/cli/test_filter_commands.py | 0 .../cli/test_filter_commands_coverage.py | 0 tests/unit/cli/test_interactive.py | 2486 +++++ .../{ => unit}/cli/test_interactive_basic.py | 0 ...test_interactive_commands_comprehensive.py | 0 .../cli/test_interactive_comprehensive.py | 0 .../cli/test_interactive_corrected.py | 0 .../cli/test_interactive_coverage.py | 0 ...est_interactive_download_file_selection.py | 0 .../cli/test_interactive_enhanced.py | 0 .../cli/test_interactive_expanded.py | 0 .../cli/test_interactive_expanded_coverage.py | 0 .../cli/test_interactive_file_selection.py | 0 .../cli/test_interactive_final_coverage.py | 0 .../cli/test_interactive_runloop.py | 0 tests/unit/cli/test_logging_enhancements.py | 335 + tests/unit/cli/test_main.py | 3825 +++++++ .../cli/test_main_checkpoints_resume.py | 0 tests/{ => unit}/cli/test_main_corrected.py | 0 .../{ => unit}/cli/test_main_coverage_gaps.py | 0 tests/{ => unit}/cli/test_main_deep_paths.py | 0 tests/{ => unit}/cli/test_main_entry.py | 5 +- tests/{ => unit}/cli/test_main_error_paths.py | 0 tests/{ => unit}/cli/test_main_focus.py | 0 .../cli/test_main_magnet_coverage.py | 0 tests/{ => unit}/cli/test_main_more.py | 0 tests/{ => unit}/cli/test_main_more_topup.py | 0 .../cli/test_main_options_matrix.py | 0 tests/{ => unit}/cli/test_main_overrides.py | 0 .../cli/test_main_resume_save_verify.py | 0 tests/{ => unit}/cli/test_main_topup.py | 0 .../cli/test_monitoring_commands.py | 0 tests/{ => unit}/cli/test_nat_commands.py | 0 tests/{ => unit}/cli/test_progress.py | 77 + tests/{ => unit}/cli/test_proxy_commands.py | 0 .../cli/test_proxy_commands_comprehensive.py | 0 tests/{ => unit}/cli/test_queue_commands.py | 0 .../cli/test_queue_commands_comprehensive.py | 0 tests/{ => unit}/cli/test_resume_commands.py | 0 tests/{ => unit}/cli/test_scrape_commands.py | 0 tests/{ => unit}/cli/test_ssl_commands.py | 0 .../cli/test_ssl_commands_coverage.py | 0 .../cli/test_status_scrape_display.py | 0 tests/{ => unit}/cli/test_utp_commands.py | 0 .../cli/test_utp_config_integration.py | 2 +- tests/unit/cli/test_verbosity.py | 255 + tests/{ => unit}/config/__init__.py | 0 .../consensus/test_byzantine_consensus.py | 137 + tests/unit/consensus/test_raft_consensus.py | 181 + tests/unit/core/test_tonic_format.py | 249 + tests/unit/core/test_torrent.py | 333 - .../core/test_torrent_edge_cases.py | 0 .../unit/discovery/test_dht_error_handling.py | 397 - tests/unit/discovery/test_dht_indexing.py | 633 -- tests/unit/discovery/test_dht_ipv6.py | 394 - tests/unit/discovery/test_dht_ipv6_merging.py | 197 - tests/unit/discovery/test_dht_ipv6_parsing.py | 160 - tests/unit/discovery/test_dht_multiaddr.py | 542 - tests/unit/discovery/test_dht_readonly.py | 146 +- tests/unit/discovery/test_dht_storage.py | 823 -- tests/unit/discovery/test_dht_xet_chunks.py | 175 - tests/unit/discovery/test_tracker_expanded.py | 37 +- .../discovery/test_tracker_ssl_parsing.py | 75 + .../discovery/test_tracker_udp_routing.py | 251 +- tests/unit/disk/test_disk_io.py | 410 - tests/unit/disk/test_disk_io_edge_cases.py | 746 -- tests/unit/disk/test_disk_io_expanded.py | 900 -- .../unit/disk/test_disk_io_final_coverage.py | 236 - .../disk/test_disk_io_phase2_optimizations.py | 484 - .../disk/test_disk_io_remaining_coverage.py | 395 - .../test_ssl_capability_tracking.py | 146 + tests/unit/file/test_file_assembler_blocks.py | 76 - .../file/test_file_assembler_edge_cases.py | 439 - .../unit/file/test_file_assembler_expanded.py | 1043 -- .../test_file_assembler_final_coverage.py | 282 - tests/unit/file/test_file_assembler_status.py | 479 - tests/unit/i18n/test_translations.py | 45 + .../splash/test_animation_helpers.py | 61 + .../unit/interface/test_monitoring_screens.py | 678 -- .../unit/interface/test_terminal_dashboard.py | 125 - .../test_terminal_dashboard_basic.py | 125 - .../test_terminal_dashboard_widgets.py | 296 - tests/{ => unit}/ml/test_adaptive_limiter.py | 0 tests/{ => unit}/ml/test_peer_selector.py | 0 tests/{ => unit}/ml/test_piece_predictor.py | 0 tests/unit/models/test_peer_info_ssl.py | 70 + tests/unit/peer/test_async_peer_connection.py | 60 + .../test_async_piece_manager_comprehensive.py | 0 .../{ => unit}/plugins/test_metrics_plugin.py | 0 .../plugins/test_plugin_base_comprehensive.py | 0 tests/{ => unit}/property/__init__.py | 0 .../property/test_bencode_properties.py | 0 .../test_piece_selection_properties.py | 0 tests/{ => unit}/protocols/__init__.py | 0 .../protocols/test_bittorrent_integration.py | 0 .../protocols/test_bittorrent_v2.py | 0 .../protocols/test_hybrid_protocol.py | 0 .../protocols/test_ipfs_connection.py | 0 .../test_ipfs_protocol_comprehensive.py | 0 .../protocols/test_protocol_base.py | 0 .../test_protocol_base_comprehensive.py | 0 tests/{ => unit}/security/__init__.py | 0 .../security/test_anomaly_detector.py | 0 .../security/test_blacklist_persistence.py | 247 + tests/unit/security/test_blacklist_updater.py | 199 + tests/{ => unit}/security/test_ciphers.py | 0 .../security/test_ciphers_chacha20.py | 0 tests/{ => unit}/security/test_dh_exchange.py | 0 .../security/test_encrypted_stream.py | 0 tests/{ => unit}/security/test_encryption.py | 0 .../security/test_encryption_coverage.py | 0 .../security/test_encryption_coverage_gaps.py | 0 .../security/test_encryption_init_coverage.py | 0 .../security/test_ip_filter_coverage.py | 0 .../security/test_ip_filter_coverage_final.py | 0 .../security/test_ip_filter_coverage_gaps.py | 0 .../security/test_ip_filter_integration.py | 0 .../security/test_ip_filter_loading.py | 0 .../security/test_ip_filter_matching.py | 0 .../security/test_ip_filter_parsing.py | 0 .../security/test_ip_filter_rules.py | 0 tests/{ => unit}/security/test_key_manager.py | 0 .../{ => unit}/security/test_mse_handshake.py | 0 .../security/test_mse_handshake_coverage.py | 0 .../security/test_mse_handshake_pe.py | 0 .../security/test_peer_validator.py | 0 .../{ => unit}/security/test_rate_limiter.py | 0 .../test_rate_limiter_coverage_gaps.py | 0 .../security/test_security_manager.py | 60 + tests/unit/security/test_xet_allowlist.py | 187 + .../session/test_checkpoint_persistence.py | 333 + tests/unit/session/test_manager_startup.py | 20 +- .../storage/test_buffers_comprehensive.py | 694 -- .../storage/test_checkpoint_edge_cases.py | 668 -- .../unit/storage/test_checkpoint_expanded.py | 916 -- .../storage/test_checkpoint_final_coverage.py | 215 - .../storage/test_disk_io_cleanup_paths.py | 295 - .../storage/test_disk_io_coverage_gaps.py | 308 - tests/unit/storage/test_disk_io_init.py | 414 - .../storage/test_disk_io_missing_coverage.py | 74 - .../storage/test_file_attributes_assembler.py | 483 - tests/unit/storage/test_resume_data.py | 557 - .../unit/storage/test_xet_data_aggregator.py | 262 + tests/unit/storage/test_xet_deduplication.py | 447 + .../storage/test_xet_defrag_prevention.py | 212 + .../storage/test_xet_file_deduplication.py | 287 + tests/unit/tracker/test_tracker.py | 4 +- tests/unit/tracker/test_tracker_udp_client.py | 49 +- .../test_tracker_udp_client_comprehensive.py | 34 +- uv.lock | 11 +- 695 files changed, 212582 insertions(+), 49797 deletions(-) delete mode 100644 .cursor/plans/network-disk-optimizations-1658c482.plan.md create mode 100644 .env copy create mode 100644 .github/workflows/publish-pypi-dev.yml create mode 100644 .github/workflows/release-to-main.yml create mode 100644 ccbt/cli/task_detector.py create mode 100644 ccbt/cli/tonic_commands.py create mode 100644 ccbt/cli/tonic_generator.py create mode 100644 ccbt/cli/torrent_commands.py create mode 100644 ccbt/cli/torrent_config_commands.py create mode 100644 ccbt/cli/verbosity.py create mode 100644 ccbt/consensus/byzantine.py create mode 100644 ccbt/consensus/raft.py create mode 100644 ccbt/consensus/raft_state.py create mode 100644 ccbt/core/tonic.py create mode 100644 ccbt/core/tonic_link.py create mode 100644 ccbt/discovery/bloom_filter.py create mode 100644 ccbt/discovery/distributed_tracker.py create mode 100644 ccbt/discovery/flooding.py create mode 100644 ccbt/discovery/gossip.py create mode 100644 ccbt/discovery/lpd.py create mode 100644 ccbt/discovery/xet_bloom.py create mode 100644 ccbt/discovery/xet_catalog.py create mode 100644 ccbt/discovery/xet_gossip.py create mode 100644 ccbt/discovery/xet_multicast.py create mode 100644 ccbt/executor/xet_executor.py create mode 100644 ccbt/extensions/xet_handshake.py create mode 100644 ccbt/extensions/xet_metadata.py create mode 100644 ccbt/interface/data_provider.py create mode 100644 ccbt/interface/metrics/__init__.py create mode 100644 ccbt/interface/metrics/graph_series.py create mode 100644 ccbt/interface/reactive_updates.py create mode 100644 ccbt/interface/screens/config/widget_factory.py create mode 100644 ccbt/interface/screens/file_selection_dialog.py create mode 100644 ccbt/interface/screens/language_selection_screen.py create mode 100644 ccbt/interface/screens/monitoring/dht_metrics.py create mode 100644 ccbt/interface/screens/monitoring/security_scan.py create mode 100644 ccbt/interface/screens/monitoring/xet_folder_sync.py create mode 100644 ccbt/interface/screens/per_peer_tab.py create mode 100644 ccbt/interface/screens/per_torrent_files.py create mode 100644 ccbt/interface/screens/per_torrent_info.py create mode 100644 ccbt/interface/screens/per_torrent_peers.py create mode 100644 ccbt/interface/screens/per_torrent_tab.py create mode 100644 ccbt/interface/screens/per_torrent_trackers.py create mode 100644 ccbt/interface/screens/preferences_tab.py create mode 100644 ccbt/interface/screens/tabbed_base.py create mode 100644 ccbt/interface/screens/theme_selection_screen.py create mode 100644 ccbt/interface/screens/torrents_tab.py create mode 100644 ccbt/interface/splash/README.md create mode 100644 ccbt/interface/splash/__init__.py create mode 100644 ccbt/interface/splash/animation_adapter.py create mode 100644 ccbt/interface/splash/animation_config.py create mode 100644 ccbt/interface/splash/animation_demo.py create mode 100644 ccbt/interface/splash/animation_executor.py create mode 100644 ccbt/interface/splash/animation_helpers.py create mode 100644 ccbt/interface/splash/animation_registry.py create mode 100644 ccbt/interface/splash/animations.py create mode 100644 ccbt/interface/splash/ascii_art.py create mode 100644 ccbt/interface/splash/ascii_art/README.md create mode 100644 ccbt/interface/splash/ascii_art/__init__.py create mode 100644 ccbt/interface/splash/ascii_art/logo_1.py create mode 100644 ccbt/interface/splash/ascii_art/nautical_ship.py create mode 100644 ccbt/interface/splash/ascii_art/row_boat.py create mode 100644 ccbt/interface/splash/ascii_art/sailing_ship.py create mode 100644 ccbt/interface/splash/backgrounds.py create mode 100644 ccbt/interface/splash/character_modifier.py create mode 100644 ccbt/interface/splash/color_matching.py create mode 100644 ccbt/interface/splash/color_themes.py create mode 100644 ccbt/interface/splash/message_overlay.py create mode 100644 ccbt/interface/splash/run_demo.py create mode 100644 ccbt/interface/splash/run_unified_demo.py create mode 100644 ccbt/interface/splash/sequence_generator.py create mode 100644 ccbt/interface/splash/splash_demo.py create mode 100644 ccbt/interface/splash/splash_manager.py create mode 100644 ccbt/interface/splash/splash_screen.py create mode 100644 ccbt/interface/splash/standalone_demo.py create mode 100644 ccbt/interface/splash/templates.py create mode 100644 ccbt/interface/splash/textual_renderable.py create mode 100644 ccbt/interface/splash/transitions.py create mode 100644 ccbt/interface/splash/unified_demo.py create mode 100644 ccbt/interface/terminal_dashboard_dev.py create mode 100644 ccbt/interface/themes/__init__.py create mode 100644 ccbt/interface/themes/rainbow.py create mode 100644 ccbt/interface/widgets/button_selector.py create mode 100644 ccbt/interface/widgets/command_bars.py create mode 100644 ccbt/interface/widgets/config_wrapper.py create mode 100644 ccbt/interface/widgets/dht_health_widget.py create mode 100644 ccbt/interface/widgets/file_browser.py create mode 100644 ccbt/interface/widgets/global_kpis_panel.py create mode 100644 ccbt/interface/widgets/graph_widget.py create mode 100644 ccbt/interface/widgets/language_selector.py create mode 100644 ccbt/interface/widgets/monitoring_wrapper.py create mode 100644 ccbt/interface/widgets/peer_quality_distribution_widget.py create mode 100644 ccbt/interface/widgets/piece_availability_bar.py create mode 100644 ccbt/interface/widgets/piece_selection_widget.py create mode 100644 ccbt/interface/widgets/reusable_table.py create mode 100644 ccbt/interface/widgets/swarm_timeline_widget.py create mode 100644 ccbt/interface/widgets/tabbed_interface.py create mode 100644 ccbt/interface/widgets/torrent_controls.py create mode 100644 ccbt/interface/widgets/torrent_file_explorer.py create mode 100644 ccbt/interface/widgets/torrent_selector.py create mode 100644 ccbt/security/blacklist_updater.py create mode 100644 ccbt/security/local_blacklist_source.py create mode 100644 ccbt/security/xet_allowlist.py create mode 100644 ccbt/session/xet_conflict.py create mode 100644 ccbt/session/xet_realtime_sync.py create mode 100644 ccbt/session/xet_sync_manager.py create mode 100644 ccbt/storage/folder_watcher.py create mode 100644 ccbt/storage/git_versioning.py create mode 100644 ccbt/storage/io_uring_wrapper.py create mode 100644 ccbt/storage/xet_data_aggregator.py create mode 100644 ccbt/storage/xet_defrag_prevention.py create mode 100644 ccbt/storage/xet_file_deduplication.py create mode 100644 ccbt/storage/xet_folder_manager.py create mode 100644 ccbt/utils/rtt_measurement.py create mode 100644 ccbt/utils/shutdown.py create mode 100644 ccbt/utils/timeout_adapter.py create mode 100644 ccbt/utils/version.py create mode 100644 dev/CHANGELOG.md rename {docs => dev}/README_PyPI.md (60%) rename {docs => dev}/RELEASE_CHECKLIST.md (92%) rename {docs => dev}/pypi-setup.md (99%) delete mode 100644 docs/CLI_PROTOCOL_VIOLATIONS.md delete mode 100644 docs/analysis/protocol-patterns-analysis.md create mode 100644 docs/arc/configuration.md create mode 100644 docs/arc/examples.md create mode 100644 docs/arc/getting-started.md create mode 100644 docs/arc/index.md create mode 100644 docs/arc/localization-status.md create mode 100644 docs/arc/rtl-guidelines.md create mode 100644 docs/blog/.gitkeep create mode 100644 docs/blog/2024-01-01-welcome.md create mode 100644 docs/blog/2024-01-15-release-notes.md create mode 100644 docs/blog/2024-02-01-feature-highlight.md create mode 100644 docs/blog/index.md delete mode 100644 docs/configuration.md delete mode 100644 docs/contributing.md delete mode 100644 docs/daemon-authentication-verification.md delete mode 100644 docs/daemon-cli-authentication-flow.md delete mode 100644 docs/daemon-implementation-plan.md delete mode 100644 docs/debugging-daemon-exit.md rename docs/{ => en}/API.md (57%) rename docs/{ => en}/CI_CD.md (98%) create mode 100644 docs/en/RELEASE_CHECKLIST.md rename docs/{ => en}/architecture.md (95%) create mode 100644 docs/en/architecture/extension-vs-protocol-separation.md rename docs/{ => en}/bep52.md (100%) rename docs/{ => en}/bep_xet.md (65%) create mode 100644 docs/en/bitonic.md rename docs/{ => en}/btbt-cli.md (88%) rename docs/{ => en}/ccBT-RAIL.md (100%) create mode 100644 docs/en/configuration.md create mode 100644 docs/en/contributing.md rename docs/{ => en}/developer/di.md (100%) rename docs/{ => en}/examples.md (100%) rename docs/{ => en}/examples/bep52/create_hybrid_torrent.py (100%) rename docs/{ => en}/examples/bep52/create_v2_torrent.py (100%) rename docs/{ => en}/examples/bep52/parse_v2_torrent.py (100%) rename docs/{ => en}/examples/bep52/protocol_v2_session.py (100%) rename docs/{ => en}/examples/example-config-advanced.toml (100%) rename docs/{ => en}/examples/example-config-basic.toml (100%) rename docs/{ => en}/examples/example-config-performance.toml (100%) rename docs/{ => en}/examples/example-config-security.toml (100%) rename docs/{ => en}/funding.md (100%) rename docs/{ => en}/getting-started.md (72%) create mode 100644 docs/en/i18n/translation-guide.md rename docs/{ => en}/includes/mkdocs.md (100%) rename docs/{ => en}/index.md (68%) rename docs/{ => en}/license.md (100%) create mode 100644 docs/en/performance.md rename docs/{ => en}/performance/encryption_benchmark_report.md (100%) rename docs/{ => en}/reports/benchmarks/runs/disk_io-20251112-191716-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/disk_io-20251112-191742-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/disk_io-20251112-191743-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191730-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191745-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191746-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191747-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191748-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191750-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191759-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/encryption-20251112-191800-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191707-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191741-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191754-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191755-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191756-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191758-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191805-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/hash_verify-20251112-191806-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191721-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191742-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191749-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191755-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191756-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191757-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191800-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191807-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251112-191808-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/loopback_throughput-20251113-165017-7cbe3b2.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191719-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191745-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191751-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191758-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191759-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191800-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191802-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191808-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/runs/piece_assembly-20251112-191809-a9c4027.json (100%) rename docs/{ => en}/reports/benchmarks/timeseries/loopback_throughput_timeseries.json (100%) rename docs/{ => en}/reports/coverage.md (100%) rename docs/{ => en}/reports/junit.xml (100%) create mode 100644 docs/es/architecture.md create mode 100644 docs/es/bep52.md create mode 100644 docs/es/bep_xet.md rename docs/{ => es}/bitonic.md (91%) create mode 100644 docs/es/btbt-cli.md create mode 100644 docs/es/configuration.md create mode 100644 docs/es/examples.md create mode 100644 docs/es/getting-started.md create mode 100644 docs/es/index.md create mode 100644 docs/es/performance.md create mode 100644 docs/eu/configuration.md create mode 100644 docs/eu/examples.md create mode 100644 docs/eu/getting-started.md create mode 100644 docs/eu/index.md create mode 100644 docs/fa/API.md create mode 100644 docs/fa/architecture.md create mode 100644 docs/fa/configuration.md create mode 100644 docs/fa/examples.md create mode 100644 docs/fa/getting-started.md create mode 100644 docs/fa/index.md create mode 100644 docs/fixes/dht-download-start-loop-fix.md create mode 100644 docs/fixes/empty-bitfield-peer-disconnect-fix.md create mode 100644 docs/fixes/peer-discovery-piece-selection-fix.md create mode 100644 docs/fixes/peer-timeout-no-pieces-fix.md create mode 100644 docs/fr/architecture.md create mode 100644 docs/fr/bep52.md create mode 100644 docs/fr/bep_xet.md create mode 100644 docs/fr/bitonic.md create mode 100644 docs/fr/btbt-cli.md create mode 100644 docs/fr/configuration.md create mode 100644 docs/fr/examples.md create mode 100644 docs/fr/getting-started.md create mode 100644 docs/fr/index.md create mode 100644 docs/fr/performance.md create mode 100644 docs/ha/configuration.md create mode 100644 docs/ha/examples.md create mode 100644 docs/ha/getting-started.md create mode 100644 docs/ha/index.md create mode 100644 docs/hi/API.md create mode 100644 docs/hi/architecture.md create mode 100644 docs/hi/configuration.md create mode 100644 docs/hi/examples.md create mode 100644 docs/hi/getting-started.md create mode 100644 docs/hi/index.md create mode 100644 docs/ja/API.md create mode 100644 docs/ja/CI_CD.md create mode 100644 docs/ja/architecture.md create mode 100644 docs/ja/bep52.md create mode 100644 docs/ja/bep_xet.md create mode 100644 docs/ja/bitonic.md create mode 100644 docs/ja/btbt-cli.md create mode 100644 docs/ja/configuration.md create mode 100644 docs/ja/contributing.md create mode 100644 docs/ja/examples.md create mode 100644 docs/ja/getting-started.md create mode 100644 docs/ja/index.md create mode 100644 docs/ja/performance.md create mode 100644 docs/ko/configuration.md create mode 100644 docs/ko/examples.md create mode 100644 docs/ko/getting-started.md create mode 100644 docs/ko/index.md delete mode 100644 docs/performance.md delete mode 100644 docs/readthedocs-setup.md create mode 100644 docs/sw/configuration.md create mode 100644 docs/sw/examples.md create mode 100644 docs/sw/getting-started.md create mode 100644 docs/sw/glossary.md create mode 100644 docs/sw/index.md create mode 100644 docs/sw/localization-status.md create mode 100644 docs/th/configuration.md create mode 100644 docs/th/examples.md create mode 100644 docs/th/getting-started.md create mode 100644 docs/th/index.md delete mode 100644 docs/unimplemented-methods.md create mode 100644 docs/ur/configuration.md create mode 100644 docs/ur/examples.md create mode 100644 docs/ur/getting-started.md create mode 100644 docs/ur/index.md create mode 100644 docs/yo/configuration.md create mode 100644 docs/yo/examples.md create mode 100644 docs/yo/getting-started.md create mode 100644 docs/yo/glossary.md create mode 100644 docs/yo/index.md create mode 100644 docs/yo/localization-status.md create mode 100644 docs/zh/API.md create mode 100644 docs/zh/CI_CD.md create mode 100644 docs/zh/architecture.md create mode 100644 docs/zh/bep52.md create mode 100644 docs/zh/bep_xet.md create mode 100644 docs/zh/bitonic.md create mode 100644 docs/zh/btbt-cli.md create mode 100644 docs/zh/configuration.md create mode 100644 docs/zh/contributing.md create mode 100644 docs/zh/examples.md create mode 100644 docs/zh/getting-started.md create mode 100644 docs/zh/index.md create mode 100644 docs/zh/performance.md delete mode 100644 scripts/socket_test.py delete mode 100644 tests/chaos/test_fault_injection.py delete mode 100644 tests/checkpoint/test_advanced_checkpoint.py delete mode 100644 tests/checkpoint/test_checkpoint.py delete mode 100644 tests/cli/test_config_commands_expanded.py delete mode 100644 tests/cli/test_config_commands_expanded_coverage.py delete mode 100644 tests/cli/test_config_commands_extended_coverage.py delete mode 100644 tests/cli/test_config_commands_extended_simple.py delete mode 100644 tests/cli/test_config_commands_safeguard.py delete mode 100644 tests/cli/test_config_commands_simple.py delete mode 100644 tests/cli/test_config_interactive_extended.py delete mode 100644 tests/cli/test_file_commands.py create mode 100644 tests/compatibility/README.md create mode 100644 tests/compatibility/__init__.py create mode 100644 tests/compatibility/trackers/README.md create mode 100644 tests/compatibility/trackers/__init__.py delete mode 100644 tests/config/test_config_backup_expanded.py delete mode 100644 tests/config/test_config_capabilities.py delete mode 100644 tests/config/test_config_conditional.py delete mode 100644 tests/config/test_config_coverage.py delete mode 100644 tests/config/test_config_edge_cases.py delete mode 100644 tests/config/test_config_expanded.py delete mode 100644 tests/config/test_config_migration.py delete mode 100644 tests/config/test_config_schema.py delete mode 100644 tests/config/test_config_templates.py delete mode 100644 tests/config/test_config_validation.py delete mode 100644 tests/config/test_dashboard_model.py delete mode 100644 tests/daemon/test_daemon_metrics.py delete mode 100644 tests/daemon/test_executor_ipc_alignment.py delete mode 100644 tests/daemon/test_ipc_metrics.py delete mode 100644 tests/daemon/test_state_manager.py delete mode 100644 tests/extensions/test_extensions_expanded.py delete mode 100644 tests/extensions/test_extensions_final_coverage.py delete mode 100644 tests/extensions/test_pex_boost.py create mode 100644 tests/integration/i18n/test_cli_translations.py rename tests/{ => integration}/monitoring/test_alert_manager_comprehensive.py (100%) rename tests/{ => integration}/monitoring/test_dashboard.py (92%) rename tests/{ => integration}/monitoring/test_dashboard_comprehensive.py (100%) rename tests/{ => integration}/monitoring/test_dashboard_expanded.py (100%) rename tests/{ => integration}/monitoring/test_metrics_collector_comprehensive.py (100%) rename tests/{ => integration}/monitoring/test_metrics_collector_expanded.py (100%) rename tests/{ => integration}/monitoring/test_monitoring_cli.py (100%) rename tests/{ => integration}/monitoring/test_tracing_expanded.py (100%) rename tests/{ => integration}/observability/test_profiler.py (100%) delete mode 100644 tests/integration/test_end_to_end.py create mode 100644 tests/integration/test_per_torrent_config.py create mode 100644 tests/integration/test_xet_sync_workflow.py delete mode 100644 tests/performance/bench_disk_io.py delete mode 100644 tests/performance/test_disk_io_phase2_benchmarks.py delete mode 100644 tests/scripts/fix_docs_links.py rename tests/{ => unit}/checkpoint/__init__.py (100%) rename tests/{ => unit}/cli/__init__.py (100%) rename tests/{ => unit}/cli/test_advanced_commands.py (100%) rename tests/{ => unit}/cli/test_advanced_commands_expanded_coverage.py (100%) rename tests/{ => unit}/cli/test_bep52_cli.py (100%) rename tests/{ => unit}/cli/test_create_torrent.py (100%) rename tests/{ => unit}/cli/test_enhanced_options.py (100%) rename tests/{ => unit}/cli/test_entry_points.py (59%) create mode 100644 tests/unit/cli/test_file_commands.py rename tests/{ => unit}/cli/test_file_commands_coverage.py (100%) rename tests/{ => unit}/cli/test_filter_commands.py (100%) rename tests/{ => unit}/cli/test_filter_commands_coverage.py (100%) create mode 100644 tests/unit/cli/test_interactive.py rename tests/{ => unit}/cli/test_interactive_basic.py (100%) rename tests/{ => unit}/cli/test_interactive_commands_comprehensive.py (100%) rename tests/{ => unit}/cli/test_interactive_comprehensive.py (100%) rename tests/{ => unit}/cli/test_interactive_corrected.py (100%) rename tests/{ => unit}/cli/test_interactive_coverage.py (100%) rename tests/{ => unit}/cli/test_interactive_download_file_selection.py (100%) rename tests/{ => unit}/cli/test_interactive_enhanced.py (100%) rename tests/{ => unit}/cli/test_interactive_expanded.py (100%) rename tests/{ => unit}/cli/test_interactive_expanded_coverage.py (100%) rename tests/{ => unit}/cli/test_interactive_file_selection.py (100%) rename tests/{ => unit}/cli/test_interactive_final_coverage.py (100%) rename tests/{ => unit}/cli/test_interactive_runloop.py (100%) create mode 100644 tests/unit/cli/test_logging_enhancements.py create mode 100644 tests/unit/cli/test_main.py rename tests/{ => unit}/cli/test_main_checkpoints_resume.py (100%) rename tests/{ => unit}/cli/test_main_corrected.py (100%) rename tests/{ => unit}/cli/test_main_coverage_gaps.py (100%) rename tests/{ => unit}/cli/test_main_deep_paths.py (100%) rename tests/{ => unit}/cli/test_main_entry.py (98%) rename tests/{ => unit}/cli/test_main_error_paths.py (100%) rename tests/{ => unit}/cli/test_main_focus.py (100%) rename tests/{ => unit}/cli/test_main_magnet_coverage.py (100%) rename tests/{ => unit}/cli/test_main_more.py (100%) rename tests/{ => unit}/cli/test_main_more_topup.py (100%) rename tests/{ => unit}/cli/test_main_options_matrix.py (100%) rename tests/{ => unit}/cli/test_main_overrides.py (100%) rename tests/{ => unit}/cli/test_main_resume_save_verify.py (100%) rename tests/{ => unit}/cli/test_main_topup.py (100%) rename tests/{ => unit}/cli/test_monitoring_commands.py (100%) rename tests/{ => unit}/cli/test_nat_commands.py (100%) rename tests/{ => unit}/cli/test_progress.py (77%) rename tests/{ => unit}/cli/test_proxy_commands.py (100%) rename tests/{ => unit}/cli/test_proxy_commands_comprehensive.py (100%) rename tests/{ => unit}/cli/test_queue_commands.py (100%) rename tests/{ => unit}/cli/test_queue_commands_comprehensive.py (100%) rename tests/{ => unit}/cli/test_resume_commands.py (100%) rename tests/{ => unit}/cli/test_scrape_commands.py (100%) rename tests/{ => unit}/cli/test_ssl_commands.py (100%) rename tests/{ => unit}/cli/test_ssl_commands_coverage.py (100%) rename tests/{ => unit}/cli/test_status_scrape_display.py (100%) rename tests/{ => unit}/cli/test_utp_commands.py (100%) rename tests/{ => unit}/cli/test_utp_config_integration.py (99%) create mode 100644 tests/unit/cli/test_verbosity.py rename tests/{ => unit}/config/__init__.py (100%) create mode 100644 tests/unit/consensus/test_byzantine_consensus.py create mode 100644 tests/unit/consensus/test_raft_consensus.py create mode 100644 tests/unit/core/test_tonic_format.py delete mode 100644 tests/unit/core/test_torrent.py rename tests/{ => unit}/core/test_torrent_edge_cases.py (100%) delete mode 100644 tests/unit/discovery/test_dht_error_handling.py delete mode 100644 tests/unit/discovery/test_dht_indexing.py delete mode 100644 tests/unit/discovery/test_dht_ipv6.py delete mode 100644 tests/unit/discovery/test_dht_ipv6_merging.py delete mode 100644 tests/unit/discovery/test_dht_ipv6_parsing.py delete mode 100644 tests/unit/discovery/test_dht_multiaddr.py delete mode 100644 tests/unit/discovery/test_dht_storage.py delete mode 100644 tests/unit/discovery/test_dht_xet_chunks.py create mode 100644 tests/unit/discovery/test_tracker_ssl_parsing.py delete mode 100644 tests/unit/disk/test_disk_io.py delete mode 100644 tests/unit/disk/test_disk_io_edge_cases.py delete mode 100644 tests/unit/disk/test_disk_io_expanded.py delete mode 100644 tests/unit/disk/test_disk_io_final_coverage.py delete mode 100644 tests/unit/disk/test_disk_io_phase2_optimizations.py delete mode 100644 tests/unit/disk/test_disk_io_remaining_coverage.py create mode 100644 tests/unit/extensions/test_ssl_capability_tracking.py delete mode 100644 tests/unit/file/test_file_assembler_blocks.py delete mode 100644 tests/unit/file/test_file_assembler_edge_cases.py delete mode 100644 tests/unit/file/test_file_assembler_expanded.py delete mode 100644 tests/unit/file/test_file_assembler_final_coverage.py delete mode 100644 tests/unit/file/test_file_assembler_status.py create mode 100644 tests/unit/i18n/test_translations.py create mode 100644 tests/unit/interface/splash/test_animation_helpers.py delete mode 100644 tests/unit/interface/test_monitoring_screens.py delete mode 100644 tests/unit/interface/test_terminal_dashboard.py delete mode 100644 tests/unit/interface/test_terminal_dashboard_basic.py delete mode 100644 tests/unit/interface/test_terminal_dashboard_widgets.py rename tests/{ => unit}/ml/test_adaptive_limiter.py (100%) rename tests/{ => unit}/ml/test_peer_selector.py (100%) rename tests/{ => unit}/ml/test_piece_predictor.py (100%) create mode 100644 tests/unit/models/test_peer_info_ssl.py rename tests/{ => unit}/piece/test_async_piece_manager_comprehensive.py (100%) rename tests/{ => unit}/plugins/test_metrics_plugin.py (100%) rename tests/{ => unit}/plugins/test_plugin_base_comprehensive.py (100%) rename tests/{ => unit}/property/__init__.py (100%) rename tests/{ => unit}/property/test_bencode_properties.py (100%) rename tests/{ => unit}/property/test_piece_selection_properties.py (100%) rename tests/{ => unit}/protocols/__init__.py (100%) rename tests/{ => unit}/protocols/test_bittorrent_integration.py (100%) rename tests/{ => unit}/protocols/test_bittorrent_v2.py (100%) rename tests/{ => unit}/protocols/test_hybrid_protocol.py (100%) rename tests/{ => unit}/protocols/test_ipfs_connection.py (100%) rename tests/{ => unit}/protocols/test_ipfs_protocol_comprehensive.py (100%) rename tests/{ => unit}/protocols/test_protocol_base.py (100%) rename tests/{ => unit}/protocols/test_protocol_base_comprehensive.py (100%) rename tests/{ => unit}/security/__init__.py (100%) rename tests/{ => unit}/security/test_anomaly_detector.py (100%) create mode 100644 tests/unit/security/test_blacklist_persistence.py create mode 100644 tests/unit/security/test_blacklist_updater.py rename tests/{ => unit}/security/test_ciphers.py (100%) rename tests/{ => unit}/security/test_ciphers_chacha20.py (100%) rename tests/{ => unit}/security/test_dh_exchange.py (100%) rename tests/{ => unit}/security/test_encrypted_stream.py (100%) rename tests/{ => unit}/security/test_encryption.py (100%) rename tests/{ => unit}/security/test_encryption_coverage.py (100%) rename tests/{ => unit}/security/test_encryption_coverage_gaps.py (100%) rename tests/{ => unit}/security/test_encryption_init_coverage.py (100%) rename tests/{ => unit}/security/test_ip_filter_coverage.py (100%) rename tests/{ => unit}/security/test_ip_filter_coverage_final.py (100%) rename tests/{ => unit}/security/test_ip_filter_coverage_gaps.py (100%) rename tests/{ => unit}/security/test_ip_filter_integration.py (100%) rename tests/{ => unit}/security/test_ip_filter_loading.py (100%) rename tests/{ => unit}/security/test_ip_filter_matching.py (100%) rename tests/{ => unit}/security/test_ip_filter_parsing.py (100%) rename tests/{ => unit}/security/test_ip_filter_rules.py (100%) rename tests/{ => unit}/security/test_key_manager.py (100%) rename tests/{ => unit}/security/test_mse_handshake.py (100%) rename tests/{ => unit}/security/test_mse_handshake_coverage.py (100%) rename tests/{ => unit}/security/test_mse_handshake_pe.py (100%) rename tests/{ => unit}/security/test_peer_validator.py (100%) rename tests/{ => unit}/security/test_rate_limiter.py (100%) rename tests/{ => unit}/security/test_rate_limiter_coverage_gaps.py (100%) rename tests/{ => unit}/security/test_security_manager.py (81%) create mode 100644 tests/unit/security/test_xet_allowlist.py create mode 100644 tests/unit/session/test_checkpoint_persistence.py delete mode 100644 tests/unit/storage/test_buffers_comprehensive.py delete mode 100644 tests/unit/storage/test_checkpoint_edge_cases.py delete mode 100644 tests/unit/storage/test_checkpoint_expanded.py delete mode 100644 tests/unit/storage/test_checkpoint_final_coverage.py delete mode 100644 tests/unit/storage/test_disk_io_cleanup_paths.py delete mode 100644 tests/unit/storage/test_disk_io_coverage_gaps.py delete mode 100644 tests/unit/storage/test_disk_io_init.py delete mode 100644 tests/unit/storage/test_disk_io_missing_coverage.py delete mode 100644 tests/unit/storage/test_file_attributes_assembler.py delete mode 100644 tests/unit/storage/test_resume_data.py create mode 100644 tests/unit/storage/test_xet_data_aggregator.py create mode 100644 tests/unit/storage/test_xet_defrag_prevention.py create mode 100644 tests/unit/storage/test_xet_file_deduplication.py 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..a4b3d60 100644 --- a/.cursor/rules/development-patterns.mdc +++ b/.cursor/rules/development-patterns.mdc @@ -87,6 +87,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_
_