иди добытчик
1.7.6
go-getter — это библиотека Go (golang) для загрузки файлов или каталогов из различных источников с использованием URL-адреса в качестве основной формы ввода.
Сила этой библиотеки заключается в гибкости, позволяющей загружать ее из различных источников (пути к файлам, Git, HTTP, Mercurial и т. д.), используя одну строку в качестве входных данных. Это снимает с разработчика необходимость знания того, как загружать из различных источников.
Концепция детектора автоматически превращает недействительные URL-адреса в правильные. Например: «github.com/hashicorp/go-getter» превратится в URL-адрес Git. Или «./foo» превратится в URL-адрес файла. Они расширяемые.
Эта библиотека используется Terraform для загрузки модулей и Nomad для загрузки двоичных файлов.
Документацию пакета можно найти на GoDoc.
Установку можно выполнить с помощью обычного go get :
$ go get github.com/hashicorp/go-getter
go-getter также имеет команду, которую вы можете использовать для проверки строк URL:
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
Команда полезна для проверки структур URL.
Извлечение ресурсов с URL-адресов, предоставленных пользователем, является по своей сути опасной операцией и может сделать ваше приложение уязвимым для подделки запросов на стороне сервера, обхода пути, отказа в обслуживании или других недостатков безопасности.
go-getter содержит средства смягчения некоторых из этих проблем безопасности, но его все равно следует использовать с осторожностью в контекстах, критически важных для безопасности. Ознакомьтесь с доступными параметрами безопасности, которые можно настроить для снижения некоторых из этих рисков.
go-getter может возвращать значения, содержащие параметры запроса, предоставленные вызывающей стороной, которые могут содержать конфиденциальные данные. Контекст вокруг того, какие параметры являются конфиденциальными, а какие нет, известен только вызывающему объекту Go-Getter и специфичен для каждого варианта использования. Мы рекомендуем вызывающей стороне убедиться, что возвращаемые значения go-getter (например, сообщения об ошибках) правильно обрабатываются и очищаются, чтобы гарантировать, что конфиденциальные данные не сохраняются в журналах.
go-getter использует однострочный URL-адрес в качестве входных данных для загрузки по различным протоколам. go-getter имеет различные «хитрости» с этим URL-адресом для выполнения определенных действий. В этом разделе описывается формат URL.
Протоколы используются для загрузки файлов/каталогов с использованием определенного механизма. Примеры протоколов: Git и HTTP.
Детекторы используются для преобразования действительного или недействительного URL-адреса в другой URL-адрес, если он соответствует определенному шаблону. Пример: «github.com/user/repo» автоматически преобразуется в полностью действительный URL-адрес Git. Это позволяет Go-Getter быть очень удобным для пользователя.
go-getter «из коробки» поддерживает следующие протоколы. Дополнительные протоколы можно расширить во время выполнения, реализовав интерфейс Getter .
Локальные файлы
Гит
Меркуриальный
HTTP
Амазонка S3
Google GCP
Помимо вышеперечисленных протоколов, Go-Getter имеет так называемые «детекторы». Они берут URL-адрес и пытаются автоматически выбрать для него лучший протокол, что может даже потребовать изменения протокола. По умолчанию встроено следующее обнаружение:
Пути к файлам, такие как «./foo», автоматически изменяются на абсолютные URL-адреса файлов.
URL-адреса GitHub, такие как «github.com/mitchellh/vagrant», автоматически изменяются на протокол Git через HTTP.
URL-адреса GitLab, такие как «gitlab.com/inkscape/inkscape», автоматически изменяются на протокол Git через HTTP.
URL-адреса BitBucket, такие как «bitbucket.org/mitchellh/vagrant», автоматически изменяются на протокол Git или mercurial с помощью API BitBucket.
В некоторых случаях используемый протокол неоднозначен в зависимости от исходного URL-адреса. Например, «http://github.com/mitchellh/vagrant.git» может ссылаться на URL-адрес HTTP или URL-адрес Git. Принудительный синтаксис протокола используется для устранения неоднозначности этого URL-адреса.
Принудительный протокол можно выполнить, указав перед URL-адресом протокол, за которым следуют двойные двоеточия. Например: git::http://github.com/mitchellh/vagrant.git загрузит указанный URL-адрес HTTP с использованием протокола Git.
Принудительные протоколы также будут игнорировать любые детекторы.
При отсутствии принудительного протокола детекторы могут быть запущены на URL-адресе, в любом случае преобразуя протокол. В приведенном выше примере в любом случае использовался бы протокол Git, поскольку детектор Git обнаружил бы, что это URL-адрес GitHub.
Каждый протокол может поддерживать специальные параметры для настройки этого протокола. Например, протокол git поддерживает указание параметра запроса ref , который сообщает, какую ссылку следует извлечь для этого репозитория Git.
Параметры указываются как параметры запроса по URL-адресу (или строке, похожей на URL-адрес), переданному go-getter. Используя приведенный выше пример Git, приведенный ниже URL-адрес является допустимым вводом для Go-Getter:
github.com/hashicorp/go-getter?ref=abcd1234
Параметры протокола описаны ниже раздела формата URL-адреса. Но поскольку они являются частью URL-адреса, мы указываем на них здесь, чтобы вы знали, что они существуют.
Если вы хотите загрузить только определенный подкаталог из загруженного каталога, вы можете указать подкаталог после двойной косой черты // . go-getter сначала загрузит URL-адрес, указанный перед двойной косой чертой (как если бы вы не указали двойную косую черту), но затем скопирует путь после двойной косой черты в целевой каталог.
Например, если вы загружаете этот репозиторий GitHub, но хотите загрузить только каталог testdata , вы можете сделать следующее:
https://github.com/hashicorp/go-getter.git//testdata
Если вы загрузили это в каталог /tmp , файл /tmp/archive.gz будет существовать. Обратите внимание, что этот файл находится в каталоге testdata в этом репозитории, но поскольку мы указали подкаталог, go-getter автоматически скопировал только содержимое этого каталога.
Пути к подкаталогам также могут использовать шаблоны glob файловой системы. Путь должен соответствовать ровно одной записи, иначе go-getter вернет ошибку. Это полезно, если вы не знаете точное имя каталога, но оно соответствует предсказуемой структуре именования.
Например, следующий URL-адрес также будет работать:
https://github.com/hashicorp/go-getter.git//test-*
Для загрузки файлов любого протокола go-getter может автоматически проверить контрольную сумму. Обратите внимание, что контрольная сумма работает только для загрузки файлов, а не каталогов, но контрольная сумма будет работать для любого протокола.
Чтобы проверить контрольную сумму файла, добавьте к URL-адресу параметр запроса checksum . go-getter автоматически анализирует этот параметр запроса и использует его для проверки контрольной суммы. Значение параметра может быть в формате type:value или просто value , где тип — «md5», «sha1», «sha256», «sha512» или «file». «Значение» должно быть фактическим значением контрольной суммы или URL-адресом загрузки «файла». Если часть type опущена, тип будет угадываться на основе длины строки контрольной суммы. Примеры:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
При суммировании контрольной суммы из файла — например: с checksum=file:url — go-getter получит файл, указанный в URL-адресе после file: используя ту же конфигурацию. Например, в file:http://releases.ubuntu.com/cosmic/MD5SUMS go-getter загрузит файл контрольной суммы по вышеупомянутому URL-адресу, используя протокол http. Могут использоваться все протоколы, поддерживаемые go-getter. Файл контрольной суммы будет загружен во временный файл, а затем проанализирован. Назначение временного файла можно изменить, установив системные переменные среды: TMPDIR для unix; TMP , TEMP или USERPROFILE в Windows. Прочтите godoc os.TempDir для получения дополнительной информации о выборе временного каталога. Ожидается, что содержимое файлов будет в стиле BSD или GNU. Как только сборщик закончит работу с файлом контрольной суммы; оно удалено.
Параметр запроса контрольной суммы никогда не отправляется в реализацию внутреннего протокола. На более высоком уровне он используется самими предпринимателями.
Если целевой файл существует и контрольные суммы совпадают: загрузка будет пропущена.
go-getter автоматически разархивирует файлы в файл или каталог в зависимости от расширения запрашиваемого файла (по любому протоколу). Это работает как для загрузки файлов, так и для загрузки каталогов.
go-getter ищет параметр запроса archive , чтобы указать формат архива. Если это не указано, go-getter будет использовать расширение пути, чтобы увидеть, отображается ли он в архиве. Разархивирование можно явно отключить, установив для параметра запроса archive значение false .
Поддерживаются следующие форматы архивов:
tar.gz и tgz
tar.bz2 и tbz2
tar.xz и txz
zip
gz
bz2
xz
Например, пример URL-адреса показан ниже:
./foo.zip
Это автоматически будет считаться ZIP-файлом и будет извлечено. Вы также можете явно указать тип архива:
./some/other/path?archive=zip
И, наконец, вы можете полностью отключить архивирование:
./some/path?archive=false
Вы можете комбинировать разархивацию с другими функциями Go-Getter, такими как подсчет контрольных сумм. Специальный параметр запроса archive будет удален из URL-адреса перед переходом к окончательному загрузчику протокола.
В этом разделе описаны параметры протокола, которые можно указать для Go-Getter. Эти параметры следует добавлять к входным данным как обычные параметры запроса (однако заголовки HTTP являются исключением). В зависимости от использования Go-Getter приложения могут предоставлять альтернативные способы ввода параметров. Например, Nomad предоставляет удобный блок параметров для указания параметров, а не в URL-адресе.
Следующие параметры доступны для всех протоколов:
archive — формат архива, используемый для разархивирования этого файла, или «» (пустая строка), чтобы отключить разархивирование. Более подробную информацию см. в полном разделе о поддержке архивов выше.
checksum - Контрольная сумма для проверки загруженного файла или архива. Формат и более подробную информацию см. в разделе о контрольной сумме выше.
filename — в режиме загрузки файла позволяет указать имя загруженного файла на диске. Не имеет эффекта в режиме каталога.
file )Никто
git ) ref — ссылка Git для оформления заказа. Это ссылка, поэтому она может указывать на SHA фиксации, имя ветки и т. д. Если это именованная ссылка, например имя ветки, go-getter будет обновлять ее до последней версии при каждом получении.
sshkey — закрытый ключ SSH, используемый во время клонирования. Предоставленный ключ должен быть строкой в кодировке Base64. Например, чтобы сгенерировать подходящий sshkey из файла закрытого ключа на диске, вы должны запустить base64 -w0 .
Примечание . Для использования этой функции требуется Git 2.3+.
depth — глубина клона Git. Указанное число указывает последние n ревизий, которые нужно клонировать из репозитория.
Геттер git принимает как SSH-адреса в стиле URL, например git::ssh://[email protected]/foo/bar , так и адреса в стиле scp, например git::[email protected]/foo/bar . В последнем случае допускается пропуск префикса git:: force, если префикс имени пользователя равен именно git@ .
Адреса в стиле scp не могут использоваться в сочетании с префиксом схемы ssh:// , поскольку в этом случае двоеточие используется для обозначения дополнительного номера порта для подключения, а не для разграничения пути от хоста.
hg ) rev — версия Mercurial для оформления заказа.
http ) Чтобы использовать базовую аутентификацию HTTP с помощью go-getter, просто добавьте username:password@ к имени хоста в URL-адресе, например https://Aladdin:[email protected]/index.html . Все специальные символы, включая имя пользователя и пароль, должны быть закодированы в URL.
Дополнительные заголовки запроса можно добавить, указав их в пользовательском HttpGetter ( а не в качестве параметров запроса, как большинство других параметров). Эти заголовки будут отправляться при каждом запросе, который делает рассматриваемый геттер.
s3 )S3 использует различные конфигурации доступа в URL-адресе. Обратите внимание, что он также будет считывать их из стандартных переменных среды AWS, если они установлены. Также поддерживаются серверы, совместимые с S3, такие как Minio. Если параметры запроса присутствуют, они имеют приоритет.
aws_access_key_id — ключ доступа к AWS.
aws_access_key_secret — секретный ключ доступа к AWS.
aws_access_token — токен доступа AWS, если он используется.
aws_profile — используйте этот профиль из локальной конфигурации ~/.aws/. Имеет приоритет над остальными тремя.
Если вы используете go-getter и хотите использовать профиль экземпляра EC2 IAM, чтобы избежать использования учетных данных, просто опустите их, и профиль, если он доступен, будет использоваться автоматически.
Если вы используете go-gitter для поддержки Minio, вы должны учитывать следующее:
aws_access_key_id (обязательно) — ключ доступа Minio.
aws_access_key_secret (обязательно) — секретный ключ доступа Minio.
region (необязательно, по умолчанию us-east-1) — идентификатор региона, который нужно использовать.
version (необязательно — по умолчанию используется Minio по умолчанию) — формат файла конфигурации.
S3 имеет несколько схем адресации, используемых для ссылки на вашу корзину. Они перечислены здесь: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html.
Некоторые примеры этих схем адресации:
s3::https://s3.amazonaws.com/bucket/foo
s3::https://s3-eu-west-1.amazonaws.com/bucket/foo
ведро.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 )Для доступа к GCS необходимо предоставить учетные данные аутентификации. Более подробную информацию можно найти здесь
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
Тесты для get_gcs.go требуют, чтобы в вашей среде были установлены учетные данные GCP. Эти учетные данные могут иметь любой уровень разрешений для любого проекта, им просто необходимо существовать. Это означает установку GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" или GOOGLE_CREDENTIALS="{stringified-credentials-json}" . Из-за этой конфигурации get_gcs_test.go не будет работать для внешних участников в CircleCI.
Отключить символические ссылки
В конфигурации вашего клиента-получателя мы рекомендуем использовать опцию DisableSymlinks , которая предотвращает запись или копирование символических ссылок (которые могут указывать за пределы каталога).
client := getter.Client{ // Это предотвратит копирование или запись файлов через символические ссылки DisableSymlinks: true,
} Отключить или ограничить X-Terraform-Get
Go-Getter поддерживает произвольные перенаправления через заголовок X-Terraform-Get . Эта функциональность существует для поддержки вариантов использования Terraform, но, скорее всего, не требуется в большинстве приложений.
Для кода, использующего HttpGetter , добавьте следующие параметры конфигурации:
var httpGetter = &getter.HttpGetter{ // Большинству клиентов следует отключить X-Terraform-Get // См. примечание ниже XTerraformGetDisabled: true, // Вероятно, ваше программное обеспечение не использует X-Terraform-Get, но // если это так , вам следует установить в приведенном выше поле значение false, а также // установить XTerraformGet Limit, чтобы предотвратить бесконечные перенаправления // XTerraformGetLimit: 10,}Принудительное соблюдение тайм-аутов
HttpGetter поддерживает тайм-ауты и другие параметры конфигурации, ограничивающие ресурсы. GitGetter и HgGetter поддерживают только таймауты.
Конфигурация HttpGetter :
var httpGetter = &getter.HttpGetter{ // Отключить запросы HEAD предварительной выборки DoNotCheckHeadFirst: true,
// В качестве альтернативы указанному выше параметру вы можете // установить разумный таймаут для запросов HEAD // HeadFirstTimeout: 10 * time.Second, // Таймаут чтения для HTTP-операций ReadTimeout: 30 * time.Second, // Установить максимальное количество байт, // которое может быть прочитано геттером MaxBytes: 500000000, // 500 МБ} Для кода, использующего GitGetter или HgGetter , установите параметр Timeout :
var gitGetter = &getter.GitGetter{ // Устанавливаем разумный таймаут для операций git. Таймаут: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // Устанавливаем разумный таймаут для операций hg. Таймаут: 5 * time.Minute,
} 
