Summary

Document the Unified API interface layer at include/kcenon/network/detail/unified/ that provides protocol-agnostic abstractions for connections, listeners, and transports.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

network_system has a unified abstraction layer that enables writing protocol-agnostic networking code. Through i_connection, i_listener, and i_transport interfaces, the same application code can work across TCP, UDP, WebSocket, QUIC, etc. This powerful abstraction is not documented.

Source files:

• include/kcenon/network/detail/unified/i_connection.h — Protocol-agnostic connection interface
• include/kcenon/network/detail/unified/i_listener.h — Protocol-agnostic listener interface
• include/kcenon/network/detail/unified/i_transport.h — Protocol-agnostic transport interface

Scope (What)

1. Unified API Architecture

• Purpose: Write-once networking code that works across protocols
• Interface hierarchy and relationships
• How concrete protocol implementations inherit from unified interfaces
• Factory pattern for creating protocol-specific instances

2. i_connection Interface (i_connection.h)

• Abstract connection methods: connect(), send(), receive(), close()
• Connection state machine (connecting → connected → closing → closed)
• Error handling and reconnection
• Properties: local/remote endpoints, connection metrics

3. i_listener Interface (i_listener.h)

• Abstract listener methods: bind(), listen(), accept(), stop()
• Connection acceptance callback
• Multi-protocol listening capability
• Backlog and concurrency configuration

4. i_transport Interface (i_transport.h)

• Transport-level abstraction
• Relationship to connections and listeners
• Transport configuration and capabilities
• Protocol negotiation

5. Protocol-Agnostic Code Example

// Works with any protocol
void send_message(i_connection& conn, const buffer& msg) {
    auto result = conn.send(msg);
    if (!result) {
        log_error("Send failed: {}", result.error());
    }
}

// Factory creates protocol-specific instances
auto tcp_conn = transport_factory::create_connection(protocol::tcp, config);
auto quic_conn = transport_factory::create_connection(protocol::quic, config);

// Same function works for both
send_message(*tcp_conn, msg);
send_message(*quic_conn, msg);

6. Supported Protocol Implementations

7. Extending with Custom Protocols

• How to implement unified interfaces for new protocols
• Required methods and contracts
• Registration with transport factory

Acceptance Criteria

• All 3 interfaces documented with full method signatures
• Connection state machine documented
• Protocol-agnostic code examples provided
• Protocol support matrix completed
• Factory pattern usage documented
• Custom protocol extension guide provided