添加c++接口文档

docs/API.md

@@ -541,7 +541,6 @@
 - class HttpRequest
 - class HttpResponse
 - class HttpParser
-- class HttpService
 
 ### httpdef.h
 - http_content_type_enum
@@ -603,6 +602,7 @@
 ### HttpServer.h
 - http_server_run
 - http_server_stop
+- class HttpService
 - class HttpServer
 
 ### WebSocketClient.h
@@ -611,6 +611,7 @@
 ### WebSocketServer.h
 - websocket_server_run
 - websocket_server_stop
+- class WebSocketService
 - class WebSocketServer
 
 ## mqtt

docs/PLAN.md

@@ -3,6 +3,7 @@
 - base: cross platfrom infrastructure
 - event: select/poll/epoll/kqueue/port
 - ssl: openssl/guntls/mbedtls
+- rudp: KCP
 - evpp: c++ EventLoop interface similar to muduo and evpp
 - http client/server: include https http1/x http2
 - websocket client/server
@@ -12,7 +13,9 @@
 
 - IOCP: fix bug, add SSL/TLS support, replace with wepoll?
 - wintls: SChannel is so hard :) need help
-- Path router: add filter chain, optimized matching via trie?
+- Path router: optimized matching via trie?
+- FileCache use LRUCache
+- HTTP TrustProxies
 
 ## Plan
 
@@ -21,7 +24,7 @@
 - lua binding
 - js binding
 - hrpc = libhv + protobuf
-- rudp: FEC, ARQ, KCP, UDT, QUIC
+- rudp: FEC, ARQ, UDT, QUIC
 - kcptun
 - have a taste of io_uring
 - coroutine

docs/cn/Channel.md

@@ -0,0 +1,153 @@
+通道类
+
+```c++
+
+class Channel {
+
+    // 返回底层的io结构体指针
+    hio_t*      io() { return io_; }
+
+    // 返回socket文件描述符
+    int         fd() { return fd_; }
+
+    // 返回一个唯一标示id
+    uint32_t    id() { return id_; }
+
+    // 返回错误码
+    int error() { return hio_error(io_); }
+
+    // 获取/设置/新建/删除 上下文
+    void* context();
+    void setContext(void* ctx);
+    template<class T> T* newContext();
+    template<class T> T* getContext();
+    template<class T> void deleteContext();
+
+    // 获取/设置/新建/删除 上下文智能指针
+    std::shared_ptr<void> contextPtr();
+    void setContextPtr(const std::shared_ptr<void>& ctx);
+    void setContextPtr(std::shared_ptr<void>&& ctx);
+    template<class T> std::shared_ptr<T> newContextPtr();
+    template<class T> std::shared_ptr<T> getContextPtr();
+    void deleteContextPtr();
+
+    // 是否打开状态
+    bool isOpened();
+
+    // 是否关闭状态
+    bool isClosed();
+
+    // 开始读
+    int startRead();
+
+    // 停止读
+    int stopRead();
+
+    // 读一次
+    int readOnce();
+    // 读一个字符串
+    int readString();
+    // 读一行
+    int readLine();
+    // 读取N个字节
+    int readBytes(int len);
+
+    // 写
+    int write(const void* data, int size);
+    int write(Buffer* buf);
+    int write(const std::string& str);
+
+    // 设置最大读缓存
+    void setMaxReadBufsize(uint32_t size);
+    // 设置最大写缓存
+    void setMaxWriteBufsize(uint32_t size);
+    // 获取当前写缓存大小
+    size_t writeBufsize();
+    // 是否写完成
+    bool isWriteComplete();
+
+    // 关闭
+    int close(bool async = false);
+
+    // 读回调
+    std::function<void(Buffer*)> onread;
+    // 写回调
+    std::function<void(Buffer*)> onwrite;
+    // 关闭回调
+    std::function<void()>        onclose;
+};
+
+// SocketChannel 继承自 Channel
+class SocketChannel : public Channel {
+    // 连接状态回调
+    std::function<void()>   onconnect;
+    // 心跳回调
+    std::function<void()>   heartbeat;
+
+    // 启用SSL/TLS加密通信
+    int enableSSL();
+    // 是否是SSL/TLS加密通信
+    bool isSSL();
+    // 设置SSL
+    int setSSL(hssl_t ssl);
+    // 设置SSL_CTX
+    int setSslCtx(hssl_ctx_t ssl_ctx);
+    // 新建SSL_CTX
+    int newSslCtx(hssl_ctx_opt_t* opt);
+    // 设置主机名
+    int setHostname(const std::string& hostname);
+
+    // 设置连接超时
+    void setConnectTimeout(int timeout_ms);
+
+    // 设置关闭超时 (说明：非阻塞写队列非空时，需要等待写完成再关闭)
+    void setCloseTimeout(int timeout_ms);
+
+    // 设置读超时 (一段时间没有数据到来便自动关闭连接)
+    void setReadTimeout(int timeout_ms);
+
+    // 设置写超时 (一段时间没有数据发送便自动关闭连接)
+    void setWriteTimeout(int timeout_ms);
+
+    // 设置keepalive超时 (一段时间没有数据收发便自动关闭连接)
+    void setKeepaliveTimeout(int timeout_ms);
+
+    // 设置心跳 (定时发送心跳包)
+    void setHeartbeat(int interval_ms, std::function<void()> fn);
+
+    // 设置拆包规则
+    void setUnpack(unpack_setting_t* setting);
+
+    // 开始连接
+    int startConnect(int port, const char* host = "127.0.0.1");
+    int startConnect(struct sockaddr* peeraddr);
+    int startConnect();
+
+    // 是否已连接
+    bool isConnected();
+
+    // 返回本地地址
+    std::string localaddr();
+
+    // 返回对段地址
+    std::string peeraddr();
+};
+
+// WebSocketChannel 继承自 SocketChannel
+class WebSocketChannel : public SocketChannel {
+
+    // 发送文本帧
+    int send(const std::string& msg, enum ws_opcode opcode = WS_OPCODE_TEXT, bool fin = true);
+
+    // 发送二进制帧
+    int send(const char* buf, int len, enum ws_opcode opcode = WS_OPCODE_BINARY, bool fin = true);
+
+    // 分片发送
+    int send(const char* buf, int len, int fragment, enum ws_opcode opcode = WS_OPCODE_BINARY);
+
+    // 关闭
+    int close();
+
+};
+
+```

