HN 日本語サマリー

← 一覧へ戻る
プログラミング

Walgit: オブジェクトストアの前に単一バイナリで構成されるGitサーバー

Walgit: A Git server that is one binary in front of an object store (github.com)

80 pointsby handfuloflight11 コメント

要約

Walgitは、データベースやリーダー、ローカル状態に依存しない、オブジェクトストア(S3やGCS)の前に単一バイナリを配置するGitサーバーです。スマートHTTP(v0/v2)でのフェッチとプッシュ、バンドルURIクローン、Git LFS、Web UI、JSON API、プッシュポリシー、Webフックなどをサポートし、リポジトリサイズ以上のスケーラビリティを持ちます。各インスタンスは使い捨てキャッシュとして機能し、オブジェクトストアがリポジトリの真実の源となります。

全文翻訳

walgit — オブジェクトストアの前面にある単一バイナリのGitサーバー

walgitは、データベース、リーダー、そして重要なローカル状態なしでGitリポジトリをホストします。単一のバイナリを実行し、S3またはGCSバケットを指し示すだけで、以下のような機能を持つサーバーが利用できます:スマートHTTP(v0/v2)のフェッチとプッシュ、静的ファイルとして提供されるbundle-uriクローン、Git LFS、ブラウジング可能なWeb UI、SDK付きのJSON API、リポジトリごとのプッシュポリシー、Webhook — そして、実行するマシンよりも大きなリポジトリにスケールするサーバーです。walgitを実行する各マシンは使い捨てのキャッシュであり、バケットがリポジトリそのものとなります。

# 1. バケット(S3互換ストアまたはGCS)と設定ファイル
cat > walgit.toml <<'EOF'
[server]
listen = "0.0.0.0:8080"
public_url = "https://git.example.com"
auto_create_on_push = true
[server.auth]
mode = "token"
anonymous_read = false
tokens = [{ principal = "me", token_env = "WALGIT_TOKEN_ME", write = true }]
[store]
backend = "s3"
bucket = "my-walgit"
[store.s3]
endpoint = "https://s3.us-east-1.amazonaws.com"
region = "us-east-1"
EOF

# 2. 実行
WALGIT_TOKEN_ME=$(openssl rand -hex 24) walgit serve --config walgit.toml

# 3. 使用 — 新しい名前へのプッシュでリポジトリが作成されます
git -c http.extraHeader="Authorization: Bearer $WALGIT_TOKEN_ME" push https://git.example.com/acme/app.git main

これがデプロイの全てです。同じバケットを指すマシンを増やせば、それらは何も調整することなく、一貫して同じリポジトリを提供します。それらを全て停止しても、暖かさ以外は何も失われません。

これは、CursorがGit at any scaleで説明しているアーキテクチャ(彼らがContinuityと呼ぶシステム)のRust実装であり、リポジトリよりも小さいマシンで実行するために必要な変更が加えられています。このブログ記事は最初に読む価値があります。docs/reference/cursor-git-at-any-scale.mdにそのまま保存されています。


なぜこの形状なのか

Gitは分散型であり、それがホスティングを悩ませる唯一の理由はpackfileです。リポジトリ内のすべては、読み取り順序ではなく小さくなるように配置された大規模なバイナリパックに圧縮されています。すべてのGit操作は数ギガバイトのランダムウォークです。これは、ファイルがページキャッシュにあるラップトップでは問題ありませんが、ネットワークファイルシステム上では壊滅的です。そのため、「リポジトリをNFSに置くだけ」という試みは、それを試みたすべての大規模ホストで失敗しました。生き残った設計(GitHubのSpokes)は、実際のレポジトリをローカルNVMeに保持し、厳密な一貫性でパックファイルレベルでレプリケートします。これは、固定レプリカセット全体での3フェーズコミット、各リポジトリをそのマシンにマッピングするデータベース、そして多数のペット(専属サーバー)によって支えられています。

