menjadi giat
1.7.6
go-getter adalah perpustakaan Go (golang) untuk mengunduh file atau direktori dari berbagai sumber menggunakan URL sebagai bentuk masukan utama.
Kekuatan perpustakaan ini adalah fleksibel karena dapat mengunduh dari sejumlah sumber berbeda (jalur file, Git, HTTP, Mercurial, dll.) menggunakan satu string sebagai masukan. Hal ini menghilangkan beban mengetahui cara mengunduh dari berbagai sumber dari pelaksana.
Konsep pendeteksi secara otomatis mengubah URL yang tidak valid menjadi URL yang tepat. Misalnya: "github.com/hashicorp/go-getter" akan berubah menjadi URL Git. Atau "./foo" akan berubah menjadi URL file. Ini dapat diperluas.
Library ini digunakan oleh Terraform untuk mendownload modul dan Nomad untuk mendownload binari.
Dokumentasi paket dapat ditemukan di GoDoc.
Instalasi dapat dilakukan dengan go get biasa :
$ go get github.com/hashicorp/go-getter
go-getter juga memiliki perintah yang dapat Anda gunakan untuk menguji string URL:
$ go install github.com/hashicorp/go-getter/cmd/go-getter ... $ go-getter github.com/foo/bar ./foo ...
Perintah ini berguna untuk memverifikasi struktur URL.
Mengambil sumber daya dari URL yang disediakan pengguna pada dasarnya merupakan operasi yang berbahaya dan dapat membuat aplikasi Anda rentan terhadap pemalsuan permintaan sisi server, traversal jalur, penolakan layanan, atau kelemahan keamanan lainnya.
go-getter berisi mitigasi untuk beberapa masalah keamanan ini, namun tetap harus digunakan dengan hati-hati dalam konteks keamanan kritis. Lihat opsi keamanan yang tersedia yang dapat dikonfigurasi untuk memitigasi beberapa risiko ini.
go-getter dapat mengembalikan nilai yang berisi parameter kueri yang disediakan pemanggil yang dapat berisi data sensitif. Konteks seputar parameter yang sensitif dan tidak sensitif hanya diketahui oleh pemanggil yang giat, dan spesifik untuk setiap kasus penggunaan. Kami merekomendasikan penelepon untuk memastikan bahwa nilai kembalian yang giat (misalnya, pesan kesalahan) ditangani dan dibersihkan dengan benar untuk memastikan data sensitif tidak disimpan dalam log.
go-getter menggunakan URL string tunggal sebagai masukan untuk mengunduh dari berbagai protokol. go-getter memiliki berbagai "trik" dengan URL ini untuk melakukan hal-hal tertentu. Bagian ini mendokumentasikan format URL.
Protokol digunakan untuk mengunduh file/direktori menggunakan mekanisme tertentu. Contoh protokolnya adalah Git dan HTTP.
Detektor digunakan untuk mengubah URL valid atau tidak valid menjadi URL lain jika cocok dengan pola tertentu. Contoh: "github.com/user/repo" secara otomatis diubah menjadi URL Git yang sepenuhnya valid. Hal ini memungkinkan orang yang giat menjadi sangat ramah pengguna.
go-getter out of the box mendukung protokol berikut. Protokol tambahan dapat ditambah pada saat runtime dengan mengimplementasikan antarmuka Getter .
File lokal
Git
Lincah
HTTP
Amazon S3
Google GCP
Selain protokol di atas, go-getter memiliki apa yang disebut "detektor". Ini mengambil URL dan mencoba untuk secara otomatis memilih protokol terbaik untuk itu, yang mungkin melibatkan perubahan protokol. Deteksi berikut sudah ada di dalamnya secara default:
Jalur file seperti "./foo" secara otomatis diubah menjadi URL file absolut.
URL GitHub, seperti "github.com/mitchellh/vagrant" secara otomatis diubah menjadi protokol Git melalui HTTP.
URL GitLab, seperti "gitlab.com/inkscape/inkscape" secara otomatis diubah menjadi protokol Git melalui HTTP.
URL BitBucket, seperti "bitbucket.org/mitchellh/vagrant" secara otomatis diubah menjadi protokol Git atau lincah menggunakan BitBucket API.
Dalam beberapa kasus, protokol yang digunakan bersifat ambigu tergantung pada URL sumber. Misalnya, "http://github.com/mitchellh/vagrant.git" dapat mereferensikan URL HTTP atau URL Git. Sintaks protokol paksa digunakan untuk memperjelas URL ini.
Protokol yang dipaksakan dapat dilakukan dengan mengawali URL dengan protokol diikuti dengan titik dua ganda. Misalnya: git::http://github.com/mitchellh/vagrant.git akan mengunduh URL HTTP yang diberikan menggunakan protokol Git.
Protokol yang dipaksakan juga akan mengesampingkan detektor apa pun.
Jika tidak ada protokol yang dipaksakan, detektor dapat dijalankan pada URL, sehingga mengubah protokol tersebut. Contoh di atas akan menggunakan protokol Git karena detektor Git akan mendeteksi bahwa itu adalah URL GitHub.
Setiap protokol dapat mendukung opsi khusus protokol untuk mengonfigurasi protokol tersebut. Misalnya, protokol git mendukung penentuan parameter kueri ref yang memberi tahu ref apa yang harus diperiksa untuk repositori Git tersebut.
Opsi ditentukan sebagai parameter kueri pada URL (atau string mirip URL) yang diberikan kepada orang yang giat. Dengan menggunakan contoh Git di atas, URL di bawah ini adalah masukan yang valid untuk orang yang giat:
github.com/hashicorp/go-getter?ref=abcd1234
Opsi khusus protokol didokumentasikan di bawah bagian format URL. Namun karena mereka adalah bagian dari URL, kami tunjukkan di sini sehingga Anda tahu bahwa mereka ada.
Jika Anda hanya ingin mengunduh subdirektori tertentu dari direktori yang diunduh, Anda dapat menentukan subdirektori setelah garis miring ganda // . go-getter pertama-tama akan mengunduh URL yang ditentukan sebelum garis miring ganda (seolah-olah Anda tidak menentukan garis miring ganda), tetapi kemudian akan menyalin jalur setelah garis miring ganda ke direktori target.
Misalnya, jika Anda mengunduh repositori GitHub ini, tetapi Anda hanya ingin mengunduh direktori testdata , Anda dapat melakukan hal berikut:
https://github.com/hashicorp/go-getter.git//testdata
Jika Anda mengunduh ini ke direktori /tmp , maka file /tmp/archive.gz akan ada. Perhatikan bahwa file ini ada di direktori testdata dalam repositori ini, tetapi karena kita menentukan subdirektori, go-getter secara otomatis hanya menyalin isi direktori tersebut.
Jalur subdirektori juga dapat menggunakan pola glob sistem file. Jalur harus cocok dengan satu entri atau orang yang giat akan mengembalikan kesalahan. Ini berguna jika Anda tidak yakin dengan nama direktori sebenarnya tetapi mengikuti struktur penamaan yang dapat diprediksi.
Misalnya, URL berikut juga bisa digunakan:
https://github.com/hashicorp/go-getter.git//test-*
Untuk pengunduhan file dengan protokol apa pun, go-getter dapat secara otomatis memverifikasi checksum untuk Anda. Perhatikan bahwa checksumming hanya berfungsi untuk mengunduh file, bukan direktori, tetapi checksumming akan berfungsi untuk protokol apa pun.
Untuk memeriksa file, tambahkan parameter kueri checksum ke URL. go-getter akan menguraikan parameter kueri ini secara otomatis dan menggunakannya untuk memverifikasi checksum. Nilai parameter dapat dalam format type:value atau hanya value , dengan tipe "md5", "sha1", "sha256", "sha512" atau "file" . "Nilai" harus berupa nilai checksum sebenarnya atau URL unduhan untuk "file". Ketika bagian type dihilangkan, tipe akan ditebak berdasarkan panjang string checksum. Contoh:
./foo.txt?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=b7d96c89d09d9e204f5fedc4d5d55b21
./foo.txt?checksum=file:./foo.txt.sha256sum
Saat melakukan checksum dari suatu file - misal: dengan checksum=file:url - go-getter akan membuat file tertaut di URL setelah file: menggunakan konfigurasi yang sama. Misalnya, dalam file:http://releases.ubuntu.com/cosmic/MD5SUMS go-getter akan mengunduh file checksum di bawah url yang disebutkan di atas menggunakan protokol http. Semua protokol yang didukung oleh go-getter dapat digunakan. File checksum akan diunduh dalam file sementara kemudian diurai. Tujuan dari file sementara dapat diubah dengan mengatur variabel lingkungan spesifik sistem: TMPDIR untuk unix; TMP , TEMP atau USERPROFILE di windows. Baca godoc dari os.TempDir untuk informasi lebih lanjut tentang pemilihan direktori sementara. Konten file diharapkan bergaya BSD atau GNU. Setelah giat selesai dengan file checksum; itu dihapus.
Parameter kueri checksum tidak pernah dikirim ke implementasi protokol backend. Ini digunakan pada tingkat yang lebih tinggi oleh orang yang giat itu sendiri.
Jika file tujuan ada dan checksumnya cocok: pengunduhan akan dilewati.
go-getter akan secara otomatis membatalkan pengarsipan file ke dalam file atau direktori berdasarkan ekstensi file yang diminta (melalui protokol apa pun). Ini berfungsi untuk pengunduhan file dan direktori.
go-getter mencari parameter kueri archive untuk menentukan format arsip. Jika ini tidak ditentukan, orang yang giat akan menggunakan ekstensi jalur untuk melihat apakah jalur tersebut tampak diarsipkan. Pembatalan pengarsipan dapat dinonaktifkan secara eksplisit dengan mengatur parameter kueri archive ke false .
Format arsip berikut ini didukung:
tar.gz dan tgz
tar.bz2 dan tbz2
tar.xz dan txz
zip
gz
bz2
xz
Misalnya, contoh URL ditunjukkan di bawah ini:
./foo.zip
Ini secara otomatis akan disimpulkan sebagai file ZIP dan akan diekstraksi. Anda juga bisa menjelaskan secara eksplisit tentang jenis arsip:
./some/other/path?archive=zip
Dan terakhir, Anda dapat menonaktifkan pengarsipan sepenuhnya:
./some/path?archive=false
Anda dapat menggabungkan pembatalan pengarsipan dengan fitur go-getter lainnya seperti checksumming. Parameter kueri archive khusus akan dihapus dari URL sebelum menuju ke pengunduh protokol akhir.
Bagian ini mendokumentasikan opsi khusus protokol yang dapat ditentukan untuk orang yang giat. Opsi ini harus ditambahkan ke input sebagai parameter kueri normal (namun, header HTTP merupakan pengecualian). Tergantung pada penggunaan go-getter, aplikasi mungkin menyediakan cara alternatif untuk memasukkan opsi. Misalnya, Nomad menyediakan blok opsi yang bagus untuk menentukan opsi, bukan di URL.
Opsi di bawah ini tersedia untuk semua protokol:
archive - Format arsip yang digunakan untuk membatalkan pengarsipan file ini, atau "" (string kosong) untuk menonaktifkan pembatalan pengarsipan. Untuk lebih jelasnya, lihat bagian lengkap tentang dukungan arsip di atas.
checksum - Checksum untuk memverifikasi file atau arsip yang diunduh. Lihat seluruh bagian checksumming di atas untuk format dan detail lebih lanjut.
filename - Saat dalam mode unduh file, memungkinkan menentukan nama file yang diunduh pada disk. Tidak berpengaruh dalam mode direktori.
file )Tidak ada
git ) ref - Referensi Git untuk checkout. Ini adalah ref, sehingga dapat menunjuk ke SHA komit, nama cabang, dll. Jika ini adalah ref bernama seperti nama cabang, go-getter akan memperbaruinya ke yang terbaru pada setiap get.
sshkey - Kunci pribadi SSH untuk digunakan selama kloning. Kunci yang diberikan harus berupa string berkode base64. Misalnya, untuk menghasilkan sshkey yang sesuai dari file kunci pribadi di disk, Anda akan menjalankan base64 -w0 .
Catatan : Git 2.3+ diperlukan untuk menggunakan fitur ini.
depth - Kedalaman klon Git. Nomor yang diberikan menentukan n revisi terakhir yang akan dikloning dari repositori.
Pengambil git menerima alamat SSH bergaya URL seperti git::ssh://[email protected]/foo/bar , dan alamat "scp-style" seperti git::[email protected]/foo/bar . Dalam kasus terakhir, menghilangkan awalan git:: force diperbolehkan jika awalan nama pengguna sama persis dengan git@ .
Alamat "scp-style" tidak dapat digunakan bersama dengan awalan skema ssh:// , karena dalam hal ini titik dua digunakan untuk menandai nomor port opsional untuk dihubungkan, bukan untuk membatasi jalur dari host.
hg ) rev - Revisi Mercurial untuk checkout.
http ) Untuk menggunakan otentikasi dasar HTTP dengan go-getter, cukup tambahkan username:password@ ke nama host di URL seperti https://Aladdin:[email protected]/index.html . Semua karakter khusus, termasuk nama pengguna dan kata sandi, harus dikodekan dengan URL.
Header permintaan opsional dapat ditambahkan dengan menyediakannya dalam HttpGetter khusus ( bukan sebagai parameter kueri seperti kebanyakan opsi lainnya). Header ini akan dikirim pada setiap permintaan yang dibuat oleh pengambil tersebut.
s3 )S3 mengambil berbagai konfigurasi akses di URL. Perhatikan bahwa ia juga akan membacanya dari variabel lingkungan AWS standar jika disetel. Server yang mendukung S3 seperti Minio juga didukung. Jika parameter kueri ada, parameter ini akan diprioritaskan.
aws_access_key_id - Kunci akses AWS.
aws_access_key_secret - Rahasia kunci akses AWS.
aws_access_token - Token akses AWS jika ini sedang digunakan.
aws_profile - Gunakan profil ini dari ~/.aws/ config lokal. Menjadi prioritas dibandingkan tiga lainnya.
Jika Anda menggunakan go-getter dan ingin menggunakan Profil Instans IAM EC2 untuk menghindari penggunaan kredensial, hilangkan saja kredensial ini dan profil tersebut, jika tersedia akan digunakan secara otomatis.
Jika Anda menggunakan go-gitter untuk dukungan Minio, Anda harus mempertimbangkan hal berikut:
aws_access_key_id (wajib) - Kunci akses Minio.
aws_access_key_secret (wajib) - Rahasia kunci akses Minio.
region (opsional - defaultnya adalah us-east-1) - Pengidentifikasi wilayah yang akan digunakan.
version (opsional - default ke Minio default) - Format file konfigurasi.
S3 memiliki beberapa skema pengalamatan yang digunakan untuk mereferensikan bucket Anda. Ini tercantum di sini: https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-bucket-intro.html
Beberapa contoh skema pengalamatan ini:
s3::https://s3.amazonaws.com/bucket/foo
s3::https://s3-eu-west-1.amazonaws.com/bucket/foo
ember.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 )Untuk mengakses GCS, kredensial autentikasi harus diberikan. Informasi lebih lanjut dapat ditemukan di sini
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
Pengujian untuk get_gcs.go mengharuskan Anda menyetel kredensial GCP di lingkungan Anda. Kredensial ini dapat memiliki tingkat izin apa pun untuk proyek apa pun, kredensial tersebut hanya perlu ada. Ini berarti menyetel GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" atau GOOGLE_CREDENTIALS="{stringified-credentials-json}" . Karena konfigurasi ini, get_gcs_test.go akan gagal untuk kontributor eksternal di CircleCI.
Nonaktifkan Symlink
Dalam konfigurasi klien pengambil Anda, sebaiknya gunakan opsi DisableSymlinks , yang mencegah penulisan atau penyalinan dari symlink (yang mungkin mengarah ke luar direktori).
client := getter.Client{ // Ini akan mencegah penyalinan atau penulisan file melalui symlinks DisableSymlinks: true,
} Nonaktifkan atau Batasi X-Terraform-Get
Go-Getter mendukung pengalihan sewenang-wenang melalui header X-Terraform-Get . Fungsionalitas ini ada untuk mendukung kasus penggunaan Terraform, tetapi mungkin tidak diperlukan di sebagian besar aplikasi.
Untuk kode yang menggunakan HttpGetter , tambahkan opsi konfigurasi berikut:
var httpGetter = &getter.HttpGetter{ // Kebanyakan klien harus menonaktifkan X-Terraform-Get // Lihat catatan di bawah XTerraformGetDisabled: true, // Perangkat lunak Anda mungkin tidak bergantung pada X-Terraform-Get, tapi // jika ya , Anda harus menyetel kolom di atas ke false, ditambah // menyetel XTerraformGet Limit untuk mencegah pengalihan tanpa akhir // XTerraformGetLimit: 10,}Terapkan Batas Waktu
HttpGetter mendukung batas waktu dan opsi konfigurasi yang membatasi sumber daya lainnya. GitGetter dan HgGetter hanya mendukung batas waktu.
Konfigurasi untuk HttpGetter :
var httpGetter = &getter.HttpGetter{ // Nonaktifkan permintaan HEAD pra-pengambilan DoNotCheckHeadFirst: true,
// Sebagai alternatif dari pengaturan di atas, Anda dapat // menetapkan batas waktu yang masuk akal untuk permintaan HEAD // HeadFirstTimeout: 10 * time.Second, // Batas waktu baca untuk operasi HTTP ReadTimeout: 30 * time.Second, // Atur waktu jumlah byte maksimum // yang dapat dibaca oleh pengambil MaxBytes: 500000000, // 500 MB} Untuk kode yang menggunakan GitGetter atau HgGetter , atur opsi Timeout :
var gitGetter = &getter.GitGetter{ // Tetapkan batas waktu yang wajar untuk operasi git Batas Waktu: 5 * waktu.Menit,
} var hgGetter = &getter.HgGetter{ // Tetapkan batas waktu yang masuk akal untuk operasi hg Timeout: 5 * time.Minute,
} 
