أشجار الأدلة
كثيرًا ما يحتاج وكيل النشر أو مهمة CI إلى دليل كامل: نسخة بناء للعبة، أو مجموعة أدوات، أو شجرة إعدادات. ينشر arkvoryctl tree الدليل بوصفه مُخرَج ZIP واحدًا، ويجلبه إلى مجلد، ويفحص مجلدًا بمقارنته به، ويصلح الملفات المختلفة فقط. المُخرَج ملف ZIP عادي: تقرؤه وحدة التحكم وAPI وأي أداة ZIP، وتحتفظ به النسخ الاحتياطية مثل أي مُخرَج آخر.
هذه الأوامر جزء من النواة المجانية. وتحتاج إلى الأذونات نفسها التي يحتاجها الرفع والتنزيل: راجع الرفع والتنزيل.
نشر دليل
arkvoryctl tree push ./Build/Game --name game-1.4.zip --label release| الخيار | المعنى |
|---|---|
--name NAME.zip | اسم المُخرَج. الافتراضي: اسم المجلد مع .zip. يجب أن ينتهي الاسم بـ .zip. |
--label TAG | تسمية للمُخرَج |
--file METADATA.json | التسميات وبيانات التعريف، كما في upload |
--compress | ضغط الإدخالات (deflate). ودونه تُخزَّن الملفات كما هي. |
تعرض النتيجة id المُخرَج وsize وsha256 وعدد الملفات في entries.
- المجلد نفسه يعطي الأرشيف نفسه. تُرتَّب الملفات حسب المسار، ويحمل كل إدخال التاريخ 1980-01-01، ولا تُحفظ إلا خاصية واحدة من نظام الملفات: الملف الذي يستطيع مالكه تنفيذه يحصل على الوضع 755، وكل ملف آخر على 644. ودفع مجلد لم يتغير مرة أخرى يعطي البايتات نفسها وSHA-256 نفسه.
- الانقطاعات. يُبنى الأرشيف بجوار المجلد (
.<folder>.arkvory-tree.zip) ويُرفع على أجزاء مع نقطة تحقق. بعد Ctrl+C أو عطل في الشبكة، شغّل الأمر نفسه مرة أخرى: فهو يبني الأرشيف نفسه ويستأنف الرفع. ويُحذف الملفان بعد النجاح. - ما يُرفض. الروابط الرمزية ونقاط الوصل (junctions) والأجهزة والأنابيب داخل المجلد (
tree_entry_unsupported)، والأسماء التي لا يقبلها Windows (unsafe_name)، واسمان لا يختلفان إلا في حالة الأحرف (case_collision). ولا تُحفظ المجلدات الفارغة. - مخزَّن أو مضغوط. دون
--compressتكون بايتات كل ملف نطاقًا متصلًا من الأرشيف. وعندها يستطيع الخادم تقديم ملف واحد بنطاق بايتات، وتنقل عمليات الإصلاح بايتات الملفات المختلفة فقط بالضبط. ومع--compressيكون الأرشيف أصغر، ويُفك ضغط الملف المُصلَح على جهازك.
جلب دليل
arkvoryctl tree pull 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game- المجلد الفارغ أو غير الموجود يحصل على الأرشيف كاملًا. يُنزَّل الأرشيف بجوار المجلد مع نقاط تحقق، لذا يُستأنف الجلب المنقطع من حيث توقف. وبعد التحقق من SHA-256 الخاص به، تُستخرج الملفات إلى مجلد جديد بجوار الهدف، ثم يحل هذا المجلد محل الهدف.
- المجلد الذي فيه ملفات يصبح مطابقًا للشجرة. عندما يملك الخادم جدول المحتويات، لا تُنزَّل إلا الملفات المختلفة، كل منها بنطاق بايتاته، وتُحذف الملفات غير الموجودة في الشجرة. ودون جدول المحتويات يُنزَّل الأرشيف كاملًا، ويحل المجلد المستخرج محل المجلد القديم.
يجب أن يكون المجلد الأب موجودًا. يُستبدل الملف داخل الهدف في خطوة واحدة: يُكتب إلى ملف مؤقت بجواره، ثم يُفحص، ثم يُعاد تسميته. والبرنامج الذي يقرأ الملف يرى إما الإصدار القديم أو الجديد.
فحص دليل
arkvoryctl tree verify 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Gameتسرد النتيجة الملفات missing (المفقودة)، والملفات mismatched (بحجم آخر أو SHA-256 آخر)، والملفات extra (الزائدة) غير الموجودة في الشجرة، مع أعدادها في counts. تعرض كل قائمة 1000 مسار على الأكثر. تكون ok مساوية لـ true عندما لا يكون هناك ملف مفقود أو مختلف؛ والملفات الزائدة لا تغيّرها. رمز الخروج 0 عندما تكون ok مساوية لـ true، و5 في غير ذلك.
إصلاح دليل
arkvoryctl tree repair 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Gameيعيد الإصلاح كتابة كل ملف مفقود أو مختلف، ويُبقي الملفات الزائدة. ومع جدول المحتويات لا يُنزّل إلا إدخالات تلك الملفات؛ ويبيّن fetchedBytes في النتيجة عدد البايتات التي قرأها من الأرشيف. ودونه يُنزّل الأرشيف كاملًا أولًا.
جدول المحتويات
بعد نشر أرشيف، يقرؤه العامل (worker) في الخادم مرة واحدة ويسجّل كل ملف: مساره وحجمه وSHA-256 الخاص به وموضع بايتاته في الأرشيف. يحدث هذا للمُخرَجات التي ينتهي اسمها بـ .zip أو .upack. وإلى أن ينتهي ذلك، أو عندما يتعذر فهرسة الأرشيف، تعمل الأوامر بالأرشيف كاملًا بدلًا منه.
الخادم الذي يملك جدول المحتويات يقدّم zip-tree في tree من GET /api/v1/capabilities (راجع arkvoryctl doctor)؛ ومع خادم أقدم تستخدم الأوامر الأرشيف كاملًا. وجدول المحتويات نفسه هو العملية getArtifactTree: تكون status إما ready أو pending أو unavailable مع reason.
reason | المعنى |
|---|---|
not_archive | اسم المُخرَج لا ينتهي بـ .zip أو .upack |
invalid_archive | الملف ليس أرشيف ZIP قابلًا للقراءة |
unsafe_entry | مسار يخرج من الأرشيف، أو إدخال هو رابط أو ملف خاص |
encrypted_entry | إدخال مشفّر |
duplicate_entry | لإدخالين المسار نفسه، ولو عند تجاهل حالة الأحرف |
unsupported_method | إدخال يستخدم طريقة ضغط غير stored أو deflate |
crc_mismatch | بايتات إدخال لا تطابق مجموعه الاختباري في الأرشيف |
too_many_entries | أكثر من 100,000 إدخال |
too_large | أكثر من 100 GiB بعد فك الضغط |
كيف تُفحص الملفات
- يُتحقق من كل ملف قبل أن يأخذ مكانه. مع جدول المحتويات يجب أن يطابق حجمه وSHA-256 الخاص به القيمَ التي حسبها الخادم من الأرشيف المنشور. ودونه يُتحقق أولًا من SHA-256 للأرشيف كله، ثم من حجم كل ملف وCRC-32 الخاص به. وعدم التطابق يوقف الأمر بالرمز
checksum_mismatch(رمز الخروج 5)، ويبقى الملف في المجلد كما كان. - لا يُكتب شيء خارج المجلد. تُقرأ المسارات من الأرشيف ومن الخادم بوصفها بيانات غير موثوقة. والمسار الذي يخرج من المجلد يُرفض بالرمز
path_outside_root. ولا يُتبع أبدًا رابط داخل المجلد يقع في الطريق إلى ملف. والأسماء التي لا يقبلها Windows (CONوaux.txtوa:b، ونقطة أو مسافة في النهاية) تُرفض بالرمزunsafe_nameعلى كل نظام، لكي تعني الشجرة الشيء نفسه على Windows وLinux. - الأوضاع. الملف المستخرج من الأرشيف يحصل على الوضع 755 إذا وسمه الأرشيف قابلًا للتنفيذ، وإلا فعلى 644 (Linux وmacOS). والملف المُصلَح بنطاق بايتات يحتفظ بوضع الملف الذي يحل محله.
نقل أسرع
يمر رفع الأرشيف كاملًا في tree push وتنزيله كاملًا في tree pull عبر النقل نفسه الذي يستخدمه upload وdownload. ويمكن لوحدة عميل فيها امتداد نقل أن تتولاهما عندما يقدّم الخادم الامتداد نفسه؛ ويبقى الأرشيف ملف ZIP عاديًا، ويُفحص SHA-256 الخاص به وكل ملف كما هو موضح أعلاه. ودون وحدة، أو عندما لا يقدّم الخادم الامتداد، يستخدم arkvoryctl النقل الخاص به.