astra/owpengram-server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
owpengram-server/docs/message-module.md
A 75a8861ec9 protocol: expose privacy and profile photo RPCs 
(cherry picked from commit 77b033c8bf8c0a76ff0d7065e2192cbe55d3a3b6)
2026-06-14 00:20:04 +08:00

34 KiB
Raw Blame History

Message Module Design

Date: 2026-05-31

Scope

二阶段先实现私聊文本闭环：

  • messages.sendMessage
  • messages.forwardMessages
  • messages.getDialogs
  • messages.getHistory
  • messages.readHistory
  • messages.editMessage
  • messages.deleteMessages
  • messages.deleteHistory
  • updates.getState
  • updates.getDifference
  • 在线 session update 推送

不在本阶段实现：媒体、定时消息、群组/频道、Bot API、文件 DC。

Storage

大表从第一版开始分区：

table partition key purpose
private_messages sender_user_id HASH 共享私聊消息主体；sender_user_id + random_id 保证发送幂等
message_boxes owner_user_id HASH owner 视角消息盒；TDesktop 看到的 message id 即 box_id，并保存当前 owner 的 media_unread/reaction_unread 内容已读状态
dialogs user_id HASH 会话摘要；folder_id=0/1 表示主列表/归档，置顶、manual unread、action bar 隐藏均是 owner 视角
contact_blocks owner_user_id HASH 当前 owner 的 blocklist；owner_user_id + blocked_user_id 唯一，作为本阶段私聊 privacy gate
dialog_filters / dialog_filter_settings user_id HASH TDesktop 自定义 dialog filter、filter 顺序与 folder tags 开关；不把自定义 filter 伪装成 dialogs.folder_id
user_update_events user_id HASH 账号级 pts durable log；承载新消息、已读 inbox/outbox、文本编辑、删除消息，也承载 contacts reset、dialog pinned/order/manual unread、peer settings、dialog filters 与 folder peers 等 owner 视角状态事件
dispatch_outbox target_user_id HASH transactional outbox，事务后批量推送在线 session；投递成功即删除，仅保留未完成任务

Redis 只存可恢复计数：

  • counter:pts:{user_id}：账号级 pts。
  • counter:box_id:{user_id}：owner 视角 box_id。
  • ratelimit:messages:send:{user_id}：发送窗口限流，当前为每用户每分钟 30 条。

Redis miss 时分别从 MAX(user_update_events.pts) 与 MAX(message_boxes.box_id) 恢复。 分配器热路径使用 Redis Lua 脚本递增；首次 miss 时先从 PG durable log 读取恢复值，再通过恢复脚本完成「初始化 + 首次自增」，避免并发 first-use 把 pts / box_id 分配出重复或回退。

Send Flow

messages.sendMessage 在 RPC 层只做 TL 转换和当前 user/session 校验，业务写入由 MessageStore.SendPrivateText 单事务完成：

  1. 写 private_messages，遇到同 sender_user_id + random_id 直接返回原消息盒。
  2. Redis 分配 sender/recipient 的 box_id 与 pts。
  3. 写 sender/recipient message_boxes，并保存 silent/noforwards/reply_to/fwd_from 元数据；reply 会把当前 owner 的 reply_to_msg_id 翻译成对端 owner 视角的 box_id。incoming media 在 recipient box 上置 media_unread=true，sender 自己始终为 false。
  4. upsert 双方 dialogs。
  5. 写双方 user_update_events(new_message)。
  6. 写双方 dispatch_outbox，sender 侧带 exclude_session_id。
  7. 提交后由 outbox worker 批量推送在线 session。

若事务失败但 Redis 已分配 pts，store 会尽力写 noop 事件占位，避免 pts 回退；PG 不可用时该补偿也可能失败，后续需要告警指标覆盖。

如果 recipient 已 block sender，SendPrivateText 仍写 sender outbox/dialog/update，保证当前用户能看到自己发出的消息；但不创建 recipient message box、不推进 recipient pts、不写 recipient dispatch_outbox，也不会进入 recipient 离线 updates.getDifference。该规则同样适用于 messages.sendMedia/sendMultiMedia 和私聊转发，因为它们共用 sendOutgoing/SendPrivateText。

Forward / Reply Flow