docs/cn/EventLoop.md

@@ -0,0 +1,123 @@
+事件循环类
+
+```c++
+
+class EventLoop {
+
+    // 返回底层的loop结构体指针
+    hloop_t* loop();
+
+    // 运行
+    void run();
+    // 停止
+    void stop();
+    // 暂停
+    void pause();
+    // 继续
+    void resume();
+
+    // 设置定时器
+    TimerID setTimer(int timeout_ms, TimerCallback cb, uint32_t repeat = INFINITE, TimerID timerID = INVALID_TIMER_ID);
+
+    // 设置一次性定时器
+    TimerID setTimeout(int timeout_ms, TimerCallback cb);
+
+    // 设置永久性定时器
+    TimerID setInterval(int interval_ms, TimerCallback cb);
+
+    // 杀掉定时器
+    void killTimer(TimerID timerID);
+
+    // 重置定时器
+    void resetTimer(TimerID timerID, int timeout_ms = 0);
+
+    // 返回事件循环所在的线程ID
+    long tid();
+
+    // 是否在事件循环所在线程
+    bool isInLoopThread();
+
+    // 断言在事件循环所在线程
+    void assertInLoopThread();
+
+    // 运行在事件循环里
+    void runInLoop(Functor fn);
+
+    // 队列在事件循环里
+    void queueInLoop(Functor fn);
+
+    // 投递一个事件到事件循环
+    void postEvent(EventCallback cb);
+
+};
+
+class EventLoopThread {
+
+    // 返回事件循环指针
+    const EventLoopPtr& loop();
+
+    // 返回底层的loop结构体指针
+    hloop_t* hloop();
+
+    // 是否运行中
+    bool isRunning();
+
+    /* 开始运行
+     * wait_thread_started: 是否阻塞等待线程开始
+     * pre:  线程开始后执行的函数
+     * post: 线程结束前执行的函数
+     */
+    void start(bool wait_thread_started = true,
+               Functor pre = Functor(),
+               Functor post = Functor());
+
+    // 停止运行
+    void stop(bool wait_thread_stopped = false);
+
+    // 等待线程退出
+    void join();
+
+};
+
+class EventLoopThreadPool {
+
+    // 获取线程数量
+    int threadNum();
+
+    // 设置线程数量
+    void setThreadNum(int num);
+
+    // 返回下一个事件循环对象
+    // 支持轮询、随机、最少连接数等负载均衡策略
+    EventLoopPtr nextLoop(load_balance_e lb = LB_RoundRobin);
+
+    // 返回索引的事件循环对象
+    EventLoopPtr loop(int idx = -1);
+
+    // 返回索引的底层loop结构体指针
+    hloop_t* hloop(int idx = -1);
+
+    /* 开始运行
+     * wait_threads_started: 是否阻塞等待所有线程开始
+     * pre:  线程开始后执行的函数
+     * post: 线程结束前执行的函数
+     */
+    void start(bool wait_threads_started = false,
+               std::function<void(const EventLoopPtr&)> pre = NULL,
+               std::function<void(const EventLoopPtr&)> post = NULL);
+
+    // 停止运行
+    void stop(bool wait_threads_stopped = false);
+
+    // 等待所有线程退出
+    void join();
+
+};
+
+```
+
+测试代码见:
+
+- [evpp/EventLoop_test.cpp](../../evpp/EventLoop_test.cpp)
+- [evpp/EventLoopThread_test.cpp](../../evpp/EventLoopThread_test.cpp)
+- [evpp/EventLoopThreadPool_test.cpp](../../evpp/EventLoopThreadPool_test.cpp)

