# zhllxt/asio2 architecture

> Architecture diagram of the GitHub repository zhllxt/asio2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhllxt/asio2
- Repository: https://github.com/zhllxt/asio2

## Overview

##### Project Type and Purpose
- This is an open-source, header-only C++ network library (“asio2”) built on top of standalone Asio (or Boost.Asio).
- It provides a unified API for TCP, UDP (including reliable KCP), HTTP/HTTPS, WebSocket/WSS, RPC, ICMP (ping), serial port I/O, timers, and utility functions (e.g., encryption, base64, event dispatching).

##### High-Level Structure from File Tree
- Top-level directories:
- /asio2 – the public API (core base modules, protocol modules, components)
- 3rd – bundled third-party libraries (asio, cereal, fmt, openssl, spdlog)
- example – usage examples for each protocol/service
- test – unit & benchmark tests
- doc – tutorials and design notes
- Core base under include/asio2/base: session management, servers, clients, iopools, timers, logging, error handling.
- Protocol layers under include/asio2: tcp/, udp/, http/, websocket/, rpc/, mqtt/, icmp/, serial_port/, proxy/ etc.
- Components under include/asio2/component: reusable modules like socks5, rdc, etc.
- Utilities under include/asio2/util: crypto, compression, threading, event dispatcher.

##### Key Architectural Patterns
- Layered modules:
- External dependencies (Asio, OpenSSL, cereal, fmt, spdlog)
- Core engine (I/O context pool, server/client/session abstractions, timers, events)
- Protocol adapters (specialized send/receive, framing, handlers)
- Components (higher-level features: RPC invokers, SOCKS5, publish/subscribe)
- Examples and tests (demonstrating composition of layers)
- Inversion-of-Control: users bind callbacks (connect, recv, disconnect).
- Composition over inheritance: protocol modules compose core base rather than inherit heavy frameworks.
- Header-only, template-driven extensibility: all modules compile in client code, no separate linking.