messages.forwardMessages 当前覆盖私聊文本转发，参考实现 的业务语义但保持 telesrv 的 owner 视角模型：

  1. RPC 层校验 from/to peer、id/random_id 等长、单次最多 100 条；scheduled/monoforum/quick reply/effect/paid/suggested 等当前阶段外能力用显式 TL 错误拒绝，目标为 channel 的 send_as 交由频道模块校验 self/current channel。
  2. store 按当前 owner + from peer + box_id 保序读取源消息，源消息带 noforwards 时返回 CHAT_FORWARDS_RESTRICTED。
  3. 未设置 drop_author 时，若源消息已有 forward header 则沿用；否则用源消息 from/date 生成 messageFwdHeader。drop_author 会去掉 forward header。
  4. 每条转发复用 SendPrivateText 写入双端 message box / dialog / update event / dispatch outbox，pts_count=1，并使用对应 random_id 保证幂等。

messages.sendMessage 的 reply_to 支持 inputReplyToMessage 的私聊同 peer 回复和 quote 文本/entities/offset；quote_text 按 TDesktop quote_length_max=1024 限制，quote_offset 是原消息文本内 offset，不是 message id，按当前文本消息上限 4096 收口。cross-peer reply、story、monoforum、todo/poll reply 仍拒绝，但返回 REPLY_MESSAGE_ID_INVALID / STORY_ID_INVALID / REPLY_TO_MONOFORUM_PEER_INVALID / POLL_OPTION_INVALID 等显式错误，不再落 NOT_IMPLEMENTED。服务端保存 sender 视角和 recipient 视角各自的 reply_to_msg_id，避免一个 owner 的 box_id 泄漏到另一个 owner。

Read Flow

messages.readHistory 采用 owner 视角的双端回执模型，参考实现 的 inbox 已读链路和 参考实现 的 inbox/outbox read history event：

  1. reader 侧锁定当前 dialog，按 max_id 与当前可见 incoming message 计算新的 read_inbox_max_id，清零 unread_count 并清除 manual unread。
  2. 如果 reader 确实推进了已读水位，给 reader 生成 updateReadHistoryInbox(pts_count=1)，写入 user_update_events + dispatch_outbox。
  3. 同一事务中找出本次被读到的最新 incoming message，定位原 sender 的 dialog，推进 sender 侧 read_outbox_max_id。
  4. sender 水位真正推进时，给 sender 生成 updateReadHistoryOutbox(pts_count=1)，离线设备可通过 updates.getDifference 补齐。

发送消息时不会预先推进 sender 的 read_outbox_max_id；只有对端实际 readHistory 后才产生 outbox 已读回执，避免“刚发出就被标成已读”的假状态。

messages.getOutboxReadDate 复用 sender 侧 durable read_history_outbox 事件：先校验当前 owner 的 msg_id 是该 peer 下可见 outgoing message，再取最早一条 max_id >= msg_id 的 outbox read event 日期返回 outboxReadDate；未被读到返回 MESSAGE_NOT_READ_YET。PG 上有 (user_id, peer_type, peer_id, max_id, date) WHERE event_type='read_history_outbox' partial index，避免 TDesktop 已读详情查询扫全量 update log。

Content Read Flow

messages.readMessageContents 处理 TDesktop 打开媒体/反应等“内容已读”入口，不等同于 history read 水位：

  1. 私聊 incoming media 创建 recipient message box 时置 media_unread=true；sender 自己为 false。
  2. 私聊 reaction 写入时，若反应者不是原消息作者，会把原作者 owner 视角的 message box 标记 reaction_unread=true，并重算该 dialog 的 unread_reactions_count。
  3. readMessageContents 在事务内锁定当前 owner 的 exact message boxes，只清理 media_unread OR reaction_unread 的行；不可见 id、已删除 id、已经 read 的 id 都不生成新 pts。
  4. 实际清理时为当前 owner 分配连续 user pts，写 user_update_events(read_message_contents) 与 dispatch_outbox，TL 转换为 updateReadMessagesContents{messages,pts,pts_count}。重复调用返回当前 affectedMessages，pts_count=0。
  5. 该事件排除当前 auth_key/session，其它在线 session 走 reliable outbox，离线设备通过 updates.getDifference 恢复。

Edit Flow

messages.editMessage 当前只支持私聊文本编辑：

  1. RPC 层校验当前账号、peer、message id、文本长度和 entities；inputMediaWebPage/inputMediaEmpty 降级为文本编辑，真实 media/reply_markup/quick replies/scheduled 返回显式 TL 错误。
  2. store 锁定当前 owner 的 message_box，确认它是当前 user 发出的 outgoing 私聊消息。
  3. 更新共享 private_messages 文本与 edit_date，并更新同一 private message 下所有未删除 owner message_box。
  4. 每个受影响 owner 各自分配 pts，写 updateEditMessage(pts_count=1) 与 dispatch_outbox。
  5. 当前请求设备直接拿到 updates 响应；其它在线设备走 reliable outbox，离线设备走 updates.getDifference。

