عن المشروع

# IzgoN IzgoN هو خادم مزامنة دلتا مصمم لأساطيل الأجهزة التي تبلغ بشكل متكرر عن حالة مماثلة. بدلاً من رفع الحمولات الكاملة كل دورة، يقوم كل عقدة بإرسال حالتها الحالية عبر POST؛ يقارن IzgoN هذه الحالة بآخر حالة رآها ويعيد إما `NO_CHANGE` (صفر بايت من الحمولة)، أو دلتا JSON ضئيلة، أو الحالة الكاملة عندما تكون الدلتا أكبر من الحالة التي تستبدلها. ## القدرات الرئيسية - **مزامنة دلتا**: يتم إرسال الحقول المتغيرة فقط مرة أخرى إلى الجهاز، مما يقلل بشكل كبير من حمولات الرد. - **المزامنة الشرطية (v1.4.0+)**: يمكن للأجهزة التي لم تتغير إرسال رمز فحص قصير بدلاً من التقرير الكامل، بحيث لا ينتقل التقرير نفسه عبر الشبكة. - **قياس التوفير**: تعرض لوحة التحكم ونقطة النهاية `/api/metrics` توفير البايتات المباشر في كلا الاتجاهين (الرد والرفع). - **أداة المعايير**: `benchmark.py` (مكتبة قياسية فقط) يعيد تشغيل تقاريرك الحقيقية لقياس التوفير على بياناتك، مع وضع اصطناعي للاختبار. - **اقتراحات الاستطلاع التكيفية**: يمكن للخادم اقتراح فترة إبلاغ أطول بعد عدة تقارير متطابقة، مع مقايضات صراحة للتقادم. - **تنبيهات الصمت**: إشعارات Webhook عندما يتوقف عقدة عن الإبلاغ وعندما يعود. - **المزامنة الدفعية**: يمكن للأجهزة التي خزنت البيانات أثناء عدم الاتصال تفريغ قائمة انتظار في طلب واحد. - **الخطة المجانية**: 10,000 مزامنة بدون مفتاح ترخيص، كافية للتقييم. ## كيف يعمل يرسل العقدة حالتها داخل `state` (أو مجرد `checksum` إذا لم تتغير). يستجيب الخادم بواحدة من أربع حالات: - `NO_CHANGE` — لا شيء تغير، صفر بايت مرسل. - `SYNC_REQUIRED` — يتم إرجاع المفاتيح المتغيرة فقط؛ يدمجها العميل. - `FULL_STATE` — يتم إرجاع الحالة الكاملة الجديدة (عندما تكون الدلتا أكبر). - `SEND_STATE` — لا يوجد لدى الخادم خط أساس أو أن المجموع الاختباري غير معروف؛ يجب على العميل إعادة إرسال الحالة الكاملة. يتم مقارنة الكائنات المتداخلة بشكل متكرر؛ تتم مقارنة القوائم ككل (قيد متعمد). رمز `epoch` اختياري يفرض حالة كاملة بعد إعادة تشغيل الخادم أو فقدان المرآة، مما يمنع عدم التزامن الصامت. ## بدء سريع ```bash docker run -p 8000:8000 -e DATAPULSE_API_KEY=change-me ghcr.io/izgamber/izgon:latest ``` أو باستخدام Docker Compose (يشمل Redis لخطوط الأساس المستمرة): ```bash git clone https://github.com/izGamber/IZgoN.git cd IZgoN cp .env.example .env docker compose up -d ``` لوحة التحكم على `http://localhost:8000`. أرسل حالة: ```bash curl -X POST http://localhost:8000/api/nodes/sensor-01/sync \ -H "Content-Type: application/json" \ -H "X-API-Key: dev-local-key" \ -d '{"state": {"temp": 21.5, "hum": 60, "batt": 98}}' ``` كرر نفس الحالة ← `NO_CHANGE` مع صفر بايت دلتا. غيّر حقلاً واحداً ← يتم إرجاع هذا الحقل فقط. ## المعايير على بياناتك الخاصة ```bash python3 benchmark.py --payload-file my-reports.json ``` يقبل مصفوفات JSON أو JSON Lines، ويكتشف تلقائياً حقول معرف الجهاز، ويقيس معدل التغيير من بياناتك. الوضع الاصطناعي: `python3 benchmark.py --nodes 50 --rounds 100 --change-rate 0.05`. التوفير المقاس (معدل تغيير 5%): ~94% على الرد، ~40% على الرفع (لكل SIM)، ~65% لعملاء الاستطلاع. عند معدل تغيير 70%، ينخفض التوفير إلى ~35% — الحد الصادق. ## نقاط نهاية API | الطريقة | المسار | المصادقة | الغرض | |---|---|---|---| | POST | `/api/nodes/{id}/sync` | مفتاح API | إرسال الحالة أو المجموع الاختباري، الحصول على دلتا/كامل/NO_CHANGE | | POST | `/api/nodes/{id}/sync/batch` | مفتاح API | إعادة تشغيل قائمة الانتظار المخزنة في طلب واحد | | GET | `/api/nodes` | مفتاح API | قائمة العقد وخطوط الأساس (مقسمة إلى صفحات) | | GET | `/api/metrics` | لا شيء | إجماليات توفير البايتات المباشرة | | GET | `/api/license` | لا شيء | الخطة الحالية والمزامنات المجانية المتبقية | | GET | `/healthz` | لا شيء | إمكانية الوصول إلى Redis، وضع التخزين | | GET | `/` | لا شيء | لوحة التحكم | ## الإعدادات جميع الإعدادات عبر متغيرات البيئة (انظر `.env.example`). الإعدادات الرئيسية: - `DATAPULSE_REDIS_URL` — اتصال Redis لخطوط الأساس - `DATAPULSE_API_KEY` — مفتاح المصادقة (الافتراضي `dev-local-key`، غيّره) - `DATAPULSE_FREE_TIER_LIMIT` — المزامنات المجانية قبل 402 (الافتراضي 10000) - `DATAPULSE_LICENSE_KEY` — مفتاح الترخيص المدفوع (موقّع بـ Ed25519، تحقق دون اتصال) - `DATAPULSE_ALERT_URL` / `DATAPULSE_ALERT_AFTER` — تنبيهات الصمت - `DATAPULSE_ADAPTIVE` — تمكين/تعطيل اقتراحات فترة الاستطلاع - `DATAPULSE_MAX_STATE_DEPTH` / `DATAPULSE_MAX_STATE_BYTES` — حدود الحمولة ## ملاحظات الأمان - مفتاح API يحمي جميع عمليات الكتابة؛ مقارنة بوقت ثابت. - `/api/metrics` و `/healthz` غير مصادق عليهما حسب التصميم. - CORS الافتراضي هو `*`؛ قيّده في الإنتاج. - لا يوجد تحديد معدل مدمج؛ ضعه خلف وكيل عكسي. - الحالة محدودة بالعمق (32) والحجم (1 ميجابايت). ## القيود - لا تتم مقارنة القوائم عنصراً بعنصر؛ تغيير عنصر واحد يرسل القائمة بأكملها. - قد تؤدي الحمولات المتقلصة إلى `FULL_STATE` (لا توفير في تلك المزامنة). - التقرير الأول من أي عقدة يكون دائماً كاملاً. - خطوط الأساس موجودة في Redis؛ إذا تم مسحها، تعيد العقد المزامنة مرة واحدة. - مثيل واحد، لا عنقودية. - لا يوجد SDK للعميل بعد؛ التكامل هو POST HTTP بسيط. ## الترخيص والتسعير المصدر متاح، وليس مفتوح المصدر. الخطة المجانية: 10,000 مزامنة. الترخيص التجاري: دفع لمرة واحدة، بدون اشتراك، تحقق من التوقيع دون اتصال بـ Ed25519. لا اتصال بالمنزل. ## الحالة الإصدار 1.4.2. مبني ومُدار بواسطة شخص واحد. عرض حي على `https://izgon-api.onrender.com` (قد يستغرق الطلب الأول 20-40 ثانية للاستيقاظ).