永続実行ラボ:ワークフローをわざと落とし、ジャーナルから再開する

このラボは、Temporal、Restate、DBOS のようなワークフローエンジンの土台にある考え方、永続実行を基本から教えます。生徒ひとりひとりに PostgreSQL のデータベースと、約100行のエンジンを持つ Python のワーカーがあります。ステップは1回だけ動き、その結果はジャーナルのテーブルに書かれ、クラッシュのあとの再実行は見つけた行をリプレイして続きから進みます。

生徒はワークフローをわざと落とし、再開します。カードに2回課金してしまう単純なジョブ、ジャーナルをリプレイする注文、冪等性キーで安全にした課金、リトライの予定、永続タイマー、サガとして予約する旅行です。永続実行モジュールに付属します。商用のエンジンは動きません。モジュールはそれらを言葉で比べます。

生徒が学ぶこと

途中で落ちたジョブを最初からリトライすると、なぜ副作用が繰り返されるのか。終わったステップのジャーナルがあれば、再実行がどう続きから進めるのか。効果とそのジャーナルの行のあいだで落ちると、なぜまだ効果が繰り返されるのか、そして冪等性キーがそのすき間をどうふさぐのか。リトライが上限、ジッター、回数の制限つきでどう待ち時間をのばすのか。永続タイマーが、動き続けるプロセスではなく行としてどう待つのか。後のステップが失敗したとき、サガが終わったステップを新しいものからどう取り消すのか。生徒はジャーナルを SQL で読み、ワークフローのコードが毎回同じステップを求めなければならない理由を見ます。分散システムやソフトウェア工学の授業、バックエンドの信頼性のモジュールに向いています。

ブラウザーで実行する

ラボは2つのサービスを起動します。PostgreSQL の db と、/tmp にラボのファイルを持つ Python の worker です。worker はデータベースが答えてから起動します。ラボの横のターミナルには自前の Python がないので、docker exec でそこに届きます。Run は毎回同じものを出します。時計を読むものはなく、ただ一つのランダムな選択はシードが固定です。

  1. コンテナーのページを開く. バーの「つくる」を開き、「コンテナーを実行」を選びます。ページは誰でも開けて、Git ラボと SQL ラボはアカウントなしで起動できます。ほかのラボには無料アカウントが必要です。アカウントを作成してサインインし、「起動」を押します。
  2. ラボを探す. 「サンプルラボ」のカードにすべてのサンプルが並んでいます。Durable executionを探します。
  3. 「起動」を押す. 「起動」はそのまま1回の操作で実行します。「先にファイルを編集」は compose ファイルを開くので、起動する前に変更できます。
  4. 開く. ラボのページで「ターミナルを開く」を押します。ラボには Web ページがないので、「ブラウザーで」の下にリンクはありません。docker exec worker python3 order.py order-7 --fresh --crash-after 2 と入力すると、2つのステップを動かし、落ちた行を出して止まります。続けて docker exec worker python3 order.py order-7 と入力すると、その2つのステップをジャーナルからリプレイし、残りの2つを動かします。

生徒に提出させるもの

engine.py で書いた自分のワークフローです。たとえば、アカウントを作り、歓迎メールを送り、面談を予約する登録です。それに、--crash-after で落とした実行の出力、それを再開した実行の出力、psql で読んだジャーナルの行を添えます。そのあとに、どのステップが2回動き、どれが動かなかったかを一文で書きます。よい答えは、副作用をすべてステップの中に置き、お金を取るものには冪等性キーを付けています。

このラボの基本レッスン

Durable Execution Basics は、このラボで進める小さなレッスンです。生徒は単純なジョブを落として支払いが2件あるのを数え、注文のワークフローを落としてジャーナルを読み、それを再開し、課金の中で落ちたあとも冪等性キーで1回だけ課金し、車で失敗する旅行を予約してサガがホテルと飛行機を取り消すのを見ます。

無料の個人アカウントでは「ホーム」にある Basics モジュールに入っていて、どの学校もライブラリーの Basics フォルダーからコピーでき、新しい学校には Data Labs (Sample) というモジュールに入っています。あえて小さくしてあり、ラボで進めるレッスンとは何かを先生に見せる役目です。あとはラボが受け持ちます。変更したいときは、自分のモジュールにコピーしてください。

GitHub のコード

compose ファイルに Dockerfile はありません。公開されている標準イメージ postgres と python を、それぞれバージョンを固定し、メモリ 256 MB と 128 MB で動かします。PostgreSQL のライセンスは PostgreSQL License、Python は PSF License で、どちらも私たちは配布していません。worker は権限のないアカウントで動きます。ファイルは compose ファイル自身が書きます。その中には、PostgreSQL 自身のプロトコルの小さなクライアント pg.py もあります。標準の Python イメージにはデータベースのドライバーがないからです。ラボの外からは誰も届かないので、データベースはパスワードを求めません。ラボにはインターネットへの出口もありません。ラボを止めると何も残りません。

課題にする

何を提出するかを、課題に書いてください。

  1. ラボを作る. モジュールで課題を追加し、「コンテナーラボ」のカードを選んでから「GitHub リポジトリ」を選びます。https://github.com/mitsurutech/lab-durable-lab とブランチ main を指定します。compose ファイルは既定の compose.yaml です。変更したい場合は、先にリポジトリをフォークしてください。
  2. 公開して試す. 「公開」すると、確認したコミットに固定されるので、あとでリポジトリを変更しても、すでに出したラボは変わりません。まず自分のコピーを起動してください。
  3. 配布する. ほかの課題と同じように配布します。期限を付けることもでき、課題には何をするか、何を提出するかを書いておきます。
  4. 提出物を採点する. 生徒のコピーを開いて提出された内容を確認し、採点します。足りない場合は理由を書いて差し戻します。

このラボを試す、そして費用

無料の個人アカウントで、このラボの基本レッスンに取り組めます。毎月、ほとんどのレッスンに足りる無料クレジットがあり、カードは要りません。クラスで使う場合、学校は最初の365日間、生徒50人まで無料で、その後は生徒1人あたりの年額です。すべてのラボが含まれ、教職員は無料です。

よくある質問

これは Temporal、Restate、DBOS ですか。
いいえ。ラボのために書いた約100行のエンジンで、それらのエンジンに共通する考え方を持っています。再実行がリプレイする、終わったステップのジャーナルです。本物のエンジンは、たくさんのワーカー、キュー、コードを変えるための道具、Web ページを加えます。永続実行モジュールは、それらを言葉で比べます。
Run はどうやってワークフローを落とすのですか。
--crash-after と --crash-inside を付けると、worker は名指した場所で自分のプロセスを終了コード 3 で止めます。だからクラッシュは本物で、毎回同じです。次の Run をオプションなしで動かすと、ジャーナルから再開します。
2回目の Run が違う行を出すことがあるのはなぜですか。
ジャーナルがまだ残っているからです。終わったワークフローを再開すると、すべてのステップをリプレイし、新しいことは何もしません。ワークフローを始める Run にはどれも --fresh が付いていて、先にそれを忘れさせるので、もう一度押せます。
ラボを停止して起動したあと、何が残りますか。
何も残りません。ジャーナル、支払い、生徒が書いたファイルは消え、ラボは起動するときに自分のファイルをまた書きます。提出するものは、停止する前にターミナルからコピーしてください。