Insomnia 桌面端数据获取体系解析：insomniaFetch、insomnia-event-source 自定义协议 SSE 与轮询兜底

本文基于 packages/insomnia/README.md 中描述的桌面端数据获取（Data fetching）策略展开，结合仓库源码深入剖析 Insomnia 桌面应用的三套数据同步机制：统一的 HTTP 请求入口 insomniaFetch、基于 insomnia-event-source:// 自定义协议的 Server-Sent Events 实时通道，以及针对 Insomnia Sync / Git Sync / Presence 的轮询刷新。读完本文，你将能够理解这套机制如何绕过 Electron 渲染进程的跨域限制、为什么 SSE 请求要改用 libcurl 转发，以及实时事件与周期轮询并存时的竞态边界。

1. 背景：桌面应用里为什么需要专门的“数据获取层”

packages/insomnia/README.md 开篇即说明 packages/insomnia 是 Insomnia 的“主桌面应用（The main desktop application）”，并在 “Data fetching” 一节中给出三条核心原则：

1. 调用自家 API 统一走 insomniaFetch 函数，用以克服跨域（cross-origin）问题、标准化取数方式、并集中处理错误；
2. 实时数据使用 SSE（Server-Sent Events），通过 insomnia-event-source:// 自定义协议在 Electron 主进程中代理处理，同样为了绕开跨域并集中管理；
3. 轮询（Polling）作为补充手段，用于定期拉取数据——因为 SSE 有时会失败、数据可能失同步。轮询的三个主要场景是：刷新 Insomnia Sync 数据、刷新 Git Sync 数据、刷新 Presence（在线协作者）数据。

这套设计的前提是：Insomnia 是 Electron 应用（package.json 中依赖 electron: 43.2.0，入口为 src/entry.main.min.js），渲染进程与主进程之间天然存在安全与网络能力的分界——渲染进程无法直接读取本地会话（session）、无法感知系统代理，而云端 API 又要求携带 X-Session-Id 等认证头。因此所有对 Insomnia Cloud 的网络请求都被收敛到主进程或受控的封装函数中。

2. insomniaFetch：统一的 API 请求入口

2.1 函数签名与参数

insomniaFetch 的完整实现位于 packages/insomnia/src/common/insomnia-fetch.ts，其参数结构（FetchConfig 来自 insomnia-api 包）如下：

参数	类型 / 默认值	说明
method	string	HTTP 方法，如 GET、POST
path	string	API 路径，拼接到 API base URL 之后
data	任意（可选）	存在时自动 JSON.stringify 并附加 Content-Type: application/json
sessionId	string（必填）	用户会话 ID，缺失时直接抛错 No session ID provided to {method}:{path}
organizationId	可选	存在时附加 X-Insomnia-Org-Id 请求头
origin	可选	缺省取 getApiBaseURL()
headers	可选	调用方自定义头，与内置头合并
timeout	默认 INSOMNIA_FETCH_TIME_OUT（30000 ms）	通过 AbortSignal.timeout(timeout) 实现
retries	可选	源码注释标记为“未使用，应当移除”，实际实现中无重试逻辑
onDeepLink	可选回调	当响应头 x-insomnia-command 携带 URI 时触发，用于打开 API 返回的深链

其中 INSOMNIA_FETCH_TIME_OUT = 30_000（30 秒）与 API 基址 getApiBaseURL() 定义在 packages/insomnia/src/common/constants.ts 中：

// packages/insomnia/src/common/constants.ts
export const getApiBaseURL = () => env.INSOMNIA_API_URL || 'https://api.insomnia.rest';
export const INSOMNIA_FETCH_TIME_OUT = 30_000;

即请求基址默认是 https://api.insomnia.rest，可通过环境变量 INSOMNIA_API_URL 覆盖——这也是 packages/insomnia-api 各客户端方法能复用同一配置的来源。

2.2 自动附加的标准请求头

每次请求都会自动注入一组标准化头（见 insomnia-fetch.ts）：

