Architecture

Architecture Overview¶

This document provides a technical overview of ccBitTorrent's architecture, components, and data flow.

Entry Points¶

ccBitTorrent provides multiple entry points for different use cases:

Basic CLI (ccbt): Simple command-line interface for single torrent downloads
Entry point: ccbt/__main__.py:main
Usage: python -m ccbt torrent.torrent or python -m ccbt "magnet:..."
Async CLI (ccbt async): High-performance async interface with full session management
Entry point: ccbt/session/async_main.py:main
Supports daemon mode, multiple torrents, and advanced features
Enhanced CLI (btbt): Rich command-line interface with comprehensive features
Entry point: ccbt/cli/main.py:main
Provides interactive commands, monitoring, and advanced configuration
Terminal Dashboard (bitonic): Live, interactive terminal dashboard (TUI)
Entry point: ccbt/interface/terminal_dashboard.py:main
Real-time visualization of torrents, peers, and system metrics

System Architecture¶

┌─────────────────────────────────────────────────────────────────┐
│                    ccBitTorrent Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│  CLI Interface                                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │   Basic     │ │ Interactive │ │  Dashboard   │              │
│  │   Commands  │ │     CLI     │ │   (TUI)     │              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│  Session Management                                             │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              AsyncSessionManager                           │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐          │ │
│  │  │   Config    │ │   Events    │ │  Checkpoint │          │ │
│  │  │  Manager    │ │   System    │ │   Manager   │          │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘          │ │
│  └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│  Core Components                                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │    Peer     │ │    Piece    │ │    Disk     │              │
│  │  Connection │ │   Manager   │ │     I/O     │              │
│  │  Manager    │ │             │ │   Manager   │              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │   Tracker   │ │     DHT     │ │  Metadata   │              │
│  │   Client    │ │   Manager   │ │  Exchange   │              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│  Network Layer                                                  │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │    TCP      │ │     UDP     │ │   WebRTC    │              │
│  │ Connections │ │  Trackers   │ │ (WebTorrent)│              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│  Monitoring & Observability                                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │   Metrics   │ │   Alerts    │ │   Tracing   │              │
│  │  Collector  │ │   Manager   │ │   Manager   │              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Core Components¶

Services Architecture¶

ccBitTorrent uses a service-oriented architecture with several core services:

PeerService: Manages peer connections and communication
Implementation: ccbt/services/peer_service.py
Tracks peer connections, bandwidth, and piece statistics
StorageService: Manages file system operations with high-performance chunked writes
Implementation: ccbt/services/storage_service.py
Handles file creation, data read/write operations
TrackerService: Manages tracker communication and health monitoring
Implementation: ccbt/services/tracker_service.py
Supports HTTP and UDP trackers with scrape support (BEP 48)

All services inherit from the base Service class which provides lifecycle management, health checks, and state tracking.

Implementation: ccbt/services/base.py

AsyncSessionManager¶

The central orchestrator that manages the entire BitTorrent session. There are two implementations:

AsyncSessionManager in ccbt/session/async_main.py: Used by the async CLI entry point, manages multiple torrents with protocol support.

The AsyncSessionManager class is defined in ccbt/session/async_main.py starting at line 319. Key initialization attributes include:

config: Configuration instance (uses global config if not provided)
torrents: Dictionary mapping torrent IDs to AsyncDownloadManager instances
metrics: MetricsCollector instance (initialized in start() if enabled)
disk_io_manager: Disk I/O manager (initialized in start())
security_manager: Security manager (initialized in start())
protocol_manager: ProtocolManager for managing multiple protocols
protocols: List of active protocol instances

See the full implementation:

AsyncSessionManager in ccbt/session/session.py: More comprehensive implementation with DHT, queue management, NAT traversal, and scrape support.

The more comprehensive AsyncSessionManager in ccbt/session/session.py (starting at line 1317) includes additional components:

