@xyo-network/event-kit-node

中文文档
2.3.4发布于 2026/11/03LGPL-3.0-onlyTypeScriptES Module

Node 26+ Event Kit持久性,握手客户端,和SQLite源代码发布者运行时

中文使用文档
文档目录5 节
  1. 握手的客户
  2. 居民出版商
  3. 耐久性模型
  4. 队列服务提供商
  5. 边界

@xyo-network/event-kit-node

Event Kit的Node.js 26+耐久性适配器。存储库是Node 26.9.0:

  • createFilesystemCursorStore -唤醒发布者参与者的发布者光标
  • createFilesystemPublisherOutbox -持久的pending-wake槽,用于重试稳定性
  • createSqliteWakeReceiver -原子持久的收件箱/队列在一个私有的FULL/WAL SQLite数据库
  • createSqliteWakeQueue -独立围栏 WakeQueue 在 node:sqlite
  • createFilesystemWakeQueue / createFilesystemWakeInbox -协调SQLite权限与可检查的JSON投影
  • createSqliteBestEffortInbox / createBestEffortSnapshotWorker -持久有界提示安全/合并和独立快照工作
  • migrateReceiverStore / migrateIdOnlyReducerCheckpoint -显式停止所有者离线迁移和报告

握手的客户

进口 @xyo-network/event-kit-node/handshake 第三阶段控制平面 表面。该子路径导出:

  • 同步的终局重播阅读器和XL1发布组合;
  • 用于声明、发现、加密的发布者和订阅者客户端 订阅/拨款的发表、质疑、接受和撤销;和
  • 文件系统存储重播检查点、突变意图、发布 日志、发布者加密密钥保管和端点质疑决策。

生成的链上握手突变使用调用者提供的16字节 小写十六进制操作ID。 createFilesystemHandshakeMutationIntentStore 原子地绑定第一个 请求其精确随机服务/密钥、授予、密文或接受 工件。在咨询可变链之前,精确的重试加载该赢家 状态;在相同作用域的操作ID下更改输入失败关闭。 记录和目录是私有的(0600/0700). 发布者服务意图 保留加密私钥,直到可以将其幂等复制到密钥中 拘留。订阅者意图保留密文和请求指纹,而不是 端点或挑战秘密明文。

createFilesystemFinalizedStatementPublicationJournal 然后绑定逻辑 声明源、有序对象/附件哈希和精确值 签署的交易。重新启动从最高持久阶段恢复,并且可能 只重播那个证据;它从不重建或重新签署一个模棱两可的 出版。

握手子路径故意不加载唤醒队列、收件箱、 发件箱,或者 node:sqlite。干净包装的消费者类型检查并执行它 没有SQLite耦合。有一种不受版本控制的源感知契约。 服务发布要求 sources 和 maxPositionsPerWake; 订阅 出版要求 source 和 fromPosition。授权仍然固定 到XL1会话独立于源位置。删除模式后缀, 块范围字段和配置文件选择器没有兼容性别名。

居民出版商

@xyo-network/event-kit-node/publisher-runtime 导出SQLite发布器 权限/存储,持久运行时,真正的D-005发现,有界传输, 原生REST网关/数据组合,以及XL1/以太坊/UTC源阅读器。 它使用共享的周期性角色生命周期;CLI拥有进程中断; 提供程序清理和探测。导入模块不会打开数据库; 打开发布者状态加载 node:sqlite 明确。

逻辑唤醒创建和挂起的发件箱持久性共同提交。持久的承认 收据、连续发布者游标和发件箱分别清除共同提交 对于每个订阅者。过程死亡和模棱两可的反应重新发送相同的身体 一个新鲜的真正的钱包智威汤逊。发布者进度是准入进度,而不是 完成接收器计算。看到 runbook 对于所有权,加密保管,重试/取消规则,传输限制和 其余的宿主/序列门。

status().deliveryDiagnostics 报告固定的故障阶段/原因计数器和 最近收到的HTTP状态和有界的Retry-After延迟。这些计数器 仅覆盖当前进程并在重试成功后存活;两者都不是 遗失通知不计算持久收据。现有的 failures 场 保持当前连胜并在匹配确认时清除。畸形的 200/202的内容不算作交付。错误文本和响应体是 排除在诊断之外。

耐久性模型

这个 2026-10-05补救 在作用域唤醒上用一个事务替换拆分身份/队列提交 和令牌绑定,稳定的收据,准确的授权工作,租赁状态和 完成。重复令牌绑定/过期扩展是原子性的。全/细胞膜SQLite 在一个本地主机上协调对象和进程;有限的100毫秒繁忙等待 在未解决的争论中明显失败。重试保留逻辑身份。

