Network System

‍Language: English | 한국어

Overview

A modern C++20 asynchronous network library providing reusable transport primitives for distributed systems and messaging applications. Originally extracted from messaging_system for enhanced modularity and ecosystem-wide reusability.

Key Characteristics:

🏗️ Modular Architecture: Coroutine-friendly async I/O with pluggable protocol stack
⚡ High Performance: ASIO-based non-blocking operations with synthetic benchmarks showing ~769K msg/s for small payloads
🛡️ Production Grade: Comprehensive sanitizer coverage (TSAN/ASAN/UBSAN clean), RAII Grade A, multi-platform CI/CD
🔒 Secure: TLS 1.2/1.3 support, certificate validation, modern cipher suites
🌐 Cross-Platform: Ubuntu, Windows, macOS with GCC, Clang, MSVC support

Installation via vcpkg

Quick Start

# Using overlay ports from the kcenon vcpkg registry
vcpkg install kcenon-network-system \
  --overlay-ports=path/to/kcenon/vcpkg-registry/ports
 
# With SSL and ecosystem features enabled
vcpkg install kcenon-network-system[ssl,ecosystem] \
  --overlay-ports=path/to/kcenon/vcpkg-registry/ports

‍Registry-based consumption: For projects already using kcenon/vcpkg-registry, add the registry to your vcpkg-configuration.json and install without --overlay-ports.

Feature Matrix

Feature	Default	Description	Transitive Dependencies
(core)	always	Async TCP/UDP, WebSocket, HTTP/1.1, TLS	common_system, thread_system, asio, openssl, zlib
`ssl`	off	Explicit SSL/TLS support flag	openssl >= 3.0.0
`ecosystem`	off	Logger and container integration	logger_system, container_system
`testing`	off	Unit tests and benchmarks	gtest, benchmark
`samples`	off	Sample applications	—
`docs`	off	Doxygen documentation	—

CMake Integration

find_package(network_system CONFIG REQUIRED)

target_link_libraries(your_target PRIVATE network_system::network_system)

Minimal Example

#include <kcenon/network/facade/tcp_facade.h>
#include <iostream>
 
int main() {
    auto server = kcenon::network::tcp_facade::create_server({
        .port = 9090,
        .on_message = [](auto session, auto data) {
            std::cout << "Received: " << data << std::endl;
        }
    });
    server->start();
    return 0;
}

Requirements

Dependency	Version	Required	Description
C++20 Compiler	GCC 13+ / Clang 17+ / MSVC 2022+ / Apple Clang 14+	Yes	Higher requirements due to thread_system dependency
CMake	3.20+	Yes	Build system
ASIO	latest	Yes	Asynchronous I/O (standalone)
OpenSSL	3.x (recommended) / 1.1.1 (minimum)	Yes	TLS/SSL support
common_system	latest	Yes	Common interfaces and Result<T>
thread_system	latest	Yes	Thread pool and async operations
logger_system	latest	Yes	Logging infrastructure
container_system	latest	Yes	Data container operations

‍OpenSSL Version Note: OpenSSL 1.1.1 reached End-of-Life on September 11, 2023. We strongly recommend upgrading to OpenSSL 3.x for continued security support. The build system will display a warning if OpenSSL 1.1.1 is detected.

Dependency Flow

network_system
├── common_system (required)
├── thread_system (required)
│   └── common_system
├── logger_system (required)
│   └── common_system
└── container_system (required)
    └── common_system

‍Note: Unlike database_system, network_system does not have a compile-time dependency on monitoring_system. For observability, network_system uses EventBus-based metric publishing via common_system. External monitoring consumers (including monitoring_system) can subscribe to network_metric_event for metrics collection. See Monitoring Integration Guide for details.

Building with Dependencies

# Clone all dependencies
git clone https://github.com/kcenon/common_system.git
git clone https://github.com/kcenon/thread_system.git
git clone https://github.com/kcenon/logger_system.git
git clone https://github.com/kcenon/container_system.git
git clone https://github.com/kcenon/network_system.git
 
# Build network_system
cd network_system
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

📖 Quick Start Guide →

Quick Start

Prerequisites

Ubuntu/Debian (Ubuntu 22.04+ provides OpenSSL 3.x by default):

sudo apt update

sudo apt install -y cmake ninja-build libasio-dev libssl-dev liblz4-dev zlib1g-dev