dht_client: DHT client for peer discovery
peer_service: PeerService instance for managing peer connections
queue_manager: Torrent queue manager for prioritization
nat_manager: NAT traversal manager for port mapping
private_torrents: Set tracking private torrents (BEP 27)
scrape_cache: Cache for tracker scrape results (BEP 48)
Background tasks for cleanup, metrics collection, and periodic scraping

See the full implementation:

        # Stop NAT manager (unmaps all ports)
        if self.nat_manager:
            try:
                await self.nat_manager.stop()
                self.logger.debug("NAT manager stopped (ports unmapped)")
            except Exception as e:
                self.logger.debug("Error stopping NAT manager: %s", e, exc_info=True)

        # Stop peer service
        try:
            if self.peer_service:
                await self.peer_service.stop()
        except Exception:
            # Best-effort: log and continue
            self.logger.debug("Peer service stop failed", exc_info=True)

        self.logger.info("Async session manager stopped (all ports released)")

    async def reload_config(self, new_config: Any) -> None:
        """Reload configuration and update affected components.

        Args:
            new_config: New Config instance to apply

        """
        old_config = self.config
        self.config = new_config

        reloaded_components = []

        try:
            # Reload security manager if IP filters changed
            if (
                old_config.security.ip_filter.filter_files
                != new_config.security.ip_filter.filter_files
                or old_config.security.ip_filter.enable_ip_filter
                != new_config.security.ip_filter.enable_ip_filter
            ) and self.security_manager:
                try:
                    await self.security_manager.load_ip_filter(new_config)
                    reloaded_components.append("security_manager")
                    self.logger.info("Reloaded security manager with new IP filters")
                except Exception as e:
                    self.logger.warning("Failed to reload security manager: %s", e)

            # Reload DHT client if DHT config changed
            dht_config_changed = (
                old_config.discovery.enable_dht != new_config.discovery.enable_dht
                or old_config.discovery.dht_port != new_config.discovery.dht_port
            )

Responsibilities: - Torrent lifecycle management - Peer connection coordination via PeerService - Protocol management (BitTorrentProtocol, IPFSProtocol) - Resource allocation and limits - Event dispatching through EventBus - Checkpoint management - DHT client management - Queue management for torrent prioritization - NAT traversal via NATManager - Tracker scraping (BEP 48)

Session Controllers (refactor)¶

To improve maintainability, the session logic is being progressively extracted into focused controllers under ccbt/session/:

models.py: TorrentStatus enum and SessionContext
types.py: Protocols (DHTClientProtocol, TrackerClientProtocol, PeerManagerProtocol, PieceManagerProtocol)
tasks.py: TaskSupervisor for background task management
checkpointing.py: CheckpointController for save/load and batching
discovery.py: DiscoveryController for DHT/tracker discovery and dedup
peer_events.py: PeerEventsBinder for callback wiring
lifecycle.py: LifecycleController for start/pause/resume/stop sequencing
metrics_status.py: Metrics and status aggregation helpers
adapters.py: DHTAdapter and TrackerAdapter to unify concrete clients behind protocols

Peer Connection Manager¶

Handles all peer connections with advanced pipelining. The AsyncPeerConnectionManager manages individual peer connections for a torrent session.

Implementation: ccbt/peer/async_peer_connection.py

Features: - Async TCP connections - Request pipelining (16-64 outstanding requests) - Adaptive block sizing - Connection pooling - Choking/unchoking algorithms - BitTorrent protocol handshake - Extension protocol support (Fast, PEX, DHT, WebSeed, SSL, XET)

Piece Manager¶

Implements advanced piece selection algorithms. The AsyncPieceManager coordinates piece downloading, verification, and completion tracking.

Implementation: ccbt/piece/async_piece_manager.py

Algorithms: - Rarest-First: Optimal swarm health - Sequential: For streaming media - Round-Robin: Simple fallback - Endgame Mode: Duplicate requests for completion - File selection support for partial downloads

Disk I/O Manager¶