docs/cn/HttpClient.md

@@ -1,3 +1,5 @@
+HTTP 客户端类
+
 ```c++
 
 class HttpClient {
@@ -75,3 +77,5 @@ namespace requests {
 }
 
 ```
+
+测试代码见 [examples/http_client_test.cpp](../../examples/http_client_test.cpp)

docs/cn/HttpServer.md

@@ -1,3 +1,5 @@
+HTTP 服务端类
+
 ```c++
 
 // HTTP服务类
@@ -40,10 +42,10 @@ class HttpService {
     // 添加静态资源映射
     void Static(const char* path, const char* dir);
 
-    // 允许跨越访问
+    // 允许跨域访问
     void AllowCORS();
 
-    // 开启转发代理
+    // 开启正向转发代理
     void EnableForwardProxy();
 
     // 添加反向代理映射
@@ -52,7 +54,7 @@ class HttpService {
     // 添加中间件
     void Use(Handler handlerFunc);
 
-    // 添加路由
+    // 添加路由处理器
     void Handle(const char* httpMethod, const char* relativePath, Handler handlerFunc);
 
     // 添加`HEAD`路由
@@ -99,10 +101,12 @@ class HttpService {
     int proxy_write_timeout;        // 代理写超时
 
     int keepalive_timeout;          // 长连接保活超时
-    int max_file_cache_size;        // 最多缓存小文件的数量
+    int max_file_cache_size;        // 文件缓存最大尺寸
     int file_cache_stat_interval;   // 文件缓存stat间隔，查询文件是否修改
     int file_cache_expired_time;    // 文件缓存过期时间，过期自动释放
 
+    int limit_rate;                 // 下载速度限制
+
 };
 
 /* 几种`handler`处理函数区别说明: */
@@ -120,3 +124,5 @@ typedef std::function<int(const HttpContextPtr& ctx)>
 typedef std::function<int(const HttpContextPtr& ctx, http_parser_state state, const char* data, size_t size)> http_state_handler;
 
 ```
+
+测试代码见 [examples/http_server_test.cpp](../../examples/http_server_test.cpp)

docs/cn/README.md

