Features - 508364/NetLeaf GitHub Wiki

功能特性|Features

核心功能

1. 跨平台支持

NetLeaf支持Windows和Linux平台,以及多种CPU架构(已验证):

平台 架构 状态
Windows x64 ✅
Windows x86 ✅
Windows ARM64 ✅
Linux amd64 ✅
Linux i386 ✅
Linux ARM ✅
Linux ARM64 ✅
Linux RISC-V 64 ✅
Linux PowerPC 64 LE ✅
Linux MIPS ✅
Linux s390x ✅

2. 协议支持

  • HTTP/1.1: 完整支持
  • HTTP/2: 多路复用、头部压缩
  • HTTP/3 (QUIC): 基于QUIC的下一代协议
  • WebSocket: 实时双向通信
  • TCP/UDP: 原始套接字支持

3. Web服务器功能

3.1 内联网页支持

// 创建Web服务器(自动启动)
nl_web_server_t* server = nl_web_create(8080);

// 添加HTML页面
nl_web_add_html(server, "/", "<h1>Hello World</h1>");

// 添加Vue页面
nl_web_add_vue(server, "/app", "<p>{{ message }}</p>");

// 服务器已自动启动,无需调用 nl_web_start()

3.2 变量硬编码功能

新增功能: 服务器端变量替换,用户即使使用F12无法看到原始变量名。

const char* vars[] = {"username", "user_id"};
const char* values[] = {"张三", "12345"};

nl_web_add_html_with_vars(server, "/profile",
    "<h1>欢迎, {{<var>username</var>}}</h1>\n"
    "<p>用户ID: {{<var>user_id</var>}}</p>",
    vars, values, 2);

输出到客户端:

<h1>欢迎, 张三</h1>
<p>用户ID: 12345</p>

变量格式: {{<var>变量名</var>}}

3.3 编码设置

// 设置响应编码(默认为UTF-8)
nl_web_set_encoding(server, "UTF-8");

3.4 文件热加载

修改外部HTML/Vue/JSON文件后,刷新页面立即生效,无需重启服务器。

nl_web_add_html_file(server, "/", "index.html");
nl_web_add_vue_file(server, "/app", "app.vue");
nl_web_add_json_file(server, "/data", "data.json");

平台: Windows/Linux/macOS

3.5 HTTP重定向

支持301永久重定向和302临时重定向,可在运行时切换类型。

// 添加重定向路由
nl_web_add_redirect(server, "/old", "/new");
nl_web_add_redirect(server, "/goto", "https://example.com");

// 运行时切换重定向类型
nl_web_set_redirect_type(server, NL_REDIRECT_PERMANENT);    // 301
nl_web_set_redirect_type(server, NL_REDIRECT_TEMPORARY);   // 302(默认)

// 获取当前重定向类型
nl_redirect_type_t type = nl_web_get_redirect_type(server);

重定向类型:

  • NL_REDIRECT_TEMPORARY (302): 临时重定向
  • NL_REDIRECT_PERMANENT (301): 永久重定向

平台: Windows/Linux/macOS

3.6 智能检测

nl_web_add_html/vue/json 自动识别URL、文件路径或静态内容:

  • URL → 自动创建重定向路由
  • 文件路径 → 自动创建热加载路由
  • 其他字符串 → 作为内联静态内容
nl_web_add_html(server, "/goto", "https://google.com");     // URL→重定向
nl_web_add_html(server, "/", "index.html");                 // 文件→热加载
nl_web_add_html(server, "/hello", "<h1>Hello</h1>");        // 静态→内联

平台: Windows/Linux/macOS

4. 运行时动态路由管理(v2.2.2新增)

在服务器运行期间添加、移除、查询和更新路由。

// 运行时添加新路由
nl_web_add_route(server, "/api/status", "{\"status\":\"ok\"}", "application/json");

// 查询路由数量
int count = nl_web_get_route_count(server);

// 列出所有路由路径
char* paths[32];
for (int i = 0; i < 32; i++) paths[i] = (char*)calloc(256, 1);
int n = nl_web_list_routes(server, paths, 32);