• X-Insomnia-Client：客户端标识（getClientString()），便于服务端区分桌面端版本；
• insomnia-request-id：generateId('desk') 生成的请求 ID，用于链路追踪；
• X-Origin：调用来源或 API base URL；
• X-Session-Id：会话认证头，由 sessionId 参数显式传入；
• X-Insomnia-Org-Id：组织上下文；
• X-Mockbin-Test: true：仅当处于 Playwright 测试环境（PLAYWRIGHT_TEST 常量）时附加，供冒烟测试用 mock 后端识别。

2.3 可替换的 fetch 实现与代理感知

README 说 insomniaFetch 用来“克服跨域问题”，源码层面这体现在可替换的底层实现上。模块顶部维护了一个 fetchImpl 变量，默认是 globalThis.fetch，并提供 setFetchImplementation(impl) 供外部替换。源码注释明确写道：

// node fetch ignores the system proxy and OS certs — main swaps in net.fetch (entry.main.ts)

即 Node 环境的原生 fetch 会忽略系统代理和操作系统证书链，因此 Electron 主进程启动时（entry.main.ts）会把实现换成 Electron 的 net.fetch，从而让请求跟随系统代理与系统 CA。此外还导出一个 proxyAwareFetch 句柄：它在每次调用时委托给当前 fetchImpl，而不是提前捕获引用，因此无论 setFetchImplementation() 是否已经执行，它始终拿到最新的代理感知实现——这个句柄用于需要裸 fetch 的场景（如 v3 SDK 的 Configuration.fetchApi）。

2.4 集中化错误处理

README 提到的“集中处理错误”在实现中体现为两层归一化：

1. HTTP 层错误：当 response.ok 为 false 时，函数会尝试解析 JSON 响应体，提取其中的 error 字段作为错误名、message 字段作为错误信息；解析失败则退化为 CODE-{status} 与 response.statusText。最终统一抛出 ResponseFailError（来自 packages/insomnia-api 包），调用方只需捕获一种错误类型；
2. 网络层错误：AbortSignal.timeout() 触发时错误名是 TimeoutError（而非浏览器常见的 AbortError），两者都被转写成 insomniaFetch timed out: {method} {path}。对于 ECONNREFUSED、证书问题等真实错误，它们藏在 err.cause 中（有时还嵌套在 AggregateError 里），实现会从 cause.code / cause.errors[0].code / cause.message 中挖出细节并附加到错误消息末尾，方便用户诊断。

3. SSE 实时通道：insomnia-event-source:// 自定义协议

3.1 为什么需要自定义协议

浏览器端 EventSource 只能向同源（或允许 CORS 的跨域）地址发起 text/event-stream 请求，而 Insomnia Cloud 的流地址需要附带会话凭证，且渲染进程不应直接持有会话。README 给出的方案是：注册 insomnia-event-source:// 协议，由主进程代理真实请求。

协议注册逻辑在 packages/insomnia/src/main/api.protocol.ts 的 registerInsomniaProtocols() 中：

protocol.registerSchemesAsPrivileged([
  {
    scheme: insomniaStreamScheme, // 'insomnia-event-source'
    privileges: {
      secure: true,
      standard: true,
      supportFetchAPI: true,
      stream: true,        // 关键：允许流式响应
      corsEnabled: true,
    },
  },
  // ... 另注册 http/https 与 insomnia-templating-worker-database 协议
]);

其中 stream: true 是 SSE 可用的前提——它允许该协议返回分块流式响应而非一次性缓冲的完整 body。渲染进程的 CSP 也相应放行了该协议，见 packages/insomnia/src/root.tsx 中 connect-src ... insomnia-event-source: 的配置。

3.2 主进程如何转发 SSE 请求

protocol.handle(insomniaStreamScheme, ...) 的处理函数（api.protocol.ts）执行如下流程：

