প্রকল্প সম্পর্কে

# 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 গ্রহণ করে, ডিভাইস আইডি ফিল্ড স্বয়ংক্রিয়ভাবে সনাক্ত করে এবং আপনার ডেটা থেকে পরিবর্তনের হার পরিমাপ করে। সিন্থেটিক মোড: `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 সেকেন্ড সময় লাগতে পারে)।