@ econ-v1/ app- sdk

状态 : 1.0.0-experimental —— API表面被冻结,等待至少两个一党包的验证. 中断更改 1.0.0-experimental.* 释放是可能的。 制作中精确的版本.

用于构建的脚本 / Bun SDK 类型 节点- App 用于此图的插件 节点 闪电驱动的市场守护进程。 Apps作为单独的 Bun 进程运行,并使用 JSON- newline 协议在一个 Unix- domain 套接字上与主机交谈.

它给你什么

• 一个抽象 NodeApp 类 —— 扩展它, 声明元数据, 并执行您需要的钩子 .
• 声明 route() 帮助者——注册HTTP处理器,并进行内置范围检查(在主机的表单执行上进行防御深入).
• invokeCapability() ——呼叫在宿主能力路由器上注册的任何能力.
• publishEvent() ——向主机事件总线发布命名空间域事件.
• host.{trace,debug,info,warn,error} ——文件支撑结构化记录.

快开始

bun add @econ-v1/[email protected]

import { NodeApp, runNodeApp, type AppRequest, type AppResponse } from "@econ-v1/app-sdk";

class MyApp extends NodeApp {
  readonly metadata = {
    name: "my-app",
    version: "0.1.0",
    author: "Me",
    description: "Hello-world Node-App",
    capabilities: ["http_handler"],
  };

  async init() {
    this.route("GET", "/hello", { requiredPermissions: [] }, async () =>
      this.json({ hello: "world" }),
    );
  }
}

runNodeApp(new MyApp());

主机启动 Bun 进程,通过 NODE_APP_SOCKET 环境变量,以及代理 HTTP 请求、事件和能力调用到套接字的路径.

汉堡应用程序

同一软件包服务于在Burger上运行的应用程序(app_type: "burger"),以及 所以汉堡应用取决于 @econ-v1/app-sdk 没有别的了 @econ-v1数字 :

两者都是从 sdk/burger-build 财务报告和审定财务报表 sdk/burger-types 在此 存储器由 bun run build (单位:千美元)scripts/build-burger-toolchain.ts) (中文(简体) ).

装入 burger-build 选择 burger 出口条件, 解决 @econ-v1/app-sdk 改为 dist/burger/index.js同样的API, 但主机频道是 burger:host (香料和JSON 由工会处理) 运行时,内存样本来自QuickJS运行时,没有 检测工人行踪 应用程序观察到的差异 :

• openDatabase() 默认为 256 KiB 页面缓存( Burger's cap) 页:1.
• 遥测保持不活动( E)telemetryActive() 实值 false:汉堡第1阶段 没有 fetch 适用于OTLP出口商.
• heap_snapshot_request 答案为 success: false。 。 。 .
• 在节点-app-burger上 0.3.3个巢 invokeCapability 携带 invocation_context_id 无论多少人 await将它与 处理器,如 Bun: SDK 负载 burger:async_hooks (ADR 004)加一个 动态导入和使用 AsyncLocalStorage在更古老的运行时间 导入会悄悄地失败, 第一阶段的行为会停止: 只有打过电话 在处理者第一个之前 await 随身携带身份证明,后期身份被分类 由主办方作为背景工作,从不作为前台(Burger合同C6), docs/superpowers/plans/2026-09-17-burger-00-overview-and-contracts.md) (中文(简体) ). 因此,同一SDK在每个运行时版本上都加载. 重建应用程序于 这个SDK在0.3.3上改变了它的巢中呼叫:现在它们携带呼叫者的呼叫 因此,东道主根据电话来电来评判他们(拒绝他们) capability.invalid_invocation_context 如果打电话者的背景已经 (已关闭)。 在发布前在0.3.3上运行应用程序的套房.

汉堡应用软件将SDK捆入 dist/index.js;运行时不共享.

生产大楼

@econ-v1/app-sdk 本身是一个 共同依赖 (已安装) 一次时间 /usr/lib/node/shared/node_modules/@econ-v1/app-sdk),所以这是 没有 绑入你的应用软件 dist/index.js。建造管道处理这个 自动——你不需要做任何特殊的事情.

您的应用程序的另一道道具在 三桶之一:

通过编辑选择一个私有的 DCP manifest.json数字 :

{
  "name": "my-app",
  "version": "0.1.0",
  "entrypoint": "dist/index.js",
  "nodeApp": {
    "privateRuntime": ["better-sqlite3"]
  }
}

使用 privateRuntime 仅针对有本地绑定或版本的软件包 与共享树相冲突 – 每个条目将其已安装的全部大小添加到 你的应用程序。 参见Cononic 参考文献: docs/app-development/12-typescript-dependencies.md 用于全面捆绑和解析模式.

构建命令

# Inside the node monorepo:
bash infra/scripts/build-bun-app.sh modules/my-app dist/build-aarch64/builtin-apps/my-app

# As a downstream app (after publishing):
bunx @econ-v1/app-sdk build .

深入防卫范围检查

this.route(
  "POST",
  "/admin/**",
  { requiredPermissions: ["payments:write"] },
  async (req) => this.json({ ok: true }),
);

主机已经执行 endpoint_policies 在申请到达应用软件之前 从您的清单中 route() 重新检查 request.caller.granted_permissions 作为第二道防线.

呼叫东道方能力

import { invokeCapability } from "@econ-v1/app-sdk";

const response = await invokeCapability({
  id: crypto.randomUUID(),
  capability: "core.storage.get",
  payload: { key: "user_pref" },
});

出版活动

import { publishEvent } from "@econ-v1/app-sdk";

publishEvent("my-app.user_created", { userId: 42 });

事件名称 必须 与应用程序名称相隔的名称( e)my-app.*);主机拒绝未命名的事件.

ABI 兼容性

类型脚本 SDK 目标 节点主机 API v1 过IPC。 线条格式是独立版本的,但跟原生(Rust / Go / C / Zig)应用中使用的 C ABI 一样的语义. 见 core/host-abi-v1/include/node-host-api-v1.h 为C表面.

许可证

根据其中任何一项颁发的许可证

• Apache 许可证,2.0版本
• MIT 许可证

随便你.