obelisk

方尖碑

构建在 WASM 组件模型之上的确定性工作流引擎

项目状态/免责声明

这是预发行版。

该存储库包含用于本地开发和测试的后端代码。该软件不提供 CLI、gRPC 或数据库架构的向后兼容性保证。

支持的平台

• Linux x64

核心原则

• 架构优先，使用 WASM 组件模型的 WIT 语言作为工作流和活动之间的接口。
• 后端开发人员的喜悦
  • 用于运行执行器、工作流和活动的单一进程，以及用于外部活动的逃生舱口（计划中）。
  • 自动重试错误、超时、服务器崩溃后继续执行工作流。
  • 可观察性（计划）- 必须保留参数和结果以及函数层次结构。
  • 可组合性 - 嵌套工作流程，调用以任何支持的语言编写的活动
  • 重放并分叉现有工作流程（计划）。解决问题并继续。

概念和特点

• 活动必须是幂等的（可重试），以便可以随时停止并重试。该合同必须由活动本身履行。

  • WASI 活动在 WASM 沙箱中执行
    • 能够使用 WASI 0.2 HTTP 客户端联系 HTTP 服务器。
    • 能够读/写文件系统（计划）。
  • 最大执行持续时间支持，之后执行将暂停到间歇性超时。
  • 出现错误时重试 - WASM 陷阱（恐慌）或返回错误结果时重试。
  • 使用指数退避重试超时。
  • 执行结果被持久化。
  • 性能选项可保持父工作流程执行热或卸载并重播事件历史记录。

• 确定性工作流程

  • 可重放：每次状态更改时都会保留执行，以便在中断或错误后可以重放。
  • 运行在 WASM 沙箱中，与环境隔离
  • 自动重试数据库错误、超时甚至陷阱（恐慌）等故障。
  • 能够生成子工作流或活动，要么阻塞直到结果到达，要么异步等待结果。
  • 可以使用添加的日志消息和其他不改变执行确定性（计划）的更改来重播工作流。
  • 连接集允许结构化并发，要么阻塞直到子执行完成，要么取消那些未等待（计划）的执行。

• WASI 网络钩子

  • 作为 URL 路径安装，提供 HTTP 流量。
  • 能够生成子工作流程或活动。

• 窃取工作的执行者

  • 定期锁定一批当前挂起的执行，开始/继续执行
  • 清理带有过期锁的旧挂起执行。将重试（计划）具有预算的执行。
  • 并发控制 - 限制可以同时运行的工作线程数量。

安装

码头工人

CONTAINER_ID= $( docker run -d getobelisk/obelisk )
docker logs --follow $CONTAINER_ID | grep " Serving gRPC requests " 

docker exec $CONTAINER_ID obelisk client component list
# See Usage for more details

预构建的二进制文件

从 GitHub 版本页面下载最新版本。

使用 crates.io 的最新版本

使用cargo-binstall下载

cargo binstall --locked obelisk

或使用货物构建

cargo install --locked obelisk

尼克斯片

nix --extra-experimental-features nix-command --extra-experimental-features flakes run github:obeli-sk/obelisk

用法

生成示例配置文件

obelisk server generate-config

启动服务器

obelisk server run

获取已加载函数的列表

obelisk client component list

提交要执行的函数（工作流或活动）

 # Call fibonacci(10) activity from the workflow 500 times in series.
obelisk client execution submit testing:fibo-workflow/workflow.fiboa ' [10, 500] ' --follow

里程碑

里程碑 1：发布二进制文件 - 完成

• 让obelisk应用程序作为 Linux 二进制文件启动并运行
• 工作流程和 wasm 活动的调度、超时和失败的重试
• 使用sqlite进行持久化
• 使用连接集同时启动子工作流程/活动
• 用于 wasm 组件配置和调度的基本 CLI
• Github发布，docker镜像，发布到crates.io，支持cargo-binstall

里程碑 2：允许通过 CLI 进行远程交互 - 完成

• 将组件和常规配置移至 TOML 文件中
• 从 OCI 注册表中提取组件
• 将方尖碑镜像发布到 Docker Hub（ubuntu、alpine）
• Obelisk客户端组件推送
• 用于执行管理的 gRPC API
• 跟踪最顶层的父级
• 创建时的参数类型检查，系统中所有函数的类型内省
• 记录和跟踪配置，将事件发送到 OTLP 收集器

里程碑 3：Webhooks、验证、结构化并发、Web UI - 启动

• HTTP Webhook 触发器能够启动新的执行（工作流和活动），能够在发送响应之前等待结果。
• 转发活动和 Webhook 的标准输出和标准错误（可配置）
• 支持分布式跟踪，记录 OTLP 收集的组件
• 通过-await-next从任何执行结果（例如陷阱、超时、错误变体）映射到其他执行结果
• 服务器验证 - 下载组件、检查 TOML 配置并将组件导入与导出进行匹配。
• 连接集的结构化并发 - 阻塞父级直到所有子级执行完成
• 基于 HTML 的 UI，用于显示执行情况、事件历史记录和关系
• 以WIT格式打印每个组件的导入和导出
• 异构连接集，允许一个连接集组合多个函数签名和延迟
• 通过活动、Webhook 的目录映射公开文件系统
• 公开活动、webhook 的网络配置
• 活动保持活动状态，延长锁定直至完成
• C#、Go、JS、Python 示例

未来的想法

• 用于执行管理的交互式 CLI
• 外部活动 gRPC API
• OpenAPI 活动生成器
• 从 WASM 活动生成进程，读取其输出
• 背压：对待处理队列的限制，或者驱逐策略，在LimitReached上减慢速度
• 外部执行器支持 - 仅基于 WIT 导出启动执行。外部执行器必须共享对 sqlite 数据库的写访问权限。
• 将工作流程/活动限制为执行者的标签
• 周期调度
• 截止日期传播
• 取消传播
• 队列容量设置，为执行提交增加反压
• 能够模拟注入故障的系统行为
• 通知活动。调用时，必须通过 API 端点提供返回值。
• 用于列出执行及其开放通知活动的 API。
• 只读查询函数，可以在等待点期间或执行完成后调用。
• 可选的stdout、stderr持久化/转发
• 通过接口导入从调用者到导出它的许多组件之一的智能依赖路由。
• 智能重试 - 重试预算，当活动失败特定百分比的请求时禁用重试
• 添加到重试中的可配置抖动
• 工作流程内存快照可加快重放速度
• 适用于工作流程的时间旅行调试器，适用于 WASM 部署
• 能够在检测到非确定性时通过审批系统修复一组工作流程
• 在工作流程和活动中追踪字符串的起源
• Webhook 映射：运行单个函数，在 HTTP 和 WIT 定义的参数和返回值之间进行转换
• 用于传出 HTTP 和 Webhook 的分布式跟踪上下文转发
• 允许在 WIT 中指定永久错误变体作为注释
• 支持（分布式）传奇 - 定义活动回滚，在失败的工作流程上调用它们

从源头构建

使用 nix flakes 设置开发依赖项：

nix develop
# or `direnv allow`, after simlinking .envrc-example -> .envrc

或者手动下载所有依赖项，参见dev-deps.txt和基于Ubuntu验证的Dockerfile运行程序

cargo run --release

运行测试

./scripts/test.sh

使用madsim模拟器进行确定性测试

./scripts/test-madsim.sh

贡献

该项目有一个路线图，并且按一定顺序添加和测试功能。如果您想贡献某个功能，请在 GitHub 上讨论该功能。为了让我们接受补丁和其他贡献，您需要采用我们的贡献者许可协议（“CLA”）。可以在此处找到 CLA 的当前版本。