डायरेक्टरी ट्री

किसी डिप्लॉयमेंट एजेंट या 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। बिना बदले फ़ोल्डर को फिर से push करने पर वही बाइट और वही SHA-256 मिलते हैं।
• रुकावटें। आर्काइव फ़ोल्डर के बगल में (.<folder>.arkvory-tree.zip) बनाया जाता है और चेकपॉइंट के साथ भागों में अपलोड होता है। Ctrl+C या नेटवर्क विफलता के बाद वही कमांड फिर से चलाएँ: वह वही आर्काइव बनाती है और अपलोड जारी रखती है। सफलता के बाद दोनों फ़ाइलें हटा दी जाती हैं।
• क्या अस्वीकार होता है। फ़ोल्डर के अंदर सिंबॉलिक लिंक, जंक्शन, डिवाइस और पाइप (tree_entry_unsupported), वे नाम जिन्हें Windows नहीं रख सकता (unsafe_name), और ऐसे दो नाम जो केवल अक्षरों के केस में अलग हैं (case_collision)। खाली फ़ोल्डर नहीं रखे जाते।
• संग्रहीत या संपीड़ित। --compress के बिना, हर फ़ाइल के बाइट आर्काइव की एक लगातार रेंज होते हैं। तब सर्वर एक फ़ाइल को बाइट रेंज से दे सकता है, और सुधार ठीक उन्हीं फ़ाइलों के बाइट ले जाते हैं जो अलग हैं। --compress के साथ आर्काइव छोटा होता है और सुधारी गई फ़ाइल आपकी मशीन पर डीकंप्रेस की जाती है।

डायरेक्टरी लाएँ

arkvoryctl tree pull 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game

• खाली या मौजूद न रहने वाले फ़ोल्डर को पूरा आर्काइव मिलता है। वह चेकपॉइंट के साथ फ़ोल्डर के बगल में डाउनलोड होता है, इसलिए रुका हुआ pull वहीं से जारी रहता है जहाँ रुका था। उसका SHA-256 सत्यापित होने के बाद फ़ाइलें लक्ष्य के बगल में एक नए फ़ोल्डर में निकाली जाती हैं, जो फिर लक्ष्य की जगह ले लेता है।
• फ़ाइलों वाला फ़ोल्डर ट्री जैसा बन जाता है। जब सर्वर के पास विषय-सूची होती है, तो केवल अलग फ़ाइलें डाउनलोड होती हैं, हर एक अपनी बाइट रेंज से, और जो फ़ाइलें ट्री में नहीं हैं वे हटा दी जाती हैं। विषय-सूची के बिना पूरा आर्काइव डाउनलोड होता है, और निकाला गया फ़ोल्डर पुराने की जगह ले लेता है।

पैरेंट फ़ोल्डर मौजूद होना चाहिए। लक्ष्य के अंदर की फ़ाइल एक ही चरण में बदली जाती है: वह बगल की एक अस्थायी फ़ाइल में लिखी जाती है, जाँची जाती है और उसका नाम बदला जाता है। फ़ाइल पढ़ने वाला प्रोग्राम या तो पुराना संस्करण देखता है या नया।

डायरेक्टरी जाँचें

arkvoryctl tree verify 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game

परिणाम missing (गायब) फ़ाइलें, mismatched (अलग आकार या अलग SHA-256 वाली) फ़ाइलें और वे extra (अतिरिक्त) फ़ाइलें सूचीबद्ध करता है जो ट्री में नहीं हैं, और उनकी संख्या counts में होती है। हर सूची अधिकतम 1000 पथ दिखाती है। जब कुछ गायब या अलग न हो तो ok का मान true होता है; अतिरिक्त फ़ाइलें इसे नहीं बदलतीं। ok true होने पर एग्ज़िट कोड 0 होता है, अन्यथा 5।

डायरेक्टरी ठीक करें

arkvoryctl tree repair 3b0c0b8e-6a4e-4f5f-9d3b-5a6c1c9b0f11 ./Game

सुधार हर गायब और अलग फ़ाइल को फिर से लिखता है और अतिरिक्त फ़ाइलें रहने देता है। विषय-सूची होने पर वह केवल उन्हीं फ़ाइलों की प्रविष्टियाँ डाउनलोड करता है; परिणाम में fetchedBytes बताता है कि उसने आर्काइव के कितने बाइट पढ़े। विषय-सूची के बिना वह पहले पूरा आर्काइव डाउनलोड करता है।

विषय-सूची

आर्काइव प्रकाशित होने के बाद सर्वर का वर्कर उसे एक बार पढ़ता है और हर फ़ाइल दर्ज करता है: उसका पथ, आकार, SHA-256 और आर्काइव में उसके बाइट कहाँ हैं। यह उन आर्टिफ़ैक्ट के लिए होता है जिनका नाम .zip या .upack पर समाप्त होता है। जब तक यह पूरा न हो, या जब आर्काइव का इंडेक्स न बन सके, तब तक कमांड इसके बजाय पूरे आर्काइव के साथ काम करती हैं।

जिस सर्वर के पास विषय-सूची होती है, वह GET /api/v1/capabilities के tree में zip-tree देता है (arkvoryctl doctor देखें); पुराने सर्वर के साथ कमांड पूरा आर्काइव इस्तेमाल करती हैं। विषय-सूची स्वयं ऑपरेशन getArtifactTree है: status का मान ready, pending या reason के साथ unavailable होता है।

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 मिलता है यदि आर्काइव उसे executable चिह्नित करता है, अन्यथा 644 (Linux और macOS)। रेंज से सुधारी गई फ़ाइल उस फ़ाइल का मोड रखती है जिसकी जगह वह लेती है।

तेज़ ट्रांसफ़र

tree push का पूरा-आर्काइव अपलोड और tree pull का पूरा-आर्काइव डाउनलोड उसी ट्रांसफ़र से होते हैं जिससे upload और download। जब सर्वर वही एक्सटेंशन देता है, तो ट्रांसफ़र एक्सटेंशन वाला क्लाइंट मॉड्यूल इन्हें संभाल सकता है; आर्काइव साधारण ZIP ही रहता है, और उसका SHA-256 और हर फ़ाइल ऊपर बताए अनुसार जाँची जाती है। मॉड्यूल के बिना, या जब सर्वर उसे नहीं देता, arkvoryctl अपना ट्रांसफ़र इस्तेमाल करता है।

संबंधित पेज

• अपलोड और डाउनलोड
• कमांड लाइन
• आर्टिफ़ैक्ट API