// 更新路由内容
nl_web_update_route(server, "/api/status", "{\"status\":\"maintenance\"}", "application/json");

// 移除路由
nl_web_remove_route(server, "/old-path");

API:

  • nl_web_add_route() - 添加静态内容路由
  • nl_web_remove_route() - 移除指定路径的路由
  • nl_web_get_route_count() - 获取当前路由数量
  • nl_web_list_routes() - 列出所有路由路径
  • nl_web_update_route() - 更新路由内容(仅支持静态内容类型)

平台: Windows/Linux/macOS

5. 日志系统

// 设置日志级别
nl_log_set_level(NL_LOG_DEBUG);

// 输出日志
nl_log_debug("调试信息");
nl_log_info("一般信息");
nl_log_warn("警告信息");
nl_log_error("错误信息");

// 启用调试模式
nl_debug_enable(1);

6. 数据解析

  • JSON解析: 完整的JSON支持
  • TOML解析: TOML配置文件支持

7. 系统信息组件(懒加载)

获取非敏感的系统信息,采用懒加载机制。

#include "netleaf.h"

int main() {
    // 获取系统信息(首次调用时懒加载)
    const char* os_name = nl_sys_info_get_os_name();
    const char* arch = nl_sys_info_get_architecture();
    const char* cpu = nl_sys_info_get_cpu_model();
    int64_t ram = nl_sys_info_get_total_ram();
    const char* runtime = nl_sys_info_get_runtime_version();
    
    printf("OS: %s\n", os_name);
    printf("Architecture: %s\n", arch);
    printf("CPU: %s\n", cpu);
    printf("Total RAM: %lld bytes\n", (long long)ram);
    printf("Runtime: %s\n", runtime);
    
    return 0;
}

RAM进制配置:

  • NL_RAM_UNIT_DECIMAL (1000): Linux默认,符合SI标准
  • NL_RAM_UNIT_BINARY (1024): Windows默认,传统二进制

8. 全局懒加载

所有组件支持懒加载机制,仅在首次使用时加载。

#include "netleaf.h"

int main() {
    // 预加载特定模块
    nl_lazy_preload_module(NL_LAZY_MODULE_HTTP);
    
    // 检查模块状态
    if (nl_lazy_is_module_loaded(NL_LAZY_MODULE_HTTP)) {
        printf("HTTP模块已加载\n");
    }
    
    // 停止模块释放资源
    nl_lazy_stop_module(NL_LAZY_MODULE_HTTP);
    
    return 0;
}

支持懒加载的模块:

  • NL_LAZY_MODULE_HTTP - HTTP服务器
  • NL_LAZY_MODULE_WEBSOCKET - WebSocket
  • NL_LAZY_MODULE_TCP - TCP通信
  • NL_LAZY_MODULE_UDP - UDP通信
  • NL_LAZY_MODULE_TOML - TOML解析
  • NL_LAZY_MODULE_JSON - JSON解析
  • NL_LAZY_MODULE_SYSINFO - 系统信息

9. 多线程优化

// 设置线程池大小(1-256)
nl_lazy_set_thread_count(8);

// 获取当前线程池大小
int threads = nl_lazy_get_thread_count();

线程池建议:

  • IO密集型: 推荐设置较大线程数(如CPU核心数的2倍)
  • CPU密集型: 推荐设置为CPU核心数

10. 反向代理(数据驱动事件引擎,Beta)

⚠️ Beta 阶段:反向代理引擎已实现完整功能,但 API 与行为可能在后续版本调整。 三平台实现:Linux epoll / macOS kqueue / Windows IOCP(select 作为兼容回退)。 混合路由支持:同一 Web 服务器可同时启用 proxy + static + content + redirect + file 路由, 引擎内部统一处理,彻底消除早期"proxy 路由激活后其它路由返回 501"的限制。

NetLeaf 的 Web 反向代理已升级为数据驱动的异步并行事件引擎:不 为每个连接建立独立对象,而是把连接状态编码为 8 位无状态字节( pr_state) + 一组按设备动态定容的整数 ring buffer 数组(pr_fd_client / pr_fd_upstream / pr_route_idx / pr_hbuf / pr_hbuf_out / pr_hdr_len / pr_remain / pr_free)。单线程通过 I/O 多路复用一次泵多个连接,彻底 摆脱旧版"并发 ≈ worker 数"的瓶颈,同时保持极低 CPU / 内存占用。

