OpenMax
免费试用

写入事件

唯一写入口收的 ChatStoreEvent 和十二种事件,含请求时的水位 requestWatermark、乐观发送和乐观改动。

写入事件

@openmaxai/chat-store 根入口里关于写入口收的事件的导出。状态、在宿主里怎么接和全部导出的索引见概览。

ChatStoreEvent

type ChatStoreEvent =
  | ChatStoreWindowLoadedEvent
  | ChatStoreOlderLoadedEvent
  | ChatStoreNewerLoadedEvent
  | ChatStoreMessageUpsertedEvent
  | ChatStoreMessageDeletedEvent
  | ChatStoreConversationClosedEvent
  | ChatStoreViewChangedEvent
  | ChatStoreSendStartedEvent
  | ChatStoreSendSettledEvent
  | ChatStoreLocalMessageRemovedEvent
  | ChatStorePatchStartedEvent
  | ChatStorePatchSettledEvent
  | ChatStoreReactionChangedEvent
  | ChatStoreCardChangedEvent;

写入口收的事件,按 type 区分。每个事件只关于一个会话。新的写入种类往联合里加成员,不改已有成员的形状。

windowLoaded 之外的四种数据事件(olderLoaded、newerLoaded、messageUpserted、messageDeleted)对没加载过的会话不起作用:那个会话还没有区间可接。乐观发送和乐观改动的事件见本页后半。

ChatStoreWindowLoadedEvent

interface ChatStoreWindowLoadedEvent {
  type: "windowLoaded";
  conversationId: string;
  messages: readonly ChatMessage[];
  hasOlder: boolean;
  olderCursor?: string;
  hasNewer: boolean;
  newerCursor?: string;
  requestWatermark?: number;
  changeSeq?: number;
}

取到一窗,整窗换入:打开会话、跳到某条消息、回到最新。

  • 最新一窗和围着某个 seq 取的一窗都用它,区别只在 hasNewer:最新一窗为 false,仓库把水位推到这一窗的最大 seq;围着取的一窗没接到最新时为 true,水位不动。hasNewer 只能来自服务端,不按条数推。
  • 最新一窗的末尾低于水位时不算接到最新:可能是请求发出后仓库又拿到过更新的消息、这一窗迟到了,也可能是水位那条在服务端被删掉了。不带 requestWatermark 时仓库分不清,一律水位不退,快照里 hasNewer 为 true、newerCursor 没有、newerPending 为 true,缺的那段从区间末尾按 seq 往后取;在那之前推送不接进区间。
  • 已在仓库里的消息按 id 合并,内容没变的保持同一个对象;删掉过的消息不再写进来。仓库自己按 seq(相同时按 id)排序。
  • changeSeq 是这一窗的改动水位,见下面的改动水位与改动编号。

请求时的水位 requestWatermark

发这次请求时仓库的水位(getSnapshot().watermark),没有就不给。只对最新一窗(hasNewer: false)有用:服务端是在仓库知道这个水位之后才说「到最新了」,所以这一窗里没有的、不大于它的号都已被删掉,这一窗的末尾即使低于它,区间也按覆盖到它算、可以接到最新。比当前水位大时按当前水位算。

不给时(不知道请求是什么时候发的)按迟到的一窗处理。补洞调度总是带上它。newerLoaded 的同名字段含义相同。

前提:读接口读到的数据不比推送旧。仓库的水位来自推送,读接口要是落后于推送(比如走了落后于主库的读副本),服务端还没读到的号会被当成已删,区间覆盖过去,补洞不会再去取。

改动水位与改动编号 changeSeq

