go getter
1.7.6
go-getter é uma biblioteca para Go (golang) para baixar arquivos ou diretórios de várias fontes usando um URL como forma principal de entrada.
O poder desta biblioteca é ser flexível ao poder fazer download de várias fontes diferentes (caminhos de arquivo, Git, HTTP, Mercurial, etc.) usando uma única string como entrada. Isso elimina o fardo de saber como fazer download de diversas fontes do implementador.
O conceito de detector transforma automaticamente URLs inválidos em URLs adequados. Por exemplo: "github.com/hashicorp/go-getter" se transformaria em uma URL do Git. Ou "./foo" se transformaria em um URL de arquivo. Estes são extensíveis.
Esta biblioteca é usada pelo Terraform para baixar módulos e Nomad para baixar binários.
A documentação do pacote pode ser encontrada no GoDoc.
A instalação pode ser feita com um go get normal:
$ go get github.com/hashicorp/go-getter
go-getter também possui um comando que você pode usar para testar strings de URL:
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
O comando é útil para verificar estruturas de URL.
Buscar recursos de URLs fornecidos pelo usuário é uma operação inerentemente perigosa e pode deixar seu aplicativo vulnerável à falsificação de solicitações do servidor, passagem de caminho, negação de serviço ou outras falhas de segurança.
go-getter contém mitigações para alguns desses problemas de segurança, mas ainda deve ser usado com cautela em contextos críticos de segurança. Veja as opções de segurança disponíveis que podem ser configuradas para mitigar alguns desses riscos.
go-getter pode retornar valores que contêm parâmetros de consulta fornecidos pelo chamador que podem conter dados confidenciais. O contexto em torno de quais parâmetros são ou não sensíveis é conhecido apenas pelo chamador do empreendedor e específico para cada caso de uso. Recomendamos que o chamador garanta que os valores de retorno do empreendedor (por exemplo, mensagens de erro) sejam tratados e higienizados adequadamente para garantir que dados confidenciais não sejam persistidos nos logs.
go-getter usa um URL de string única como entrada para download de uma variedade de protocolos. O go-getter tem vários "truques" com esse URL para fazer certas coisas. Esta seção documenta o formato do URL.
Os protocolos são usados para baixar arquivos/diretórios usando um mecanismo específico. Protocolos de exemplo são Git e HTTP.
Os detectores são usados para transformar uma URL válida ou inválida em outra URL se ela corresponder a um determinado padrão. Exemplo: "github.com/user/repo" é automaticamente transformado em um URL Git totalmente válido. Isso permite que o empreendedor seja muito amigável.
O go-getter pronto para uso oferece suporte aos seguintes protocolos. Protocolos adicionais podem ser aumentados em tempo de execução implementando a interface Getter .
Arquivos locais
Git
Mercurial
HTTP
Amazon S3
Google GCP
Além dos protocolos acima, o empreendedor possui os chamados “detectores”. Eles pegam uma URL e tentam escolher automaticamente o melhor protocolo para ela, o que pode envolver até mesmo a alteração do protocolo. A seguinte detecção é integrada por padrão:
Caminhos de arquivo como "./foo" são automaticamente alterados para URLs de arquivo absolutos.
URLs do GitHub, como "github.com/mitchellh/vagrant" são automaticamente alterados para o protocolo Git por HTTP.
URLs do GitLab, como "gitlab.com/inkscape/inkscape" são automaticamente alterados para o protocolo Git por HTTP.
URLs do BitBucket, como "bitbucket.org/mitchellh/vagrant" são automaticamente alterados para um protocolo Git ou Mercurial usando a API BitBucket.
Em alguns casos, o protocolo a utilizar é ambíguo dependendo do URL de origem. Por exemplo, "http://github.com/mitchellh/vagrant.git" pode fazer referência a um URL HTTP ou a um URL Git. A sintaxe de protocolo forçada é usada para desambiguar este URL.
O protocolo forçado pode ser feito prefixando o URL com o protocolo seguido por dois pontos duplos. Por exemplo: git::http://github.com/mitchellh/vagrant.git baixaria o URL HTTP fornecido usando o protocolo Git.
Os protocolos forçados também substituirão quaisquer detectores.
Na ausência de um protocolo forçado, os detectores podem ser executados na URL, transformando o protocolo de qualquer maneira. O exemplo acima teria usado o protocolo Git de qualquer maneira, já que o detector Git teria detectado que era um URL do GitHub.
Cada protocolo pode suportar opções específicas de protocolo para configurar esse protocolo. Por exemplo, o protocolo git suporta a especificação de um parâmetro de consulta ref que informa qual referência deve ser verificada para aquele repositório Git.
As opções são especificadas como parâmetros de consulta no URL (ou string semelhante a URL) fornecido ao empreendedor. Usando o exemplo do Git acima, o URL abaixo é uma entrada válida para empreendedores:
github.com/hashicorp/go-getter?ref=abcd1234
As opções específicas do protocolo estão documentadas abaixo da seção de formato de URL. Mas como fazem parte da URL, apontamos isso aqui para que você saiba que eles existem.
Se quiser fazer download apenas de um subdiretório específico de um diretório baixado, você pode especificar um subdiretório após uma barra dupla // . go-getter primeiro fará o download do URL especificado antes da barra dupla (como se você não tivesse especificado uma barra dupla), mas copiará o caminho após a barra dupla para o diretório de destino.
Por exemplo, se você estiver baixando este repositório GitHub, mas quiser baixar apenas o diretório testdata , poderá fazer o seguinte:
https://github.com/hashicorp/go-getter.git//testdata
Se você baixou isso para o diretório /tmp , então o arquivo /tmp/archive.gz existiria. Observe que este arquivo está no diretório testdata neste repositório, mas como especificamos um subdiretório, o go-getter copiou automaticamente apenas o conteúdo desse diretório.
Os caminhos dos subdiretórios também podem usar padrões glob do sistema de arquivos. O caminho deve corresponder exatamente a uma entrada ou o empreendedor retornará um erro. Isso é útil se você não tiver certeza do nome exato do diretório, mas segue uma estrutura de nomenclatura previsível.
Por exemplo, o seguinte URL também funcionaria:
https://github.com/hashicorp/go-getter.git//test-*
Para downloads de arquivos de qualquer protocolo, o empreendedor pode verificar automaticamente uma soma de verificação para você. Observe que a soma de verificação funciona apenas para download de arquivos, não de diretórios, mas a soma de verificação funcionará para qualquer protocolo.
Para fazer a soma de verificação de um arquivo, anexe um parâmetro de consulta de checksum ao URL. O go-getter analisará esse parâmetro de consulta automaticamente e o usará para verificar a soma de verificação. O valor do parâmetro pode estar no formato type:value ou apenas value , onde type é "md5", "sha1", "sha256", "sha512" ou "file" . O "valor" deve ser o valor real da soma de verificação ou o URL de download do "arquivo". Quando a parte type é omitida, o tipo será adivinhado com base no comprimento da string da soma de verificação. Exemplos:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
Ao fazer a soma de verificação de um arquivo - ex: com checksum=file:url - o go-getter obterá o arquivo vinculado na URL após file: usando a mesma configuração. Por exemplo, no file:http://releases.ubuntu.com/cosmic/MD5SUMS o go-getter baixará um arquivo de soma de verificação no URL mencionado acima usando o protocolo http. Todos os protocolos suportados pelo go-getter podem ser usados. O arquivo de soma de verificação será baixado em um arquivo temporário e então analisado. O destino do arquivo temporário pode ser alterado definindo variáveis de ambiente específicas do sistema: TMPDIR para unix; TMP , TEMP ou USERPROFILE no Windows. Leia godoc de os.TempDir para obter mais informações sobre a seleção de diretório temporário. Espera-se que o conteúdo dos arquivos seja do estilo BSD ou GNU. Assim que o empreendedor terminar com o arquivo de soma de verificação; ele é excluído.
O parâmetro de consulta checksum nunca é enviado para a implementação do protocolo backend. É usado em um nível superior pelo próprio empreendedor.
Se o arquivo de destino existir e as somas de verificação corresponderem: o download será ignorado.
go-getter desarquivará automaticamente os arquivos em um arquivo ou diretório com base na extensão do arquivo que está sendo solicitado (em qualquer protocolo). Isso funciona para downloads de arquivos e diretórios.
go-getter procura um parâmetro de consulta archive para especificar o formato do arquivo. Se isso não for especificado, o empreendedor usará a extensão do caminho para ver se ele aparece arquivado. O desarquivamento pode ser desabilitado explicitamente definindo o parâmetro de consulta archive como false .
Os seguintes formatos de arquivo são suportados:
tar.gz e tgz
tar.bz2 e tbz2
tar.xz e txz
zip
gz
bz2
xz
Por exemplo, um URL de exemplo é mostrado abaixo:
./foo.zip
Isso será automaticamente inferido como um arquivo ZIP e será extraído. Você também pode ser explícito sobre o tipo de arquivo:
./some/other/path?archive=zip
E, finalmente, você pode desabilitar completamente o arquivamento:
./some/path?archive=false
Você pode combinar o desarquivamento com outros recursos do empreendedor, como soma de verificação. O parâmetro de consulta archive especial será removido da URL antes de ir para o downloader de protocolo final.
Esta seção documenta as opções específicas do protocolo que podem ser especificadas para empreendedores. Essas opções devem ser anexadas à entrada como parâmetros de consulta normais (no entanto, os cabeçalhos HTTP são uma exceção). Dependendo do uso do empreendedor, os aplicativos podem fornecer formas alternativas de inserir opções. Por exemplo, o Nomad fornece um bloco de opções interessante para especificar opções em vez de na URL.
As opções abaixo estão disponíveis para todos os protocolos:
archive - O formato de arquivo a ser usado para desarquivar este arquivo ou "" (string vazia) para desabilitar o desarquivamento. Para obter mais detalhes, consulte a seção completa sobre suporte a arquivos acima.
checksum - Checksum para verificar o arquivo ou arquivo baixado. Consulte a seção inteira sobre soma de verificação acima para formato e mais detalhes.
filename - Quando no modo de download de arquivo, permite especificar o nome do arquivo baixado no disco. Não tem efeito no modo diretório.
file )Nenhum
git ) ref - A referência do Git para checkout. Esta é uma referência, portanto pode apontar para um SHA de commit, um nome de ramificação, etc. Se for uma referência nomeada, como um nome de ramificação, o go-getter irá atualizá-lo para o mais recente em cada obtenção.
sshkey – Uma chave privada SSH para usar durante clones. A chave fornecida deve ser uma string codificada em base64. Por exemplo, para gerar uma sshkey adequada a partir de um arquivo de chave privada no disco, você executaria base64 -w0 <file> .
Nota : Git 2.3+ é necessário para usar este recurso.
depth - A profundidade do clone do Git. O número fornecido especifica as últimas n revisões a serem clonadas do repositório.
O git getter aceita endereços SSH estilo URL, como git::ssh://[email protected]/foo/bar , e endereços "estilo scp", como git::[email protected]/foo/bar . Neste último caso, a omissão do prefixo git:: force é permitida se o prefixo do nome de usuário for exatamente git@ .
Os endereços "estilo scp" não podem ser usados em conjunto com o prefixo do esquema ssh:// , porque nesse caso os dois pontos são usados para marcar um número de porta opcional para conexão, em vez de delimitar o caminho do host.
hg ) rev - A revisão do Mercurial para checkout.
http ) Para usar a autenticação básica HTTP com go-getter, basta acrescentar username:password@ ao nome do host no URL, como https://Aladdin:[email protected]/index.html . Todos os caracteres especiais, incluindo nome de usuário e senha, devem ser codificados em URL.
Cabeçalhos de solicitação opcionais podem ser adicionados fornecendo-os em um HttpGetter personalizado ( não como parâmetros de consulta como a maioria das outras opções). Esses cabeçalhos serão enviados em todas as solicitações feitas pelo getter em questão.
s3 )O S3 aceita várias configurações de acesso na URL. Observe que ele também os lerá nas variáveis de ambiente padrão da AWS, se estiverem definidas. Servidores compatíveis com S3 como Minio também são suportados. Se os parâmetros de consulta estiverem presentes, estes terão prioridade.
aws_access_key_id – Chave de acesso da AWS.
aws_access_key_secret - segredo da chave de acesso da AWS.
aws_access_token - token de acesso da AWS se estiver sendo usado.
aws_profile - Use este perfil em ~/.aws/config local. Tem prioridade sobre os outros três.
Se você usa o go-getter e deseja usar um perfil de instância IAM do EC2 para evitar o uso de credenciais, basta omiti-las e o perfil, se disponível, será usado automaticamente.
Se você usar o go-gitter para suporte ao Minio, considere o seguinte:
aws_access_key_id (obrigatório) – chave de acesso Minio.
aws_access_key_secret (obrigatório) – segredo da chave de acesso Minio.
region (opcional - o padrão é us-east-1) - Identificador de região a ser usado.
version (opcional - o padrão é Minio) - Formato do arquivo de configuração.
O S3 possui vários esquemas de endereçamento usados para referenciar seu bucket. Eles estão listados aqui: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
Alguns exemplos para esses esquemas de endereçamento:
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 )Para acessar o GCS, deverão ser fornecidas credenciais de autenticação. Mais informações podem ser encontradas aqui
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
Os testes para get_gcs.go exigem que você tenha credenciais do GCP definidas em seu ambiente. Essas credenciais podem ter qualquer nível de permissão para qualquer projeto, elas só precisam existir. Isso significa definir GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" ou GOOGLE_CREDENTIALS="{stringified-credentials-json}" . Devido a esta configuração, get_gcs_test.go falhará para contribuidores externos no CircleCI.
Desativar links simbólicos
Na configuração do seu cliente getter, recomendamos usar a opção DisableSymlinks , que evita a gravação ou cópia de links simbólicos (que podem apontar para fora do diretório).
client := getter.Client{ // Isso impedirá a cópia ou gravação de arquivos por meio de links simbólicos DisableSymlinks: true,
} Desabilitar ou limitar X-Terraform-Get
Go-Getter oferece suporte a redirecionamentos arbitrários por meio do cabeçalho X-Terraform-Get . Essa funcionalidade existe para oferecer suporte a casos de uso do Terraform, mas provavelmente não é necessária na maioria dos aplicativos.
Para código que usa HttpGetter , adicione as seguintes opções de configuração:
var httpGetter = &getter.HttpGetter{ // A maioria dos clientes deve desativar o X-Terraform-Get // Veja a nota abaixo XTerraformGetDisabled: true, // Seu software provavelmente não depende do X-Terraform-Get, mas // se depender , você deve definir o campo acima como falso, além de // definir XTerraformGet Limit para evitar redirecionamentos infinitos // XTerraformGetLimit: 10,}Aplicar tempos limite
O HttpGetter oferece suporte a tempos limite e outras opções de configuração que restringem recursos. O GitGetter e HgGetter suportam apenas tempos limite.
Configuração para o HttpGetter :
var httpGetter = &getter.HttpGetter{ // Desativa solicitações HEAD de pré-busca DoNotCheckHeadFirst: true,
// Como alternativa à configuração acima, você pode // definir um tempo limite razoável para solicitações HEAD // HeadFirstTimeout: 10 * time.Second, // Tempo limite de leitura para operações HTTP ReadTimeout: 30 * time.Second, // Definir o número máximo de bytes // que podem ser lidos pelo getter MaxBytes: 500000000, // 500 MB} Para código que usa GitGetter ou HgGetter , defina a opção Timeout :
var gitGetter = &getter.GitGetter{ // Defina um tempo limite razoável para operações git Tempo limite: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // Defina um tempo limite razoável para operações hg Tempo limite: 5 * time.Minute,
} 