多路复用后端(按平台自动选择):

平台 后端 索引携带方式 空闲退避
Linux epoll event.data.u32 编码 idx + 方向位 epoll_wait 1000ms
macOS kqueue kevent.udata 编码 idx + 方向位 kevent 1s
Windows IOCP 完成端口 AcceptEx 预 post + GetQueuedCompletionStatus 分发 200ms 退避

极低占用设计:

  • 所有 fd(listen / 客户端 / 上游)一律非阻塞(O_NONBLOCK / ioctlsocket(FIONBIO)),事件驱动、忙时零等待。
  • 空闲时退避超时(Linux/macOS 1s、Windows 200ms),无连接时近乎零 CPU。
  • 单线程引擎:nl_web_start 检测到 proxy 路由时直接起 1 个引擎线程, 不分配 worker 池;无 proxy 路由时回退到原有 worker 池,行为不变。
  • pr_remain 记录每方向"已收待发余量",先补发上次 EAGAIN / WSAEWOULDBLOCK 未发完的部分再读新数据,杜绝半包丢数据。

ring 容量按设备动态调整(三平台统一):

  • Linux / macOS / Windows:逻辑核数 × 64,下限 64、上限 4096(1 核=64、8 核=512、 16 核=1024,高压 4096)。
  • Windows 采用 IOCP 内核完成端口,不受 FD_SETSIZE 硬上限约束;4096 为工程 保护值(防低内存设备爆掉),需要可按需调大。

上游协议分流(upstream 前缀决定):

  • tcp://host:port —— 纯字节透传,不解协议。
  • http:// / https:// —— 重组 request line + Host / X-Forwarded-For / Connection: close 头,透传原始 header / body。

用法:

#include "netleaf.h"

int main(void) {
    nl_web_server_t* server = nl_web_create(8080);
    // 把 /api/ 透明转发到上游 API 服务(自动走数据驱动引擎)
    nl_web_add_proxy(server, "/api/", "http://127.0.0.1:9000");
    // TCP 上游(如 Redis)
    nl_web_add_proxy(server, "/cache/", "tcp://127.0.0.1:6379");
    nl_web_start(server);   // 有 proxy 路由时单线程引擎自动拉起
    nl_web_stop(server);
    nl_web_destroy(server);
    return 0;
}

引擎接线细节:

  • nl_web_start 持锁遍历 routes,发现任意 NL_ROUTE_TYPE_PROXY 即起引擎 线程(pthread_create / CreateThread 包装 nl_web_proxy_engine)。
  • 混合路由统一分发(v2.4.2 修复):引擎内对四种路由类型做完整分发, 非 proxy 路由(REDIRECT / FILE / CONTENT)临时把 fd 切阻塞处理后立即 close + 释放 slot,proxy 路由保持非阻塞走引擎 pump 链路,彻底消除早期"proxy 路由 激活后其它路由返回 501"的限制;路由查找走引擎内锁保护的 pr_lookup_route_idx。
  • nl_web_stop 关闭 listen socket 后 join 引擎线程;引擎正常退出时已自行 close 全部活跃连接并逐字段 free ring。stop / destroy 额外做兜底 清理(防 TerminateThread 路径残留),保证无泄漏。

11. 编码动态适配

实现"见人说人话,见鬼说鬼话"的智能编码协商机制。

#include "netleaf.h"

int main() {
    // 创建服务器
    nl_web_server_t* server = nl_web_create(8080);
    
    // 启用自动编码协商
    nl_web_enable_auto_encoding(server, 1);
    
    // 设置回退编码(当客户端未指定时使用)
    nl_web_set_fallback_encoding(server, "UTF-8");
    
    // 添加页面(内部始终使用UTF-8)
    nl_web_add_html(server, "/", "<h1>你好,世界!</h1>");
    
    // 添加JSON响应(自动转码)
    nl_web_add_json(server, "/api/data", "{\"message\": \"你好世界\"}");
    
    // 服务器会自动根据客户端Accept-Charset头转换编码
    
    return 0;
}

