Der Bundle-URI-Standard zielt darauf ab, flexibel genug zu sein, um mehrere Workloads zu erfüllen. Der Bundle-Provider und der Git-Client haben mehrere Wahlmöglichkeiten, wie sie Bundle-URIs erstellen und konsumieren.

Jedes Repository ist anders und jeder Git-Server hat unterschiedliche Bedürfnisse. Hoffentlich ist die Bundle-URI-Funktion flexibel genug, um alle Bedürfnisse zu erfüllen. Wenn nicht, kann die Funktion über ihren Versionsmechanismus erweitert werden.

Um eine serverseitige Implementierung von Bundle-Servern bereitzustellen, sind keine anderen Teile des Git-Protokolls erforderlich. Dies ermöglicht es Server-Betreuern, statische Inhaltslösungen wie CDNs zu verwenden, um die Bundle-Dateien zu bedienen.

Im aktuellen Umfang der Bundle-URI-Funktion werden alle URIs als HTTP(S)-URLs erwartet, von denen Inhalte mit einer GET-Anfrage an diese URL in eine lokale Datei heruntergeladen werden. Der Server könnte Authentifizierungsanforderungen für diese Anfragen enthalten, um den konfigurierten Anmeldeinformationshelfer für sicheren Zugriff auszulösen. (Zukünftige Erweiterungen könnten "file://" URIs oder SSH-URIs verwenden.)

Unter der Annahme einer 200 OK-Antwort des Servers wird der Inhalt der URL inspiziert. Zuerst versucht Git, die Datei als Bundle-Datei der Version 2 oder höher zu parsen. Wenn die Datei kein Bundle ist, wird die Datei als einfache Textdatei mithilfe des Git-Konfigurationsparsers geparst. Es wird erwartet, dass die Schlüssel-Wert-Paare in dieser Konfigurationsdatei eine Liste von Bundle-URIs beschreiben. Wenn keiner dieser Parse-Versuche erfolgreich ist, meldet Git dem Benutzer einen Fehler, dass die angegebene Bundle-URI fehlerhafte Daten enthält.

Alle anderen vom Server bereitgestellten Daten werden als fehlerhaft betrachtet.

Der Git-Server kann Bundle-URIs mithilfe eines Satzes von key=value-Paaren bewerben. Eine Bundle-URI kann auch eine einfache Textdatei im Git-Konfigurationsformat enthalten, die dieselben key=value-Paare enthält. In beiden Fällen betrachten wir dies als eine *Bundle-Liste*. Die Paare geben Informationen über die Bundles an, die der Client verwenden kann, um zu entscheiden, welche Bundles heruntergeladen und welche ignoriert werden sollen.

Einige Schlüssel konzentrieren sich auf Eigenschaften der Liste selbst.

Die restlichen Schlüssel enthalten ein <id>-Segment, das ein vom Server designierter Name für jedes verfügbare Bundle ist. Das <id> muss nur alphanumerische Zeichen und - enthalten.

Hier ist eine Beispiel-Bundle-Liste im Git-Konfigurationsformat

Dieses Beispiel verwendet bundle.mode=all sowie die Heuristik bundle.<id>.creationToken. Es verwendet auch die Optionen bundle.<id>.filter, um zwei parallele Bundle-Sätze bereitzustellen: einen für vollständige Klone und einen für blobless partielle Klone.

Angenommen, diese Bundle-Liste wurde unter der URI https://bundles.example.com/git/git/ gefunden, dann haben die beiden blobless Bundles die folgenden vollständig expandierten URIs

Wenn ein Benutzer eine Bundle-URI für das zu klonende Repository kennt, kann er diese URI manuell über eine Kommandozeilenoption angeben. Ein Git-Host möchte jedoch möglicherweise Bundle-URIs während des Klonvorgangs bewerben, um Benutzern zu helfen, die die Funktion nicht kennen.

Das Einzige, was für diese Funktion erforderlich ist, ist, dass der Server eine oder mehrere Bundle-URIs bewerben kann. Diese Werbung erfolgt in Form einer neuen Protokoll v2-Funktion, die speziell für die Erkennung von Bundle-URIs vorgesehen ist.

Der Client könnte eine beliebige Bundle-URI als Option wählen *oder* die URI mit der besten Leistung durch einige explorative Prüfungen auswählen. Es liegt am Bundle-Provider zu entscheiden, ob mehrere URIs besser sind als eine einzelne URI, die über serverseitige Infrastruktur geodistributed ist.

