Home - 508364/NetLeaf GitHub Wiki

NetLeaf v2.4.2

高性能跨平台网络库，支持TCP/UDP/HTTP/HTTP2/HTTP3，以及内联HTML/Vue响应式Web服务器。内置TLS/SSL加密和MQTT v5.0协议支持。

快速链接

附加模块

  • Auto-complete - 自动补全charset和Vue引入
  • Auto-route - 自动路由建议
  • ErrorPage - 自定义错误页面模板
  • IPC - 进程间通讯服务
  • LinkAgg - 同端口链路聚合
  • Lang - 多语言错误消息
  • Vue - Vue.js后端支持
  • TLS - TLS/SSL 加密扩展
  • MQTT - MQTT v5.0 协议客户端
  • Extension - 扩展库开发指南

主要特性

  • ✅ 跨平台支持（Windows/Linux/macOS）
  • ✅ 多架构支持（x86, x64, ARM, ARM64, RISC-V, etc.）
  • ✅ HTTP/1.1 + HTTP/2 + HTTP/3 (QUIC)
  • ✅ TCP + UDP 套接字
  • ✅ WebSocket 支持
  • ✅ JSON + TOML 解析
  • ✅ 响应式 Web UI（Vue.js）
  • ✅ 变量硬编码（服务器端变量替换）
  • ✅ 自定义编码设置
  • ✅ 完整日志系统
  • ✅ 系统信息组件（懒加载）
  • ✅ 全局懒加载支持
  • ✅ 模块启停功能
  • ✅ 多线程优化
  • ✅ IPC通讯服务（Windows Named Pipe/Linux Unix Domain Socket）
  • ✅ 同端口链路聚合（负载均衡）
  • ✅ 统一模块接口
  • ✅ 多语言错误消息（无限语言支持）
  • ✅ ASan内存检测支持
  • ✅ 动态扩展库系统（自动加载、热重载、搜索过滤）
  • ✅ HTTP重定向（301/302运行时切换）
  • ✅ 文件热加载（修改外部HTML/Vue/JSON后刷新立即生效）
  • ✅ 智能检测（nl_web_add_html/vue/json自动识别URL/文件/静态内容）
  • ✅ 扩展生命周期管理 API
  • ✅ 扩展批量操作 API
  • ✅ 扩展搜索过滤 API
  • ✅ 扩展元数据管理 API
  • ✅ Lang变量替换（{{VAR_NAME}}模板语法，v2.4.0）
  • ✅ Lang条件表达式（== != >= <= > <，兼容数值与字符串，v2.4.0）
  • ✅ Lang脚本引擎回调（可扩展接入Lua/Python/JS，v2.4.0）
  • ✅ TLS/SSL 加密（mbedTLS 2.28.10 LTS 内置，v2.4.0）
  • ✅ MQTT v5.0 协议（完整实现，v2.4.0）
  • ✅ Lang 动态/外部变量（provider 动态求值、环境变量绑定与 .env 导入，v2.4.1）
  • ✅ 表驱动错误码注册（NL_ERROR_BEGIN/NL_ERROR/NL_ERROR_END，各模块返回码接入多语言，v2.4.1）

更新日志

v2.4.2

新增:

  • HTTPS 拆出独立库 netleaf_https（纯 HTTP 的 netleaf_http 不依赖 TLS，HTTPS/TLS 独立成库）
  • TLS 扩展拆分：netleaf_tls2（mbedTLS 2.28.10）与新增 netleaf_tls3（mbedTLS 3.x，TLS 1.2/1.3）
  • MQTT 默认开启：BUILD_MQTT / BUILD_MQTT_SERVER 默认值 OFF → ON
  • 平台无关公共工具层 nl_util（字符串/安全/一次性初始化，收敛各扩展重复拷贝）
  • HTTP 短名转接层 nlh_*（长名标记 deprecated，仅对外部调用告警）
  • MQTT 服务端 + 回环回归测试 test_mqtt_server_loopback

变更:

  • 测试 CMake 拆分至 test/CMakeLists.txt，顶层改为 add_subdirectory(test)，按开关裁剪链接
  • 三平台公共 HTTP 逻辑去重（netleaf_http_common.c）
  • 扩展注册自动依赖检查：必需依赖缺失时 nl_extension_register 返回 -2
  • netleaf_lang 软依赖解耦（未构建时 lang 调用点退化为 no-op）
  • 新增 LTO 选项 NETLEAF_ENABLE_LTO（仅加 -flto//GL /LTCG，不提升 -O 等级）
  • 性能占用优化：H2 动态表指针化（每连接削减 ≈4.7 MB）、H3 回包栈缓冲复用

修复:

  • QUIC varint 编码 8 字节档缺上界（value ≥ 2^62 溢出，真实 BUG）
  • H2 帧协议补全：END_HEADERS/CONTINUATION/PUSH_PROMISE
  • QUIC 传输层帧补全（MAX_DATA/ACK/PING/CONNECTION_CLOSE 等，RFC 9000）
  • mbedTLS 3.6 API 移植（12 处）
  • HTTP 写完不关 fd → CLOSE-WAIT（BUG-001）、epoll 事件处理（BUG-101/102）
  • UDP handler 缺对端地址（BUG-201，新增 nl_udp_message_handler_v2）
  • 编译器告警根除（-Wstringop-truncation 等，BUG-304）