1. URL 重写：把 insomnia-event-source://v1/teams/{teamId}/streams 重写为 ${getApiBaseURL()}/v1/teams/{teamId}/streams，即透明地替换 scheme 并拼接真实 API 基址；
2. 会话注入：从本地 services.userSession.get() 取出 id，作为 X-Session-Id 头追加到请求头中——渲染进程从未接触会话 ID；
3. 代理解析：优先读取 Insomnia 的代理设置（settings.proxyEnabled、proxyScope、httpProxy/httpsProxy/noProxy）；未启用应用内代理时，通过 session.defaultSession.resolveProxy(urlStr) 跟随系统代理（PAC 格式），解析失败则回退为直连；
4. libcurl 执行请求：这是最关键的实现细节。源码注释说明为什么不用 Electron 自带的 net.fetch：

// here we use libcurl to forward the SSE request because the SSE request sent by net.fetch can not be disconnected correctly in some cases
// see https://github.com/electron/electron/issues/47097

即 Electron 的 net.fetch 发起的 SSE 连接在某些情况下无法正确断开，因此改用 @getinsomnia/node-libcurl（package.json 中版本为 3.3.0）建立长连接：TIMEOUT_MS 设为 0（不设超时，SSE 需长期保持）、开启 FOLLOWLOCATION、启用 CurlFeature.StreamResponse，在 stream 事件中将 libcurl 的 Readable 流用 Readable.toWeb() 包装后作为 Response 返回给渲染进程。

3.3 渲染进程消费事件流

渲染进程侧的入口是 React Context 提供者 InsomniaEventStreamProvider（packages/insomnia/src/ui/context/app/insomnia-event-stream-context.tsx）。当存在有效会话时，它创建：

const source = new EventSource(`insomnia-event-source://v1/teams/${sanitizeTeamId(organizationId)}/streams`);

组件卸载时 source.close() 关闭连接。message 事件中的数据是 JSON，按 type 字段分派处理，源码中定义的事件类型包括：

事件 type	触发行为
PresentStateChanged / PresentUserLeave	更新 Presence（在线协作者）列表；新头像出现后按 CDN_INVALIDATION_TTL（10 秒，constants.ts）延迟失效头像缓存
OrganizationChanged	提交组织同步（syncOrganizationsSubmit()），刷新组织/团队数据
StorageRuleChanged	失效对应团队的存储规则缓存（invalidateStorageRule）
TeamProjectChanged	提交项目同步（syncProjectsSubmit），刷新该组织下的项目列表
FileChanged / BranchDeleted	若事件属于当前工作区对应的远端文件，触发 Insomnia Sync 数据同步（syncDataSubmit）；否则（如列表页且无进行中的提交）执行 revalidate() 重校验路由数据
FileDeleted	同上；同时通过 uiEventBus.emit(CLOUD_SYNC_FILE_CHANGE) 广播，供工作区列表更新
VaultKeyChanged	对其他会话的 Vault Key 变更执行清除本地 vault key 的操作

一个值得注意的细节：事件处理器在触发 revalidate() 前会检查 ifInSubmission——若当前有进行中的 POST fetcher，则跳过重校验，避免与用户正在提交的操作互相干扰。这正是 README 末尾警告“SSE 与轮询组合可能产生竞态”在代码层面的具体缓解手段之一。

4. 轮询：SSE 的兜底与周期刷新

README 指出轮询用于三个场景：刷新 Insomnia Sync 数据、刷新 Git Sync 数据、刷新 Presence 数据，原因是 SSE 可能失败、数据可能失同步。仓库中对应的轮询点均基于 react-use 的 useInterval Hook：

4.1 Insomnia Sync 轮询

packages/insomnia/src/ui/components/dropdowns/sync-dropdown.tsx：

reactUse.useInterval(
  () => {
    triggerSync();
  },
  isWindowFocused ? ONE_MINUTE_IN_MS : null,  // ONE_MINUTE_IN_MS = 1000 * 60
);

即窗口聚焦时每 1 分钟触发一次 Insomnia Sync 同步；窗口失焦时传 null 暂停轮询，避免后台空转。

4.2 Git Sync 轮询

