检查接口
只读检查接口 @openmaxai/chat-store/inspect:每个会话和全局(存储、实时信号)的检查快照,以及仓库事件流。调试面板就建在它上面。
检查接口
@openmaxai/chat-store/inspect 入口的导出:只读检查接口。状态、在宿主里怎么接和全部导出的索引见概览。
检查接口让仓库之外的代码看到仓库此刻的内部状态:一个会话的窗口、缺口、补洞和补改动的进度、本端消息,本机存储用的是什么,以及按顺序发生的每一次改动:经 dispatch 的写入,和不经 dispatch 的那些(本机写完、补改动写回、补洞排队、会话打开关掉、收到实时信号)。它只读,不改变仓库的任何行为。调试面板就建在它上面;你也可以用它写自己的诊断、把状态附进错误报告。
它在单独的入口里,不依赖 React,也不依赖其它聊天包。根入口 @openmaxai/chat-store 的导出和 ChatStore 接口都不因它变,不用检查接口的应用不用改任何代码。
inspect-example.ts
import { inspectChatStore } from "@openmaxai/chat-store/inspect";
const inspector = inspectChatStore(store);
// 一个会话此刻的状态
const c = inspector.getConversation(conversationId);
console.log(c.window.fromSeq, c.window.toSeq, c.window.gaps, c.gapFill.running);
// 全局:本机存储、实时信号
console.log(inspector.getGlobal().storage.inUse);
// 仓库事件流
const unsubscribe = inspector.subscribe((record) => {
if (record.kind === "event") console.debug(record.event.type, record.change);
});
保证
- 只读。 检查器上没有能写的方法。返回的快照和里面的数组、对象都是冻结的副本;没有变化时
getConversation、getGlobal返回同一个对象,变了的那份里没变的部分也还是原来的对象。事件流里的event是交给dispatch的那个对象本身,change是订阅者收到的那个对象本身,不要改它们。 - 不改变仓库的行为。 检查器不调
ChatStorage,不进本机数据的读写队列,不发请求,不改订阅者收到通知的次数和顺序,也不改补洞调度返回的结果(gapFill.last.result是冻结的副本)。estimateStorage只调浏览器的navigator.storage.estimate()。 - 快照的每一次变化都有一条记录。
getConversation、getGlobal返回的任何字段变了,事件流里正好有一条记录宣告它:是那次改动本身的记录(一次dispatch的event、补洞开始结束的gapFill、本机数据的localData),不经这几条路的改动是一条kind: "snapshot"的记录(见ChatStoreInspectRecord)。一次操作同时改了几个字段只有一条;反过来,有的记录什么都没改(比如change为undefined的event)。记录在改动生效之后同步发出,所以把subscribe和getConversation/getGlobal交给useSyncExternalStore是安全的:不会漏掉一次变化,没变时拿到同一个对象、不重渲染。一次本机打开、清掉的中途(换用户时先关上一个用户的库)变的存储字段,由它做完时的那条记录宣告。 - 没人看时几乎没有开销。 第一次对一个仓库调
inspectChatStore之前,仓库只常记一项:IndexedDB 存储改用内存的原因(它发生在openLocalData,通常早于检查开始;一个枚举),此外不为检查多记任何东西,也不读时钟。之后每个会话多记几项(上一次补洞和补改动的结果、服务端最新改动编号)、全局几个计数;记下一个时间(补洞的开始和结束、补改动结束、实时信号、写失败)时读一次时钟,每条记录再读一次;事件流的记录只在有人订阅时才创建。读快照的开销和本端消息、在途改动、先到的改动编号的个数成正比,和窗口里有多少条消息无关。 - 事件就是仓库收到的那些。 每次
dispatch调用(包括补洞调度、取数协调和本机读回在包内发出的)正好一条kind: "event"的记录,顺序和调用顺序相同(订阅者回调里再dispatch也是),什么都没改的也有(change为undefined)。被拒的事件(dispatch抛TypeError的)也有一条,带error,异常照样抛给调用方。 - 同步送达,坏的回调不连累仓库。 回调在那次
dispatch改完数据、通知完仓库的订阅者之后同步调用。回调抛出的异常被接住,在下一个宏任务里交给reportError(没有时重新抛出),不影响这次dispatch,也不影响其它回调。回调里不要调dispatch。
inspectChatStore
function inspectChatStore(store: ChatStore): ChatStoreInspector;
拿到 store 的检查器,并从此刻起开始记检查要用的东西(见保证)。同一个仓库再调返回同一个检查器。store 必须是 createChatStore 建的,否则抛 TypeError。
ChatStoreInspector
interface ChatStoreInspector {
getConversation(conversationId: string): ChatStoreConversationInspection;
getGlobal(): ChatStoreGlobalInspection;
subscribe(listener: ChatStoreInspectListener): () => void;
estimateStorage(): Promise<ChatStoreStorageEstimate | undefined>;
}
| 方法 | 说明 |
|---|---|
getConversation(conversationId) |
一个会话此刻的检查快照。仓库里没有这个会话时 loaded 为 false,其余字段是空值(open 也为 false);没变的会话(包括没加载过的)每次返回同一个对象 |
getGlobal() |
全局的检查快照 |
subscribe(listener) |
订阅事件流,返回取消订阅的函数,重复调用无害。只收到订阅之后的记录:仓库不缓存记录,要看之前的就早点订阅 |
estimateStorage() |
浏览器估计的存储用量和配额。浏览器没有 navigator.storage.estimate、或它失败时得到 undefined;不会 reject |
快照什么时候该重读:任何一条记录到达之后(见保证:快照的每一次变化都有一条记录)。getConversation、getGlobal 在没变化时返回同一个对象,所以收到记录后重读、按引用比较即可;检查器的方法不依赖 this,可以单独拿出来传。在 React 里可以直接这样写:
use-inspection.ts
const conversation = useSyncExternalStore(inspector.subscribe, () =>
inspector.getConversation(conversationId),
);
ChatStoreConversationInspection
interface ChatStoreConversationInspection {
readonly conversationId: string;
readonly loaded: boolean;
readonly open: boolean;
readonly window: ChatStoreWindowInspection;
readonly gapFill: ChatStoreGapFillInspection;
readonly changeLog: ChatStoreChangeLogInspection;
readonly sends: readonly ChatStoreSendInspection[];
readonly patches: readonly ChatStorePatchInspection[];
readonly local: ChatStoreLocalSegmentInspection;
}
| 字段 | 说明 |
|---|---|
loaded |
仓库里有这个会话(加载过,或发过消息) |
open |
有补洞调度器把它记为打开着(open 之后、close 之前) |
window |
内存里的区间,见 ChatStoreWindowInspection |
gapFill |
补洞的进度,见 ChatStoreGapFillInspection |
changeLog |
改动水位和补改动的进度,见 ChatStoreChangeLogInspection |
sends |
本端的消息,按发出的先后,见 ChatStoreSendInspection |
patches |
在途的改动,按开始的先后,见 ChatStorePatchInspection |
local |
本机那一段,见 ChatStoreLocalSegmentInspection |
ChatStoreWindowInspection
interface ChatStoreWindowInspection {
readonly count: number;
readonly limit: number;
readonly fromSeq: number | undefined;
readonly toSeq: number | undefined;
readonly hasOlder: boolean;
readonly hasNewer: boolean;
readonly watermark: number | undefined;
readonly catchingUp: boolean;
readonly gaps: readonly ChatStoreGap[];
}
| 字段 | 说明 |
|---|---|
count、limit |
区间里的服务端消息条数和上限(500)。本端的消息不算 |
fromSeq、toSeq |
区间覆盖的 seq 范围。删掉消息不收窄它;会话关掉后没有 |
hasOlder、hasNewer、watermark |
同会话快照 |
catchingUp |
从水位补到一半:服务端说后面还有,补洞会从水位接着取。这时 hasNewer 也为 true |
gaps |
仓库知道还没拿到的 seq 段,见 ChatStoreGap。没有缺口时是空数组 |
已加载区间之内没有缺口:区间里缺的号是删掉的消息,仓库按已删掉算。
ChatStoreGap
interface ChatStoreGap {
readonly kind: "behindWatermark" | "pendingPush";
readonly afterSeq: number;
readonly throughSeq: number;
}
一段还没拿到的 seq,afterSeq 不含、throughSeq 含。behindWatermark:区间被告知到了最新、末尾却低于水位,缺的是 toSeq 到水位之间;pendingPush:推送来过比水位新的消息、没能接进区间,缺的是水位到那条推送之间(还没有水位时从区间末尾算)。
ChatStoreGapFillInspection
interface ChatStoreGapFillInspection {
readonly running: boolean;
readonly rerunQueued: boolean;
readonly last: ChatStoreGapFillRun | undefined;
}
| 字段 | 说明 |
|---|---|
running |
有补洞调度器正在补这个会话 |
rerunQueued |
补的期间又来了触发,这一次补完会再补一次 |
last |
上一次补完的那次,见 ChatStoreGapFillRun。开始检查之后还没补完过时没有;开始检查之前就已开始的那次补完时也不记(没记下它的开始) |
ChatStoreGapFillRun
interface ChatStoreGapFillRun {
readonly trigger: ChatGapFillTrigger;
readonly result: ChatGapFillResult;
readonly startedAt: number;
readonly settledAt: number;
}
补完的一次补洞:哪个时刻触发的、结果(冻结的副本)、开始和结束的时间(毫秒时间戳)。补的期间又来了触发时,接着补的那一次是单独的一次。
ChatGapFillTrigger
type ChatGapFillTrigger =
| "open"
| "reconnected"
| "foreground"
| "catchUp"
| "messages"
| "sent"
| "changes";
触发补洞的时刻:补洞调度器上同名的那个方法。补的期间又来的几次触发并成接着补的那一次,记其中第一个。
ChatStoreChangeLogInspection
interface ChatStoreChangeLogInspection {
readonly watermark: number | undefined;
readonly serverHead: number | undefined;
readonly ahead: readonly number[];
readonly lastCatchUp: ChatStoreCatchUpRun | undefined;
}
| 字段 | 说明 |
|---|---|
watermark |
改动水位:编号不大于它的改动在区间里都已生效。没有时这个会话不补改动 |
serverHead |
最近一次从服务端读到的最新改动编号(一窗、一页、一批、改动日志的一页或按 id 取回的一批里带的 headChangeSeq;从本机读回的不算)。开始检查之后还没读到过时没有 |
ahead |
比改动水位加一大、已经写入过的改动编号,升序:中间还缺号 |
lastCatchUp |
上一次补改动,见 ChatStoreCatchUpRun |
ChatStoreCatchUpRun
interface ChatStoreCatchUpRun {
readonly outcome: ChatGapFillChangesOutcome;
readonly rounds: number;
readonly fetched: number;
readonly missing: number;
readonly tooOld: boolean;
readonly at: number;
}
上一次补改动:结果、取了几轮改动日志、按 id 取回了几条、说不在了几条(几轮合计)、服务端是否说太旧了(tooOld;一次要取的超过 10 页也算),以及结束的时间。读接口没有改动日志时不补改动,也就没有它。
ChatStoreSendInspection
interface ChatStoreSendInspection {
readonly clientMsgId: string;
readonly status: ChatMessageDeliveryStatus;
readonly messageId: string;
readonly serverId: string | undefined;
}
| 字段 | 说明 |
|---|---|
clientMsgId |
这条本端消息的 client_msg_id |
status |
它此刻的 delivery_status:发送中、失败、被拦,或已确认、服务端那条还没对上 |
messageId |
快照里这条消息的 id |
serverId |
发送响应或推送给的服务端那条的 id,还不知道时没有 |
不含消息正文。要正文,用 messageId 从 getSnapshot 里取。
ChatStorePatchInspection
interface ChatStorePatchInspection {
readonly patchId: string;
readonly messageId: string;
readonly committed: boolean;
}
| 字段 | 说明 |
|---|---|
patchId |
这笔改动的 patchId(patchStarted 给的);同一条消息有几笔在途改动时各一行 |
messageId |
改的是哪一条 |
committed |
改动的请求已成功,在等服务端那条带回新内容 |
ChatStoreLocalSegmentInspection
interface ChatStoreLocalSegmentInspection {
readonly writing: boolean;
readonly fromSeq: number | undefined;
readonly toSeq: number | undefined;
}
| 字段 | 说明 |
|---|---|
writing |
区间和本机那一段对齐着,之后区间的变化逐次写进本机(见写进本机) |
fromSeq、toSeq |
对齐时本机那一段的 seq 范围 |
ChatStoreGlobalInspection
interface ChatStoreGlobalInspection {
readonly conversations: readonly string[];
readonly openConversations: readonly string[];
readonly storage: ChatStoreStorageInspection;
readonly realtime: ChatStoreRealtimeInspection;
}
| 字段 | 说明 |
|---|---|
conversations |
仓库里有的会话 |
openConversations |
补洞调度器记为打开着的会话,按打开的先后(几个调度器打开同一个会话时按最早的那次) |
storage |
本机存储,见 ChatStoreStorageInspection |
realtime |
实时信号,见 ChatStoreRealtimeInspection |
ChatStoreStorageInspection
interface ChatStoreStorageInspection {
readonly configured: "memory" | "indexedDb" | "custom";
readonly inUse: "memory" | "indexedDb" | "custom" | undefined;
readonly fallbackReason: "lockHeld" | "noWebLocks" | "noIndexedDb" | "openFailed" | undefined;
readonly tabLock: "held" | "notHeld" | "notApplicable";
readonly encrypted: boolean;
readonly state: "closed" | "opening" | "open";
readonly userId: string | undefined;
readonly pendingWrites: number;
readonly lastWriteError: ChatStoreWriteError | undefined;
readonly evictedConversations: number;
}
| 字段 | 说明 |
|---|---|
configured |
localData.storage 配的是什么:createMemoryStorage()(不配时也是它)、createIndexedDbStorage(),还是你自己实现的 ChatStorage(把包里的存储展开包一层的也算自己实现的) |
inUse |
实际在用的。配了 IndexedDB 时可能是 memory,原因在 fallbackReason:lockHeld 另一个标签页拿着锁,noWebLocks 浏览器没有 Web Locks(或取锁本身出错),noIndexedDb 没有 IndexedDB,openFailed 库打不开;改用内存后这个存储一直用内存,直到页面刷新。本机数据没打开时没有 |
tabLock |
这个标签页是否拿着本机数据的锁;不是 IndexedDB 存储时为 notApplicable |
encrypted |
配了 localData.encryption,且在用的是会加密的库 |
state、userId |
本机数据关着、正在打开还是开着(openLocalData 调用当下就是正在打开,打开好之前一直是),以及是哪个用户的(openLocalData 给的 id) |
pendingWrites |
排在本机数据队里、还没写完的写入(开始检查之后排上的) |
lastWriteError |
最近一次写失败,见 ChatStoreWriteError |
evictedConversations |
开始检查之后,因配额被淘汰的会话个数 |
ChatStoreWriteError
interface ChatStoreWriteError {
readonly at: number;
readonly name: string;
readonly message: string;
}
写失败的时间、错误名(比如 QuotaExceededError)和消息;抛的不是错误对象时名字为 Error、消息是它的字符串形式。写失败不影响内存里的数据,下一次写入整段重写。
ChatStoreRealtimeInspection
interface ChatStoreRealtimeInspection {
readonly lastSignal: ChatStoreSignal | undefined;
}
实时连接本身(连没连着、最后一帧什么时候到的)不在仓库里,仓库不持有连接。用 SDK 时它们由 @openmaxai/chat-sdk 给出,见调试面板 · 实时连接。
ChatStoreSignal
interface ChatStoreSignal {
readonly trigger: "messages" | "reconnected" | "changes";
readonly conversationId: string | undefined;
readonly at: number;
}
补洞调度器最近收到的实时信号:messages、reconnected 或 changes(补洞调度器上同名的方法;不管有没有因此补洞,回到前台不算),哪个会话(reconnected 没有),什么时候。
ChatStoreInspectRecord
type ChatStoreInspectRecord =
| {
readonly kind: "event";
readonly id: number;
readonly at: number;
readonly event: ChatStoreEvent;
readonly source: ChatStoreEventSource;
readonly change: ChatStoreChange | undefined;
readonly error?: unknown;
}
| {
readonly kind: "gapFill";
readonly id: number;
readonly at: number;
readonly conversationId: string;
readonly trigger: ChatGapFillTrigger;
readonly phase: "started" | "settled";
readonly result?: ChatGapFillResult;
}
| {
readonly kind: "localData";
readonly id: number;
readonly at: number;
readonly op: "opening" | "opened" | "clearing" | "cleared" | "fellBack" | "writeFailed" | "evicted" | "conversationCleared";
readonly userId?: string;
readonly conversationId?: string;
readonly error?: unknown;
}
| {
readonly kind: "snapshot";
readonly id: number;
readonly at: number;
readonly area: ChatStoreSnapshotArea;
readonly conversationId: string | undefined;
};
事件流里的一条,冻结的。id 在这个仓库里从 1 递增(只有建出来的记录占号),at 是毫秒时间戳。
kind |
什么时候 | 说明 |
|---|---|---|
event |
每次 dispatch |
event 是交给 dispatch 的事件本身;source 是谁发的,见 ChatStoreEventSource;change 是订阅者收到的那次 ChatStoreChange,什么都没改时为 undefined;error 是被拒时抛出的异常 |
gapFill |
一次补洞开始、结束 | trigger 同 ChatGapFillTrigger;结束时带 result(和 gapFill.last.result 是同一个冻结的副本)。补的期间又来了触发时,每一轮各一对开始、结束(下一轮的开始那条宣告 rerunQueued 变回 false);最后一轮的结束那条在不再算在补之后才发,宣告 running 变为 false |
localData |
本机数据开始打开(opening,openLocalData 调用当下)、打开了(opened)、开始清(clearing,clearLocalData 调用当下)、清完(cleared)、改用内存(fellBack,在 opened 之前)、写失败(writeFailed)、因配额淘汰一个会话(evicted)、按会话清(conversationCleared,clearConversation 调用当下;删本机那份是一笔本机写入,删完有它的 localWrite) |
opening、opened、fellBack 带 userId;clearing、cleared 在知道是哪个用户时带 userId;evicted 带被淘汰的 conversationId,conversationCleared 带被清的 conversationId(淘汰几个会话就几条);writeFailed 带 error 和那笔写入的 conversationId(随后还有那笔写入的 localWrite) |
snapshot |
快照变了、但不是上面三种操作改的 | area 说是哪一块,见 ChatStoreSnapshotArea。conversationId 是改到的会话;只改全局的、或一下改到几个会话的(调度器停下)为 undefined |
ChatStoreSnapshotArea
type ChatStoreSnapshotArea =
| "localWrite"
| "gapFillQueue"
| "changeLog"
| "openConversations"
| "realtimeSignal"
| "localSegment";
area |
什么时候 | 改到的 |
|---|---|---|
localWrite |
一笔排着的本机写入写完或失败(失败时先有一条带着变化的 localData 的 writeFailed,这一条随后,不再改什么;开始检查之前排上的写入落定时也有);整段写下时并进了改动水位更小的一段,退回改动水位的当下另有一条,不等这笔写完 |
storage.pendingWrites、storage.lastWriteError;写的期间本机那一段对不上了时还有 local,并段时退回了改动水位时还有 changeLog.watermark、changeLog.ahead |
gapFillQueue |
补洞进行中又来了触发;或一次补洞结束了却没有 gapFill 的结束记录(开始检查之前就开始的那次、写回时仓库订阅者的回调抛错结束的那次) |
gapFill.rerunQueued、gapFill.running |
changeLog |
补改动把取回的消息写回仓库(不经 dispatch,所以没有 event 记录)、读到了新的服务端最新编号,或一次补改动结束 |
消息、changeLog |
openConversations |
补洞调度器打开、关掉一个会话,或停下(打开那条在 gapFill 的开始记录之前) |
open、openConversations;停下时还有 gapFill.running |
realtimeSignal |
补洞调度器收到实时信号,包括没起补洞的那些 | realtime.lastSignal |
localSegment |
一个会话的本机那一段被作废(补改动时改动日志说太旧了,或取数协调发现本机读回的一段没有改动水位),当下同步发出,不等下一次网络往返 | local 清掉;改动日志说太旧了时改动水位和 changeLog.ahead 也清掉;storage.pendingWrites 加一 |
ChatStoreEventSource
type ChatStoreEventSource =
| "caller"
| "gapFill"
| "threadLoader"
| "localData";
一次 dispatch 是谁发的:caller 你的代码,gapFill 补洞调度,threadLoader 取数协调,localData 从本机读回(不管是谁读的)。
ChatStoreInspectListener
type ChatStoreInspectListener = (record: ChatStoreInspectRecord) => void;
事件流的回调,见 subscribe 和保证。同一个函数订阅两次算两个订阅,各收一份、各自取消。
ChatStoreStorageEstimate
interface ChatStoreStorageEstimate {
readonly usageBytes: number;
readonly quotaBytes: number;
readonly scope: "origin";
}
浏览器对整个站点(源)的估计,不只是聊天的数据,也不只是这个用户的;数字是近似的,各浏览器算法不同,浏览器没给的数按 0。
调试面板怎么用它
调试面板只用本页的接口读仓库:
- 挂上时调
inspectChatStore(store),从这时起仓库开始记;接着subscribe,把收到的记录放进一个 50 条的环形记录(事件记录那一块),并安排下一帧重画。收起时也照样记,只是不重画。 - 重画时读
getGlobal():会话选择列openConversations,存储那一块读storage;再对选中的会话读getConversation(id),画窗口、改动日志、发送和本机那一段。两个快照没变时是同一个对象,面板据此跳过没变的区块。 - 打开时调一次
estimateStorage(),「大约大小」显示它的结果。 - 实时连接那一块:连接状态和最后一帧来自 SDK(或不用 SDK 时宿主交给面板的连接状态),最后一个信号来自
realtime.lastSignal。
面板不调本页以外的任何仓库方法,所以它能做的事不会超过本页允许的。
