feat: 补齐模块接口契约与管理 API 文档
This commit is contained in:
Nixevol
+17
-1
@@ -29,7 +29,7 @@ func cmdServe(_ []string) error {
|
|||||||
}
|
}
|
||||||
|
|
||||||
func runServe(ctx context.Context, cfg config.Config) error {
|
func runServe(ctx context.Context, cfg config.Config) error {
|
||||||
wire()
|
deps := wire()
|
||||||
|
|
||||||
if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
|
if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
|
||||||
return fmt.Errorf("mkdir data_dir: %w", err)
|
return fmt.Errorf("mkdir data_dir: %w", err)
|
||||||
@@ -41,6 +41,22 @@ func runServe(ctx context.Context, cfg config.Config) error {
|
|||||||
}
|
}
|
||||||
defer func() { _ = db.Close() }()
|
defer func() { _ = db.Close() }()
|
||||||
|
|
||||||
|
// 启动恢复入口已挂上（假实现为空操作）；M 线替换 message.Service 后生效。
|
||||||
|
if recoverErr := deps.Messages.RecoverOnStart(ctx); recoverErr != nil {
|
||||||
|
return fmt.Errorf("message recover: %w", recoverErr)
|
||||||
|
}
|
||||||
|
// 其余 deps 供后续 admin / broker / httpx 接线；此处显式引用避免未使用告警。
|
||||||
|
_ = deps.Identity
|
||||||
|
_ = deps.Groups
|
||||||
|
_ = deps.Presence
|
||||||
|
_ = deps.Downlink
|
||||||
|
_ = deps.Conns
|
||||||
|
_ = deps.Uplink
|
||||||
|
_ = deps.HashPool
|
||||||
|
_ = deps.SessionTokens
|
||||||
|
_ = deps.APITokens
|
||||||
|
_ = deps.LoginLocks
|
||||||
|
|
||||||
mux := http.NewServeMux()
|
mux := http.NewServeMux()
|
||||||
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
|
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
|
||||||
w.WriteHeader(http.StatusOK)
|
w.WriteHeader(http.StatusOK)
|
||||||
|
|||||||
+44
-2
@@ -1,4 +1,46 @@
|
|||||||
package main
|
package main
|
||||||
|
|
||||||
// wire 组装各业务模块。T0.1 仅占位，T0.4 起由各线注册。
|
import (
|
||||||
func wire() {}
|
"git.asio.asia/nixevol/NixMsg/internal/app/group"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/identity"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/message"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/presence"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/auth"
|
||||||
|
)
|
||||||
|
|
||||||
|
// appDeps 是 serve 组装出的模块依赖。各线在后续任务中替换假实现为真实实现。
|
||||||
|
type appDeps struct {
|
||||||
|
HashPool auth.HashPool
|
||||||
|
SessionTokens auth.SessionTokens
|
||||||
|
APITokens auth.APITokens
|
||||||
|
LoginLocks auth.LoginLocks
|
||||||
|
|
||||||
|
Messages message.Service
|
||||||
|
Identity identity.Service
|
||||||
|
Groups group.Service
|
||||||
|
Presence presence.Service
|
||||||
|
|
||||||
|
Uplink port.UplinkHandler
|
||||||
|
Downlink port.Downlink
|
||||||
|
Conns port.ConnControl
|
||||||
|
}
|
||||||
|
|
||||||
|
// wire 组装各业务模块的骨架依赖（T0.4：假实现；后续各线替换）。
|
||||||
|
func wire() appDeps {
|
||||||
|
return appDeps{
|
||||||
|
HashPool: auth.NewStubHashPool(),
|
||||||
|
SessionTokens: auth.NewStubSessionTokens(),
|
||||||
|
APITokens: auth.NewStubAPITokens(),
|
||||||
|
LoginLocks: auth.NewStubLoginLocks(),
|
||||||
|
|
||||||
|
Messages: message.NewStub(),
|
||||||
|
Identity: identity.NewStub(),
|
||||||
|
Groups: group.NewStub(),
|
||||||
|
Presence: presence.NewStub(),
|
||||||
|
|
||||||
|
Uplink: port.StubUplinkHandler{},
|
||||||
|
Downlink: &port.StubDownlink{},
|
||||||
|
Conns: &port.StubConnControl{},
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -0,0 +1,16 @@
|
|||||||
|
package main
|
||||||
|
|
||||||
|
import "testing"
|
||||||
|
|
||||||
|
func TestWireAssemblesStubs(t *testing.T) {
|
||||||
|
d := wire()
|
||||||
|
if d.HashPool == nil || d.SessionTokens == nil || d.APITokens == nil || d.LoginLocks == nil {
|
||||||
|
t.Fatal("auth deps missing")
|
||||||
|
}
|
||||||
|
if d.Messages == nil || d.Identity == nil || d.Groups == nil || d.Presence == nil {
|
||||||
|
t.Fatal("app deps missing")
|
||||||
|
}
|
||||||
|
if d.Uplink == nil || d.Downlink == nil || d.Conns == nil {
|
||||||
|
t.Fatal("port deps missing")
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -119,6 +119,36 @@
|
|||||||
- 备选方案：Unix 发 SIGTERM；Windows 用 Job Object / Ctrl+Break。
|
- 备选方案：Unix 发 SIGTERM；Windows 用 Job Object / Ctrl+Break。
|
||||||
- 影响：不覆盖优雅停机验收；该验收仍归 P1/Q。
|
- 影响：不覆盖优雅停机验收；该验收仍归 P1/Q。
|
||||||
|
|
||||||
|
### T0.4 2026-09-30
|
||||||
|
|
||||||
|
1. **broker↔app 契约包放在 `internal/app/port`**
|
||||||
|
- 原条款：TASKS T0.4「broker 和 app 之间的接口」；示例路径 `internal/app/port` 或 `internal/broker/port`。
|
||||||
|
- 实际做法：放在 `internal/app/port`：`UplinkHandler`（broker→app）、`Downlink` / `ConnControl`（app→broker）。不依赖 mochi。
|
||||||
|
- 原因：契约由 app 消费形态主导，避免 broker 包在 N 线实现前成为空壳；N 线实现 broker 时 import 本包即可。
|
||||||
|
- 备选方案：放在 `internal/broker/port` 或单独 `internal/port`。
|
||||||
|
- 影响：N/M/I 依赖路径固定为 `internal/app/port`。
|
||||||
|
|
||||||
|
2. **接口方法先返回未实现或空操作，不做业务状态机**
|
||||||
|
- 原条款：T0.4 要求 Go 接口与测试假实现；不要实现真正业务逻辑。
|
||||||
|
- 实际做法：`auth` / `message` / `identity` / `group` 的写路径假实现返回 `ErrNotImplemented`；调度/推送/清理/在线查询等返回空成功或固定假数据；`wire()` 组装这些假实现，`serve` 仅调用 `RecoverOnStart`（空操作）并保留依赖引用。
|
||||||
|
- 原因：让后续各线有可编译的替换点，且不抢 P/N/M/I/A 实现范围。
|
||||||
|
- 备选方案：接口方法全部 panic；或完全不接线 serve。
|
||||||
|
- 影响：在假实现替换前，端协议与管理 API 仍不可用（本任务预期）。
|
||||||
|
|
||||||
|
3. **管理契约补充 `GET /api/admin/groups/{id}`**
|
||||||
|
- 原条款：DEVELOPMENT 第 8 节路由表列出 groups 的 GET/POST 列表创建与 PATCH/DELETE，未单列群详情。
|
||||||
|
- 实际做法：`docs/api/admin-api.md` 增加 `GET /api/admin/groups/{id}`（成员分页），供后台详情页使用。
|
||||||
|
- 原因：改名/解散/成员管理需要详情；与端协议 `group.get` 对称。
|
||||||
|
- 备选方案：详情拼进列表项或仅用 PATCH 回显。
|
||||||
|
- 影响：A/W 按契约实现该只读路由。
|
||||||
|
|
||||||
|
4. **CSV 导入校验失败时用信封外的 `data.errors`**
|
||||||
|
- 原条款：写明返回出错行号和原因；未规定 JSON 形状。
|
||||||
|
- 实际做法：HTTP 400，`ok=false`，`error.code=bad_request`，同行号列表放在顶层 `data.errors`。
|
||||||
|
- 原因：通用 `error` 只有 code/message，放不下多行明细。
|
||||||
|
- 备选方案：把明细塞进 `error.message` 字符串。
|
||||||
|
- 影响：W 线按 `data.errors` 渲染。
|
||||||
|
|
||||||
|
|
||||||
## 平台 P
|
## 平台 P
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,733 @@
|
|||||||
|
# 管理接口契约（Admin API）
|
||||||
|
|
||||||
|
| 项 | 内容 |
|
||||||
|
|---|---|
|
||||||
|
| 版本 | 0.1（T0.4 契约） |
|
||||||
|
| 对应 | [DEVELOPMENT.md](../DEVELOPMENT.md) 第 8 节、[PRD.md](../PRD.md) F17 |
|
||||||
|
| 读者 | 后台接口 A、后台网页 W、集成测试 |
|
||||||
|
|
||||||
|
本文约定管理后台 HTTP 接口的方法、路径、请求字段、成功响应、分页与错误格式。W 线可先按本文用假数据开发；A 线实现时响应字段名与语义须与本文一致。
|
||||||
|
|
||||||
|
**硬性规则**
|
||||||
|
|
||||||
|
- 所有 JSON 响应在序列化前去掉消息正文；响应中不得出现 `body` 字段（含嵌套）。
|
||||||
|
- 管理接口不开跨域。
|
||||||
|
- 时间字段为 Unix 毫秒（整数），JSON 字段名蛇形。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 鉴权与通用约定
|
||||||
|
|
||||||
|
### 1.1 Cookie 会话（网页登录）
|
||||||
|
|
||||||
|
| 项 | 值 |
|
||||||
|
|---|---|
|
||||||
|
| Cookie 名 | `nixmsg_admin` |
|
||||||
|
| 属性 | `HttpOnly`；`SameSite=Lax`；经 HTTPS（含受信任代理认定的 HTTPS）时加 `Secure` |
|
||||||
|
| 服务端 | 只存令牌哈希；默认有效 12 小时 |
|
||||||
|
|
||||||
|
改变状态的请求（POST / PATCH / PUT / DELETE）在使用 Cookie 鉴权时，必须带请求头：
|
||||||
|
|
||||||
|
```http
|
||||||
|
X-Nixmsg-Request: 1
|
||||||
|
```
|
||||||
|
|
||||||
|
缺少该头返回 **403**（防跨站表单）。`GET` 不要求此头。
|
||||||
|
|
||||||
|
### 1.2 API 令牌（程序调用）
|
||||||
|
|
||||||
|
```http
|
||||||
|
Authorization: Bearer nxm_...
|
||||||
|
```
|
||||||
|
|
||||||
|
- 带 Bearer 令牌时**不看** Cookie，也**不要求** `X-Nixmsg-Request`。
|
||||||
|
- 权限等同管理员，但不能调用：
|
||||||
|
- `POST /api/admin/password`
|
||||||
|
- `/api/admin/tokens` 及其子路径
|
||||||
|
- 令牌不过期；停用或删除后立即失效。
|
||||||
|
- 错误令牌按来源 IP 计入管理员登录锁定。
|
||||||
|
|
||||||
|
### 1.3 通用响应信封
|
||||||
|
|
||||||
|
成功（业务成功）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"ok": true, "data": { }}
|
||||||
|
```
|
||||||
|
|
||||||
|
失败：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"ok": false, "error": {"code": "unauthorized", "message": "未登录"}}
|
||||||
|
```
|
||||||
|
|
||||||
|
| HTTP | 常见 code | 说明 |
|
||||||
|
|---|---|---|
|
||||||
|
| 400 | `bad_request` | 字段不合法 |
|
||||||
|
| 401 | `unauthorized` | 未登录、密码错误、令牌无效 |
|
||||||
|
| 403 | `forbidden` | 缺 `X-Nixmsg-Request`、令牌无权访问该路由、已锁定等 |
|
||||||
|
| 404 | `not_found` | 资源不存在 |
|
||||||
|
| 409 | `id_taken` / `conflict` | 编号占用等 |
|
||||||
|
| 429 | `rate_limited` | 登录/令牌试错锁定 |
|
||||||
|
| 500 | `internal` | 服务器错误 |
|
||||||
|
| 503 | `busy` | 暂时不可用，可重试 |
|
||||||
|
|
||||||
|
列表类成功时 `data` 形如：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"items": [ ],
|
||||||
|
"next_cursor": "",
|
||||||
|
"total": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `next_cursor` 为空表示没有下一页。
|
||||||
|
- `total` 为符合筛选条件的总数（可选实现；契约要求有该字段，假数据可给 `items.length`）。
|
||||||
|
- 默认 `limit` 为 50，最大 200（除非单接口另有说明）。
|
||||||
|
|
||||||
|
### 1.4 操作日志
|
||||||
|
|
||||||
|
每个改变状态的请求写结构化日志：操作者（`admin` 或 `token:<名称>`）、动作、对象编号、结果、来源 IP。不写密码、令牌和正文。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 认证与账号
|
||||||
|
|
||||||
|
### 2.1 登录
|
||||||
|
|
||||||
|
`POST /api/admin/login`
|
||||||
|
|
||||||
|
不需要已登录。不要求 `X-Nixmsg-Request`。
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"username": "admin", "password": "..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `username` 固定为 `admin`。
|
||||||
|
- 成功时设置 Cookie `nixmsg_admin`。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"username": "admin"}
|
||||||
|
```
|
||||||
|
|
||||||
|
失败：密码错误 `401 unauthorized`；锁定 `429 rate_limited`。
|
||||||
|
|
||||||
|
### 2.2 登出
|
||||||
|
|
||||||
|
`POST /api/admin/logout`
|
||||||
|
|
||||||
|
作废当前会话 Cookie。成功 `data` 可为 `{}`。
|
||||||
|
|
||||||
|
### 2.3 当前管理员
|
||||||
|
|
||||||
|
`GET /api/admin/me`
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"username": "admin", "auth": "cookie"}
|
||||||
|
```
|
||||||
|
|
||||||
|
`auth` 为 `cookie` 或 `token`（API 令牌访问时）。
|
||||||
|
|
||||||
|
### 2.4 修改管理员密码
|
||||||
|
|
||||||
|
`POST /api/admin/password`
|
||||||
|
|
||||||
|
**仅 Cookie 会话**；API 令牌调用返回 `403 forbidden`。
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"old_password": "...", "new_password": "..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 新密码至少 12 位。
|
||||||
|
- 成功后可选择保持当前会话或全部作废（实现默认：当前会话保留，其它会话作废）。成功 `data`：`{}`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 概览
|
||||||
|
|
||||||
|
`GET /api/admin/overview`
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": "0.1.0",
|
||||||
|
"endpoints_total": 0,
|
||||||
|
"endpoints_online": 0,
|
||||||
|
"endpoints_disabled": 0,
|
||||||
|
"groups_total": 0,
|
||||||
|
"messages_pending": 0,
|
||||||
|
"messages_scheduled": 0,
|
||||||
|
"uptime_ms": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
不含正文、不含端编号明细。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 端（endpoints）
|
||||||
|
|
||||||
|
### 4.1 列表
|
||||||
|
|
||||||
|
`GET /api/admin/endpoints`
|
||||||
|
|
||||||
|
查询参数：
|
||||||
|
|
||||||
|
| 参数 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| `cursor` | 分页游标 |
|
||||||
|
| `limit` | 默认 50，最大 200 |
|
||||||
|
| `source` | 可选：`admin` / `self` |
|
||||||
|
| `online` | 可选：`true` / `false` |
|
||||||
|
| `enabled` | 可选：`true` / `false` |
|
||||||
|
| `query` | 可选：编号前缀或名称包含，不区分大小写 |
|
||||||
|
|
||||||
|
成功 `data.items[]`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "device-1",
|
||||||
|
"name": "门口",
|
||||||
|
"remark": "",
|
||||||
|
"source": "admin",
|
||||||
|
"enabled": true,
|
||||||
|
"online": false,
|
||||||
|
"online_since_ms": null,
|
||||||
|
"offline_since_ms": 1750000000000,
|
||||||
|
"talk_password_set": false,
|
||||||
|
"default_delay_ms": 0,
|
||||||
|
"created_at_ms": 1750000000000,
|
||||||
|
"login_locked": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
无密码、无正文。
|
||||||
|
|
||||||
|
### 4.2 开通
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints`
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "",
|
||||||
|
"name": "门口",
|
||||||
|
"remark": "",
|
||||||
|
"login_password": "",
|
||||||
|
"talk_password": "",
|
||||||
|
"default_delay_seconds": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
字段规则同 PRD F01（编号小写、密码不以 `nst_` 开头等）。`id` / `login_password` 留空则服务器生成。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "e_ab12cd34",
|
||||||
|
"login_password": "只在本次生成时返回"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
冲突：`409 id_taken`。
|
||||||
|
|
||||||
|
### 4.3 批量开通（CSV）
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints/import`
|
||||||
|
|
||||||
|
- `Content-Type: text/csv` 或 `multipart/form-data`（字段名 `file`）。
|
||||||
|
- UTF-8，可带 BOM。
|
||||||
|
- 表头：`id,name,login_password,talk_password,default_delay_seconds,remark`
|
||||||
|
- 最多 1000 行。先整体校验，任一行出错则一行都不建。
|
||||||
|
|
||||||
|
校验失败（HTTP 400）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"ok": false,
|
||||||
|
"error": {"code": "bad_request", "message": "CSV 校验失败"},
|
||||||
|
"data": {
|
||||||
|
"errors": [{"line": 3, "reason": "编号不合法"}]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
（实现可将 `errors` 放在 `error` 旁的 `data`；W 线按 `data.errors` 读取。）
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"items": [
|
||||||
|
{"id": "e_1", "login_password": "生成或原文（仅此一次）", "name": "..."}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 多选批量
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints/batch`
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"ids": ["a", "b"], "action": "disable"}
|
||||||
|
```
|
||||||
|
|
||||||
|
`action`：`disable` | `enable` | `delete`。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"ok_ids": ["a"], "failed": [{"id": "b", "code": "not_found"}]}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.5 详情
|
||||||
|
|
||||||
|
`GET /api/admin/endpoints/{id}`
|
||||||
|
|
||||||
|
成功 `data` 同列表项，可额外含：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"session_issued_at_ms": null, "session_used_at_ms": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
仍无密码哈希与正文。
|
||||||
|
|
||||||
|
### 4.6 修改
|
||||||
|
|
||||||
|
`PATCH /api/admin/endpoints/{id}`
|
||||||
|
|
||||||
|
请求（皆可选）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "新名",
|
||||||
|
"remark": "",
|
||||||
|
"default_delay_seconds": 0,
|
||||||
|
"enabled": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
成功 `data` 为更新后的详情（同 4.5）。
|
||||||
|
|
||||||
|
### 4.7 删除
|
||||||
|
|
||||||
|
`DELETE /api/admin/endpoints/{id}`
|
||||||
|
|
||||||
|
成功 `data`：`{}`。级联行为见 PRD F01 / DEVELOPMENT 7.6。
|
||||||
|
|
||||||
|
### 4.8 踢下线
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints/{id}/kick`
|
||||||
|
|
||||||
|
只断开当前连接，不阻止令牌重连。成功 `data`：`{"kicked": true}`（当时不在线可为 `false`）。
|
||||||
|
|
||||||
|
### 4.9 重置登录密码
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints/{id}/reset-login-password`
|
||||||
|
|
||||||
|
请求体可空 `{}`，或 `{"login_password": ""}`（留空则生成）。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"login_password": "只出现一次"}
|
||||||
|
```
|
||||||
|
|
||||||
|
会话令牌作废；在线连接收到 `fatal`（`password_reset`）后断开。
|
||||||
|
|
||||||
|
### 4.10 设置对话密码
|
||||||
|
|
||||||
|
`PUT /api/admin/endpoints/{id}/talk-password`
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"talk_password": ""}
|
||||||
|
```
|
||||||
|
|
||||||
|
空字符串表示清除。增加对话密码版本号，旧授权失效。成功 `data`：`{"talk_password_set": false}`。
|
||||||
|
|
||||||
|
### 4.11 解除登录锁定
|
||||||
|
|
||||||
|
`POST /api/admin/endpoints/{id}/unlock`
|
||||||
|
|
||||||
|
清除该编号的两种登录锁定。成功 `data`：`{}`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 注册设置
|
||||||
|
|
||||||
|
### 5.1 获取
|
||||||
|
|
||||||
|
`GET /api/admin/registration`
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"enabled": false,
|
||||||
|
"code": "明文安全码（后台可查看）",
|
||||||
|
"updated_at_ms": 1750000000000
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 更新
|
||||||
|
|
||||||
|
`PUT /api/admin/registration`
|
||||||
|
|
||||||
|
请求（字段皆可选，至少一项）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"enabled": true, "code": "新码", "generate": false}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `generate: true` 时服务器生成 16 位安全码并忽略请求里的 `code`。
|
||||||
|
- 成功 `data` 同 GET。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. API 令牌
|
||||||
|
|
||||||
|
以下路由**仅 Cookie 会话**；Bearer 调用返回 `403 forbidden`。
|
||||||
|
|
||||||
|
### 6.1 列表
|
||||||
|
|
||||||
|
`GET /api/admin/tokens`
|
||||||
|
|
||||||
|
成功 `data.items[]`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"name": "ops",
|
||||||
|
"enabled": true,
|
||||||
|
"created_at_ms": 1750000000000,
|
||||||
|
"last_used_at_ms": null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
不含令牌明文。
|
||||||
|
|
||||||
|
### 6.2 创建
|
||||||
|
|
||||||
|
`POST /api/admin/tokens`
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"name": "ops"}
|
||||||
|
```
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"name": "ops",
|
||||||
|
"token": "nxm_只出现一次",
|
||||||
|
"created_at_ms": 1750000000000
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.3 修改
|
||||||
|
|
||||||
|
`PATCH /api/admin/tokens/{id}`
|
||||||
|
|
||||||
|
请求（可选字段）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"name": "new", "enabled": false}
|
||||||
|
```
|
||||||
|
|
||||||
|
成功 `data` 同列表项。
|
||||||
|
|
||||||
|
### 6.4 删除
|
||||||
|
|
||||||
|
`DELETE /api/admin/tokens/{id}`
|
||||||
|
|
||||||
|
成功 `data`：`{}`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 群（groups）
|
||||||
|
|
||||||
|
### 7.1 列表
|
||||||
|
|
||||||
|
`GET /api/admin/groups`
|
||||||
|
|
||||||
|
查询：`cursor`、`limit`、`query`（名称包含）。
|
||||||
|
|
||||||
|
成功 `data.items[]`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "g_ab12cd34",
|
||||||
|
"name": "一组",
|
||||||
|
"owner_id": "a",
|
||||||
|
"member_count": 3,
|
||||||
|
"created_at_ms": 1750000000000
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.2 创建
|
||||||
|
|
||||||
|
`POST /api/admin/groups`
|
||||||
|
|
||||||
|
请求：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "",
|
||||||
|
"name": "一组",
|
||||||
|
"owner_id": "a",
|
||||||
|
"member_ids": ["b", "c"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
后台**不要求**对话密码。`id` 留空则生成。部分成员失败时群仍创建，响应列出失败项。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "g_ab12cd34",
|
||||||
|
"name": "一组",
|
||||||
|
"owner_id": "a",
|
||||||
|
"failed": [{"id": "c", "code": "not_found"}]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7.3 改名
|
||||||
|
|
||||||
|
`PATCH /api/admin/groups/{id}`
|
||||||
|
|
||||||
|
请求：`{"name": "新名"}`。成功 `data` 为群摘要（同列表项）。
|
||||||
|
|
||||||
|
### 7.4 解散
|
||||||
|
|
||||||
|
`DELETE /api/admin/groups/{id}`
|
||||||
|
|
||||||
|
成功 `data`：`{}`。
|
||||||
|
|
||||||
|
### 7.5 加人
|
||||||
|
|
||||||
|
`POST /api/admin/groups/{id}/members`
|
||||||
|
|
||||||
|
请求：`{"member_ids": ["d"]}`。
|
||||||
|
|
||||||
|
成功 `data`：`{"failed": []}`（结构同创建时的 `failed`）。
|
||||||
|
|
||||||
|
### 7.6 移除成员
|
||||||
|
|
||||||
|
`DELETE /api/admin/groups/{id}/members/{endpointId}`
|
||||||
|
|
||||||
|
成功 `data`：`{}`。
|
||||||
|
|
||||||
|
### 7.7 转让群主
|
||||||
|
|
||||||
|
`POST /api/admin/groups/{id}/transfer`
|
||||||
|
|
||||||
|
请求：`{"endpoint_id": "b"}`。成功 `data`：`{"owner_id": "b"}`。
|
||||||
|
|
||||||
|
### 7.8 群详情（成员分页）
|
||||||
|
|
||||||
|
契约补充：`GET /api/admin/groups/{id}`（DEVELOPMENT 路由表未单列，但列表改名/解散需要详情；W 线可用）
|
||||||
|
|
||||||
|
查询：`cursor`、`limit`。
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "g_ab12cd34",
|
||||||
|
"name": "一组",
|
||||||
|
"owner_id": "a",
|
||||||
|
"created_at_ms": 1750000000000,
|
||||||
|
"members": [
|
||||||
|
{"id": "a", "name": "", "online": true, "joined_at_ms": 1750000000000}
|
||||||
|
],
|
||||||
|
"next_cursor": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. 消息记录（messages）
|
||||||
|
|
||||||
|
响应**不得**含正文或 `body` 字段。
|
||||||
|
|
||||||
|
### 8.1 列表
|
||||||
|
|
||||||
|
`GET /api/admin/messages`
|
||||||
|
|
||||||
|
查询参数（PRD F17）：
|
||||||
|
|
||||||
|
| 参数 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| `cursor` / `limit` | 分页 |
|
||||||
|
| `sender_id` | 发送方 |
|
||||||
|
| `endpoint_id` | 接收端（投递表） |
|
||||||
|
| `group_id` | 目标群 |
|
||||||
|
| `state` | 消息级状态：`scheduled` / `dispatched` / `completed` |
|
||||||
|
| `from_ms` / `to_ms` | 按 `created_at` 时间范围 |
|
||||||
|
|
||||||
|
成功 `data.items[]`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"seq": 1,
|
||||||
|
"id": "018f...",
|
||||||
|
"sender_id": "a",
|
||||||
|
"dest_kind": "endpoint",
|
||||||
|
"dest_id": "b",
|
||||||
|
"state": "completed",
|
||||||
|
"reason": "",
|
||||||
|
"send_at_ms": 1750000010000,
|
||||||
|
"created_at_ms": 1750000000000,
|
||||||
|
"keep": false,
|
||||||
|
"receipt": true,
|
||||||
|
"content_type": "text/plain",
|
||||||
|
"delivery_counts": {
|
||||||
|
"pending": 0,
|
||||||
|
"accepted": 1,
|
||||||
|
"recalled": 0,
|
||||||
|
"expired": 0,
|
||||||
|
"dropped": 0,
|
||||||
|
"rejected": 0
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8.2 详情（各接收端）
|
||||||
|
|
||||||
|
`GET /api/admin/messages/{seq}`
|
||||||
|
|
||||||
|
成功 `data`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"seq": 1,
|
||||||
|
"id": "018f...",
|
||||||
|
"sender_id": "a",
|
||||||
|
"dest_kind": "group",
|
||||||
|
"dest_id": "g_1",
|
||||||
|
"state": "dispatched",
|
||||||
|
"reason": "",
|
||||||
|
"send_at_ms": 1750000010000,
|
||||||
|
"created_at_ms": 1750000000000,
|
||||||
|
"meta": {},
|
||||||
|
"content_type": "text/plain",
|
||||||
|
"deliveries": [
|
||||||
|
{
|
||||||
|
"endpoint_id": "b",
|
||||||
|
"state": "pending",
|
||||||
|
"reason": "",
|
||||||
|
"attempts": 1,
|
||||||
|
"pushed_at_ms": 1750000010100,
|
||||||
|
"updated_at_ms": 1750000010100
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"next_cursor": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`deliveries` 可分页（`cursor` / `limit` 查询参数）。无正文。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. 只读运行参数
|
||||||
|
|
||||||
|
`GET /api/admin/settings`
|
||||||
|
|
||||||
|
成功 `data`（只读，对应配置与生效值；不含密钥）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"listen": ":7443",
|
||||||
|
"admin_listen": "",
|
||||||
|
"session_idle_days": 30,
|
||||||
|
"record_retention_days": 7,
|
||||||
|
"idempotency_hours": 24,
|
||||||
|
"receipt_retention_days": 7,
|
||||||
|
"sqlite_synchronous": "FULL",
|
||||||
|
"limits": {
|
||||||
|
"max_body_bytes": 262144,
|
||||||
|
"max_meta_bytes": 4096,
|
||||||
|
"max_frame_bytes": 786432,
|
||||||
|
"max_ttl_seconds": 2592000,
|
||||||
|
"max_schedule_seconds": 31536000,
|
||||||
|
"max_group_members": 1000,
|
||||||
|
"grace_seconds": 60,
|
||||||
|
"ack_timeout_seconds": 300,
|
||||||
|
"delivery_window": 32,
|
||||||
|
"receipt_window": 64,
|
||||||
|
"requests_per_second": 50,
|
||||||
|
"max_pending_per_sender": 10000,
|
||||||
|
"max_pending_per_receiver": 10000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. 路由速查
|
||||||
|
|
||||||
|
| 方法 | 路径 | Cookie 可变 | Bearer | 节 |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| POST | `/api/admin/login` | — | — | 2.1 |
|
||||||
|
| POST | `/api/admin/logout` | 要 | 可 | 2.2 |
|
||||||
|
| GET | `/api/admin/me` | — | 可 | 2.3 |
|
||||||
|
| POST | `/api/admin/password` | 要 | **否** | 2.4 |
|
||||||
|
| GET | `/api/admin/overview` | — | 可 | 3 |
|
||||||
|
| GET | `/api/admin/endpoints` | — | 可 | 4.1 |
|
||||||
|
| POST | `/api/admin/endpoints` | 要 | 可 | 4.2 |
|
||||||
|
| POST | `/api/admin/endpoints/import` | 要 | 可 | 4.3 |
|
||||||
|
| POST | `/api/admin/endpoints/batch` | 要 | 可 | 4.4 |
|
||||||
|
| GET | `/api/admin/endpoints/{id}` | — | 可 | 4.5 |
|
||||||
|
| PATCH | `/api/admin/endpoints/{id}` | 要 | 可 | 4.6 |
|
||||||
|
| DELETE | `/api/admin/endpoints/{id}` | 要 | 可 | 4.7 |
|
||||||
|
| POST | `/api/admin/endpoints/{id}/kick` | 要 | 可 | 4.8 |
|
||||||
|
| POST | `/api/admin/endpoints/{id}/reset-login-password` | 要 | 可 | 4.9 |
|
||||||
|
| PUT | `/api/admin/endpoints/{id}/talk-password` | 要 | 可 | 4.10 |
|
||||||
|
| POST | `/api/admin/endpoints/{id}/unlock` | 要 | 可 | 4.11 |
|
||||||
|
| GET | `/api/admin/registration` | — | 可 | 5.1 |
|
||||||
|
| PUT | `/api/admin/registration` | 要 | 可 | 5.2 |
|
||||||
|
| GET | `/api/admin/tokens` | — | **否** | 6.1 |
|
||||||
|
| POST | `/api/admin/tokens` | 要 | **否** | 6.2 |
|
||||||
|
| PATCH | `/api/admin/tokens/{id}` | 要 | **否** | 6.3 |
|
||||||
|
| DELETE | `/api/admin/tokens/{id}` | 要 | **否** | 6.4 |
|
||||||
|
| GET | `/api/admin/groups` | — | 可 | 7.1 |
|
||||||
|
| POST | `/api/admin/groups` | 要 | 可 | 7.2 |
|
||||||
|
| GET | `/api/admin/groups/{id}` | — | 可 | 7.8 |
|
||||||
|
| PATCH | `/api/admin/groups/{id}` | 要 | 可 | 7.3 |
|
||||||
|
| DELETE | `/api/admin/groups/{id}` | 要 | 可 | 7.4 |
|
||||||
|
| POST | `/api/admin/groups/{id}/members` | 要 | 可 | 7.5 |
|
||||||
|
| DELETE | `/api/admin/groups/{id}/members/{endpointId}` | 要 | 可 | 7.6 |
|
||||||
|
| POST | `/api/admin/groups/{id}/transfer` | 要 | 可 | 7.7 |
|
||||||
|
| GET | `/api/admin/messages` | — | 可 | 8.1 |
|
||||||
|
| GET | `/api/admin/messages/{seq}` | — | 可 | 8.2 |
|
||||||
|
| GET | `/api/admin/settings` | — | 可 | 9 |
|
||||||
|
|
||||||
|
「Cookie 可变」列：改变状态且走 Cookie 时必须带 `X-Nixmsg-Request: 1`。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. 假数据开发提示（W 线）
|
||||||
|
|
||||||
|
- 可用静态 JSON 或 MSW；列表返回 2～3 条样例即可。
|
||||||
|
- 重置密码 / 创建令牌 / 开通生成密码的响应只展示一次，刷新后不再出现明文。
|
||||||
|
- 任意管理接口响应用测试断言：序列化字符串中不出现 `"body"` 键。
|
||||||
@@ -0,0 +1,73 @@
|
|||||||
|
// Package group 定义 DEVELOPMENT 第 6.7 节群操作的接口。
|
||||||
|
package group
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ErrNotImplemented 表示假实现未提供业务能力。
|
||||||
|
var ErrNotImplemented = errors.New("group: not implemented")
|
||||||
|
|
||||||
|
// MemberFail 是建群/加人时部分失败的项。
|
||||||
|
type MemberFail struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Code string `json:"code"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// CreateResult 是建群结果。
|
||||||
|
type CreateResult struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
OwnerID string `json:"owner_id"`
|
||||||
|
Failed []MemberFail `json:"failed,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// AddResult 是加人结果。
|
||||||
|
type AddResult struct {
|
||||||
|
Failed []MemberFail `json:"failed,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// ListItem 是 group.list 一项。
|
||||||
|
type ListItem struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
OwnerID string `json:"owner_id"`
|
||||||
|
MemberCount int `json:"member_count"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// MemberItem 是 group.get 成员项。
|
||||||
|
type MemberItem struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
Online bool `json:"online"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// GetResult 是群详情。
|
||||||
|
type GetResult struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
OwnerID string `json:"owner_id"`
|
||||||
|
Members []MemberItem `json:"members"`
|
||||||
|
NextCursor string `json:"next_cursor,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// Service 是群子系统契约（第 6.7 节）。
|
||||||
|
type Service interface {
|
||||||
|
Create(ctx context.Context, actorID string, req *protocol.GroupCreate) (CreateResult, error)
|
||||||
|
Add(ctx context.Context, actorID string, req *protocol.GroupAdd) (AddResult, error)
|
||||||
|
Remove(ctx context.Context, actorID string, req *protocol.GroupRemove) error
|
||||||
|
Leave(ctx context.Context, actorID string, req *protocol.GroupLeave) error
|
||||||
|
Transfer(ctx context.Context, actorID string, req *protocol.GroupTransfer) error
|
||||||
|
Rename(ctx context.Context, actorID string, req *protocol.GroupRename) error
|
||||||
|
Dissolve(ctx context.Context, actorID string, req *protocol.GroupDissolve) error
|
||||||
|
List(ctx context.Context, actorID string, req *protocol.GroupList) (items []ListItem, nextCursor string, err error)
|
||||||
|
Get(ctx context.Context, actorID string, req *protocol.GroupGet) (GetResult, error)
|
||||||
|
|
||||||
|
// AdminCreate 后台建群（不要求对话密码）。
|
||||||
|
AdminCreate(ctx context.Context, name string, ownerID string, memberIDs []string) (CreateResult, error)
|
||||||
|
// AdminAddMembers 后台加人。
|
||||||
|
AdminAddMembers(ctx context.Context, groupID string, memberIDs []string) (AddResult, error)
|
||||||
|
}
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
package group
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubCreateNotImplemented(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
_, err := s.Create(context.Background(), "a", &protocol.GroupCreate{Name: "g"})
|
||||||
|
if !errors.Is(err, ErrNotImplemented) {
|
||||||
|
t.Fatalf("got %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubListEmpty(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
items, cursor, err := s.List(context.Background(), "a", &protocol.GroupList{})
|
||||||
|
if err != nil || len(items) != 0 || cursor != "" {
|
||||||
|
t.Fatalf("items=%v cursor=%q err=%v", items, cursor, err)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,58 @@
|
|||||||
|
package group
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Stub 是测试用假实现。
|
||||||
|
type Stub struct{}
|
||||||
|
|
||||||
|
func NewStub() *Stub { return &Stub{} }
|
||||||
|
|
||||||
|
func (s *Stub) Create(context.Context, string, *protocol.GroupCreate) (CreateResult, error) {
|
||||||
|
return CreateResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Add(context.Context, string, *protocol.GroupAdd) (AddResult, error) {
|
||||||
|
return AddResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Remove(context.Context, string, *protocol.GroupRemove) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Leave(context.Context, string, *protocol.GroupLeave) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Transfer(context.Context, string, *protocol.GroupTransfer) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Rename(context.Context, string, *protocol.GroupRename) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Dissolve(context.Context, string, *protocol.GroupDissolve) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) List(context.Context, string, *protocol.GroupList) ([]ListItem, string, error) {
|
||||||
|
return nil, "", nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Get(context.Context, string, *protocol.GroupGet) (GetResult, error) {
|
||||||
|
return GetResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) AdminCreate(context.Context, string, string, []string) (CreateResult, error) {
|
||||||
|
return CreateResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) AdminAddMembers(context.Context, string, []string) (AddResult, error) {
|
||||||
|
return AddResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
var _ Service = (*Stub)(nil)
|
||||||
@@ -0,0 +1,63 @@
|
|||||||
|
// Package identity 定义注册、self.*、对话密码授权、停用与删除级联的接口。
|
||||||
|
package identity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ErrNotImplemented 表示假实现未提供业务能力。
|
||||||
|
var ErrNotImplemented = errors.New("identity: not implemented")
|
||||||
|
|
||||||
|
// RegisterRequest 对应 POST /api/client/register 与后台开通的公共字段。
|
||||||
|
type RegisterRequest struct {
|
||||||
|
RegistrationCode string
|
||||||
|
ID string
|
||||||
|
LoginPassword string
|
||||||
|
Name string
|
||||||
|
TalkPassword string
|
||||||
|
Remark string
|
||||||
|
DefaultDelayMs int64
|
||||||
|
Source string // admin | self
|
||||||
|
RemoteIP string
|
||||||
|
}
|
||||||
|
|
||||||
|
// RegisterResult 是注册/开通结果。
|
||||||
|
type RegisterResult struct {
|
||||||
|
ID string
|
||||||
|
LoginPassword string // 仅当请求留空由服务器生成时非空
|
||||||
|
}
|
||||||
|
|
||||||
|
// SelfInfo 是 self.get 返回。
|
||||||
|
type SelfInfo struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
DefaultDelayMs int64 `json:"default_delay_ms"`
|
||||||
|
TalkPasswordSet bool `json:"talk_password_set"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// Service 是身份子系统契约。
|
||||||
|
type Service interface {
|
||||||
|
// Register 处理自助注册或供管理开通复用（第 6.9 节）。
|
||||||
|
Register(ctx context.Context, req RegisterRequest) (RegisterResult, error)
|
||||||
|
|
||||||
|
SelfGet(ctx context.Context, endpointID string) (SelfInfo, error)
|
||||||
|
SelfUpdate(ctx context.Context, endpointID string, req *protocol.SelfUpdate) error
|
||||||
|
SelfSetTalkPassword(ctx context.Context, endpointID string, talkPassword string) error
|
||||||
|
SelfChangeLoginPassword(ctx context.Context, endpointID string, oldPassword, newPassword string) (sessionToken string, err error)
|
||||||
|
SelfLogout(ctx context.Context, endpointID string) error
|
||||||
|
|
||||||
|
// UnlockTalk 校验并写入对话密码授权（第 6.6 节 unlock）。
|
||||||
|
UnlockTalk(ctx context.Context, senderID, targetID, talkPassword string) error
|
||||||
|
// HasTalkGrant 查询发送方对目标是否有有效授权。
|
||||||
|
HasTalkGrant(ctx context.Context, senderID, targetID string) (bool, error)
|
||||||
|
|
||||||
|
// Disable 停用端并作废相关消息/令牌（第 7.6 节）。
|
||||||
|
Disable(ctx context.Context, endpointID string) error
|
||||||
|
// Enable 重新启用。
|
||||||
|
Enable(ctx context.Context, endpointID string) error
|
||||||
|
// Delete 删除端并做级联清理。
|
||||||
|
Delete(ctx context.Context, endpointID string) error
|
||||||
|
}
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
package identity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubRegisterNotImplemented(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
_, err := s.Register(context.Background(), RegisterRequest{Source: "self"})
|
||||||
|
if !errors.Is(err, ErrNotImplemented) {
|
||||||
|
t.Fatalf("got %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubHasTalkGrantFalse(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
ok, err := s.HasTalkGrant(context.Background(), "a", "b")
|
||||||
|
if err != nil || ok {
|
||||||
|
t.Fatalf("ok=%v err=%v", ok, err)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,48 @@
|
|||||||
|
package identity
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Stub 是测试用假实现。
|
||||||
|
type Stub struct{}
|
||||||
|
|
||||||
|
func NewStub() *Stub { return &Stub{} }
|
||||||
|
|
||||||
|
func (s *Stub) Register(context.Context, RegisterRequest) (RegisterResult, error) {
|
||||||
|
return RegisterResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) SelfGet(context.Context, string) (SelfInfo, error) {
|
||||||
|
return SelfInfo{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) SelfUpdate(context.Context, string, *protocol.SelfUpdate) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) SelfSetTalkPassword(context.Context, string, string) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) SelfChangeLoginPassword(context.Context, string, string, string) (string, error) {
|
||||||
|
return "", ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) SelfLogout(context.Context, string) error { return ErrNotImplemented }
|
||||||
|
|
||||||
|
func (s *Stub) UnlockTalk(context.Context, string, string, string) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) HasTalkGrant(context.Context, string, string) (bool, error) {
|
||||||
|
return false, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Disable(context.Context, string) error { return ErrNotImplemented }
|
||||||
|
func (s *Stub) Enable(context.Context, string) error { return ErrNotImplemented }
|
||||||
|
func (s *Stub) Delete(context.Context, string) error { return ErrNotImplemented }
|
||||||
|
|
||||||
|
var _ Service = (*Stub)(nil)
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
// Package message 定义消息提交、分发、推送、确认、撤回、回执、清理与启动恢复的接口。
|
||||||
|
package message
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ErrNotImplemented 表示假实现未提供业务能力。
|
||||||
|
var ErrNotImplemented = errors.New("message: not implemented")
|
||||||
|
|
||||||
|
// SubmitResult 是发送提交的结果（对应 send 的 resp data）。
|
||||||
|
type SubmitResult struct {
|
||||||
|
ID string
|
||||||
|
SendAtMs int64
|
||||||
|
State string // scheduled | dispatched | ...
|
||||||
|
}
|
||||||
|
|
||||||
|
// AckResult 是确认结果。
|
||||||
|
type AckResult struct {
|
||||||
|
Result string // accepted | recalled | expired | dropped | rejected 等最终态
|
||||||
|
}
|
||||||
|
|
||||||
|
// Service 是消息子系统对外契约。方法签名供 M 线实现；T0.4 不写状态机。
|
||||||
|
type Service interface {
|
||||||
|
// Submit 处理端发送请求（第 7.3 节）。
|
||||||
|
Submit(ctx context.Context, senderID string, conn port.ConnInfo, req *protocol.Send) (SubmitResult, error)
|
||||||
|
// Ack 处理确认（第 7.6 节）。
|
||||||
|
Ack(ctx context.Context, endpointID string, req *protocol.Ack) (AckResult, error)
|
||||||
|
// Recall 处理撤回。
|
||||||
|
Recall(ctx context.Context, senderID string, req *protocol.Recall) (protocol.RecallData, error)
|
||||||
|
// Status 查询自己发出的消息状态。
|
||||||
|
Status(ctx context.Context, senderID string, req *protocol.Status) (any, error)
|
||||||
|
// ReceiptAck 确认回执已收下。
|
||||||
|
ReceiptAck(ctx context.Context, endpointID string, req *protocol.ReceiptAck) error
|
||||||
|
|
||||||
|
// DispatchDue 分发已到点的 scheduled 消息（第 7.4 节）；由调度循环调用。
|
||||||
|
DispatchDue(ctx context.Context, nowMs int64, limit int) (dispatched int, err error)
|
||||||
|
// PushPending 向已握手连接推送 pending 投递与回执（第 7.5 节）。
|
||||||
|
PushPending(ctx context.Context, endpointID string, connID port.ConnID) error
|
||||||
|
// OnPublishDropped 下行未写入发送队列时，清推送标记并安排重推。
|
||||||
|
OnPublishDropped(ctx context.Context, endpointID string, connID port.ConnID, payload []byte) error
|
||||||
|
|
||||||
|
// CleanupOnce 执行一轮过期投递与记录清理（第 7.5 / 7.6 节）。
|
||||||
|
CleanupOnce(ctx context.Context, nowMs int64) error
|
||||||
|
// RecoverOnStart 启动恢复：清残留 pushed_conn、宽限、补发定时等（第 7.8 节）。
|
||||||
|
RecoverOnStart(ctx context.Context) error
|
||||||
|
|
||||||
|
// WakePush 唤醒某端推送循环（提交/分发后由内部或其它模块调用）。
|
||||||
|
WakePush(endpointID string)
|
||||||
|
}
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
package message
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubSubmitNotImplemented(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
_, err := s.Submit(context.Background(), "a", port.ConnInfo{}, &protocol.Send{})
|
||||||
|
if !errors.Is(err, ErrNotImplemented) {
|
||||||
|
t.Fatalf("got %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubRecoverNoop(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
if err := s.RecoverOnStart(context.Background()); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
package message
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Stub 是测试用假实现：方法返回 ErrNotImplemented 或固定空结果。
|
||||||
|
type Stub struct{}
|
||||||
|
|
||||||
|
func NewStub() *Stub { return &Stub{} }
|
||||||
|
|
||||||
|
func (s *Stub) Submit(context.Context, string, port.ConnInfo, *protocol.Send) (SubmitResult, error) {
|
||||||
|
return SubmitResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Ack(context.Context, string, *protocol.Ack) (AckResult, error) {
|
||||||
|
return AckResult{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Recall(context.Context, string, *protocol.Recall) (protocol.RecallData, error) {
|
||||||
|
return protocol.RecallData{}, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Status(context.Context, string, *protocol.Status) (any, error) {
|
||||||
|
return nil, ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) ReceiptAck(context.Context, string, *protocol.ReceiptAck) error {
|
||||||
|
return ErrNotImplemented
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) DispatchDue(context.Context, int64, int) (int, error) {
|
||||||
|
return 0, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) PushPending(context.Context, string, port.ConnID) error {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) OnPublishDropped(context.Context, string, port.ConnID, []byte) error {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) CleanupOnce(context.Context, int64) error { return nil }
|
||||||
|
|
||||||
|
func (s *Stub) RecoverOnStart(context.Context) error { return nil }
|
||||||
|
|
||||||
|
func (s *Stub) WakePush(string) {}
|
||||||
|
|
||||||
|
var _ Service = (*Stub)(nil)
|
||||||
@@ -0,0 +1,81 @@
|
|||||||
|
// Package port 定义 broker 与 app 之间的契约。
|
||||||
|
//
|
||||||
|
// broker（连接 N）实现 Downlink / ConnControl；app 各模块通过这些接口下行发布或踢线。
|
||||||
|
// broker 在连接生命周期与上行帧到达时调用 UplinkHandler。
|
||||||
|
// 本包不依赖 mochi，也不包含业务状态机。
|
||||||
|
package port
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ConnID 是连接代号（同一端编号新旧连接 ClientID 相同，用独立代号区分）。
|
||||||
|
type ConnID string
|
||||||
|
|
||||||
|
// Transport 区分接入方式。
|
||||||
|
type Transport string
|
||||||
|
|
||||||
|
const (
|
||||||
|
TransportTCP Transport = "tcp"
|
||||||
|
TransportWS Transport = "ws"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ConnInfo 描述一条已建立的 MQTT 连接（登录校验通过之后）。
|
||||||
|
type ConnInfo struct {
|
||||||
|
ConnID ConnID
|
||||||
|
EndpointID string
|
||||||
|
Transport Transport
|
||||||
|
RemoteIP string
|
||||||
|
// SessionToken 非空表示本次用密码登录后新签发的令牌（握手响应里交给端）。
|
||||||
|
SessionToken string
|
||||||
|
// MaxPacketSize 来自 CONNECT；0 表示未声明。
|
||||||
|
MaxPacketSize uint32
|
||||||
|
}
|
||||||
|
|
||||||
|
// HandshakeInfo 是握手完成时的补充信息。
|
||||||
|
type HandshakeInfo struct {
|
||||||
|
ConnInfo
|
||||||
|
MaxReceiveBytes int // 0 表示不限（仍受 MaxPacketSize 约束）
|
||||||
|
Client string
|
||||||
|
}
|
||||||
|
|
||||||
|
// DisconnectReason 说明断开原因，便于 app 区分当前连接与被顶号的旧连接。
|
||||||
|
type DisconnectReason string
|
||||||
|
|
||||||
|
const (
|
||||||
|
DisconnectNormal DisconnectReason = "normal"
|
||||||
|
DisconnectTakenOver DisconnectReason = "taken_over"
|
||||||
|
DisconnectKicked DisconnectReason = "kicked"
|
||||||
|
DisconnectFatal DisconnectReason = "fatal"
|
||||||
|
DisconnectIdle DisconnectReason = "idle"
|
||||||
|
)
|
||||||
|
|
||||||
|
// UplinkHandler 由 app 实现，broker 在钩子里调用。
|
||||||
|
type UplinkHandler interface {
|
||||||
|
// OnSessionEstablished 在 MQTT 会话建立、登录已通过后调用（握手前）。
|
||||||
|
OnSessionEstablished(ctx context.Context, conn ConnInfo) error
|
||||||
|
// OnHandshakeComplete 在 hello 成功处理后调用；此后该连接算在线并可推送。
|
||||||
|
OnHandshakeComplete(ctx context.Context, hs HandshakeInfo) error
|
||||||
|
// OnDisconnect 在连接断开时调用；是否为当前连接由 app 按 ConnID 判断。
|
||||||
|
OnDisconnect(ctx context.Context, conn ConnInfo, reason DisconnectReason)
|
||||||
|
// HandleUplink 处理上行应用帧原始 JSON（已从 MQTT 发布拷贝）。
|
||||||
|
HandleUplink(ctx context.Context, conn ConnInfo, payload []byte) error
|
||||||
|
}
|
||||||
|
|
||||||
|
// PublishOpts 控制下行发布。
|
||||||
|
type PublishOpts struct {
|
||||||
|
QoS byte // 0 或 1；msg/receipt/revoked/resp/fatal 用 1，presence/group_event 用 0
|
||||||
|
}
|
||||||
|
|
||||||
|
// Downlink 由 broker 实现，供 app 向下行主题发布。
|
||||||
|
type Downlink interface {
|
||||||
|
// PublishDown 向 nix/c/{endpointID}/down 发布一帧。
|
||||||
|
// connID 非空时仅在该连接仍是当前连接时发布；空表示发给该端当前连接。
|
||||||
|
PublishDown(ctx context.Context, endpointID string, connID ConnID, payload []byte, opts PublishOpts) error
|
||||||
|
}
|
||||||
|
|
||||||
|
// ConnControl 由 broker 实现，供 app/admin 踢线或发 fatal 后断开。
|
||||||
|
type ConnControl interface {
|
||||||
|
// Disconnect 断开指定连接；connID 为空则断开该端当前连接。
|
||||||
|
Disconnect(ctx context.Context, endpointID string, connID ConnID, reason DisconnectReason) error
|
||||||
|
}
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
package port
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubDownlinkPublish(t *testing.T) {
|
||||||
|
d := &StubDownlink{}
|
||||||
|
if err := d.PublishDown(context.Background(), "a", "c1", []byte(`{}`), PublishOpts{QoS: 1}); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if d.Published != 1 {
|
||||||
|
t.Fatalf("published=%d", d.Published)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubUplinkHandlerCompile(t *testing.T) {
|
||||||
|
var h UplinkHandler = StubUplinkHandler{}
|
||||||
|
if err := h.OnSessionEstablished(context.Background(), ConnInfo{EndpointID: "a"}); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,40 @@
|
|||||||
|
package port
|
||||||
|
|
||||||
|
import "context"
|
||||||
|
|
||||||
|
// StubDownlink 吞掉所有下行发布。
|
||||||
|
type StubDownlink struct {
|
||||||
|
Published int
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubDownlink) PublishDown(_ context.Context, _ string, _ ConnID, _ []byte, _ PublishOpts) error {
|
||||||
|
s.Published++
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// StubConnControl 记录断开请求。
|
||||||
|
type StubConnControl struct {
|
||||||
|
Calls []string
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubConnControl) Disconnect(_ context.Context, endpointID string, _ ConnID, _ DisconnectReason) error {
|
||||||
|
s.Calls = append(s.Calls, endpointID)
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
// StubUplinkHandler 空实现，供 broker 接线测试。
|
||||||
|
type StubUplinkHandler struct{}
|
||||||
|
|
||||||
|
func (StubUplinkHandler) OnSessionEstablished(context.Context, ConnInfo) error { return nil }
|
||||||
|
|
||||||
|
func (StubUplinkHandler) OnHandshakeComplete(context.Context, HandshakeInfo) error { return nil }
|
||||||
|
|
||||||
|
func (StubUplinkHandler) OnDisconnect(context.Context, ConnInfo, DisconnectReason) {}
|
||||||
|
|
||||||
|
func (StubUplinkHandler) HandleUplink(context.Context, ConnInfo, []byte) error { return nil }
|
||||||
|
|
||||||
|
var (
|
||||||
|
_ Downlink = (*StubDownlink)(nil)
|
||||||
|
_ ConnControl = (*StubConnControl)(nil)
|
||||||
|
_ UplinkHandler = StubUplinkHandler{}
|
||||||
|
)
|
||||||
@@ -0,0 +1,53 @@
|
|||||||
|
// Package presence 定义在线查询、目录与上下线订阅的接口。
|
||||||
|
package presence
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ErrNotImplemented 表示假实现未提供业务能力。
|
||||||
|
var ErrNotImplemented = errors.New("presence: not implemented")
|
||||||
|
|
||||||
|
// StatusItem 是 presence.get 单项。
|
||||||
|
type StatusItem struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Online bool `json:"online"`
|
||||||
|
SinceMs int64 `json:"since_ms"`
|
||||||
|
// NotFound 为 true 时该项对应未知编号（协议用 not_found 表达，实现可汇总）。
|
||||||
|
NotFound bool `json:"-"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// DirectoryItem 是目录一项。
|
||||||
|
type DirectoryItem struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Name string `json:"name"`
|
||||||
|
Online bool `json:"online"`
|
||||||
|
OnlineSinceMs *int64 `json:"online_since_ms"`
|
||||||
|
OfflineSinceMs *int64 `json:"offline_since_ms"`
|
||||||
|
TalkPasswordSet bool `json:"talk_password_set"`
|
||||||
|
}
|
||||||
|
|
||||||
|
// Service 是在线与目录子系统契约（第 6.5 节）。
|
||||||
|
type Service interface {
|
||||||
|
// Get 查询若干编号在线状态。
|
||||||
|
Get(ctx context.Context, ids []string) ([]StatusItem, error)
|
||||||
|
// Directory 分页目录。
|
||||||
|
Directory(ctx context.Context, req *protocol.DirectoryList) (items []DirectoryItem, nextCursor string, err error)
|
||||||
|
// Watch 覆盖本连接的上下线订阅；断线由 ClearWatch 清空。
|
||||||
|
Watch(ctx context.Context, connID port.ConnID, endpointID string, req *protocol.PresenceWatch) error
|
||||||
|
// ClearWatch 在连接断开时清空订阅。
|
||||||
|
ClearWatch(connID port.ConnID)
|
||||||
|
|
||||||
|
// SetOnline 握手完成时标记在线并通知订阅者。
|
||||||
|
SetOnline(ctx context.Context, endpointID string, connID port.ConnID, atMs int64) error
|
||||||
|
// SetOffline 当前连接断开时标记离线并通知订阅者。
|
||||||
|
SetOffline(ctx context.Context, endpointID string, connID port.ConnID, atMs int64) error
|
||||||
|
// IsOnline 查询端是否有已握手连接。
|
||||||
|
IsOnline(endpointID string) bool
|
||||||
|
// CurrentConn 返回端的当前连接代号；无则空。
|
||||||
|
CurrentConn(endpointID string) (port.ConnID, bool)
|
||||||
|
}
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
package presence
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubGetOffline(t *testing.T) {
|
||||||
|
s := NewStub()
|
||||||
|
items, err := s.Get(context.Background(), []string{"a", "b"})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if len(items) != 2 || items[0].Online || items[1].Online {
|
||||||
|
t.Fatalf("%+v", items)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubIsOnlineFalse(t *testing.T) {
|
||||||
|
if NewStub().IsOnline("x") {
|
||||||
|
t.Fatal("expected offline")
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,41 @@
|
|||||||
|
package presence
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/app/port"
|
||||||
|
"git.asio.asia/nixevol/NixMsg/internal/protocol"
|
||||||
|
)
|
||||||
|
|
||||||
|
// Stub 是测试用假实现：全部视为离线。
|
||||||
|
type Stub struct{}
|
||||||
|
|
||||||
|
func NewStub() *Stub { return &Stub{} }
|
||||||
|
|
||||||
|
func (s *Stub) Get(_ context.Context, ids []string) ([]StatusItem, error) {
|
||||||
|
out := make([]StatusItem, 0, len(ids))
|
||||||
|
for _, id := range ids {
|
||||||
|
out = append(out, StatusItem{ID: id, Online: false, SinceMs: 0})
|
||||||
|
}
|
||||||
|
return out, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Directory(context.Context, *protocol.DirectoryList) ([]DirectoryItem, string, error) {
|
||||||
|
return nil, "", nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) Watch(context.Context, port.ConnID, string, *protocol.PresenceWatch) error {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *Stub) ClearWatch(port.ConnID) {}
|
||||||
|
|
||||||
|
func (s *Stub) SetOnline(context.Context, string, port.ConnID, int64) error { return nil }
|
||||||
|
|
||||||
|
func (s *Stub) SetOffline(context.Context, string, port.ConnID, int64) error { return nil }
|
||||||
|
|
||||||
|
func (s *Stub) IsOnline(string) bool { return false }
|
||||||
|
|
||||||
|
func (s *Stub) CurrentConn(string) (port.ConnID, bool) { return "", false }
|
||||||
|
|
||||||
|
var _ Service = (*Stub)(nil)
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
// Package auth 定义密码哈希池、会话令牌、API 令牌与登录锁定计数的接口。
|
||||||
|
// 本包在 T0.4 只提供契约与测试假实现；真正的 argon2 池与令牌逻辑由平台 P 实现。
|
||||||
|
package auth
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"errors"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
// ErrNotImplemented 表示假实现尚未提供业务能力。
|
||||||
|
var ErrNotImplemented = errors.New("auth: not implemented")
|
||||||
|
|
||||||
|
// PasswordKind 区分哈希用途（便于日志与限流，不影响算法）。
|
||||||
|
type PasswordKind string
|
||||||
|
|
||||||
|
const (
|
||||||
|
PasswordLogin PasswordKind = "login"
|
||||||
|
PasswordTalk PasswordKind = "talk"
|
||||||
|
PasswordAdmin PasswordKind = "admin"
|
||||||
|
)
|
||||||
|
|
||||||
|
// HashPool 是 argon2id 并发池（DEVELOPMENT 第 12 节）。
|
||||||
|
type HashPool interface {
|
||||||
|
// Hash 计算 PHC 格式哈希。
|
||||||
|
Hash(ctx context.Context, kind PasswordKind, password string) (phc string, err error)
|
||||||
|
// Verify 常量时间比较；ok 为 false 时 err 仍可为 nil（密码不匹配）。
|
||||||
|
Verify(ctx context.Context, kind PasswordKind, password, phc string) (ok bool, err error)
|
||||||
|
// QueueLen 返回等待哈希的任务数（指标用）。
|
||||||
|
QueueLen() int
|
||||||
|
}
|
||||||
|
|
||||||
|
// SessionTokens 管理端会话令牌（nst_ 前缀，库中存 SHA-256）。
|
||||||
|
type SessionTokens interface {
|
||||||
|
// Issue 生成新令牌明文，返回明文与 SHA-256 十六进制（或原始哈希字节由实现约定）。
|
||||||
|
Issue(ctx context.Context) (token string, hash []byte, err error)
|
||||||
|
// HashToken 对已有令牌做 SHA-256（校验用，不走 argon2）。
|
||||||
|
HashToken(token string) []byte
|
||||||
|
// LooksLikeSessionToken 判断密码字段是否以 nst_ 开头。
|
||||||
|
LooksLikeSessionToken(credential string) bool
|
||||||
|
}
|
||||||
|
|
||||||
|
// APITokenInfo 是列表项（不含令牌明文）。
|
||||||
|
type APITokenInfo struct {
|
||||||
|
ID int64
|
||||||
|
Name string
|
||||||
|
Enabled bool
|
||||||
|
CreatedAt time.Time
|
||||||
|
LastUsedAt *time.Time
|
||||||
|
}
|
||||||
|
|
||||||
|
// APITokens 管理后台 API 令牌（nxm_ 前缀）。
|
||||||
|
type APITokens interface {
|
||||||
|
Issue(ctx context.Context) (token string, hash []byte, err error)
|
||||||
|
HashToken(token string) []byte
|
||||||
|
LooksLikeAPIToken(credential string) bool
|
||||||
|
}
|
||||||
|
|
||||||
|
// LockKind 区分锁定计数器类型。
|
||||||
|
type LockKind string
|
||||||
|
|
||||||
|
const (
|
||||||
|
// LockLoginEndpointIP：编号 + IP，5 分钟内 10 次错 → 锁该组合 5 分钟。
|
||||||
|
LockLoginEndpointIP LockKind = "login_endpoint_ip"
|
||||||
|
// LockLoginEndpoint：编号总数，1 小时内 50 次错 → 暂停该编号密码登录 1 小时。
|
||||||
|
LockLoginEndpoint LockKind = "login_endpoint"
|
||||||
|
// LockTalkPair：发送方 + 对方对话密码。
|
||||||
|
LockTalkPair LockKind = "talk_pair"
|
||||||
|
// LockTalkTarget：对方对话密码总数。
|
||||||
|
LockTalkTarget LockKind = "talk_target"
|
||||||
|
// LockAdminIP：管理员登录 / 错误 API 令牌。
|
||||||
|
LockAdminIP LockKind = "admin_ip"
|
||||||
|
// LockRegisterIP：注册安全码错误。
|
||||||
|
LockRegisterIP LockKind = "register_ip"
|
||||||
|
)
|
||||||
|
|
||||||
|
// LockKey 是一次锁定查询/计数的键。
|
||||||
|
type LockKey struct {
|
||||||
|
Kind LockKind
|
||||||
|
EndpointID string // 端编号；管理员/注册场景可空
|
||||||
|
PeerID string // 对话密码对方；可空
|
||||||
|
IP string // 来源 IP；按编号总数等场景可空
|
||||||
|
}
|
||||||
|
|
||||||
|
// LoginLocks 是内存锁定计数器（重启清零）。
|
||||||
|
type LoginLocks interface {
|
||||||
|
// Check 若当前已锁定返回 locked=true 与剩余时间。
|
||||||
|
Check(key LockKey) (locked bool, retryAfter time.Duration)
|
||||||
|
// Fail 记录一次失败；若因此触发锁定，返回 locked=true。
|
||||||
|
Fail(key LockKey) (locked bool, retryAfter time.Duration)
|
||||||
|
// ClearEndpoint 清除某端编号相关的登录锁定（两种都清），对应管理 unlock。
|
||||||
|
ClearEndpoint(endpointID string)
|
||||||
|
// Clear 清除精确键。
|
||||||
|
Clear(key LockKey)
|
||||||
|
}
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
package auth
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestStubHashPoolRoundTrip(t *testing.T) {
|
||||||
|
p := NewStubHashPool()
|
||||||
|
h, err := p.Hash(context.Background(), PasswordLogin, "secret")
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
ok, err := p.Verify(context.Background(), PasswordLogin, "secret", h)
|
||||||
|
if err != nil || !ok {
|
||||||
|
t.Fatalf("verify: ok=%v err=%v", ok, err)
|
||||||
|
}
|
||||||
|
ok, _ = p.Verify(context.Background(), PasswordLogin, "wrong", h)
|
||||||
|
if ok {
|
||||||
|
t.Fatal("expected mismatch")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubSessionTokenPrefix(t *testing.T) {
|
||||||
|
s := NewStubSessionTokens()
|
||||||
|
tok, hash, err := s.Issue(context.Background())
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if !s.LooksLikeSessionToken(tok) {
|
||||||
|
t.Fatalf("token %q should look like session", tok)
|
||||||
|
}
|
||||||
|
if len(hash) != 32 {
|
||||||
|
t.Fatalf("hash len %d", len(hash))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubAPITokenPrefix(t *testing.T) {
|
||||||
|
s := NewStubAPITokens()
|
||||||
|
tok, _, err := s.Issue(context.Background())
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if !s.LooksLikeAPIToken(tok) {
|
||||||
|
t.Fatalf("token %q should look like api", tok)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestStubLoginLocksFailRecord(t *testing.T) {
|
||||||
|
l := NewStubLoginLocks()
|
||||||
|
locked, _ := l.Fail(LockKey{Kind: LockLoginEndpointIP, EndpointID: "a", IP: "1.2.3.4"})
|
||||||
|
if locked {
|
||||||
|
t.Fatal("stub should not lock")
|
||||||
|
}
|
||||||
|
l.ClearEndpoint("a")
|
||||||
|
if len(l.Cleared) != 1 || l.Cleared[0] != "a" {
|
||||||
|
t.Fatalf("cleared=%v", l.Cleared)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,105 @@
|
|||||||
|
package auth
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"crypto/sha256"
|
||||||
|
"strings"
|
||||||
|
"sync"
|
||||||
|
"time"
|
||||||
|
)
|
||||||
|
|
||||||
|
// StubHashPool 是测试用假哈希池：明文加前缀，不做 argon2。
|
||||||
|
type StubHashPool struct {
|
||||||
|
mu sync.Mutex
|
||||||
|
queue int
|
||||||
|
}
|
||||||
|
|
||||||
|
func NewStubHashPool() *StubHashPool { return &StubHashPool{} }
|
||||||
|
|
||||||
|
func (p *StubHashPool) Hash(_ context.Context, _ PasswordKind, password string) (string, error) {
|
||||||
|
return "stub$" + password, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (p *StubHashPool) Verify(_ context.Context, _ PasswordKind, password, phc string) (bool, error) {
|
||||||
|
return phc == "stub$"+password, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (p *StubHashPool) QueueLen() int {
|
||||||
|
p.mu.Lock()
|
||||||
|
defer p.mu.Unlock()
|
||||||
|
return p.queue
|
||||||
|
}
|
||||||
|
|
||||||
|
// StubSessionTokens 假会话令牌。
|
||||||
|
type StubSessionTokens struct{}
|
||||||
|
|
||||||
|
func NewStubSessionTokens() *StubSessionTokens { return &StubSessionTokens{} }
|
||||||
|
|
||||||
|
func (s *StubSessionTokens) Issue(_ context.Context) (string, []byte, error) {
|
||||||
|
tok := "nst_stub_session_token_000000000000"
|
||||||
|
sum := sha256.Sum256([]byte(tok))
|
||||||
|
return tok, sum[:], nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubSessionTokens) HashToken(token string) []byte {
|
||||||
|
sum := sha256.Sum256([]byte(token))
|
||||||
|
return sum[:]
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubSessionTokens) LooksLikeSessionToken(credential string) bool {
|
||||||
|
return strings.HasPrefix(credential, "nst_")
|
||||||
|
}
|
||||||
|
|
||||||
|
// StubAPITokens 假 API 令牌。
|
||||||
|
type StubAPITokens struct{}
|
||||||
|
|
||||||
|
func NewStubAPITokens() *StubAPITokens { return &StubAPITokens{} }
|
||||||
|
|
||||||
|
func (s *StubAPITokens) Issue(_ context.Context) (string, []byte, error) {
|
||||||
|
tok := "nxm_stub_api_token_0000000000000000"
|
||||||
|
sum := sha256.Sum256([]byte(tok))
|
||||||
|
return tok, sum[:], nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubAPITokens) HashToken(token string) []byte {
|
||||||
|
sum := sha256.Sum256([]byte(token))
|
||||||
|
return sum[:]
|
||||||
|
}
|
||||||
|
|
||||||
|
func (s *StubAPITokens) LooksLikeAPIToken(credential string) bool {
|
||||||
|
return strings.HasPrefix(credential, "nxm_")
|
||||||
|
}
|
||||||
|
|
||||||
|
// StubLoginLocks 假锁定：永不锁定，记录调用便于测试。
|
||||||
|
type StubLoginLocks struct {
|
||||||
|
mu sync.Mutex
|
||||||
|
Fails []LockKey
|
||||||
|
Cleared []string
|
||||||
|
}
|
||||||
|
|
||||||
|
func NewStubLoginLocks() *StubLoginLocks { return &StubLoginLocks{} }
|
||||||
|
|
||||||
|
func (l *StubLoginLocks) Check(LockKey) (bool, time.Duration) { return false, 0 }
|
||||||
|
|
||||||
|
func (l *StubLoginLocks) Fail(key LockKey) (bool, time.Duration) {
|
||||||
|
l.mu.Lock()
|
||||||
|
defer l.mu.Unlock()
|
||||||
|
l.Fails = append(l.Fails, key)
|
||||||
|
return false, 0
|
||||||
|
}
|
||||||
|
|
||||||
|
func (l *StubLoginLocks) ClearEndpoint(endpointID string) {
|
||||||
|
l.mu.Lock()
|
||||||
|
defer l.mu.Unlock()
|
||||||
|
l.Cleared = append(l.Cleared, endpointID)
|
||||||
|
}
|
||||||
|
|
||||||
|
func (l *StubLoginLocks) Clear(LockKey) {}
|
||||||
|
|
||||||
|
// 编译期检查：假实现满足接口。
|
||||||
|
var (
|
||||||
|
_ HashPool = (*StubHashPool)(nil)
|
||||||
|
_ SessionTokens = (*StubSessionTokens)(nil)
|
||||||
|
_ APITokens = (*StubAPITokens)(nil)
|
||||||
|
_ LoginLocks = (*StubLoginLocks)(nil)
|
||||||
|
)
|
||||||
Reference in New Issue
Block a user