# imks — IM 实时消息服务

基于 **Engine.IO + Socket.IO** 协议的即时通讯（IM）实时消息服务，支持 WebSocket、WebTransport、HTTP Long-Polling 多种传输层，通过 gRPC 与 [appks](https://github.com/your-org/appks) 核心服务集成，提供认证、权限、消息持久化和跨节点广播。

## 架构

```
Client (Browser/App)
    │  Socket.IO over WebSocket / WebTransport / Polling
    ▼
┌─────────────────────────────────────┐
│              imks                    │
│                                     │
│  engine/     socket/                │
│  • WS/WT/      • Socket.IO Server   │
│    Polling     • Namespace/Room     │
│  • Session     • Adapter (Redis/NATS)│
│  • Heartbeat   • Message Bus        │
│                                     │
│  models/      repo/       svc/      │
│  • 20+ 消息     • SQL CRUD   • 业务    │
│    领域模型      • 分页查询    逻辑层   │
│                                     │
│  auth/        rpc/                  │
│  • JWT 双模    • gRPC Stubs         │
│    验证        • Token/Channel/     │
│  • 密钥缓存      Member/Permission  │
└──────────────┬──────────────────────┘
               │ gRPC (mTLS)
               ▼
┌─────────────────────────────────────┐
│              appks (core)           │
│  Token  │ Channel │ Member │ ...    │
│  Postgres • Redis • NATS            │
└─────────────────────────────────────┘
```

## 快速开始

### 前置依赖

- **Rust** 1.85+ (edition 2024)
- **PostgreSQL** 16+ (消息持久化)
- **appks** gRPC 服务 (认证 & 权限)
- **Redis** (可选, 多节点广播)
- **NATS** (可选, 低延迟多节点广播)

### 安装 & 运行

```bash
# 克隆仓库
git clone https://github.com/your-org/imks.git
cd imks

# 配置环境变量
cp .env.example .env
# 编辑 .env，至少设置 DATABASE_URL 和 APPKS_GRPC_ADDR

# 数据库迁移（自动执行）
# 首次启动会自动运行 migrate/ 下的 SQL 迁移

# 编译
cargo build --release

# 运行
cargo run --release
# 默认监听 http://0.0.0.0:3000
```

### 端点

| 端点 | 说明 |
|---|---|
| `GET /engine.io/` | Engine.IO 握手 & WebSocket 升级 |
| `POST /engine.io/` | Engine.IO HTTP Long-Polling |
| `GET /health` | 健康检查（含连接数、会话数、依赖检查） |
| `GET /metrics` | Prometheus 格式指标 |

### 健康检查示例

```json
{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-06-11T10:00:00Z",
  "uptime_secs": 3600,
  "connections_active": 42,
  "sessions_count": 42,
  "checks": {
    "postgres": { "status": "up", "latency_ms": 3 },
    "redis": { "status": "up", "latency_ms": 1 }
  }
}
```

## 环境变量

完整列表见 [`.env.example`](./.env.example)。

### 核心配置

| 变量 | 默认值 | 说明 |
|---|---|---|
| `IMKS_ADAPTER` | `local` | `local` \| `redis` \| `nats` |
| `DATABASE_URL` | `postgres://localhost/imks` | PostgreSQL 连接串 |
| `APPKS_GRPC_ADDR` | `http://localhost:50051` | appks gRPC 地址 |

## 开发

```bash
cargo check          # 快速检查语法
cargo test           # 运行所有测试（111 个）
cargo test --lib     # 仅库测试（91 个）
cargo clippy         # Lint 检查
cargo fmt            # 格式化
```

## 文档

- [AGENTS.md](./AGENTS.md) — 开发规范
- [rpc.md](docs/rpc.md) — 认证方案 & Proto 契约
- [migrate/](./migrate/) — 数据库迁移脚本

## 许可证

[待定]