写入事件
唯一写入口收的 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(别人作答那一帧的编号)时先按改动水位判断:已收过的号整笔不写(卡片字段是帧之后读回的,仓库里已经反映过这一笔),否则照写并记下编号,见改动水位与改动编号。
