Exceptions handling and structure

[mhchia]

1. We should revisit the whole codebase to ensure exceptions are well defined and handled well.
2. We don't have a good picture of the exception tree now. As a reference, in trinity, the package trinity has its own exception tree and so do p2p. I'm not sure what is the best structure for us, but I think probably a single exception tree(i.e. all exceptions inherit from BaseLibp2pError and its descendants) can be a start?

@ChihChengLiang @ralexstokes @NIC619 @pipermerriam

Would love to have your comment on it:)

[ChihChengLiang]

Agree to just inheriting every exception from BaseLibp2pError. Keep it simple.

[pipermerriam]

👍 to using a base exception for all library exceptions. It's a nice pattern to allow blanket catching of anything from this specific library.

[Abidoyesimze]

Hi,

I would like to work on this issue. I'm a full-stack blockchain developer with two years of experience in Python development and have worked extensively on exception handling and error management in large codebases.

My Approach

1. Exception Tree Design

I'll create a hierarchical exception structure inheriting from BaseLibp2pError:

BaseLibp2pError
├── NetworkError
│   ├── ConnectionError
│   ├── StreamError
│   └── TransportError
├── SecurityError
│   ├── SecioError
│   ├── CryptoError
│   └── AuthenticationError
├── ProtocolError
│   ├── MultistreamError
│   └── NegotiationError
└── PeerError
    ├── PeerIDError
    └── PeerStoreError

2. Implementation Steps

Phase 1: Audit & Documentation

• Conduct full codebase audit to identify all exception usage
• Document current exception patterns and inconsistencies
• Map exceptions to appropriate hierarchy levels

Phase 2: Base Exception Implementation

• Create libp2p/exceptions.py with BaseLibp2pError and hierarchy
• Add helpful error messages and context to each exception class
• Include __str__ and __repr__ methods for better debugging

Phase 3: Refactoring

• Replace generic exceptions with specific typed exceptions
• Update all raise statements throughout codebase
• Ensure proper exception chaining with raise ... from where appropriate

Phase 4: Exception Handling

• Add proper try/except blocks where missing
• Implement context managers where appropriate
• Add logging for caught exceptions

Phase 5: Testing & Documentation

• Write unit tests for exception scenarios
• Update documentation with exception handling examples
• Add exception reference guide

3. Key Features

• Clear hierarchy: Easy to catch broad or specific exception types
• Informative messages: Include context about what went wrong and why
• Backwards compatibility: Gradual migration path if needed
• Type safety: Proper exception typing for better IDE support
• Documentation: Clear examples of when each exception is raised

I'm confident I can deliver a clean, well-documented exception structure that improves code maintainability and debugging experience.

Kindly assign me to this issue.

Thanks!

[seetadev]

@Abidoyesimze : Please go ahead. Kindly keep @lla-dane, @acul71, @yashksaini-coder and @pacrob in the loop.

[Abidoyesimze]

Okay thanks,
On it

[Abidoyesimze]

Hi @lla-dane @acul71 @yashksaini-coder @pacrob

Here's some question i have after checking

1. Should async-service exceptions inherit from BaseLibp2pError, or remain separate?
2. Should exceptions that currently inherit from built-ins (KeyError, ValueError) use multiple inheritance?
3. Should i rename Bitswap's TimeoutError to avoid conflict with built-in?
4. Should enhanced resource manager errors be integrated into the base hierarchy or kept separate?
5. What's the preferred migration strategy for backwards compatibility?

[Abidoyesimze]

#1197