[R2] 前端启动所需接口的最小实现(桩,返回空/默认值) #3

Closed
opened 2026-11-08 23:06:06 +00:00 by keith · 1 comment
Owner

部署背景

单域名 https://wire.treeden.app:根路径由 wire-webapp 提供前端;/api/* 与 /ws/* 由 Caddy 反代到 wire-rs 并剥离前缀(handle_path)。前端配置 BACKEND_REST=https://wire.treeden.app/api、BACKEND_WS=wss://wire.treeden.app/ws。

对接原则

前端尽量不改,由后端适配;后端保持最小,前端启动链路之外的接口返回空值或默认值。

冒烟证据(2026-11-09,wire-rs ccecae5)

/self 200,/v6/self 404;/feature-configs、/properties、/teams、/list-connections、/notifications/last、/calls/config/v2、/system/settings/unauthorized 均 404;/conversations/list-ids 400(被当作会话 ID);/mls/public-keys 400(未配置 REMOVAL_PRIVATE_KEY);/await 101。

API 版本约定

前端 MAX_API_VERSION 默认 17(libraries/config/src/client.config.ts),wire-rs /api-version 宣称 0–19,协商结果为 17。部署时固定 MAX_API_VERSION=8,后端 /api-version 宣称与之匹配的 supported 范围(上限 8),桩接口按该版本的路径实现;以下路径均为剥离 /v{N} 之后的形式。v7 起 1:1 路径为 /one2one-conversations/...(libraries/api-client/src/conversation/conversationApi/conversationApi.ts)。

期望行为

前端启动路径上的每个接口都在后端有实现;非核心接口只返回空值/默认值,不得 404/405 导致前端启动失败。{DOMAIN} 指 wire-rs 的 DOMAIN(wire.treeden.app),{self} 指当前用户 UUID。

1. 功能配置(只开 MLS,关闭 consumable notifications)

GET /feature-configs → 200

{
  "mls": {"status":"enabled","lockStatus":"locked","config":{
    "protocolToggleUsers":[],"defaultProtocol":"mls","supportedProtocols":["mls"],
    "allowedCipherSuites":[1],"defaultCipherSuite":1}},
  "mlsMigration": {"status":"disabled","lockStatus":"locked","config":{}},
  "consumableNotifications": {"status":"disabled","lockStatus":"locked"},
  "conferenceCalling": {"status":"disabled","lockStatus":"locked"},
  "fileSharing": {"status":"disabled","lockStatus":"locked"},
  "selfDeletingMessages": {"status":"disabled","lockStatus":"locked","config":{"enforcedTimeoutSeconds":0}},
  "conversationGuestLinks": {"status":"disabled","lockStatus":"locked"},
  "sndFactorPasswordChallenge": {"status":"disabled","lockStatus":"locked"},
  "searchVisibility": {"status":"disabled","lockStatus":"locked"},
  "searchVisibilityInbound": {"status":"disabled","lockStatus":"locked"},
  "legalhold": {"status":"disabled","lockStatus":"locked"},
  "sso": {"status":"disabled","lockStatus":"locked"},
  "validateSAMLemails": {"status":"disabled","lockStatus":"locked"},
  "digitalSignatures": {"status":"disabled","lockStatus":"locked"},
  "appLock": {"status":"disabled","lockStatus":"locked","config":{"enforceAppLock":false,"inactivityTimeoutSecs":60}},
  "classifiedDomains": {"status":"disabled","lockStatus":"locked","config":{"domains":[]}},
  "mlsE2EId": {"status":"disabled","lockStatus":"locked","config":{"verificationExpiration":86400,"acmeDiscoveryUrl":null}},
  "outlookCalIntegration": {"status":"disabled","lockStatus":"locked"},
  "exposeInvitationURLsToTeamAdmin": {"status":"disabled","lockStatus":"locked"},
  "enforceFileDownloadLocation": {"status":"disabled","lockStatus":"locked","config":{}},
  "limitedEventFanout": {"status":"disabled","lockStatus":"locked"}
}

