# Rust 后端

这是多租户直播组件服务的可复用核心和唯一运行时进程。`src/main.rs` 只处理进程启动；主要行为由 library
crate 导出。

## 模块职责

| 模块          | 职责                                                     |
| ------------- | -------------------------------------------------------- |
| `app`         | 依赖组装、迁移、事件队列、源启动与旧配置导入             |
| `auth`        | 邀请码、TOTP、恢复码、会话、secret 加密和组件 token      |
| `components`  | 组件定义、设置版本、订阅、projection 与 handler registry |
| `config`      | TOML 解析、部署策略校验和旧单用户兼容字段                |
| `credentials` | CookieCloud URL 边界与 Bilibili Cookie 提取              |
| `db`          | PostgreSQL pool、迁移和 RLS tenant context               |
| `domain`      | provider-independent event 与 WebSocket envelope         |
| `http_api`    | REST/WS、会话、权限、same-origin、静态资源与安全响应头   |
| `live`        | provider trait、Bilibili adapter 与 source supervisor    |
| `overlay`     | 弹幕姬设置及礼物/表情目录                                |
| `rate_limit`  | 匿名登录和 enrollment 滥用限制                           |
| `realtime`    | source event routing 与 component-scoped fanout          |
| `repository`  | PostgreSQL component facade 和热路径缓存同步             |

## 重要不变量

- handler 不能信任请求体中的 owner；owner 必须来自 session 或 source context。
- tenant table 查询必须在 `Db::set_tenant` 后的事务中执行。
- provider 只能输出 canonical、bounded、sanitized `LiveEvent`。
- projection 无副作用；可靠业务动作必须使用幂等 handler。
- token、邀请码和恢复码只存摘要，TOTP/CookieCloud Secret 只存认证加密密文。
- EventHub 的 channel key 是 component ID，不允许增加无权限的全局 receiver。

## 本地质量检查

在仓库根目录执行：

```bash
cargo fmt --manifest-path apps/server-rust/Cargo.toml --check
cargo clippy --manifest-path apps/server-rust/Cargo.toml --all-targets --no-deps -- -D warnings
cargo test --manifest-path apps/server-rust/Cargo.toml --all-targets
```

第三方 `vendor/blivedm` 不作为本项目风格重写目标；项目只维护保留原始 JSON 所需的小补丁。

更多设计说明：

- [总体架构](../../docs/architecture.md)
- [组件开发](../../docs/components/README.md)
- [实时协议](../../docs/protocol.md)
- [安全模型](../../docs/security.md)