编码转换API:

// 编码转换(双向转换)
char* gbk_output = nl_encoding_convert(utf8_string, strlen(utf8_string), 
                                        "UTF-8", "GBK");

// 自动检测编码
const char* detected = nl_encoding_detect(data, data_len);

// 获取系统默认编码
const char* sys_enc = nl_encoding_get_system_default();

支持的编码:

  • UTF-8
  • GBK
  • GB2312
  • GB18030
  • Big5
  • ISO-8859-1
  • US-ASCII
  • UTF-16

全场景支持:

  • ✅ 控制台输出
  • ✅ Web响应
  • ✅ HTML页面
  • ✅ Vue组件
  • ✅ JSON响应
  • ✅ TOML响应

特性:

  • ✅ 自动解析Accept-Charset请求头
  • ✅ 运行时自动转码
  • ✅ 双向编码转换
  • ✅ 跨平台支持(Windows/Linux)
  • ✅ 编码自动检测
  • ✅ 懒加载机制:功能拉起使用后自动下线,减少内存占用
  • ✅ 智能优化:仅对非ASCII字符进行转码,减少性能开销

安全特性

  • ✅ 空指针检查
  • ✅ 缓冲区溢出防护
  • ✅ 字符串格式化安全
  • ✅ 数组边界检查
  • ✅ 内存管理安全
  • ✅ 只能停止本库启动的端口

附加模块 (v2.4.0)

NetLeaf支持多个独立可拆卸模块,与主库共用版本号。

Auto-complete (netleaf_autocomplete)

功能: 自动补全charset标签和自动引入Vue库

特性:

  • Charset自动补全:根据统一编码格式添加 <meta charset> 和 <meta name="viewport">
  • Vue自动引用:检测Vue代码但无引用时自动从CDN引入
  • 灵活启用方式:支持 true/false, on/off, yes/no, 1/0
  • 单独控制:charset和Vue功能可独立启用/禁用

平台: Windows/Linux/macOS

Auto-route (netleaf_autoroute)

功能: 404时自动查找相近端点并在错误页面提示

特性:

  • Levenshtein距离算法计算路径相似度
  • 多策略评分:路径段匹配、前缀共有、段数相同
  • 通配符支持:* 和 **

平台: Windows/Linux/macOS

ErrorPage (netleaf_errorpage)

功能: 支持自定义错误页面模板,强制预留变量区域