要点:consumableNotifications 必须为 disabled(或缺省),前端才走 /await + /notifications(apps/webapp/src/script/auth/module/action/clientAction.ts、apps/webapp/src/script/main/app.ts)。密码套件 1 = MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519,需与 wire-rs MLS 校验一致。

2. 系统设置

  • GET /system/settings/unauthorized → {"setRestrictUserCreation":false,"setEnableMls":true}
  • GET /system/settings → {"setRestrictUserCreation":false,"setEnableMls":true}

3. 用户属性(properties)

  • GET /properties → []
  • GET /properties/{key} → 404 {"code":404,"label":"not-found","message":"Property not found"}(前端对 webapp/labels 等键缺失可正常处理)
  • PUT /properties/{key}(任意 JSON,≤ 64KB)→ 200 空体;需持久化,后续 GET 返回原 JSON
  • DELETE /properties/{key} → 200 空体

4. 自身协议

  • PUT /self/supported-protocols 体 {"supported_protocols":["mls"]} → 200 空体(可只接受含 mls 的数组)
  • GET /self 已有,保持 supported_protocols:["mls"]、无 team

5. 连接(无好友体系,返回空)

  • POST /list-connections 体 {"size":500,"paging_state":null} → {"connections":[],"has_more":false,"paging_state":""}
  • GET /connections/{domain}/{uid} → 404 not-found

6. 会话列表

  • POST /conversations/list-ids 体 {"size":N,"paging_state":null} → {"qualified_conversations":[{"id":"<cid>","domain":"{DOMAIN}"}...],"has_more":false,"paging_state":"x"}(返回用户参与的所有会话,含 R4 的 self / 1:1 会话)。路由必须排在 /conversations/{cid} 之前,修复当前 400。
  • POST /conversations/list 体 {"qualified_ids":[...]} → {"found":[<Conversation>...],"failed":[],"not_found":[]},Conversation 形状与现有 GET /conversations/{cid} 相同(qualified_id、type、protocol:"mls"、group_id、epoch、cipher_suite:1、members:{self:{...},others:[...]}、name、access:["invite"]、access_role:["team_member","non_team_member"]、receipt_mode:0、message_timer:null、creator、last_event、last_event_time、team:null)
  • GET /conversations/{cid}/self(GET 自身成员信息)→ {"id":"{self}","qualified_id":{...},"conversation_role":"wire_admin","otr_muted_status":null,"otr_archived":false,"hidden":false,"service":null,"status":0};PUT 同路径 → 200 空体(静音/归档,可只存不处理)

7. 通知

  • GET /notifications/last?client=<cid> → 有记录时返回最新一条 {"id":"<uuidv7>","payload":[...]},无记录时 404 {"code":404,"label":"not-found","message":"Some notifications not found"}(前端把 404 视为“无历史”)
  • GET /notifications/{id}?client=<cid> → 对应单条或 404
  • 已有 GET /notifications?since= 保持不变

8. 通话配置(无 TURN,返回空)

  • GET /calls/config/v2?limit=N → {"ice_servers":[],"sft_servers":[],"sft_servers_all":[],"ttl":3600,"is_federating":false}
  • GET /calls/config → {"ice_servers":[],"ttl":3600}

9. 团队(用户不属于团队)

  • /self 不含 team 字段,前端不会进入 initTeam;GET /teams/{tid}/... 一律 404 no-team。GET /teams → {"teams":[],"has_more":false}。

10. 用户与设备

  • GET /users/{domain}/{uid} → UserProfile:{"id","qualified_id","name","handle","accent_id":0,"assets":[],"supported_protocols":["mls"],"legalhold_status":"no_consent","deleted":false},不存在 404 not-found
  • POST /list-users 体 {"qualified_ids":[...]} → {"found":[UserProfile...],"failed":[]}
  • POST /users/list-clients 体 {"qualified_users":[...]} → {"qualified_user_map":{"{DOMAIN}":{"<uid>":[{"id":"<cid>","class":"desktop","mls_public_keys":{...}}]}}}
  • GET /users/{domain}/{uid}/clients → [{"id","class","mls_public_keys"}](已有的 /users/{uid}/clients 补带域名形式)
  • POST /users/list-prekeys → {"qualified_user_client_prekeys":{},"failed_to_list":[]}(MLS-only 下不应真正使用,空即可)
  • GET /users/{domain}/{uid}/prekeys → 404 not-found

