OpenMax
免费试用

检查接口

只读检查接口 @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。

调试面板怎么用它

调试面板只用本页的接口读仓库:

  1. 挂上时调 inspectChatStore(store),从这时起仓库开始记;接着 subscribe,把收到的记录放进一个 50 条的环形记录(事件记录那一块),并安排下一帧重画。收起时也照样记,只是不重画。
  2. 重画时读 getGlobal():会话选择列 openConversations,存储那一块读 storage;再对选中的会话读 getConversation(id),画窗口、改动日志、发送和本机那一段。两个快照没变时是同一个对象,面板据此跳过没变的区块。
  3. 打开时调一次 estimateStorage(),「大约大小」显示它的结果。
  4. 实时连接那一块:连接状态和最后一帧来自 SDK(或不用 SDK 时宿主交给面板的连接状态),最后一个信号来自 realtime.lastSignal。

面板不调本页以外的任何仓库方法,所以它能做的事不会超过本页允许的。