如果文本和 entities 完全未变化，返回 MESSAGE_NOT_MODIFIED；非作者编辑返回 MESSAGE_AUTHOR_REQUIRED。

若 peer 已 block 当前用户，私聊 edit 会返回 EDIT_MESSAGES_FORBIDDEN，避免修改对方侧已存在的 message box。该 gate 只来自 contact_blocks；完整 Telegram privacy keys 暂不扩展。

Delete Flow

messages.deleteMessages / messages.deleteHistory 以 owner 视角软删除 message_boxes，不会删除共享 private_messages 主体。默认 deleteHistory 清空后如果该 peer 已无可见消息，则删除当前 owner 的 dialog；后续任意新消息会通过正常 send/upsert 路径重建 dialog。just_clear=true 对齐 参考实现 语义：清空历史但保留一个空 dialog（当前阶段不生成 messageActionHistoryClear 服务消息）。

revoke=true 时按 (message_sender_id, private_message_id) 找到同一私聊消息在其它 owner 下的 message_box 并软删除。每个受影响 owner 都生成自己的 updateDeleteMessages，message_ids 是该 owner 视角 box_id，pts_count=len(message_ids)，并写入 user_update_events + dispatch_outbox。如果删除后仍有可见消息，dialog 的 top/unread 会按剩余消息重算；否则删除 dialog 或在 just_clear 下保留空 dialog。

若 revoke=true 会影响已 block 当前用户的一方，RPC 层返回 DELETE_MESSAGES_FORBIDDEN；revoke=false 或本地清理仍只影响当前 owner，可继续执行。

全清也必须让所有被删的 owner 视角 message_id 最终进入 update/difference，但不能合成一个超大 update。messages.deleteHistory 单次最多删除 MaxDeleteHistoryBatch=1000 条，按 box_id 倒序批量软删并返回 affectedHistory.offset=1 表示客户端应继续发起下一批；每一批各自产生一条有界 updateDeleteMessages。messages.deleteMessages 单次 id 数限制为 MaxDeleteMessageIDs=1000，服务端还会丢弃 <=0 或超过 TL/PG int4 可表达范围的 id。

Query Path

  • messages.getHistory 以 owner_user_id + peer_user_id + box_id/date 命中 message_boxes 分区索引；offset_id、offset_date、max_id、min_id 都下推为游标条件；add_offset 只允许 [-100,100] 的小窗口偏移，避免异常客户端把超大偏移变成 SQL 跳过扫描或内存 slice capacity。
  • messages.search / messages.searchGlobal 当前只覆盖当前 owner 私聊文本搜索；查询仍限定在 owner_user_id HASH 分区内，文本条件由 pg_trgm GIN 索引兜底。参考实现 的经验，未接外部全文搜索前禁止无索引大表模糊扫；后续群组/频道/全局多 peer 搜索应接专用搜索索引或 FTS。
  • messages.getDialogs 以 user_id 分区定位当前账号，再按 top_message_date/top_message_id/peer_id 做 seek pagination；folder_id=0/1 直接走 dialogs.folder_id，folder_id>=2 先取当前账号 dialog_filters 后按 include/exclude/contact 规则过滤；hash 与 count 基于当前筛选后的完整会话集计算。
  • messages.getDialogs/getPeerDialogs/getHistory/getMessages/search 返回的 users 统一经过 internal/app/userprojection：批量读取 viewer personal photo、profile_photos(kind=profile|fallback)、当前 viewer contacts 与 account privacy，按 personal > allowed profile > fallback > empty 选择头像，并按联系人备注/PhoneNumber/StatusTimestamp privacy 裁剪姓名、手机号与状态。该路径是 TDesktop dialog 标题、头像、history 标题与 action bar 用户状态的公共入口，禁止在各 handler 内重复拼用户资料。
  • messages.getDialogFilters 返回 dialogFilterDefault + 当前账号持久化 filters；messages.updateDialogFilter/updateDialogFiltersOrder/toggleDialogFilterTags 与 folders.editPeerFolders 都是 owner 视角写入，归档只允许 folder_id 0/1，自定义 filters 从 ID 2 开始。
  • updates.getDifference 只按 user_id + pts 顺序扫描 user_update_events，多设备各自的 (auth_key_id,user_id) state 只记录消费位置，不参与账号事件归属；离线设备通过同一条 durable log 恢复新消息、已读 inbox/outbox、内容已读、文本编辑、删除消息、联系人 reset、dialog pinned/order/manual unread、peer settings、dialog filters/order/reload 与 folder peers 变化，置顶顺序、peer settings flags、filter payload 与 folder peers 会随事件负载持久化。

参考实现 Comparison

