@ariestools/aries-dapp-core

中文文档

0.3.0发布于 2026/10/31LGPL-3.0-onlyTypeScriptES Module近 30 天下载 2917

Aries dapp后端核心: DappActor (forked xl1 演员模式),全流程提供者定位器,可插接的还原器,以及运行存储服务器加演员的由编组守护进程

文档目录15 节

发展与生产
块
生产成分(仅限出口)
出版物布局
本地守护进程( 只编辑)
国际
减员模块合同
信封( 守护)
生产入口(不是CLI bin)
最低优先权IAM/R2注解
出版安全
释放、接针、回滚、GC
递增的高心率出版物
浏览器中性消费者
R2合同测试

@ riestools/ aries- dapp- core (日语)

App后端核心:全流程的提供者定位器,可插接的还原器,相通用于 S3/R2 备份索引的生成出版物和存量 DappActor 计时器。设计用途 仅限出境 生产指数(无公众入境) 关于计算过程的API)以及当地 aries dapp 发展修补.

发展与生产

表面	目的
`aries-dapp-server` 宾+ `noopReducer`	仅当地发展 - 嵌入式 s3rver 通过 `@ariestools/aries-dapp-serve`,内存支持,没有真正的衍生
项目所属入境点+实际裁减点	生产 ——注入S3/R2客户端,将逻辑角色绑定到桶/前缀上,发布不可变的世代

dapp-serve 而"Noop"守护进程仍然是明确的本地工具. 生产使用是一个 项目所属 创建此软件包的可执行文件; dappcore does 不动态加载任意的还原模块,也不存储应用程序授权(签署种子、 Webb 控制器根等).

已公布状态和索引为 可重建预测而不是权威. 不可认为公共桶对简洁的私人材料是安全的.

块

AbstractActor - 创建/启动/停止生命周期,不重叠计时器 (单位:千美元)firstRunDelay 是第一次通过之前的真正延迟,中止信号开启停机,可选停机飞行工作,准备合同.
DappProviderLocator 编号 : createDappLocator ——全过程定位. 一个共享不同角色的 S3 客户端,或 每名客户 最低特权主; 逻辑角色 → 物理桶 + 前缀 + 可选的公用CDN基. 这个数据角色默认只登记为只读( e)put - 扔下来).
DappObjectReader 编号 : DappObjectWriter 编号 : DappBucketStore 能力拆分: 减号见 data ; 状态/索引仍然是作者. 获取/getWithMeta/stat/put(元数据+有条件写作)/list */destroy.
publishGeneration 编号 : readPublishedHead ——有栅栏的出版物:只创建生成对象, 以 conditional-head CAS或注入式租赁 (或 unfenced 仅用于本地 s3rver). 回返 { ok: true, … } 或者说 { ok: false, conflict }。。。 .
writeIndexerStatus 编号 : readIndexerStatus - 耐用地板/装饰, 已完成位置、观测到源头、生成、成功/错误时间戳,连续的失败(CDN- revalidate).
DappActor - 驱动器 a DappReducer 间隔; 可选状态出版; 可选 maxConsecutiveFailures 用于主管重新启动.
bootDappActors - 开始N演员,准备就绪,停止早期演员如果后来一个失败.

生产成分(仅限出口)

import { S3Client } from '@aws-sdk/client-s3'
import {
  bootDappActors,
  createDappLocator,
  publishGeneration,
  type DappReducer,
} from '@ariestools/aries-dapp-core'

const client = new S3Client({
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
  },
})

const locator = createDappLocator({
  client,
  ownClient: true,
  bindings: {
    data: {
      bucket: 'my-dapp',
      prefix: 'data',
      publicBaseUrl: 'https://cdn.example.com/data',
    },
    state: {
      bucket: 'my-dapp',
      prefix: 'state',
      publicBaseUrl: 'https://cdn.example.com/state',
    },
    index: {
      bucket: 'my-dapp',
      prefix: 'index',
      publicBaseUrl: 'https://cdn.example.com/index',
    },
  },
})

const reducer: DappReducer = {
  name: 'my-app-indexer',
  version: '1',
  async reduce({ state, index, signal, logger }) {
    const published = await publishGeneration({
      state,
      index,
      safety: { mode: 'conditional-head' }, // fail closed if provider lacks CAS
      // expectedHeadEtag: prior?.headEtag,
      reducer: { name: 'my-app-indexer', version: '1' },
      source: { cursor: '…', completedPosition: '…', observedHead: '…' },
      stateObjects: [{ key: 'view.json', body: '{}', contentType: 'application/json' }],
      indexObjects: [{ key: 'by-id.json', body: '{}', contentType: 'application/json' }],
      signal,
    })
    if (!published.ok) {
      logger.warn(`publish conflict: ${published.conflict.kind} ${published.conflict.message}`)
      return // do not advance checkpoint on conflict
    }
    logger.info(`published ${published.generation}`)
    return {
      cursor: '…',
      lastCompletedPosition: '…',
      observedSourceHead: '…',
      generation: published.generation,
      generationRoot: published.manifestKey,
    }
  },
}

