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 的當前版本。