后端给每个会话记一本改动日志:对已有消息的每一笔改动(编辑、撤回、删除、表态增删、卡片落定)记一行,编号按会话递增。仓库给每个会话记一个改动水位:编号不大于它的改动,在区间(以及和它对齐的本机那一段)里的消息上都已生效。补洞调度从它往后取改动日志,见补洞调度 · 补改动。

  • 整窗换入时定下。 windowLoaded 的 changeSeq 是和这一窗同一快照读出的最新编号(列表响应的 head_change_seq;从本机读出的一窗是本机那一段记着的)。换入后改动水位就是它,可以比原来的小;不给时没有改动水位,这个会话不补改动、写入带的编号不记。
  • 一页、一批只会让它退。 olderLoaded、newerLoaded 的 changeSeq 是那一页的快照编号;比改动水位小时(这一页比已经记下的改动旧)改动水位退到它,之后补改动把这之后改过的消息重新取回。比它大时不动。
  • 带编号的写入只在号正好接上时推进它。 messageUpserted、messageDeleted、reactionChanged(实时推送)和 patchSettled(改动接口的响应)都可以带 changeSeq。没有改动水位、不给或为 0(没有新改动)时照常写入,改动水位不动。有改动水位 W 时:
编号 怎么处理
不大于 W,或之前已经收过 重复:什么都不做(表态不会多加一次,旧的整条也不会盖掉新的)。例外是只交回了编号的那一笔,见下。
等于 W + 1 照常写入,W 推到它;之前先到的、紧接着的号一并推过去。
大于 W + 1 照常写入、记下这个号,W 不动。缺的号要么随后到,要么由补洞调度的 changes 补。先到的号最多记 100 个,满了之后再来的照常写入但不记:W 推到它跟前就停下,等下一次补改动把它重新取回。

patchSettled 不会因为编号重复而不收尾。它带了 message 时那一笔的内容已经写进来了,之后同一个号的推送算重复;没带 message(表态接口只交回编号)时 W 照样推进,但同一个号的推送仍照常写入一次,把这次改动并进服务端那一版。

ChatStoreOlderLoadedEvent

interface ChatStoreOlderLoadedEvent {
  type: "olderLoaded";
  conversationId: string;
  beforeSeq: number;
  messages: readonly ChatMessage[];
  hasOlder: boolean;
  olderCursor?: string;
  changeSeq?: number;
}

取到更早的一页:往上翻历史,或从本机存储读出的更早一段,接到已加载区间前面。beforeSeq 是发请求时区间最早那条的 seq,这一页是紧挨在它之前的消息;beforeSeq 不在当前区间里(期间整窗换过)时,这一页和区间接不上,整页丢弃。changeSeq 是这一页的快照编号,比改动水位小时改动水位退到它,见改动水位与改动编号。

ChatStoreNewerLoadedEvent

interface ChatStoreNewerLoadedEvent {
  type: "newerLoaded";
  conversationId: string;
  afterSeq: number;
  messages: readonly ChatMessage[];
  hasNewer: boolean;
  newerCursor?: string;
  requestWatermark?: number;
  changeSeq?: number;
}

取到更新的一批:往下翻回新端的一页,或从水位补洞(loadThreadSince)取回的一批,接到已加载区间后面。afterSeq 是请求的起点,这一批是 seq 紧接在它之后的消息。

  • afterSeq 不大于区间末尾(最新那条的 seq;那条被删掉后仍按它算)时,这一批和区间接得上,新的消息接到后面。这一批说到头了(hasNewer: false)而末尾仍低于水位时,区间照旧标为没接到最新,除非带了 requestWatermark。
  • afterSeq 不大于水位时,这一批和水位接得上,水位推到这一批的最大 seq。
  • 两边都接不上时整批丢弃,水位不动。
  • hasNewer 只能来自服务端,拿不准给 true。
  • changeSeq 是这一批的快照编号,接得上区间时比改动水位小就让它退到这里,见改动水位与改动编号。

ChatStoreMessageUpsertedEvent

interface ChatStoreMessageUpsertedEvent {
  type: "messageUpserted";
  conversationId: string;
  message: ChatMessage;
  changeSeq?: number;
}