Der Hauptbedarf für Bundle-URIs ist die Beschleunigung von Klonvorgängen. Der Git-Client interagiert gemäß dem folgenden Ablauf mit Bundle-URIs

Beachten Sie, dass während eines Klons erwartet wird, dass alle Bundles benötigt werden, und Heuristiken wie bundle.<uri>.creationToken verwendet werden können, um Bundles chronologisch oder parallel herunterzuladen.

Wenn eine gegebene Bundle-URI eine Bundle-Liste mit einem bundle.heuristic-Wert ist, dann kann der Client diese URI als seine gewählte Bundle-URI speichern. Der Client kann dann während späterer git fetch-Aufrufe direkt auf diese URI zugreifen.

Beim Herunterladen von Bundle-URIs kann der Client den Anfangsinhalt inspizieren, bevor er sich zum Herunterladen des gesamten Inhalts verpflichtet. Dies kann genügend Informationen liefern, um festzustellen, ob die URI eine Bundle-Liste oder ein Bundle ist. Im Falle eines Bundles kann der Client den Bundle-Header inspizieren, um festzustellen, dass alle beworbenen Spitzen bereits im Client-Repository vorhanden sind, und den restlichen Download abbrechen.

Wenn der Client neue Daten abruft, kann er entscheiden, zuerst von Bundle-Servern abzurufen, bevor er vom Ursprungsserver abruft. Dies kann über eine Kommandozeilenoption erfolgen, ist aber wahrscheinlich nützlicher über einen Konfigurationswert, wie den während des Klons angegebenen.

Der Fetch-Vorgang folgt demselben Verfahren, um Bundles aus einer Bundle-Liste herunterzuladen (obwohl wir hier *keine* parallelen Downloads wünschen). Wir erwarten, dass der Prozess endet, wenn alle erforderlichen Commit-OIDs in einem Thin-Bundle bereits in der Objektdatenbank vorhanden sind.

Wenn die creationToken-Heuristik verwendet wird, kann der Client das Herunterladen von Bundles vermeiden, wenn ihre Erstellungstoken nicht größer als das gespeicherte Erstellungstoken sind. Nach dem Abrufen neuer Bundles aktualisiert Git dieses lokale Erstellungstoken.

Wenn der Bundle-Provider keine Heuristik bereitstellt, dann sollte der Client versuchen, die Bundle-Header zu inspizieren, bevor er die vollständigen Bundle-Daten herunterlädt, falls die Bundle-Spitzen bereits im Client-Repository vorhanden sind.

Wenn der Git-Client beim Herunterladen von Informationen gemäß einer Bundle-URI oder der dort gefundenen Bundle-Liste unerwartetes entdeckt, kann Git diese Daten ignorieren und so fortfahren, als wäre ihm keine Bundle-URI übergeben worden. Der entfernte Git-Server ist die ultimative Quelle der Wahrheit, nicht die Bundle-URI.

Hier sind einige Beispiel-Fehlerfälle

Es gibt auch Situationen, die als verschwenderisch angesehen werden können, aber keine Fehlerbedingungen sind

Die Bundle-URI-Funktion ist absichtlich flexibel gestaltet, um verschiedene Arten der Organisation von Objektdaten durch einen Bundle-Provider zu ermöglichen. Es kann jedoch hilfreich sein, ein vollständiges Organisationsmodell hier zu beschreiben, damit Provider von dieser Basis ausgehen können.

Dieses Beispiel-Organisationsmodell ist eine vereinfachte Version dessen, was von den GVFS-Cache-Servern verwendet wird (siehe Abschnitt am Ende dieses Dokuments), die sich bei der Beschleunigung von Klon- und Fetch-Vorgängen für sehr große Repositories als vorteilhaft erwiesen haben, wenn auch unter Verwendung zusätzlicher Software außerhalb von Git.

Der Bundle-Provider stellt Server an mehreren geografischen Standorten bereit. Jeder Server verwaltet seine eigene Bundle-Menge. Der Server kann eine Reihe von Git-Repositories verwalten, stellt aber für jedes eine Bundle-Liste basierend auf einem Muster bereit. Wenn beispielsweise ein Repository unter https://<domain>/<org>/<repo> gespiegelt wird, könnte der Bundle-Server seine Bundle-Liste unter https://<server-url>/<domain>/<org>/<repo> verfügbar haben. Der Origin-Git-Server kann all diese Server unter dem "any"-Modus auflisten