macOS (OpenSSL 3.x via Homebrew):

brew install cmake ninja asio openssl@3 lz4 zlib

Windows (vcpkg):

# vcpkg provides OpenSSL 3.x

vcpkg install openssl asio lz4 zlib --triplet x64-windows

Windows (MSYS2):

pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja \

mingw-w64-x86_64-asio mingw-w64-x86_64-openssl

Build

git clone https://github.com/kcenon/network_system.git
cd network_system
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

C++20 Module Build (Experimental)

For C++20 module support (requires CMake 3.28+ and compatible compiler):

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DNETWORK_BUILD_MODULES=ON

cmake --build build -j

Usage with modules:

import kcenon.network;
 
int main() {
    auto server = std::make_unique<kcenon::network::core::messaging_server>("MyServer");
    server->start_server(8080);
    server->wait_for_stop();
}

Your First Server (60 seconds)

#include <kcenon/network/core/messaging_server.h>
#include <iostream>
 
int main() {
    auto server = std::make_shared<kcenon::network::core::messaging_server>("MyServer");
 
    auto result = server->start_server(8080);
    if (result.is_err()) {
        const auto& err = result.error();
        std::cerr << "Failed to start: " << err.message
                  << " (code: " << err.code << ")" << std::endl;
        return -1;
    }
 
    std::cout << "Server running on port 8080..." << std::endl;
    server->wait_for_stop();
    return 0;
}

Your First Client

#include <kcenon/network/core/messaging_client.h>
#include <iostream>
 
int main() {
    auto client = std::make_shared<kcenon::network::core::messaging_client>("MyClient");
 
    auto result = client->start_client("localhost", 8080);
    if (result.is_err()) {
        const auto& err = result.error();
        std::cerr << "Failed to connect: " << err.message
                  << " (code: " << err.code << ")" << std::endl;
        return -1;
    }
 
    // Send message (std::move avoids extra copies)
    std::string message = "Hello, Network System!";
    std::vector<uint8_t> data(message.begin(), message.end());
 
    auto send_result = client->send_packet(std::move(data));
    if (send_result.is_err()) {
        const auto& err = send_result.error();
        std::cerr << "Failed to send: " << err.message
                  << " (code: " << err.code << ")" << std::endl;
    }
 
    client->wait_for_stop();
    return 0;
}

Simplified Facade API (NEW in v2.0)

For even simpler usage, use the Facade API that hides template complexity:

#include <kcenon/network/facade/tcp_facade.h>
#include <iostream>
 
int main() {
    using namespace kcenon::network;
 
    // Create server with declarative configuration
    facade::tcp_facade facade;
    auto server = facade.create_server({
        .port = 8080,
        .server_id = "MyServer"
    });
 
    // Set callbacks
    server->set_receive_callback([&](auto session_id, const auto& data) {
        std::cout << "Received " << data.size() << " bytes\n";
        // Echo back
        server->send(session_id, data);
    });
 
    // Start server
    auto result = server->start(8080);
    if (result.is_err()) {
        std::cerr << "Failed: " << result.error().message << "\n";
        return -1;
    }
 
    std::cout << "Server running on port 8080...\n";
    server->wait_for_stop();
    return 0;
}

Benefits:

✅ No template parameters
✅ Clear configuration struct
✅ Protocol-agnostic interface
✅ Same performance as direct API

📖 Full Facade Documentation →

Modular Architecture (NEW)

Starting with v2.0, network_system is organized into protocol-specific libraries for improved maintainability and selective linking.

Library Overview

Library	Description	Dependencies
`network-core`	Core interfaces and session management	None
`network-tcp`	TCP protocol with SSL/TLS support	network-core, ASIO, OpenSSL
`network-udp`	UDP datagram protocol	network-core, ASIO
`network-websocket`	WebSocket (RFC 6455)	network-tcp
`network-http2`	HTTP/2 multiplexed protocol	network-websocket
`network-quic`	QUIC (RFC 9000)	network-udp, OpenSSL
`network-grpc`	gRPC high-performance RPC	network-quic
`network-all`	Umbrella package (all protocols)	All above

Dependency Graph

           network-core
           /    |    \
          /     |     \
   network-tcp  |  network-udp
         |      |      |
network-websocket    network-quic
         |             |
     network-http2  network-grpc

Selective Linking