验证:

  • test_http_frames（H2/QUIC 回环 + 短名一致性）16/16 通过
  • ctest 7/7 全部通过（含 MqttServerLoopbackTest）

完整变更与技术细节见仓库根目录 CHANGELOG.md。

v2.4.1

Lang 模块增强:

  • 错误码接入多语言：新增 NL_ERROR_BEGIN/NL_ERROR/NL_ERROR_END 宏与 nl_lang_register_errors()，autoroute/autocomplete/errorpage/ipc 等模块返回码统一纳入
  • 动态变量：nl_lang_var_set_provider() / nl_lang_var_is_dynamic()
  • 外部变量：nl_lang_var_bind_env() / nl_lang_var_load_env() / nl_lang_var_load_file()

质量与构建:

  • 清理编译告警（多余分号、末尾换行、dllimport、格式串、未使用项等），并修复 MQTT 报文 ID 未初始化等隐患
  • 一键脚本完成全平台交叉编译：Windows(x64/x86/arm64)、Linux(13 架构)、macOS(x86_64/arm64)

v2.4.0

Lang 模块增强:

  • 变量替换：nl_lang_var_set/set_int/set_float/set_bool + nl_lang_var_get/get_int/get_float/get_bool
  • 模板替换：nl_lang_var_replace — 支持 {{VAR_NAME}} 语法，自动 trim 空白
  • 条件表达式：nl_lang_var_condition_eval — 支持 == != >= <= > <，兼容数值与字符串
  • 脚本引擎回调：nl_lang_register_script_engine / nl_lang_execute_script — 可扩展接入 Lua/Python/JS
  • 多线程安全：全局变量读写使用 mutex 保护

TLS/SSL 扩展 (v2.4.0):

  • 内置 mbedTLS 2.28.10 LTS 源码
  • 通用 TLS API：nl_tls_create/destroy/configure/handshake/send/recv/close
  • 证书管理：CA证书链、客户端证书、私钥
  • 支持 TLS 1.0 - TLS 1.3（⚠️ 不推荐使用 TLS 1.0/1.1）
  • 随机数生成器（entropy + CTR-DRBG）
  • MQTT TLS 集成：nl_mqtt_tls_create/destroy/configure/handshake
  • 构建选项：-DBUILD_TLS=ON

MQTT 模块增强（v2.4.0）:

  • MQTT v5.0 完整协议支持
  • CONNECT/PUBLISH/SUBSCRIBE/UNSUBSCRIBE 完整实现
  • QoS 0/1/2 消息质量保障
  • MQTT 5.0 属性编码/解码
  • 主题通配符匹配（+ 和 #）
  • 连接认证（用户名/密码）
  • 遗嘱消息支持
  • 客户端 ID 验证
  • 事件循环机制（maintain/connect/disconnect/ping）
  • 构建选项：-DBUILD_MQTT=ON

NL扩展系统 API 导出符号修复:

  • 为 nl_module_register 及相关函数添加 NL_API 装饰符
  • 修复扩展模块链接时找不到核心库符号的问题

扩展系统 API 增强:

  • 扩展生命周期管理：nl_extension_init()、nl_extension_shutdown()、nl_extension_force_shutdown()
  • 扩展状态查询：nl_extension_is_initialized()、nl_extension_is_running()、nl_extension_get_state()
  • 扩展信息查询：nl_extension_get_name()、nl_extension_get_author()、nl_extension_get_description()、nl_extension_get_caps()
  • 平台支持检查：nl_extension_supports_platform()
  • 批量操作：nl_extension_init_all()、nl_extension_shutdown_all()、nl_extension_force_shutdown_all()
  • 扩展搜索过滤：nl_extension_find_by_capability()、nl_extension_find_by_platform()、nl_extension_find_by_name_pattern()
  • 热重载支持：nl_extension_reload()、nl_extension_reload_all()
  • 元数据管理：nl_extension_get_metadata()、nl_extension_set_metadata()
  • 自动加载机制优化：支持标准符号命名约定（library_id_get_info、get_library_id_info、library_id_extension_info）
  • 所有版本号统一更新为 2.4.0

v2.2.1

新增功能 - IPC通讯服务:

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

新增功能 - 同端口链路聚合:

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

统一模块接口:

  • 模块信息结构 nl_module_info_t
  • 模块注册/注销 API
  • 模块版本、能力、平台支持查询
  • 统一的模块管理 API

多语言错误消息 (netleaf_lang):

  • 无限语言支持（en_us, zh_cn, ja_jp, ko_kr 等）
  • 语言代码格式强制 xx_xx（忽略大小写）
  • 分开注册语言和错误消息
  • 自定义语言代码和错误码注册
  • 多文件支持（一个库多个语言文件）
  • 多库共享文件（需显示声明）
  • 错误码重复检测
  • 异步加载支持
  • 跨平台：Windows / Linux / macOS

