refactor: Unify all exceptions under BaseLibp2pError hierarchy

[Abidoyesimze]

Unify all exceptions under BaseLibp2pError hierarchy

• Enhanced BaseLibp2pError with error_code and context support
• Created intermediate base classes: NetworkError, ProtocolError, PeerError, ResourceError, ServiceError, DiscoveryError, PubsubError
• Refactored QUIC transport exceptions (24+) to inherit from NetworkError
• Refactored Bitswap errors to inherit from ProtocolError
• Renamed Bitswap TimeoutError to BitswapTimeoutError to avoid conflict
• Refactored Rendezvous discovery errors to inherit from DiscoveryError
• Refactored peer-related errors with multiple inheritance for backwards compatibility (PeerStoreError, PeerDataError, InvalidAddrError)
• Refactored resource manager exceptions to inherit from ResourceError
• Updated existing exceptions (SwarmException, PubsubRouterError) to use intermediate base classes
• Added comprehensive tests for exception inheritance
• All 12 exception tests passing

This implements the unified exception hierarchy as discussed in issue #XXX, allowing users to catch all libp2p errors with BaseLibp2pError while maintaining backwards compatibility where possible.

Breaking change: BitswapTimeoutError renamed from TimeoutError

What was wrong?

The codebase had inconsistent exception handling with approximately 50+ exceptions that did not inherit from BaseLibp2pError. This created several issues:

1. No unified exception catching: Users could not catch all libp2p-specific errors with a single exception type (BaseLibp2pError)
2. Inconsistent hierarchy: Exceptions were scattered across the codebase with different base classes:
   • Some inherited from BaseLibp2pError (network, security, transport, IO)
   • Others inherited directly from Exception (QUIC, Bitswap, Rendezvous, Resource Manager)
   • Some inherited from built-in exceptions like KeyError and ValueError (peer-related errors)
3. Poor error categorization: No logical grouping of exceptions, making it difficult to catch broad categories of errors
4. Naming conflicts: BitswapTimeoutError conflicted with Python's built-in TimeoutError
5. Limited error context: BaseLibp2pError lacked support for error codes and contextual information

This made error handling inconsistent and prevented users from easily catching all libp2p errors in their applications.

How was it fixed?

Approach

1. Enhanced BaseLibp2pError: Added support for error_code and context parameters, along with improved __str__ and __repr__ methods for better debugging.

2. Created Intermediate Base Classes: Introduced 7 logical base classes:

   • NetworkError - for network-related errors (connections, streams, transport)
   • ProtocolError - for protocol-related errors (negotiation, violations)
   • PeerError - for peer-related errors (peer store, peer data, addresses)
   • ResourceError - for resource management errors (limits, allocation)
   • ServiceError - for service lifecycle errors
   • DiscoveryError - for discovery-related errors (rendezvous, routing)
   • PubsubError - for pubsub-related errors

3. Refactored Exceptions Module by Module:

   • QUIC Transport (24+ exceptions): Changed QUICError to inherit from NetworkError
   • Bitswap (7 exceptions): Changed BitswapError to inherit from ProtocolError, renamed TimeoutError → BitswapTimeoutError
   • Rendezvous Discovery (8 exceptions): Changed RendezvousError to inherit from DiscoveryError
   • Peer-related (4 exceptions): Used multiple inheritance to maintain KeyError/ValueError compatibility while adding PeerError
   • Resource Manager (6+ exceptions): Changed all to inherit from ResourceError
   • Other exceptions: Updated InvalidMACException, CircuitBreakerError, etc.

4. Maintained Backwards Compatibility:

   • Used multiple inheritance for peer errors (PeerStoreError(PeerError, KeyError)) so code catching KeyError still works
   • Preserved all existing exception class names except the necessary TimeoutError rename
   • All existing exception catching patterns continue to work

5. Added Comprehensive Tests: Created 12 test cases verifying:

   • Exception inheritance from BaseLibp2pError
   • Proper inheritance through intermediate base classes
   • Multiple inheritance compatibility
   • Ability to catch all libp2p errors with BaseLibp2pError

Results

• ✅ ~50+ exceptions now inherit from BaseLibp2pError
• ✅ Unified exception hierarchy with logical grouping
• ✅ All tests passing (12/12 exception tests)
• ✅ Backwards compatible (except for BitswapTimeoutError rename)
• ✅ Better error context with error codes and context support

Example Usage

# Before: Could not catch all libp2p errors
try:
    # some libp2p operation
except BaseLibp2pError:  # Misses QUICError, BitswapError, etc.
    pass

# After: Can catch all libp2p errors
try:
    # some libp2p operation
except BaseLibp2pError:  # Catches everything!
    pass

# Can also catch by category
try:
    # network operation
except NetworkError:
    pass

try:
    # protocol operation
except ProtocolError:
    pass

To-Do

• Clean up commit history
• Add or update documentation related to these changes
• Add entry to the release notes

Cute Animal Picture