# API-libmongoose — 嵌入式 HTTP/WebSocket 网络库

> 版本: v1.0  
> 日期: 2026-07-08  
> 来源: Mongoose v7.22 (MIT 许可，https://github.com/cesanta/mongoose)  
> 状态: ✅ 导入完成，x86 + ARM 双平台编译通过（零警告）

---

## 1. 模块概述

libmongoose 是 Mongoose v7.22 开源库的封装模块。Mongoose 是一个**单文件、纯 C 实现的嵌入式网络库**，广泛用于 IoT 和嵌入式设备。本模块主要用于 RTU 的 Web 管理服务（`libweb_server`），提供 HTTP REST API 和 WebSocket 双向通信能力。

| 功能 | 说明 |
|------|------|
| HTTP 服务器 | 解析请求、路由匹配、JSON 响应，用于 REST API |
| WebSocket | 双向消息推送（实时遥测数据、告警通知） |
| 事件驱动 | 基于 epoll 的异步 IO，单线程管理所有连接 |
| 定时器 | 毫秒级软定时器，无需额外线程 |
| 跨平台 | Linux / FreeRTOS / Zephyr / ESP32 等，本工程只用 Linux |

### 架构位置

```
libweb_server (system/) — REST API + WebSocket 管理
    │
    ▼
libmongoose (protocol/) — HTTP/WS 协议栈
    │
    ▼
Linux kernel socket + epoll
```

---

## 2. 文件结构

```
src/protocol/libmongoose/
├── inc/
│   ├── myMongoose.h      # RTU 适配头（编译配置宏 + #include "mongoose.h"）
│   └── mongoose.h        # Mongoose v7.22 头文件（5748 行，上游文件）
└── src/
    └── mongoose.c        # Mongoose v7.22 实现（31786 行，上游文件）

release/
├── inc/
│   ├── myMongoose.h      # 拷贝自 src，供其他模块包含
│   └── mongoose.h        # 拷贝自 src
└── x86/lib/
    └── libmongoose.a     # x86 编译产物（462KB）
└── arm/lib/
    └── libmongoose.a     # ARM 编译产物（471KB）
```

---

## 3. 编译配置

在 `myMongoose.h` 中定义以下宏（必须在 `#include "mongoose.h"` 之前）：

| 宏 | 值 | 说明 |
|------|-----|------|
| `MG_ENABLE_LOG` | 1 | 启用内置日志（printf 到 stderr） |
| `MG_ENABLE_FILE` | 0 | 禁用文件系统（RTU 不通过 mongoose 提供静态文件） |
| `MG_ENABLE_POSIX_FS` | 0 | 禁用 POSIX 文件 API |
| `MG_ENABLE_EPOLL` | 1 | 启用 epoll（Linux 高效 IO 多路复用） |
| `MG_ENABLE_POLL` | 1 | 启用 poll（epoll 回退方案） |
| `MG_ENABLE_SOCKET` | 1 | 使用 Linux 内核 socket |

---

## 4. 核心数据结构

### 4.1 mg_mgr — 事件管理器

```c
struct mg_mgr
{
    struct mg_connection *conns;  /* 活动连接链表 */
    struct mg_timer *timers;      /* 定时器链表 */
    // ... 内部字段
};
```

每个进程只需一个 `mg_mgr` 实例，管理所有连接和定时器。

### 4.2 mg_connection — 连接

```c
struct mg_connection
{
    struct mg_connection *next;   /* 链表指针 */
    struct mg_mgr *mgr;           /* 所属管理器 */
    struct mg_addr peer;          /* 对端地址 */
    void *fd;                     /* socket 文件描述符 */
    unsigned long id;             /* 连接 ID */
    unsigned is_websocket : 1;    /* 是否为 WebSocket 连接 */
    unsigned is_client : 1;       /* 是否为客户端连接 */
    // ...
};
```

### 4.3 事件类型

```c
enum
{
    MG_EV_ERROR,       /* 错误 */
    MG_EV_OPEN,        /* 连接建立（仅客户端出站连接） */
    MG_EV_POLL,        /* mg_mgr_poll() 每次迭代触发 */
    MG_EV_RESOLVE,     /* DNS 解析完成 */
    MG_EV_CONNECT,     /* TCP 连接完成 */
    MG_EV_ACCEPT,      /* TCP 新连接接受 */
    MG_EV_TLS_HS,      /* TLS 握手完成 */
    MG_EV_READ,        /* 数据可读 */
    MG_EV_WRITE,       /* 数据可写 */
    MG_EV_CLOSE,       /* 连接关闭 */
    MG_EV_HTTP_MSG,    /* HTTP 请求/响应解析完成 */
    MG_EV_HTTP_CHUNK,  /* HTTP 分块数据 */
    MG_EV_WS_OPEN,     /* WebSocket 握手完成 */
    MG_EV_WS_MSG,      /* WebSocket 消息到达 */
    MG_EV_WS_CTL,      /* WebSocket 控制帧 */
    MG_EV_MQTT_CMD,    /* MQTT 命令 */
    MG_EV_MQTT_MSG,    /* MQTT 消息 */
    MG_EV_MQTT_OPEN,   /* MQTT 连接建立 */
    MG_EV_SNTP_TIME,   /* SNTP 时间 */
    MG_EV_USER,        /* 用户自定义事件起点 */
};
```

---

## 5. 接口函数

### 5.1 生命周期

```c
/** 初始化事件管理器 */
void mg_mgr_init(struct mg_mgr *mgr);

/** 事件循环（每次调用处理一批事件，阻塞不超过 ms 毫秒） */
void mg_mgr_poll(struct mg_mgr *mgr, int ms);

/** 销毁事件管理器（关闭所有连接，释放所有内存） */
void mg_mgr_free(struct mg_mgr *mgr);
```

**典型用法**:
```c
struct mg_mgr mgr;

mg_mgr_init(&mgr);

/* 注册 HTTP/WS 监听 + 定时器 */
// ...

while (running)
{
    mg_mgr_poll(&mgr, 50);  /* 50ms 超时 */
}

mg_mgr_free(&mgr);
```

### 5.2 HTTP 服务器

```c
/** 创建 HTTP 监听连接 */
struct mg_connection *mg_http_listen(struct mg_mgr *mgr, const char *url,
                                     mg_event_handler_t fn, void *fn_data);

/** 获取 HTTP 请求/响应消息 */
int mg_http_get_request_len(const unsigned char *buf, size_t buf_len);
struct mg_http_message *mg_http_parse(const char *buf, size_t len);
struct mg_http_message *mg_http_parse2(const char *buf, size_t len);

/** 响应辅助 */
void mg_http_reply(struct mg_connection *c, int status_code,
                   const char *headers, const char *body_fmt, ...);
void mg_http_serve_dir(struct mg_connection *c, struct mg_http_message *hm,
                       const char *root);

/** 路由匹配 */
bool mg_match(struct mg_str str, struct mg_str pattern, struct mg_str *caps);
bool mg_http_match_uri(const struct mg_http_message *hm, const char *pattern);
```

**REST API 示例**:
```c
static void fn(struct mg_connection *c, int ev, void *ev_data)
{
    if (ev == MG_EV_HTTP_MSG)
    {
        struct mg_http_message *hm = (struct mg_http_message *)ev_data;

        if (mg_http_match_uri(hm, "/api/status"))
        {
            mg_http_reply(c, 200, "Content-Type: application/json\r\n",
                          "{\"status\":\"ok\"}");
        }
    }
}

mg_http_listen(&mgr, "http://0.0.0.0:8080", fn, NULL);
```

### 5.3 WebSocket

```c
/** 升级 HTTP 连接到 WebSocket */
void mg_ws_upgrade(struct mg_connection *c, struct mg_http_message *hm,
                   const char *fmt, ...);

/** 发送 WebSocket 消息 */
size_t mg_ws_send(struct mg_connection *c, const void *buf, size_t len, int op);

/** 格式化发送 WebSocket 消息 */
size_t mg_ws_printf(struct mg_connection *c, int op, const char *fmt, ...);

/** 封装非 WS socket 为 WS 帧（用于代理） */
size_t mg_ws_wrap(struct mg_connection *c, size_t len, int op,
                  const void *buf, size_t buf_len);

/** 主动连接 WebSocket 服务器（客户端模式） */
struct mg_connection *mg_ws_connect(struct mg_mgr *mgr, const char *url,
                                    mg_event_handler_t fn, void *fn_data,
                                    const char *fmt, ...);
```

**WebSocket 帧操作码 (op)**:
```c
#define WEBSOCKET_OP_CONTINUE  0   /* 继续帧 */
#define WEBSOCKET_OP_TEXT      1   /* 文本消息 */
#define WEBSOCKET_OP_BINARY    2   /* 二进制消息 */
#define WEBSOCKET_OP_CLOSE     8   /* 关闭握手 */
#define WEBSOCKET_OP_PING      9   /* Ping */
#define WEBSOCKET_OP_PONG      10  /* Pong */
```

**WebSocket 服务端示例**:
```c
static void fn(struct mg_connection *c, int ev, void *ev_data)
{
    if (ev == MG_EV_HTTP_MSG)
    {
        struct mg_http_message *hm = (struct mg_http_message *)ev_data;

        if (mg_match(hm->uri, mg_str("/ws"), NULL))
        {
            mg_ws_upgrade(c, hm, NULL);
        }
    }
    else if (ev == MG_EV_WS_MSG)
    {
        struct mg_ws_message *wm = (struct mg_ws_message *)ev_data;

        /* 回显消息 */
        mg_ws_send(c, wm->data.buf, wm->data.len, WEBSOCKET_OP_TEXT);
    }
}
```

### 5.4 定时器

```c
/** 添加一次性定时器 */
struct mg_timer *mg_timer_add(struct mg_mgr *mgr, uint64_t milliseconds,
                              unsigned flags, void (*fn)(void *), void *arg);

/** 定时器标志 */
#define MG_TIMER_REPEAT  1    /* 周期性定时器 */
#define MG_TIMER_RUN_NOW 2    /* 立即运行一次 */
```

### 5.5 通用收发

```c
/** 发送原始数据 */
bool mg_send(struct mg_connection *c, const void *buf, size_t len);

/** 格式化发送 */
size_t mg_printf(struct mg_connection *c, const char *fmt, ...);
size_t mg_vprintf(struct mg_connection *c, const char *fmt, va_list *ap);

/** 关闭连接 */
void mg_close_conn(struct mg_connection *c);
```

---

## 6. 使用约束与注意事项

### 6.1 线程安全
- `mg_mgr_poll()` 必须在**单线程**中调用
- 如需要多线程，通过 `mg_wakeup()` 向事件循环投递消息

### 6.2 内存管理
- 所有通过 `mg_http_listen()` 创建的连接在 `mg_mgr_free()` 时自动关闭释放
- `mg_http_message` 中的 `hm->body`、`hm->query` 等字段为协议栈内部缓冲区，**不可手动 free**

### 6.3 与 RTU 的集成方式
- `libweb_server` 作为 RTU 的独立线程模块，在线程内创建自己的 `mg_mgr`
- 通过 X-Macro 框架的定时器触发 `mg_mgr_poll()`
- HTTP 路由中使用 `dc_get_signal_val()` 获取实时数据，`dc_set_out_signal_val()` 发布前端写入的数据

### 6.4 日志说明
mongoose 内部使用 `printf` 向 stderr 输出日志（`MG_ENABLE_LOG=1`）。在 RTU 装置上 stderr 通常重定向到 `/dev/null` 或 syslog。如需捕获 mongoose 日志，可定义 `MG_ENABLE_CUSTOM_LOG=1` 并提供自定义 `MG_LOG()` 宏。

---

## 7. 依赖关系

### 7.1 本模块依赖
- **无**（mongoose 是纯 C、零依赖的单文件库，直接使用 Linux socket API）

### 7.2 依赖本模块的模块

| 模块 | 用途 |
|------|------|
| `libweb_server` (system/) | HTTP REST API + WebSocket 通信 |

### 7.3 模块依赖图

```
┌──────────────────┐
│ libweb_server    │ (RTU 线程模块)
│ REST API + WS    │
└────────┬─────────┘
         │ myMongoose.h
         ▼
┌──────────────────┐
│ libmongoose      │ (纯 C 协议栈)
│ HTTP + WebSocket │
└────────┬─────────┘
         │
         ▼
    Linux Socket API + epoll
```

---

## 8. 编译与构建

```bash
# 编译 libmongoose.a
cd release/src/protocol/libmongoose
make -f makefile all            # x86
make -f makefile CROSS=arm all  # ARM

# 参与全量构建
cd release && ./build.sh        # x86
cd release && ./build.sh arm    # ARM
```

---

## 9. 许可证

Mongoose 使用 **MIT 许可证**（商业友好）。完整许可文本见 `mongoose.h` 头部注释。

---

## 10. 参考链接

- [Mongoose 官方文档](https://mongoose.ws/documentation/)
- [Mongoose GitHub](https://github.com/cesanta/mongoose)
- [WebSocket RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455)
- [HTTP/1.1 RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230)