11. 搜索与 handle

  • GET /search/contacts?q=&size= → {"documents":[],"found":0,"returned":0,"took":0,"search_policy":"full_search"}(可选:按 email/handle 精确匹配返回已注册用户,便于建群)
  • HEAD /handles/{handle} → 404(未被占用)或 200
  • GET /handles/{handle} 同上;POST /users/handles 体 {"handles":[...],"return":N} → []
  • PUT /self/handle 体 {"handle":"..."} → 200 空体(可选持久化)

12. 其他启动期调用

  • GET /mls/public-keys → 部署时必须设置 REMOVAL_PRIVATE_KEY,返回 {"removal":{"ed25519":"<base64>"}}(现已实现,仅部署配置)
  • GET /clients/{cid} 若前端调用(校验本地设备仍存在)→ 返回 Self Client 对象;不存在 404 client-not-found
  • PUT /clients/{cid} → 见 R3
  • GET /self/consent → {"results":[]};PUT /self/locale → 200 空体
  • GET /conversations/{cid}/roles → {"conversation_roles":[{"conversation_role":"wire_admin","actions":["add_conversation_member","remove_conversation_member","modify_conversation_name","modify_conversation_message_timer","modify_conversation_receipt_mode","modify_conversation_access","modify_other_conversation_member","leave_conversation","delete_conversation"]},{"conversation_role":"wire_member","actions":["leave_conversation"]}]}
  • GET /assets/... → 见 R5;在其实现前返回 404

验证方式

前端源码类型对照:libraries/api-client/src/team/feature/、libraries/api-client/src/self/、libraries/api-client/src/connection/、libraries/api-client/src/conversation/、libraries/api-client/src/notification/、libraries/api-client/src/account/accountApi.ts、libraries/api-client/src/user/userApi.ts。实现后用真实前端登录,浏览器网络面板不应再出现 404/405 导致的启动中断。

涉及文件/模块

  • src/http.rs(路由注册与顺序)
  • src/auth/http.rs(self、handle、supported-protocols)
  • src/conversations/(list-ids、list、self 成员、roles)
  • src/clients/(list-clients、prekeys 空实现)
  • 新增模块:feature-configs、properties、calls、system、search(建议 src/stubs/)
  • migrations/(properties 持久化表)
  • README.md

工作量

M–L(2–4 天)

