Update README.md

fantasy-peak · fantasy-peak · commit c2e6e9aeb7fd · 2026-04-10T16:41:08.000+08:00
diff --git a/README.md b/README.md
@@ -1,89 +1,58 @@
-# simple_http
+# simple_http 🚀
+
+> **Lightweight, Modern, High-Performance C++20 HTTP/1.1 & HTTP/2 Framework.**
 
 [![gcc](https://github.com/fantasy-peak/simple_http/actions/workflows/gcc.yaml/badge.svg)](https://github.com/fantasy-peak/simple_http/actions/workflows/gcc.yaml)
 [![clang](https://github.com/fantasy-peak/simple_http/actions/workflows/clang.yaml/badge.svg)](https://github.com/fantasy-peak/simple_http/actions/workflows/clang.yaml)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-`simple_http` is a lightweight, high-performance, asynchronous HTTP/1.1 & HTTP/2 server and client library for C++20, built upon Boost.Asio and nghttp2. It is designed as header-only for easy integration and use.
-
-## ✨ Features
+![C++ Standard](https://img.shields.io/badge/C%2B%2B-20%2F23%2F26-blue.svg)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-- **Header-only**: Easy to integrate into any project by just including headers.
-- **Modern C++**: Leverages C++20/23/26 and coroutines for clean, asynchronous logic.
-- **Dual Protocol Support**: Supports both HTTP/1.1 and HTTP/2 with automatic negotiation.
-- **Server & Client**: Provides a consistent API for both server and client functionalities.
-- **Secure Communication**: Supports HTTPS and TLS mutual authentication (mTLS).
-- **Highly Configurable**: Easily configure server worker threads, concurrent stream limits, window sizes, and more.
-- **Middleware Support**: Offers a `setBefore` interface for middleware-style request pre-processing.
-- **IPv4 & IPv6**: Full dual-stack support.
-- **UNIX Domain Sockets**: High-performance local IPC with zero network overhead.
+`simple_http` is a lightweight, asynchronous HTTP/1.1 & HTTP/2 framework for C++20/23/26. Built upon **Boost.Beast** and **nghttp2**, it leverages modern C++ coroutines to provide a clean, high-performance API for both servers and clients.
 
-## 🚀 Requirements
+---
 
-- **C++20/23/26** compatible compiler (e.g., GCC 13+, Clang 20+).
-- **xmake**: Used for building examples and dependency management.
-- **Boost** (`beast`)
-- **nghttp2**
-- **OpenSSL**
+## 📖 Table of Contents
+- [✨ Features](#-features)
+- [🚀 Quick Start](#-quick-start)
+- [📦 Requirements](#-requirements)
+- [🧪 C++20 Modules Support (Experimental)](#-c20-modules-support-experimental)
+- [🛠 Configuration Macros](#-configuration-macros)
+- [📊 Performance](#-performance)
+- [🧪 Testing Guide](#-testing-guide)
+- [🤝 Contributing](#-contributing)
 
-> **Note**: When building with `xmake`, it automatically downloads and links all necessary dependencies, so you don't need to install them manually.
+---
 
-## 📦 C++20 Modules Support (Experimental)
+## ✨ Features
 
-`simple_http` provides experimental support for C++20 Modules via `include/simple_http.cppm`. This allows for faster compilation and better code isolation compared to traditional header inclusions.
+- **📦 Header-only**: Simple to integrate; just include and go.
+- **🛡️ Modern C++**: Built with C++20/23/26 coroutines for intuitive async logic.
+- **🔄 Dual Protocol**: Seamless HTTP/1.1 & HTTP/2 support with ALPN negotiation.
+- **🔄 Server & Client**: Symmetrical API design for both roles.
+- **🔒 Secure**: Robust HTTPS and mTLS (Mutual TLS) support.
+- **🔌 Advanced Transport**: Supports **IPv4/IPv6** and **UNIX Domain Sockets** for high-speed local IPC.
+- **🧩 Middleware**: Flexible `setBefore` interceptors for pre-processing.
+- **🌊 Full Streaming**: Bi-directional streaming for client and server.
+- **🌐 Proxy**: Built-in client-side HTTP proxy support.
 
-> **Note**: Currently, C++20 Modules support is verified on **Clang 20+**. Support for GCC and MSVC is planned.
+---
 
-### Usage in C++
-To use the module, simply replace your `#include` with an `import` statement:
+## 🚀 Quick Start
 
+### Simple Server Snippet
 ```cpp
 import simple_http;
 
-simple_http::HttpServer hs(cfg);
-```
-
-### Integration with xmake
-The following example shows how to integrate `simple_http` as a C++20 module in your `xmake.lua` project:
-
-```lua
-add_requires("simple_http")
-
-set_policy("build.c++.modules", true)
-set_policy("build.c++.modules.std", true)
-
-target("server")
-    set_kind("binary")
-
-    add_cxflags("-fuse-ld=mold")
-    add_cxxflags("-stdlib=libc++")
-
-    on_load(function (target)
-        local pkg = target:pkg("simple_http")
-        if pkg then
-            local installdir = pkg:installdir()
-            local module_file = path.join(installdir, "include", "simple_http.cppm")
-            target:add("files", module_file)
-            print("Successfully linked C++20 module from: " .. module_file)
-        end
-    end)
-
-    add_files("src/main.cpp")
-    add_packages("simple_http")
+hs.setHttpHandler("/hello", [](auto req, auto writer) -> asio::awaitable<void> {
+    writer->writeHttpResponse(simple_http::makeHttpResponse(http::status::ok, "Hello World!"));
+    co_return;
+});
 ```
 
+<details>
+<summary><b>Click to view Full Server Example</b></summary>
 
-## 🛠 Configuration Macros
-
-The following macros can be defined to enable or customize specific features:
-
-- `SIMPLE_HTTP_EXPERIMENT_WEBSOCKET`: Enables experimental WebSocket support.
-- `SIMPLE_HTTP_EXPERIMENT_HTTP2CLIENT`: Enables experimental HTTP/2 client support.
-- `SIMPLE_HTTP_USE_BOOST_REGEX`: Uses `boost::regex` instead of `std::regex` for header parsing and routing. This can provide better performance and compatibility in certain environments.
-- `SIMPLE_HTTP_BIND_UNIX_SOCKET`: Enables support for binding the server to UNIX Domain Sockets (UDS) for high-performance local IPC.
-
-## Server Example
-```
+```cpp
 import std;
 import simple_http;
 
@@ -101,7 +70,6 @@ asio::awaitable<void> start() {
         .ssl_ca = "./test/tls_certificates/ca_cert.pem",
         .socket_setup_cb =
             [](asio::ip::tcp::socket& socket) {
-                // Set socket properties
                 socket.set_option(asio::socket_base::keep_alive(true));
             },
         .enable_ipv6 = true,
@@ -131,6 +99,13 @@ asio::awaitable<void> start() {
             writer->writeStreamEnd();
             co_return;
         });
+    hs.setHttpHandler("/world",
+        [](auto req, auto writer) -> asio::awaitable<void> {
+            auto response = simple_http::makeHttpResponse(http::status::ok);
+            response->body() = "ok!";
+            writer->writeHttpResponse(response);
+            co_return;
+        });
     co_await hs.start();
 }
 
@@ -143,8 +118,12 @@ int main() {
     return 0;
 }
 ```
-## Client Example
-```
+</details>
+
+<details>
+<summary><b>Click to view Full Client Example</b></summary>
+
+```cpp
 import std;
 import simple_http;
 
@@ -161,7 +140,6 @@ asio::awaitable<void> client(simple_http::IoCtxPool& pool) {
         .ssl_context = nullptr,
         .tlsext_host_name = "SimpleHttpServer",
     };
-    // only support h2 and h2c not support http1.1
     auto client = std::make_shared<simple_http::Http2Client>(cfg, pool.getIoContextPtr());
     auto [ret, err] = co_await client->asyncStart(std::chrono::seconds(5), asio::use_awaitable);
     if (!ret) {
@@ -211,8 +189,7 @@ int main() {
     pool.start();
     asio::co_spawn(pool.getIoContext(), client(pool), [](const std::exception_ptr& ep) {
         try {
-            if (ep)
-                std::rethrow_exception(ep);
+            if (ep) std::rethrow_exception(ep);
         } catch (const std::exception& e) {
             SIMPLE_HTTP_ERROR_LOG("{}", e.what());
         } catch (...) {
@@ -224,37 +201,100 @@ int main() {
     return 0;
 }
 ```
+</details>
 
-## 📊 Performance
+---
 
-The following benchmark was performed using `h2load`.
+## 📦 Requirements
+- **C++20/23/26** (GCC 13+, Clang 20+)
+- **xmake** Used for building examples and dependency management.
+- **Dependencies**: Boost.Beast, nghttp2, OpenSSL
 
-**Machine Configuration:**
-- **OS**: Ubuntu 25.10
-- **CPU**: 13th Gen Intel(R) Core(TM) i7-13620H (16 vCPUs)
-- **Memory**: 41Gi RAM
+## 🧪 C++20 Modules Support (Experimental)
+`simple_http` provides native C++20 Modules support via `include/simple_http.cppm`.
 
-**Test Configuration:**
-- **Request Size**: 1KB (via `b.txt`)
-- **Response Size**: 10KB
-- **Command**: `h2load -t 4 -n 1000000 -c 1000 -m 40 -H 'Content-Type: application/json' --data=b.txt http://localhost:7788/hello`
+> **Status**: Verified on Clang 20+. Support for GCC and MSVC is on the roadmap.
 
-**Results:**
+#### xmake Integration
+
+<details>
+<summary><b>Click to view detailed xmake.lua configuration</b></summary>
+
+The following example shows how to integrate `simple_http` as a C++20 module in your `xmake.lua` project:
+
+```lua
+add_requires("simple_http")
+
+set_policy("build.c++.modules", true)
+set_policy("build.c++.modules.std", true)
+
+target("server")
+    set_kind("binary")
+
+    add_cxflags("-fuse-ld=mold")
+    add_cxxflags("-stdlib=libc++")
+
+    on_load(function (target)
+        local pkg = target:pkg("simple_http")
+        if pkg then
+            local installdir = pkg:installdir()
+            local module_file = path.join(installdir, "include", "simple_http.cppm")
+            target:add("files", module_file)
+            print("Successfully linked C++20 module from: " .. module_file)
+        end
+    end)
+
+    add_files("src/main.cpp")
+    add_packages("simple_http")
+```
+</details>
+
+---
+
+## 🛠 Configuration Macros
+
+| Macro | Description |
+| :--- | :--- |
+| `SIMPLE_HTTP_EXPERIMENT_WEBSOCKET` | Enables experimental WebSocket support. |
+| `SIMPLE_HTTP_EXPERIMENT_HTTP2CLIENT` | Enables experimental HTTP/2 client support. |
+| `SIMPLE_HTTP_USE_BOOST_REGEX` | Uses `boost::regex` instead of `std::regex` for better performance. |
+| `SIMPLE_HTTP_BIND_UNIX_SOCKET` | Enables support for binding to UNIX Domain Sockets (UDS). |
+
+---
+
+## 📊 Performance
+
+Benchmark conducted using `h2load` on **Ubuntu 25.10 | i7-13620H (16 vCPUs) | 41Gi RAM**.
+
+| Metric | Result |
+| :--- | :--- |
+| **Throughput** | **~99,558 req/s** |
+| **Transfer Rate** | **~976.28 MB/s** |
+| **Success Rate** | 100% (1,000,000 requests) |
+
+**Detailed Results:**
 
 ```text
 finished in 10.04s, 99558.82 req/s, 976.28MB/s
 requests: 1000000 total, 1000000 started, 1000000 done, 1000000 succeeded, 0 failed, 0 errored, 0 timeout
 status codes: 1000000 2xx, 0 3xx, 0 4xx, 0 5xx
 traffic: 9.58GB (10282450426) total, 2.89MB (3026000) headers (space savings 95.12%), 9.54GB (10243000000) data
+
                      min         max         mean         sd        +/- sd
 time for request:     5.99ms       1.43s    342.76ms    137.20ms    77.08%
 time for connect:     5.65ms    151.01ms     62.93ms     37.19ms    67.60%
 time to 1st byte:    79.20ms       1.02s    537.90ms    308.48ms    51.80%
 req/s           :     100.72      124.03      105.92        4.56    71.10%
 ```
 
-## Test Cmd
-```
+> **Benchmark Command**:
+> `h2load -t 4 -n 1000000 -c 1000 -m 40 -H 'Content-Type: application/json' --data=b.txt http://localhost:7788/hello`
+
+---
+
+## 🧪 Testing Guide
+
+```bash
 curl -N -v --http2-prior-knowledge http://localhost:7788/hello\?key1\=value1\&key2\=value2
 curl -N -v --http2-prior-knowledge http://localhost:7788/hello -d "abcd"
 curl -N -v --http2 http://localhost:7788/hello -d "abcd"
@@ -267,10 +307,10 @@ need define SIMPLE_HTTP_BIND_UNIX_SOCKET macro
 curl --unix-socket /tmp/simple_http.sock https://SimpleHttpServer:7788/hello?123456 --cacert ca_cert.pem --cert client_cert.pem --key client_key.pem -X POST -d "123"
 ```
 
-## 🤝 Contributing
+---
 
-Contributions of any kind are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to contribute to the project.
+## 🤝 Contributing
+Contributions are welcome! Please check [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## 📄 License
-
 `simple_http` is licensed under the [MIT License](LICENSE).