参考实现 的 SyncUpdatesNotMe 设计有两个值得借鉴的点：所有“其它端通知”收敛到 sync 服务，以及带 pts 的消息/已读类 update 会写 user_pts_updates 后再推 session。它的不足也很明确：updatePeerSettings 只在线 push 不入 durable pts 队列，markDialogUnread / hidePeerSettingsBar 仍有 TODO，离线设备可能依赖后续主动刷新才能看到状态变化。

telesrv 当前做得更进一步：联系人 reset、dialog pinned/order/manual unread、peer settings、dialog filter/order/reload 与 folder peers 都写入账号级 user_update_events，并通过 Postgres AppendWithDispatch 在同一事务里写入 dispatch_outbox。updatePinnedDialogs.order、updatePeerSettings.settings、updateDialogFilter.filter、updateDialogFilterOrder.order、updateFolderPeers.folder_peers 都是 durable payload，不依赖后续主动刷新；在线投递由 outbox worker 负责，排除当前设备时同时携带 exclude_auth_key_id + exclude_session_id，避免同一 session_id 在不同 auth key 下误排除或串号。RPC handler 在检测到可靠 outbox 后不再额外手动 push，避免其它设备收到重复在线通知。

dialog 分组借鉴 参考实现 的 dialog_filters/editPeerFolders 业务语义与 参考实现 的 UpdateDialogFilter / UpdateFolderPeers 事件模型，但修正两点：filter 设置不仅在线 push，也有持久化真值表和 durable update；归档 folder 与自定义 filter 分离，避免一个 folder_id 字段同时承担归档状态和任意筛选规则。

删除链路借鉴 参考实现 的 just_clear / dialog 删除边界：普通 deleteHistory 会移除 dialog，just_clear 保留 dialog。借鉴 参考实现 的点是“先按 owner 计算受影响 message_id，再按 owner 重建 top message 并发 updateDeleteMessages”，而不是只对当前请求账号返回 affectedMessages；这样 revoke、多设备离线补偿和 dialog 后续重建都在同一条 owner 视角语义里。

已读和编辑链路也分别借鉴了两边的优点：参考实现 在 edit 时会校验 sender 并把编辑同步到 inbox/outbox，参考实现 把 readHistory 分成 reader 的 UpdateReadHistoryInbox 和 sender 的 UpdateReadHistoryOutbox。telesrv 将这两类事件都落到账号级 durable log，同事务写 reliable outbox，且 edit 更新共享消息主体和所有 owner 视角 message_box，避免只在线 push 或只改当前盒子导致离线设备/对端历史不一致。

reply/forward 的语义参考实现 的 handler：send/forward 都透传 silent 和 noforwards，reply 用 inputReplyToMessage，forward 在源消息没有 fwd_from 时构造原作者 header，遇到受保护内容拒绝转发。telesrv 额外修正 owner 视角 id 翻译与 durable update 负载：对端收到的 reply header 使用对端自己的 message id，离线设备通过 updates.getDifference 也能拿到同样的 reply_to/fwd_from 元数据。

Observability

消息链路 RPC 层预留 Metrics 接口，当前覆盖：

  • MessageSend：记录发送成功、payload 长度与双端 pts。
  • MessageRateLimited：记录用户级窗口限流。
  • OutboxClaimed / OutboxDelivered / OutboxFailed：记录 outbox claim、在线推送成功与重试失败。

默认实现是 no-op，生产接 Prometheus/OpenTelemetry 时只需在 rpc.Deps 注入实现，不污染业务服务和 store 边界。

Next Execution Plan