Link only the protocols your application needs:

# Option 1: All protocols (simple, larger binary)
find_package(network-all REQUIRED)
target_link_libraries(my_app PRIVATE kcenon::network-all)
 
# Option 2: Specific protocols (smaller binary)
find_package(network-tcp REQUIRED)
find_package(network-udp REQUIRED)
target_link_libraries(my_app PRIVATE
    kcenon::network-tcp
    kcenon::network-udp
)

Umbrella Header

Include all protocols with a single header:

#include <network_all/network.h>
 
// Check protocol availability at compile time
#if NETWORK_ALL_HAS_QUIC
    auto quic_conn = protocol::quic::connect({...});
#endif

📖 Migration Guide → | Library READMEs

Core Features

Protocols

TCP: Asynchronous TCP server/client with lifecycle management
- Non-blocking I/O, automatic reconnection, health monitoring
- Multi-threaded message processing, session management
UDP: Connectionless UDP for real-time applications
- Low-latency datagram transmission, broadcast/multicast support
TLS/SSL: Secure communication (TLS 1.2/1.3)
- Modern cipher suites (AES-GCM, ChaCha20-Poly1305)
- Certificate validation, forward secrecy (ECDHE)
WebSocket: RFC 6455 compliant
- Text and binary message framing, ping/pong keepalive
- Fragmentation/reassembly, graceful connection lifecycle
HTTP/1.1: Server and client with advanced features
- Routing, cookies, multipart/form-data, chunked encoding
- Automatic compression (gzip/deflate)
QUIC: RFC 9000/9001/9002 compliant
- UDP-based multiplexed transport with TLS 1.3 encryption
- Stream multiplexing, 0-RTT connection resumption
- Loss detection and congestion control
- Connection migration support
gRPC: High-performance RPC framework (NEW)
- Official gRPC library wrapper with network_system integration
- Service registry with dynamic method registration
- All streaming modes (unary, server, client, bidirectional)
- Health checking and reflection support
- Result<T> to gRPC Status conversion

📖 Detailed Protocol Documentation → 📖 gRPC Guide →

Distributed Tracing

OpenTelemetry-compatible distributed tracing for observability:

W3C Trace Context: Standard context propagation across service boundaries
RAII Spans: Automatic span lifecycle management with NETWORK_TRACE_SPAN macro
Multiple Exporters: Console, OTLP HTTP/gRPC, Jaeger, Zipkin support
Sampling: Always-on, always-off, trace-id-based, parent-based samplers
Rich Attributes: String, integer, double, boolean attributes and events

#include <kcenon/network/tracing/tracing_config.h>
#include <kcenon/network/tracing/trace_context.h>
 
// Configure tracing (once at startup)
auto config = tracing_config::otlp_http("http://localhost:4318/v1/traces");
config.service_name = "my-service";
configure_tracing(config);
 
// Create spans using RAII
void process_request() {
    NETWORK_TRACE_SPAN("http.request.process");
    _span.set_attribute("http.method", "POST");
    _span.set_attribute("http.url", "/api/orders");
 
    // Child spans inherit trace context
    {
        auto db_span = trace_context::current().create_child_span("database.query");
        db_span.set_attribute("db.system", "postgresql");
        // ... perform database operation
        db_span.set_status(span_status::ok);
    }
 
    _span.set_status(span_status::ok);
}

📖 Tracing Guide →

Asynchronous Model

ASIO-Based: Non-blocking event loop with async operations
C++20 Coroutines: Optional coroutine-based async helpers
C++20 Concepts: Compile-time type validation with clear error messages
Pipeline Architecture: Message transformation with compression/encryption hooks
Move Semantics: Zero-copy friendly APIs (move-aware buffer handling)

Failure Handling

All server/client start helpers return Result<void>; check result.is_err() before continuing and log result.error().message.
For historical fixes (session cleanup, backpressure, TLS rollout), review IMPROVEMENTS.md to understand the safeguards already in place and how to react if regression symptoms reappear.
When building higher-level services, propagate common::error_info up the stack so monitoring and alerting pipelines can correlate failures across tiers.

Error Handling

Result<T> Pattern (75-80% migrated):

auto result = server->start_server(8080);
if (result.is_err()) {
    const auto& err = result.error();
    std::cerr << "Error: " << err.message
              << " (code: " << err.code << ")\n";
    return -1;
}