一条消息的新内容:编辑、撤回、表态汇总、卡片结果,或带正文的推送。

  • 这条已在仓库里:原地替换。内容版本更旧的(content_version 更小,或仓库里已撤回、已删除而它没有)不覆盖。
  • 这条被 messageDeleted 删掉过:忽略。
  • 不在仓库里,且正好是水位的下一条、区间接到最新:接到后面,水位推到它。
  • 不在仓库里、比水位新但接不上(中间缺了,或窗口没接到最新):不进窗口,只记下 newerPending,等补洞。
  • 其他(比水位旧、不在窗口里的):忽略。

带了 changeSeq 时先按改动水位判断:重复的什么都不做,见改动水位与改动编号。

ChatStoreMessageDeletedEvent

interface ChatStoreMessageDeletedEvent {
  type: "messageDeleted";
  conversationId: string;
  messageId: string;
  changeSeq?: number;
}

一条消息从仓库里删掉(硬删除;撤回不是删除,撤回走 messageUpserted)。水位不动。仓库记下这个 id:之后在途的一窗、一页、一批或推送再带回这条时不再写进来。区间覆盖的范围不因删除收窄,首条或末条被删后,紧挨着它取的一页照样接得上。本机数据打开着时,本机那条也删掉(内存里没有这个会话时也删)。带了 changeSeq 时先按改动水位判断,见改动水位与改动编号。

ChatStoreConversationClosedEvent

interface ChatStoreConversationClosedEvent {
  type: "conversationClosed";
  conversationId: string;
}

关掉一个会话:区间里的消息从内存去掉,只留水位。取数协调在一个会话的最后一个读者离开时发它。

  • 快照里只剩本端的消息,hasOlder、hasNewer 为 false,游标没有;watermark 和 newerPending 照旧。
  • 之后它按没加载过的会话处理:推送不接进来,只记下有新消息(newerPending);往新的一批不写;补洞调度不补它;换入一窗(再打开)时照常。删掉过的 id 仍记着,在途的数据带回它们时照旧不要。在途的改动作废。
  • 本机数据打开着时,区间里的消息早已逐次写进本机(见 openLocalData),再打开时从本机读回;关着期间来了改到其中消息的表态、编辑时,本机那一段作废(见 openLocalData),再打开时从后端取最新一窗。网页关着期间的改动没有推送到达,本机那一段不作废:再打开时由补洞调度按本机那一段记着的改动水位补回,见补洞调度 · 补改动。
  • 没有区间(没加载过、已经关掉)时什么都不做。改到了数据时订阅者收到一次 window。

ChatStoreViewChangedEvent

interface ChatStoreViewChangedEvent {
  type: "viewChanged";
  conversationId: string;
  anchorMessageId?: string;
}

当前视图停在哪条消息附近,供内存窗口超限时判断哪一端离视图最远。只是提示:不改数据、不通知订阅者、快照不变(没加载过的会话也是,提示留到第一窗换入时用)。anchorMessageId 不给表示清掉提示;没有提示(或那条已不在窗口里)时,超限卸掉的是刚插入那一端的另一端。

ChatStoreSendStartedEvent

interface ChatStoreSendStartedEvent {
  type: "sendStarted";
  conversationId: string;
  message: ChatMessage;
}

自己发出一条消息:先以「发送中」写进仓库,服务端确认之前就能显示。重试也用它,带着同一个 client_msg_id 再发一次。

  • 本端那条不进按 seq 排的已加载区间,不占 seq、不动水位,补洞看不到它;message.seq 仓库不看。
  • 快照里它排在已加载消息的最后(几条之间按发出的先后),区间没接到最新(hasNewer 为 true)时不显示;它的 id 就是 client_msg_id,delivery_status 为 sending。
  • 同一个 client_msg_id 的本端那条已在仓库里:失败或被拦下的回到「发送中」,位置不动;已确认的不再改。
  • 已加载区间里已有带这个 client_msg_id 的服务端消息:什么都不做。
  • message.client_msg_id 没有或为空串时 dispatch 抛 TypeError,什么都不改。没加载过的会话也可以发。

