vixcpp/middleware
GitHub: vixcpp/middleware
为 Vix.cpp HTTP 运行时提供可组合、非阻塞的现代化中间件系统，内置认证、安全加固、速率限制和缓存等生产级预设。
Stars: 0 | Forks: 0
# Vix 中间件
高性能 • 非阻塞 • 可组合 • 面向生产
Vix **middleware** 模块为 **Vix.cpp HTTP runtime** 提供了一个现代化、人性化的中间件系统。
它专为实际应用设计：安全加固、解析、认证、请求范围状态以及安全组合。
该模块支持**两种中间件风格**：
* **基于上下文的中间件** (`MiddlewareFn`) —— 推荐
* **传统 HTTP 中间件** (`HttpMiddleware`) —— 通过适配器支持
它还内置了**开箱即用的预设**（CORS、速率限制、CSRF、安全标头、IP 过滤、解析器、认证、HTTP 缓存）。
## 为什么要有这个模块
大多数 C++ “中间件”系统要么：
* 过于依赖特定框架
* 难以组合
* 容易意外阻塞
* 对安全性不明确（提前返回、状态变更、可观察行为）
Vix middleware 旨在做到：
* **显式**：每个中间件都决定是继续 (`next()`) 还是停止
* **可组合**：清晰地链接中间件
* **安全**：防御性解析、可预测的提前返回、没有隐藏的魔法
* **快速**：尽可能零成本抽象，默认采用非阻塞模式
## 快速开始
运行完整的“mega 示例”：
```
vix run examples/http_middleware/mega_middleware_routes.cpp
```
快速测试：
```
curl -i http://127.0.0.1:8080/
curl -i http://127.0.0.1:8080/api/ping -H "x-demo: 1"
curl -i http://127.0.0.1:8080/api/secure/whoami -H "x-api-key: dev_key_123"
curl -i http://127.0.0.1:8080/dev/trace
curl -i http://127.0.0.1:8080/api/cache/demo
curl -i http://127.0.0.1:8080/api/cache/demo -H "x-vix-cache: bypass"
```
## 最小示例
### 1) 一个简单的基于上下文的中间件
```
#include
#include
static vix::middleware::MiddlewareFn hello_mw()
{
return [](vix::middleware::Context& ctx, vix::middleware::Next next) {
ctx.res().header("x-hello", "vix");
next();
};
}
int main()
{
vix::App app;
// Adapt ctx middleware into an App middleware
app.use(vix::middleware::app::adapt_ctx(hello_mw()));
app.get("/", [](auto&, auto& res) {
res.send("ok");
});
app.run(8080);
}
```
### 2) 一个传统风格的中间件（仍然支持）
```
#include
#include
static vix::middleware::HttpMiddleware require_header(std::string key)
{
return [key = std::move(key)](vix::Request& req, vix::Response& res, vix::middleware::Next next) {
if (req.header(key).empty()) {
res.status(401).send("missing header");
return; // do not call next()
}
next();
};
}
int main()
{
vix::App app;
// Adapt legacy middleware into an App middleware
app.use(vix::middleware::app::adapt(require_header("x-demo")));
app.get("/", [](auto&, auto& res) {
res.send("ok");
});
app.run(8080);
}
```
## 核心概念
### 1) 基于上下文的中间件（推荐）
`MiddlewareFn` 如下所示：
```
(vix::middleware::Context& ctx, vix::middleware::Next next) -> void
```
规则：
* 要继续流水线，请调用 `next()`。
* 要提前停止，**不要**调用 `next()`。
* 您可以修改请求/响应并存储请求范围的状态。
### 2) RequestState（跨中间件和处理程序存储数据）
Vix 提供了基于类型的请求存储（类似于 `std::any`）。
```
struct AuthInfo { bool authed{}; std::string role; };
ctx.req().emplace_state(AuthInfo{true, "admin"});
if (ctx.req().has_state_type()) {
const auto& a = ctx.req().state();
}
```
用于：
* 将计算数据传递给处理程序
* 保存认证/会话信息
* 跟踪时间/追踪 ID
* 附加解析结果
### 3) 安装模式
应用适配器层提供安装助手：
* `app.use(mw)` —— 全局
* `install(app, "/prefix/", mw)` —— 前缀中间件
* `install_exact(app, "/path", mw)` —— 精确路径中间件
* `chain(mw1, mw2, ...)` —— 组合中间件
这就是您构建安全且可读的路由保护的方式：
```
using namespace vix::middleware::app;
install(app, "/api/", rate_limit_dev(120, std::chrono::minutes(1)));
install(app, "/api/secure/", api_key_dev("dev_key_123"));
install(app, "/api/admin/", chain(adapt_ctx(fake_auth()), adapt_ctx(require_admin())));
```
## 包含的预设
该模块包含满足常见需求的“电池内置”中间件预设。
名称可能根据您的代码树结构略有不同，但示例演示了：
### 安全
* CORS（开发/可配置）
* 安全标头
* CSRF（可选）
* IP 过滤
### 速率限制
* 简单的内存开发限制器（适用于本地、演示、CI）
### 认证
* API 密钥
* JWT（启用时）
* 类 RBAC 门控模式
### 解析器
* JSON 解析器
* 表单解析器
* Multipart 解析器
* Multipart 保存（安全地将上传内容写入磁盘）
### HTTP 缓存（GET 缓存）
用于 GET 端点的缓存中间件，带有显式绕过控制：
* 基于 TTL 的缓存
* 可选绕过标头（例如 `x-vix-cache: bypass`）
* 调试标头（例如 `x-vix-cache-status: hit/miss/bypass`）
## 完整参考示例
推荐的起点是：
* `examples/http_middleware/mega_middleware_routes.cpp`
它演示了：
* 路由（GET/POST 等）
* 全局中间件 (`App::use`)
* 前缀中间件 (`install`)
* 精确路径中间件 (`install_exact`)
* `adapt_ctx()` 和 `adapt()`
* 中间件链 (`chain`)
* 安全预设（CORS、标头、CSRF、IP 过滤）
* 速率限制
* 解析器（JSON、表单、multipart）
* 认证（API 密钥、角色门控）
* HTTP 缓存（GET）
* RequestState 模式
* 提前返回模式和防御性 JSON 响应
## 目录布局
典型布局：
```
modules/middleware/
│
├─ include/vix/middleware/
│ ├─ app/
│ │ ├─ adapter.hpp # adapt_ctx(), adapt(), install(), chain(), ...
│ │ ├─ presets.hpp # cors_dev(), rate_limit_dev(), api_key_dev(), ...
│ │ └─ http_cache.hpp # install_http_cache() + config
│ ├─ Context.hpp
│ ├─ Middleware.hpp
│ └─ ...
│
└─ examples/
└─ http_middleware/
└─ mega_middleware_routes.cpp
```
## 设计理念
* **仅控制平面**：中间件显式决定流程。
* **无隐藏阻塞**：处理程序保持简短；繁重的工作应被调度。
* **防御性解析**：无效输入产生可预测的错误。
* **可观察行为**：追踪 ID、调试标头、显式缓存绕过。
* **默认可组合**：链式和前缀安装构建可读的安全性。
## 许可证
MIT —— 与 Vix.cpp 相同
仓库：[https://github.com/vixcpp/vix](https://github.com/vixcpp/vix)
标签：C++, CISA项目, CORS跨域, CSRF防护, ETW劫持, HTTP服务器, HTTP缓存, IP过滤, PE 加载器, Syscall, Vix.cpp, Web开发, Web框架组件, 上下文管理, 中间件, 可组合性, 后端开发, 安全头, 数据压缩, 数据擦除, 日志记录, 生产环境, 网络安全, 请求处理, 错误处理, 限流, 隐私保护, 零成本抽象, 非阻塞IO