भाग X: डेस्क संदर्भ और निदान¶
एंडपॉइंट, मेट्रिक, त्रुटि सूची, नीति स्कीमा और स्टोरेज टेबल, सब एक स्थान पर।
एंडपॉइंट¶
| एंडपॉइंट | मेथड | कार्य |
|---|---|---|
/__sibuna/challenge |
GET | इंटरस्टिशियल पेज |
/__sibuna/challenge.json?need=&path= |
GET | एक स्टेटलेस चैलेंज जारी करता है: चैलेंज वाले रिस्पॉन्स का आवश्यकता टिकट उसे तय करता है, अन्यथा रिपोर्ट किए गए URL का सामान्य रूप में मूल्यांकन होता है (8 KiB से ऊपर 414, सामान्य रूप न रखने वाले पाथ के लिए 400)। {id, algorithm, difficulty, challenges, expires_at} लौटाता है |
/__sibuna/verify |
POST | {"challenge_id", "nonce"} या {"challenge_id", "proof"} स्वीकार करता है; Set-Cookie के साथ 200, निदान के साथ 400, या कनेक्शन बफ़र से बड़ी बॉडी के लिए 413 |
/__sibuna/wasm/sibuna-pow.wasm |
GET | सॉल्वर मॉड्यूल, 14,744 बाइट (benchmarks/results/primitives-latest.json में wasm_bytes), एक घंटे तक cache योग्य |
/__sibuna/worker.js |
GET | WASM और JavaScript प्रूवर वाला Web Worker, एक घंटे तक cache योग्य |
/__sibuna/honeypot |
GET | कॉल करने वाले पर --ban-seconds के लिए प्रतिबंध लगाता है और एक घटना दर्ज करता है; 403। केवल शीर्ष-स्तर का अनुरोध प्रतिबंध लगवाता है (Sec-Fetch-Dest न हो या document हो, और cross-site Sec-Fetch-Site न हो); किसी अन्य को 404 उत्तर मिलता है और उसे गिना जाता है |
/__sibuna/health |
GET | इंजन के नाम, संस्करण, प्रॉक्सी मोड और प्रमाण एल्गोरिदम के साथ JSON liveness स्टेटस |
/__sibuna/metrics |
GET | Prometheus टेक्स्ट प्रारूप (संस्करण 0.0.4) |
/__sibuna/ के अंतर्गत किसी भी अन्य पाथ को 404 उत्तर मिलता है। जारी करना और सत्यापन अलग --challenge-rate-limit बजट खर्च करते हैं, और प्रतिबंधित पते को हर रूट पर 403 से अस्वीकार किया जाता है। चैलेंज रिस्पॉन्स X-Sibuna-Status: CHALLENGE ले जाते हैं; स्वीकृत अनुरोध अपस्ट्रीम की ओर X-Sibuna-Status: PASS और X-Sibuna-Rule ले जाते हैं (और forward-auth उत्तरों में हेक्साडेसिमल में X-Sibuna-Rule-Hash)। जो क्लाइंट HTML स्वीकार नहीं करता, उसे {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"} के साथ 401 मिलता है।
अलग, वैकल्पिक प्रबंधन listener /console/ देता है। इसके एडमिनिस्ट्रेटर को sibuna init-admin से स्थानीय रूप से प्रारंभ करें, फिर पहले साइन-इन पर अस्थायी पासवर्ड बदलें। /console/api/stats और /console/ws के लिए प्रमाणित सत्र चाहिए (kiosk सत्र सहित)। WebSocket सीमित स्नैपशॉट, delta और gap recovery के साथ आँकड़े, इवेंट, नोड, नीति, चैलेंज और ऑडिट को मल्टीप्लेक्स करता है। प्रबंधन पीयर /console/peer से जुड़ते हैं, और हर API रूट /console/api/ के अंतर्गत है। forward-auth मोड में ऑरिजिन त्रुटि काउंटर नहीं देखे जाते। भाग IX कंसोल के वर्कफ़्लो, HTTPS डिप्लॉयमेंट और SID 0007 की वर्तमान सीमाओं का दस्तावेज़ देता है।
मेट्रिक¶
Prometheus टेक्स्ट प्रारूप में sibuna_<name>_total के रूप में दिखाए जाने वाले काउंटर, इस क्रम में:
| काउंटर | कब बढ़ता है |
|---|---|
incidents_persisted, incident_batches |
वे रिकॉर्ड और ट्रांज़ैक्शन जिनके कमिट की पुष्टि स्टोरेज थ्रेड ने की |
incidents_dropped, incident_write_failures |
रिंग भरी होने के कारण अस्वीकार किए गए कतार push, और कमिट के विफल प्रयास |
requests |
पार्स किया गया अनुरोध डिस्पैच तक पहुँचा (आरक्षित रूट सहित) |
allowed, denied, challenged |
नीति निर्णय लिया गया (स्वीकृत, अस्वीकृत, चैलेंज जारी या दोबारा जारी) |
challenges_issued |
/__sibuna/challenge.json ने एक चैलेंज रिकॉर्ड जारी किया |
solutions_accepted, solutions_rejected |
/__sibuna/verify ने किसी प्रमाण को स्वीकार या अस्वीकार किया |
rate_limited |
GCRA ने किसी अनुरोध को अस्वीकार किया (429): अनुरोध सीमा, चैलेंज बजट या किसी नियम का कोटा |
banned |
किसी प्रतिबंधित पते को अस्वीकार किया गया, या हनीपॉट ने किसी पर प्रतिबंध लगाया |
bans_issued |
एक प्रतिबंध दर्ज किया गया (हनीपॉट या किसी नियम कोटा का प्रतिबंध) |
proxied, upstream_errors |
एक अनुरोध ऑरिजिन तक रिले किया गया, या ऑरिजिन विफल हुआ (502) |
parse_errors |
विकृत हेड, दोहराया गया Host, सामान्य रूप न रखने वाला लक्ष्य (400), या असमर्थित transfer coding (501) अस्वीकार किया गया |
overloaded |
--max-connections या --max-connections-per-ip से आगे के कनेक्शन को 503 उत्तर मिला |
bans_refused |
प्रतिबंध दर्ज नहीं हुआ, क्योंकि उसकी कुंजी जो भी स्लॉट ले सकती थी उन सभी में एक प्रभावी प्रतिबंध था |
forwarded_invalid |
विश्वसनीय फ़ॉरवर्ड किया गया क्लाइंट पता पार्स नहीं हुआ; अनुरोध का निर्णय सॉकेट पीयर से हुआ |
honeypot_refused |
हनीपॉट हिट से किसी पर प्रतिबंध नहीं लगा, क्योंकि उसे किसी व्यक्ति ने नहीं, एक पेज ने माँगा था |
rate_evictions |
लिमिटर में किसी आगमन ने किसी दूसरे सक्रिय क्लाइंट की सेल को हटा दिया |
ja4_present |
--ja4-header और विश्वसनीय फ़ॉरवर्डिंग के साथ, अनुरोध में उस नाम का ठीक एक हेडर JA4 फ़िंगरप्रिंट के साथ था |
ja4_invalid |
--ja4-header और विश्वसनीय फ़ॉरवर्डिंग के साथ, हेडर विकृत या दोहराया गया था; अनुरोध का मूल्यांकन बिना फ़िंगरप्रिंट के हुआ |
एक रीट्राई रिकॉर्ड खोए बिना incident_write_failures बढ़ा सकता है, क्योंकि लंबित बैच रखा जाता है। किसी अंतराल में हुई बढ़ोतरी की निगरानी करें; केवल कुल योग कतार की गहराई नहीं बताते।
स्टेटस कोड¶
| कोड | कब |
|---|---|
| 200 | स्वीकृत (forward-auth), इंटरस्टिशियल (चैलेंज की ज़रूरत वाला HTML नेविगेशन), आंतरिक रूट |
| 302 | वर्तमान प्रोटोकॉल में उपयोग नहीं होता; सत्यापन 200 उत्तर देता है और पेज दोबारा लोड होता है |
| 400 | विकृत अनुरोध, दोहराया गया Host फ़ील्ड, सामान्य रूप न रखने वाला लक्ष्य, अमान्य फ़ॉरवर्ड किया गया मेटाडेटा, विकृत बॉडी, या Elm-शैली के निदान के साथ अस्वीकृत समाधान |
| 401 | HTML स्वीकार न करने वाले क्लाइंट के लिए, या forward-auth मोड में, चैलेंज आवश्यक |
| 403 | नीति या WAF द्वारा अस्वीकृति, प्रतिबंधित पता, हनीपॉट |
| 404 | /__sibuna/ के अंतर्गत अज्ञात पाथ, या ऐसा हनीपॉट हिट जो शीर्ष-स्तर का अनुरोध नहीं है |
| 413 | समाधान की बॉडी 64 KB कनेक्शन बफ़र से बड़ी |
| 414 | रिपोर्ट किया गया चैलेंज URL 8 KiB से बड़ा |
| 417 | असमर्थित अनुरोध अपेक्षा (expectation); 100-continue स्थानीय रूप से संभाला जाता है |
| 429 | GCRA सीमा पार; Retry-After सेकंड में |
| 431 | अनुरोध हेड 16 KB से बड़ा |
| 501 | chunked के अलावा किसी अन्य coding वाला Transfer-Encoding |
| 502 | ऑरिजिन तक पहुँच नहीं, या उसका रिस्पॉन्स हेड विकृत था या 16 KB से बड़ा था |
| 503 | कनेक्शन सीमा (--max-connections या --max-connections-per-ip) पूरी, या नोड ड्रेन हो रहा है; उत्तर के बाद सॉकेट बंद कर दिया जाता है |
त्रुटि सूची¶
INVALID COMMAND LINE हर उस विकल्प के लिए स्टार्टअप रोक देता है जिसे डेमन नहीं पहचानता, अपनी दस्तावेज़ित सीमा से बाहर के हर मान के लिए, और अमान्य, अनुपस्थित या दोहराए गए मोड चयन के लिए। ब्लॉक विकल्प, दिया गया मान, अपेक्षित सीमा और त्रुटि (UnknownOption, MissingValue, InvalidValue, InvalidMode, MissingMode, DuplicateMode, Zaxonlite क्लस्टर विकल्प के लिए RemovedOption, एक-दूसरे को बाहर करने वाले दो स्टोरेज विकल्पों के लिए ConflictingOptions, --cluster-node के बिना डेटाबेस URL के लिए MissingOption) का नाम देता है, और एक संकेत के साथ समाप्त होता है। डेटाबेस URL [redacted] के रूप में दिखाया जाता है। --mode reverse_proxy या --mode forward_auth एक बार दें; -m समतुल्य छोटा विकल्प है। अस्वीकृत नीति फ़ाइल अपनी त्रुटि के शीर्षक वाला एक ब्लॉक छापती है (उदाहरण के लिए INVALID POLICY ACTION), जिसमें फ़ाइल, त्रुटि का नाम, नियम, फ़ील्ड और मान होते हैं। ऐसा ja4 पैटर्न जिससे कोई फ़िंगरप्रिंट मेल नहीं खा सकता, INVALID POLICY JA4 (InvalidJa4) छापता है; ऐसे पैटर्न वाला कंसोल प्रबंधन दस्तावेज़ उसी त्रुटि नाम के साथ अस्वीकार होता है। कंसोल विकल्पों की जाँच अलग से होती है: CONSOLE002 विकृत या दोहराए गए कंसोल विकल्प का नाम देता है, और CONSOLE001 किसी नियम को तोड़ने वाले कंसोल कॉन्फ़िगरेशन का (स्टोरेज के बिना StorageRequired)।
| त्रुटि | कारण | संकेत |
|---|---|---|
MalformedChallenge |
पहचानकर्ता एक सही रूप वाला चैलेंज रिकॉर्ड नहीं है | नया चैलेंज लाएँ और उसे बिना बदले सबमिट करें |
InvalidChallengeTag |
टैग प्रमाणित नहीं होता; इस क्लस्टर ने जारी नहीं किया या संपादित किया गया | चैलेंज जाली नहीं बनाए जा सकते; नया माँगें |
ChallengeExpired |
चैलेंज TTL से पुराना, या भविष्य में जारी किया गया | नया चैलेंज माँगें |
FingerprintMismatch |
किसी दूसरे पते या User-Agent से सबमिट किया गया | उसी क्लाइंट से सबमिट करें जिसने उसे मँगाया था |
DifficultyNotMet |
Hashcash नॉनस में आवश्यक शून्य बिट नहीं हैं | नॉनस खोजते रहें |
InvalidProof |
अनुक्रमिक कार्य का प्रमाण कमिट किए गए लेबल नहीं खोलता | जारी की गई गहराई और ओपनिंग के लिए प्रूवर को पूरा चलाएँ |
WrongSolutionType |
PoSW चैलेंज के लिए नॉनस या Hashcash के लिए प्रमाण | समाधान के फ़ील्ड को एल्गोरिदम से मिलाएँ |
DoubleSpendAttempt |
चैलेंज पहले ही खर्च हो चुका था | चैलेंज एक बार ही उपयोग होते हैं |
StoreFull |
spent set भरा हुआ है | चैलेंज TTL घटाएँ या --spent-tags बढ़ाएँ |
InvalidTokenSignature |
कुकी का टैग या हस्ताक्षर विफल | इंटरस्टिशियल के ज़रिए दोबारा प्रमाणित हों |
TokenExpired |
कुकी अपनी समाप्ति से आगे | दोबारा प्रमाणित हों |
TokenBoundAddressMismatch |
कुकी किसी दूसरी क्लाइंट पहचान से प्रस्तुत की गई | कुकी साझा नहीं की जा सकतीं |
कंसोल का API विफलता का उत्तर {"error":"<CODE>","hint":"<sentence>"} से देता है; hint वह टेक्स्ट है जो इंटरफ़ेस दिखाता है (crates/console/src/http/reply.rs)।
| कोड | स्टेटस | अर्थ |
|---|---|---|
CONSOLE002 |
400 | अनुरोध विकृत है, बहुत बड़ा है, या अपने रूप में अनुमत नहीं है |
CONSOLE003 |
503 / 429 | स्टोरेज जॉब कतार भरी है (32 जॉब), या पासवर्ड सत्यापनकर्ता व्यस्त है |
CONSOLEQUORUM |
503 | डेटाबेस ने अनुरोध की 10 सेकंड की प्रतीक्षा के भीतर उत्तर नहीं दिया; परिणाम अज्ञात है, और डेटा plane अंतिम लागू नीति से चलता रहता है |
CONSOLE004 |
503 | सेवा उत्तर नहीं दे सकती: इस बिल्ड में उपलब्ध नहीं, रुक रही है, या आंतरिक विफलता |
CONSOLENODE |
400 / 409 / 503 | नोड कमांड अस्वीकार हुई: वह किसी दूसरे नोड का नाम देती है (400), पुराना boot या control revision (409), या वह तब आई जब कोई दूसरी कमांड चल रही थी या किसी पूर्णता को दर्ज नहीं किया जा सका (503); रीट्राई से पहले operation receipt की जाँच करें |
CONSOLEMUTATION |
429 | एक सत्र से एक मिनट में साठ से अधिक प्रबंधन परिवर्तन (mutation) |
नीति स्कीमा¶
{
"default_action": "ALLOW" | "DENY" | "CHALLENGE",
"waf": true | false,
"inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
"thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
"ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
"rules": [ // अधिकतम 128
{
"name": "<kebab-case>", // 1 से 128 printable बाइट
"path" | "path_regex": "<pattern>", // अधिकतम 512 बाइट
"user_agent" | "user_agent_regex": "<pattern>",
"headers" | "headers_regex": { "<Header>": "<pattern>" }, // अधिकतम 4
"remote_addresses" | "cidrs": ["<cidr>", ...], // अधिकतम 8, IPv4 या IPv6
"action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
"weight": int, // केवल WEIGH, -1000..1000
"challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
"limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
"ja4": "<fingerprint>" | "<prefix>*" // 36 बाइट, या प्रीफ़िक्स और *
}
]
}
challenge_at और deny_at -1000 से 1000 के बीच होते हैं, deny_at का मान challenge_at के बराबर या उससे ऊपर होता है, और bits_step 1 से 1000 के बीच। challenge ब्लॉक केवल CHALLENGE नियमों का होता है, 1 से 64 वर्क बिट्स के साथ। limits किसी नियम को उसका अपना कोटा देता है: rate 1 से 1,000,000 और window_seconds 1 से 86,400 आवश्यक हैं, ban_seconds (अधिकतम 86,400) वैकल्पिक है, और WEIGH नियम सीमाएँ नहीं रख सकते। ja4 या तो एक पूरा JA4 फ़िंगरप्रिंट है, जिसके बराबर फ़िंगरप्रिंट होना चाहिए, या ऐसा प्रीफ़िक्स जिसके बाद * हो, और फ़िंगरप्रिंट उसी से शुरू होना चाहिए; अकेला * किसी भी फ़िंगरप्रिंट से मेल खाता है, और फ़िंगरप्रिंट रहित अनुरोध किसी ja4 नियम से मेल नहीं खाता। ऐसा पैटर्न जिससे कोई फ़िंगरप्रिंट मेल नहीं खा सकता, InvalidJa4 के साथ अस्वीकार होता है (भाग IX, इनग्रेस से JA4 फ़िंगरप्रिंट)। ip_rules का प्रतिष्ठा trie अधिकतम 8,192 नोड रखता है। हर नियम हर मानदंड की एक ही वर्तनी का उपयोग कर सकता है।
पैटर्न का व्याकरण: .* या * किसी भी चीज़ से मेल खाते हैं; ^...$ एक सटीक पाथ को बाँधता है; अंत में *, /* या .* प्रीफ़िक्स है; / से शुरू होने वाला पैटर्न सटीक पाथ है; बाकी सब केस-असंवेदी सबस्ट्रिंग है। पाथ पैटर्न सामान्य रूप वाले पाथ से मेल खाते हैं (खंडों के बीच एक स्लैश, कोई dot खंड नहीं, unreserved अक्षर unescaped, अन्य escape बड़े अक्षरों वाले हेक्साडेसिमल अंकों के साथ), इसलिए ;, %2F, %5C या \ रखने वाला पैटर्न किसी से मेल नहीं खाता, और पाथ मिलान केस-संवेदी है (SID 0003)।
स्टोरेज टेबल¶
policy_revision, policies (अधिकतम 37 बाइट के nullable ja4_pattern मानदंड के साथ), policy_inspection, ip_reputation, incident_receipts, security_incidents (256-बाइट एम्बेडिंग और nullable 36-बाइट ja4 फ़िंगरप्रिंट के साथ), full-text इंडेक्स (SQLite पर incidents_fts, canonical टोकन पर FTS5; PostgreSQL पर GIN इंडेक्स के साथ tsvector कॉलम search) और sibuna_schema; कंसोल 33 console_* टेबल जोड़ता है। संग्रहीत एक्शन, एल्गोरिदम और मोड के नाम छोटे अक्षरों में हैं। घटना id node_id << 40 | sequence हैं, जो बिना समन्वय के पूरे क्लस्टर में अद्वितीय हैं; नोड id 1 से 8,388,607 तक होते हैं।
बिल्ड टारगेट¶
| कमांड | परिणाम |
|---|---|
cargo build --release -p sibuna |
SQLite स्टोरेज और कंसोल वाला डेमन (डिफ़ॉल्ट features) |
cargo build --release -p sibuna --no-default-features |
मेमोरी में चलने वाला डेमन, स्टोरेज या कंसोल के बिना और किसी बाहरी क्रेट के बिना |
cargo build --release -p sibuna --features postgres-tls |
डेमन जो एक साझा PostgreSQL डेटाबेस से भी जुड़ता है, सत्यापित TLS के साथ (केवल postgres feature TLS के बिना जुड़ता है) |
cargo test |
यूनिट परीक्षण, चलते हुए डेमन पर integration परीक्षण, स्टोरेज और कंसोल परीक्षण (SIBUNA_TEST_DATABASE_URL सेट होने पर PostgreSQL वाले भी) |
cargo clippy --all-targets, cargo fmt --check |
लिंट और फ़ॉर्मेटिंग (max_width = 99) |
cargo xtask check |
70-पंक्ति फ़ंक्शन, 1,408-पंक्ति फ़ाइल और 99/108-कॉलम पंक्ति की सीमाएँ; कोई टैब नहीं |
cargo xtask browser |
headless Chromium में जाँचें (sibuna-browser) |
cargo xtask bench <primitives|product|latency> |
रिलीज़ मोड के बेंचमार्क; परिणाम benchmarks/results/<command>-latest.json में |
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm |
केवल ब्राउज़र मॉड्यूल (कंसोल इंटरफ़ेस के लिए -p sibuna-console-ui) |
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... |
देश डेटा का सत्यापन करें और एम्बेड करने योग्य GeoIP स्नैपशॉट लिखें |
guidedog build / guidedog dsc |
यह पुस्तक / SID रिकॉर्ड |
डेमन की बिल्ड स्क्रिप्ट (cmd/sibuna/build.rs) दोनों WebAssembly मॉड्यूल को wasm प्रोफ़ाइल के साथ वर्कस्पेस की टारगेट डायरेक्टरी में बनाती है, और कंसोल इंटरफ़ेस 768 KiB से अधिक होने पर बिल्ड विफल कर देती है। wasm32-unknown-unknown टारगेट के बिना बिल्ड के लिए SIBUNA_POW_WASM और SIBUNA_CONSOLE_WASM इसके बजाय पहले से बने मॉड्यूल का नाम देते हैं। SIBUNA_GEOIP_DATA एम्बेड करने के लिए एक GeoIP स्नैपशॉट का नाम देता है; इसे बिल्ड के समय डिकोड किया जाता है, और कंसोल के बिना बिल्ड इसे अस्वीकार करता है (GEOIP001)।