Error Codes (-600 to -699):

Connection (-600 to -619): connection_failed, connection_refused, connection_timeout
Session (-620 to -639): session_not_found, session_expired
Send/Receive (-640 to -659): send_failed, receive_failed, message_too_large
Server (-660 to -679): server_not_started, server_already_running, bind_failed

Performance Highlights

Synthetic Benchmarks (Intel i7-12700K, Ubuntu 22.04, GCC 11, `-O3`)

Payload	Throughput	Latency (ns/op)	Scope
64 bytes	~769K msg/s	1,300	CPU-only (allocation + memcpy)
256 bytes	~305K msg/s	3,270	CPU-only (allocation + memcpy)
1 KB	~128K msg/s	7,803	CPU-only (allocation + memcpy)
8 KB	~21K msg/s	48,000	CPU-only (allocation + memcpy)

Real I/O Benchmarks (Loopback TCP)

Benchmark	Payload	Scope
TCP Connection Establish	N/A	Connect + disconnect via loopback
TCP Echo Roundtrip	64B, 1KB, 8KB	Send + receive through kernel TCP stack
TCP Stream Throughput	1KB, 64KB	Sustained bytes/sec over loopback

Note: Synthetic benchmarks measure CPU-only operations without real network I/O. Real I/O benchmarks use a TCP echo server on the loopback interface to measure actual kernel TCP stack overhead.

Reproducing Benchmarks

# Build with benchmarks
cmake -B build -DCMAKE_BUILD_TYPE=Release -DNETWORK_BUILD_BENCHMARKS=ON
cmake --build build -j
 
# Run all benchmarks
./build/benchmarks/network_benchmarks
 
# Run synthetic benchmarks only
./build/benchmarks/network_benchmarks --benchmark_filter=MessageThroughput
 
# Run real I/O benchmarks only
./build/benchmarks/network_benchmarks --benchmark_filter=TCP

⚡ Full Benchmarks & Load Testing →

Platform: Apple M1 @ 3.2GHz (when tested on Apple Silicon)

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Network System Architecture                  │
├─────────────────────────────────────────────────────────────────┤
│  Public API Layer                                               │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐    │
│  │ messaging    │ │ messaging    │ │  messaging_ws        │    │
│  │ _server      │ │ _client      │ │  _server / _client   │    │
│  │ (TCP)        │ │ (TCP)        │ │  (WebSocket)         │    │
│  └──────────────┘ └──────────────┘ └──────────────────────┘    │
│  ┌──────────────────────┐ ┌─────────────────────────┐          │
│  │ secure_messaging     │ │ secure_messaging        │          │
│  │ _server (TLS/SSL)    │ │ _client (TLS/SSL)       │          │
│  └──────────────────────┘ └─────────────────────────┘          │
│  ┌──────────────────────┐ ┌─────────────────────────┐          │
│  │ messaging_quic       │ │ messaging_quic          │          │
│  │ _server (QUIC)       │ │ _client (QUIC)          │          │
│  └──────────────────────┘ └─────────────────────────┘          │
├─────────────────────────────────────────────────────────────────┤
│  Protocol Layer                                                 │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐    │
│  │ tcp_socket   │ │ udp_socket   │ │ websocket_socket     │    │
│  └──────────────┘ └──────────────┘ └──────────────────────┘    │
│  ┌──────────────────────┐ ┌──────────────────────────────┐     │
│  │ secure_tcp_socket    │ │ websocket_protocol           │     │
│  │ (SSL stream wrapper) │ │ (frame/handshake/msg handle) │     │
│  └──────────────────────┘ └──────────────────────────────┘     │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │ protocols/quic/ (RFC 9000/9001/9002)                     │  │
│  │ connection, stream, packet, frame, crypto, varint        │  │
│  └──────────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  Session Management Layer                                       │
│  ┌──────────────┐ ┌──────────────┐ ┌────────────────────────┐  │
│  │ messaging    │ │ secure       │ │ ws_session_manager     │  │
│  │ _session     │ │ _session     │ │ (WebSocket mgmt)       │  │
│  │ (TCP)        │ │ (TLS/SSL)    │ │                        │  │
│  └──────────────┘ └──────────────┘ └────────────────────────┘  │
│  ┌────────────────────────────────────────────────────────────┐│
│  │ quic_session (QUIC session management)                     ││
│  └────────────────────────────────────────────────────────────┘│
├─────────────────────────────────────────────────────────────────┤
│  Core Network Engine (ASIO-based)                              │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐              │
│  │ io_context  │ │   async     │ │  Result<T>  │              │
│  │             │ │  operations │ │   pattern   │              │
│  └─────────────┘ └─────────────┘ └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Design Patterns: Factory, Observer, Strategy, RAII, Template Metaprogramming

