nexus
Core 指南

身份与元数据

识别对端、筛选连接,并区分对端声明的身份与本地观察到的事实。

多个上下文参与通信时,应用需要区分它们的角色、所属工作区或就绪状态。Nexus 在握手时交换一个小型身份对象,并通过 Connection 提供访问。

三种不同的输入

输入提供者用途
ConnectionTarget发起连接的应用由适配器接受的精确地址
ContextMeta远程应用声明的身份、角色和应用标签
ConnectionMeta本地适配器本次会话中观察或验证的事实

目标地址决定连接到哪里,元数据描述对端和已建立的连接。它们来自不同位置,信任边界也不同。

声明本地身份

显式配置 Endpoint 时,在 endpoint.meta 中声明身份:

app.configure({
  endpoint: {
    implementation: endpoint,
    meta: {
      context: "document-source",
      workspace: "drafts",
      documentsReady: false,
    },
  },
});

这是一个配置片段:app 和 endpoint 必须使用同一个声明了这些字段的模型。官方适配器辅助函数会配置标准身份信息;参阅对应的适配器指南。

身份信息应精简且可序列化。可以包含角色、工作区标签和就绪状态,不应包含密钥、可变业务数据或本应由适配器观察得到的事实。

读取元数据并筛选对端

connection.contextMeta 保存最新接受的对端身份信息,connection.connectionMeta 保存本地适配器对该会话观察到的事实。

在连接谓词中同时使用两者:

const connection = await app.connect({
  where: (contextMeta, connectionMeta) =>
    contextMeta.workspace === "drafts" &&
    connectionMeta.observed.authenticated === true,
  timeout: 10_000,
});

示例假定适配器模型声明了这些字段。不指定 target 时,只会被动等待恰好一个匹配的会话。 where 仅筛选获取到的连接,不发现服务提供者,也不负责后续调用的授权。

groups 等标签只是应用元数据,不是内置路由组;其含义由应用的筛选函数决定。 固定的 ConnectionCollection 不会随标签变化而改变成员。

更新身份

await app.updateIdentity({ documentsReady: true });

更新只改变本地 Endpoint 声明的身份,不改变适配器事实或连接目标。 使用 connection.subscribeIdentity(listener) 监听对端身份;它先通知当前完整身份,再通知后续接受的完整快照。 服务注册与就绪通知的顺序请参阅连接生命周期。

信任边界

除非适配器明确提供额外验证,否则 ContextMeta 只是对端自行声明的信息。ConnectionMeta 可以包含本地观察到的发送方详情或认证结果,其可信程度取决于适配器的具体保证。

访问控制应使用授权策略。role: "admin" 这样的应用标签本身不是权限证明。

将类型与 AdapterModel 关联

AdapterModel 关联三类类型:

import type { AdapterModel } from "@nexus-js/core";

interface DocumentModel extends AdapterModel {
  contextMeta: {
    context: "document-source" | "viewer";
    workspace: string;
    documentsReady: boolean;
  };
  connectionMeta: { observed: { authenticated: boolean } };
  connectionTarget: { address: string };
}

这只是自定义模型的示例,不包含适配器实现。使用现有适配器时,请采用其官方模型和精确目标构造函数。 Nexus<M>、IEndpoint<M> 和绑定模型的 Token 共享这一关联。它提供编译期一致性,不提供运行时验证或认证。

在 GitHub 上编辑此页