Continuityの洞察は経済性を変えます:オブジェクトストレージへのライトアヘッドログ(WAL)を真実の源とし、ディスク上の各リポジトリをキャッシュとします。プッシュはバケット内の不変オブジェクトとして保存され、小さなマニフェストが比較・交換(CAS)で書き換えられたときにのみ可視になります。そのCASこそがコンセンサスです — 選挙も、クォーラムも、プライマリもありません。どのインスタンスもプッシュを受け入れることができます。競合する2つのインスタンスが同時に成功することはありません。リポジトリを一度も見たことのないレプリカはログを読み込み、それを取得します。読み取りは調整なしで一貫性があります。なぜなら、すべての読み取りは最初にストアに何か変更があったか(条件付きGET、通常は304)を尋ねるからです。コンパクションは、リースを保持している誰かによって一度だけ実行され、ログに公開されるため、レプリカは再パックする代わりにコンパクションされたパックをダウンロードします。そして、WALが真実であるため、完全な来歴があります:すべてのプッシュとすべてのリパックは、任意の時点まで再生可能です。

walgitはそれをそのまま取り込み、モノリポを小さなマシンで扱うために必要なもの、つまり、リポジトリのパックがインスタンスに収まらない場合の参照とWebページの提供(HTTPレンジリクエスト über リモートリーダー)、ブロブはバケット内に保持しコミットとツリーはローカルに保持する(ヒストリーパック)、そしてクローンバイトをサーバーから完全に削除する(バンドルURI:新しいクローンとキャッチアップはバケットまたはCDNが配布する静的ファイル)を追加します。

何をするか

