go getter
1.7.6
go-getter est une bibliothèque pour Go (golang) permettant de télécharger des fichiers ou des répertoires à partir de diverses sources en utilisant une URL comme principale forme d'entrée.
La puissance de cette bibliothèque réside dans sa flexibilité, car elle permet de télécharger à partir d'un certain nombre de sources différentes (chemins de fichiers, Git, HTTP, Mercurial, etc.) en utilisant une seule chaîne comme entrée. Cela supprime le fardeau de savoir comment télécharger à partir de diverses sources auprès de l'implémenteur.
Le concept de détecteur transforme automatiquement les URL invalides en URL appropriées. Par exemple : « github.com/hashicorp/go-getter » se transformerait en une URL Git. Ou "./foo" se transformerait en une URL de fichier. Ceux-ci sont extensibles.
Cette bibliothèque est utilisée par Terraform pour télécharger des modules et Nomad pour télécharger des binaires.
La documentation du package peut être trouvée sur GoDoc.
L'installation peut être effectuée avec un go get normal :
$ go get github.com/hashicorp/go-getter
go-getter dispose également d'une commande que vous pouvez utiliser pour tester les chaînes d'URL :
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
La commande est utile pour vérifier les structures d'URL.
La récupération de ressources à partir d'URL fournies par l'utilisateur est une opération intrinsèquement dangereuse et peut rendre votre application vulnérable à la falsification de requêtes côté serveur, à la traversée de chemin, au déni de service ou à d'autres failles de sécurité.
go-getter contient des atténuations pour certains de ces problèmes de sécurité, mais doit toujours être utilisé avec prudence dans des contextes critiques en matière de sécurité. Consultez les options de sécurité disponibles qui peuvent être configurées pour atténuer certains de ces risques.
go-getter peut renvoyer des valeurs contenant des paramètres de requête fournis par l'appelant pouvant contenir des données sensibles. Le contexte autour des paramètres sensibles et non sensibles n'est connu que par l'appelant du fonceur et est spécifique à chaque cas d'utilisation. Nous recommandons à l'appelant de s'assurer que les valeurs de retour du fonceur (par exemple, les messages d'erreur) sont correctement traitées et nettoyées pour garantir que les données sensibles ne sont pas conservées dans les journaux.
go-getter utilise une URL à chaîne unique comme entrée pour télécharger à partir d'une variété de protocoles. go-getter a diverses "astuces" avec cette URL pour faire certaines choses. Cette section documente le format de l'URL.
Les protocoles sont utilisés pour télécharger des fichiers/répertoires à l'aide d'un mécanisme spécifique. Des exemples de protocoles sont Git et HTTP.
Les détecteurs sont utilisés pour transformer une URL valide ou invalide en une autre URL si elle correspond à un certain modèle. Exemple : "github.com/user/repo" est automatiquement transformé en une URL Git entièrement valide. Cela permet au fonceur d'être très convivial.
Le go-getter prêt à l'emploi prend en charge les protocoles suivants. Des protocoles supplémentaires peuvent être augmentés au moment de l'exécution en implémentant l'interface Getter .
Fichiers locaux
Git
Mercuriel
HTTP
Amazone S3
Google GCP
En plus des protocoles ci-dessus, Go-getter dispose de ce qu'on appelle des « détecteurs ». Ceux-ci prennent une URL et tentent de choisir automatiquement le meilleur protocole, ce qui peut même impliquer de modifier le protocole. La détection suivante est intégrée par défaut :
Les chemins de fichiers tels que "./foo" sont automatiquement remplacés par des URL de fichiers absolues.
Les URL GitHub, telles que « github.com/mitchellh/vagrant », sont automatiquement remplacées par le protocole Git sur HTTP.
Les URL GitLab, telles que « gitlab.com/inkscape/inkscape », sont automatiquement remplacées par le protocole Git sur HTTP.
Les URL BitBucket, telles que « bitbucket.org/mitchellh/vagrant », sont automatiquement remplacées par un protocole Git ou Mercurial à l'aide de l'API BitBucket.
Dans certains cas, le protocole à utiliser est ambigu selon l'URL source. Par exemple, « http://github.com/mitchellh/vagrant.git » peut faire référence à une URL HTTP ou à une URL Git. La syntaxe de protocole forcé est utilisée pour lever l'ambiguïté de cette URL.
Le protocole forcé peut être effectué en préfixant l'URL avec le protocole suivi de doubles deux-points. Par exemple : git::http://github.com/mitchellh/vagrant.git téléchargerait l'URL HTTP donnée à l'aide du protocole Git.
Les protocoles forcés remplaceront également tous les détecteurs.
En l'absence de protocole forcé, des détecteurs peuvent être exécutés sur l'URL, transformant de toute façon le protocole. L'exemple ci-dessus aurait utilisé le protocole Git dans les deux cas puisque le détecteur Git aurait détecté qu'il s'agissait d'une URL GitHub.
Chaque protocole peut prendre en charge des options spécifiques au protocole pour configurer ce protocole. Par exemple, le protocole git prend en charge la spécification d'un paramètre de requête ref qui lui indique quelle référence extraire pour ce référentiel Git.
Les options sont spécifiées sous forme de paramètres de requête sur l'URL (ou la chaîne de type URL) donnée au fonceur. En utilisant l'exemple Git ci-dessus, l'URL ci-dessous est une entrée valide pour le fonceur :
github.com/hashicorp/go-getter?ref=abcd1234
Les options spécifiques au protocole sont documentées sous la section Format d'URL. Mais comme ils font partie de l’URL, nous le signalons ici afin que vous sachiez qu’ils existent.
Si vous souhaitez télécharger uniquement un sous-répertoire spécifique à partir d'un répertoire téléchargé, vous pouvez spécifier un sous-répertoire après une double barre oblique // . go-getter téléchargera d'abord l'URL spécifiée avant la double barre oblique (comme si vous n'aviez pas spécifié de double barre oblique), mais copiera ensuite le chemin après la double barre oblique dans le répertoire cible.
Par exemple, si vous téléchargez ce référentiel GitHub, mais que vous souhaitez uniquement télécharger le répertoire testdata , vous pouvez procéder comme suit :
https://github.com/hashicorp/go-getter.git//testdata
Si vous l'avez téléchargé dans le répertoire /tmp , alors le fichier /tmp/archive.gz existerait. Notez que ce fichier se trouve dans le répertoire testdata de ce référentiel, mais comme nous avons spécifié un sous-répertoire, go-getter a automatiquement copié uniquement le contenu de ce répertoire.
Les chemins de sous-répertoire peuvent également utiliser des modèles globaux du système de fichiers. Le chemin doit correspondre exactement à une entrée, sinon le go-getter renverra une erreur. Ceci est utile si vous n'êtes pas sûr du nom exact du répertoire mais qu'il suit une structure de dénomination prévisible.
Par exemple, l'URL suivante fonctionnerait également :
https://github.com/hashicorp/go-getter.git//test-*
Pour les téléchargements de fichiers de n'importe quel protocole, go-getter peut vérifier automatiquement une somme de contrôle pour vous. Notez que la somme de contrôle ne fonctionne que pour le téléchargement de fichiers, pas de répertoires, mais la somme de contrôle fonctionnera pour n'importe quel protocole.
Pour vérifier la somme d'un fichier, ajoutez un paramètre de requête checksum à l'URL. go-getter analysera automatiquement ce paramètre de requête et l'utilisera pour vérifier la somme de contrôle. La valeur du paramètre peut être au format type:value ou simplement value , où type est "md5", "sha1", "sha256", "sha512" ou "file" . La « valeur » doit être la valeur réelle de la somme de contrôle ou l'URL de téléchargement du « fichier ». Lorsque la partie type est omise, le type sera deviné en fonction de la longueur de la chaîne de somme de contrôle. Exemples :
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
Lors de la somme de contrôle à partir d'un fichier - ex : avec checksum=file:url - go-getter obtiendra le fichier lié dans l'URL après file: en utilisant la même configuration. Par exemple, dans file:http://releases.ubuntu.com/cosmic/MD5SUMS go-getter téléchargera un fichier de somme de contrôle sous l'URL susmentionnée en utilisant le protocole http. Tous les protocoles pris en charge par go-getter peuvent être utilisés. Le fichier de somme de contrôle sera téléchargé dans un fichier temporaire puis analysé. La destination du fichier temporaire peut être modifiée en définissant des variables d'environnement spécifiques au système : TMPDIR pour Unix ; TMP , TEMP ou USERPROFILE sous Windows. Lisez le godoc de os.TempDir pour plus d'informations sur la sélection de répertoire temporaire. Le contenu des fichiers doit être de style BSD ou GNU. Une fois que le fonceur a terminé avec le fichier de somme de contrôle ; il est supprimé.
Le paramètre de requête de somme de contrôle n’est jamais envoyé à l’implémentation du protocole backend. Il est utilisé à un niveau supérieur par le fonceur lui-même.
Si le fichier de destination existe et que les sommes de contrôle correspondent : le téléchargement sera ignoré.
go-getter désarchivera automatiquement les fichiers dans un fichier ou un répertoire en fonction de l'extension du fichier demandé (sur n'importe quel protocole). Cela fonctionne à la fois pour les téléchargements de fichiers et de répertoires.
go-getter recherche un paramètre de requête archive pour spécifier le format de l'archive. Si cela n'est pas précisé, go-getter utilisera l'extension du chemin pour voir s'il apparaît archivé. La désarchivage peut être explicitement désactivée en définissant le paramètre de requête archive sur false .
Les formats d'archives suivants sont pris en charge :
tar.gz et tgz
tar.bz2 et tbz2
tar.xz et txz
zip
gz
bz2
xz
Par exemple, un exemple d'URL est présenté ci-dessous :
./foo.zip
Celui-ci sera automatiquement considéré comme un fichier ZIP et sera extrait. Vous pouvez également être explicite sur le type d'archive :
./some/other/path?archive=zip
Et enfin, vous pouvez désactiver complètement l'archivage :
./some/path?archive=false
Vous pouvez combiner le désarchivage avec les autres fonctionnalités de Go-getter telles que la somme de contrôle. Le paramètre spécial de requête archive sera supprimé de l'URL avant d'accéder au téléchargeur de protocole final.
Cette section documente les options spécifiques au protocole qui peuvent être spécifiées pour le fonceur. Ces options doivent être ajoutées à l'entrée en tant que paramètres de requête normaux (les en-têtes HTTP constituent cependant une exception à cette règle). En fonction de l'utilisation de go-getter, les applications peuvent proposer d'autres moyens de saisir des options. Par exemple, Nomad fournit un bloc d'options intéressant pour spécifier des options plutôt que dans l'URL.
Les options ci-dessous sont disponibles pour tous les protocoles :
archive - Le format d'archive à utiliser pour désarchiver ce fichier, ou "" (chaîne vide) pour désactiver la désarchivage. Pour plus de détails, consultez la section complète sur la prise en charge des archives ci-dessus.
checksum - Somme de contrôle pour vérifier le fichier ou l'archive téléchargé. Consultez la section complète sur la somme de contrôle ci-dessus pour le format et plus de détails.
filename - En mode téléchargement de fichier, permet de spécifier le nom du fichier téléchargé sur le disque. N'a aucun effet en mode répertoire.
file )Aucun
git ) ref - La référence Git à payer. Il s'agit d'une référence, elle peut donc pointer vers un SHA de validation, un nom de branche, etc. S'il s'agit d'une référence nommée telle qu'un nom de branche, go-getter la mettra à jour avec la dernière version à chaque obtention.
sshkey - Une clé privée SSH à utiliser lors des clones. La clé fournie doit être une chaîne codée en base64. Par exemple, pour générer une sshkey appropriée à partir d'un fichier de clé privée sur le disque, vous exécuterez base64 -w0 <file> .
Remarque : Git 2.3+ est requis pour utiliser cette fonctionnalité.
depth - La profondeur du clone Git. Le numéro fourni spécifie les n dernières révisions à cloner à partir du référentiel.
Le getter git accepte à la fois les adresses SSH de style URL comme git::ssh://[email protected]/foo/bar , et les adresses "style scp" comme git::[email protected]/foo/bar . Dans ce dernier cas, l'omission du préfixe git:: force est autorisée si le préfixe du nom d'utilisateur est exactement git@ .
Les adresses "de style scp" ne peuvent pas être utilisées conjointement avec le préfixe du schéma ssh:// , car dans ce cas, les deux points sont utilisés pour marquer un numéro de port facultatif sur lequel se connecter, plutôt que pour délimiter le chemin depuis l'hôte.
hg ) rev - La révision Mercurial à la caisse.
http ) Pour utiliser l'authentification de base HTTP avec go-getter, ajoutez simplement username:password@ au nom d'hôte dans l'URL, par exemple https://Aladdin:[email protected]/index.html . Tous les caractères spéciaux, y compris le nom d'utilisateur et le mot de passe, doivent être codés en URL.
Des en-têtes de requête facultatifs peuvent être ajoutés en les fournissant dans un HttpGetter personnalisé ( et non en tant que paramètres de requête comme la plupart des autres options). Ces en-têtes seront envoyés à chaque demande faite par le getter en question.
s3 )S3 prend diverses configurations d'accès dans l'URL. Notez qu'il les lira également à partir des variables d'environnement AWS standard si elles sont définies. Les serveurs compatibles S3 comme Minio sont également pris en charge. Si les paramètres de requête sont présents, ceux-ci sont prioritaires.
aws_access_key_id - Clé d'accès AWS.
aws_access_key_secret - Clé secrète de clé d'accès AWS.
aws_access_token - Jeton d'accès AWS s'il est utilisé.
aws_profile - Utilisez ce profil depuis le local ~/.aws/ config. A la priorité sur les trois autres.
Si vous utilisez go-getter et souhaitez utiliser un profil d'instance EC2 IAM pour éviter d'utiliser les informations d'identification, omettez-les simplement et le profil, s'il est disponible, sera utilisé automatiquement.
Si vous utilisez go-gitter pour le support Minio, vous devez prendre en compte les éléments suivants :
aws_access_key_id (obligatoire) - Clé d'accès Minio.
aws_access_key_secret (obligatoire) - Clé secrète de la clé d'accès Minio.
region (facultatif - par défaut us-east-1) - Identifiant de région à utiliser.
version (facultatif - par défaut Minio) - Format du fichier de configuration.
S3 dispose de plusieurs schémas d'adressage utilisés pour référencer votre compartiment. Ceux-ci sont répertoriés ici : https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
Quelques exemples de ces schémas d'adressage :
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 )Pour accéder à GCS, des informations d'authentification doivent être fournies. Plus d'informations peuvent être trouvées ici
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
Les tests pour get_gcs.go nécessitent que vous ayez défini les informations d'identification GCP dans votre environnement. Ces informations d'identification peuvent avoir n'importe quel niveau d'autorisation sur n'importe quel projet, elles doivent simplement exister. Cela signifie définir GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" ou GOOGLE_CREDENTIALS="{stringified-credentials-json}" . En raison de cette configuration, get_gcs_test.go échouera pour les contributeurs externes dans CircleCI.
Désactiver les liens symboliques
Dans la configuration de votre client getter, nous vous recommandons d'utiliser l'option DisableSymlinks , qui empêche l'écriture ou la copie à partir de liens symboliques (qui peuvent pointer en dehors du répertoire).
client := getter.Client{ // Cela empêchera la copie ou l'écriture de fichiers via des liens symboliques DisableSymlinks: true,
} Désactiver ou limiter X-Terraform-Get
Go-Getter prend en charge les redirections arbitraires via l'en-tête X-Terraform-Get . Cette fonctionnalité existe pour prendre en charge les cas d'utilisation de Terraform, mais n'est probablement pas nécessaire dans la plupart des applications.
Pour le code qui utilise HttpGetter , ajoutez les options de configuration suivantes :
var httpGetter = &getter.HttpGetter{ // La plupart des clients devraient désactiver X-Terraform-Get // Voir la note ci-dessous XTerraformGetDisabled : true, // Votre logiciel ne repose probablement pas sur X-Terraform-Get, mais // si c'est le cas , vous devez définir le champ ci-dessus sur false, plus // définir XTerraformGet Limit pour empêcher les redirections sans fin // XTerraformGetLimit: 10,}Appliquer les délais d'attente
HttpGetter prend en charge les délais d'attente et d'autres options de configuration contraignant les ressources. GitGetter et HgGetter ne prennent en charge que les délais d'attente.
Configuration pour le HttpGetter :
var httpGetter = &getter.HttpGetter{ // Désactiver les requêtes HEAD de pré-extraction DoNotCheckHeadFirst : true,
// Comme alternative au paramètre ci-dessus, vous pouvez // définir un délai d'expiration raisonnable pour les requêtes HEAD // HeadFirstTimeout : 10 * time.Second, // Délai d'expiration de lecture pour les opérations HTTP ReadTimeout : 30 * time.Second, // Définir le nombre maximum d'octets // pouvant être lus par le getter MaxBytes : 500000000, // 500 Mo} Pour le code qui utilise GitGetter ou HgGetter , définissez l'option Timeout :
var gitGetter = &getter.GitGetter{ // Définir un délai d'attente raisonnable pour les opérations git Timeout : 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // Définir un délai d'attente raisonnable pour les opérations hg Timeout : 5 * time.Minute,
} 
