概念
理解 Node IPC 中守护进程、客户端、套接字和会话的关系。
本页解释适配器心智模型。如果希望先看可运行代码再了解概念,请先阅读快速开始。
守护进程与客户端
Node IPC 适配器连接一个本地守护进程与一个或多个本地客户端。
守护进程:
- 监听文件系统 Unix 套接字
- 提供 Nexus 服务
- 管理套接字生命周期
客户端:
- 连接守护进程的套接字
- 从已获取的连接取得 Nexus 服务代理
- 调用守护进程提供的服务
两端都是普通的 Nexus 运行时,适配器负责端点连接和元数据。
客户端提供服务与启动连接
客户端也可以向守护进程提供服务。如果客户端由守护进程创建,应先启动监听,再创建客户端进程,并通过 daemonNexus.connect({ where, timeout: 10_000 }) 被动等待连接。
usingNodeIpcClient({
appId: "worker-B",
connectTo: [{ context: "node-ipc-daemon", appId: "owner-A" }],
}).provide(WorkerToken, workerService);在 where 中匹配新客户端的唯一身份。被动获取等待的是已授权且就绪的会话,不会发现服务提供者,也不只是等待套接字打开。
守护进程需要立即使用服务时,客户端应先注册服务,再发布业务就绪标记。
connectTo 只尝试连接一次,不阻塞 ready(),不重试,也不获取服务;守护进程无需为此额外提供服务。
连接目标与套接字地址
Nexus 使用 NodeIpcConnectionTarget 表示连接目标,由适配器将精确目标映射到套接字地址。
ConnectionTarget 示例:
{ context: "node-ipc-daemon", appId: "example-app", instance: "default" }套接字地址示例:
{ kind: "path", path: "/run/user/1000/nexus/example-app/default.sock" }明确区分:
- 精确目标表达应用想连接到哪里
- 套接字地址是适配器使用的具体传输地址
应用通常使用导出的 Node IPC 目标类型。如果需要自行管理套接字路径布局,可以提供自定义地址解析器。
适配器预认证与 Core 授权策略
共享密钥预认证是适配器的准入检查,在将套接字交给 Nexus Core 之前,验证对端是否持有配置的认证令牌。
Core 策略是 Nexus 的通用授权层,决定对端是否能完成逻辑握手,以及是否允许调用服务;无论是否启用预认证,都可以使用。
常见流程:
- Node IPC 验证共享密钥
- node-ipc 记录
connection.observed.authenticated policy.canConnect检查连接事实policy.canCall检查服务访问权限
ContextMeta 与 ConnectionMeta
端点元数据是进程自行声明的逻辑身份。
守护进程的元数据结构:
{
context: "node-ipc-daemon";
appId: string;
instance?: string;
pid: number;
}客户端的元数据结构:
{
context: "node-ipc-client";
appId: string;
pid: number;
}连接元数据是适配器观察到的数据:
{
observed: {
socket: NodeIpcSocketAddress;
authenticated: boolean;
authMethod?: "none" | "shared-secret";
};
}当前适配器不提供经操作系统验证的对端 pid、uid 或 gid。端点元数据中的 pid 只是进程自行声明的诊断信息,不能当作对端凭据。
消息分帧与序列化
Unix 套接字传输字节流,适配器需要先恢复消息包边界,再将完整消息包交给 Nexus Core。
帧格式:
[uint32 byteLength][ArrayBuffer packet bytes]分帧不定义 Nexus 消息的含义,只用于区分相邻消息包的边界。
序列化仍由 Core 负责。当前 BinarySerializer 将紧凑格式的 Nexus JSON 编码为 UTF-8 字节,并非 MessagePack。
绑定会话的句柄
Nexus 的连接代理和远程引用绑定到创建它们时使用的逻辑连接。
守护进程重启或套接字断开后:
- 旧代理的调用会失败
- 旧远程引用失效
- 客户端需要重新连接并获取新的代理
这样会话生命周期的边界始终明确。Core 代理不会自动转向守护进程的新会话。
能力边界
该适配器用于本地进程间通信,不是跨机器网络适配器。
它不提供:
- 跨机器传输
- TLS
- 应用目标到套接字映射之外的全局服务或目标发现
- 可跨重连持续使用的代理句柄
- 基于操作系统对端凭据的授权
这些能力可以在其他层扩展,但不属于当前包的契约。