Optimized disk operations with multiple strategies. The disk I/O system is initialized via init_disk_io() and managed through the session manager.

Implementation: ccbt/storage/disk_io.py

Optimizations: - File preallocation (sparse/full) - Write batching and buffering - Memory-mapped I/O - io_uring support (Linux) - Direct I/O for high-performance storage - Parallel hash verification - Checkpoint management for resume capability

Data Flow¶

Download Process¶

1. Torrent Loading
   ┌─────────────┐
   │ Torrent File│ ──┐
   │ or Magnet   │   │
   └─────────────┘   │
                     │
2. Tracker Announce  │
   ┌─────────────┐   │
   │   Tracker  │ ◄──┘
   │   Client   │
   └─────────────┘
           │
           ▼
3. Peer Discovery
   ┌─────────────┐
   │    DHT     │
   │   Manager  │
   └─────────────┘
           │
           ▼
4. Peer Connections
   ┌─────────────┐
   │    Peer    │
   │ Connection │
   │   Manager  │
   └─────────────┘
           │
           ▼
5. Piece Selection
   ┌─────────────┐
   │    Piece    │
   │   Manager   │
   └─────────────┘
           │
           ▼
6. Data Transfer
   ┌─────────────┐
   │    Disk     │
   │     I/O     │
   │   Manager   │
   └─────────────┘

Event System¶

The system uses an event-driven architecture for loose coupling. Events are emitted through the global EventBus and can be subscribed to by any component.

Implementation: ccbt/utils/events.py

The event system includes comprehensive event types:

The EventType enum defines all system events including peer, piece, torrent, tracker, DHT, protocol, extension, and security events. The complete enum with all event types:

