nexus
适配器WebSocket

WebSocket

通过 WebSocket 将受控的浏览器、WebView 和 Node 客户端连接到 Nexus 服务端。

@nexus-js/websocket 通过 WebSocket 传输 Nexus 二进制数据包,适用于连接到应用自有 Node 宿主的受控浏览器、WebView 和 Node 客户端。

pnpm add @nexus-js/core @nexus-js/websocket

浏览器安全的客户端 API 从 @nexus-js/websocket 导入;仅 Node 服务端 Endpoint 从 @nexus-js/websocket/server 导入。

适用范围

  • 本机 Node 服务及其浏览器、WebView 或 Node 客户端
  • 开发服务器调试面板和多窗口工具 UI
  • 测试控制器与受控测试运行时
  • 由应用自行治理的受控远程工作区或隧道

适配器不提供公网或多租户治理,也不负责发现对端、启动 HTTP 或 WebSocket 服务、登录 或配对、自动重连、调用重放、持久化消息、恢复旧代理或 Ref,或提供大文件和持续流式传输。

连接客户端

在共享代码中定义不绑定 target 的服务契约和 Token。先配置运行时,再使用精确的 WebSocket target 建立连接,并从返回的连接获取服务。

// shared/contracts.ts
import { Token } from "@nexus-js/core";
import type { WorkspaceService } from "./workspace-service.js";

export const WorkspaceToken = new Token<WorkspaceService>("app:workspace");
// browser/bootstrap.ts,或 Node 22+ 客户端
import { usingWebSocketClient } from "@nexus-js/websocket";
import { WorkspaceToken } from "../shared/contracts.js";

const target = {
  context: "websocket-server" as const,
  url: "ws://127.0.0.1:43120/nexus",
};

const clientNexus = usingWebSocketClient({
  protocols: ["my-app"],
  connectTimeoutMs: 5_000,
  connectTo: [target],
  callTimeout: 10_000,
  providers: [],
  policy: {
    canConnect: ({ connection }) => connection.role === "client",
  },
});

const connection = await clientNexus.connect({ target });
const workspace = connection.get(WorkspaceToken);
await workspace.open("one");

客户端使用浏览器原生 WebSocket 或 Node 22+ 原生 WebSocket,不使用 ws 作为客户端 实现。protocols 是标准 WebSocket 子协议列表,默认省略。connectTimeoutMs 独立限制 原生拨号时间,不替代 Core 的连接获取超时。connectTo 是可选的一次性启动目标列表, 不会添加重试。

usingWebSocketClient(options?) 配置默认 Nexus 实例;设置 configure: false 时返回 配置对象,供应用自己的 Nexus 设置使用。options 也接受 Nexus 的 providers、policy 和 callTimeout。适配器没有 ticket、header、credential 或自动重连选项。浏览器客户端 不能任意添加 HTTP header。应用凭证不要放入 URL、query string 或自动日志。

不带 target 的 connect 只等待一个已经存在且匹配的 ready session,不会发现或启动服务端。 URL 只标识宿主地址,不是身份或授权声明。

接入服务端 Socket

服务端 Endpoint 只接入已经 OPEN 的 Node ws socket。它不会创建 HTTP/TLS 服务、执行 Upgrade、检查 Origin 或路径、认证请求、发送 ping/pong,也不暴露自定义 control API。这些 职责由宿主负责,宿主决定传给 Nexus 哪些本地事实。

在启用宿主回调前先配置 providers 和 policy,并先 await nexus.ready():这一步会安装 Endpoint listener 和 providers。随后 Upgrade 回调只同步调用 safeAttach;接收 OPEN socket 到交给 Nexus 之间不能 await。

import { createServer } from "node:http";
import { Nexus } from "@nexus-js/core";
import { WebSocketServer } from "ws";
import {
  WebSocketServerEndpoint,
  type WebSocketAdapterModel,
} from "@nexus-js/websocket/server";
import { WorkspaceToken } from "../shared/contracts.js";
import { workspaceService } from "./workspace-service.js";

type Facts = {
  readonly cookie?: string;
  readonly origin?: string;
};

