nexus
适配器Node IPC

生命周期和错误

处理 Node IPC 会话、守护进程重启和结构化错误。

本页介绍守护进程启动、残留套接字清理、连接断开行为和错误码。

守护进程启动

守护进程启动时依次执行:

  1. 将精确连接目标解析为套接字路径
  2. 验证路径安全性与长度
  3. 检查运行目录的安全性
  4. 检查套接字路径是否已存在
  5. 在安全的前提下清理失效的残留套接字文件
  6. 开始监听

无法确定某项安全检查是否通过时,启动会失败,不会猜测后继续执行。

与正在运行的守护进程冲突

如果另一个进程已占用套接字并接受连接,启动会失败并返回:

E_IPC_ADDRESS_IN_USE

这可避免新进程使用相同的 appId 和 instance 抢占已有守护进程。

清理残留套接字

进程崩溃后,Unix 套接字文件可能残留。

适配器会探测已有套接字;确认它已失效后,才会在监听前移除残留文件。

只有套接字文件可参与这类清理,普通文件和符号链接不会被移除。

清理失败时返回:

E_IPC_STALE_SOCKET_CLEANUP_FAILED

连接生命周期

底层套接字连接建立后,Nexus Core 执行逻辑握手。

只有完成以下步骤,连接才可用:

  1. 若配置了适配器预认证,认证通过
  2. 完成 Core 握手消息交换
  3. 若配置了 policy.canConnect,连接获准通过

握手超时可避免无限等待那些只接受套接字连接、却不完成 Nexus 握手的对端。

守护进程重启

守护进程关闭或重启后,客户端已有的代理会失效。

Nexus 句柄绑定到会话:

  • 旧连接上的代理调用会失败
  • 旧远程引用失效
  • 开始新任务前,需要重新连接并获取新代理

这是明确的生命周期边界。Nexus 不会自动将旧代理转向守护进程的新会话。

错误代码

Node IPC 适配器错误:

Code含义
E_IPC_ADDRESS_INVALID连接目标或解析结果无法产生有效套接字地址。
E_IPC_ADDRESS_IN_USE套接字已被正在运行的守护进程占用。
E_IPC_PATH_TOO_LONG文件系统套接字路径超过平台长度限制。
E_IPC_CONNECT_FAILED底层套接字连接失败。
E_IPC_AUTH_FAILED共享密钥预认证失败或超时。
E_IPC_PROTOCOL_ERROR消息分帧或预认证协议格式错误。
E_IPC_STALE_SOCKET_CLEANUP_FAILED无法安全移除失效的残留套接字文件。

Node IPC 中常见的 Core 授权错误:

Code含义
E_AUTH_CONNECT_DENIEDpolicy.canConnect 拒绝握手。
E_AUTH_CALL_DENIEDpolicy.canCall 拒绝服务调用。

调试清单

启动失败时:

  1. 打印解析出的套接字路径。
  2. 检查是否已有使用相同 appId 和 instance 的守护进程。
  3. 检查目录所有权和权限。
  4. 检查套接字路径是否被普通文件或符号链接占用。
  5. 检查路径是否超过 Unix 套接字的长度限制。

调用失败时:

  1. 检查适配器预认证是否成功。
  2. 检查 policy.canConnect。
  3. 检查 policy.canCall。
  4. 检查代理是否在守护进程重启之前获取。
  5. 重新连接并获取新代理。
在 GitHub 上编辑此页