Bug修复:

  • 修复边缘触发 epoll 循环读取问题
  • 修复 socket 双重关闭问题
  • 修复内存泄漏问题
  • 修复缓冲区溢出问题
  • 修复线程安全问题

性能优化:

  • 启用 LTO 链接时优化
  • qsort 替换 bubble sort
  • 移除 usleep(100ms) 忙等待，改用 poll
  • 添加安全加固编译标志
  • 构建系统优化（OBJECT库避免重复编译）

构建系统更新:

  • CMake选项: BUILD_IPC, BUILD_LINKAGG
  • ASan支持: BUILD_ASAN

v2.2.0

新增功能 - macOS平台支持:

  • 完整的macOS实现（kqueue事件机制）
  • iconv编码转换
  • pthread懒加载机制
  • sysctl系统信息获取

新增功能 - Auto-complete模块:

  • 自动补全HTML中缺失的charset和viewport标签
  • 自动检测Vue代码并添加CDN引用
  • 支持灵活的启用/禁用方式
  • 支持单独控制charset和Vue功能

新增功能 - Auto-route模块:

  • 智能路由匹配（Levenshtein距离算法）
  • 多策略评分（路径段匹配、前缀共有、段数相同）
  • 404时自动给出路由建议
  • 支持通配符模式匹配

新增功能 - ErrorPage模块:

  • 自定义错误页面模板
  • 强制预留变量区域
  • 支持条件块
  • 可与Auto-route联动显示路由建议

构建系统更新:

  • CMake选项: BUILD_AUTOCOMPLETE, BUILD_AUTOROUTE, BUILD_ERRORPAGE
  • 所有附加模块默认一起构建，共用主库版本号
  • macOS交叉编译toolchain支持

v2.1.6

新增功能 - 编码动态适配:

  • nl_web_enable_auto_encoding() - 启用自动编码协商
  • nl_encoding_convert() - 编码转换函数
  • nl_encoding_detect() - 自动检测字符串编码
  • nl_encoding_get_system_default() - 获取系统默认编码
  • 支持UTF-8/GBK/GB2312/GB18030/Big5等8种编码
  • 自动解析客户端Accept-Charset请求头
  • 运行时自动转码响应内容

全场景支持:

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

性能优化:

  • ✅ 懒加载机制：功能拉起使用后自动下线，减少内存占用
  • ✅ 智能优化：仅对非ASCII字符进行转码，减少性能开销

编译器修复:

  • 默认使用UTF-8编码编译，解决中文乱码问题

v2.1.5

新增功能:

  • nl_sys_info_get_os_name() - 获取操作系统名称
  • nl_sys_info_get_architecture() - 获取系统架构
  • nl_sys_info_get_cpu_model() - 获取CPU型号
  • nl_sys_info_get_total_ram() - 获取总内存
  • nl_sys_info_get_runtime_version() - 获取运行库版本
  • nl_sys_info_set_ram_unit() - 设置RAM进制（1000/1024）
  • nl_lazy_enable() - 全局启用/禁用懒加载
  • nl_lazy_preload_module() - 预加载指定模块
  • nl_lazy_stop_module() - 停止指定模块并释放资源
  • nl_lazy_set_thread_count() - 设置线程池大小
  • 全局懒加载支持（7个模块）
  • RAM进制配置（Linux默认1000，Windows默认1024）
  • 多线程优化（默认4线程，可配置1-256）

安全更新:

  • nl_web_stop_by_port() 只能停止本库启动的端口

旧版本

作者: 508364 版本: 2.4.2 许可: MIT License

开源项目来源

本项目的部分功能和实现参考了以下开源项目：

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

mbedTLS 集成说明

本项目内置了 mbedTLS 2.28.10 LTS 源码（位于 third-party/mbedtls/），用于提供 TLS 1.0 - TLS 1.3 加密支持：

⚠️ 安全提示（不推荐 TLS 1.0 / 1.1） TLS 1.0 与 TLS 1.1 已被 RFC 8996 正式废弃且不再安全，不建议使用。 NetLeaf 的 TLS 能力由独立的 TLS 扩展库（netleaf_tls，内置 mbedTLS）统一负责；保留 TLS 1.0/1.1 仅为兼容老旧对端， 实际使用请将 min_proto 设置为 NL_TLS_PROTO_TLS1_2 或更高。

#include "netleaf_tls.h"

// 创建 TLS 上下文
nl_tls_ctx_t* ctx = nl_tls_create();

// 配置证书
nl_tls_config_t cfg = {
    .ca_file = "ca.crt",
    .verify_peer = 1
};
nl_tls_configure(ctx, &cfg);

// 建立安全连接
nl_tls_handshake(ctx, socket_fd);
nl_tls_send(ctx, data, len);
nl_tls_recv(ctx, buffer, bufsize);

详细 API 请参考 TLS 模块文档。