const endpoint = new WebSocketServerEndpoint<Facts>({
  maxConnections: 100,
  transport: { maxFrameBytes: 1_048_576 },
});
const nexus = new Nexus<WebSocketAdapterModel<Facts>>();
nexus.configure({
  endpoint: {
    implementation: endpoint,
    meta: { context: "websocket-server" },
  },
  providers: [{ token: WorkspaceToken, service: workspaceService }],
  policy: {
    async canConnect({ connection }) {
      if (connection.role !== "server") return false;
      return await authenticateCookie(connection.cookie);
    },
    async canCall({ connection, serviceName, path }) {
      return await authorizeCall(connection, serviceName, path);
    },
  },
  callTimeout: 10_000,
});
await nexus.ready();

const httpServer = createServer();
const wsServer = new WebSocketServer({ noServer: true });

httpServer.on("upgrade", (request, socket, head) => {
  const requestUrl = new URL(request.url ?? "/", "http://localhost");
  if (requestUrl.pathname !== "/nexus") {
    socket.destroy();
    return;
  }

  const origin = request.headers.origin;
  if (origin !== undefined && origin !== "https://app.example.test") {
    socket.destroy();
    return;
  }

  wsServer.handleUpgrade(request, socket, head, (ws) => {
    const result = endpoint.safeAttach(ws, {
      cookie: request.headers.cookie,
      origin,
    });
    if (result.isErr()) ws.close();
  });
});

httpServer.listen(43120, "127.0.0.1");

// 应用关闭时,先关闭 Nexus 所有的 socket,再关闭宿主所有的服务。
process.once("SIGTERM", () => {
  endpoint.close();
  wsServer.close();
  httpServer.close();
});

attach(socket, facts) 是 safeAttach 的 throw-style 版本。socket 必须处于 OPEN, Endpoint 必须已经 listening,且容量未满。成功后所有权转移给 Nexus,facts 会以 { ...facts, role: "server" } 写入 connection metadata;role 始终由适配器提供。失败时 socket 仍归宿主,是否关闭或销毁由宿主决定。attach 成功不等于 Nexus connection 已 ready; Core 仍会执行正常握手和授权。

facts 是应用定义的浅层快照。当 canConnect 需要时,可以包含 cookie 或 session 值等本地 凭证,也可以包含 Origin 结果或其他事实。适配器不定义 principal 或认证模式,也不会保留 request 或 socket。这些事实只属于该连接,并在连接生命周期内保留;应用必须负责其敏感性, 不得记录或传输这些事实。

宿主也可以在 Upgrade 阶段完成认证,再将非敏感的 principal 快照作为 facts 传入。无论采用哪种 方式,canConnect 都仍然是 Nexus 的连接授权边界。

endpoint.close() 会关闭 Nexus 所有的 socket,但不会关闭宿主的 HTTP、TLS 或 WebSocketServer;这些服务何时以及如何停止由宿主决定。

宿主边界与策略

宿主应负责 TLS、HTTP 路由、路径检查、Origin 检查、Upgrade 认证、协议协商、原生 ws ping/pong 和宿主资源限制。适配器只传输包含既有 Core 数据包的二进制消息;文本消息是不支持 的输入,会终止通道。适配器仍会限制收到后的 payload、early packet 和发送积压,但无法提供 浏览器收到数据之前的分配保证。

Nexus 授权独立于 WebSocket 握手。canConnect 接收实际的 connection 属性,可以异步 认证或授权;canCall 独立决定每次操作。where 只用于连接获取,不是 RPC 授权。如果服务端 对不可信客户端可达,必须显式定义 policy:省略 Nexus policy 时,默认允许连接和调用。

需要观察应用生命周期时,使用 nexus.onConnect、connection.onDisconnected 和普通 identity observer。

生命周期与限制

一条 socket 对应一个 Nexus session。代理和 Ref 与 session 绑定:断开、重启或 session 替换后,必须重新连接并获取新句柄。没有自动重连、调用重放或旧引用恢复。已经执行但未响应 的调用不会在新连接上自动重放。

Upgrade 路径、接入、policy、二进制帧、资源限制和关闭行为应通过真实 WebSocket 集成覆盖验证。 createMockNexus() 只适用于 NexusInstance 调用侧的应用测试。

传输限额

WebSocket 固定使用二进制数据包。可通过 transport 配置帧、消息和框架聚合缓冲限额; 默认值分别为 64 KiB、16 MiB 和 64 MiB:

const endpoint = new WebSocketServerEndpoint({
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
  },
});

maxBufferedAmountBytes 是 WebSocket 原生发送高水位阈值,与框架聚合缓冲预算不同。

在 GitHub 上编辑此页