Summary

Document the DTLS (Datagram Transport Layer Security) socket implementation and the resilient client with automatic reconnection capabilities.

Parent Issue

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

Background (Why)

network_system includes two internal utility components that are critical for production reliability but undocumented:

1. DTLS Socket — TLS over UDP for secure datagram communication
2. Resilient Client — Automatic reconnection with exponential backoff

Both are in src/internal/ indicating they're internal implementations, but they affect user-facing behavior significantly.

Source files:

• src/internal/tcp/dtls_socket.h — DTLS socket implementation
• src/internal/dtls_socket.cpp — DTLS implementation
• src/internal/utils/resilient_client.h — Auto-reconnecting client
• src/internal/utils/resilient_client.cpp — Resilient client implementation

Scope (What)

1. DTLS Socket (dtls_socket.h)

Overview

• DTLS purpose: TLS security for UDP datagrams
• RFC compliance (DTLS 1.2/1.3)
• Relationship to TLS socket implementation

API

• Socket creation and configuration
• DTLS handshake process (different from TLS due to unreliable transport)
• Cookie exchange for DoS prevention
• Sending/receiving secure datagrams
• Certificate handling

Use Cases

• IoT sensor data encryption
• VoIP/real-time media security
• DNS over DTLS
• Game server secure communication

2. Resilient Client (resilient_client.h)

Overview

• Automatic reconnection for unreliable networks
• Exponential backoff algorithm
• Connection state preservation

Configuration

• Max retry count
• Initial/max backoff delay
• Jitter factor
• Health check interval
• On-reconnect callback

Reconnection Strategy

• Detection of connection loss
• Backoff algorithm: initial_delay × 2^attempt + random_jitter
• Circuit breaker integration (if any)
• State restoration after reconnection

Usage

auto client = resilient_client::create(tcp_facade)
    .endpoint("server:8080")
    .max_retries(10)
    .initial_backoff(std::chrono::seconds(1))
    .max_backoff(std::chrono::minutes(5))
    .on_reconnect([](auto& conn) {
        conn.send(re_auth_message());
    })
    .build();

3. Combined Usage

• DTLS with resilient client for robust IoT communication
• Production deployment patterns

Acceptance Criteria

• DTLS socket API documented
• DTLS handshake process explained
• Resilient client configuration documented
• Backoff algorithm explained with parameters
• Usage examples for both components
• Production deployment patterns provided