连接层已具备 per-connection outbound actor、scoped session context 与 bounded inbound RPC scheduler。消息模块下一轮按以下顺序推进，不再先扩 RPC 面：

  1. 压测基线：单机目标 200 msg/s 私聊文本、p99 sendMessage < 150ms、p99 getDifference < 100ms。已落地 internal/loadtest 真实 PG+Redis 压测 harness，首版基线见下「Load Baseline」节；1k online session 的网络 fanout 属连接层，本轮 harness 未覆盖（binder 用零连接 SessionManager，只测 outbox 的 PG 排空）。
  2. Redis 计数强一致：pts / box_id 分配已收敛到 Lua 脚本路径，覆盖 Redis miss 从 PG durable log 恢复与并发 first-use 连续分配；事务失败 noop gap 与 random_id 幂等已有 store 测试覆盖，后续补真实 Redis+PG 混合压测。
  3. PG 分区验收：已有 message_boxes history seek 与 dispatch_outbox stale retry 索引；已补 explain 集成测试，固定 message_boxes / user_update_events 单用户查询命中分区索引，dispatch_outbox 全局 claim 允许跨分区但必须走分区 partial index、不出现 Seq Scan。
  4. Outbox 背压（已做到生产级，见下「Load Baseline」）：worker 有 batch claim、lease timeout、retry/backoff、failed 终态和 claim/deliver/fail 指标；batch size / interval / lease timeout / worker 数 均配置化（env TELESRV_OUTBOX_BATCH / _INTERVAL / _LEASE_TIMEOUT / _WORKERS）。已并行化（N worker 竞争 FOR UPDATE SKIP LOCKED claim）并批量化（每批一次 BatchListDispatchEvents unnest join + 一次 MarkDispatchDeliveredBatch，取代逐条往返），排空上限从单 worker ~270 行/s 提到 ~12k 行/s（本机 PG，~45x）；批量化后瓶颈转移到 PG 本身。主动 push 仍只走 auth_key_id + session_id + user_id scoped API。
  5. TDesktop 私聊闭环：用双账号/多设备验证 sendMessage、forwardMessages、reply、getDialogs、getHistory、readHistory、getOutboxReadDate、editMessage、deleteMessages/deleteHistory、updates.getDifference、当前设备过滤与退出换号不串号。2026-05-31 已用 Alice/Bob 两个 TDesktop workdir 验证在线 read/edit/delete 与 Bob 离线 send+edit/read/delete 差量同步；删除后 dialog 可清除，后续新消息仍按正常路径重建。2026-06-01 已补 reply/forward 服务端路径和单测，仍待重新用双 TDesktop 实机点 UI 行为（通知声音、reply 预览、forward header）。
  6. 兼容矩阵回填：所有真实跑到的未知 RPC 自动入 trace，按 TDesktop 首屏和私聊流程补 done/stub/todo 状态。

Load Baseline

压测 harness：internal/loadtest/send_load_test.go，env-gated，未设 TELESRV_TEST_POSTGRES_DSN+TELESRV_TEST_REDIS_ADDR 时 Skip，对默认 go test ./... 无副作用。

方法：与 main.go 一致装配连接池 + Redis 分配器 + PG 消息存储 + transactional outbox + 真实 OutboxDispatcher（binder 用零连接 SessionManager，PushToUserExceptSession 返回 0，因此 outbox 走完整 claim→批量取事件→push→批量标记 的 PG 往返，测排空而非网络 fanout）。closed-loop 饱和：concurrency 个 worker 各自不停发满 messages 条。TELESRV_LOAD_DEFER_DISPATCH=1 时先把积压攒满、发送结束才启 dispatcher，用以隔离测量 outbox 纯排空上限（否则 dispatcher 实时跟上发送、积压近 0 量不出天花板）。

运行（PowerShell）：

$env:TELESRV_TEST_POSTGRES_DSN = "postgres://telesrv:telesrv@localhost:5432/telesrv?sslmode=disable"
$env:TELESRV_TEST_REDIS_ADDR   = "localhost:6399"
# 稳态（dispatcher 与发送并发）
go test ./internal/loadtest/ -run TestMessageSendBaseline -v -count=1 -timeout 240s
# 纯排空上限（先攒满积压再排空）
$env:TELESRV_LOAD_MESSAGES=30000; $env:TELESRV_OUTBOX_BATCH=200; $env:TELESRV_LOAD_DEFER_DISPATCH=1
go test ./internal/loadtest/ -run TestMessageSendBaseline -v -count=1 -timeout 300s

可调 env：TELESRV_LOAD_USERS(50) / _CONCURRENCY(32) / _MESSAGES(5000) / _POOL_CONNS(64) / _DEFER_DISPATCH；outbox 用 TELESRV_OUTBOX_WORKERS(loadtest 默认 8，运行时默认 2) / _BATCH(100) / _INTERVAL / _LEASE_TIMEOUT；TELESRV_LOAD_ENFORCE_SLO=1 时 SLO 超标硬失败（回归门禁）。正确性（无发送错误/无意外重复/全部发出/outbox 必须排空/无终态失败）始终硬断言。

生产化做了什么（2026-05-31）：

  • 连接池配置化（TELESRV_POSTGRES_MAX_CONNS 默认 50，TELESRV_POSTGRES_MIN_CONNS 默认 16，经 postgres.WithMaxConns/WithMinConns）。postgres.Open 会在启动时显式预热 min 连接，避免 TDesktop 双端冷启动时大量 RPC 一边建 PG 连接一边排队；pgx 默认 max(4,NumCPU) 在高并发下排队，是首版 send max 2s 突刺的根因。
  • dispatcher 并行（TELESRV_OUTBOX_WORKERS，运行时默认 2，loadtest 默认 8，rpc.WithOutboxWorkers）。N worker 各跑 claim 循环，靠 FOR UPDATE SKIP LOCKED 互不重叠；本地 TDesktop 双端启动默认偏保守，避免多个 worker 同扫 64 分区父表触发 PG lock/shared-memory 压力。
  • dispatcher 批量（store 具备批量能力时自动启用，否则逐条回退）。每批一次 BatchListDispatchEvents（双 unnest WITH ORDINALITY USING(ord) 配对 (user_id,pts) 的 join）+ 一次 MarkDispatchDeliveredBatch，把每条 ~2 次 PG 往返降到每批 ~3 次。

