补洞调度
createChatGapFillScheduler 和它的参数、读接口、各个时刻的入口与结果。
补洞调度
@openmaxai/chat-store 根入口里关于补洞调度的导出。状态、在宿主里怎么接和全部导出的索引见概览。
补洞调度决定什么时候、从哪个 seq 往后取,取回来的经仓库的写入口写回。它不发请求(读接口由调用方注入),不碰 DOM,不读时间;唯一的计时器是按 id 取失败后重发之前的退避(见补改动)。补洞的时刻和规则见实时与同步 · 补洞。
一次补洞按仓库里这个会话此刻的状态走:
- 区间接到最新,或补到一半(之前的补洞从水位接上过一批、服务端说还有):从水位往后取,接到区间后面。
- 区间被告知到了最新、末尾却低于水位(迟到的一窗,或水位那条被删掉了):从区间末尾按
seq往后取。 - 其他(没加载过、还没有水位、围着某条取的一窗、往上翻卸掉了新端):不补。窗口没接到最新时只靠
newerPending提示有新消息;开了latestWindowOnGap时,这期间的messages信号改为取一次最新那一窗。
每一轮都带上发请求时的水位(requestWatermark)。同一会话的一次补洞最多调 10 次 loadThreadSince;到了上限还没补完,取一次最新一窗,这次补洞就此结束:这一窗和区间接得上(最老那条的 seq 不大于这一轮取的起点加一:起点通常是水位,区间停在水位之下时是区间末尾)时接在区间后面,重叠段里发请求时已有、这一窗里却没有的按删除处理;接不上(中间还有缺口)才整窗换入。「补到一半」记在仓库里,不记在调度器里:上一次补洞中途失败,或调度器停下后在同一个仓库上新建了一个,下一次补洞照样从水位接着取。
窗口没接到最新时取最新那一窗
建调度器时给了 latestWindowOnGap,窗口有区间、没接到最新(围着某条取的一窗、往上翻卸掉了新端;不是补到一半,也不是末尾低于水位)期间来了 messages 信号时,这次补洞改为取一次最新那一窗:source.loadThread(id, undefined, { limit })。仍不往缺口里按 seq 补。
- 接得上(最老那条的
seq不大于区间末尾加一):接到区间后面,重叠段里发请求时已有、这一窗里却没有的按删除处理,区间接到最新。随后再补一次,从水位往后补取回之后又到的。结果是reloaded、rounds为 0。 - 接不上(中间还有缺口):不进仓库,按会话留着(同一会话只留最新取回的那一份),结果是
skipped。同一仓库上的取数协调器往更新翻(loadNewer)之前先按那时的区间末尾判一次,接得上就当场接上、不发请求;否则照常翻一页,翻回来之后再判一次。接上之后同样再补一次洞。 - 回来的一窗带往更新的游标(
newerCursor)时当它不是最新那一窗、丢掉。 - 取的途中会话关掉了、窗口已接到最新、会话被清掉了(
clearConversation):丢掉(interrupted)。close这个会话、调度器停下时,留着的那一窗也丢掉;会话被清掉时也作废(会话没关、之后又围着某条取了一窗,往更新翻时也不再接上它)。 - 重连、回到前台、打开会话、发送之后不取。同一会话不并发的规则照旧:取的途中再来的信号只并成再补一次。
不给 latestWindowOnGap 时与以前一样:这期间的 messages 信号得到 skipped,一发都不取。
补改动
补洞只取比水位新的消息,离开、断线期间别人对已有消息的改动(编辑、撤回、删除、表态增删、卡片落定)不在其中。读接口有 loadChangesSince 和 getMessagesByIds 时,每次补完新消息接着补改动,结果记在 ChatGapFillResult 的 changes 里:
- 从这个会话的改动水位(见写入事件 · 改动水位与改动编号)往后取改动日志,一页接一页,取到
hasMore为假。 - 挑出改到的、落在持有范围里的消息:比区间和本机那一段都旧的不取,比水位新的没有持有、也不取。去重后按 100 个一批按 id 取回,说要再取的(
deferredIds)排到后面再取。 - 取回的写进仓库:区间里有的按 id 合并,内存里没有、本机那一段里有的写进本机;说不在了的(
missingIds)按删除处理。 - 写回之后才推进改动水位,推到改动日志取到头时的最新编号。本机那一段的改动水位记在段记录里,和消息排在同一个写入队里、排在消息之后,所以本机的改动水位不会跑在消息前面。
几种例外:
- 太旧了。 改动日志说
tooOld(超过保留期,或改动水位比最新编号还大),或一轮要取的超过 10 页:作废本机那一段,换入最新一窗,改动水位用这一窗的headChangeSeq。窗口没接到最新(跳到了某条)时不换掉正在看的那一窗,只作废本机那一段和改动水位。 - 取回期间先到了更新的推送。 按 id 取回的那一版是请求时的快照,比它新、已经先写进来的推送可能被它盖掉:这时改动水位只推到取回时的编号,再补一轮把它们重新取回,最多 3 轮;3 轮之后仍是这样时停下(
incomplete),等下一个时刻。 - 期间换了一窗、关掉了会话: 取回的不写进仓库(
interrupted)。 - 按 id 取失败。 某一批 reject、错误带
retryable: true(如@openmaxai/chat-sdk的ChatSdkError断网、超时、服务暂不可用、限流)时,等 1 秒重发同一批,再失败等 2 秒再发,一批最多发 3 次。别的错误(凭据失效、无权限、不存在、没带retryable: true的)不重发。退避期间调度器停下(dispose)、关掉了这个会话(close)或换入了一窗时不再重发。都没成时这次补改动以最后那次的错误结束(failed),改动水位不动:下一次补洞从同一个改动水位重新列出这几笔、再取一次。 - 换了用户: 取回的照样写进内存,不写进新用户的本机,本机的改动水位也不推。
实时推送带改动编号时按写入事件 · 改动水位与改动编号推进改动水位;推送跳了号(缺的那几笔没到)时调 changes。
createChatGapFillScheduler
function createChatGapFillScheduler(options: ChatGapFillSchedulerOptions): ChatGapFillScheduler;
建一个补洞调度器。options.store 不是 createChatStore 建的仓库时抛 TypeError。
ChatGapFillSchedulerOptions
interface ChatGapFillSchedulerOptions {
store: ChatStore;
source: ChatGapFillSource;
latestWindowOnGap?: {
limit?: number;
};
}
| 字段 | 说明 |
|---|---|
store |
写回哪个仓库,必须是 createChatStore 建的。补到一半的进度记在仓库里:停下旧的调度器、在同一个仓库上新建一个,接着补不受影响。 |
source |
取数接口。 |
latestWindowOnGap |
窗口没接到最新期间来了 messages 信号时取一次最新那一窗,见窗口没接到最新时取最新那一窗。limit 作为第三参 { limit } 交给 source.loadThread(上限提示,可以不认),不给时第三参不传。不给这个选项时不取。 |
ChatGapFillSource
interface ChatGapFillSource {
loadThreadSince?(conversationId: string, afterSeq: number): Promise<readonly ChatMessage[] | ChatGapFillSincePage>;
loadThread(conversationId: string, cursor?: undefined, options?: {
limit?: number;
}): Promise<ChatGapFillLatestPage>;
loadChangesSince?(conversationId: string, sinceChangeSeq: number): Promise<ChatGapFillChangesPage>;
getMessagesByIds?(conversationId: string, messageIds: readonly string[]): Promise<ChatGapFillMessagesPage>;
}
补洞要用的两个读接口,由调用方注入(仓库不发请求,也不认识宿主)。形状和宿主的 messaging 相同,可以直接把宿主的 messaging 交进来。
| 成员 | 说明 |
|---|---|
loadThreadSince |
取 seq 大于 afterSeq 的消息,升序。可以返回数组,也可以返回 ChatGapFillSincePage;返回数组时空数组表示没有更新的了。失败时 reject:这次补洞静默放弃,下一个时刻从水位接着补。不给时不补洞。 |
loadThread |
取最新一窗(不带游标)。补了 10 轮还没补完时取它(接得上接在后面,接不上整窗换入);改动日志说太旧了时用它换入最新一窗。开了 latestWindowOnGap 时窗口没接到最新期间也取它,第二参是 undefined、第三参带 limit(给了时);回来的一窗带 newerCursor 时丢掉。只收一个参数的实现照样能用。 |
loadChangesSince |
取改动日志里编号大于 sinceChangeSeq 的一页,同 GET /conversations/{id}/changes。sinceChangeSeq 不含本号,0 表示从第一笔起。和 getMessagesByIds 都给了才补改动,只给一个等于没给。 |
getMessagesByIds |
按 id 取消息的最新一版,同 POST /conversations/{id}/messages/batch-get。每次至多 100 个、互不重复的 id:服务端按去重之前的个数算上限,调度器先去重再分批。失败时 reject;错误带 retryable: true 时调度器退避后重发同一批,最多发 3 次(见补改动)。 |
ChatGapFillSincePage
interface ChatGapFillSincePage {
messages: readonly ChatMessage[];
hasNewer: boolean;
headChangeSeq?: number;
}
从水位往后取的一批,同宿主 messaging.loadThreadSince 返回的对象形式。messages 是 seq 大于请求的 afterSeq 的消息,按 seq 升序;hasNewer 只能来自服务端,拿不准给 true。headChangeSeq 是和这一批同一快照读出的改动编号(列表响应的 head_change_seq),比改动水位小时改动水位退到它;不给时不动改动水位。
ChatGapFillLatestPage
interface ChatGapFillLatestPage {
messages: readonly ChatMessage[];
nextCursor?: string;
headChangeSeq?: number;
}
最新一窗,同宿主 messaging.loadThread(不带游标)的返回值。messages 按 seq 升序;还有更早的消息时给 nextCursor,不给表示到头了。headChangeSeq 是和这一窗同一快照读出的改动编号(列表响应的 head_change_seq):换入这一窗时它就是这个会话的改动水位,不给时没有改动水位、这个会话不补改动。
ChatGapFillChange
interface ChatGapFillChange {
changeSeq: number;
messageId: string;
messageSeq: number;
}
改动日志里的一条:会话里一条已有的消息被改过。changeSeq 是这一笔的编号,按会话递增;messageSeq 是那条消息的 seq,比持有范围更旧的不取。
ChatGapFillChangesPage
interface ChatGapFillChangesPage {
changes: readonly ChatGapFillChange[];
nextSinceChangeSeq: number;
hasMore: boolean;
headChangeSeq: number;
tooOld: boolean;
}
改动日志的一页,同 GET /conversations/{id}/changes 的响应。
| 字段 | 说明 |
|---|---|
changes |
编号大于请求的 sinceChangeSeq 的改动,按编号升序;同一条消息在一页里只留最后一笔。tooOld 时为空。 |
nextSinceChangeSeq |
这一页扫到的最大编号,下一页从它往后取;空页时等于请求的 sinceChangeSeq。hasMore 为真而它没有往前走时,这次补改动失败。 |
hasMore |
后面还有。 |
headChangeSeq |
和 changes 同一快照读出的最新编号。补完后改动水位推到最后一页的它。 |
tooOld |
请求的位置已被清理(超过保留期),或比最新编号还大(编号来自别处):增量取不了,要整段重取。 |
ChatGapFillMessagesPage
interface ChatGapFillMessagesPage {
messages: readonly ChatMessage[];
missingIds: readonly string[];
deferredIds: readonly string[];
headChangeSeq: number;
}
按 id 取回的一批,同 POST /conversations/{id}/messages/batch-get 的响应。messages 是找到的消息的最新一版(撤回的是墓碑),missingIds 是不在了的 id(删掉了、不属于这个会话),deferredIds 是这一次没返回、要再取一次的 id(超出了单次响应的卡片上限),headChangeSeq 是和 messages 同一快照读出的改动编号。服务端在一批里有卡片时每次只交回一部分、其余放进 deferredIds,这是正常的分页,要取多少次就取多少次;连着 10 次以上一条都没交回(没有 messages、也没有 missingIds)时,这次补改动失败。
ChatGapFillScheduler
interface ChatGapFillScheduler {
open(conversationId: string): Promise<ChatGapFillResult>;
close(conversationId: string): void;
reconnected(): Promise<ChatGapFillResult[]>;
foreground(): Promise<ChatGapFillResult[]>;
catchUp(): Promise<ChatGapFillResult[]>;
messages(conversationId: string): Promise<ChatGapFillResult | undefined>;
sent(conversationId: string): Promise<ChatGapFillResult>;
changes(conversationId: string): Promise<ChatGapFillResult | undefined>;
dispose(): void;
}
同一会话不并发:正在补时又来了触发,等这一次补完再从新的水位补一次,期间再来的触发都并进这一次,拿到同一个结果。返回的 promise 不会 reject。每一次补洞都是先补新消息、再补改动(读接口有改动日志时)。
| 方法 | 说明 |
|---|---|
open(conversationId) |
打开会话,或切回一个打开过的会话:记为打开着,补一次。 |
close(conversationId) |
切走或关掉会话:之后重连、回到前台和 messages 信号不再补它;在途的那次照样做完,只是按 id 取失败后正等着重发的不再重发。 |
reconnected() |
实时连接重连成功:每个打开着的会话补一次。 |
foreground() |
页面从后台回到前台:每个打开着的会话补一次。 |
catchUp() |
宿主在没发生什么的时候要求补一次(连接看着开着时的定时补拉、恢复联网):每个打开着、此刻没在补的会话补一次。正在补的跳过、不排队,返回的列表里没有它。不表示有新消息。它是给定时器用的,没有改动时每个会话只发一个请求:补新消息补到最新、那一页的 headChangeSeq 不高于改动水位时,不读改动日志(changes 记 caughtUp、rounds 为 0)。 |
messages(conversationId) |
这个会话有新消息(messages 信号):打开着的补一次;没打开的不补、返回 undefined,切回时再补。 |
sent(conversationId) |
发送成功、服务端那条没有交回来(sendSettled 没带 message):不管会话打没打开,从水位补一次。这次补洞在调用之后才发请求,补到最新(caughtUp、reloaded)时服务端那条已在区间里,调用时已确认、还没对上的本端消息经写入口去掉;没补到最新时它们留着,之后任何一次补到最新的补洞(不管由哪个时刻触发)都会去掉开始补之前已确认、还没对上的本端消息。 |
changes(conversationId) |
实时推送的改动跳了号(改动编号大于改动水位加一,缺的那几笔没到):打开着、仓库里仍有缺口的补一次;其他情况不补、返回 undefined。推送之间跨消息乱序是常态,收到带改动编号的推送后等 1–2 秒再调它,缺的号这期间到齐了就不补。 |
dispose() |
停下:之后不再发请求,在途请求的结果不再写进仓库。在途的那次补洞先看请求成没成:请求成功时得到 disposed,请求失败时仍得到 failed。打开着的会话一并清掉,所以之后 open 直接得到 disposed,reconnected、foreground 返回 [],messages 信号返回 undefined。 |
ChatGapFillResult
interface ChatGapFillResult {
conversationId: string;
outcome: ChatGapFillOutcome;
rounds: number;
error?: unknown;
changes?: ChatGapFillChangesResult;
}
一个会话的一次补洞的结果。rounds 是这次补洞调了几次 loadThreadSince(不含取最新一窗那一次),最多 10;error 只在 outcome 为 failed 时有,是请求 reject 的原因。outcome 只说补新消息那一步;补改动那一步的结果在 changes 里,读接口有改动日志、调度器没停下时才有。
ChatGapFillOutcome
type ChatGapFillOutcome =
| "caughtUp"
| "reloaded"
| "skipped"
| "interrupted"
| "failed"
| "disposed";
| 值 | 说明 |
|---|---|
caughtUp |
服务端说没有更新的了,区间接到了最新。 |
reloaded |
10 轮之后服务端仍说还有(或区间仍停在水位之下),取了最新一窗:和区间接得上时接在后面,接不上时整窗换入。开了 latestWindowOnGap 时,窗口没接到最新期间取回的最新那一窗接到了区间后面也是它(rounds 为 0)。 |
skipped |
没有要补的:没加载过、已关掉(conversationClosed)、还没有水位、窗口没接到最新,或没有 loadThreadSince。开了 latestWindowOnGap 时,取回的最新那一窗接不上、先留着(或不是最新那一窗、丢掉)也是它。 |
interrupted |
补到一半时窗口换成了没接到最新的一窗(比如跳到了某条消息),在途那一批(或最新一窗)不写进仓库,那一窗保持原样。开了 latestWindowOnGap 时,取最新那一窗的途中会话关掉了、窗口已接到最新、会话被清掉了也是它。 |
failed |
请求失败,见 error。 |
disposed |
调度器已停下。停下时在途的那次补洞只有请求成功才得到它,请求失败时得到 failed。 |
ChatGapFillChangesResult
interface ChatGapFillChangesResult {
outcome: ChatGapFillChangesOutcome;
rounds: number;
error?: unknown;
}
一次补改动的结果。rounds 是取了几轮改动日志(每轮从当时的改动水位取到头、再按 id 取回),最多 3;error 只在 outcome 为 failed 时有,是请求 reject 的原因(按 id 取重发过的是最后那次的;或改动日志没往前走、按 id 取连着 10 次以上一条都没交回)。
ChatGapFillChangesOutcome
type ChatGapFillChangesOutcome =
| "caughtUp"
| "reloaded"
| "skipped"
| "incomplete"
| "interrupted"
| "failed"
| "disposed";
| 值 | 说明 |
|---|---|
caughtUp |
改动日志取到了头,改到的消息都取回、写进了仓库,改动水位推到了这次取到的编号。 |
reloaded |
改动日志说太旧了(或一轮要取的超过 10 页),作废了本机那一段、换入了最新一窗。 |
skipped |
没有要补的:没加载过、已关掉、没有改动水位(换入的一窗没带 headChangeSeq)。 |
incomplete |
补了 3 轮,期间不断有比取回那一版新的推送先到,改动水位停在最后取到的编号,等下一个时刻再补。 |
interrupted |
补的期间这个会话换了一窗、关掉了,取回的不写进仓库;或改动日志说太旧了、而窗口没接到最新:只作废本机那一段,不换掉正在看的那一窗。 |
failed |
请求失败,见 error;按 id 取可以重试的已重发到 3 次(或退避期间停下、关掉、换了一窗)。改动水位不动。 |
disposed |
调度器已停下。 |
