مواصفات مستودع VEX الإصدار 0.1

• مواصفات مستودع VEX الإصدار 0.1
  • 1. ترقيم الإصدارات
  • 2. بيان المستودع
    • 2.1 نظرة عامة
    • 2.2 موقع الملف
    • 2.3 المخطط
    • 2.4 مثال
    • 2.5 أوصاف الحقول وملاحظات الاستخدام
      • الحقول الرئيسية
      • الحقول الفرعية للإصدارات
      • الحقول الفرعية للمواقع
  • 3. بنية المستودع
    • 3.1 بنية الملفات
    • 3.2 index.json
    • 3.3 مستندات VEX
    • 3.4 ملاحظات الاستخدام
      • بنية الدليل
      • محتوى مستند VEX
    • 3.5 تحديث المستودع
  • 4. توزيع المستودع
    • 4.1 نظرة عامة
    • 4.2 صيغة الأرشيف
  • 5. إرشادات تنفيذ العميل
    • 5.1 اختيار الإصدار
    • 5.2 اختيار الموقع
    • 5.3 دعم مستودعات متعددة
      • أولوية المستودعات
    • 5.4 التحقق من التحديثات
    • 5.5 استراتيجيات الكفاءة

يجب تفسير الكلمات المفتاحية "MUST" و"MUST NOT" و"REQUIRED" و"SHALL" و"SHALL NOT" و"SHOULD" و"SHOULD NOT" و"RECOMMENDED" و"MAY" و"OPTIONAL" الواردة في هذا المستند كما هو موصوف في RFC 2119.

1. ترقيم الإصدارات

• يجب أن تستخدم مواصفات مستودع VEX (تبادل قابلية استغلال الثغرات) ترقيم إصدارات بصيغة vX.Y.
• بالنسبة للإصدار v1.0 والإصدارات الأحدث:
  • يجب تحديث X (الإصدار الرئيسي) عند حدوث تغييرات جذرية (breaking changes).
  • يجب تحديث Y (الإصدار الثانوي) عند حدوث تغييرات متوافقة مع الإصدارات السابقة.
• بالنسبة لإصدارات v0.Y، قد تحدث تغييرات جذرية مع تحديثات الإصدار الثانوي.

عند مقارنة الإصدارات:

• يجب مقارنة الإصدارات عدديًا، وليس معجميًا.
• يجب مقارنة الإصدارات الرئيسية أولاً:
  • إذا اختلفت الإصدارات الرئيسية، يُعتبر الإصدار ذو الإصدار الرئيسي الأعلى أحدث.
  • إذا تساوت الإصدارات الرئيسية، تابع بمقارنة الإصدارات الثانوية.
• يجب مقارنة الإصدارات الثانوية فقط عندما تتساوى الإصدارات الرئيسية:
  • يُعتبر الإصدار ذو الإصدار الثانوي الأعلى أحدث.

أمثلة على المقارنات:

• 1.0 < 2.0
• 1.1 < 1.2
• 1.10 > 1.2

2. بيان المستودع

2.1 نظرة عامة

يوفر ملف البيان (manifest) بيانات وصفية حول مستودع بيانات VEX. يجب أن يحتوي هذا الملف على المعلومات اللازمة لاسترجاع بيانات VEX وتحديثها.

2.2 موقع الملف

• لبروتوكول HTTPS: يجب أن يكون ملف البيان موجودًا على https://<domain>/.well-known/vex-repository.json
• لمستودعات GitHub: يجب وضع vex-repository.json في الدليل الجذر للفرع الرئيسي.

2.3 المخطط

يتم تعريف مخطط JSON لملف البيان هنا.

2.4 مثال

{
  "name": "Example Org VEX Repository",
  "description": "VEX repository for Example Organization",
  "versions": [
    {
      "spec_version": "0.1",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
        }
      ],
      "update_interval": "24h",
      "repository_specific": {
        "location": {
          "repository_type": "db",
          "db_type": "bbolt",
          "url": "oci://ghcr.io/example.com/vex-db:0"
        }
      }
    },
    {
      "spec_version": "1.0",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
        },
        {
          "url": "https://example.com/vex-api/v1"
        }
      ],
      "update_interval": "1h"
    }
  ]
}

2.5 أوصاف الحقول وملاحظات الاستخدام

الحقول الرئيسية

Field	Required	Description and Usage Notes
name	✓	اسم المستودع.
description	✓	وصف موجز للمستودع.
versions	✓	مصفوفة تحتوي على تفاصيل الإصدارات المتاحة. يمثل كل كائن في المصفوفة إصدارًا ينفذ نسخة من مواصفات مستودع VEX. يجب ترتيب الإصدارات تصاعديًا، من الأقدم إلى الأحدث. راجع الجدول المنفصل للحقول الفرعية.

الحقول الفرعية للإصدارات

Field	Required	Description and Usage Notes
spec_version	✓	إصدار مواصفات مستودع VEX المنفذ (مثل "0.1"). يجب أن يكون التنسيق "X.Y" كما هو معرّف في القسم 1.
locations	✓	مصفوفة من الكائنات تصف مواقع بيانات VEX. يجب أن تحتوي على كائن موقع واحد على الأقل. راجع الجدول المنفصل للحقول الفرعية.
update_interval	✓	الفاصل الزمني الموصى به للتحقق من التحديثات لبيانات VEX الخاصة بهذا الإصدار. يستخدم تنسيق مدة Go (مثل "1h" أو "30m" أو "24h").
repository_specific	-	معلومات إضافية خاصة بالمستودع.

الحقول الفرعية للمواقع

Field	Required	Description and Usage Notes
url	✓	عنوان URL لموقع بيانات VEX، يبدأ بـ "https://". يلتزم المحتوى بمواصفات بنية المستودع في القسم 3 والقسم 4. قد يتضمن عنوان URL تحديد دليل فرعي بإلحاق '//' يتبعه مسار الدليل الفرعي.

3. بنية المستودع

3.1 بنية الملفات

يجب أن يكون للمستودع البنية التالية:

vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
    ├── <type>/
    │   ├── <namespace>/
    │   │   ├── <name>/
    │   │   │   └── vex.json
    │   │   └── ...
    │   └── ...
    └── ...

حيث <archive_extension> هي إحدى صيغ الأرشيف المدعومة.

يتم تضمين [optional_subdirectory/] عندما ينتهي عنوان URL في حقل locations بـ // يتبعه مسار دليل فرعي. يسمح هذا بمرونة في بنية المستودع، خاصة عند استخدام تخطيطات مستودعات قائمة مثل تلك الموجودة في مستودعات GitHub.