इस प्रोजेक्ट के बारे में

# IzgoN IzgoN एक डेल्टा-सिंक सर्वर है जो उन डिवाइस फ्लीट्स के लिए डिज़ाइन किया गया है जो बार-बार समान स्थिति रिपोर्ट करते हैं। हर चक्र में पूर्ण पेलोड अपलोड करने के बजाय, प्रत्येक नोड अपनी वर्तमान स्थिति POST करता है; IzgoN इसे पिछली स्थिति से तुलना करता है और या तो `NO_CHANGE` (शून्य पेलोड बाइट्स), एक न्यूनतम JSON डेल्टा, या पूर्ण स्थिति लौटाता है जब डेल्टा उस स्थिति से बड़ा हो जिसे वह प्रतिस्थापित करता है। ## मुख्य क्षमताएँ - **डेल्टा सिंक**: केवल बदले हुए फ़ील्ड डिवाइस को वापस भेजे जाते हैं, जिससे रिप्लाई पेलोड नाटकीय रूप से कम हो जाते हैं। - **कंडीशनल सिंक (v1.4.0+)**: जो डिवाइस नहीं बदले हैं वे पूर्ण रिपोर्ट के बजाय एक छोटा चेकसम टोकन भेज सकते हैं, इसलिए रिपोर्ट कभी वायर पर नहीं जाती। - **बचत माप**: डैशबोर्ड और `/api/metrics` एंडपॉइंट दोनों दिशाओं (रिप्लाई और अपलिंक) में लाइव बाइट बचत दिखाते हैं। - **बेंचमार्क टूल**: `benchmark.py` (केवल stdlib) आपकी अपनी वास्तविक रिपोर्ट को रीप्ले करके आपके डेटा पर बचत मापता है, परीक्षण के लिए सिंथेटिक मोड के साथ। - **अनुकूली पोलिंग सुझाव**: सर्वर कई समान रिपोर्टों के बाद लंबा रिपोर्टिंग अंतराल सुझा सकता है, स्पष्ट स्टेलनेस ट्रेड-ऑफ के साथ। - **साइलेंस अलर्ट**: जब कोई नोड रिपोर्ट करना बंद कर देता है और जब वह लौटता है तो वेबहुक सूचनाएँ। - **बैच सिंक**: जो डिवाइस ऑफ़लाइन रहते हुए बफर करते हैं वे एक अनुरोध में कतार फ्लश कर सकते हैं। - **फ्री टियर**: लाइसेंस कुंजी के बिना 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 स्वीकार करता है, डिवाइस ID फ़ील्ड स्वतः पहचानता है, और आपके डेटा से परिवर्तन दर मापता है। सिंथेटिक मोड: `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 MB) में सीमित है। ## सीमाएँ - सूचियों को तत्व-दर-तत्व डिफ़ नहीं किया जाता है; एक आइटम बदलने से पूरी सूची भेजी जाती है। - सिकुड़ते पेलोड `FULL_STATE` ट्रिगर कर सकते हैं (उस सिंक पर कोई बचत नहीं)। - किसी भी नोड से पहली रिपोर्ट हमेशा पूर्ण होती है। - बेसलाइन Redis में रहती हैं; यदि मिटा दी जाती हैं, तो नोड्स एक बार फिर सिंक करते हैं। - एकल उदाहरण, कोई क्लस्टरिंग नहीं। - अभी तक कोई क्लाइंट SDK नहीं; एकीकरण सादा HTTP POST है। ## लाइसेंस और मूल्य निर्धारण स्रोत-उपलब्ध, ओपन सोर्स नहीं। फ्री टियर: 10,000 सिंक। वाणिज्यिक लाइसेंस: एकमुश्त भुगतान, कोई सदस्यता नहीं, ऑफ़लाइन Ed25519 हस्ताक्षर सत्यापन। कोई फ़ोन-होम नहीं। ## स्थिति संस्करण 1.4.2। एक व्यक्ति द्वारा निर्मित और अनुरक्षित। लाइव डेमो `https://izgon-api.onrender.com` पर (पहला अनुरोध जागने में 20–40 सेकंड लग सकते हैं)।