go getter
1.7.6
go-getter ist eine Bibliothek für Go (Golang) zum Herunterladen von Dateien oder Verzeichnissen aus verschiedenen Quellen unter Verwendung einer URL als primärer Eingabeform.
Die Stärke dieser Bibliothek liegt darin, dass sie flexibel ist und Downloads aus verschiedenen Quellen (Dateipfade, Git, HTTP, Mercurial usw.) mit einer einzigen Zeichenfolge als Eingabe ermöglicht. Dadurch entfällt für den Implementierer die Notwendigkeit, zu wissen, wie er Daten aus verschiedenen Quellen herunterladen kann.
Das Konzept eines Detektors wandelt ungültige URLs automatisch in richtige URLs um. Beispiel: „github.com/hashicorp/go-getter“ würde zu einer Git-URL werden. Oder „./foo“ würde sich in eine Datei-URL verwandeln. Diese sind erweiterbar.
Diese Bibliothek wird von Terraform zum Herunterladen von Modulen und von Nomad zum Herunterladen von Binärdateien verwendet.
Die Paketdokumentation finden Sie auf GoDoc.
Die Installation kann mit einem normalen go get erfolgen:
$ go get github.com/hashicorp/go-getter
go-getter verfügt auch über einen Befehl, mit dem Sie URL-Strings testen können:
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
Der Befehl ist nützlich zum Überprüfen von URL-Strukturen.
Das Abrufen von Ressourcen von vom Benutzer bereitgestellten URLs ist ein grundsätzlich gefährlicher Vorgang und kann Ihre Anwendung anfällig für serverseitige Anforderungsfälschung, Path Traversal, Denial of Service oder andere Sicherheitslücken machen.
go-getter enthält Abhilfemaßnahmen für einige dieser Sicherheitsprobleme, sollte jedoch in sicherheitskritischen Kontexten dennoch mit Vorsicht verwendet werden. Sehen Sie sich die verfügbaren Sicherheitsoptionen an, die konfiguriert werden können, um einige dieser Risiken zu mindern.
go-getter gibt möglicherweise Werte zurück, die vom Aufrufer bereitgestellte Abfrageparameter enthalten, die vertrauliche Daten enthalten können. Der Kontext darüber, welche Parameter sensibel sind und welche nicht, ist nur dem Aufrufer des Go-Getters bekannt und für jeden Anwendungsfall spezifisch. Wir empfehlen dem Aufrufer sicherzustellen, dass die Rückgabewerte des Go-Getters (z. B. Fehlermeldungen) ordnungsgemäß verarbeitet und bereinigt werden, um sicherzustellen, dass vertrauliche Daten nicht in Protokollen gespeichert werden.
go-getter verwendet eine einzelne Zeichenfolgen-URL als Eingabe zum Herunterladen verschiedener Protokolle. go-getter hat verschiedene „Tricks“ mit dieser URL, um bestimmte Dinge zu tun. In diesem Abschnitt wird das URL-Format dokumentiert.
Protokolle werden zum Herunterladen von Dateien/Verzeichnissen mithilfe eines bestimmten Mechanismus verwendet. Beispielprotokolle sind Git und HTTP.
Detektoren werden verwendet, um eine gültige oder ungültige URL in eine andere URL umzuwandeln, wenn sie einem bestimmten Muster entspricht. Beispiel: „github.com/user/repo“ wird automatisch in eine vollständig gültige Git-URL umgewandelt. Dadurch ist Go-Getter sehr benutzerfreundlich.
go-getter unterstützt ab Werk die folgenden Protokolle. Zusätzliche Protokolle können zur Laufzeit durch Implementierung der Getter -Schnittstelle erweitert werden.
Lokale Dateien
Git
Mercurial
HTTP
Amazon S3
Google GCP
Zusätzlich zu den oben genannten Protokollen verfügt Go-Getter über sogenannte „Detektoren“. Diese nehmen eine URL und versuchen, automatisch das beste Protokoll dafür auszuwählen, was möglicherweise sogar eine Änderung des Protokolls erfordert. Die folgende Erkennung ist standardmäßig integriert:
Dateipfade wie „./foo“ werden automatisch in absolute Datei-URLs geändert.
GitHub-URLs wie „github.com/mitchellh/vagrant“ werden automatisch über HTTP in das Git-Protokoll geändert.
GitLab-URLs wie „gitlab.com/inkscape/inkscape“ werden automatisch über HTTP in das Git-Protokoll geändert.
BitBucket-URLs wie „bitbucket.org/mitchellh/vagrant“ werden mithilfe der BitBucket-API automatisch in ein Git- oder Mercurial-Protokoll geändert.
In manchen Fällen ist das zu verwendende Protokoll je nach Quell-URL nicht eindeutig. Beispielsweise könnte „http://github.com/mitchellh/vagrant.git“ auf eine HTTP-URL oder eine Git-URL verweisen. Um diese URL eindeutig zu machen, wird eine erzwungene Protokollsyntax verwendet.
Ein erzwungenes Protokoll kann durchgeführt werden, indem der URL das Protokoll gefolgt von Doppelpunkten vorangestellt wird. Beispiel: git::http://github.com/mitchellh/vagrant.git würde die angegebene HTTP-URL mithilfe des Git-Protokolls herunterladen.
Erzwungene Protokolle setzen auch alle Detektoren außer Kraft.
Wenn kein erzwungenes Protokoll vorhanden ist, können Detektoren auf der URL ausgeführt werden, wodurch das Protokoll trotzdem umgewandelt wird. Im obigen Beispiel hätte das Git-Protokoll so oder so verwendet, da der Git-Detektor erkannt hätte, dass es sich um eine GitHub-URL handelte.
Jedes Protokoll kann protokollspezifische Optionen zur Konfiguration dieses Protokolls unterstützen. Das git -Protokoll unterstützt beispielsweise die Angabe eines ref Abfrageparameters, der ihm mitteilt, welcher Ref für dieses Git-Repository ausgecheckt werden soll.
Die Optionen werden als Abfrageparameter in der URL (oder URL-ähnlichen Zeichenfolge) angegeben, die dem Go-Getter übergeben wird. Unter Verwendung des obigen Git-Beispiels ist die folgende URL eine gültige Eingabe für den Macher:
github.com/hashicorp/go-getter?ref=abcd1234
Die protokollspezifischen Optionen sind unterhalb des Abschnitts zum URL-Format dokumentiert. Da sie jedoch Teil der URL sind, weisen wir Sie hier darauf hin, damit Sie wissen, dass sie vorhanden sind.
Wenn Sie nur ein bestimmtes Unterverzeichnis aus einem heruntergeladenen Verzeichnis herunterladen möchten, können Sie nach einem doppelten Schrägstrich // ein Unterverzeichnis angeben. go-getter lädt zunächst die vor dem doppelten Schrägstrich angegebene URL herunter (als ob Sie keinen doppelten Schrägstrich angegeben hätten), kopiert dann aber den Pfad nach dem doppelten Schrägstrich in das Zielverzeichnis.
Wenn Sie beispielsweise dieses GitHub-Repository herunterladen, aber nur das testdata Verzeichnis herunterladen möchten, können Sie Folgendes tun:
https://github.com/hashicorp/go-getter.git//testdata
Wenn Sie dies in das Verzeichnis /tmp herunterladen würden, wäre die Datei /tmp/archive.gz vorhanden. Beachten Sie, dass sich diese Datei im Verzeichnis testdata in diesem Repository befindet. Da wir jedoch ein Unterverzeichnis angegeben haben, hat go-getter automatisch nur den Inhalt dieses Verzeichnisses kopiert.
Unterverzeichnispfade können auch Dateisystem-Glob-Muster verwenden. Der Pfad muss mit genau einem Eintrag übereinstimmen, sonst gibt der Macher einen Fehler zurück. Dies ist nützlich, wenn Sie den genauen Verzeichnisnamen nicht kennen, dieser jedoch einer vorhersehbaren Namensstruktur folgt.
Beispielsweise würde auch die folgende URL funktionieren:
https://github.com/hashicorp/go-getter.git//test-*
Beim Herunterladen von Dateien aller Protokolle kann go-getter automatisch eine Prüfsumme für Sie überprüfen. Beachten Sie, dass die Prüfsummenbildung nur beim Herunterladen von Dateien und nicht bei Verzeichnissen funktioniert, die Prüfsummenbildung jedoch für jedes Protokoll funktioniert.
Um eine Prüfsumme für eine Datei zu erstellen, hängen Sie einen checksum Abfrageparameter an die URL an. go-getter analysiert diesen Abfrageparameter automatisch und verwendet ihn zur Überprüfung der Prüfsumme. Der Parameterwert kann das Format type:value oder nur value haben, wobei type „md5“, „sha1“, „sha256“, „sha512“ oder „file“ ist. Der „Wert“ sollte der tatsächliche Prüfsummenwert oder die Download-URL für „Datei“ sein. Wenn type Typteil weggelassen wird, wird der Typ anhand der Länge der Prüfsummenzeichenfolge erraten. Beispiele:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
Bei der Prüfsummenbildung aus einer Datei – z. B.: mit checksum=file:url – erhält go-getter die in der URL nach file: verlinkte Datei unter Verwendung derselben Konfiguration. Beispielsweise lädt der Go-Getter in file:http://releases.ubuntu.com/cosmic/MD5SUMS mithilfe des http-Protokolls eine Prüfsummendatei unter der oben genannten URL herunter. Alle von go-getter unterstützten Protokolle können verwendet werden. Die Prüfsummendatei wird in eine temporäre Datei heruntergeladen und dann analysiert. Das Ziel der temporären Datei kann durch Festlegen systemspezifischer Umgebungsvariablen geändert werden: TMPDIR für Unix; TMP , TEMP oder USERPROFILE unter Windows. Weitere Informationen zur temporären Verzeichnisauswahl finden Sie im godoc von os.TempDir. Es wird erwartet, dass der Inhalt der Dateien im BSD- oder GNU-Stil ist. Sobald Go-Getter mit der Prüfsummendatei fertig ist; es wird gelöscht.
Der Prüfsummen-Abfrageparameter wird niemals an die Backend-Protokollimplementierung gesendet. Es wird auf einer höheren Ebene vom Draufgänger selbst genutzt.
Wenn die Zieldatei vorhanden ist und die Prüfsummen übereinstimmen: Der Download wird übersprungen.
go-getter dearchiviert Dateien automatisch in einer Datei oder einem Verzeichnis, basierend auf der Erweiterung der angeforderten Datei (über jedes Protokoll). Dies funktioniert sowohl für Datei- als auch für Verzeichnis-Downloads.
go-getter sucht nach einem archive , um das Format des Archivs anzugeben. Wenn dies nicht angegeben ist, verwendet go-getter die Erweiterung des Pfads, um zu sehen, ob er archiviert erscheint. Die Dearchivierung kann explizit deaktiviert werden, indem der archive auf false gesetzt wird.
Folgende Archivformate werden unterstützt:
tar.gz und tgz
tar.bz2 und tbz2
tar.xz und txz
zip
gz
bz2
xz
Nachfolgend sehen Sie beispielsweise eine Beispiel-URL:
./foo.zip
Dies wird automatisch als ZIP-Datei erkannt und extrahiert. Sie können den Archivtyp auch explizit angeben:
./some/other/path?archive=zip
Und schließlich können Sie die Archivierung vollständig deaktivieren:
./some/path?archive=false
Sie können die Entarchivierung mit den anderen Funktionen von go-getter wie der Prüfsummenbildung kombinieren. Der spezielle archive wird aus der URL entfernt, bevor zum endgültigen Protokoll-Downloader gewechselt wird.
In diesem Abschnitt werden die protokollspezifischen Optionen dokumentiert, die für go-getter angegeben werden können. Diese Optionen sollten als normale Abfrageparameter an die Eingabe angehängt werden (eine Ausnahme bilden jedoch HTTP-Header). Abhängig von der Verwendung von Go-Getter bieten Anwendungen möglicherweise alternative Möglichkeiten zur Eingabe von Optionen. Nomad bietet beispielsweise einen netten Optionsblock zum Angeben von Optionen statt in der URL.
Die folgenden Optionen stehen für alle Protokolle zur Verfügung:
archive – Das Archivformat, das zum Dearchivieren dieser Datei verwendet werden soll, oder „“ (leere Zeichenfolge), um das Dearchivieren zu deaktivieren. Weitere Einzelheiten finden Sie oben im vollständigen Abschnitt zur Archivunterstützung.
checksum – Prüfsumme zur Überprüfung der heruntergeladenen Datei oder des heruntergeladenen Archivs. Das Format und weitere Details finden Sie oben im gesamten Abschnitt zur Prüfsummenbildung.
filename – Ermöglicht im Datei-Download-Modus die Angabe des Namens der heruntergeladenen Datei auf der Festplatte. Hat im Verzeichnismodus keine Auswirkung.
file )Keiner
git ) ref – Der Git-Referenz zum Auschecken. Dies ist eine Referenz, sodass sie auf einen Commit-SHA, einen Filialnamen usw. verweisen kann. Wenn es sich um eine benannte Referenz wie z. B. einen Filialnamen handelt, aktualisiert Go-Getter sie bei jedem Abruf auf den neuesten Stand.
sshkey – Ein privater SSH-Schlüssel zur Verwendung beim Klonen. Der bereitgestellte Schlüssel muss eine Base64-codierte Zeichenfolge sein. Um beispielsweise einen geeigneten sshkey aus einer privaten Schlüsseldatei auf der Festplatte zu generieren, würden Sie base64 -w0 <file> ausführen.
Hinweis : Zur Nutzung dieser Funktion ist Git 2.3+ erforderlich.
depth – Die Tiefe des Git-Klons. Die angegebene Zahl gibt die letzten n Revisionen an, die aus dem Repository geklont werden sollen.
Der git Getter akzeptiert sowohl SSH-Adressen im URL-Stil wie git::ssh://[email protected]/foo/bar als auch Adressen im „scp-Stil“ wie git::[email protected]/foo/bar . Im letzteren Fall ist das Weglassen des Präfixes git:: force zulässig, wenn das Präfix des Benutzernamens genau git@ lautet.
Die „scp-style“-Adressen können nicht in Verbindung mit dem Schemapräfix ssh:// verwendet werden, da in diesem Fall der Doppelpunkt dazu verwendet wird, eine optionale Portnummer für die Verbindung zu markieren, und nicht, um den Pfad vom Host abzugrenzen.
hg ) rev – Die Mercurial-Überarbeitung des Checkouts.
http ) Um die HTTP-Basisauthentifizierung mit Go-Getter zu verwenden, stellen Sie einfach username:password@ dem Hostnamen in der URL voran, z. B. https://Aladdin:[email protected]/index.html . Alle Sonderzeichen, einschließlich Benutzername und Passwort, müssen URL-codiert sein.
Optionale Anforderungsheader können hinzugefügt werden, indem sie in einem benutzerdefinierten HttpGetter bereitgestellt werden ( nicht als Abfrageparameter wie die meisten anderen Optionen). Diese Header werden bei jeder Anfrage des betreffenden Getters gesendet.
s3 )S3 akzeptiert verschiedene Zugriffskonfigurationen in der URL. Beachten Sie, dass diese auch aus Standard-AWS-Umgebungsvariablen gelesen werden, sofern diese festgelegt sind. S3-kompatible Server wie Minio werden ebenfalls unterstützt. Wenn die Abfrageparameter vorhanden sind, haben diese Vorrang.
aws_access_key_id – AWS-Zugriffsschlüssel.
aws_access_key_secret – AWS-Zugriffsschlüsselgeheimnis.
aws_access_token – AWS-Zugriffstoken, falls dieses verwendet wird.
aws_profile – Verwenden Sie dieses Profil aus der lokalen ~/.aws/config. Hat Vorrang vor den anderen drei.
Wenn Sie go-getter verwenden und ein EC2-IAM-Instanzprofil verwenden möchten, um die Verwendung von Anmeldeinformationen zu vermeiden, dann lassen Sie diese einfach weg und das Profil, sofern verfügbar, wird automatisch verwendet.
Wenn Sie go-gitter für die Minio-Unterstützung verwenden, müssen Sie Folgendes berücksichtigen:
aws_access_key_id (erforderlich) – Minio-Zugriffsschlüssel.
aws_access_key_secret (erforderlich) – Geheimnis des Minio-Zugriffsschlüssels.
region (optional – Standardwert ist us-east-1) – Zu verwendende Regionskennung.
version (optional – standardmäßig Minio-Standard) – Konfigurationsdateiformat.
S3 verfügt über mehrere Adressierungsschemata, mit denen auf Ihren Bucket verwiesen wird. Diese sind hier aufgeführt: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
Einige Beispiele für diese Adressierungsschemata:
s3::https://s3.amazonaws.com/bucket/foo
s3::https://s3-eu-west-1.amazonaws.com/bucket/foo
Bucket.s3.amazonaws.com/foo
Bucket.s3-eu-west-1.amazonaws.com/foo/bar
„s3::http://127.0.0.1:9000/test-bucket/hello.txt?aws_access_key_id=KEYID&aws_access_key_secret=SECRETKEY®ion=us-east-2“
gcs )Für den Zugriff auf GCS müssen Authentifizierungsdaten bereitgestellt werden. Weitere Informationen finden Sie hier
gcs::https://www.googleapis.com/storage/v1/bucket
gcs::https://www.googleapis.com/storage/v1/bucket/foo.zip
www.googleapis.com/storage/v1/bucket/foo
Für die Tests für get_gcs.go müssen in Ihrer Umgebung GCP-Anmeldeinformationen festgelegt sein. Diese Anmeldeinformationen können über beliebige Berechtigungsstufen für jedes Projekt verfügen, sie müssen lediglich vorhanden sein. Dies bedeutet, dass GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" oder GOOGLE_CREDENTIALS="{stringified-credentials-json}" festgelegt wird. Aufgrund dieser Konfiguration schlägt get_gcs_test.go für externe Mitwirkende in CircleCI fehl.
Symlinks deaktivieren
In Ihrer Getter-Client-Konfiguration empfehlen wir die Verwendung der Option DisableSymlinks , die das Schreiben oder Kopieren von Symlinks (die möglicherweise außerhalb des Verzeichnisses verweisen) verhindert.
client := getter.Client{ // Dies verhindert das Kopieren oder Schreiben von Dateien über Symlinks DisableSymlinks: true,
} Deaktivieren oder beschränken Sie X-Terraform-Get
Go-Getter unterstützt beliebige Weiterleitungen über den X-Terraform-Get Header. Diese Funktionalität dient der Unterstützung von Terraform-Anwendungsfällen, wird jedoch in den meisten Anwendungen wahrscheinlich nicht benötigt.
Fügen Sie für Code, der HttpGetter verwendet, die folgenden Konfigurationsoptionen hinzu:
var httpGetter = &getter.HttpGetter{ // Die meisten Clients sollten X-Terraform-Get deaktivieren // Siehe den Hinweis unten XTerraformGetDisabled: true, // Ihre Software ist wahrscheinlich nicht auf X-Terraform-Get angewiesen, aber // wenn ja, ist dies der Fall , sollten Sie das obige Feld auf „false“ setzen und außerdem // XTerraformGet Limit festlegen, um endlose Weiterleitungen zu verhindern // XTerraformGetLimit: 10,}Zeitüberschreitungen erzwingen
Der HttpGetter unterstützt Zeitüberschreitungen und andere ressourcenbeschränkende Konfigurationsoptionen. GitGetter und HgGetter unterstützen nur Timeouts.
Konfiguration für den HttpGetter :
var httpGetter = &getter.HttpGetter{ // Prefetch-HEAD-Anfragen deaktivieren DoNotCheckHeadFirst: true,
// Alternativ zur obigen Einstellung können Sie // ein angemessenes Timeout für HEAD-Anfragen festlegen // HeadFirstTimeout: 10 * time.Second, // Lesetimeout für HTTP-Operationen ReadTimeout: 30 * time.Second, // Legen Sie fest maximale Anzahl an Bytes // die vom Getter gelesen werden können MaxBytes: 500000000, // 500 MB} Legen Sie für Code, der GitGetter oder HgGetter verwendet, die Option Timeout fest:
var gitGetter = &getter.GitGetter{ // Legen Sie eine angemessene Zeitüberschreitung für Git-Operationen fest. Zeitüberschreitung: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // Legen Sie eine angemessene Zeitüberschreitung für hg-Operationen fest. Zeitüberschreitung: 5 * time.Minute,
} 