##### Main Components and Interactions
- External libs → provide low-level I/O, serialization, logging, crypto.
- Core Engine (asio2::iopool, server, client, session, timer, condition_event)
- Manages Asio’s io_context threads, dispatches async operations, ensures orderly start/stop, safe shutdown.
- Protocol Modules
- TCP/TCPS (SSL), UDP/KCP, HTTP/HTTPS, WebSocket/WSS, RPC/RPCS, MQTT, ICMP, Serial Port.
- Each module exposes server/client/session classes that adapt core base for protocol semantics (framing, headers).
- Components
- e.g., socks5, rdc: plug into core engine and protocol modules to add functions (authentication, relaying).
- Utilities
- Encryption (AES, DES, Base64), compression (zlib), event dispatcher, reflection, UUID, INI parser, thread pool.
- Examples & Tests connect everything and demonstrate typical data flow: Client → Server → Session → Protocol handler → User callback.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% External Dependencies
  subgraph "External Dependencies"
    AD1["3rd/"]:::external
    AD2["include/asio2/external/"]:::external
    AD3["Asio"]:::external
    AD4["OpenSSL"]:::external
    AD5["cereal"]:::external
    AD6["fmt"]:::external
    AD7["spdlog"]:::external
  end

  %% Core Engine
  subgraph "Core Engine"
    CE1["asio2::iopool"]:::core
    CE2["asio2::base::server"]:::core
    CE3["asio2::base::client"]:::core
    CE4["asio2::base::session"]:::core
    CE5["asio2::base::timer"]:::core
    CE6["asio2::base::condition_event"]:::core
    CE7["asio2::base::log"]:::core
    CE8["asio2::base::error"]:::core
  end

  %% Protocol Modules
  subgraph "Protocol Modules"
    PM1["asio2::tcp_client"]:::protocol
    PM2["asio2::tcp_server"]:::protocol
    PM3["asio2::tcp_session"]:::protocol
    PM4["asio2::tcps_client"]:::protocol
    PM5["asio2::tcps_server"]:::protocol
    PM6["asio2::tcps_session"]:::protocol
    PM7["asio2::udp_client"]:::protocol
    PM8["asio2::udp_server"]:::protocol
    PM9["asio2::udp_session"]:::protocol
    PM10["asio2::http_client"]:::protocol
    PM11["asio2::http_server"]:::protocol
    PM12["asio2::http_session"]:::protocol
    PM13["asio2::https_client"]:::protocol
    PM14["asio2::https_server"]:::protocol
    PM15["asio2::https_session"]:::protocol
    PM16["asio2::ws_client"]:::protocol
    PM17["asio2::ws_server"]:::protocol
    PM18["asio2::ws_session"]:::protocol
    PM19["asio2::wss_client"]:::protocol
    PM20["asio2::wss_server"]:::protocol
    PM21["asio2::wss_session"]:::protocol
    PM22["asio2::rpc_client"]:::protocol
    PM23["asio2::rpc_server"]:::protocol
    PM24["asio2::rpc_session"]:::protocol
    PM25["asio2::rpcs_client"]:::protocol
    PM26["asio2::rpcs_server"]:::protocol
    PM27["asio2::rpcs_session"]:::protocol
    PM28["asio2::mqtt_client"]:::protocol
    PM29["asio2::mqtt_server"]:::protocol
    PM30["asio2::mqtt_session"]:::protocol
    PM31["asio2::mqtts_client"]:::protocol
    PM32["asio2::mqtts_server"]:::protocol
    PM33["asio2::mqtts_session"]:::protocol
    PM34["asio2::icmp_ping"]:::protocol
    PM35["asio2::serial_port"]:::protocol
  end

  %% Components
  subgraph "Components"
    CP1["rdc_invoker"]:::component
    CP2["rdc_call_cp"]:::component
    CP3["socks5_core"]:::component
    CP4["socks5_client_cp"]:::component
    CP5["socks5_server_cp"]:::component
  end

  %% Utilities
  subgraph "Utilities"
    U1["aes"]:::component
    U2["des"]:::component
    U3["base64"]:::component
    U4["event_dispatcher"]:::component
    U5["thread_pool"]:::component
    U6["spin_lock"]:::component
    U7["ini"]:::component
    U8["uuid"]:::component
    U9["zlib"]:::component
    U10["md5"]:::component
    U11["sha1"]:::component
  end

  %% Examples & Tests
  subgraph "Examples & Tests"
    ET1["example/"]:::example
    ET2["test/unit/"]:::example
    ET3["test/bench/"]:::example
  end

  %% Dependencies
  AD1 --> CE1
  AD2 --> CE2
  AD3 --> CE1
  AD4 --> PM4
  AD5 --> CE3
  AD6 --> CE7
  AD7 --> CE7

  CE1 --> PM1
  CE1 --> PM7
  CE1 --> PM10
  CE1 --> PM16
  CE1 --> PM22
  CE1 --> PM28
  CE1 --> PM34
  CE1 --> PM35

  PM1 --> CP1
  PM1 --> CP3
  PM7 --> CP1
  PM22 --> CP1

  ET1 --> CE2
  ET1 --> PM11
  ET1 --> PM16
  ET2 --> CE4
  ET2 --> PM3
  ET3 --> PM21

  %% Click Events
  click AD1 "https://github.com/zhllxt/asio2/tree/main/3rd/"
  click AD2 "https://github.com/zhllxt/asio2/tree/main/include/asio2/external/"
  click CE1 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/iopool.hpp"
  click CE2 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/server.hpp"
  click CE3 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/client.hpp"
  click CE4 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/session.hpp"
  click CE5 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/timer.hpp"
  click CE6 "https://github.com/zhllxt/asio2/tree/main/include/asio2/base/condition_event_cp"
  click CE7 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/log.hpp"
  click CE8 "https://github.com/zhllxt/asio2/blob/main/include/asio2/base/error.hpp"
  click PM1 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcp_client.hpp"
  click PM2 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcp_server.hpp"
  click PM3 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcp_session.hpp"
  click PM4 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcps_client.hpp"
  click PM5 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcps_server.hpp"
  click PM6 "https://github.com/zhllxt/asio2/blob/main/include/asio2/tcp/tcps_session.hpp"
  click PM7 "https://github.com/zhllxt/asio2/blob/main/include/asio2/udp/udp_client.hpp"
  click PM8 "https://github.com/zhllxt/asio2/blob/main/include/asio2/udp/udp_server.hpp"
  click PM9 "https://github.com/zhllxt/asio2/blob/main/include/asio2/udp/udp_session.hpp"
  click PM10 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/http_client.hpp"
  click PM11 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/http_server.hpp"
  click PM12 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/http_session.hpp"
  click PM13 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/https_client.hpp"
  click PM14 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/https_server.hpp"
  click PM15 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/https_session.hpp"
  click PM16 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/ws_client.hpp"
  click PM17 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/ws_server.hpp"
  click PM18 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/ws_session.hpp"
  click PM19 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/wss_client.hpp"
  click PM20 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/wss_server.hpp"
  click PM21 "https://github.com/zhllxt/asio2/blob/main/include/asio2/http/wss_session.hpp"
  click PM22 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpc_client.hpp"
  click PM23 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpc_server.hpp"
  click PM24 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpc_session.hpp"
  click PM25 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpcs_client.hpp"
  click PM26 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpcs_server.hpp"
  click PM27 "https://github.com/zhllxt/asio2/blob/main/include/asio2/rpc/rpcs_session.hpp"
  click PM28 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtt_client.hpp"
  click PM29 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtt_server.hpp"
  click PM30 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtt_session.hpp"
  click PM31 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtts_client.hpp"
  click PM32 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtts_server.hpp"
  click PM33 "https://github.com/zhllxt/asio2/blob/main/include/asio2/mqtt/mqtts_session.hpp"
  click PM34 "https://github.com/zhllxt/asio2/blob/main/include/asio2/icmp/ping.hpp"
  click PM35 "https://github.com/zhllxt/asio2/blob/main/include/asio2/serial_port/serial_port.hpp"
  click CP1 "https://github.com/zhllxt/asio2/blob/main/include/asio2/component/rdc/rdc_invoker.hpp"
  click CP2 "https://github.com/zhllxt/asio2/blob/main/include/asio2/component/rdc/rdc_call_cp.hpp"
  click CP3 "https://github.com/zhllxt/asio2/blob/main/include/asio2/component/socks/socks5_core.hpp"
  click CP4 "https://github.com/zhllxt/asio2/blob/main/include/asio2/component/socks/socks5_client_cp.hpp"
  click CP5 "https://github.com/zhllxt/asio2/blob/main/include/asio2/component/socks/socks5_server_cp.hpp"
  click U1 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/aes.hpp"
  click U2 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/des.hpp"
  click U3 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/base64.hpp"
  click U4 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/event_dispatcher.hpp"
  click U5 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/thread_pool.hpp"
  click U6 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/spin_lock.hpp"
  click U7 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/ini.hpp"
  click U8 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/uuid.hpp"
  click U9 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/zlib.hpp"
  click U10 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/md5.hpp"
  click U11 "https://github.com/zhllxt/asio2/blob/main/include/asio2/util/sha1.hpp"
  click ET1 "https://github.com/zhllxt/asio2/tree/main/example/"
  click ET2 "https://github.com/zhllxt/asio2/tree/main/test/unit/"
  click ET3 "https://github.com/zhllxt/asio2/tree/main/test/bench/"

  %% Styles
  classDef external fill:#cccccc,stroke:#888888
  classDef core fill:#add8e6,stroke:#0077b6
  classDef protocol fill:#98fb98,stroke:#2e8b57
  classDef component fill:#ffa500,stroke:#cc5500
  classDef example fill:#ffff99,stroke:#cccc00
```