特性:

  • 独立standalone模块,其他模块不可使用其功能
  • 模板必须预留变量:{{ERROR_CODE}}, {{ERROR_MESSAGE}}, {{REQUESTED_PATH}}, {{SERVER_VERSION}}, {{TIMESTAMP}}
  • 支持 {{#if SUGGESTION}} 条件块
  • 可与Auto-route联动显示路由建议

平台: Windows/Linux/macOS

IPC (netleaf_ipc) - v2.2.1新增

功能: 进程间通讯服务

特性:

  • Windows: Named Pipe
  • Linux: Unix Domain Socket
  • 支持服务端监听和客户端连接
  • 跨进程数据传输
  • 线程安全设计

平台: Windows/Linux

Link Aggregation (netleaf_linkagg) - v2.2.1新增

功能: 同端口链路聚合,将请求转发到多个后端

特性:

  • 单端口监听
  • 负载均衡策略: Round Robin, Random, Least Connections, Weighted Round Robin
  • 支持 HTTP 和 IPC 后端
  • 同端口路由聚合

平台: Windows/Linux

Vue (netleaf_vue) - v2.2.2新增

功能: Vue.js 后端支持和 HTML 生成

特性:

  • Vue CDN 配置(unpkg、cdnjs、jsdelivr、local)
  • Vue 代码检测和自动导入
  • HTML 页面生成(带 Vue CDN)
  • 本地 Vue.js 文件支持(离线/内嵌模式)
  • 预制系统信息页面(nl_vue_generate_sysinfo / nl_vue_generate_sysinfo_inline)
  • 变量替换支持

平台: Windows/Linux/macOS

统一模块接口 (v2.2.1)

所有独立模块通过统一接口进行管理:

typedef struct nl_module_info {
    nl_module_type_t type;
    const char* name;
    const char* version;
    uint32_t capabilities;
    nl_module_status_t status;
    int platform_windows;
    int platform_linux;
    int platform_macos;
    int (*init)(void);
    void (*shutdown)(void);
    int (*is_available)(void);
    const char* (*get_version)(void);
    const char* description;
    const char* author;
    struct nl_module_info* next;
} nl_module_info_t;

模块管理API:

  • nl_module_register() - 注册模块
  • nl_module_unregister() - 注销模块
  • nl_module_find() - 查找模块
  • nl_module_get_all() - 获取所有模块列表
  • nl_module_init_all() - 初始化所有模块
  • nl_module_shutdown_all() - 关闭所有模块

Lang (netleaf_lang) - 多语言错误消息 + 变量替换(v2.4.0)

功能: 提供统一的多语言错误消息翻译功能,并增强支持变量替换和条件表达式求值

特性:

  • 中英文错误消息支持
  • 所有 NetLeaf 库的错误码统一翻译
  • 简单易用的 API
  • 运行时语言切换
  • 变量替换:{{VAR_NAME}} 模板语法,支持字符串/整数/浮点/布尔类型
  • 条件表达式:支持 == != >= <= > < 运算符,兼容数值和字符串比较
  • 脚本引擎:通过回调注册 Lua/Python/JavaScript 引擎(扩展 API)
  • 动态变量(v2.4.1):nl_lang_var_set_provider() 按需计算变量值
  • 外部变量(v2.4.1):nl_lang_var_bind_env() / nl_lang_var_load_env() / nl_lang_var_load_file()
  • 表驱动错误注册(v2.4.1):NL_ERROR_BEGIN/NL_ERROR/NL_ERROR_END + nl_lang_register_errors()

API 示例:

#include "netleaf_lang.h"

// 设置语言为中文
nl_lang_set(NL_LANG_ZH);

// 获取 LinkAgg 错误消息
const char* msg = nl_lang_get_error(NL_LIB_LINKAGG, -9);
// 输出: "不接入,ID被占用"

// 设置语言为英文
nl_lang_set(NL_LANG_EN);
msg = nl_lang_get_error(NL_LIB_LINKAGG, -9);
// 输出: "ID already in use, not connected"

// === v2.4.0 新增:变量替换 ===
nl_lang_var_set("user",    "Alice");
nl_lang_var_set_int("age",  25);
nl_lang_var_set_float("price", 3.14);
nl_lang_var_set_bool("active", 1);

char buf[256];
nl_lang_var_replace("Hello {{ user }}, age={{ age }}", buf, sizeof(buf));
// buf == "Hello Alice, age=25"

// === v2.4.0 新增:条件表达式 ===
int result = nl_lang_var_condition_eval("age > 18");           // 1 (true)
result = nl_lang_var_condition_eval("user == 'Alice'");        // 1 (true)
result = nl_lang_var_condition_eval("price >= 3.0");           // 1 (true)
result = nl_lang_var_condition_eval("active == true");         // 1 (true)

// === v2.4.0 新增:脚本引擎注册 ===
nl_script_result_t* my_exec(const char* script, const char* lang_code, int error_code, void* userdata) {
    // 实现脚本执行逻辑
    static nl_script_result_t result;
    result.status = 0;
    result.result_type = 1;
    result.result_str = "hello from script";
    return &result;
}
nl_lang_register_script_engine("myscript", my_exec, NULL);
char script_out[256];
nl_lang_execute_script("myscript", "echo hello", NULL, 0, script_out, sizeof(script_out));

平台: Windows/Linux/macOS

库标识符:

库 标识符
Core NL_LIB_CORE (0x0000)
IPC NL_LIB_IPC (0x0001)
LinkAgg NL_LIB_LINKAGG (0x0002)
Auto-route NL_LIB_AUTOROUTE (0x0003)
Auto-complete NL_LIB_AUTOCOMPLETE (0x0004)
ErrorPage NL_LIB_ERRORPAGE (0x0005)
Lang NL_LIB_LANG (0x0006)
TLS NL_LIB_TLS (0x0007)
MQTT NL_LIB_MQTT (0x0008)

TLS/SSL 加密扩展 (v2.4.0)

模块: netleaf_tls.dll

说明: TLS/SSL 是一个独立的扩展库,其他通信协议(包括 MQTT)可通过 NL 扩展系统调用其功能。基于 mbedTLS 2.28.10 LTS 构建,支持多种安全协议。

特性

  • ✅ 协议支持: TLS 1.0, 1.1, 1.2, 1.3
  • ✅ 密码套件: 多种主流密码套件
  • ✅ 证书验证: CA 证书链验证、客户端证书认证
  • ✅ 随机数生成: 基于硬件熵源的加密安全随机数
  • ✅ 内存管理: 自动内存分配和释放
  • ✅ 线程安全: 支持多线程并发使用

⚠️ 安全提示(不推荐 TLS 1.0 / 1.1):TLS 1.0/1.1 已被 RFC 8996 废弃且不再安全,不建议使用。 TLS 由本独立的 TLS 扩展库(netleaf_tls,内置 mbedTLS)统一负责,保留 1.0/1.1 仅为兼容老旧对端; 请将 min_proto 设置为 NL_TLS_PROTO_TLS1_2 或更高。

架构

flowchart TD
    subgraph NLEXT["NetLeaf 扩展系统"]
        MQTT["netleaf_mqtt"]
        OTHER["其他扩展库"]
    end
    TLS["netleaf_tls.dll<br/>(TLS/SSL 加密扩展)"]
    MQTT -->|调用| TLS
    OTHER -->|调用| TLS
Loading

构建配置

# CMakeLists.txt
option(BUILD_TLS "Build TLS/SSL extension" ON)

# 编译时自动包含 mbedTLS 源码
if(BUILD_TLS)
    target_link_libraries(netleaf_mqtt PRIVATE netleaf_tls)
endif()

平台: Windows/Linux/macOS


MQTT v5.0 协议客户端 (v2.4.0)

模块: netleaf_mqtt.dll

说明: 轻量级 MQTT v5.0 协议客户端实现,支持 QoS 0/1/2、主题订阅发布、消息回调等核心功能。可选集成 TLS 加密通信。

特性

  • ✅ MQTT 5.0: 完整支持 MQTT v5.0 协议
  • ✅ QoS 级别: QoS 0 (至多一次), QoS 1 (至少一次), QoS 2 (恰好一次)
  • ✅ 主题订阅: 支持通配符 (+ 和 #)
  • ✅ 消息回调: 异步消息接收和处理
  • ✅ 连接管理: 自动重连、心跳保活
  • ✅ 属性支持: 完整的属性编码/解码
  • ✅ TLS 加密: 可选集成 TLS/SSL 安全通信

架构

flowchart TD
    subgraph MQTT["netleaf_mqtt.dll"]
        direction LR
        CORE["MQTT 核心<br/>(netleaf_mqtt.c)"]
        MTLSP["MQTT TLS 模块<br/>(netleaf_mqtt_tls.c)"]
    end
    TLS["netleaf_tls<br/>(可选)"]
    MQTT --> TLS
Loading

构建配置

# CMakeLists.txt
option(BUILD_MQTT "Build MQTT client module" ON)
option(BUILD_TLS   "Build TLS/SSL extension for MQTT" ON)

平台: Windows/Linux/macOS


开源项目来源

NetLeaf 项目中使用了以下开源项目,特此致谢:

项目 许可证 用途 链接
mbedTLS Apache 2.0 / GPL v2.0 TLS/SSL 加密库 github.com/Mbed-TLS/mbedTLS
MQTT 规范 EPL-2.0 / EDL 1.0 MQTT v5.0 协议定义 mqtt.org
Paho MQTT C EPL-2.0 / EDL 1.0 MQTT 协议参考实现 github.com/eclipse/paho.mqtt.c

注意: 本项目中 mbedTLS 源码已内置于 third-party/mbedtls/ 目录,编译时自动包含,无需用户单独安装。

⚠️ **GitHub.com Fallback** ⚠️