ChatStoreSendSettledEvent

type ChatStoreSendSettledEvent =
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "sent";
      message?: ChatMessage;
    }
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "failed";
    }
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "blocked";
      refusalText: string;
      seq?: number;
    };

一次发送的结果,按 clientMsgId 找到本端那条。服务端那条进了已加载区间(发送响应、推送、补洞、翻页、换窗任一路径)且和本端那条对得上(同一个 client_msg_id,或发送响应给的 id)时,本端那条在同一次写入里去掉、那一行换成服务端那条,不会出现两条;不按发送者、正文和时间去猜。

outcome 说明
sent 服务端确认了。带了服务端那条(message)时,它照 messageUpserted 的规则写进区间;暂时接不进区间(中间缺了)时本端那条换成服务端的内容、标成 sent、留在最后,等补洞把它带进区间;它在响应到达之前已被删掉(删除先到)时,本端那条去掉。没带时本端那条标成 sent、留在最后,等推送或补洞带回同一个 client_msg_id 的那条;服务端从不带回时,调补洞调度的 sent()。本端那条已不在仓库里时,只把 message 照 messageUpserted 写进来。
failed 发送失败。本端那条标成 failed,留在当时的位置(之后到的消息排在它后面),等重试。
blocked 被内容过滤拦下,服务端没有存。本端那条标成 blocked、带上 refusalText,排在 seq 那条之后(不给 seq 时留在当时的位置)。之后的补洞、换窗都不会冲掉它。

failed、blocked 只改还在发送中的本端那条:已确认的不会被改回失败。失败、被拦的那条所在位置不在当前这一窗里时(跳到了更早的一窗),这一窗里不显示它。不认识的 outcome 让 dispatch 抛 TypeError。

ChatStoreLocalMessageRemovedEvent

interface ChatStoreLocalMessageRemovedEvent {
  type: "localMessageRemoved";
  conversationId: string;
  clientMsgId: string;
}

去掉一条本端消息(发送中、失败、被拦或已确认还没对上的),比如用户删掉一条发送失败的消息。不影响已加载区间和水位;没有这条时什么都不做。

ChatStorePatchStartedEvent

interface ChatStorePatchStartedEvent {
  type: "patchStarted";
  conversationId: string;
  patchId: string;
  messageId: string;
  apply: (message: ChatMessage) => ChatMessage;
}

自己对一条消息动手(表态、编辑、撤回):先改仓库里那条,请求结束后用 patchSettled 收尾。

  • 仓库记下服务端给的那一版(底版)和这次改动,显示的是底版依次套上还没收尾的改动。改动期间服务端那条有新内容到达时(整条的 messageUpserted、一窗、一页、一批,或增量的 reactionChanged),换掉的是底版,改动重新套在新底版上;整条的新内容是否更旧只和底版比。
  • apply 收到冻结的消息,返回改好的新对象,不要改它收到的那个;可能被调用多次。
  • apply 必须幂等:套在已经包含这次改动的底版上,结果和底版相同(表态:自己已经点过这种就不再加,没点过就不减;编辑:把正文设成新的那份)。自己这次改动的推送可能先于请求的响应到达、先进了底版,幂等才不会把它套两次。
  • 别人的表态经 reactionChanged 写进底版,不要拿快照里的那条加上它再 messageUpserted:快照里那条已经套着改动,拿它当底版,失败时就退不掉这次改动了。
  • 只对已加载区间里的消息起作用;这条不在区间里、或 patchId 已在用时什么都不做。这条被卸掉、删掉或换窗时不在新一窗里,它的改动一并作废。

ChatStorePatchSettledEvent

interface ChatStorePatchSettledEvent {
  type: "patchSettled";
  conversationId: string;
  patchId: string;
  outcome: "succeeded" | "failed";
  message?: ChatMessage;
  changeSeq?: number;
}

