تكامل SkySpark

اكتشف المشاريع تلقائياً، وزامن الدوال، واحتفظ بسجل الإصدارات لكل التزام.

واجهتا التكامل

هناك طريقتان يتحدث بهما الخادم إلى SkySpark:

  1. نظام الملفات — يقرأ config/ في مجلد SkySpark الرئيسي لتعداد المشاريع واستخراج الدوال المحددة من قبل المستخدم دون الحاجة إلى تشغيل المثيل.
  2. HTTP + Haystack — ينفذ الاستعلامات، ويقيم التعبيرات، والتزاما الدوال مقابل مثيل قيد التشغيل.

يتم تشغيل اكتشاف نظام الملفات عند بدء تشغيل الخادم. تحدث استدعاءات HTTP عند الطلب عندما يستدعي العميل queryHaystack أو executeAxonCode أو commitAxonFunction.

الاكتشاف التلقائي

مع skyspark.autoDiscover: true في الإعدادات، يمر الخادم عبر مجلد SkySpark الرئيسي عند بدء التشغيل:

/path/to/skyspark/
├── config/            ← معددة
│   ├── project-a/
│   ├── project-b/
│   └── sensorRead/
└── ...

لكل مجلد مشروع يتم العثور عليه، يقوم الخادم بما يلي:

  1. قراءة ملف البيانات الوصفية للمشروع للتأكد من أنه مشروع Haystack صحيح.
  2. جلب قائمة الدوال المحددة من قبل المستخدم (سجلات func).
  3. فهرسة تلك الدوال في فهرس Axon المحلي، موسومة بـ project:<name>.

النتيجة: يمكن لـ searchAxonExamples أن تعرض دوال من مشاريع SkySpark الفعلية جنباً إلى جنب مع أمثلة المكتبة الثابتة.

مزامنة الدوال

الاكتشاف يعدد فقط. تجلب المزامنة كود مصدر الدالة الفعلي.

مع autoSyncFunctions: true، تعمل المزامنة تلقائياً عند بدء التشغيل. وإلا، يمكن للعميل تفعيلها عبر discoverProjectFunctions:

{
  "tool": "discoverProjectFunctions",
  "arguments": { "project": "sensorRead" }
}

التزامن

syncConcurrency (الافتراضي 10) يتحكم في عدد الدوال التي يتم جلبها بالتوازي. ارفعه للمثيلات على شبكة محلية سريعة، أو خفّضه للمثيلات البطيئة أو المحدودة.

إصدار الإصدارات

مع functionVersioning: true و maxVersions: 4 (الافتراضية)، كل استدعاء commitAxonFunction:

  1. يقرأ الإصدار الحالي من SkySpark.
  2. يكتب الإصدار الجديد.
  3. يؤرشف الإصدار السابق في .data/versions/<project>/<function>-v<N>.axon.
  4. يحذف المراجعات الأقدم من maxVersions.

استعادة نسخة قديمة هي حالياً نسخ يدوي للملف مرة أخرى إلى SkySpark — لا توجد أداة restoreFunctionVersion حتى الآن.

مفهوم المشروع الأساسي

أدوات التنفيذ والالتزام تحتاج إلى اختيار مشروع واحد. المشروع الأساسي هو هذا الاختيار:

"primaryProject": {
  "instance": "localhost8080",
  "project":  "sensorRead"
}

يمكن للعملاء تبديله في وقت التشغيل:

{ "tool": "setPrimaryProject", "arguments": { "instance": "localhost8080", "project": "plantRoom" } }

استدعاءات executeAxonCode و commitAxonFunction اللاحقة تستهدف plantRoom حتى التبديل التالي.

تشغيل الاستعلامات

queryHaystack يأخذ سلسلة استعلام Haystack خام ويعيد الشبكة الناتجة كـ JSON:

{
  "tool": "queryHaystack",
  "arguments": {
    "query": "read(site)"
  }
}

النتيجة:

{
  "meta": { "ver": "3.0" },
  "cols": [ { "name": "id" }, { "name": "dis" }, { "name": "site" } ],
  "rows": [
    { "id": "@p:sensorRead:r:1a2b", "dis": "Main Campus", "site": true }
  ]
}

يتم تنفيذ الاستعلامات باستخدام سياق المصادقة لمشروع المشروع الأساسي.

بيانات الاعتماد الاحتياطية

إذا فشل الاكتشاف التلقائي (مسار خاطئ، SkySpark غير مثبت على نفس المضيف، إلخ)، يعود الخادم إلى كتلة الاتصال الصريحة:

"fallback": {
  "host":     "skyspark.example.com",
  "port":     443,
  "project":  "demo",
  "username": "readonly",
  "password": "<use-env-var>",
  "protocol": "https"
}

فضّل استبدال متغيرات البيئة لكلمة المرور (SKYSPARK_PASSWORD) بدلاً من حفظها في ملف الإعدادات.

استكشاف أخطاء الاتصال

  • SKYSPARK_UNREACHABLE — المثيل لا يقبل الاتصالات على المضيف/المنفذ المحدد. تحقق من curl http://<host>:<port>/about.
  • SKYSPARK_AUTH_FAILED — بيانات الاعتماد خاطئة، أو المستخدم لا يملك إذن الوصول للمشروع المستهدف.
  • PROJECT_NOT_FOUND — المشروع الأساسي غير موجود على المثيل. قم بتشغيل listSkySparkProjects لمعرفة ما هو متاح.