Summary

Add unified transport interfaces to common_system to enable clean dependency injection for network communication across the ecosystem.

5W1H Specification

• Who: common_system maintainers
• What: Add IHttpClient and IUdpClient interfaces to common_system
• Where: include/kcenon/common/interfaces/transport/
• When: Before v0.4.0.0 (blocks monitoring_system and network_system integration)
• Why:
  • monitoring_system currently defines its own http_transport interface
  • network_system has its own client interfaces
  • Consolidating in common_system enables clean dependency inversion
• How: Create abstract interfaces that both modules can implement

Priority

CRITICAL - This is a blocking dependency for:

• monitoring_system network transport implementation
• network_system monitoring decoupling

Proposed Interface Design

File: include/kcenon/common/interfaces/transport/http_client_interface.h

#pragma once

#include <kcenon/common/patterns/result.h>
#include <map>
#include <span>
#include <string>
#include <vector>

namespace kcenon::common::interfaces {

class IHttpClient {
public:
    virtual ~IHttpClient() = default;

    struct request {
        std::string url;
        std::string method = "GET";
        std::map<std::string, std::string> headers;
        std::vector<uint8_t> body;
    };

    struct response {
        int status_code;
        std::map<std::string, std::string> headers;
        std::vector<uint8_t> body;
    };

    virtual auto send(const request& req) -> Result<response> = 0;
    virtual auto is_available() const -> bool = 0;
};

} // namespace kcenon::common::interfaces

File: include/kcenon/common/interfaces/transport/udp_client_interface.h

#pragma once

#include <kcenon/common/patterns/result.h>
#include <cstdint>
#include <span>
#include <string>

namespace kcenon::common::interfaces {

class IUdpClient {
public:
    virtual ~IUdpClient() = default;

    virtual auto connect(const std::string& host, uint16_t port) -> Result<void> = 0;
    virtual auto send(std::span<const uint8_t> data) -> Result<void> = 0;
    virtual auto is_connected() const -> bool = 0;
    virtual auto disconnect() -> void = 0;
};

} // namespace kcenon::common::interfaces

File: include/kcenon/common/interfaces/transport.h (umbrella header)

#pragma once

#include "transport/http_client_interface.h"
#include "transport/udp_client_interface.h"

Tasks

• Create include/kcenon/common/interfaces/transport/ directory structure
• Implement IHttpClient interface with request/response structs
• Implement IUdpClient interface with connection management
• Add umbrella header include/kcenon/common/interfaces/transport.h
• Add CMake install rules for new headers
• Add unit tests for interface concepts (compile-time validation)
• Update documentation with usage examples

CMake Integration

# In common_system/CMakeLists.txt
target_sources(${PROJECT_NAME} INTERFACE
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/kcenon/common/interfaces/transport.h>
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/kcenon/common/interfaces/transport/http_client_interface.h>
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/kcenon/common/interfaces/transport/udp_client_interface.h>
)

Acceptance Criteria

• IHttpClient interface compiles with C++20 concepts
• IUdpClient interface compiles with C++20 concepts
• Umbrella header transport.h properly includes all transport interfaces
• Headers are installed to correct location
• No runtime dependencies introduced (header-only)

Downstream Impact

Parent Epic

• Epic: Cross-Module Circular Dependency Resolution #232

Related Issues

• Epic: Unified feature-flag consolidation #223 (Feature Flag Consolidation)