🏛️ Detailed Architecture Guide →

Ecosystem Integration

Ecosystem Dependency Map

graph TD
    A[common_system] --> B[thread_system]
    A --> C[container_system]
    B --> D[logger_system]
    B --> E[monitoring_system]
    D --> F[database_system]
    E --> F
    F --> G[network_system]
    G --> H[pacs_system]
 
    style G fill:#f9f,stroke:#333,stroke-width:3px

‍Ecosystem reference: common_system — Result<T>, interfaces, and shared utilities thread_system — Thread pool and async execution primitives container_system — Type-safe data serialization logger_system — Logging infrastructure database_system — Database operations (depends on network_system) pacs_system — DICOM/PACS system (consumes network_system)

Related Projects

This system integrates seamlessly with:

messaging_system: High-performance message routing and delivery
container_system: Type-safe data serialization (MessagePack, FlatBuffers)
thread_system: Thread pool management for concurrent operations
logger_system: Comprehensive network diagnostics and logging
database_system: Network-based database operations and clustering

Integration Example

#include <kcenon/network/core/messaging_server.h>
#include <kcenon/network/integration/thread_system_adapter.h>
 
using namespace kcenon::network;
 
int main() {
    // Bind thread_system for unified thread management
#if KCENON_WITH_THREAD_SYSTEM
    integration::bind_thread_system_pool_into_manager("network_pool");
#endif
 
    // Create and start server
    auto server = std::make_shared<core::messaging_server>("IntegratedServer");
    auto result = server->start_server(8080);
 
    if (result.is_err()) {
        std::cerr << "Failed: " << result.error().message << std::endl;
        return -1;
    }
 
    // Get thread pool metrics
    auto& manager = integration::thread_integration_manager::instance();
    auto metrics = manager.get_metrics();
    std::cout << "Workers: " << metrics.worker_threads << std::endl;
 
    server->wait_for_stop();
    return 0;
}

Thread Pool Adapters

Bidirectional adapters enable interoperability between network_system's thread pool and common_system's executor:

#include <kcenon/network/integration/thread_pool_adapters.h>
 
using namespace kcenon::network::integration;
 
// Use network_system pool where IExecutor is expected
auto network_pool = thread_integration_manager::instance().get_thread_pool();
auto executor = std::make_shared<network_to_common_thread_adapter>(network_pool);
// Pass executor to messaging_system, database_system, etc.
 
// Use external IExecutor in network_system
auto external_executor = container.resolve<common::interfaces::IExecutor>();
auto adapted = std::make_shared<common_to_network_thread_adapter>(external_executor);
thread_integration_manager::instance().set_thread_pool(adapted);

🌐 Full Integration Guide →

Documentation

Getting Started

📖 Features Guide - Comprehensive feature descriptions
🏗️ Architecture - System design and patterns
📘 API Reference - Complete API documentation
🔧 Build Guide - Detailed build instructions
🚀 Migration Guide - Migrating from messaging_system

Advanced Topics

⚡ Performance & Benchmarks - Performance metrics and testing
🏭 Production Quality - CI/CD, security, quality assurance
📁 Project Structure - Directory organization and modules
🧩 C++20 Concepts - Compile-time type validation
🔒 TLS Setup Guide - TLS/SSL configuration
🔍 Troubleshooting - Common issues and solutions
🧪 Load Test Guide - Load testing procedures
📝 Design Decisions - Architectural patterns and rationale

Development

🔄 Integration Guide - Ecosystem integration patterns
📊 Operations Guide - Deployment and operations
📋 Changelog - Version history and updates

Platform Support

Platform	Compiler	Architecture	Support Level
Ubuntu 22.04+	GCC 13+	x86_64, ARM64	✅ Full Support
Ubuntu 22.04+	Clang 17+	x86_64, ARM64	✅ Full Support
Windows 2022+	MSVC 2022+	x86_64	✅ Full Support
Windows 2022+	MinGW64	x86_64	✅ Full Support
macOS 12+	Apple Clang 14+	x86_64, ARM64	✅ Full Support

