# butianyoushu/libhv architecture

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

- Interactive diagram: https://gitdiagram.com/butianyoushu/libhv
- Repository: https://github.com/butianyoushu/libhv

## Overview

##### Project Type and Purpose
- libhv is an open-source, cross-platform C/C++ networking and event-loop library—similar to libevent/libuv but with richer built-in protocols (HTTP, WebSocket, MQTT, RPC) and simplified APIs. It provides non-blocking IO, timers, thread-safety, SSL/TLS, RUDP (KCP), and utilities (logging, JSON, INI, file IO, etc.) for building high-performance servers and clients.

##### File-Structure Analysis
- Top-level build and config: BUILD.bazel, CMakeLists.txt, Makefile, scripts/, .github/, WORKSPACE.bazel
- Core modules:
- base/            — core abstractions (threads, mutex, atomic, sockets, logging, error, time)
- event/           — EventLoop and OS adapters (epoll, kqueue, IOCP, wepoll, NIO) plus custom/timer/signal events, KCP support
- http/            — HTTP/1.x & HTTP/2 parser, HTTP client/server, WebSocketChannel, middleware, router
- ssl/             — Pluggable SSL/TLS back-ends (OpenSSL, GNUTLS, MBEDTLS, WinTLS, NoSSL)
- protocol/        — Additional protocol parsers/servers (DNS, FTP, ICMP, SMTP)
- mqtt/            — MQTT client implementation
- util/ & cpputil/ — Misc utilities: base64, MD5/SHA1, file path, thread-pool, URL, INI parser, LRU cache, object pool, RAII wrappers
- C++ wrapper: evpp/ provides higher-level C++ classes around hv core.
- Examples, echo-servers, unittest: illustrate usage and benchmark performance.

##### Key Insights from README
- Cross-platform support (Linux, Windows, macOS, Android, iOS, BSD, Solaris)
- Feature list emphasizes EventLoop, TCP/UDP clients & servers, HTTP/2 & gRPC, WebSocket, MQTT, multi-thread safety, SSL, unpacking modes, RUDP.
- Getting-started includes sample httpd, curl, wrk tools—demonstrates layering of application on libhv.

- CORE:
- EventLoop
- OS-specific Pollers (epoll, kqueue, IOCP, WePoll, select/poll)
- Timer, Idle, Custom Event, Signal modules
- TRANSPORT:
- SocketChannel abstraction (wraps TCP/UDP sockets)
- ThreadPool for multi-threaded dispatch
- PROTOCOL LAYERS:
- TCP/UDP Server & Client APIs
- HTTP Module (Parser, Server, Client, Router, Middleware)
- WebSocket Module (over HTTP handshake + frame parser)
- MQTT Module
- RPC & other protocol handlers (DNS, FTP, ICMP, SMTP)
- RUDP/KCP
- SECURITY:
- SSL/TLS Abstraction (pluggable back-ends)
- UTILITIES:
- Logging, Config parser, JSON (header-only), Buffer, LRUCache, Path/File IO, ObjectPool, RAII
- APPLICATION:
- Example executables (httpd, curl, wrk, echo servers)
- BUILD & CI:
- Bazel, CMake, Makefiles, scripts, CI workflows

1. External Network → OS Kernel Socket → OS Poller
2. OS Poller → EventLoop → SocketChannel
3. SocketChannel → Protocol Parser (e.g., HTTPParser, WebSocketParser)
4. Protocol Handler → User Callback (application logic)
5. User Callback → Response Generator → EventLoop → OS Socket → External Network
6. Timer Signals and Custom Events flow into EventLoop similarly
7. For SSL: SocketChannel wraps SSL BIO → encrypted data flows through SSL stack → EventLoop

c. Architectural Patterns & Design Principles
- Reactor pattern (EventLoop + non-blocking IO)
- Layered protocol stack (transport → protocol → application)
- Pluggable modules (SSL back-ends, unpacking modes, protocol handlers)
- Thread-pool integration for concurrency
- Cross-platform abstraction: OS-conditional adapters hidden behind consistent APIs