const actors = await bootDappActors(locator, [{
  name: 'MyIndexer',
  reducer,
  firstRunDelayMs: 1_000,
  reduceIntervalMs: 15_000,
  maxConsecutiveFailures: 10,
  publishStatus: true,
}])

客户从不联系此进程。他们读了 head.json,生成对象, 财务报告和审定财务报表 status.json 从公共CDN/基址。证书不在已发布配置和日志.

另见 src/examples/productionComposition.ts。。。 .

出版物布局

state/head.json                          # mutable head (revalidate CDN)
state/status.json                        # indexer status (revalidate CDN)
state/generations/<id>/manifest.json     # immutable
state/generations/<id>/…                 # immutable state objects
index/generations/<id>/…                 # immutable index objects

头写了 最后一个。头部离开前的崩溃生成可见。检查站不得通过完全公布的检查站生成( 演员在成功减少后只记录生成) 已发布标题).

本地守护进程( 只编辑)

组装的垃圾桶dist/bin/dappServer.mjs)启动存储服务器和 a 达普达多. aries dapp up 产下它.

国际

# Empty spine (noop reducer)
aries dapp up

# Real project reducer (ESM .mjs or package export — TypeScript not supported)
aries dapp up --reducer ./dist/indexer.mjs
aries dapp up --reducer ./dist/indexer.mjs --reducer-export myIndex
aries dapp up --reducer @myorg/my-dapp/indexer

# Persist buckets across restarts
aries dapp up --backing disk --data-dir ~/.aries/dapp/data

使用此软件包运出的实例减小器 :

aries dapp up --reducer ./node_modules/@ariestools/aries-dapp-core/examples/countFactsReducer.mjs
# monorepo:
aries dapp up --reducer ./packages/dapp-core/examples/countFactsReducer.mjs

减员模块合同

模块必须导出一个 DappReducer数字 :

默认导出,或
命名导出 reducer,或
任何名称通过 --reducer-export 编号 : DAPP_REDUCER_EXPORT

// dist/indexer.mjs
export default {
  name: 'my-index',
  version: '1',
  async reduce({ data, state, index, signal, logger }) {
    // read data, publishGeneration / publishIncremental, return progress
  },
}

当地出版物应使用 safety: { mode: 'unfenced' } (或荣誉) DAPP_PUBLICATION_SAFETY,守护进程设定为 unfenced (默认情况下). s3rver 不支持可靠的CAS头.

信封( 守护)

变量	默认	页:1
`DAPP_PORT`	`8801`
`HOST`	`127.0.0.1`
`DAPP_BACKING`	`memory`	`memory` \| `disk`
`DAPP_DATA_DIR`	`~/.aries/dapp/data`	磁盘根
`DAPP_REDUCER`	(无)	路径到 `.mjs`编号 :`.js` 或包导出
`DAPP_REDUCER_EXPORT`	默认 / `reducer`	命名导出
`DAPP_REDUCE_INTERVAL_MS`	`5000`
`DAPP_FIRST_RUN_DELAY_MS`	`0`
`DAPP_PUBLICATION_SAFETY`	`unfenced`	由守护进程为缩小工程设置
`DAPP_PUBLIC_HOST` 编号 : `DAPP_TLS_*`		`--ssl auto`

下 --ssl auto 守护进程通过 NODE_EXTRA_CA_CERTS。。。 .

生产入口(不是CLI bin)

执行没有运行 aries-dapp-server 或者说 aries dapp up 在生产中。写一个项目自有程序:

构建一个 S3Client 用于 R2/S3( env/IAM 证书—— 从未登录)
电话 createDappLocator({ client, bindings, ownClient: true })
执行a DappReducer (静态进口——不需要动态CLI载荷)
电话 bootDappActors 与 safety: { mode: 'conditional-head' } 内部 publishGeneration 编号 : publishIncremental
SIGTERM的收听和停止演员+ locator.destroy()

见 examples/productionComposition.ts 和上文组成部分. 没有进入的公众听众;客户端从CDN读取头部/状态/对象.

最低优先权IAM/R2注解

作家( 私人 API ): 状态/索引需求 s3:GetObject, (中文(简体) ), s3:PutObject,以及通常 s3:ListBucket 关于角色前缀。数据角色 : GetObject编号 :ListBucket 仅(无) PutObject) (中文(简体) ). 优先通过 createDappLocator({ clients: { data, state, index } })。。。 .
公开CDN: 允许匿名 GET编号 :HEAD 只有这个. 拒绝 s3:ListBucket 财务报告和审定财务报表全部 Put*编号 :Delete* 公费从不要求公开名单或点.
全权证书 不得在已发布的标题/显示/状态或日志中出现.

出版安全

模式	使用
`conditional-head`	当提供者支持 If-Match / If-None-Match 时生产
`lease`	用应用喷入式租赁/装配适配器生产
`unfenced`	只有本地 s3rver / 测试 ——无同时机安全

释放、接针、回滚、GC

import {
  listReleases, pinRelease, rollbackHead,
  planGarbageCollection, runGarbageCollection,
} from '@ariestools/aries-dapp-core'