Production Quality

CI/CD Infrastructure

Comprehensive Multi-Platform Testing:

✅ Sanitizer Coverage: ThreadSanitizer, AddressSanitizer, UBSanitizer
✅ Multi-Platform: Ubuntu (GCC/Clang), Windows (MSVC/MinGW), macOS
✅ Performance Gates: Automated regression detection
✅ Static Analysis: clang-tidy, cppcheck with modernize checks
✅ Code Coverage: ~80% with Codecov integration

Security

TLS/SSL Implementation:

TLS 1.2/1.3 protocol support
Modern cipher suites (AES-GCM, ChaCha20-Poly1305)
Forward secrecy (ECDHE), certificate validation
Hostname verification, optional certificate pinning

Additional Security:

Input validation and buffer overflow protection
WebSocket origin validation and frame masking
HTTP request size limits and path traversal protection
Cookie security (HttpOnly, Secure, SameSite)

Thread Safety & Memory Safety

Thread Safety:

✅ Comprehensive synchronization (mutex, atomic, shared_mutex)
✅ ThreadSanitizer clean (zero data races)
✅ Concurrent session handling tested

Memory Safety (RAII Grade A):

✅ 100% smart pointer usage (std::shared_ptr, std::unique_ptr)
✅ Zero manual memory management
✅ AddressSanitizer clean (zero leaks, zero buffer overflows)
✅ Automatic resource cleanup via RAII

🛡️ Complete Production Quality Guide →

Dependencies

Required

C++20 compatible compiler (GCC 13+, Clang 17+, MSVC 2022+, Apple Clang 14+)

‍Note: The higher GCC/Clang requirements come from the thread_system dependency, which requires GCC 13+ and Clang 17+ for full C++20 feature support.

CMake 3.20+

ASIO or Boost.ASIO 1.28+

OpenSSL 3.x recommended / 1.1.1+ minimum (for TLS/SSL and WebSocket)

common_system (Result<T> pattern, common interfaces)

thread_system (thread pool integration)

logger_system (structured logging)

container_system (data container operations)

fmt 10.0.0+ (formatting library)

zlib (compression support)

Build Options

Using CMake Presets (Recommended)

CMake presets provide standardized build configurations:

# List available presets
cmake --list-presets
 
# Configure with a preset
cmake --preset debug          # Debug build
cmake --preset release        # Release build
cmake --preset asan           # AddressSanitizer
cmake --preset tsan           # ThreadSanitizer
cmake --preset ubsan          # UndefinedBehaviorSanitizer
cmake --preset coverage       # Code coverage
 
# Build
cmake --build --preset debug
 
# Test with sanitizer-specific environment
ctest --preset asan           # Runs with ASAN_OPTIONS configured
ctest --preset tsan           # Runs with TSAN_OPTIONS configured

Manual CMake Configuration

# Basic build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
 
# With sanitizers (mutually exclusive)
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON   # AddressSanitizer
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_TSAN=ON   # ThreadSanitizer
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_UBSAN=ON  # UndefinedBehaviorSanitizer
 
# With benchmarks
cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DNETWORK_BUILD_BENCHMARKS=ON
 
# With tests
cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_TESTS=ON
 
# With optional integrations
cmake -B build -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_WITH_THREAD_SYSTEM=ON \
    -DBUILD_WITH_LOGGER_SYSTEM=ON \
    -DBUILD_WITH_CONTAINER_SYSTEM=ON
 
# Build and run tests
cmake --build build -j
cd build && ctest --output-on-failure

Cleaning Build Directories

To remove all build directories at once:

./scripts/clean.sh

‍Tip: Prefer cmake --preset <name> over manual mkdir build_* directories. Named presets produce consistent, reproducible builds and avoid build directory proliferation.

Available CMake Options

Option	Default	Description
`BUILD_TESTS`	ON	Build unit tests
`BUILD_SAMPLES`	ON	Build sample applications
`BUILD_TLS_SUPPORT`	ON	Enable TLS/SSL support
`BUILD_WEBSOCKET_SUPPORT`	ON	Enable WebSocket protocol
`NETWORK_BUILD_BENCHMARKS`	OFF	Build performance benchmarks
`ENABLE_ASAN`	OFF	Enable AddressSanitizer
`ENABLE_TSAN`	OFF	Enable ThreadSanitizer
`ENABLE_UBSAN`	OFF	Enable UndefinedBehaviorSanitizer
`ENABLE_COVERAGE`	OFF	Enable code coverage
`NETWORK_ENABLE_GRPC_OFFICIAL`	OFF	Use official gRPC library

