go getter
1.7.6
go-getter هي مكتبة لـ Go (golang) لتنزيل الملفات أو الدلائل من مصادر مختلفة باستخدام عنوان URL كشكل أساسي للإدخال.
تكمن قوة هذه المكتبة في كونها مرنة في قدرتها على التنزيل من عدد من المصادر المختلفة (مسارات الملفات، Git، HTTP، Mercurial، إلخ) باستخدام سلسلة واحدة كمدخل. وهذا يزيل عبء معرفة كيفية التنزيل من مجموعة متنوعة من المصادر من جهة التنفيذ.
يقوم مفهوم الكاشف تلقائيًا بتحويل عناوين URL غير الصالحة إلى عناوين 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 out of the box البروتوكولات التالية. يمكن زيادة البروتوكولات الإضافية في وقت التشغيل من خلال تنفيذ واجهة Getter .
الملفات المحلية
بوابة
زئبقي
HTTP
أمازون إس 3
جوجل جي سي بي
بالإضافة إلى البروتوكولات المذكورة أعلاه، يمتلك 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 أو بروتوكول زئبقي باستخدام واجهة برمجة تطبيقات 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 أدناه إدخالاً صالحًا للبدء:
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 تلقائيًا بنسخ محتويات هذا الدليل فقط.
قد تستخدم مسارات الدليل الفرعي أيضًا أنماطًا عالمية لنظام الملفات. يجب أن يتطابق المسار مع إدخال واحد بالضبط وإلا فسيُرجع go-getter خطأً. يعد هذا مفيدًا إذا لم تكن متأكدًا من اسم الدليل الدقيق ولكنه يتبع بنية تسمية يمكن التنبؤ بها.
على سبيل المثال، قد يعمل عنوان URL التالي أيضًا:
https://github.com/hashicorp/go-getter.git//test-*
بالنسبة لتنزيلات الملفات لأي بروتوكول، يمكن لـ go-getter التحقق تلقائيًا من المجموع الاختباري لك. لاحظ أن الجمع الاختباري يعمل فقط لتنزيل الملفات، وليس الدلائل، ولكن الجمع الاختباري يعمل مع أي بروتوكول.
للمجموع الاختباري لملف، قم بإلحاق معلمة استعلام checksum بعنوان URL. سيقوم 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 على النوافذ. اقرأ godoc of os.TempDir لمزيد من المعلومات حول اختيار الدليل المؤقت. من المتوقع أن يكون محتوى الملفات على نمط BSD أو GNU. بمجرد الانتهاء من استخدام ملف المجموع الاختباري؛ يتم حذفه.
لا يتم إرسال معلمة استعلام المجموع الاختباري مطلقًا إلى تطبيق بروتوكول الواجهة الخلفية. يتم استخدامه على مستوى أعلى بواسطة go-getter نفسه.
إذا كان الملف الوجهة موجودًا وتطابق المجموع الاختباري: فسيتم تخطي التنزيل.
سيقوم 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 خاص لاستخدامه أثناء النسخ. يجب أن يكون المفتاح المقدم عبارة عن سلسلة مشفرة بالأساس 64. على سبيل المثال، لإنشاء مفتاح sshkey مناسب من ملف مفتاح خاص على القرص، يمكنك تشغيل base64 -w0 <file> .
ملحوظة : مطلوب Git 2.3+ لاستخدام هذه الميزة.
depth - عمق استنساخ Git. يحدد الرقم المقدم آخر n المراجعات التي سيتم استنساخها من المستودع.
يقبل git getter عناوين SSH على نمط URL مثل git::ssh://[email protected]/foo/bar وعناوين "scp-style" مثل git::[email protected]/foo/bar . في الحالة الأخيرة، يُسمح بحذف بادئة git:: force إذا كانت بادئة اسم المستخدم هي git@ .
لا يمكن استخدام عناوين "نمط scp" مع بادئة المخطط ssh:// ، لأنه في هذه الحالة يتم استخدام النقطتين لتحديد رقم منفذ اختياري للاتصال به، بدلاً من تحديد المسار من المضيف.
hg ) rev - المراجعة الزئبقية للخروج.
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
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 )من أجل الوصول إلى 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 تعيين بيانات اعتماد Google Cloud Platform في بيئتك. يمكن أن تحتوي بيانات الاعتماد هذه على أي مستوى من الأذونات لأي مشروع، فهي تحتاج فقط إلى أن تكون موجودة. وهذا يعني تعيين GOOGLE_APPLICATION_CREDENTIALS="~/path/to/credentials.json" أو GOOGLE_CREDENTIALS="{stringified-credentials-json}" . بسبب هذا التكوين، سيفشل get_gcs_test.go بالنسبة للمساهمين الخارجيين في CircleCI.
تعطيل الارتباطات الرمزية
في تكوين عميل getter الخاص بك، نوصي باستخدام خيار DisableSymlinks ، الذي يمنع الكتابة من خلال الروابط الرمزية أو النسخ منها (والتي قد تشير إلى خارج الدليل).
العميل := getter.Client{ // هذا سيمنع نسخ الملفات أو كتابتها من خلال الروابط الرمزية DisableSymlinks: true،
} تعطيل أو تقييد X-Terraform-Get
يدعم Go-Getter عمليات إعادة التوجيه التعسفية عبر رأس X-Terraform-Get . توجد هذه الوظيفة لدعم حالات استخدام Terraform، ولكن من المحتمل ألا تكون مطلوبة في معظم التطبيقات.
بالنسبة للتعليمات البرمجية التي تستخدم HttpGetter ، قم بإضافة خيارات التكوين التالية:
var httpGetter = &getter.HttpGetter{ // يجب على معظم العملاء تعطيل X-Terraform-Get // راجع الملاحظة أدناه XTerraformGetDisabled: صحيح، // ربما لا يعتمد برنامجك على X-Terraform-Get، ولكن // إذا كان يعتمد عليه ، يجب عليك ضبط الحقل أعلاه على خطأ، بالإضافة إلى // تعيين حد XTerraformGet لمنع عمليات إعادة التوجيه التي لا نهاية لها // XTerraformGetLimit: 10,}فرض المهلات
يدعم HttpGetter المهلات وخيارات التكوين الأخرى المقيدة للموارد. يدعم GitGetter و HgGetter المهلات فقط.
تكوين HttpGetter :
var httpGetter = &getter.HttpGetter{ // تعطيل طلبات HEAD الجلب المسبق DoNotCheckHeadFirst: صحيح،
// كبديل للإعداد أعلاه، يمكنك // تعيين مهلة معقولة لطلبات HEAD // HeadFirstTimeout: 10 * time.Second، // مهلة القراءة لعمليات HTTP ReadTimeout: 30 * time.Second، // تعيين الحد الأقصى لعدد البايتات // التي يمكن قراءتها بواسطة برنامج getter MaxBytes: 500000000، // 500 ميجابايت} بالنسبة للتعليمات البرمجية التي تستخدم GitGetter أو HgGetter ، قم بتعيين خيار Timeout :
var gitGetter = &getter.GitGetter{ // تعيين مهلة معقولة لعمليات git Timeout: 5 * time.Minute,
} var hgGetter = &getter.HgGetter{ // تعيين مهلة معقولة لعمليات hg المهلة: 5 * time.Minute,
} 