class EventType(Enum):
    """Built-in event types."""

    # Peer events
    PEER_CONNECTED = "peer_connected"
    PEER_DISCONNECTED = "peer_disconnected"
    PEER_HANDSHAKE_COMPLETE = "peer_handshake_complete"
    PEER_BITFIELD_RECEIVED = "peer_bitfield_received"

    # Piece events
    PIECE_REQUESTED = "piece_requested"
    PIECE_DOWNLOADED = "piece_downloaded"
    PIECE_VERIFIED = "piece_verified"
    PIECE_COMPLETED = "piece_completed"

    # Torrent events
    TORRENT_ADDED = "torrent_added"
    TORRENT_REMOVED = "torrent_removed"
    TORRENT_STARTED = "torrent_started"
    TORRENT_STOPPED = "torrent_stopped"
    TORRENT_COMPLETED = "torrent_completed"

    # Tracker events
    TRACKER_ANNOUNCE = "tracker_announce"
    TRACKER_ANNOUNCE_SUCCESS = "tracker_announce_success"
    TRACKER_ANNOUNCE_ERROR = "tracker_announce_error"

    # DHT events
    DHT_NODE_FOUND = "dht_node_found"
    DHT_PEER_FOUND = "dht_peer_found"
    DHT_QUERY_COMPLETE = "dht_query_complete"

    # System events
    SYSTEM_START = "system_start"
    SYSTEM_STOP = "system_stop"
    SYSTEM_ERROR = "system_error"

    # Performance events
    PERFORMANCE_METRIC = "performance_metric"
    BANDWIDTH_UPDATE = "bandwidth_update"
    DISK_IO_UPDATE = "disk_io_update"

    # Fast Extension events
    PIECE_SUGGESTED = "piece_suggested"
    PEER_HAVE_ALL = "peer_have_all"
    PEER_HAVE_NONE = "peer_have_none"
    REQUEST_REJECTED = "request_rejected"
    PIECE_ALLOWED_FAST = "piece_allowed_fast"

    # Extension Protocol events
    EXTENSION_HANDSHAKE = "extension_handshake"
    UNKNOWN_EXTENSION_MESSAGE = "unknown_extension_message"
    EXTENSION_ERROR = "extension_error"
    EXTENSION_STARTED = "extension_started"
    EXTENSION_STOPPED = "extension_stopped"

    # SSL Extension events
    SSL_NEGOTIATION = "ssl_negotiation"

    # Xet Extension events
    XET_CHUNK_REQUESTED = "xet_chunk_requested"
    XET_CHUNK_RECEIVED = "xet_chunk_received"
    XET_CHUNK_PROVIDED = "xet_chunk_provided"
    XET_CHUNK_NOT_FOUND = "xet_chunk_not_found"
    XET_CHUNK_ERROR = "xet_chunk_error"

    # PEX events
    PEER_DISCOVERED = "peer_discovered"
    PEER_DROPPED = "peer_dropped"

    # DHT events
    DHT_NODE_ADDED = "dht_node_added"
    DHT_NODE_REMOVED = "dht_node_removed"
    DHT_ERROR = "dht_error"

    # WebSeed events
    WEBSEED_ADDED = "webseed_added"
    WEBSEED_REMOVED = "webseed_removed"
    WEBSEED_DOWNLOAD_SUCCESS = "webseed_download_success"
    WEBSEED_DOWNLOAD_FAILED = "webseed_download_failed"
    WEBSEED_ERROR = "webseed_error"

    # Protocol events
    PROTOCOL_STARTED = "protocol_started"
    PROTOCOL_STOPPED = "protocol_stopped"
    PROTOCOL_STATE_CHANGED = "protocol_state_changed"
    PROTOCOL_REGISTERED = "protocol_registered"
    PROTOCOL_UNREGISTERED = "protocol_unregistered"
    PROTOCOL_ERROR = "protocol_error"
    SUB_PROTOCOL_STARTED = "sub_protocol_started"
    SUB_PROTOCOL_STOPPED = "sub_protocol_stopped"
    SUB_PROTOCOL_ERROR = "sub_protocol_error"
    SUB_PROTOCOL_ANNOUNCE = "sub_protocol_announce"
    HYBRID_ANNOUNCE = "hybrid_announce"

    # WebTorrent events
    WEBRTC_CONNECTION_ESTABLISHED = "webrtc_connection_established"
    WEBRTC_CONNECTION_FAILED = "webrtc_connection_failed"
    DATA_CHANNEL_OPENED = "data_channel_opened"
    DATA_CHANNEL_CLOSED = "data_channel_closed"

    # IPFS events
    IPFS_CONTENT_ADDED = "ipfs_content_added"
    IPFS_CONTENT_RETRIEVED = "ipfs_content_retrieved"
    IPFS_CONTENT_PINNED = "ipfs_content_pinned"
    IPFS_CONTENT_UNPINNED = "ipfs_content_unpinned"
    IPFS_PEER_DISCOVERED = "ipfs_peer_discovered"

    # Peer events
    PEER_ADDED = "peer_added"
    PEER_REMOVED = "peer_removed"
    PEER_CONNECTION_FAILED = "peer_connection_failed"

    # Tracker events
    TRACKER_ERROR = "tracker_error"

    # Security events
    SECURITY_EVENT = "security_event"
    SECURITY_BLACKLIST_ADDED = "security_blacklist_added"

Events are emitted using the global event bus via the emit_event() function:

    if _event_bus is None:
        _event_bus = EventBus()
    return _event_bus

Configuration System¶

Hierarchical Configuration¶

Configuration is managed by ConfigManager which loads settings from multiple sources in priority order.

Implementation: ccbt/config/config.py

The ConfigManager class handles configuration loading, validation, and hot-reload. It searches for configuration files in standard locations and supports encrypted proxy passwords. See the initialization:

class ConfigManager:
    """Manages configuration loading, validation, and hot-reload."""

    def __init__(self, config_file: str | Path | None = None):
        """Initialize configuration manager.

        Args:
            config_file: Path to TOML config file. If None, searches for ccbt.toml

        """
        # internal
        self._hot_reload_task: asyncio.Task | None = None
        self._encryption_key: bytes | None = None
        self.config_file = self._find_config_file(config_file)
        self.config = self._load_config()