## 部署背景 单域名 https://wire.treeden.app:根路径由 wire-webapp 提供前端;`/api/*` 与 `/ws/*` 由 Caddy 反代到 wire-rs 并剥离前缀(handle_path)。前端配置 `BACKEND_REST=https://wire.treeden.app/api`、`BACKEND_WS=wss://wire.treeden.app/ws`。 ## 对接原则 前端尽量不改,由后端适配;后端保持最小,前端启动链路之外的接口返回空值或默认值。 ## 冒烟证据(2026-11-09,wire-rs `ccecae5`) `/self` 200,`/v6/self` 404;`/feature-configs`、`/properties`、`/teams`、`/list-connections`、`/notifications/last`、`/calls/config/v2`、`/system/settings/unauthorized` 均 404;`/conversations/list-ids` 400(被当作会话 ID);`/mls/public-keys` 400(未配置 `REMOVAL_PRIVATE_KEY`);`/await` 101。 ## API 版本约定 前端 `MAX_API_VERSION` 默认 17(`libraries/config/src/client.config.ts`),wire-rs `/api-version` 宣称 0–19,协商结果为 17。部署时固定 `MAX_API_VERSION=8`,后端 `/api-version` 宣称与之匹配的 supported 范围(上限 8),桩接口按该版本的路径实现;以下路径均为剥离 `/v{N}` 之后的形式。v7 起 1:1 路径为 `/one2one-conversations/...`(`libraries/api-client/src/conversation/conversationApi/conversationApi.ts`)。 ## 期望行为 前端启动路径上的每个接口都在后端有实现;非核心接口只返回空值/默认值,不得 404/405 导致前端启动失败。`{DOMAIN}` 指 wire-rs 的 `DOMAIN`(wire.treeden.app),`{self}` 指当前用户 UUID。 ### 1. 功能配置(只开 MLS,关闭 consumable notifications) `GET /feature-configs` → 200 ```json { "mls": {"status":"enabled","lockStatus":"locked","config":{ "protocolToggleUsers":[],"defaultProtocol":"mls","supportedProtocols":["mls"], "allowedCipherSuites":[1],"defaultCipherSuite":1}}, "mlsMigration": {"status":"disabled","lockStatus":"locked","config":{}}, "consumableNotifications": {"status":"disabled","lockStatus":"locked"}, "conferenceCalling": {"status":"disabled","lockStatus":"locked"}, "fileSharing": {"status":"disabled","lockStatus":"locked"}, "selfDeletingMessages": {"status":"disabled","lockStatus":"locked","config":{"enforcedTimeoutSeconds":0}}, "conversationGuestLinks": {"status":"disabled","lockStatus":"locked"}, "sndFactorPasswordChallenge": {"status":"disabled","lockStatus":"locked"}, "searchVisibility": {"status":"disabled","lockStatus":"locked"}, "searchVisibilityInbound": {"status":"disabled","lockStatus":"locked"}, "legalhold": {"status":"disabled","lockStatus":"locked"}, "sso": {"status":"disabled","lockStatus":"locked"}, "validateSAMLemails": {"status":"disabled","lockStatus":"locked"}, "digitalSignatures": {"status":"disabled","lockStatus":"locked"}, "appLock": {"status":"disabled","lockStatus":"locked","config":{"enforceAppLock":false,"inactivityTimeoutSecs":60}}, "classifiedDomains": {"status":"disabled","lockStatus":"locked","config":{"domains":[]}}, "mlsE2EId": {"status":"disabled","lockStatus":"locked","config":{"verificationExpiration":86400,"acmeDiscoveryUrl":null}}, "outlookCalIntegration": {"status":"disabled","lockStatus":"locked"}, "exposeInvitationURLsToTeamAdmin": {"status":"disabled","lockStatus":"locked"}, "enforceFileDownloadLocation": {"status":"disabled","lockStatus":"locked","config":{}}, "limitedEventFanout": {"status":"disabled","lockStatus":"locked"} } ``` 要点:`consumableNotifications` 必须为 disabled(或缺省),前端才走 `/await` + `/notifications`(`apps/webapp/src/script/auth/module/action/clientAction.ts`、`apps/webapp/src/script/main/app.ts`)。密码套件 1 = `MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519`,需与 wire-rs MLS 校验一致。 ### 2. 系统设置 - `GET /system/settings/unauthorized` → `{"setRestrictUserCreation":false,"setEnableMls":true}` - `GET /system/settings` → `{"setRestrictUserCreation":false,"setEnableMls":true}` ### 3. 用户属性(properties) - `GET /properties` → `[]` - `GET /properties/{key}` → 404 `{"code":404,"label":"not-found","message":"Property not found"}`(前端对 webapp/labels 等键缺失可正常处理) - `PUT /properties/{key}`(任意 JSON,≤ 64KB)→ 200 空体;需持久化,后续 GET 返回原 JSON - `DELETE /properties/{key}` → 200 空体 ### 4. 自身协议 - `PUT /self/supported-protocols` 体 `{"supported_protocols":["mls"]}` → 200 空体(可只接受含 `mls` 的数组) - `GET /self` 已有,保持 `supported_protocols:["mls"]`、无 `team` ### 5. 连接(无好友体系,返回空) - `POST /list-connections` 体 `{"size":500,"paging_state":null}` → `{"connections":[],"has_more":false,"paging_state":""}` - `GET /connections/{domain}/{uid}` → 404 `not-found` ### 6. 会话列表 - `POST /conversations/list-ids` 体 `{"size":N,"paging_state":null}` → `{"qualified_conversations":[{"id":"<cid>","domain":"{DOMAIN}"}...],"has_more":false,"paging_state":"x"}`(返回用户参与的所有会话,含 R4 的 self / 1:1 会话)。**路由必须排在 `/conversations/{cid}` 之前**,修复当前 400。 - `POST /conversations/list` 体 `{"qualified_ids":[...]}` → `{"found":[<Conversation>...],"failed":[],"not_found":[]}`,`Conversation` 形状与现有 `GET /conversations/{cid}` 相同(`qualified_id`、`type`、`protocol:"mls"`、`group_id`、`epoch`、`cipher_suite:1`、`members:{self:{...},others:[...]}`、`name`、`access:["invite"]`、`access_role:["team_member","non_team_member"]`、`receipt_mode:0`、`message_timer:null`、`creator`、`last_event`、`last_event_time`、`team:null`) - `GET /conversations/{cid}/self`(GET 自身成员信息)→ `{"id":"{self}","qualified_id":{...},"conversation_role":"wire_admin","otr_muted_status":null,"otr_archived":false,"hidden":false,"service":null,"status":0}`;`PUT` 同路径 → 200 空体(静音/归档,可只存不处理) ### 7. 通知 - `GET /notifications/last?client=<cid>` → 有记录时返回最新一条 `{"id":"<uuidv7>","payload":[...]}`,无记录时 404 `{"code":404,"label":"not-found","message":"Some notifications not found"}`(前端把 404 视为“无历史”) - `GET /notifications/{id}?client=<cid>` → 对应单条或 404 - 已有 `GET /notifications?since=` 保持不变 ### 8. 通话配置(无 TURN,返回空) - `GET /calls/config/v2?limit=N` → `{"ice_servers":[],"sft_servers":[],"sft_servers_all":[],"ttl":3600,"is_federating":false}` - `GET /calls/config` → `{"ice_servers":[],"ttl":3600}` ### 9. 团队(用户不属于团队) - `/self` 不含 `team` 字段,前端不会进入 `initTeam`;`GET /teams/{tid}/...` 一律 404 `no-team`。`GET /teams` → `{"teams":[],"has_more":false}`。 ### 10. 用户与设备 - `GET /users/{domain}/{uid}` → `UserProfile`:`{"id","qualified_id","name","handle","accent_id":0,"assets":[],"supported_protocols":["mls"],"legalhold_status":"no_consent","deleted":false}`,不存在 404 `not-found` - `POST /list-users` 体 `{"qualified_ids":[...]}` → `{"found":[UserProfile...],"failed":[]}` - `POST /users/list-clients` 体 `{"qualified_users":[...]}` → `{"qualified_user_map":{"{DOMAIN}":{"<uid>":[{"id":"<cid>","class":"desktop","mls_public_keys":{...}}]}}}` - `GET /users/{domain}/{uid}/clients` → `[{"id","class","mls_public_keys"}]`(已有的 `/users/{uid}/clients` 补带域名形式) - `POST /users/list-prekeys` → `{"qualified_user_client_prekeys":{},"failed_to_list":[]}`(MLS-only 下不应真正使用,空即可) - `GET /users/{domain}/{uid}/prekeys` → 404 `not-found` ### 11. 搜索与 handle - `GET /search/contacts?q=&size=` → `{"documents":[],"found":0,"returned":0,"took":0,"search_policy":"full_search"}`(可选:按 email/handle 精确匹配返回已注册用户,便于建群) - `HEAD /handles/{handle}` → 404(未被占用)或 200 - `GET /handles/{handle}` 同上;`POST /users/handles` 体 `{"handles":[...],"return":N}` → `[]` - `PUT /self/handle` 体 `{"handle":"..."}` → 200 空体(可选持久化) ### 12. 其他启动期调用 - `GET /mls/public-keys` → 部署时必须设置 `REMOVAL_PRIVATE_KEY`,返回 `{"removal":{"ed25519":"<base64>"}}`(现已实现,仅部署配置) - `GET /clients/{cid}` 若前端调用(校验本地设备仍存在)→ 返回 Self Client 对象;不存在 404 `client-not-found` - `PUT /clients/{cid}` → 见 [R3](https://gitforge.treeden.app/keith/wire-rs/issues/7) - `GET /self/consent` → `{"results":[]}`;`PUT /self/locale` → 200 空体 - `GET /conversations/{cid}/roles` → `{"conversation_roles":[{"conversation_role":"wire_admin","actions":["add_conversation_member","remove_conversation_member","modify_conversation_name","modify_conversation_message_timer","modify_conversation_receipt_mode","modify_conversation_access","modify_other_conversation_member","leave_conversation","delete_conversation"]},{"conversation_role":"wire_member","actions":["leave_conversation"]}]}` - `GET /assets/...` → 见 [R5](https://gitforge.treeden.app/keith/wire-rs/issues/5);在其实现前返回 404 ## 验证方式 前端源码类型对照:`libraries/api-client/src/team/feature/`、`libraries/api-client/src/self/`、`libraries/api-client/src/connection/`、`libraries/api-client/src/conversation/`、`libraries/api-client/src/notification/`、`libraries/api-client/src/account/accountApi.ts`、`libraries/api-client/src/user/userApi.ts`。实现后用真实前端登录,浏览器网络面板不应再出现 404/405 导致的启动中断。 ## 涉及文件/模块 - `src/http.rs`(路由注册与顺序) - `src/auth/http.rs`(self、handle、supported-protocols) - `src/conversations/`(list-ids、list、self 成员、roles) - `src/clients/`(list-clients、prekeys 空实现) - 新增模块:feature-configs、properties、calls、system、search(建议 `src/stubs/`) - `migrations/`(properties 持久化表) - `README.md` ## 工作量 M–L(2–4 天)
keith changed title from [R3] 前端启动所需的最小桩接口 to [R3][必需] 前端启动所需接口的最小实现(桩,返回空/默认值) 2026-11-08 23:26:40 +00:00
keith changed title from [R3][必需] 前端启动所需接口的最小实现(桩,返回空/默认值) to [R3] 前端启动所需接口的最小实现(桩,返回空/默认值) 2026-11-08 23:37:04 +00:00
keith changed title from [R3] 前端启动所需接口的最小实现(桩,返回空/默认值) to [R2] 前端启动所需接口的最小实现(桩,返回空/默认值) 2026-11-08 23:40:44 +00:00
Author
Owner

