# yellow-camper/libevhtp architecture

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

- Interactive diagram: https://gitdiagram.com/yellow-camper/libevhtp
- Repository: https://github.com/yellow-camper/libevhtp

## Overview

##### Project Type and Purpose
- Libevhtp is a native C library that builds on top of the Libevent event loop to provide a lightweight, high-performance HTTP(S) server API.
- Its primary role is not a standalone application but as a reusable networking component: it accepts connections, parses HTTP requests, dispatches user-provided callbacks (handlers), and writes responses.

##### File Structure Analysis
- Top-level:
- core source files (evhtp.c, parser.c, thread.c, sslutils.c, log.c, numtoa.c)
- public headers under include/evhtp
- internal headers in include/ and compat/ for portability
- CMakeLists.txt, cmake/ and build/ for build configuration and packaging
- examples/ demonstrating usage patterns (basic server, chunked, vhost, HTTPS, threaded server, etc.)
- dist/, .travis.yml, .gitignore, LICENSE, README.md for project maintenance
- The modular directory layout indicates a separation between:
- Core engine (connection management & event loop integration)
- HTTP parsing
- Threading support
- SSL support (optional)
- Logging and utility functions

##### README Insights
- Lists dependencies: Libevent2, OpenSSL (optional), pthreads, oniguruma (regex).
- Describes build steps, supported platforms, and points to performance benchmarks.

a. Main Components
- External Clients (HTTP or HTTPS requesters)
- TCP/IP layer (OS sockets)
- Libevent Event Loop
- Libevhtp Core Module (connection lifecycle, request/response objects)
- HTTP Parser Submodule
- Thread Pool Submodule (optional pthreads dispatch)
- SSL/TLS Submodule (wrapping socket I/O via OpenSSL)
- Regex/Router Submodule (using oniguruma for URI matching, vhost)
- User-Defined Callbacks / Application Logic
- Logging / Refcount / Utilities
b. Relationships & Data Flow
1. Client → TCP Socket accept()
2. Socket registered with Libevent → socket event triggers
3. Libevent calls into Libevhtp Core → Core reads raw bytes
4. Raw bytes → HTTP Parser → parsed evhtp_request object
5. Router / Regex → Lookup matched callback (vhost, regex route)
6. Dispatch to Thread Pool OR direct event-loop thread (configurable)
7. User Callback processes request → constructs evhtp_headers, body
8. evhtp constructs HTTP response → writes to socket buffer
9. Libevent monitors socket WRITE events → sends bytes back to client
10. Optional SSL/TLS wrapper: stepping in at read/write phases
c. Architectural Patterns & Principles
- Reactor Pattern (Libevent event loop dispatch)
- Modular design: core engine + optional submodules (SSL, threading, regex)
- Callback-based extensibility for request handling
- Reference counting for request/connection objects to manage lifecycle
d. Key Technologies & Libraries
- Libevent2 (event-driven I/O)
- CMake (build & packaging)
- OpenSSL (HTTPS support)
- pthreads (concurrency)
- Oniguruma (regex-based routing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["External Clients (HTTP/HTTPS)"]:::external

    %% OS Socket Layer
    Socket["TCP/IP Socket"]:::core

    %% Event Loop
    Libevent["Libevent Event Loop"]:::external

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        Core["evhtp_core\n(connection & request/response lifecycle)"]:::core
        Parser["HTTP Parser"]:::core
        Logging["Logging & Utilities"]:::core
    end

    %% Optional Modules
    subgraph "Optional Modules"
        direction TB
        Thread["Thread Pool Submodule"]:::optional
        SSL["SSL/TLS Submodule"]:::optional
        Router["Regex/Router Submodule"]:::optional
    end

    %% Application Logic
    UserCallback["User Callbacks\n(Application Logic)"]:::app

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        CMake["CMakeLists.txt"]:::external
        cmakeDir["cmake/"]:::external
        buildDir["build/"]:::external
        dist["dist/"]:::external
        travis[".travis.yml"]:::external
    end

    %% Documentation & Metadata
    subgraph "Documentation & Metadata"
        direction TB
        readme["README.md"]:::external
        license["LICENSE"]:::external
        doxy["Doxyfile"]:::external
        changelog["ChangeLog"]:::external
    end

    %% Examples
    Examples["Example Applications"]:::external

    %% Connections
    Client -->|"1. TCP accept()"| Socket
    Socket -->|"2. register with"| Libevent
    Libevent -->|"3. event callback"| Core
    Core -->|"4. parse bytes"| Parser
    Parser -->|"parsed evhtp_request"| Core
    Core -->|"5. route lookup"| Router
    Router -->|"6. dispatch"| Thread
    Router -->|"6. dispatch"| UserCallback
    Thread -->|"7. call"| UserCallback
    UserCallback -->|"8. build response"| Core
    Core -->|"9. write to buffer"| Socket
    Socket -->|"10. send bytes"| Client
    SSL -. "wrap read/write I/O" .-> Core
    Logging --- Core

    %% Click Events
    click Libevent "https://github.com/yellow-camper/libevhtp/blob/develop/evhtp.c"
    click Core "https://github.com/yellow-camper/libevhtp/blob/develop/evhtp.c"
    click Parser "https://github.com/yellow-camper/libevhtp/blob/develop/parser.c"
    click Thread "https://github.com/yellow-camper/libevhtp/blob/develop/thread.c"
    click SSL "https://github.com/yellow-camper/libevhtp/blob/develop/sslutils.c"
    click Logging "https://github.com/yellow-camper/libevhtp/blob/develop/log.c"
    click Examples "https://github.com/yellow-camper/libevhtp/tree/develop/examples/"
    click CMake "https://github.com/yellow-camper/libevhtp/blob/develop/CMakeLists.txt"
    click cmakeDir "https://github.com/yellow-camper/libevhtp/tree/develop/cmake/"
    click buildDir "https://github.com/yellow-camper/libevhtp/tree/develop/build/"
    click dist "https://github.com/yellow-camper/libevhtp/tree/develop/dist/"
    click travis "https://github.com/yellow-camper/libevhtp/blob/develop/.travis.yml"
    click readme "https://github.com/yellow-camper/libevhtp/blob/develop/README.md"
    click license "https://github.com/yellow-camper/libevhtp/tree/develop/LICENSE"
    click doxy "https://github.com/yellow-camper/libevhtp/tree/develop/Doxyfile"
    click changelog "https://github.com/yellow-camper/libevhtp/tree/develop/ChangeLog"
    click Router "https://github.com/yellow-camper/libevhtp/blob/develop/include/evhtp/parser.h"
    click Logging "https://github.com/yellow-camper/libevhtp/blob/develop/include/evhtp/log.h"
    click Parser "https://github.com/yellow-camper/libevhtp/blob/develop/include/evhtp/parser.h"
    click Thread "https://github.com/yellow-camper/libevhtp/blob/develop/include/evhtp/thread.h"
    click SSL "https://github.com/yellow-camper/libevhtp/blob/develop/include/evhtp/sslutils.h"
    click Radi "https://github.com/yellow-camper/libevhtp/blob/develop/compat/sys/queue.h.in"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1976D2,stroke-width:1px;
    classDef optional fill:#C8E6C9,stroke:#388E3C,stroke-dasharray: 5 5,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:1px;
    classDef app fill:#E1BEE7,stroke:#8E24AA,stroke-width:1px;
```
