capture-ledger

どの URL を撮るかを決め、撮れたものを台帳に残します。投げるのは capture-scheduler、撮るのは BrowserHive です。

3 つの役割

クロールには 3 つの仕事があり、それぞれ別のものが受け持っています。

役割	受け持つもの	すること
決める・記録する	capture-ledger（この repo）	どの URL を撮るかを決め、撮れたものを台帳に残す
投げる・報告する	capture-scheduler（Windmill の flow）	空いている BrowserHive を選んで頼み、段の結果を返す
撮る・保存する	BrowserHive	ブラウザで開いて撮り、成果物を bucket に書く

flowchart LR
  U((呼び出し元)) -->|クロールを頼む| L["capture-ledger<br/>決める・記録する"]
  L -->|1 段ずつ渡す| S["capture-scheduler<br/>投げる・報告する"]
  S -->|Capture| B["BrowserHive<br/>撮る・保存する"]
  B -->|成果物| O[(bucket)]
  S -->|段の報告| L
  O -.->|結果の manifest| L

capture-ledger とは

capture-ledger が答えるのは 「どの URL を撮るか」 の一点だけです。呼び出し元がクロールを頼むと、capture-ledger は起点の URL を揃え（明示された一覧か、Postgres の capture_targets テーブルの enabled な行）、辿る範囲を判断し、1 段ずつ Windmill の flow に渡します。実際に投げるのはその flow です。

capture-ledger の責務ではないこと

ブラウザの操作、スクリーンショットの撮影、WACZ の生成、S3 への保存 — これらは すべて BrowserHive の責務です。BrowserHive の docs は web に公開されていないので、 BrowserHive のチェックアウトで pnpm run docs:local を実行して読んでください。

投げることも、もう capture-ledger の仕事ではありません。 capture-scheduler の Windmill flow が BrowserHive を呼び（POST /captures）、capture-ledger の設定に BrowserHive の在り処は 1 つも入っていません。flow が報告する 1 段には、ページごとの taskId が載っています。capture-ledger はそこからアーカイブを生んだものをアーカイブ台帳に記録します。そこで入らなかったものは、後から pnpm run fga:reconcile が、段の報告の書き留めた manifest の鍵を読んで拾います。

目的別の入口

やりたいこと	ページ
はじめてスタックを立てる	クイックスタート
開発環境を用意する	開発環境
URL のリストを管理する	URL ソース
クロールの撮り方を変える	キャプチャオプション
新しい BrowserHive に上げる	BrowserHive の更新
構成を理解する	アーキテクチャ