@@ -0,0 +1,16 @@
+## c接口
+
+TODO
+
+## c++接口
+
+- [class EventLoop: 事件循环类](EventLoop.md)
+- [class Channel: 通道类](Channel.md)
+- [class TcpServer: TCP服务端类](TcpServer.md)
+- [class TcpClient: TCP客户端类](TcpClient.md)
+- [class UdpServer: UDP服务端类](UdpServer.md)
+- [class UdpClient: UDP客户端类](UdpClient.md)
+- [class HttpServer: HTTP服务端类](HttpServer.md)
+- [class HttpClient: HTTP客户端类](HttpClient.md)
+- [class WebSocketServer: WebSocket服务端类](WebSocketServer.md)
+- [class WebSocketClient: WebSocket客户端类](WebSocketClient.md)

docs/cn/TcpClient.md

@@ -0,0 +1,63 @@
+TCP 客户端类
+
+```c++
+
+class TcpClient {
+
+    // 返回所在的事件循环
+    const EventLoopPtr& loop();
+
+    // 创建套接字
+    int createsocket(int remote_port, const char* remote_host = "127.0.0.1");
+    int createsocket(struct sockaddr* remote_addr);
+
+    // 绑定端口
+    int bind(int local_port, const char* local_host = "0.0.0.0");
+    int bind(struct sockaddr* local_addr);
+
+    // 关闭套接字
+    void closesocket();
+
+    // 开始运行
+    void start(bool wait_threads_started = true);
+
+    // 停止运行
+    void stop(bool wait_threads_stopped = true);
+
+    // 是否已连接
+    bool isConnected();
+
+    // 发送
+    int send(const void* data, int size);
+    int send(Buffer* buf);
+    int send(const std::string& str);
+
+    // 设置SSL/TLS加密通信
+    int withTLS(hssl_ctx_opt_t* opt = NULL);
+
+    // 设置连接超时
+    void setConnectTimeout(int ms);
+
+    // 设置重连
+    void setReconnect(reconn_setting_t* setting);
+
+    // 是否是重连
+    bool isReconnect();
+
+    // 设置拆包规则
+    void setUnpack(unpack_setting_t* setting);
+
+    // 连接状态回调
+    std::function<void(const TSocketChannelPtr&)>           onConnection;
+
+    // 消息回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onMessage;
+
+    // 写完成回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onWriteComplete;
+
+};
+
+```
+
+测试代码见 [evpp/TcpClient_test.cpp](../../evpp/TcpClient_test.cpp)

docs/cn/TcpServer.md

@@ -0,0 +1,60 @@
+TCP 服务端类
+
+```c++
+
+class TcpServer {
+
+    // 返回索引的事件循环
+    EventLoopPtr loop(int idx = -1);
+
+    // 创建套接字
+    int createsocket(int port, const char* host = "0.0.0.0");
+
+    // 关闭套接字
+    void closesocket();
+
+    // 设置最大连接数
+    void setMaxConnectionNum(uint32_t num);
+
+    // 设置负载均衡策略
+    void setLoadBalance(load_balance_e lb);
+
+    // 设置线程数
+    void setThreadNum(int num);
+
+    // 开始运行
+    void start(bool wait_threads_started = true);
+
+    // 停止运行
+    void stop(bool wait_threads_stopped = true);
+
+    // 设置SSL/TLS加密通信
+    int withTLS(hssl_ctx_opt_t* opt = NULL);
+
+    // 设置拆包规则
+    void setUnpack(unpack_setting_t* setting);
+
+    // 返回当前连接数
+    size_t connectionNum();
+
+    // 遍历连接
+    int foreachChannel(std::function<void(const TSocketChannelPtr& channel)> fn);
+
+    // 广播消息
+    int broadcast(const void* data, int size);
+    int broadcast(const std::string& str);
+
+    // 连接到来/断开回调
+    std::function<void(const TSocketChannelPtr&)>           onConnection;
+
+    // 消息回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onMessage;
+
+    // 写完成回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onWriteComplete;
+
+};
+
+```
+
+测试代码见 [evpp/TcpServer_test.cpp](../../evpp/TcpServer_test.cpp)

docs/cn/UdpClient.md