await pinRelease(state, 'gen-a', { reason: 'hotfix' })
await rollbackHead(state, {
  targetGeneration: 'gen-a',
  safety: { mode: 'conditional-head' },
  expectedHeadEtag: currentEtag,
})

const plan = await planGarbageCollection({
  state,
  index,
  policy: { mode: 'bounded', retainGenerations: 5, cdnGraceMs: 86_400_000 },
})
await runGarbageCollection(plan, { state, index }, { dryRun: true })

来源数据从来没有GC'd。活生生的头,针,和飞行中世代都受到保护.

递增的高心率出版物

用于变化不大的大型指数 publishIncremental (化学文摘社机构+256道) (原始内容存档于2013-10-29). sharded map.). 未更改的密钥保持稳定 cas/sha256/<hash> URL; 每个通过只写已更改对象 + 被触摸到的 shards + root + 接收.

import { publishIncremental } from '@ariestools/aries-dapp-core'

const result = await publishIncremental({
  state,
  index,
  safety: { mode: 'conditional-head' },
  expectedHeadEtag: prior?.headEtag,
  reducer: { name: 'addr-index', version: '1' },
  indexChanges: [{ key: 'by-source/0xabc', body: frameJson, contentType: 'application/json' }],
})

浏览器中性消费者

import {
  verifyPublishedView, resolveObject,
} from '@ariestools/aries-dapp-core/consumer'

const view = await verifyPublishedView({
  fetch,
  bases: { state: 'https://cdn.example/state', index: 'https://cdn.example/index' },
})
const one = await resolveObject({
  fetch,
  bases: { state: 'https://cdn.example/state', index: 'https://cdn.example/index' },
  logicalKey: 'by-source/0xabc',
  role: 'index',
})

这个子路径上的节点内置或AWS SDK.

R2合同测试

普通CI不需要R2机密. 持全权证书:

export DAPP_R2_CONTRACT_TEST=1
export R2_ACCOUNT_ID=…
export R2_ACCESS_KEY_ID=…
export R2_SECRET_ACCESS_KEY=…
export R2_BUCKET=…
# optional: R2_PUBLIC_BASE_URL=https://pub-….r2.dev
pnpm xy test @ariestools/aries-dapp-core

见 src/spec/r2.contract.spec.ts。。。 .

版本与发布记录

@ariestools/aries-dapp-core 共发布 19 个版本，首次发布于 2026/07/21；过去 12 个月发布了 19 个版本。

版本	发布日期	距今
`0.3.0`latest	2026/10/31	8 天前
`0.2.1`	2026/10/27	11 天前
`0.2.0`	2026/10/02	1 个月前
`0.1.22`	2026/09/14	1 个月前
`0.1.21`	2026/09/13	1 个月前
`0.1.20`	2026/08/30	2 个月前

关于 @ariestools/aries-dapp-core 的常见问题

@ariestools/aries-dapp-core 是什么？

Aries dapp后端核心: DappActor (forked xl1 演员模式),全流程提供者定位器,可插接的还原器,以及运行存储服务器加演员的由编组守护进程

如何安装 @ariestools/aries-dapp-core？

在项目目录运行 npm install @ariestools/aries-dapp-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@ariestools/sdk（^9.0）、@ariestools/actor（^2.0）、@ariestools/actor-model（^2.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 aries-dapp-server，可以用 npx aries-dapp-server 直接运行。

@ariestools/aries-dapp-core 支持 TypeScript 吗？

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

@ariestools/aries-dapp-core 支持 ESM 还是 CommonJS？

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

@ariestools/aries-dapp-core 需要什么版本的 Node.js？

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

@ariestools/aries-dapp-core 可以商用吗？

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

@ariestools/aries-dapp-core 的下载量有多少？

根据 npm 官方下载统计，@ariestools/aries-dapp-core 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,917 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@ariestools/aries-dapp-core 还在维护吗？

最新版本 0.3.0 发布于 2026/10/31（8 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/07/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @ariestools/aries-dapp-core

pnpmpnpm add @ariestools/aries-dapp-core
yarnyarn add @ariestools/aries-dapp-core
bunbun add @ariestools/aries-dapp-core

peer 依赖@ariestools/sdk ^9.0@ariestools/actor ^2.0@ariestools/actor-model ^2.0

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

命令行npx aries-dapp-server

在你的项目目录中运行此命令。

近 30 天下载

2,917

约 2917 次日均 97 次

统计周期 2026/10/07 – 2026/11/05
数据来自 npm 官方下载统计，1 天前更新

最新版本0.3.0发布于 8 天前

开源许可LGPL-3.0-only弱 Copyleft

包体积357 kB80 个文件 · 解压后

运行依赖5 个另有 3 个 peer 依赖

模块格式ES Module无副作用，可 tree-shake

TypeScript自带类型

Node.js>=26

发布版本19 个近 12 个月 19 个

首次发布2026/07/213 个月前

元数据更新2026/10/31

每一个软件包背后，
都有分享与创造的人。