Diese "Liste von Listen" ist statisch und ändert sich nur, wenn ein Bundle-Server hinzugefügt oder entfernt wird.

Jeder Bundle-Server verwaltet seine eigene Menge an Bundles. Die anfängliche Bundle-Liste enthält nur ein einzelnes Bundle, das alle Objekte enthält, die durch das Klonen des Repositorys vom Origin-Server erhalten wurden. Die Liste verwendet die Heuristik creationToken, und ein creationToken wird für das Bundle basierend auf dem Zeitstempel des Servers erstellt.

Der Bundle-Server führt regelmäßig geplante Aktualisierungen für die Bundle-Liste durch, z. B. einmal täglich. Während dieser Aufgabe ruft der Server die neuesten Inhalte vom Origin-Server ab und generiert ein Bundle, das die von den neuesten Origin-Refs erreichbaren, aber in einem zuvor berechneten Bundle nicht enthaltenen Objekte enthält. Dieses Bundle wird der Liste hinzugefügt, wobei darauf geachtet wird, dass das creationToken strikt größer als das vorherige maximale creationToken ist.

Wenn die Bundle-Liste zu groß wird, z. B. mehr als 30 Bundles, dann werden die ältesten "N minus 30" Bundles zu einem einzigen Bundle zusammengefasst. Das creationToken dieses Bundles entspricht dem maximalen creationToken der zusammengeführten Bundles.

Eine Beispiel-Bundle-Liste ist hier aufgeführt, obwohl sie nur zwei tägliche Bundles und keine vollständige Liste von 30 enthält.

Um die Speicherung und Bereitstellung von Objektdaten in alle Ewigkeit zu vermeiden, obwohl sie im Origin-Server nicht mehr erreichbar sind, kann diese Bundle-Zusammenführung sorgfältiger sein. Anstatt eine absolute Vereinigung der alten Bundles zu nehmen, kann das Bundle erstellt werden, indem die neueren Bundles betrachtet und sichergestellt wird, dass ihre notwendigen Commits alle in diesem zusammengeführten Bundle (oder in einem anderen der neueren Bundles) verfügbar sind. Dies ermöglicht die "Ablaufzeit" von Objektdaten, die in diesem Zeitraum nicht von neuen Commits verwendet werden. Diese Daten könnten durch einen späteren Push wieder eingeführt werden.

Die Absicht dieser Datenorganisation verfolgt zwei Hauptziele. Erstens werden anfängliche Klonvorgänge des Repositorys schneller, indem vorab berechnete Objektdaten von einer näheren Quelle heruntergeladen werden. Zweitens können git fetch-Befehle schneller sein, insbesondere wenn der Client seit einigen Tagen nicht mehr abgerufen hat. Wenn ein Client jedoch 30 Tage lang nicht abruft, würde die Bundle-Listenorganisation eine große Menge an Objektdaten neu herunterladen.

Eine Möglichkeit, diese Organisation für Benutzer, die häufig abrufen, nützlicher zu machen, ist eine häufigere Bundle-Erstellung. Zum Beispiel könnten Bundles jede Stunde erstellt und dann einmal täglich diese "stündlichen" Bundles zu einem "täglichen" Bundle zusammengefasst werden. Die täglichen Bundles werden nach 30 Tagen in das älteste Bundle zusammengefasst.

Es wird empfohlen, diese Bundle-Strategie mit dem Filter blob:none zu wiederholen, wenn Clients dieses Repositorys erwarten, blobless partielle Klone zu verwenden. Diese Liste von blobless Bundles verbleibt in derselben Liste wie die vollständigen Bundles, verwendet aber den Schlüssel bundle.<id>.filter, um die beiden Gruppen zu trennen. Für sehr große Repositories möchte der Bundle-Provider möglicherweise *nur* blobless Bundles bereitstellen.

Dieses Design-Dokument wird eigenständig als aspiratives Dokument eingereicht, mit dem Ziel, alle erwähnten Client-Funktionen im Laufe mehrerer Patchserien zu implementieren. Hier ist ein möglicher Überblick für die Einreichung dieser Funktionen

Da diese Funktionen überprüft werden, kann dieser Plan aktualisiert werden. Wir erwarten auch, dass neue Designs entdeckt und implementiert werden, wenn sich diese Funktion weiterentwickelt und in realen Szenarien eingesetzt wird.