d. Key Technologies & Frameworks
- C/C++11, header-only JSON, zlib (optional), OpenSSL/GNUTLS/MBEDTLS
- Build: Bazel, CMake, Make, vcpkg, xmake
- OS APIs: epoll (Linux), kqueue (BSD/macOS), IOCP (Windows), WePoll (Windows), select/poll

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    Network["External Network"]:::external
    Kernel["OS Kernel Socket"]:::external

    %% Core Layer
    subgraph "Core Components"
        direction TB
        Base["Base Module"]:::core
        EventLoop["EventLoop Core"]:::core
        Pollers["OS Pollers"]:::core
        CustomEvents["Timer/Signal/Custom Events"]:::core
        RUDP["RUDP/KCP Support"]:::core
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        SocketChannel["SocketChannel Abstraction"]:::transport
        ThreadPool["ThreadPool"]:::transport
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        TCPUDP["TCP/UDP Server & Client"]:::protocol
        HTTP["HTTP Module"]:::protocol
        WebSocket["WebSocket Module"]:::protocol
        MQTT["MQTT Module"]:::protocol
        OtherProto["DNS/FTP/ICMP/SMTP"]:::protocol
    end

    %% Security Layer
    subgraph "Security Layer"
        direction TB
        SSL["SSL/TLS Abstraction"]:::security
    end

    %% Utilities & Build
    subgraph "Utilities & Build"
        direction TB
        Utils["Utilities (util/ & cpputil/)"]:::utils
        BuildCI["Build & CI Config"]:::build
    end

    %% Application Layer
    subgraph "Examples & Tests"
        direction TB
        Examples["Examples & Applications"]:::app
        Echo["Echo Servers & Benchmarks"]:::app
        Tests["Unit Tests & CI"]:::app
    end

    %% Flows
    Network -->|"socket data"| Kernel
    Kernel -->|"fd events"| Pollers
    Pollers -->|"events"| EventLoop
    EventLoop -->|"dispatch"| SocketChannel
    SocketChannel -->|"read/write"| TCPUDP
    TCPUDP -->|"handshake/parser"| HTTP
    HTTP -->|"upgrade/frame"| WebSocket
    SocketChannel -->|"publish/subscribe"| MQTT
    SocketChannel -->|"protocol data"| OtherProto
    SocketChannel -->|"+ SSL BIO"| SSL
    EventLoop -->|"timer/signal"| CustomEvents
    EventLoop -->|"RUDP packets"| RUDP
    ThreadPool -->|"concurrency"| TCPUDP
    EventLoop -->|"user callbacks"| Examples
    Examples -->|"invoke APIs"| HTTP
    Examples -->|"invoke APIs"| MQTT
    Examples -->|"invoke APIs"| OtherProto
    BuildCI --> Examples
    BuildCI --> Utils
    Utils --> EventLoop
    Utils --> HTTP
    Utils --> SSL
    Utils --> MQTT
    Utils --> OtherProto
    Tests -.-> Examples

    %% Click Events
    click Base "https://github.com/butianyoushu/libhv/tree/master/base/"
    click EventLoop "https://github.com/butianyoushu/libhv/blob/master/event/hloop.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/epoll.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/kqueue.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/iocp.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/overlapio.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/wepoll/wepoll.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/select.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/poll.c"
    click Pollers "https://github.com/butianyoushu/libhv/blob/master/event/nio.c"
    click CustomEvents "https://github.com/butianyoushu/libhv/blob/master/event/hevent.c"
    click CustomEvents "https://github.com/butianyoushu/libhv/blob/master/event/unpack.c"
    click RUDP "https://github.com/butianyoushu/libhv/blob/master/event/rudp.c"
    click RUDP "https://github.com/butianyoushu/libhv/blob/master/event/kcp/hkcp.c"
    click SocketChannel "https://github.com/butianyoushu/libhv/blob/master/base/hsocket.c"
    click ThreadPool "https://github.com/butianyoushu/libhv/blob/master/cpputil/hthreadpool.h"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/Http1Parser.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/Http2Parser.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/HttpMessage.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/client/HttpClient.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/client/AsyncHttpClient.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/server/HttpServer.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/server/HttpHandler.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/server/HttpMiddleware.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/server/HttpResponseWriter.cpp"
    click HTTP "https://github.com/butianyoushu/libhv/blob/master/http/server/HttpContext.h"
    click WebSocket "https://github.com/butianyoushu/libhv/blob/master/http/WebSocketChannel.cpp"
    click WebSocket "https://github.com/butianyoushu/libhv/blob/master/http/WebSocketParser.cpp"
    click MQTT "https://github.com/butianyoushu/libhv/blob/master/mqtt/mqtt_client.c"
    click MQTT "https://github.com/butianyoushu/libhv/blob/master/mqtt/mqtt_protocol.c"
    click OtherProto "https://github.com/butianyoushu/libhv/blob/master/protocol/dns.c"
    click OtherProto "https://github.com/butianyoushu/libhv/blob/master/protocol/ftp.c"
    click OtherProto "https://github.com/butianyoushu/libhv/blob/master/protocol/icmp.c"
    click OtherProto "https://github.com/butianyoushu/libhv/blob/master/protocol/smtp.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/hssl.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/openssl.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/gnutls.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/mbedtls.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/wintls.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/nossl.c"
    click SSL "https://github.com/butianyoushu/libhv/blob/master/ssl/appletls.c"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/util/base64.c"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/util/md5.c"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/util/sha1.c"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/cpputil/LRUCache.h"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/cpputil/json.hpp"
    click Utils "https://github.com/butianyoushu/libhv/blob/master/cpputil/hpath.cpp"
    click Examples "https://github.com/butianyoushu/libhv/tree/master/examples/"
    click Echo "https://github.com/butianyoushu/libhv/tree/master/echo-servers/"
    click Tests "https://github.com/butianyoushu/libhv/tree/master/unittest/"
    click BuildCI "https://github.com/butianyoushu/libhv/blob/master/BUILD.bazel"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef transport fill:#D6F5D6,stroke:#28a745,color:#28a745;
    classDef protocol fill:#FFE8C0,stroke:#e69500,color:#e69500;
    classDef security fill:#FFCCCC,stroke:#d73a49,color:#d73a49;
    classDef utils fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef build fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef app fill:#E8DAEF,stroke:#6f42c1,color:#6f42c1;
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 2 2;
```
