Nexus Relay
通过中间上下文转发服务调用,并管理回调、远程引用和断连清理。
Nexus Relay 把收到的服务调用转发给指定的远端。调用方使用相同的服务接口,回调和远程引用也能经过 Relay 调用。
适用场景
侧边栏需要持续显示文档变化,后台负责记录当前选中的页面。侧边栏连接后台的文档服务,后台通过 Relay 把调用交给那个页面的内容脚本。
页面选择因此集中在后台。如果侧边栏自己选择页面,可以直接连接内容脚本。跨适配器通信也可以使用 Relay,例如由宿主把 iframe 的调用转发给 Chrome 后台。
服务转发
侧边栏、后台和内容脚本共享 DocumentToken 和 DocumentService。watch() 接收文档变化回调,返回带有 stop() 方法的观察对象引用。接口和实现见远程资源。
内容脚本用配置好的实例注册服务:
contentNexus.provide(DocumentToken, documents);后台用 relay() 注册转发。selectedDocument 包含应用选定的 tabId 和 documentId。应用负责加载内容脚本,Relay 在调用需要时连接它。
import { chromeTarget, usingBackgroundScript } from "@nexus-js/chrome";
import { DocumentToken } from "./shared";
import { selectedDocument } from "./selection";
const backgroundNexus = usingBackgroundScript();
const relay = backgroundNexus.relay({
services: [DocumentToken],
to: {
target: chromeTarget.contentDocument(selectedDocument),
},
});注册后,后台的服务目录包含 DocumentToken。services 指定转发哪些服务,to.target 指定它们的提供方。省略 to.nexus 时,由当前的 backgroundNexus 连接目标。
侧边栏连接后台,获取相同的 Token:
import { chromeTarget, usingSidePanel } from "@nexus-js/chrome";
import { DocumentToken } from "./shared";
const panelNexus = usingSidePanel();
const connection = await panelNexus.connect({
target: chromeTarget.background(),
});
const documents = connection.get(DocumentToken);
const observation = await documents.watch("intro", (change) => {
panel.apply(change);
});panel 是应用自己的 UI 对象。get() 在侧边栏创建代理,await documents.watch(...) 发起远程调用。后台到内容脚本的连接称为上游连接。
relay() 同步返回用于释放注册的 RelayHandle,不会等待内容脚本上线。因此,即使 get() 成功,后面的 watch() 也可能因连不上内容脚本而失败。
需要检查注册是否成功时,使用同步返回 Result 的 safeRelay()。调用 watch() 等远程方法时,通过 await 或 Nexus.safeCall() 接收结果。
可以在启动模块中同步注册,也可以等 await backgroundNexus.ready() 完成后注册。同一实例不能重复注册同一个 Token,包括本地服务和 Relay。
services 中的 Token 使用相同的目标选择条件,也会一起释放。其中任何一个 Token 冲突,整批注册都会失败。
回调与远程引用
回调和它捕获的 panel 留在侧边栏。内容脚本调用这个回调时,函数最终在侧边栏执行,可以直接更新本地 UI。
观察对象留在内容脚本,服务通过 ref(...) 返回它的引用。侧边栏调用 observation.stop() 时,执行的是内容脚本里那个对象的方法。后台负责把这些调用和结果送到对应的一端。
停止观察后,用 Nexus.release(observation) 释放单个引用,或关闭它所属的资源域。
资源域
多个界面可以通过后台观察同一份文档,后台复用同一条内容脚本连接。关闭界面 A 时,界面 B 还需要接收更新,因此不能为了清理 A 而断开这条共享连接。
ResourceScope 把相关调用、回调和远程引用放在一组,方便一起清理。给 A、B 各建一个资源域,A 关闭自己的域时,Relay 会通知路径上的其他实例释放 A 的通信资源。
直接调用 connection.get(DocumentToken) 时,Nexus 会使用默认资源域。在同一条 Connection 上再次获取同一个 Token,仍会使用当前有效的默认域。
多个界面共享连接且需要分别清理整组资源时,为它们各建一个域:
const scope = connection.createScope(DocumentToken);
const documents = connection.get(DocumentToken, { scope });
try {
const observation = await documents.watch("intro", (change) => {
panel.apply(change);
});
await waitUntilPanelCloses();
await observation.stop();
} finally {
scope.close();
}waitUntilPanelCloses() 由应用实现,在界面关闭时结束等待。代码先调用 stop(),让内容脚本停止观察,再关闭资源域、释放其中的回调和引用。即使 stop() 失败,finally 也会关闭域。
scope.close() 使域内的调用、回调和引用失效,共享 Connection 保持打开。业务监听器需要由服务清理,已经完成的操作也不会被撤销。
侧边栏意外断开时,可能来不及调用 observation.stop()。内容脚本中的服务还需要处理这种情况,移除它为这次观察安装的文档监听器。Nexus 释放回调引用后,应用安装的监听器不会自动移除。见远程资源的清理示例。
重复调用 close() 没有额外效果,[Symbol.dispose]() 也执行相同的关闭操作。用 closed 检查是否已关闭,用 onClosed(listener) 接收关闭通知;关闭后添加的监听器会立即执行。
每个资源域只属于创建它的 Connection 和 Token。显式创建的域一旦关闭,需要创建新域才能继续使用。
断连与恢复
假设内容脚本退出了,侧边栏与后台仍然连接。后台检测到与内容脚本断开后,会关闭相关资源域,并通知侧边栏。侧边栏正在等待的调用会失败,手里的旧观察引用也随之失效。
几种关闭操作的影响如下:
- 只关闭 A 的资源域时,B 仍能收到更新。
- 后台到内容脚本的共享连接断开时,A、B 通过这条连接创建的观察引用都会失效。
- 侧边栏到后台的连接断开时,侧边栏需要重新
connect()并获取服务代理。
适配器发现断开需要时间,调用可能在此之前先超时。请求也可能已经执行,只是结果没有返回,所以 Nexus 不会自动重新执行失败的调用。
连接恢复
上游断开后,后台仍保留 Relay 注册。侧边栏到后台的连接仍可用、原目标也已恢复时,可以再次调用 documents.watch(...)。未指定显式资源域的代理会建立新域,后台按原来的目标重新获取连接。
调用成功后会返回新的观察引用。通过旧 observation.stop() 发起的调用仍会失败。
如果之前显式创建了资源域,需要先创建新域,再取得服务代理。State 镜像失效后需要重新订阅。
只配置 where 的 Relay 会等待匹配的连接出现;配置了 target 才能主动连接该目标。
目标变更
示例中的 contentDocument 目标绑定具体的 documentId。页面导航后,新文档有自己的 ID。后台选中新文档时,需要释放旧注册,再用新目标注册:
relay.dispose();
const nextRelay = backgroundNexus.relay({
services: [DocumentToken],
to: {
target: chromeTarget.contentDocument(nextDocument),
},
});nextDocument 是应用新选中的文档。dispose() 移除这份注册发布的服务入口,并关闭所属资源域,保留共享 Connection。新注册把后续调用送到新文档。
连接与路由
跨实例转发
同一个上下文可以拥有多个 Nexus 实例。例如宿主用 iframe 实例接收嵌入页面的调用,再通过 Chrome 实例连接后台。此时显式指定 to.nexus:
// 两个本地实例已通过各自的适配器完成配置。
const relay = iframeNexus.relay({
services: [DocumentToken],
to: {
nexus: chromeNexus,
target: chromeTarget.background(),
},
});嵌入页面连接 iframeNexus,从它的服务目录获取 DocumentToken。收到调用后,宿主通过 chromeNexus 连接 Chrome 后台。两个实例都在宿主里。
target 和 where 使用 chromeNexus 对应的适配器类型。省略 to.nexus 时,由调用 relay() 的实例连接目标。
多跳转发与目标选择
路径 A → B → C → D 中,B 注册转发到 C,C 注册转发到 D。A 连接 B,D 提供服务。回调和引用沿已经建立的路径通信,每一跳都保留各自的连接会话。
to.target 与 to.where 遵循连接获取规则。target 指定连接地址,where(contextMeta, connectionMeta) 检查对端身份和适配器观察到的连接信息,两者都必须满足。
没有 target 时,只等待已有会话中的唯一匹配;多个匹配会产生歧义错误。
同一份注册对所有调用方使用相同的 target 和 where。资源域建立后,就固定使用当时取得的上游会话。后来出现新连接,也不会把已有的观察引用切换过去。
各实例通过 policy.canConnect 和 policy.canCall 检查权限。内容脚本的直接对端是后台,因此授权时看到的是后台的连接身份。
如果服务需要知道最初是哪个用户或界面发起调用,应用应在契约中传递相应信息,并由服务验证。见授权策略。
State 转发
把共享 StoreToken 加入 services,侧边栏就可以通过 connectNexusStore() 连接后台并订阅 Store。每次订阅都会自动创建独立资源域。
调用镜像的 destroy() 会清理这次订阅,其他镜像继续接收更新。资源域关闭后,需要重新订阅,读取一份新的完整状态。见 Nexus State。