Gateway लॉक

क्यों

• केवल एक Gateway प्रक्रिया को किसी स्टेट डायरेक्टरी का स्वामित्व रखना चाहिए; अतिरिक्त Gateway को अलग-अलग प्रोफ़ाइल, स्टेट डायरेक्टरी, कॉन्फ़िगरेशन और पोर्ट के साथ चलाएँ।
• क्रैश/SIGKILL के बाद भी पुरानी लॉक फ़ाइलें छोड़े बिना कार्यरत रहें।
• जब कोई अन्य Gateway पहले से पोर्ट का स्वामी हो, तो स्पष्ट त्रुटि के साथ तुरंत विफल हो जाएँ।

तीन परतें

स्टार्टअप क्रम से तीन चरणों में स्वामित्व लागू करता है:

1. स्टेट स्वामित्व लॉक कैनोनिकल स्टेट डायरेक्टरी पर आधारित लॉक प्राप्त करता है। OPENCLAW_ALLOW_MULTI_GATEWAY=1 के साथ शुरू किए गए Gateway सहित प्रत्येक Gateway इसमें भाग लेता है, ताकि विनाशकारी SQLite रखरखाव किसी सक्रिय स्वामी के साथ प्रतिस्पर्धा न कर सके।
2. कॉन्फ़िगरेशन लॉक ऐतिहासिक प्रति-कॉन्फ़िगरेशन लॉक प्राप्त करता है और रनटाइम पोर्ट दर्ज करता है। मल्टी-Gateway मोड इस कॉन्फ़िगरेशन सिंगलटन को छोड़ देता है, लेकिन स्टेट स्वामित्व लॉक बनाए रखता है।
3. सॉकेट बाइंड HTTP/WebSocket लिसनर (डिफ़ॉल्ट ws://127.0.0.1:18789) को विशिष्ट TCP लिसनर के रूप में बाइंड करता है।

प्रत्येक परत स्वतंत्र रूप से विफल हो सकती है और अपना GatewayLockError थ्रो करती है।

स्टेट और कॉन्फ़िगरेशन लॉक

• लॉक की सक्रियता दर्ज PID, उपलब्ध होने पर प्लेटफ़ॉर्म प्रक्रिया की आरंभ पहचान और Gateway प्रक्रिया की पहचान से निर्धारित होती है। सत्यापित स्वामी स्टार्टअप के दौरान अपने पोर्ट के सुनना शुरू करने से पहले भी आधिकारिक बना रहता है।

• एक समर्पित SQLite समन्वयक मेटाडेटा निरीक्षण, निष्क्रिय स्वामी से पुनः प्राप्ति और लॉक प्रतिस्थापन को क्रमबद्ध करता है। स्वामी प्रक्रिया के क्रैश होने पर उसका एक्सक्लूसिव ट्रांज़ैक्शन अपने-आप रिलीज़ हो जाता है।

• यदि कोई लॉक फ़ाइल मौजूद नहीं है या दर्ज स्वामी प्रक्रिया समाप्त हो चुकी है, तो स्टार्टअप लॉक को पुनः प्राप्त करके जारी रहता है।

• यदि कोई भी लॉक सक्रिय रूप से धारण किया गया है, तो स्टार्टअप हार मानने से पहले अधिकतम 5 सेकंड (डिफ़ॉल्ट) तक पुनः प्रयास करता है:

  GatewayLockError("Gateway पहले से चल रहा है (pid <pid>); <ms>ms के बाद लॉक का समय समाप्त")

सॉकेट बाइंड

• EADDRINUSE पर, हाल ही में समाप्त हुई प्रक्रिया के बाद की TIME_WAIT अवधि से निकलने के लिए स्टार्टअप 500ms के अंतराल पर अधिकतम 20 बार (कुल मिलाकर लगभग 10 सेकंड) बाइंड करने का पुनः प्रयास करता है।

• यदि पुनः प्रयासों के बाद भी पोर्ट उपयोग में है:

  GatewayLockError("कोई अन्य Gateway इंस्टेंस पहले से ws://127.0.0.1:<port> पर सुन रहा है")

• अन्य बाइंड विफलताएँ:

  GatewayLockError("ws://127.0.0.1:<port> पर Gateway सॉकेट बाइंड करने में विफल: <cause>")

शटडाउन पर Gateway HTTP/WebSocket सर्वर बंद करता है और अपनी स्टेट तथा कॉन्फ़िगरेशन लॉक फ़ाइलें हटा देता है।

संचालन संबंधी टिप्पणियाँ

• यदि पोर्ट पर कोई अलग, गैर-Gateway प्रक्रिया मौजूद है, तो त्रुटि समान रहती है; पोर्ट खाली करें या openclaw gateway --port <port> से कोई अन्य पोर्ट चुनें।
• OPENCLAW_ALLOW_MULTI_GATEWAY=1 कई कॉन्फ़िगरेशन/रनटाइम इंस्टेंस की अनुमति देता है, साझा परिवर्तनशील स्टेट की नहीं। प्रत्येक इंस्टेंस को फिर भी एक अद्वितीय OPENCLAW_STATE_DIR चाहिए।
• सर्विस सुपरवाइज़र के अंतर्गत, ऊपर दी गई किसी भी त्रुटि का सामना करने वाली नई Gateway प्रक्रिया पहले मौजूदा प्रक्रिया पर /healthz की जाँच करती है। यदि वह प्रक्रिया स्वस्थ है, तो नई प्रक्रिया विफल होने के बजाय नियंत्रण उसी के पास रहने देती है। systemd पर यह कोड 78 के साथ बाहर निकलती है; यूनिट का RestartPreventExitStatus=78, Restart=always को लॉक या EADDRINUSE टकराव पर लगातार चलने से रोकता है। यदि मौजूदा प्रक्रिया कभी स्वस्थ नहीं होती, तो स्वास्थ्य-जाँच के पुनः प्रयास समय-सीमित रहते हैं और स्टार्टअप हमेशा चलते रहने के बजाय ऊपर दी गई लॉक त्रुटि के साथ विफल हो जाता है।
• macOS ऐप Gateway शुरू करने से पहले अपना हल्का PID सुरक्षा तंत्र बनाए रखता है; ऊपर दिए गए फ़ाइल लॉक और सॉकेट बाइंड ही वास्तविक रनटाइम प्रवर्तन हैं।

संबंधित

• एकाधिक Gateway - अद्वितीय पोर्ट के साथ एकाधिक इंस्टेंस चलाना
• समस्या निवारण - EADDRINUSE और पोर्ट टकराव का निदान करना