packages/insomnia/src/ui/components/dropdowns/git-sync-dropdown.tsx：

reactUse.useInterval(
  () => {
    gitFetchFetcher.submit({ projectId, workspaceId });
  },
  1000 * 60 * 5, // 每 5 分钟
);

每 5 分钟向 Git 远端执行一次 fetch，保证本地分支/提交状态与远端仓库对齐。packages/insomnia/src/ui/components/dropdowns/git-project-sync-dropdown.tsx 中还存在另一处 useInterval，服务于项目级 Git 同步下拉菜单，属于同一模式的复用。

4.3 Presence 轮询

Presence 数据并不走定时轮询，而是在上下文变化时主动刷新：InsomniaEventStreamProvider 在 organizationId、远端项目 ID（remoteId）、workspaceId 或会话 ID 变化时，调用 getRealTimeCollaborators()（来自 packages/insomnia-api/src/collaborators.ts）拉取一次当前协作者列表，后续增量更新则依赖 SSE 推送的 PresentStateChanged / PresentUserLeave 事件。这种“切换即拉取、运行中靠推送”的模式，恰好对应 README 中“Presence 数据刷新”这一轮询场景的准确实现形态——它是按需的周期性/事件驱动刷新，而非盲轮询。

4.4 文件系统层的轮询兜底（补充佐证）

从源码结构看，轮询兜底思想还延伸到本地文件监听：packages/insomnia/src/sync/git/repo-file-watcher.ts 的注释写明 Git 仓库目录变更“以 fs.watch（主）+ 周期性轮询（回退，10 s）”检测。当 fs.watch 出错时会显式打印 falling back to polling 并启动 10 秒间隔的 setInterval 轮询，且轮询只在 fs.watch 不可用时启用。这为 README 的核心论点——“推送机制可能失败，需要周期检查兜底”——提供了一个与云同步无关但架构上同构的实例。

5. SSE + 轮询组合下的竞态问题

README 末尾的警告值得单独展开：

使用 SSE 和轮询的组合可以让数据保持同步和最新，但也可能导致一些竞态条件。例如，如果每 5 秒轮询一次数据，而服务器恰好在同一时刻发送了一条 SSE 消息，数据可能会失同步几秒钟。

结合仓库实现，这类竞态的收敛手段主要有三处：

1. 事件驱动路径的防抖：SSE 事件触发 revalidate() / syncDataSubmit() 前，先检查是否存在进行中的 POST 提交（latestInSubmission），有则让位给显式提交；
2. Presence 状态的幂等合并：PresentStateChanged 更新采用“按 acct 去重替换”（prev.filter(p => p.acct !== event.acct) 后追加新事件），同一用户的多次推送不会叠加出重复条目；
3. 轮询与推送周期分离：Insomnia Sync 轮询为 1 分钟、Git Sync 轮询为 5 分钟，而 SSE 是即时推送，两者频率差异大且轮询只触发同步入口（triggerSync() / gitFetchFetcher.submit()），同步动作本身在远端以版本/快照语义收敛，短暂窗口内的交错不会造成状态分叉。

6. 小结

packages/insomnia 桌面端的数据获取是一个三层结构：

• 同步请求层：insomniaFetch 统一附加认证/追踪头、30 秒超时与归一化错误，底层 fetch 可替换为 Electron net.fetch 以获得系统代理与系统证书支持；
• 实时层：insomnia-event-source:// 特权流协议（api.protocol.ts）由主进程用 libcurl 代理 SSE，渲染进程通过 insomnia-event-stream-context.tsx 按事件类型分派 UI 更新；
• 兜底层：Sync 1 分钟、Git 5 分钟的 useInterval 轮询，以及 Presence 的按需刷新与文件监听轮询回退，保证 SSE 断连或服务端漏发时数据最终一致。

三者组合既绕开了 Electron 渲染进程的跨域与会话隔离限制，又在实时性与可靠性之间取得了明确的权衡——这也是该 README 一节虽短，却浓缩了桌面端与云端协作型应用网络架构全部要点的地方。