# Push Gateway 推送网关服务

> 版本：1.0（P5 仲裁回写）
> 端口：8081
> 关联：[02 架构设计](./docs/02-architecture-design.md)、[modules/push-gateway/README](../../docs/modules/push-gateway/README.md)

## 职责

实时推送基础设施服务（Go 实现），管理 WebSocket 长连接（仅 WebSocket，不支持 SSE — ISSUE-001）。
接收 msg 服务的推送请求（HTTP `/internal/*` + Kafka `edu.notification.requested`），维护用户在线连接池，
将消息实时投递到浏览器/移动端。无 DB（ISSUE-005），审计/落库由 msg 负责。

## 技术栈

- Go 1.25+ / Gin 1.12+
- gorilla/websocket 1.5（RFC 6455 控制帧心跳）
- segmentio/kafka-go 0.4（纯 Go，无 cgo）
- redis/go-redis/v9（在线 SET + Pub/Sub 跨实例 fanout）
- golang-jwt/jwt/v5 + shared-go/jwks（RS256 校验，5min 缓存）
- log/slog（结构化日志，JSON prod / text dev）
- prometheus/client_golang（9 个指标）
- shared-go（tracer/logger/env/jwks 复用 — ARB-015 §17.5）

## 开发

```bash
go mod tidy
go run main.go   # :8081

# DevMode（跳过内部鉴权，接受 dev-token）
DEV_MODE=true go run main.go

# 生产模式（需设置 JWT_SECRET + INTERNAL_API_TOKEN）
JWT_SECRET=xxx INTERNAL_API_TOKEN=yyy go run main.go
```

## API

| 方法 | 路径                        | 鉴权               | 说明                                             |
| ---- | --------------------------- | ------------------ | ------------------------------------------------ |
| GET  | `/ws?token=JWT`             | JWT RS256          | WebSocket 升级（亦支持 `Authorization: Bearer`） |
| POST | `/internal/push`            | `X-Internal-Token` | 定向推送（msg 服务调用）                         |
| POST | `/internal/broadcast`       | `X-Internal-Token` | 广播                                             |
| GET  | `/internal/online/<userID>` | `X-Internal-Token` | 查在线状态                                       |
| GET  | `/healthz`                  | 无                 | liveness 探针                                    |
| GET  | `/readyz`                   | 无                 | readiness 探针（软失败 — ISSUE-058）             |
| GET  | `/metrics`                  | 无                 | Prometheus 指标                                  |

## 环境变量

| 变量                          | 默认值                                         | 说明                                     |
| ----------------------------- | ---------------------------------------------- | ---------------------------------------- |
| `PUSH_GATEWAY_PORT`           | 8081                                           | HTTP 监听端口                            |
| `DEV_MODE`                    | false                                          | 开发模式（跳过内部鉴权，接受 dev-token） |
| `JWT_SECRET`                  | （DevMode 有默认）                             | JWT 密钥（生产必填）                     |
| `JWKS_URL`                    | `http://localhost:50052/.well-known/jwks.json` | iam JWKS 端点                            |
| `INTERNAL_API_TOKEN`          | （生产必填）                                   | `/internal/*` 鉴权 token（ISSUE-002）    |
| `REDIS_URL`                   | `redis://localhost:6379/0`                     | Redis 连接 URL                           |
| `KAFKA_BROKERS`               | `localhost:9092`                               | Kafka broker 列表（逗号分隔）            |
| `KAFKA_NOTIFICATION_TOPIC`    | `edu.notification.requested`                   | 消费 topic（ISSUE-053）                  |
| `KAFKA_CONSUMER_GROUP`        | `push-gateway`                                 | consumer group                           |
| `WS_ALLOWED_ORIGINS`          | （空）                                         | WebSocket Origin 白名单（逗号分隔）      |
| `MAX_CONNS_PER_USER`          | 5                                              | 单用户最大连接数                         |
| `HEARTBEAT_INTERVAL_SECONDS`  | 30                                             | 心跳间隔                                 |
| `INSTANCE_ID`                 | （hostname）                                   | 实例标识（Redis SET 成员）               |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4318`                               | OTLP 端点                                |

## WebSocket 心跳（RFC 6455 控制帧）

- 客户端每 30s 发送 WebSocket **Ping 控制帧**（非文本消息）
- 服务端自动回 Pong（gorilla/websocket 默认行为）
- 服务端 `SetReadDeadline(60s)`：60s 未收到任何帧则断开
- 每次 Pong 刷新 Redis 在线 SET 的 TTL（60s）

## 内部包结构

```
internal/
├─ config/           # 环境变量配置（shared-go/env）
├─ hub/              # 连接池（userID -> connID -> Connection）
├─ ws/               # WebSocket 升级 + /internal/* HTTP API
├─ redisclient/      # Redis Pub/Sub + 在线 SET（ISSUE-058 启动重建）
├─ kafkaconsumer/    # Kafka 消费（edu.notification.requested）
├─ observability/    # slog logger + OTel tracer + Prometheus metrics
└─ health/           # /healthz + /readyz（软失败）
```

## 优雅关闭顺序

1. 收到 SIGTERM → 标记 Hub `closing`（拒绝新连接，`/readyz` 返 503）
2. `Hub.CloseAll()`：向所有在线连接发送 close 帧（code=1001 going away）
3. `srv.Shutdown(10s)`：停止 HTTP 服务，drain 在途请求
4. Kafka consumer cancel + reader.Close
5. Redis Pub/Sub cancel + client.Close
6. Tracer shutdown（flush span）

## 关键设计决策

- **软失败**（ISSUE-058/006）：Redis/Kafka 故障时 `/readyz` 返 200 + `degraded:true`，不断本地 WebSocket
- **Redis SET 启动重建**（ISSUE-058）：启动时 SREM 旧 instanceID，基于内存重建
- **无 gRPC**（ISSUE-007）：仅 HTTP + WebSocket
- **shared-go 复用**（ARB-015 §17.5）：tracer/logger/env/jwks 不重复实现

完整 ADR 见 [02 架构设计 §14](./docs/02-architecture-design.md#14-架构决策记录adr)。