| | |
| --- | --- | --- |
| git | スマートHTTP v0/v2:プレフィックス付きls-refs、フィルター/シャロー/ディープン/サイドバンドオール付きフェッチ、receive-pack(アトミック、削除、タグ、プッシュオプション、レポートステータスv2)、<owner>/<repo>名前空間、sha1およびsha256リポジトリ。アップストリームgitはupload-pack/repack/bundleを実行し、walgitはreceive-pack、WAL、および配管を担当します。 |
| bundle-uri | カレンダースロット(週次フル、デイリーチェーン、アワーリー)でカットされたバンドルはWALの純粋関数です:新しいクローンは最新のフルバンドルとそれより上のチェーンをバケットからダウンロードし、サーバーには残りの部分のみを要求します。キャッチアップは、欠落したスロットのみをダウンロードします。リポジトリごとに2つのリスト:クローン用のbundles/list、フェッチ用のbundles/catchup。ブロブレスファミリーは--filter=blob:none用です。 |
| LFS | バッチAPI + 基本転送、バケット内のオブジェクト、インポートされたリポジトリの場合はアップストリームLFSサーバーからのオプションのリードスルー。 |
| Web UI + API | React UI(ツリー、ブロブ、コミット、差分、WAL自体のヘルスページ)は、/{owner}/{repo}/api/*下の読み取り専用JSON APIで提供されます。SHAアドレス指定された回答は不変で、どこでもキャッシュされます。長い回答はSSEとして進行状況をストリーミングします。repos.jsはページ、エージェント、スクリプト用の依存関係のないSDKです。 |
| ポリシー | リポジトリごとのプッシュルール(policy.json):保護された参照、グループ、ファストフォワードのみ、バイパスリスト。docs/POLICY.md。 |
| 設定 | リポジトリごとの設定(バンドルスケジュール、コンパクション、アップストリームフォロー)は、履歴とともにWALに公開されます。 |
| イベント | 小さなブリッジがWALをテールし、Webhookに参照イベントをPOSTします。(repo, seq, ref)ごとに正確に1回、耐久性のあるカーソルを使用します。docs/EVENTS.md。 |
| メンテナンス | チェックポイント、バンドルビルド、幾何学的コンパクション、ベース再構築、接続監査と修復 — 設定とWALから望ましい状態を毎パス計算し、最も重要な欠落作業の1つの制限付きユニットを実行する単一ループ。構築による自己修復:障害は穴を残さず、削除されたアーティファクトは「欠落」し、同一に再構築されます。 |
| 認証 | none(ループバック)、token(静的トークン)、oidc(任意のOpenID Connect発行者:ブラウザサインイン、IDトークン、Git用のwalgit発行アクセストークン)。/services/public/install.shは、開発者のマシンを1つの冪等なコマンドでセットアップします。 |
| ストア | S3およびS3互換(AWS、MinIO、rustfs、R2、Ceph、…)およびGCSを第一級として扱います。テスト用のインメモリストア。 |

簡単な仕組み

リポジトリはバケット内のWALです。 repos/<owner>/<repo>/の下には以下が含まれます:manifest.pb(小さい、CASで書き換えられる:ヘッドシーケンス、ライブパックセット、チェックポイントポインタ、設定 — 線形化ポイント)、log/<seq>.pb(不変エントリ:PUSH、COMPACT、CHECKPOINT、SETTINGS)、wal/<checksum>.pack|.idx|.rev|.bitmap|.commit-graph(不変のコンテンツアドレス指定パックとそのサイドファイル)、checkpoints/<seq>/(折りたたまれた参照スナップショット+パックインベントリなのでコールドスタートはスナップショット+テール)、bundles/、leases/(TTL付きCAS — 唯一のインスタンス間ミューテックス)、policy.json、lfs/objects/、events/cursor.json。

プッシュ:receive-packはパックをインデックス化し(スクラッチディレクトリでgit index-pack --fix-thin --rev-index)、接続性とポリシーをチェックし、pack ∥ idx ∥ log entryをアップロードしてからマニフェストをCASします。412エラーの場合、再読み込みし、すべての参照の古い値を再検証して再試行します。1つのインスタンスで1つのリポジトリへの同時プッシュは、1つのCASにグループコミットされます。クライアントは、バケットが受け取った後にのみokを見ます。

読み取り:マニフェストの条件付きGETを1回実行します。304ならローカルコピーから提供します。200なら新しいエントリを適用します。「適用」の意味は、リクエストが必要とするものによって異なります:参照(スナップショット+ログ → packed-refs、パックなし:広告、API、バンドルリスト)、提供(このマシンが保持できるパックセット:小さなパックとヒストリーパックをローカルに、大きすぎるベースはレンジで読み取る)、フル(すべてローカル、リパック用)、オブジェクト(リポジトリに収まらない場合のUI用のリモートリーダー)。パックダウンロードは独自のランタイムで実行され、参照リクエストをブロックしません。

配置は設定です。[placement] serve / maintainのグロブは、ホストがオブジェクトワークを行うリポジトリを指定します。参照レベルの読み取りはどこでも機能します。1台のマシン:デフォルトのままにします。複数台:モノリポをSSDのあるホストに置きます(cache.mode = "disk")、その他はすべて小さなマシンに置き、/<owner>/<repo>でルーティングします。

何も静かに待機しません。遅いものはすべて、ID、ログ、進行状況ストリームを持つタスクです — サイドバンド2(remote: * …)でGitに、SSEとしてブラウザにナレーションされます。

AGENTS.mdは完全なアーキテクチャと運用マニュアルです:制約、WAL戦略、理由付きのすべての設計決定、不変条件、およびコストモデル(バケットへのラウンドトリップが予算です)。

実行方法

# ビルド(Rust per rust-toolchain.toml, protoc, Node 24 + pnpm for the web UI が必要)
just web-build && cargo build --release -p walgit-cli
# または: nix build .#walgit        または: podman build -t walgit -f Containerfile .

# 1台のマシン、TLSはwalgit自身で提供、ローカルS3ストア(コンテナ内のrustfs)
just dev-store
./target/release/walgit-server --config walgit.standalone.toml
open https://walgit.localhost:8080/
  • walgit.standalone.toml — 1台のマシン構成(自己署名TLS、rustfs、全役割)。ここから開始します。
  • walgit.example.toml — 各キーにデフォルト値とコメントが付いています。
  • Containerfile, flake.nix — OCIイメージとNixパッケージ/開発シェル。
  • deploy/nginx.conf.example — オプションのNginxを前面に配置:パブリックTLS、各クレデンシャルに対する1つのauth_request、そしてバイトオフロード:walgitはバンドル/LFSダウンロードにX-Accel-Redirectで応答し、Nginxはバケットから直接オブジェクトをストリーミング+キャッシュします(S3プリサインまたはwalgitのベアラー付きGCS)。このファイルは契約を文書化しています。

役割(server.roles):serve(Git、API、UI、バンドル、LFS)、maintain(チェックポイント、バンドル、コンパクション、fsck/修復)、events(Webhookブリッジ)。空の場合はすべてを意味します。任意の数のserveホストが1つのバケットを指すことができます。各リポジトリに1つのメンテナー(配置グロブ)を与えれば完了です。

認証
モード誰が入れるかGitはどのように認証するか
none全員が書き込み権限を持つanon(ループバック実験)なし
token設定内の静的tokens(token_envは環境から秘密鍵を読み取る)Authorization: Bearer <token>、またはHTTP Basicパスワードとしてのトークン
oidc任意のOpenID Connect発行者(issuer, oauth_client_id/secret, allowed_domains/allowed_emails):Google, Entra, Okta, Auth0, Keycloak, Dex, GitLab…walgitアクセストークン:ブラウザで一度サインインし、/_auth/tokensで1つ作成し、インストーラーに貼り付けます。ステートレス(session_secret, access_token_ttl付きHMAC);秘密鍵をローテーションするとすべて無効になります。発行者からのIDトークン(audiences)と静的tokensも機能します。

開発者のセットアップは1つの冪等なコマンドです — sh -c "$(curl -fsSL 'https://git.example.com/services/public/install.sh')" — これは、ユーザーのみが読み取れるファイルにトークンを保存し、小さなGitクレデンシャルヘルパーをインストールします(Git ≥ 2.46:getにauthtype=Bearerで応答し、実際の401ではトークンをeraseして新しいトークンがどこから来るかを伝えます)、そしてtransfer.bundleURIを有効にします。?repo=owner/nameでクローンがすぐに実行されます。

開発
just test          # 高速で隔離されたティア(1分未満):単体テスト+クイック統合、インメモリストア、実際のGit
just e2e           # サーバーに対する実際のGit(約20秒)
just warnings      # 全ターゲットでRustc警告ゼロ
just ci            # 上記すべて
cargo test -p walgit-server --test sim     # 障害注入シミュレーション(クラッシュ、パーティション、古い読み取り)
just test-s3       # ローカルrustfsに対するストア契約

コードマップ:

crates/
  walgit-proto    protobufスキーマ(wal.proto)、ログフレーミング、ストアキー
  walgit-store    ObjectStoreトレイト(CASバージョン、条件付きGET、レンジ、コンポーズ);バックエンドs3、gcs、メモリ;リース
  walgit-git      ディスク上のベアリポジトリ、receive-pack、パック取り込み、参照↔packed-refs、広告、upload-packドライバー
  walgit-wal      RepoHandle:同期レベル、公開(グループコミット+CAS)、チェックポイント、ログリーダー、リモートリーダー、タスク
  walgit-bundle   bundle-uri:スロットとチェーン、ビルド、ヘッダー∘パックコンポジション、リスト、保持
  walgit-server   axum:スマートHTTP、LFS、バンドル、認証(なし/トークン/oidc)、メンテナーループ、アップストリームフォロー、
                  web/(API、UI、SDKルート、SSE)、setup.rs(インストーラー+レシピ)、イベントブリッジ
  walgit-config   walgit.toml(+ WALGIT__ 環境オーバーライド)、リポジトリごとの設定マージ、フェイルクローズバリデーション
  walgit-cli      `walgit serve|import|compact|bundle|wal|mirror|synth|config|repo`;`walgit-server` = `walgit serve`
web/              React SPA(Vite)+ sdk/repos.ts、バイナリにビルド済み;ワイヤー契約はweb/API.md
docs/             BUNDLE_URI_DESIGN、ROUNDTRIPS(コストモデル)、POLICY、LFS、INTEGRITY、EVENTS、CONTRACT、patches/

記憶すべき不変条件

  • マニフェストCASは唯一のコミットポイントです。それ以前のすべては不可視であり、それ以降のすべては冪等で再生可能です。
  • 不変オブジェクトはコンテンツアドレス指定されています。マニフェスト、バンドルリスト、リース以外は何も上書きされません。
  • すべての読み取りは最初にバケットに対して再検証されます。「最終的には」ということはありません。
  • ローカルディスクはキャッシュです。メモリもキャッシュです。バケットがリポジトリです。
  • 配置は設定されており、推測されることはありません。参照レベルの読み取りはどこでも機能し、オブジェクトワークは配置された場所でのみ機能します。
  • メンテナーの出力は(設定、WAL)の純粋関数です。欠落しているものは単に「まだ構築されていない」だけです。
  • コストは、ホットパス上の参照数、またはパックを保持するには小さすぎるマシン上のパックサイズとスケーリングしてはなりません。
  • 長い作業はタスクです:発見可能、アタッチ可能、ナレーション可能。
  • 正しいことだけでは不十分です:すべてのプロトコル変更は、バケットへのラウンドトリップに基づいて判断されます(docs/ROUNDTRIPS.md)。

ライセンス

MIT — LICENSEを参照してください。