Mongoose 网络库之概述

Mongoose 是一个单文件、事件驱动的 C/C 网络库它将 TCP、UDP、HTTP、WebSocket、MQTT 和 TLS 协议引入了几乎任何平台——从裸机微控制器到云服务器。自 2004 年发布以来它已部署到全球数亿台设备包括国际空间站其存在的意义在于让嵌入式网络编程变得快速、健壮且异常简单。什么是 Mongoose在其核心Mongoose 提供了一个由中央事件循环驱动的异步非阻塞 I/O 模型。你创建一个事件管理器为所需的协议注册监听器提供一个回调函数然后让mg_mgr_poll()循环处理其余的一切——连接生命周期、数据分帧、协议解析、TLS 握手、DNS 解析和超时处理。这里没有线程要求没有外部依赖也没有需要费力应对的复杂构建系统。整个库仅以两个文件发布——mongoose.c和mongoose.h——你可以将它们放入任何项目中并通过单条命令进行编译。尽管如此极简其源码完全符合 ISO C 和 ISO C 标准当前版本为7.21。它的独特之处传统的嵌入式网络方法往往迫使人面临艰难的权衡要么采用消耗宝贵 Flash 和 RAM 的重量级 TCP/IP 协议栈加操作系统组合要么从头开始构建一切并独自承担协议正确性和安全的全部重担。Mongoose 占据了一个独特的中间地带。它可以运行在任何兼容 BSD socket 的协议栈lwIP、Zephyr、Azure RTOS 等之上或者直接在裸机硬件上运行其自带的 TCP/IP 协议栈——完全消除了对任何第三方网络软件的需求。高层架构每个 Mongoose 应用程序都围绕相同的基本模式构建一个事件管理器持有一个由连接组成的链表每个连接携带一个用户提供的事件处理函数而一个轮询循环驱动这一切向前运行。特定协议的逻辑HTTP 解析、WebSocket 分帧、MQTT 消息处理分层构建在这个统一的抽象之上将原始的 socket 字节转化为你的处理函数接收的结构化事件。这种架构意味着你只需学习一种 API 模式就能将其应用于所有协议。无论你是在提供 Web 仪表板、发布 MQTT 遥测数据还是建立用于实时控制的 WebSocket其基础代码结构都是完全相同的。支持的协议Mongoose 实现了现代物联网和嵌入式设备所需的完整网络协议套件。每个协议都通过遵循相同事件处理模式的整洁、一致的 API 接口暴露出来。协议角色核心头文件描述TCP / UDP传输层src/net.h原始连接管理、发送/接收、DNS 解析HTTP应用层src/http.h完整的 HTTP/1.1 服务端和客户端、REST API、文件服务、分块上传WebSocket应用层src/ws.h文本和二进制帧、ping/pong、从 HTTP 升级MQTT应用层src/mqtt.h支持 QoS 的发布/订阅客户端已为 MQTT v5 做好准备TLS安全层src/tls.h内置支持 ECC 的 TLS 1.3或可插拔的 mbedTLS/OpenSSL 后端DNS基础设施src/dns.h异步非阻塞 DNS 解析器A、AAAA、SRV 记录SNTP基础设施src/sntp.h通过 NTP 服务器进行网络时间同步JSON-RPC应用层src/rpc.h在任何传输层上运行的内置远程过程调用框架OTA基础设施src/ota.h支持 15 个以上 MCU 系列的空中固件升级平台覆盖Mongoose 最引人注目的属性在于其广泛的平台支持。相同的源代码可以在工作站、嵌入式 Linux 系统、RTOS 环境以及完全裸机的微控制器上编译和运行。这是通过一个平台抽象层src/arch_*.h实现的该层将所有特定于操作系统和硬件的细节隔离在一组整洁的宏和函数签名之后 。外部 TCP/IP 协议栈模式在现有的网络协议栈上运行时Mongoose 使用标准的 BSD socket API。这几乎涵盖了所有已具备 TCP/IP 协议栈的平台。平台TCP/IP 协议栈用例Linux、macOS、Windows原生 OS sockets开发、测试、服务端ESP32 / ESP32-S3 / ESP32-C3lwIPEspressif Wi-Fi MCUZephyr RTOSZephyr 原生Nordic、STM32 及其他 Zephyr 开发板FreeRTOSFreeRTOS-TCP、lwIP通用 RTOS 环境任何 BSD socket 协议栈自定义Amazon FreeRTOS-TCP 等内置 TCP/IP 协议栈模式Mongoose 自带了其 TCP/IP 协议栈MG_ENABLE_TCPIP允许它直接在具备以太网能力的 MCU 上运行且零外部网络依赖。这在资源受限的设备上特别有价值因为引入 lwIP 可能显得大材小用。在裸机 STM32 Nucleo 开发板上实现一个完整的 Web 设备仪表板仅需 6 个文件——相比之下典型的 CubeIDE 生成的 HTTP 示例则需要 400 多个文件。硬件系列支持的芯片驱动位置STM32Fxx、H5xx、H7xxsrc/drivers/stm32f.c、stm32h.cNXPi.MX RT10xx、RT11xx、RW612、MCXN94xsrc/drivers/imxrt.c、rw612.cMicrochipATSAME54src/drivers/same54.cRenesasRA5M、RA6M、RA8Msrc/drivers/ra.cInfineonXMC4、XMC7src/drivers/xmc.c、xmc7.cTexas InstrumentsTM4C、TMS570src/drivers/tm4c.c、tms570.cWiznetW5500、W5100src/drivers/w5500.c、w5100.cCypress WiFiCYW43xx (Pico-W、Portenta)src/drivers/pico-w.c事件系统理解事件系统是高效使用 Mongoose 最重要的一步。每一个连接——无论是监听套接字、已接受的客户端连接、外发的 MQTT 链接还是 WebSocket——都会向你提供的一个回调函数触发事件。ev参数告诉你发生了什么而ev_data携带了特定协议的上下文。核心连接事件事件含义ev_data类型MG_EV_OPEN连接已创建NULLMG_EV_CONNECT出站连接已建立NULLMG_EV_ACCEPT入站连接已接受NULLMG_EV_READ从套接字接收到数据long *读取的字节数MG_EV_WRITE数据已写入套接字long *写入的字节数MG_EV_CLOSE连接已关闭NULLMG_EV_ERROR发生错误char *错误消息特定协议事件事件协议含义MG_EV_HTTP_MSGHTTP已解析完整的 HTTP 请求/响应MG_EV_HTTP_HDRSHTTP已接收 HTTP 头部正文之前MG_EV_WS_OPENWebSocket握手完成升级成功MG_EV_WS_MSGWebSocket接收到文本或二进制消息MG_EV_WS_CTLWebSocket控制帧关闭、ping、pongMG_EV_MQTT_OPENMQTT收到 CONNACK连接就绪MG_EV_MQTT_MSGMQTT收到 PUBLISH 消息MG_EV_SNTP_TIMESNTP已从 NTP 服务器同步时间MG_EV_TLS_HSTLSTLS 握手已完成项目结构代码仓库被组织为三个顶层区域根目录下的单文件发行版、src/下的模块化源码树以及丰富的教程和测试集合。mongoose/ ├── mongoose.c ← 单文件合并版所有代码编译在一起 ├── mongoose.h ← 公共 API 头文件版本、架构定义、所有声明 │ ├── src/ ← 用于高级集成的模块化源码 │ ├── arch_*.h ← 平台抽象UNIX、WIN32、ESP32、Zephyr 等 │ ├── config.h ← 编译时功能标志 (MG_ENABLE_*) │ ├── event.h / event.c ← 事件分发系统 │ ├── net.h / net.c ← 连接管理器 (mg_mgr, mg_connection) │ ├── net_builtin.c/h ← 内置 TCP/IP 协议栈 │ ├── drivers/ ← 内置 TCP/IP 的硬件驱动30 多个文件 │ ├── http.h / http.c ← HTTP 服务端和客户端 │ ├── ws.h / ws.c ← WebSocket 协议 │ ├── mqtt.h / mqtt.c ← MQTT 客户端 │ ├── tls_*.c / tls_*.h ← TLS 后端内置、mbedTLS、OpenSSL │ ├── dns.h / dns.c ← 异步 DNS 解析器 │ ├── sntp.h / sntp.c ← SNTP 时间客户端 │ ├── fs.h / fs_*.c ← 文件系统抽象POSIX、FAT、打包文件 │ ├── ota_*.c / ota.h ← OTA 固件升级15 个以上 MCU 系列 │ ├── rpc.h / rpc.c ← JSON-RPC 框架 │ ├── json.h / json.c ← JSON 解析器 │ ├── iobuf.h / iobuf.c ← IO 缓冲区管理 │ ├── timer.h / timer.c ← 定时器子系统 │ └── ... ← base64、md5、sha1、sha256、fmt、str、queue、log │ ├── tutorials/ ← 30 多个协议和平台教程 │ ├── core/ ← 基本概念事件循环、嵌入式文件系统 │ ├── http/ ← HTTP 服务端、REST API、文件上传、认证 │ ├── websocket/ ← WebSocket 回显、聊天、仪表板 │ ├── mqtt/ ← MQTT 发布/订阅 │ ├── tls/ ← TLS 服务端和客户端 │ ├── tcp/ / udp/ ← 原始 TCP/UDP 通信 │ ├── stm32/ / esp32/ / ← 按厂商划分的硬件特定教程 │ │ nxp/ / zephyr/ / │ │ pico-sdk/ / ... │ └── device-dashboard/ ← 完整的 Web UI 仪表板示例 │ └── test/ ← 单元测试、模糊测试、硬件测试套件构建配置Mongoose 完全通过在src/config.h中定义的编译时宏进行控制。每个功能都可以独立启用或禁用从而允许你仅编译项目所需的内容并将 Flash/RAM 占用降至最低。极小体积在禁用所有协议的情况下Mongoose 编译后的 Flash 占用约为 30KB。一个带有 TLS 的典型 HTTP 服务端根据所选的 TLS 后端大约会增加 100–200KB。MG_IO_SIZE宏默认为 512 字节控制 IO 缓冲区的粒度——在 RAM 受限的设备上可以减小它以牺牲吞吐量为代价来换取内存。宏默认值用途MG_ENABLE_TCPIP0启用内置 TCP/IP 协议栈裸机MG_ENABLE_LWIP0使用 lwIP 作为网络后端MG_TLSMG_TLS_NONETLS 后端BUILTIN、MBED、OPENSSL、WOLFSSLMG_OTAMG_OTA_NONEOTA 支持STM32H5、STM32H7、ESP32、PICOSDK等MG_ENABLE_SOCKET!MG_ENABLE_TCPIPBSD socket 支持使用内置协议栈时自动禁用MG_ENABLE_FATFS0FAT 文件系统支持MG_ENABLE_IPV60IPv6 协议支持MG_ENABLE_DIRLIST0HTTP 目录列表MG_IO_SIZE512IO 缓冲区增长粒度字节MG_MAX_RECV_SIZE3MB最大接收缓冲区大小MG_ENABLE_PROFILE0用于性能分析的连接性能剖析安全态势Mongoose 持续受到多层自动化和手动安全分析的审查。代码仓库集成了GitHub Actions CI在每次提交时使用地址 sanitizer 运行数百个单元测试、Google 的 OSS-Fuzz持续模糊测试工具并定期接收来自独立安全组织包括 Cisco Talos、Microsoft Security Response Center、MITRE Corporation 和 Compass Security的漏洞报告。双重许可Mongoose 针对开源项目以 GPLv2 发布同时为专有产品提供商业许可证。商业许可证包含优先的安全通知——在规模化部署生产设备时这一点至关重要 。API 初探理解 Mongoose 最好的方式就是看它的实际运行。下面这个完整的 HTTP 服务端——用于提供目录中的文件——仅用不到 15 行 C 代码即可实现static void timer_fn(void *arg) {struct mg_mgr *mgr (struct mg_mgr *) arg;for (struct mg_connection *c mgr-conns; c ! NULL; c c-next) {if (c-data[0] W) mg_ws_send(c, hi, 2, WEBSOCKET_OP_TEXT);}}int main(void) {struct mg_mgr mgr;mg_mgr_init(mgr);mg_timer_add(mgr, 1000, MG_TIMER_REPEAT, timer_fn, mgr); // 每 1 秒mg_http_listen(mgr, http://localhost:8000, fn, NULL);for (;;) mg_mgr_poll(mgr, 500);mg_mgr_free(mgr);return 0;}编译命令cc main.c mongoose.c -I.——这就是整个构建系统。