nexus
适配器Node IPC

概览

配置本地守护进程与客户端之间的 Nexus 进程间通信。

@nexus-js/node-ipc 通过文件系统路径形式的 Unix 域套接字连接本地守护进程和客户端进程。 它适用于由一个长期运行的本地进程提供 Nexus 服务、一个或多个本地客户端调用这些服务的场景。

本节介绍适配器专属行为。所有适配器共用的授权钩子见授权策略。

从这里开始

所需依赖

  • 核心运行时:@nexus-js/core
  • 本地 IPC 适配器:@nexus-js/node-ipc

在守护进程和客户端项目中都安装:

pnpm add @nexus-js/core @nexus-js/node-ipc

何时使用

当应用具有以下条件时使用 node-ipc:

  • 一个提供服务的本地守护进程
  • 一个或多个本地客户端,例如命令行程序或辅助进程
  • 仅同机通信
  • 用于标识守护进程实例的 Unix 套接字路径

它不适用于浏览器上下文或跨机器通信,也不提供在守护进程重启后仍可直接使用、无需重新获取的持久句柄。

适配器提供什么

  • 守护进程与客户端的创建辅助函数
  • 默认套接字地址解析
  • 自定义地址解析器
  • 基于文件系统 Unix 套接字的服务端与客户端 Endpoint
  • 套接字字节流上的二进制消息分帧
  • 可选的共享密钥预认证
  • 运行目录与残留套接字的安全检查
  • Node IPC 的端点与连接元数据、精确目标类型和地址辅助函数

Core 负责的能力

适配器不会替代 Core Nexus 行为。

以下能力仍由 Core 负责:

  • Token 和服务契约
  • 服务注册与暴露
  • 代理创建
  • 连接目标解析
  • 逻辑连接握手
  • policy.canConnect 和 policy.canCall
  • 资源引用生命周期
  • 代理与会话绑定的行为

运行时支持范围

当前验证范围是 Linux 和类 Unix 系统上的 Node,使用文件系统 Unix 域套接字。 仓库 CI 尚未验证 Bun,因此这里不承诺其兼容性,也不据此判定它不可用。 详见运行时兼容性。

测试边界

如果调用守护进程服务的应用代码依赖 NexusInstance,可以用 @nexus-js/testing 和 createMockNexus() 编写单元测试。

不要用测试替身验证 Node IPC 适配器本身。它不覆盖 Unix 套接字寻址、文件系统权限、消息分帧、共享密钥预认证、残留套接字清理、守护进程关闭与重建,以及真实断开时序。

适配器和真实套接字的集成测试指导见测试。

传输限额

Node IPC 固定使用二进制数据包。守护进程和客户端 helper 接受 transport 选项, 用于设置帧、消息和框架聚合缓冲限额;默认值分别为 64 KiB、16 MiB 和 64 MiB:

usingNodeIpcDaemon({
  appId: "example-app",
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
  },
});

配置的帧上限不能超过 IPC 分帧协议的消息上限。

在 GitHub 上编辑此页