Configuration Sources (in order): 1. Default values (from Pydantic models) 2. Configuration file (ccbt.toml in current directory, ~/.config/ccbt/ccbt.toml, or ~/.ccbt.toml) 3. Environment variables (CCBT_*) 4. CLI arguments 5. Per-torrent overrides

Hot Reload¶

The ConfigManager supports hot-reload of configuration files without restarting the application. Hot-reload is automatically started when a config file is detected.

Monitoring and Observability¶

Metrics Collection¶

Metrics collection is initialized via init_metrics() and provides Prometheus-compatible metrics.

Implementation: ccbt/monitoring/metrics_collector.py

Metrics are initialized in the session manager's start() method and can be accessed via session.metrics if enabled in configuration.

Alert System¶

The alert system provides rule-based alerting for various system conditions.

Implementation: ccbt/monitoring/alert_manager.py

Tracing¶

Distributed tracing support for performance analysis and debugging.

Implementation: ccbt/monitoring/tracing.py

Security Features¶

Security Manager¶

The SecurityManager provides comprehensive security features including IP filtering, peer validation, rate limiting, and anomaly detection.

Implementation: ccbt/security/security_manager.py

The security manager is initialized in the session manager's start() method and can load IP filters from configuration.

Peer Validation¶

Peer validation is handled by the PeerValidator which checks for blocked IPs and suspicious behavior patterns.

Implementation: ccbt/security/peer_validator.py

Rate Limiting¶

Adaptive rate limiting for bandwidth management is provided by the RateLimiter and AdaptiveLimiter (ML-based).

Implementation: ccbt/security/rate_limiter.py, ccbt/ml/adaptive_limiter.py

Extensibility¶

Plugin System¶

The plugin system allows for optional plugins and extensions to be registered and managed.

Implementation: ccbt/plugins/base.py

Plugins can be registered with the PluginManager and provide hooks for various system events.

Protocol Extensions¶

BitTorrent protocol extensions are managed by the ExtensionManager which handles Fast Extension, PEX, DHT, WebSeed, SSL, and XET extensions.

Implementation: ccbt/extensions/manager.py

The ExtensionManager initializes all supported BitTorrent extensions including Protocol, SSL, Fast, PEX, and DHT extensions. Each extension is registered with its capabilities and status. See the initialization logic:

