go getter
1.7.6
go-getter es una biblioteca para Go (golang) para descargar archivos o directorios de varias fuentes utilizando una URL como forma principal de entrada.
El poder de esta biblioteca es ser flexible al poder descargar desde varias fuentes diferentes (rutas de archivos, Git, HTTP, Mercurial, etc.) usando una sola cadena como entrada. Esto elimina la carga de saber cómo descargar desde una variedad de fuentes desde el implementador.
El concepto de detector convierte automáticamente las URL no válidas en URL adecuadas. Por ejemplo: "github.com/hashicorp/go-getter" se convertiría en una URL de Git. O "./foo" se convertiría en la URL de un archivo. Estos son extensibles.
Terraform utiliza esta biblioteca para descargar módulos y Nomad para descargar binarios.
La documentación del paquete se puede encontrar en GoDoc.
La instalación se puede realizar con un go get normal:
$ go get github.com/hashicorp/go-getter
go-getter también tiene un comando que puedes usar para probar cadenas de URL:
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
El comando es útil para verificar estructuras de URL.
Obtener recursos de las URL proporcionadas por el usuario es una operación intrínsecamente peligrosa y puede dejar su aplicación vulnerable a la falsificación de solicitudes del lado del servidor, cruce de rutas, denegación de servicio u otras fallas de seguridad.
go-getter contiene mitigaciones para algunos de estos problemas de seguridad, pero aún así debe usarse con precaución en contextos críticos para la seguridad. Vea las opciones de seguridad disponibles que se pueden configurar para mitigar algunos de estos riesgos.
go-getter puede devolver valores que contengan parámetros de consulta proporcionados por la persona que llama que pueden contener datos confidenciales. El contexto sobre qué parámetros son y no son sensibles solo lo conoce la persona que llama al ambicioso y es específico de cada caso de uso. Recomendamos que la persona que llama se asegure de que los valores de retorno del buscador (por ejemplo, mensajes de error) se manejen y desinfecten adecuadamente para garantizar que los datos confidenciales no persistan en los registros.
go-getter utiliza una URL de cadena única como entrada para descargar desde una variedad de protocolos. go-getter tiene varios "trucos" con esta URL para hacer ciertas cosas. Esta sección documenta el formato de la URL.
Los protocolos se utilizan para descargar archivos/directorios utilizando un mecanismo específico. Los protocolos de ejemplo son Git y HTTP.
Los detectores se utilizan para transformar una URL válida o no válida en otra URL si coincide con un patrón determinado. Ejemplo: "github.com/user/repo" se transforma automáticamente en una URL de Git totalmente válida. Esto permite que el emprendedor sea muy fácil de usar.
Go-getter listo para usar admite los siguientes protocolos. Se pueden aumentar protocolos adicionales en tiempo de ejecución implementando la interfaz Getter .
Archivos locales
git
Mercurial
HTTP
amazon s3
Google GCP
Además de los protocolos anteriores, Go-Getter tiene lo que se llama "detectores". Estos toman una URL e intentan elegir automáticamente el mejor protocolo para ella, lo que podría implicar incluso cambiar el protocolo. La siguiente detección está integrada de forma predeterminada:
Las rutas de archivos como "./foo" se cambian automáticamente a URL de archivos absolutas.
Las URL de GitHub, como "github.com/mitchellh/vagrant", se cambian automáticamente al protocolo Git a través de HTTP.
Las URL de GitLab, como "gitlab.com/inkscape/inkscape", se cambian automáticamente al protocolo Git a través de HTTP.
Las URL de BitBucket, como "bitbucket.org/mitchellh/vagrant", se cambian automáticamente a un protocolo Git o mercurial utilizando la API de BitBucket.
En algunos casos, el protocolo a utilizar es ambiguo dependiendo de la URL de origen. Por ejemplo, "http://github.com/mitchellh/vagrant.git" podría hacer referencia a una URL HTTP o una URL Git. La sintaxis de protocolo forzada se utiliza para eliminar la ambigüedad de esta URL.
El protocolo forzado se puede realizar anteponiendo a la URL el protocolo seguido de dos puntos dobles. Por ejemplo: git::http://github.com/mitchellh/vagrant.git descargaría la URL HTTP proporcionada utilizando el protocolo Git.
Los protocolos forzados también anularán cualquier detector.
En ausencia de un protocolo forzado, se pueden ejecutar detectores en la URL, transformando el protocolo de todos modos. El ejemplo anterior habría usado el protocolo Git de cualquier manera ya que el detector de Git habría detectado que era una URL de GitHub.
Cada protocolo puede admitir opciones específicas del protocolo para configurar ese protocolo. Por ejemplo, el protocolo git admite la especificación de un parámetro de consulta ref que le indica qué referencia verificar para ese repositorio de Git.
Las opciones se especifican como parámetros de consulta en la URL (o cadena similar a una URL) proporcionada al buscador. Usando el ejemplo de Git anterior, la siguiente URL es una entrada válida para obtener resultados:
github.com/hashicorp/go-getter?ref=abcd1234
Las opciones específicas del protocolo están documentadas debajo de la sección de formato de URL. Pero como son parte de la URL, lo señalamos aquí para que sepas que existen.
Si desea descargar solo un subdirectorio específico de un directorio descargado, puede especificar un subdirectorio después de una doble barra // . go-getter primero descargará la URL especificada antes de la doble barra (como si no hubiera especificado una doble barra), pero luego copiará la ruta después de la doble barra en el directorio de destino.
Por ejemplo, si estás descargando este repositorio de GitHub, pero solo quieres descargar el directorio testdata , puedes hacer lo siguiente:
https://github.com/hashicorp/go-getter.git//testdata
Si descargó esto en el directorio /tmp , entonces existiría el archivo /tmp/archive.gz . Tenga en cuenta que este archivo está en el directorio testdata de este repositorio, pero debido a que especificamos un subdirectorio, go-getter copió automáticamente solo el contenido de ese directorio.
Las rutas de subdirectorio también pueden utilizar patrones globales del sistema de archivos. La ruta debe coincidir exactamente con una entrada o el buscador devolverá un error. Esto es útil si no está seguro del nombre exacto del directorio pero sigue una estructura de nombres predecible.
Por ejemplo, la siguiente URL también funcionaría:
https://github.com/hashicorp/go-getter.git//test-*
Para descargas de archivos de cualquier protocolo, go-getter puede verificar automáticamente una suma de verificación por usted. Tenga en cuenta que la suma de verificación solo funciona para descargar archivos, no directorios, pero la suma de verificación funcionará para cualquier protocolo.
Para realizar la suma de verificación de un archivo, agregue un parámetro de consulta checksum a la URL. go-getter analizará este parámetro de consulta automáticamente y lo utilizará para verificar la suma de verificación. El valor del parámetro puede tener el formato type:value o simplemente value , donde tipo es "md5", "sha1", "sha256", "sha512" o "file". El "valor" debe ser el valor real de la suma de comprobación o la URL de descarga del "archivo". Cuando se omite la parte type , el tipo se adivinará en función de la longitud de la cadena de suma de comprobación. Ejemplos:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
Al realizar la suma de verificación de un archivo, por ejemplo, con checksum=file:url , go-getter obtendrá el archivo vinculado en la URL después file: usando la misma configuración. Por ejemplo, en file:http://releases.ubuntu.com/cosmic/MD5SUMS go-getter descargará un archivo de suma de comprobación en la URL antes mencionada utilizando el protocolo http. Se pueden utilizar todos los protocolos admitidos por go-getter. El archivo de suma de comprobación se descargará en un archivo temporal y luego se analizará. El destino del archivo temporal se puede cambiar configurando variables de entorno específicas del sistema: TMPDIR para Unix; TMP , TEMP o USERPROFILE en Windows. Lea godoc de os.TempDir para obtener más información sobre la selección del directorio temporal. Se espera que el contenido de los archivos sea de estilo BSD o GNU. Una vez que haya terminado con el archivo de suma de comprobación; se elimina.
El parámetro de consulta de suma de comprobación nunca se envía a la implementación del protocolo de fondo. Lo utiliza a un nivel superior el propio ambicioso.
Si el archivo de destino existe y las sumas de verificación coinciden: se omitirá la descarga.
go-getter descomprimirá automáticamente los archivos en un archivo o directorio según la extensión del archivo solicitado (a través de cualquier protocolo). Esto funciona tanto para descargas de archivos como de directorios.
go-getter busca un parámetro de consulta archive para especificar el formato del archivo. Si no se especifica esto, go-getter usará la extensión de la ruta para ver si aparece archivada. La desarchivación se puede deshabilitar explícitamente configurando el parámetro de consulta archive en false .
Se admiten los siguientes formatos de archivo:
tar.gz y tgz
tar.bz2 y tbz2
tar.xz y txz
zip
gz
bz2
xz
Por ejemplo, a continuación se muestra una URL de ejemplo:
./foo.zip
Automáticamente se inferirá que es un archivo ZIP y se extraerá. También puedes ser explícito sobre el tipo de archivo:
./some/other/path?archive=zip
Y finalmente, puedes desactivar el archivado por completo:
./some/path?archive=false
Puede combinar el desarchivado con otras funciones de Go-getter, como la suma de verificación. El parámetro de consulta archive especial se eliminará de la URL antes de ir al descargador del protocolo final.
Esta sección documenta las opciones específicas del protocolo que se pueden especificar para go-getter. Estas opciones deben agregarse a la entrada como parámetros de consulta normales (sin embargo, los encabezados HTTP son una excepción a esto). Dependiendo del uso de Go-getter, las aplicaciones pueden proporcionar formas alternativas de ingresar opciones. Por ejemplo, Nomad proporciona un bonito bloque de opciones para especificar opciones en lugar de en la URL.
Las siguientes opciones están disponibles para todos los protocolos:
archive : el formato de archivo que se utilizará para desarchivar este archivo, o "" (cadena vacía) para deshabilitar la desarchivación. Para obtener más detalles, consulte la sección completa sobre compatibilidad con archivos anterior.
checksum : suma de comprobación para verificar el archivo o archivo descargado. Consulte la sección completa sobre suma de verificación anterior para conocer el formato y más detalles.
filename : cuando está en modo de descarga de archivos, permite especificar el nombre del archivo descargado en el disco. No tiene ningún efecto en modo directorio.
file )Ninguno
git ) ref : la referencia de Git para realizar el pago. Esta es una referencia, por lo que puede apuntar a un SHA de confirmación, un nombre de rama, etc. Si es una referencia con nombre, como el nombre de una rama, go-getter la actualizará a la última versión en cada obtención.
sshkey : una clave privada SSH para usar durante las clones. La clave proporcionada debe ser una cadena codificada en base64. Por ejemplo, para generar una sshkey adecuada a partir de un archivo de clave privada en el disco, ejecutaría base64 -w0 <file> .
Nota : Se requiere Git 2.3+ para utilizar esta función.
depth : la profundidad del clon de Git. El número proporcionado especifica las últimas n revisiones para clonar desde el repositorio.
El git getter acepta direcciones SSH de estilo URL como git::ssh://[email protected]/foo/bar y direcciones de "estilo scp" como git::[email protected]/foo/bar . En el último caso, se permite omitir el prefijo git:: force si el prefijo del nombre de usuario es exactamente git@ .
Las direcciones "estilo scp" no se pueden usar junto con el prefijo de esquema ssh:// , porque en ese caso los dos puntos se usan para marcar un número de puerto opcional para conectarse, en lugar de delimitar la ruta desde el host.
hg ) rev - La revisión de Mercurial para finalizar la compra.
http ) Para utilizar la autenticación básica HTTP con go-getter, simplemente anteponga username:password@ al nombre de host en la URL, como https://Aladdin:[email protected]/index.html . Todos los caracteres especiales, incluidos el nombre de usuario y la contraseña, deben estar codificados en URL.
Se pueden agregar encabezados de solicitud opcionales proporcionándolos en un HttpGetter personalizado ( no como parámetros de consulta como la mayoría de las otras opciones). Estos encabezados se enviarán en cada solicitud que realice el captador en cuestión.
s3 )S3 toma varias configuraciones de acceso en la URL. Tenga en cuenta que también los leerá desde las variables de entorno estándar de AWS si están configuradas. También se admiten servidores compatibles con S3 como Minio. Si los parámetros de consulta están presentes, estos tienen prioridad.
aws_access_key_id : clave de acceso de AWS.
aws_access_key_secret : secreto de clave de acceso de AWS.
aws_access_token : token de acceso de AWS si se está utilizando.
aws_profile : utilice este perfil desde la configuración local ~/.aws/. Tiene prioridad sobre los otros tres.
Si utiliza go-getter y desea utilizar un perfil de instancia EC2 IAM para evitar el uso de credenciales, simplemente omítalas y el perfil, si está disponible, se utilizará automáticamente.
Si utiliza go-gitter para soporte de Minio, debe considerar lo siguiente:
aws_access_key_id (obligatorio): clave de acceso a Minio.
aws_access_key_secret (obligatorio): clave secreta de acceso a Minio.
region (opcional; por defecto es us-east-1): identificador de región a utilizar.
version (opcional - por defecto es Minio) - Formato del archivo de configuración.
S3 tiene varios esquemas de direccionamiento que se utilizan para hacer referencia a su depósito. Estos se enumeran aquí: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
Algunos ejemplos de estos esquemas de direccionamiento:
s3::https://s3.amazonaws.com/bucket/foo
s3::https://s3-eu-west-1.amazonaws.com/bucket/foo
cubo.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 acceder a GCS, se deben proporcionar credenciales de autenticación. Puede encontrar más información aquí.
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
Las pruebas para get_gcs.go requieren que tengas las credenciales de GCP configuradas en tu entorno. Estas credenciales pueden tener cualquier nivel de permisos para cualquier proyecto, solo necesitan existir. Esto significa configurar GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" o GOOGLE_CREDENTIALS="{stringified-credentials-json}" . Debido a esta configuración, get_gcs_test.go fallará para los contribuyentes externos en CircleCI.
Deshabilitar enlaces simbólicos
En la configuración de su cliente getter, recomendamos utilizar la opción DisableSymlinks , que evita escribir o copiar desde enlaces simbólicos (que pueden apuntar fuera del directorio).
client := getter.Client{ // Esto evitará copiar o escribir archivos a través de enlaces simbólicos DisableSymlinks: true,
} Deshabilitar o limitar X-Terraform-Get
Go-Getter admite redirecciones arbitrarias a través del encabezado X-Terraform-Get . Esta funcionalidad existe para admitir casos de uso de Terraform, pero probablemente no sea necesaria en la mayoría de las aplicaciones.
Para el código que utiliza HttpGetter , agregue las siguientes opciones de configuración:
var httpGetter = &getter.HttpGetter{ // La mayoría de los clientes deberían deshabilitar X-Terraform-Get // Vea la nota a continuación XTerraformGetDisabled: true, // Su software probablemente no dependa de X-Terraform-Get, pero // si lo hace , debes establecer el campo anterior en falso, además // establecer el límite XTerraformGet para evitar redireccionamientos interminables // XTerraformGetLimit: 10,}Aplicar tiempos de espera
HttpGetter admite tiempos de espera y otras opciones de configuración que limitan los recursos. GitGetter y HgGetter solo admiten tiempos de espera.
Configuración para HttpGetter :
var httpGetter = &getter.HttpGetter{ // Deshabilitar las solicitudes HEAD de búsqueda previa DoNotCheckHeadFirst: verdadero,
// Como alternativa a la configuración anterior, puede // establecer un tiempo de espera razonable para las solicitudes HEAD // HeadFirstTimeout: 10 * time.Second, // Tiempo de espera de lectura para operaciones HTTP ReadTimeout: 30 * time.Second, // Establecer el número máximo de bytes // que puede leer el getter MaxBytes: 500000000, // 500 MB} Para el código que utiliza GitGetter o HgGetter , configure la opción Timeout :
var gitGetter = &getter.GitGetter{ // Establece un tiempo de espera razonable para las operaciones de git Tiempo de espera: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // Establece un tiempo de espera razonable para las operaciones de hg Tiempo de espera: 5 * time.Minute,
} 