outbox 排空上限演进（本机 docker PG+Redis，攒满 6 万行积压后纯排空）：

方案 drain 速率 相对
单 worker 逐条（首版） ~270 行/s 1x
8 worker 逐条（仅并行） ~1711 行/s ~6x
8 worker 批量（当前） ~12285 行/s ~45x

稳态下（concurrent，出厂默认 users=1000/concurrency=32/8 worker/batch100）：峰值积压仅 ~330 行、排空 ~80ms——dispatcher 实时跟上发送（~2500 行/s 入队）；send p99 ~114ms、getDifference p99 ~2ms、吞吐 ~1255 msg/s，SLO 全过。12k 行/s ≈ 6k msg/s 可持续 outbox 吞吐；16 worker/batch500 仍 ~11.7k 行/s（与 8 worker 持平 → 瓶颈已是 PG 而非 worker 数）。

send p99 对用户池集中度敏感：harness 用 50 用户时 p99 飙到 ~220–325ms（32 并发挤少数用户的 dialog/message_box 行，行锁争用），2000 用户降到 ~58ms。这是小池假象，生产 20 万用户分散后争用极低；默认已取 users=1000。

面向 20 万在线的剩余 levers（按 §8 记账，本轮未做）：

  1. PG 已是共享瓶颈：批量化后 send 与 drain 都打在同一 PG 上，本机 ~12k 行/s 触顶。生产需更强的 PG（多核/NVMe/调参），更高规模再上读副本 / 按 user 分库。worker/batch/池均可调以匹配硬件。
  2. send 路径 Redis 分配已移出事务（已做）：原先 sender/recipient 的 pts/box_id 分配（4 次 Redis 往返）嵌在 PG 事务内，持连接空等 Redis。现已移到 BeginTx 之前——分配本就走 Redis 不属 PG 事务，前移后不再在持有 PG 连接（与行锁）期间空等，连接周转更快（池受压时收益最大；收益随 Redis RTT 增大，远端 Redis 更明显）。本机 docker（Redis 亚毫秒 RTT）下 pool=24/conc=96（4x 超订）实测 send p99 ~130ms（<150ms）、~1800 msg/s、0 err 0 dup、SLO 全过。
    • 配套的 pts 连续性兜底（mtproto 对齐，已做）：分配前移加宽了「pts 已分配未提交」的瞬时空洞窗口（并发发送 commit 重排序，本就存在），故 updates 服务改为只暴露连续 pts：getState 报告最大连续已提交 pts（非 allocator 最大已分配值），getDifference 只返回从客户端 pts 起连续的事件、遇空洞即截断、State.Pts 取最后连续值、超 limit(100) 置 updates.differenceSlice。客户端永不越过在途空洞，空洞由 commit/补洞在毫秒内自愈，下次拉取补齐——绝不丢消息。连续值由 UpdateEventStore.MaxContiguousPts（PG 顶部 4096 窗口）计算。正确性已由单测（空洞截断/slice 翻页/getState 连续）+ 真实 PG 集成测试（200 并发发送 pts 严格 1..200 无空洞无重复无丢失、PG 空洞场景）覆盖。
    • 仍可继续：把 4 次 Redis 分配 pipeline/合并成 1 次（每用户 pts+box 一个 Lua、sender/recipient 并行），进一步缩短分配耗时。
  3. 连接层 SessionManager 全局锁——已实测，非吞吐瓶颈（结论被数据修正）：原假设是"pushToUser 抢全局锁 = 20 万在线最大瓶颈"。新增连接层 benchmark（session_manager_bench_test.go，20 万连接、内存 Conn 不走真实 socket）实测：
    • push fanout：~4.6M push/s（24 核），延迟 1→24 核仅 249ns→328ns，几乎不随核数恶化——临界区只是 snapshot 一个 per-user 小 map，锁极短。20 万在线 @ 200 msg/s × 双端 = ~40 万 push/s，比上限低一个数量级，push 不是瓶颈。
    • Register/Unregister churn：全局写锁，~2067ns/op @ 24 核 ≈ 48 万 churn/s。稳态 churn（20 万连接 × 平均存活分钟级）≈ 千级/s，余量巨大。
    • mutexprofile 确认两者都 100% 串行在同一把锁，但因临界区极短，当前规模下不构成瓶颈。
    • 真正的风险点（分片的价值所在，但非紧急）：重连风暴（断网恢复 / 发版重启）时瞬时 churn 飙升，写锁会阻塞同期所有 push 读锁。按 userID 分片可把写锁从全局 1 把拆成 N 片，churn 风暴只影响 1/N 的 push——这是稳健性/尾延迟提升，不是吞吐解锁。建议留待真有重连风暴尾延迟问题、或单机连接数再上一个量级时再做。
    • 仍未覆盖：真实 socket 的 per-conn 加密/写出背压、20 万 fd 的内核态开销——那需要真实网络压测环境，非本 harness（内存 Conn）目标。