已实现并通过 M11 验收

启动链 25+ 路由全部真实注册(不再 404/405):/feature-configs(consumableNotifications=disabled)、/system/settings(/unauthorized)、/properties(GET/PUT/DELETE,迁移 0009 持久化)、PUT /self/supported-protocols、/list-connections、/conversations/list-ids(路由顺序已修复,400→200)、/conversations/list、/conversations/{cid}/self、/notifications/last、/notifications/{id}、/calls/config(/v2)、/teams、/users/{domain}/{uid}、/list-users、/users/list-clients、/search/contacts、handle 系列、/conversations/{cid}/roles 等。

已知限制(非持久化桩:teams/connections/calls/search 恒空;列表不分页)。

M11 accepted · commit 56437e7 · doc docs/milestones/M11.md · gates: default 886 / test:db 177 (14 suites) / interop 971 / live 14 (×3, no flake) · integration agent 221 real-process assertions.

## 已实现并通过 M11 验收 启动链 25+ 路由全部真实注册(不再 404/405):`/feature-configs`(`consumableNotifications=disabled`)、`/system/settings(/unauthorized)`、`/properties`(GET/PUT/DELETE,迁移 0009 持久化)、`PUT /self/supported-protocols`、`/list-connections`、`/conversations/list-ids`(路由顺序已修复,400→200)、`/conversations/list`、`/conversations/{cid}/self`、`/notifications/last`、`/notifications/{id}`、`/calls/config(/v2)`、`/teams`、`/users/{domain}/{uid}`、`/list-users`、`/users/list-clients`、`/search/contacts`、handle 系列、`/conversations/{cid}/roles` 等。 已知限制(非持久化桩:teams/connections/calls/search 恒空;列表不分页)。 M11 accepted · commit `56437e7` · doc `docs/milestones/M11.md` · gates: default **886** / test:db **177 (14 suites)** / interop **971** / live **14** (×3, no flake) · integration agent 221 real-process assertions.
keith closed this issue 2026-11-09 14:02:15 +00:00
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
keith/wire-rs#3
No description provided.