一次改动的请求结束了。没有这个 patchId 时什么都不做;不认识的 outcome 让 dispatch 抛 TypeError。

outcome 说明
succeeded 带了服务端返回的那条(message)时,它成为新底版、这次改动去掉。没带时这次改动继续套在底版上,直到服务端那条下一次有整条的新内容到达(那时服务端已经包含这次改动),或底版已经包含它(套上去不变,比如自己这次表态的推送到了)而它前面没有还套着的改动。
failed 去掉这次改动,退回底版(连同其他还没收尾的改动)。期间经写入口到达的服务端新内容(整条的新内容、reactionChanged 写进来的表态)在底版里,不会被退掉:别人期间点的表态还在,编辑失败时正文回到服务端那一版。

changeSeq 是改动接口响应里的编号,只对 succeeded 有用,0 表示没有新改动(比如重复的表态)。它按改动水位与改动编号推进改动水位,只是不会因为重复而不收尾。

ChatStoreReactionChangedEvent

interface ChatStoreReactionChangedEvent {
  type: "reactionChanged";
  conversationId: string;
  messageId: string;
  reactorId: string;
  code: string;
  added: boolean;
  byMe: boolean;
  unicodeFallback?: string;
  changeSeq?: number;
}

一条消息上的一次表态变化(实时信号里的增量:谁、哪种、加还是减),直接改服务端那一版(底版)。byMe 是 reactorId 等于当前用户;unicodeFallback 是新建这一种时的字形,不给时用 code。

  • 加:没有这种时新建一项(人数 1);有时人数加 1、名单不满 20 个时记上这个人。减:人数减 1、名单里去掉这个人,减到 0 时去掉这一项。reacted_by_me 只跟着 byMe 的变化走。不动 content_version。
  • 幂等:加一个已经记着的(这个人已在 reactor_ids 里,或自己的而 reacted_by_me 已为真)、减一个没记着的(自己的而 reacted_by_me 为假,或别人的不在名单里、名单也没被截断)都什么都不做,所以重复的推送、自己那次表态先由请求的响应写进来过都不会算两次。例外:名单被截断(满 20 个)时,名单外的人重复发来的「加」或「减」查不出是重复,会多加或多减;服务端只给前 20 个人,仓库这一层没法分辨。
  • 有在途改动时改的是底版,改动重新套上,所以改动失败退回时这次表态还在。
  • 只对已加载区间里的消息起作用;不在区间里(包括本端的消息)时什么都不做:那条下次被取回时带着服务端的汇总。
  • 带了 changeSeq 时先按改动水位判断:同一个号的推送重复到达时不再加减一次,名单被截断时也一样,见改动水位与改动编号。

ChatStoreCardChangedEvent

interface ChatStoreCardChangedEvent {
  type: "cardChanged";
  conversationId: string;
  messageId: string;
  card: Partial<Pick<ChatMessage, "card_body" | "card_preview" | "card_truncated" | "card_superseded" | "card_expired" | "card_state">>;
  changeSeq?: number;
}

一条消息上卡片那几格的新值(自己作答后带回的落定记录、重读回来的卡片字段),直接改服务端那一版(底版)。

  • card 里给了的键照写,值为 undefined 即去掉那一格;没给的键不动。
  • card_state 例外:落定记录只认第一份,底版已有时不覆盖,给 undefined 也不清(作答后的读取可能比落定发得早、回得晚)。
  • 写进去和原来一样时不通知。不动 content_version。
  • 有在途改动时改的是底版,改动重新套上。
  • 只对已加载区间里的消息起作用;不在区间里(包括本端的消息)时什么都不做:那条下次被取回时带着服务端的卡片字段。内存里没有那条、本机那份又没跟着改时,本机那一段作废(同 reactionChanged)。
  • 带了 changeSeq(别人作答那一帧的编号)时先按改动水位判断:已收过的号整笔不写(卡片字段是帧之后读回的,仓库里已经反映过这一笔),否则照写并记下编号,见改动水位与改动编号。