Multi-Account / Multi-Device

  • authorizations 是 auth_key 到 user 的权威绑定。
  • active session 缓存 auth_key_id + user_id；router 额外按业务 auth_key 缓存 user_id，并用 singleflight 合并启动期并发 miss，避免同一永久 auth_key 派生的多个 temp session 重复查授权表。
  • update_states 主键是 (auth_key_id, user_id)；同设备退出登录或换账号只清 auth_key 设备状态，不删除账号级 user_update_events。
  • 一个账号多设备共享 user_update_events，各设备通过自己的 auth_key_id + user_id 状态和 updates.getDifference 补偿。
  • 联系人备注、联系人 mutual/shareContact 状态、dialog pinned/order/manual unread、peer settings 都是 owner 视角数据；写业务表后同步写账号级 durable update event，并把投递任务写入 dispatch_outbox，避免“只在线 push、离线设备永远不知道”的状态漂移。

ACK / Global Sequence Note

参考实现 的可借鉴点是：msgs_ack 不直接生成业务事件，它只确认某个已发送 server msg_id / RPC response 已被客户端收到；server 通过 ack cache 找回该响应对应的 pts / globalSeqNo，再推进 (auth_key_id,user_id) 维度的已确认水位。这个设计适合频道、多 peer 混合更新和 server 侧 delivered watermark。

当前阶段私聊文本只需要账号级 pts durable log，客户端 updates.getDifference 仍以请求里的 pts 为准；MTProto ACK 只释放出站重发缓存。后续引入频道或跨 peer 全局更新流时，再新增独立的 per-device global_seq_no / delivered watermark，不把它塞进 MTProto ACK 状态本身。

客户端 pts 重排依赖 pts_count 准确（TDesktop PtsWaiter，已核对源码）

结论来自实读 TDesktop pinned baseline（9caf32dffc）源码： tdesktop/Telegram/SourceFiles/data/data_pts_waiter.cpp、data_pts_waiter.h、api/api_updates.cpp。

背景：outbox worker 多 worker 并发 claim + 发送事务乱序提交，所以主动推送可能乱序到达客户端（pts=6 的 UpdateNewMessage 先于 pts=5 发出）。这不会让客户端乱序或丢消息——前提是每条 update 的 pts / pts_count 准确。

客户端如何处理乱序（PtsWaiter::check，data_pts_waiter.cpp:170-187）：客户端维护 _good（已应用的最大连续 pts）、_last = max(见过的 pts)、_count += 每条 update 的 pts_count：

  • 收到 pts=6（count=1）：_last=6, _count=5 → _last > _count（中间缺 pts）→ 这条 update 不应用，先缓存进 _updatesQueue，setWaitingForSkipped(1000ms)。
  • 随后收到 pts=5（count=1）：_last=6, _count=6 → 相等 → _good=6，applySkippedUpdates 把缓存的 5、6 按序应用（data_pts_waiter.cpp:48-72）。
  • 若 1 秒（kWaitForSkippedTimeout，data_pts_waiter.h:24）内空缺没补上 → 触发 getDifference 主动补齐。

即客户端缓存乱序、等空缺、按序应用，1 秒补不齐才 getDifference——比"丢弃重拉"更优雅。普通私聊 updates 与 channel 复用同一个 _ptsWaiter 单例（调用时 channel 传 nullptr，api_updates.cpp:603-604）。

对 server 的硬约束：客户端这套重排完全依赖 _count += pts_count 累加，因此 server 必须保证：

  1. 每条 update 的 pts_count 准确等于它推进的 pts 步数。私聊文本、已读 inbox/outbox、文本编辑恒为 1；批量删除为 owner 视角删除 message_id 数量：UpdateDeleteMessages{Pts: event.Pts, PtsCount: len(message_ids)}。
  2. 每个分配出去的 pts 最终都能被 getDifference 拿到（即使事务回滚，也要写 noop 占位，见 recordPtsGaps）——否则连续水位永远卡在空缺处，客户端会永久 getDifference 重试或永久 gap。