@@ -0,0 +1,42 @@
+UDP 客户端类
+
+```c++
+
+class UdpClient {
+
+    // 返回所在的事件循环
+    const EventLoopPtr& loop();
+
+    // 创建套接字
+    int createsocket(int remote_port, const char* remote_host = "127.0.0.1");
+
+    // 绑定端口
+    int bind(int local_port, const char* local_host = "0.0.0.0");
+
+    // 关闭套接字
+    void closesocket();
+
+    // 开始运行
+    void start(bool wait_threads_started = true);
+
+    // 停止运行
+    void stop(bool wait_threads_stopped = true);
+
+    // 发送
+    int sendto(const void* data, int size, struct sockaddr* peeraddr = NULL);
+    int sendto(Buffer* buf, struct sockaddr* peeraddr = NULL);
+    int sendto(const std::string& str, struct sockaddr* peeraddr = NULL);
+
+    // 设置KCP
+    void setKcp(kcp_setting_t* setting);
+
+    // 消息回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onMessage;
+
+    // 写完成回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onWriteComplete;
+};
+
+```
+
+测试代码见 [evpp/UdpClient_test.cpp](../../evpp/UdpClient_test.cpp)

docs/cn/UdpServer.md

@@ -0,0 +1,39 @@
+UDP 服务端类
+
+```c++
+
+class UdpServer {
+
+    // 返回所在的事件循环
+    const EventLoopPtr& loop();
+
+    // 创建套接字
+    int createsocket(int port, const char* host = "0.0.0.0");
+
+    // 关闭套接字
+    void closesocket();
+
+    // 开始运行
+    void start(bool wait_threads_started = true);
+
+    // 停止运行
+    void stop(bool wait_threads_stopped = true);
+
+    // 发送
+    int sendto(const void* data, int size, struct sockaddr* peeraddr = NULL);
+    int sendto(Buffer* buf, struct sockaddr* peeraddr = NULL);
+    int sendto(const std::string& str, struct sockaddr* peeraddr = NULL);
+
+    // 设置KCP
+    void setKcp(kcp_setting_t* setting);
+
+    // 消息回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onMessage;
+
+    // 写完成回调
+    std::function<void(const TSocketChannelPtr&, Buffer*)>  onWriteComplete;
+};
+
+```
+
+测试代码见 [evpp/UdpServer_test.cpp](../../evpp/UdpServer_test.cpp)

docs/cn/WebSocketClient.md

@@ -0,0 +1,37 @@
+WebSocket 客户端类
+
+```c++
+
+class WebSocketClient {
+
+    // 打开回调
+    std::function<void()> onopen;
+    // 关闭回调
+    std::function<void()> onclose;
+    // 消息回调
+    std::function<void(const std::string& msg)> onmessage;
+
+    // 打开
+    int open(const char* url, const http_headers& headers = DefaultHeaders);
+
+    // 关闭
+    int close();
+
+    // 发送
+    int send(const std::string& msg);
+    int send(const char* buf, int len, enum ws_opcode opcode = WS_OPCODE_BINARY);
+
+    // 设置心跳间隔
+    void setPingInterval(int ms);
+
+    // 设置WebSocket握手阶段的HTTP请求
+    void setHttpRequest(const HttpRequestPtr& req);
+
+    // 获取WebSocket握手阶段的HTTP响应
+    const HttpResponsePtr& getHttpResponse();
+
+};
+
+```
+
+测试代码见 [examples/websocket_client_test.cpp](../../examples/websocket_client_test.cpp)

docs/cn/WebSocketServer.md

@@ -0,0 +1,30 @@
+WebSocket 服务端类
+
+```c++
+
+// WebSocketServer 继承自 HttpServer
+class WebSocketServer : public HttpServer {
+
+    // 注册WebSocket业务类
+    void registerWebSocketService(WebSocketService* service);
+
+};
+
+// WebSocket业务类
+struct WebSocketService {
+    // 打开回调
+    std::function<void(const WebSocketChannelPtr&, const HttpRequestPtr&)>  onopen;
+
+    // 消息回调
+    std::function<void(const WebSocketChannelPtr&, const std::string&)>     onmessage;
+
+    // 关闭回调
+    std::function<void(const WebSocketChannelPtr&)>                         onclose;
+
+    // 心跳间隔
+    int ping_interval;
+};
+
+```
+
+测试代码见 [examples/websocket_server_test.cpp](../../examples/websocket_server_test.cpp)