Examples

Complete examples are available in the samples/ directory:

basic_usage.cpp - Basic TCP client/server
simple_tcp_server.cpp - TCP server with session management
simple_tcp_client.cpp - TCP client with reconnection
simple_http_server.cpp - HTTP server with routing
simple_http_client.cpp - HTTP client with various request types
websocket_example.cpp - WebSocket server and client
quic_server_example.cpp - QUIC server with multi-stream support
quic_client_example.cpp - QUIC client with stream multiplexing
grpc_service_example.cpp - gRPC service registration and management

Build and run examples:

cmake --build build --target samples
./build/bin/simple_tcp_server
./build/bin/simple_tcp_client

Roadmap

Recently Completed

✅ QUIC Protocol Support: RFC 9000/9001/9002 compliant implementation
✅ gRPC Integration: Official gRPC library wrapper with full streaming support

Current Focus

🚧 Real network load test validation and baseline establishment
🚧 Complete Result<T> migration (currently 75-80%)
🚧 Documentation examples update

Planned Features

🚧 Connection Pooling: Enterprise-grade connection management
🚧 Zero-Copy Pipelines: Eliminate unnecessary buffer copies
🚧 HTTP/2 Client: Modern HTTP/2 protocol support

See IMPROVEMENTS.md for detailed roadmap and tracking.

Contributing

Contributions are welcome! Please see our Contributing Guide for detailed guidelines.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Follow the Coding Style Rules
Commit changes with conventional commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Before submitting:

Ensure all tests pass (ctest)
Run sanitizers (TSAN, ASAN, UBSAN)
Check code formatting (clang-format)
Update documentation as needed

License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.

Contact & Support

Contact Type	Details
Project Owner	kcenon (kceno.nosp@m.n@na.nosp@m.ver.c.nosp@m.om)
Repository	https://github.com/kcenon/network_system
Issues & Bug Reports	https://github.com/kcenon/network_system/issues
Discussions & Questions	https://github.com/kcenon/network_system/discussions

Acknowledgments

Core Dependencies

ASIO Library Team: Foundation of asynchronous network programming
C++ Standards Committee: C++20 features enabling modern networking

Ecosystem Integration

Thread System: Seamless thread pool integration
Logger System: Comprehensive logging and debugging
Container System: Advanced serialization support
Database System: Network-database integration patterns
Monitoring System: Performance metrics and observability

Made with ❤️ by 🍀☀🌕🌥 🌊

Network System

Table of Contents

Overview

Installation via vcpkg

Quick Start

Feature Matrix

CMake Integration

Minimal Example

Requirements

Dependency Flow

Building with Dependencies

Quick Start

Prerequisites

Build

C++20 Module Build (Experimental)

Your First Server (60 seconds)

Your First Client

Simplified Facade API (NEW in v2.0)

Modular Architecture (NEW)

Library Overview

Dependency Graph

Selective Linking

Umbrella Header

Core Features

Protocols

Distributed Tracing

Asynchronous Model

Failure Handling

Error Handling

Performance Highlights

Synthetic Benchmarks (Intel i7-12700K, Ubuntu 22.04, GCC 11, -O3)

Real I/O Benchmarks (Loopback TCP)

Reproducing Benchmarks

Architecture Overview

Ecosystem Integration

Ecosystem Dependency Map

Related Projects

Integration Example

Thread Pool Adapters

Documentation

Getting Started

Advanced Topics

Development

Platform Support

Production Quality

CI/CD Infrastructure

Security

Thread Safety & Memory Safety

Dependencies

Required

Build Options

Using CMake Presets (Recommended)

Manual CMake Configuration

Cleaning Build Directories

Available CMake Options

Examples

Roadmap

Recently Completed

Current Focus

Planned Features

Contributing

License

Contact & Support

Acknowledgments

Core Dependencies

Ecosystem Integration

Synthetic Benchmarks (Intel i7-12700K, Ubuntu 22.04, GCC 11, `-O3`)