文件系统适配器在中使用相同的权限 receiver.sqlite。私人 pending/ 和 inflight/ JSON文件是投影,仅由 link 还有同步目录。他们不决定入场或租赁所有权。 缺失的凸出物可以修复;损坏或不匹配的字节停止处理 并随时准备接受检查。声明验证形状和规范散列 反对承诺的权威。补全将在保持时移除保留的函数体 稳定的身份/收据墓碑;过时的文件无法恢复已完成的工作。 repairProjections() 显式扫描活动工作和文件系统引用。

所属目录/文件为 0700/0600,包含owner、regular-file和symbol - link 检查。不安全的现有保管被拒绝,而不是修改不相关的路径。 发布者游标/发件箱替换仍然是单写入器 rename,带文件 以及出版目录同步。读取,解析,状态和同步失败传播; 保留的重试字节/ id不会因为读取失败而被替换。

在日志模式更改之前,将拒绝遗留存储。使用 脱机迁移手册 在已停止所有者副本上;保留备份、库存和隔离证据。这个 新的源格式故意与旧的编写器和运行时不兼容 没有双读卡器。

队列服务提供商

所有三个提供商都为每个索赔分配了一个新的租赁围栏。 ack()/release() 自动比较当前条目/状态/令牌。陈腐的或相反的完成 抛出 StaleWakeLeaseError; 重复同样的成功操作是惰性的。 经济复苏需要 recoverInflight({ consumersStopped: true }) 在每一个 消费者共享商店已经停止。断言是一个操作符契约, 不是活体探测器。单独启动不能建立静默。

扩展的共享一致性涵盖了陈旧/重复的完成和后续 保存。独立对象/进程允许竞争,真正的SIGKILL边界, 私有托管和签名HTTP测试对其进行了补充。供应商条款要求 reopen/跨编写器支持仍然显式跳过内存。

应用程序效果至少保留一次。栅栏的排队状态和分开制作 外部效果幂等或自动提交效果/检查点在其所有者。

node:sqlite 是内建的,所以这不会增加依赖项。它不发射射线 在固定的Node 26.9.0运行时加载时的ExperimentalWarning。

边界

当前的恢复证据包括本地对象/进程和复制的fixture; 不能主机丢失、存储硬件故障、恢复或跨机鉴定。 历史核心5号门的证据仍然局限于它的原始文物。看到 当前检查和测量的性能/保留成本的补救计划。 链上发行商路线图 通过阶段4-7的单个VM;多虚拟机协同部署需要一个 事务性共享存储、租赁和围栏,以及路线图第8阶段。

版本与发布记录

@xyo-network/event-kit-node 共发布 22 个版本,首次发布于 2026/08/21;过去 12 个月发布了 22 个版本。

版本发布日期距今
2.3.4latest2026/11/03今天
2.3.32026/11/03今天
2.3.22026/10/313 天前
2.3.12026/10/303 天前
2.3.02026/10/295 天前
2.2.32026/10/286 天前

关于 @xyo-network/event-kit-node 的常见问题

@xyo-network/event-kit-node 是什么?

Node 26+ Event Kit持久性,握手客户端,和SQLite源代码发布者运行时

如何安装 @xyo-network/event-kit-node?

在项目目录运行 npm install @xyo-network/event-kit-node,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:ajv(^8.20)、zod(^4.6)、ethers(^6.17)、async-mutex(^0.5)、@ariestools/sdk(^9.0)、@xyo-network/sdk(^8.1)、@ariestools/actor(^2.0)、@opentelemetry/api(^1.10)、@xyo-network/xl1-sdk(^5.8)、@xyo-network/sdk-protocol(^8.0)、@xyo-network/xl1-protocol(^5.8)、@xyo-network/xl1-statement-graph-sdk(^0.7)、@xyo-network/xl1-statement-graph-engine(^0.7)、@xyo-network/xl1-statement-graph-schemas(^0.7)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@xyo-network/event-kit-node 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@xyo-network/event-kit-node 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@xyo-network/event-kit-node 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=26。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@xyo-network/event-kit-node 可以商用吗?

@xyo-network/event-kit-node 使用 LGPL-3.0-only 许可。弱 Copyleft:作为库被调用时通常不要求开源你自己的代码,但修改库本身需以 LGPL 开源;前端打包合并后的适用边界存在不同理解。以上为概括,不构成法律意见,请以许可原文为准。

@xyo-network/event-kit-node 还在维护吗?

最新版本 2.3.4 发布于 2026/11/03(今天);至今共发布 22 个版本,其中过去 12 个月发布了 22 个;首次发布于 2026/08/21。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。