当前安全：私聊文本、转发、已读回执、文本编辑 pts_count 恒为 1，删除消息 pts_count 等于删除数量；每个 pts 都有真实事件或 noop 占位，且 getState/getDifference 只暴露连续 pts（见上文 Load Baseline 的「pts 连续性兜底」）。未来风险：引入其它“一次操作产生多条 update / pts_count ≠ 1”的场景（批量 service action、频道 editMessage 等）时，若 server 的 pts_count 算错，客户端 _count 会永久错位 → 永久 gap。新增此类 RPC 时必须同步核对 pts_count 语义。

Current Limits

  • messages.sendMessage 仅支持私聊文本；reply 仅支持同一私聊 peer 的 inputReplyToMessage。
  • messages.forwardMessages 仅支持当前 owner 可见的私聊文本消息转发到 user peer，单次最多 100 条。
  • messages.editMessage 仅支持文本消息编辑；网页预览 media 降级文本编辑，真实媒体、reply markup、quick replies、scheduled edit 留后续并返回显式 TL 错误。
  • messages.deleteMessages / messages.deleteHistory 仅支持私聊消息；min_date/max_date 当前作为兼容 no-op，服务消息 messageActionHistoryClear 留到后续消息类型扩展。
  • messages.deleteHistory 全清按 1000 条一批推进，offset>0 续删；deleteMessages 单次最多 1000 个 id，避免客户端构造超大数组或超大 max_id 导致服务端 OOM。
  • messages.getHistory/messages.search 的 add_offset 统一 clamp 到 [-100,100]；TDesktop 正常滚动只会使用小偏移，恶意超大值不能触发无界内存分配或大 SQL OFFSET。
  • reply_markup、quick replies、effects、paid send、suggested posts、story/monoforum/todo/poll reply 均返回客户端可理解的显式 TL 错误（如 REPLY_MARKUP_INVALID、SHORTCUT_INVALID、EFFECT_ID_INVALID、PAYMENT_UNSUPPORTED、SUGGESTED_POST_PEER_INVALID、STORY_ID_INVALID、REPLY_TO_MONOFORUM_PEER_INVALID、POLL_OPTION_INVALID），不再落 NOT_IMPLEMENTED；send_as 仅在目标为 channel 时按频道模块规则接受 self/current channel，私聊目标返回 SEND_AS_PEER_INVALID；目标为 channel 且请求未显式带 send_as 时，RPC 层读取 messages.saveDefaultSendAs 保存的默认身份并重新校验。
  • 定时消息返回 SCHEDULE_DATE_INVALID。
  • messages.search / messages.searchGlobal 当前是私聊文本 ILIKE + pg_trgm，后续大规模数据需要按语言/分词策略补全文索引或外部搜索服务。
  • 单条文本当前限制 4096 个 Unicode code point；超限返回 MESSAGE_TOO_LONG，触发窗口限流返回 FLOOD_WAIT_X。

媒体消息（2026-06-02）

  • messages.sendMedia / uploadMedia / sendMultiMedia 接入：RPC 层 resolveInputMedia 把 inputMediaUploadedPhoto/Document（组装 upload.* 分片→建 Photo/Document）与 inputMediaPhoto/Document（引用已存在资源，含贴纸）转成 domain.MessageMedia，经抽取的 sendOutgoing 走与文本完全相同的 pts/box/outbox/在线推送/离线 getDifference 路径；私聊与 channel 共用。
  • private_messages / message_boxes 增 media JSONB 快照列：发送在事务内随 body/entities 一起写双端盒子，历史 getHistory/getMessages/dialog preview 读取时随消息一并解码，无需 join documents/photos。转发复制源消息 media（同一文档引用）；文本编辑保留 media。
  • tgMessage 在 media 非空时 SetMedia(MessageMediaPhoto/Document)，客户端经 upload.getFile 从 blob backend 下载。Document id 在 domain/store 中保持 telesrv-owned 正数；外部 seed source id 在导入阶段归一，InputDocument / inputDocumentFileLocation 入站直接按服务端 id 解析，避免把第三方导出 id 当成本服资源身份。
  • 仅媒体消息（无 caption）：放宽 private_messages body 非空 CHECK 为 body<>'' OR media<>'{}'。
  • 范围外：grouped_id 相册聚合（sendMultiMedia 当前各条独立成消息）、geo/contact/poll/todo/dice/story media 仍 MEDIA_INVALID。