Bundle URIs

バンドル URI 標準は、 複数の作業(workload)を満たすのに十分な柔軟性を目指しています。 バンドル提供側(bundle provider)と Git クライアントには、 バンドル URI を作成および使用する方法についていくつかの選択肢があります。

各リポジトリは異なり、そして、各Git サーバーごとに異なるニーズがあります。 うまくいけば、 バンドル URI 機能は、 すべてのニーズを満たすのに十分柔軟です。 そうでない場合は、 バージョン管理メカニズムを通じて機能を拡張できる訳です。

バンドル・サーバーのサーバー側実装を提供するために、 Git プロトコルの他の部分は必要ありません。 これにより、 サーバー管理者は CDN などの静的コンテンツ・ソリューションを使用してバンドル・ファイルを提供できます。

バンドル URI 機能の現在のスコープでは、 すべての URI が HTTP(S) URL であると想定され、 その URL への GET リクエストを使用してコンテンツがローカル・ファイルにダウンロードされます。 サーバーは、 安全なアクセスのために構成された資格情報ヘルパー(configured credential helper)をトリガーする目的で、 これらのリクエストに認証要件(authentication requirement)を含めることができます。 (将来の拡張では、 file:// URI または SSH URI を使用できるようになる予定です。)

サーバーからの 200 OK 応答が得られたとして、 URL の指すコンテンツを調べます。 最初に、 Git はファイルをバージョン 2 以降のバンドル・ファイルと見なしてパースしようとします。 ファイルがバンドルでない場合、 ファイルは Git の構成パーサー(config parser)を使用してプレーン・テキスト・ファイルと見なしてパースし、 その構成ファイルのキーと値のペアは、バンドル URI のリストを記述することが期待されます。 これらのパースの試みがいずれも成功しない場合、 Git は、 バンドル URI が誤ったデータを提供したというエラーをユーザーに報告します。

サーバーによって提供されるその他のデータは、エラーと見なされます。

Git サーバーは、一連の key=value ペアを使用してバンドル URI を広告(advertise)できます。 バンドル URI は、 これらの同一の key=value ペアを含む Git 構成形式のプレーン・テキスト・ファイルを提供することもできます。 どちらの場合も、 これを バンドル・リスト(bundle list) と見なします。 key=value ペアは、 クライアントがダウンロードするバンドルと無視するバンドルを決定するために使用できる、 バンドルに関する情報を指定します。

いくつかのキーは、 リスト自体の属性(property)に焦点を当てています。

以下のキー達には、 利用可能な各バンドルのサーバー指定名である <id> セグメントが含まれます。 <id> には、英数字(alphanumeric)と - 文字のみを含める必要があります。

Git 構成形式(Git config format)を使用したバンドル・リストの例を以下に示します:

この例では、 bundle.mode=all はもちろん、 bundle.<id>.creationToken ヒューリスティックも使用しています。 また、 bundle.<id>.filter オプションを使用して、 バンドルの 2 つの並列セットを提示します。 1 つは完全なクローン用(full clone)で、 もう 1 つはブロブn無し部分クローン用(blobless partial clones)です。

このバンドル・リストは URI https://bundles.example.com/git/git/ で見つかったので、2 つのブロブ無しバンドル(blobless bundles)には以下の完全に展開された URI があると見なします。

ユーザーがクローンしているリポジトリのバンドル URI を知っている場合、 コマンドライン・オプションを使用してその URI を手動で指定できます。 けれども、 Gitホストとしては、 クローン操作中にバンドル URI を広告(advertise)して、 この機能を知らないユーザーを支援したいと思うかもしれません。

この機能に必要なのは、 サーバーが 1 つ以上のバンドル URI を広告(advertise)可能であることだけです。 この広告(advertisement)は、 バンドル URI を検出するために、特別に、新しいプロトコル v2 機能の形式を取ります。

クライアントはオプションとして任意(arbitrary)のバンドル URI を選択するか、または、いくつかの探索的チェック(exploratory checks)によって最高のパフォーマンスを持つ URI を選択できます。 複数の URI を持つことが、 サーバー側のインフラストラクチャを通じて地理的に分散された単一の URI よりも望ましいかどうかを判断するのは、バンドル提供側次第です。

バンドル URI の主な需要はクローンを高速化することです。 Git クライアントは、 以下の流れに従ってバンドル URI と対話します:

注意: クローン中はすべてのバンドルが必要になることが予想されます。 また、 bundle.<uri>.creationToken などのヒューリスティックを使用して、 バンドルを時系列または並列でダウンロードできます。

特定のバンドル URI が bundle.heuristic 値を持つバンドル・リストである場合、 クライアントはその URI を選択したバンドル URI として保存することを選択できます。 その後、クライアントは、 後の git fetch 呼び出し中にその URI に直接移動できます。

クライアントは、 バンドル URI をダウンロードするとき、 コンテンツ全体のダウンロードをお願いする前に、 最初のコンテンツを調査することを選択できます。 これにより、 URI がバンドル・リストかバンドルかを判断するのに十分な情報が得られる場合があります。 バンドルの場合、 クライアントはバンドル・ヘッダーを調べて、 広告(advertise)されたすべての先端(tips)がクライアント・リポジトリに既にあることを確認し、 残りのダウンロードをキャンセルすることができます。

クライアントが新しいデータをフェッチするとき、 origin のリモートから取得する前に、バンドル・サーバーから取得するよう決めておく事ができます。 これはコマンド・ライン・オプションを介して行うこともできますが、 クローン中に指定したような構成値を使用する方が便利な場合があります。

フェッチ操作は、 バンドル・リストからバンドルをダウンロードするのと同じ手順に従います(ただし、 私達は、ここでは並列ダウンロードを使用することを「望んでいません」)。 薄いバンドル(thin bundle)内のすべての前提条件のコミット OID がオブジェクト・データベースに既にある場合、 私達は処理の終了(end)を期待します。

creationToken ヒューリスティックを使用する場合、 それらの作成トークン(creation tokens)が格納されている作成トークン(creation tokens)以下の数値の場合、 クライアントはバンドルのダウンロードを回避できます。 新しいバンドルをフェッチした後、 Git はこのローカル作成トークン(creation token)を更新します。

バンドル提供側(bundle provider)がヒューリスティックを提供しない場合、 クライアント・リポジトリにバンドル先端(bundle tips)が既に存在する場合に、 クライアントは全バンドル・データをダウンロードする前にバンドル・ヘッダーの調査を試みるべきです。

バンドル URI またはその場所で見つかったバンドル・リストに従って情報をダウンロードしているときに、 Git クライアントが予期しないものを発見した場合、 Git はそのデータを無視して、 バンドル URI が指定されていないかのように処理を続行できます。 バンドル URI ではなく、リモート Git サーバーは、最終的に信頼できる情報源です。

以下にエラー状態の例をいくつか示します:

また、以下は無駄だと見なされる状況な事もありますが、エラー状態ではありません:

バンドル URI 機能は、バンドル提供側(bundle provider)がオブジェクト・データを編成するさまざまな方法に柔軟に対応できるように意図的に設計されています。 ただし、 以下で説明する完全な編成モデルを用意しておけば、 提供側(provider)がそのベースから始める事ができるので、役に立つことがあります。

この編成例は、 GVFS キャッシュ・サーバー (このドキュメントの最後のセクションを参照) で使用されるものの単純化されたモデルであり 、Git 以外の追加のソフトウェアを使用していますが、 非常に大きなリポジトリ(very large repositories)のクローンとフェッチを高速化するのに役立ちました。

バンドル提供側(bundle provider)は、 サーバーを複数の地域に展開します。 各サーバーは独自のバンドル・セットを管理します。 サーバーは多数の Git リポジトリを追跡できますが、 バンドル・リストの提供は各々のパターンに基づいています。 たとえば、 https://<domain>/<org>/<repo> でリポジトリをミラーリングする場合、 バンドル・サーバーはそのバンドル・リストを https://<server-url>/<domain>/<org>/<repo> で使用できるようにすることができます。 origin の Git サーバーは、 これらすべてのサーバーを any モードでリストできます:

この「リストのリスト」は静的であり、 バンドル・サーバーが追加または削除された場合にのみ変更されます。

各バンドル・サーバーは、 独自のバンドルの組を管理します。 最初のバンドル・リストには、 単一のバンドルのみが含まれており、 origin サーバーからリポジトリをクローンして受け取ったすべてのオブジェクトが含まれています。 リストは creationToken ヒューリスティックを使用し、 creationToken はサーバーのタイムスタンプに基づいてバンドル用に作成されます。

バンドル・サーバーは、 1 日 1 回など、 定期的にスケジュールされたバンドル・リストの更新を実行します。 このタスクの処理中、 サーバーは origin サーバーから最新のコンテンツをフェッチし、 最新の origin ref から到達可能であるが、 以前に計算されたバンドルには含まれていないオブジェクトを含むバンドルを生成します。 このバンドルは、 creationToken 値が以前の最大 creationToken 値より必ず大きくなるように注意してリストに追加されます。

バンドルリストが大きくなりすぎたとき、 つまり、 バンドルの数が30を超えると、 「N - 30」(N minus 30)より古いバンドル達を1つのバンドルにまとめます。 このバンドルの creationToken は、 まとめられたバンドルの中の最大の creationToken と等しくなります。

以下にバンドル・リストの例を示しますが、日毎のバンドルは2つしかなく、リストは30個にはとうてい足りていません:

origin サーバーで到達不能になったにもかかわらず、 永続的にオブジェクト・データを保存および提供することを避けるために、 このバンドルのマージをより慎重に行うことができます。 古いバンドル達の絶対結合(absolute union)を得る代わりに、 より新しいバンドル達を調べて、 このマージされたバンドルで必要なコミットが全て利用可能であることを確認することでバンドルを作成できます。 これにより、 この期間内に新しいコミット達で使用されていないオブジェクト・データを「期限切れにする」ことができます。 そのデータは、その後のプッシュによって再導入される可能性があります。

このデータ編成は主に2つの事を意図しています。 ひとつ目は、 リポジトリの最初のクローンは、 より近いソースから事前計算(precompute)されたオブジェクト・データをダウンロードすることで高速に行われます。 ふたつ目は、 特に、 クライアントが数日間フェッチしていない場合は、 git fetch コマンドの方が高速ですが、 クライアントが 30 日間フェッチしないと、 バンドル・リストの編成により、 大量のオブジェクト・データが再ダウンロードされます。

頻繁にフェッチするユーザーにとってこの編成をより便利にする方法のひとつは、 より頻繁にバンドルを作成することです。 たとえば、 バンドルを 1 時間ごと(every hour)に作成し、 1 日に 1 回これらの「毎時」(hourly)バンドルを、「日次」(daily)バンドルにマージすることができます。 日次(daily)バンドルは、 30 日後に「最古のバンドル」(the oldest bundle)にマージされます。

このリポジトリのクライアントがブロブ無し部分クローン(blobless partial clones)を使用することを期待している場合は、 このバンドル戦略を blob:none フィルターで繰り返すことをお勧めします。 この ブロブ無しバンドル(blobless bundle)のリストは、 完全なバンドル(full bundle)と同一のリストに入りますが、 bundle.<id>.filter キーを使用することで 2 つのグループに分離します。 非常に大きなリポジトリの場合、 バンドル提供側(bundle provider)はブロブ無しバンドル(blobless bundle)のみを提供したい場合があります。

この設計ドキュメントは、 いくつかのパッチ・シリーズの過程で言及されたすべてのクライアント機能を実装することを目標として、 野心的なドキュメントとして単独で提案されています。 提案に値する見込みのある機能(概要)は以下のとおり:

これらの機能が見直されるにつれて、 この計画は更新される可能性があります。 また、 この機能が成熟し、 実際のシナリオで使用されるようになるにつれて、 新しい設計が発見され、 実装されることも期待しています。

Git プロトコルには、 Git サーバーがクライアントのリクエストを処理するときに、 パックファイル応答(response)と共に URL の組をリストできる機能が既に備わっています。 クライアントは、 レスポンスを受け取った後、 レスポンスを完全に理解するために、 それらの URL の場所にあるパックファイルをダウンロードする必要があります。

このメカニズムは(JGit で実装された) Gerrit サーバーによって使用され、 クローン時の、 CPU 負荷の削減とユーザー・パフォーマンスの向上に効果的です。

このメカニズムの主な欠点は、 origin サーバーがこれらのパックファイルの内容を「正確に」知る必要があり、 サーバーが応答した後しばらくの間、 ユーザーがパックファイルを利用できる必要があることです。 この、 origin と パックファイル・データの間の結合の管理は困難です。

さらに、 この実装はフェッチで機能させるのが非常に困難です。

GVFS プロトコル [2] は、Git の部分(partial)クローンが作成される以前に、 Git プロジェクトとは別に設計された一連の HTTP 通信端点(endponts)です。 このプロトコルの特徴の 1 つは、 中央サーバーに過負荷をかけずに Git データを転送するために、 ビルド・マシンまたは開発者オフィスと同じ場所に配置できる「キャッシュ・サーバー」のアイデアです。

VFS for Git で有名な通信端点(endpoint)は、 オンデマンドでオブジェクトをダウンロードできる GET /gvfs/objects/{oid} 通信端点(endpoint)です。 これは、 当該製品のファイル・システム仮想化の重要な部分です。

けれども、 GET /gvfs/prefetch?lastPackTimestamp=<t> 通信端点(endpoint)は必要性が薄いです。 オプションのタイムスタンプを指定すると、 キャッシュ・サーバーは、 それらの時間間隔で導入されたコミットとツリーを含む、事前計算されたパックファイルのリストで応答します。

キャッシュ・サーバーは、 以下の戦略を使用してこれらの「プリフェッチ」パックファイルを計算します: The cache server computes these "prefetch" packfiles using the following strategy:

ユーザーがキャッシュ・サーバーを使用して、リポジトリ対して gvfs clone または scalar clone を実行すると、 クライアントはすべてのプリフェッチ・パック・ファイルを要求します。これは、コミットとツリーのみをダウンロードする、最大で「24 + 30 + 1」の数のパックファイルです。 次に、 クライアントは origin サーバーに参照を要求し、その先端参照(tip reference)のチェックアウトを試みます。 (コミットがまだプリフェッチ・パック・ファイルに含まれていない場合に備えて、 特定のコミットから到達可能なすべてのツリーを取得するのに役立つ追加の通信端点(endpoint)があります。)

git fetch 中、 フックは、 以前にダウンロードされたプリフェッチ・パック・ファイルからの最新のタイムスタンプを使用して、 プリフェッチ通信端点(endnpoint)を要求します。 タイムスタンプが新しいパック・ファイルのリストのみがダウンロードされます。 ほとんどのユーザーは 1 時間ごとにフェッチするため、 1 時間ごとに最大 1 つのプリフェッチ・パックを取得します。 マシンの電源がオフになっているか、 30 日以上フェッチされていないユーザーは、 すべてのプリフェッチ・パック・ファイルを再ダウンロードする可能性がありますが、これはまれな事です。

クライアントは常に refs 広告(advertisement)のために origin サーバーに接続するため、 refs はプリフェッチされたパック・データよりも「先に」なることが多いことに注意することが重要です。 不足しているオブジェクトは、 git checkout や git log などのコマンドで必要になったときに、 GET gvfs/objects/{oid} リクエストを使用してオンデマンドでダウンロードされます。 一部の Git 最適化は、これらのオンデマンド・ダウンロードに積極的になりすぎる原因となるチェックを無効にします。

[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ An earlier RFC for a bundle URI feature.

[2] https://github.com/microsoft/VFSForGit/blob/master/Protocol.md The GVFS Protocol