class ExtensionManager:
    """Manages all BitTorrent extensions."""

    def __init__(self):
        """Initialize extension manager."""
        self.extensions: dict[str, Any] = {}
        self.extension_states: dict[str, ExtensionState] = {}
        self.peer_extensions: dict[str, dict[str, Any]] = {}  # peer_id -> extensions

        # Initialize extensions
        self._initialize_extensions()

    def _initialize_extensions(self) -> None:
        """Initialize all extensions."""
        # Extension Protocol
        protocol_ext = ExtensionProtocol()
        self.extensions["protocol"] = protocol_ext
        self.extension_states["protocol"] = ExtensionState(
            name="protocol",
            status=ExtensionStatus.ENABLED,
            capabilities={"extensions": {}},
            last_activity=0.0,
        )

        # Register SSL extension in protocol early so it's included in handshake
        ssl_ext = SSLExtension()
        protocol_ext.register_extension("ssl", "1.0", handler=None)

        # Fast Extension
        self.extensions["fast"] = FastExtension()
        self.extension_states["fast"] = ExtensionState(
            name="fast",
            status=ExtensionStatus.ENABLED,
            capabilities={
                "suggest": True,
                "have_all": True,
                "have_none": True,
                "reject": True,
                "allow_fast": True,
            },
            last_activity=0.0,
        )

        # Peer Exchange
        self.extensions["pex"] = PeerExchange()
        self.extension_states["pex"] = ExtensionState(
            name="pex",
            status=ExtensionStatus.ENABLED,
            capabilities={
                "added": True,
                "added.f": True,
                "dropped": True,
                "dropped.f": True,
            },
            last_activity=0.0,
        )

        # DHT
        self.extensions["dht"] = DHTExtension()
        self.extension_states["dht"] = ExtensionState(

Protocol Manager¶

The ProtocolManager manages multiple protocols (BitTorrent, IPFS, WebTorrent, XET, Hybrid) with circuit breaker support and performance tracking.

Implementation: ccbt/protocols/base.py

The ProtocolManager manages multiple protocols with circuit breaker support, performance tracking, and automatic event emission. Protocols are registered with their type and statistics are tracked per protocol. See the initialization and registration:

class ProtocolManager:
    """Manages multiple protocols with enhanced features."""

    def __init__(self):
        """Initialize protocol manager."""
        self.protocols: dict[ProtocolType, Protocol] = {}
        self.active_protocols: set[ProtocolType] = set()
        self.protocol_stats: dict[ProtocolType, ProtocolStats] = {}

        # Circuit breaker state
        self.circuit_breaker_state: dict[ProtocolType, dict[str, Any]] = {}
        self.failure_threshold = 5
        self.recovery_timeout = 60.0  # seconds

        # Performance metrics
        self.protocol_performance: dict[ProtocolType, float] = {}

    def register_protocol(self, protocol: Protocol) -> None:
        """Register a protocol."""
        self.protocols[protocol.protocol_type] = protocol
        self.protocol_stats[protocol.protocol_type] = ProtocolStats()

        # Emit protocol registered event
        try:
            loop = asyncio.get_running_loop()
            loop.create_task(  # noqa: RUF006
                emit_event(
                    Event(
                        event_type=EventType.PROTOCOL_REGISTERED.value,
                        data={
                            "protocol_type": protocol.protocol_type.value,
                            "timestamp": time.time(),
                        },
                    ),
                )
            )
        except RuntimeError:
            # No event loop running, skip event emission
            pass

Performance Optimizations¶

Async/Await Throughout¶

All I/O operations are asynchronous: - Network operations - Disk I/O - Hash verification - Configuration loading

Memory Management¶

Zero-copy message handling where possible
Ring buffers for high-throughput scenarios
Memory-mapped file I/O
Efficient data structures

Connection Pooling¶

Connection pooling is implemented in the peer connection layer to efficiently reuse TCP connections and manage connection limits.

Implementation: ccbt/peer/connection_pool.py

Testing Architecture¶

Test Categories¶

Unit Tests: Individual component testing
Integration Tests: Component interaction testing
Performance Tests: Benchmarking and profiling
Chaos Tests: Fault injection and resilience testing

Test Utilities¶

Test utilities and mocks are available in the tests/ directory for unit, integration, property, and performance testing.

Future Architecture Considerations¶

Scalability¶

Horizontal scaling with multiple session managers
Distributed peer discovery
Load balancing across instances

Cloud Integration¶

Cloud storage backends
Serverless deployment options
Container orchestration

Advanced Features¶

Machine learning for peer selection
Blockchain-based peer discovery
IPFS integration (Implemented)
WebTorrent compatibility

IPFS Protocol Integration¶

Architecture Overview¶

The IPFS protocol integration provides decentralized content addressing and peer-to-peer networking capabilities through an IPFS daemon.

Implementation: ccbt/protocols/ipfs.py

Integration Points¶

┌─────────────────────────────────────────────────────────────┐
│                    IPFS Protocol Integration                  │
├─────────────────────────────────────────────────────────────┤
│  Session Manager                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │         AsyncSessionManager                           │  │
│  │  ┌─────────────────────────────────────────────────┐ │  │
│  │  │         ProtocolManager                         │ │  │
│  │  │  ┌──────────────┐  ┌──────────────┐           │ │  │
│  │  │  │ BitTorrent   │  │    IPFS      │           │ │  │
│  │  │  │  Protocol    │  │  Protocol    │           │ │  │
│  │  │  └──────────────┘  └──────────────┘           │ │  │
│  │  └─────────────────────────────────────────────────┘ │  │
│  └───────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│  IPFS Protocol                                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   HTTP API   │  │   Pubsub     │  │     DHT      │     │
│  │  Client      │  │  Messaging   │  │  Discovery   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Content    │  │   Gateway    │  │   Pinning    │     │
│  │  Operations  │  │   Fallback   │  │   Manager    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
├─────────────────────────────────────────────────────────────┤
│  IPFS Daemon (External)                                      │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  IPFS Node (libp2p, Bitswap, DHT, Gateway)          │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Protocol Lifecycle¶

Initialization: Protocol created and registered in ProtocolManager
Connection: start() connects to IPFS daemon via HTTP API
Verification: Node ID queried to verify connection
Operation: Content operations, peer connections, messaging
Cleanup: stop() disconnects and cleans up resources

Session Manager Integration¶

The IPFS protocol is automatically registered during session manager startup if enabled in configuration. The protocol is registered with the protocol manager and started, with graceful error handling that doesn't prevent session startup if IPFS is unavailable. See the initialization:

Content Addressing¶

IPFS uses Content Identifiers (CIDs) for immutable content addressing:

CIDv0: Base58-encoded, legacy format (e.g., Qm...)
CIDv1: Multibase-encoded, modern format (e.g., bafybei...)
Content is addressed by its cryptographic hash
Same content always produces the same CID

Torrent-to-IPFS Conversion¶

Torrents can be converted to IPFS content:

Torrent metadata serialized to JSON
Metadata added to IPFS, generating CID
Piece hashes referenced as blocks
Content automatically pinned if configured

Peer Communication¶

Pubsub: Topic-based messaging (/ccbt/peer/{peer_id})
Multiaddr: Standard format for peer addresses
DHT: Distributed hash table for peer discovery
Message Queues: Per-peer queues for reliable delivery

Content Operations¶

Add: Content added to IPFS, returns CID
Get: Content retrieved by CID
Pin: Content pinned to prevent garbage collection
Unpin: Content unpinned, may be garbage collected
Stats: Content statistics (size, blocks, links)

Configuration¶

IPFS configuration is part of the main Config model. See the configuration documentation for details on IPFS settings.

Error Handling¶

Connection failures: Automatic retry with exponential backoff
Timeouts: Configurable per-operation timeouts
Daemon unavailable: Graceful degradation, protocol remains registered
Content not found: Returns None, logs warning

Performance Considerations¶

Async Operations: All IPFS API calls use asyncio.to_thread to avoid blocking
Caching: Discovery results and content stats cached with TTL
Gateway Fallback: Public gateways used if daemon unavailable
Connection Pooling: Reuses HTTP connections to IPFS daemon

Sequence Diagram¶

Session Manager          IPFS Protocol          IPFS Daemon
     │                         │                      │
     │  start()                │                      │
     ├────────────────────────>│                      │
     │                         │  connect()           │
     │                         ├─────────────────────>│
     │                         │  id()                │
     │                         ├─────────────────────>│
     │                         │<─────────────────────┤
     │                         │                      │
     │  add_content()           │                      │
     ├────────────────────────>│  add_bytes()         │
     │                         ├─────────────────────>│
     │                         │<─────────────────────┤
     │  <CID>                  │                      │
     │<────────────────────────┤                      │
     │                         │                      │
     │  get_content(CID)       │                      │
     ├────────────────────────>│  cat(CID)            │
     │                         ├─────────────────────>│
     │                         │<─────────────────────┤
     │  <content>               │                      │
     │<────────────────────────┤                      │
     │                         │                      │
     │  stop()                  │                      │
     ├────────────────────────>│  close()             │
     │                         ├─────────────────────>│
     │                         │<─────────────────────┤
     │                         │                      │

For more detailed information about specific components, see the individual documentation files and source code.