Das Git-Protokoll verfügt bereits über eine Funktion, bei der der Git-Server eine Reihe von URLs zusammen mit der Packfile-Antwort auflisten kann, wenn eine Client-Anfrage bedient wird. Der Client wird dann erwartet, die Packfiles an diesen Orten herunterzuladen, um ein vollständiges Verständnis der Antwort zu erhalten.

Dieser Mechanismus wird vom Gerrit-Server (implementiert mit JGit) verwendet und war wirksam bei der Reduzierung der CPU-Last und der Verbesserung der Benutzerleistung für Klone.

Ein wesentlicher Nachteil dieses Mechanismus ist, dass der Origin-Server *genau* wissen muss, was in diesen Packfiles enthalten ist, und die Packfiles müssen dem Benutzer für einige Zeit nach der Antwort des Servers zur Verfügung stehen. Diese Kopplung zwischen dem Origin und den Packfile-Daten ist schwer zu verwalten.

Darüber hinaus ist diese Implementierung extrem schwierig mit Fetches zum Laufen zu bringen.

Das GVFS-Protokoll [2] ist eine Reihe von HTTP-Endpunkten, die unabhängig vom Git-Projekt entwickelt wurden, bevor Git's partielles Klonen erstellt wurde. Eine Funktion dieses Protokolls ist die Idee eines "Cache-Servers", der mit Build-Maschinen oder Entwicklerbüros ko-lokalisiert sein kann, um Git-Daten zu übertragen, ohne den zentralen Server zu überlasten.

Der Endpunkt, für den VFS for Git berühmt ist, ist der Endpunkt GET /gvfs/objects/{oid}, der das Herunterladen eines Objekts bei Bedarf ermöglicht. Dies ist ein kritischer Teil der Dateisystemvirtualisierung dieses Produkts.

Eine subtilere Anforderung ist jedoch der Endpunkt GET /gvfs/prefetch?lastPackTimestamp=<t>. Unter Angabe eines optionalen Zeitstempels antwortet der Cache-Server mit einer Liste von vorab berechneten Packfiles, die die Commits und Trees enthalten, die in diesen Zeitintervallen eingeführt wurden.

Der Cache-Server berechnet diese "Prefetch"-Packfiles nach folgender Strategie

Wenn ein Benutzer gvfs clone oder scalar clone gegen ein Repo mit Cache-Servern ausführt, fordert der Client alle Prefetch-Packfiles an, was höchstens 24 + 30 + 1 Packfiles sind, die nur Commits und Trees herunterladen. Der Client folgt dann mit einer Anfrage an den Origin-Server für die Referenzen und versucht, diese Tip-Referenz auszuchecken. (Es gibt einen zusätzlichen Endpunkt, der hilft, alle erreichbaren Trees von einem gegebenen Commit zu erhalten, falls dieser Commit noch nicht in einem Prefetch-Packfile enthalten war.)

Während eines git fetch fordert ein Hook den Prefetch-Endpunkt unter Verwendung des aktuellsten Zeitstempels eines zuvor heruntergeladenen Prefetch-Packfiles an. Nur die Liste der Packfiles mit späteren Zeitstempeln wird heruntergeladen. Die meisten Benutzer rufen stündlich ab und erhalten daher höchstens ein stündliches Prefetch-Pack. Benutzer, deren Maschinen ausgeschaltet waren oder die aus anderen Gründen seit über 30 Tagen nicht abgerufen haben, könnten alle Prefetch-Packfiles neu herunterladen. Dies ist selten.

Es ist wichtig zu beachten, dass die Clients immer den Origin-Server für die Refs-Werbung kontaktieren, sodass die Refs häufig "vor" den vorgeabgerufenen Pack-Daten liegen. Die fehlenden Objekte werden bei Bedarf über die GET gvfs/objects/{oid}-Anfragen heruntergeladen, wenn sie von einem Befehl wie git checkout oder git log benötigt werden. Einige Git-Optimierungen deaktivieren Prüfungen, die dazu führen würden, dass diese On-Demand-Downloads zu aggressiv wären.

[1] https://lore.kernel.org/git/RFC-cover-00.13-0000000000-20210805T150534Z-avarab@gmail.com/ Ein früherer RFC für eine Bundle-URI-Funktion.

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