What

Summary

Introduces two core unified interfaces (i_protocol_client and i_protocol_server) that establish common contracts across all protocol implementations (TCP, UDP, HTTP, WebSocket, QUIC).

Change Type

• Refactor (architectural improvement)

Affected Components

• include/kcenon/network/interfaces/i_protocol_client.h - New client interface
• include/kcenon/network/interfaces/i_protocol_server.h - New server interface

Why

Related Issues

Closes #593
Part of #577 (EPIC: Apply Facade pattern to reduce protocol header complexity)

Motivation

Currently, each protocol (TCP, UDP, HTTP, WebSocket, QUIC) has its own client/server structure with duplicated patterns. This creates:

• Maintenance burden: Changes must be replicated across protocols
• Learning curve: Developers must understand each protocol's unique structure
• Testing complexity: Each protocol requires separate test infrastructure

These unified interfaces provide:

• Consistency: Uniform API across all protocols
• Maintainability: Single source of truth for protocol contracts
• Extensibility: New protocols can easily adopt the common interface
• Foundation: Required base for EPIC [EPIC] refactor: Apply Facade pattern to reduce protocol header complexity #577 facade implementation

Who

Reviewers

@kcenon - Architecture review

When

Urgency

• High Priority - Foundation for EPIC [EPIC] refactor: Apply Facade pattern to reduce protocol header complexity #577

Target Release

Milestone: EPIC #577 completion

Where

Files Created

Design Decisions

Both interfaces:

• Extend i_network_component for common lifecycle methods
• Use VoidResult return type for error handling consistency
• Support observer pattern via connection_observer
• Include comprehensive Doxygen documentation
• Provide protocol-specific behavior notes

How

Implementation Highlights

1. i_protocol_client Interface

   • Lifecycle: start(), stop(), is_connected()
   • Data transfer: send() with move semantics
   • Event handling: Observer pattern + legacy callbacks
   • Design: Protocol-agnostic with protocol-specific notes

2. i_protocol_server Interface

   • Lifecycle: start(), stop(), connection_count()
   • Session management: Via i_session interface
   • Event handling: Connection, disconnection, receive, error callbacks
   • Design: Unified across TCP, UDP, HTTP, WebSocket, QUIC

3. Documentation

   • Detailed Doxygen comments for all methods
   • Protocol-specific behavior notes (TCP vs UDP vs WebSocket)
   • Thread safety guarantees
   • Usage examples
   • Error condition documentation

Testing Done

• Code compiles without errors
• No warnings generated
• All existing tests pass (build verification)
• Interface-only change - no runtime tests required

Test Plan for Reviewers

1. Verify compilation: cmake --build build --config Release
2. Review interface design against existing i_client and i_server
3. Check documentation completeness
4. Confirm no breaking changes to existing code

Breaking Changes

None - This is an additive change. Existing code is not modified.
Protocols will be updated in subsequent PRs to implement these interfaces.

Next Steps

After this PR merges:

1. Update TCP implementations to implement i_protocol_client/i_protocol_server
2. Update UDP implementations
3. Update WebSocket implementations
4. Implement facade classes using these interfaces

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation added (comprehensive Doxygen)
• No breaking changes
• Compiles without warnings
• Related issue linked with closing keywords