Natives आर्किटेक्चर

@f5-sales-demo/pi-natives एक तीन-स्तरीय स्टैक है:

1. TypeScript wrapper/API लेयर स्थिर JS/TS एंट्रीपॉइंट्स को एक्सपोज़ करती है।
2. Addon लोडिंग/वैलिडेशन लेयर वर्तमान रनटाइम के लिए .node बाइनरी को रिज़ॉल्व और वैलिडेट करती है।
3. Rust N-API मॉड्यूल लेयर JS को एक्सपोर्ट किए जाने वाले परफ़ॉर्मेंस-क्रिटिकल प्रिमिटिव्स को इम्प्लीमेंट करती है।

यह दस्तावेज़ गहन मॉड्यूल-स्तरीय डॉक्स के लिए आधार है।

इम्प्लीमेंटेशन फ़ाइलें

• packages/natives/src/index.ts
• packages/natives/src/native.ts
• packages/natives/src/bindings.ts
• packages/natives/src/embedded-addon.ts
• packages/natives/scripts/build-native.ts
• packages/natives/scripts/embed-native.ts
• packages/natives/package.json
• crates/pi-natives/src/lib.rs

लेयर 1: TypeScript wrapper/API लेयर

packages/natives/src/index.ts पब्लिक बैरल है। यह एक्सपोर्ट्स को क्षमता डोमेन के अनुसार समूहित करता है और रॉ N-API बाइंडिंग्स को सीधे एक्सपोज़ करने के बजाय टाइप्ड रैपर्स को री-एक्सपोर्ट करता है।

वर्तमान शीर्ष-स्तरीय समूह:

• Search/text प्रिमिटिव्स: grep, glob, text, highlight
• Execution/process/terminal प्रिमिटिव्स: shell, pty, ps, keys
• System/media/conversion प्रिमिटिव्स: image, html, clipboard, system-info, work

packages/natives/src/bindings.ts बेस इंटरफ़ेस कॉन्ट्रैक्ट को परिभाषित करता है:

• NativeBindings शेयर्ड सदस्यों (cancelWork(id: number)) से शुरू होता है
• मॉड्यूल-विशिष्ट बाइंडिंग्स प्रत्येक मॉड्यूल की types.ts से डिक्लेरेशन मर्जिंग द्वारा जोड़ी जाती हैं
• Cancellable उन रैपर्स के लिए timeout और abort-signal ऑप्शन्स को मानकीकृत करता है जो कैंसिलेशन एक्सपोज़ करते हैं

गारंटीड कॉन्ट्रैक्ट (API-फेसिंग): उपभोक्ता @f5-sales-demo/pi-natives से इम्पोर्ट करते हैं और टाइप्ड रैपर्स का उपयोग करते हैं।

इम्प्लीमेंटेशन डिटेल (बदल सकता है): डिक्लेरेशन मर्जिंग और आंतरिक रैपर लेआउट (src/<module>/index.ts, src/<module>/types.ts)।

लेयर 2: Addon लोडिंग और वैलिडेशन

packages/natives/src/native.ts रनटाइम addon चयन, वैकल्पिक एक्सट्रैक्शन, और एक्सपोर्ट वैलिडेशन का स्वामित्व रखता है।

कैंडिडेट रिज़ॉल्यूशन मॉडल

• प्लेटफ़ॉर्म टैग "${process.platform}-${process.arch}" है।
• वर्तमान में समर्थित टैग हैं:
  • linux-x64
  • linux-arm64
  • darwin-x64
  • darwin-arm64
  • win32-x64
• x64 CPU वेरिएंट्स का उपयोग कर सकता है:
  • modern (AVX2-सक्षम)
  • baseline (फ़ॉलबैक)
• गैर-x64 डिफ़ॉल्ट फ़ाइलनाम का उपयोग करता है (कोई वेरिएंट सफ़िक्स नहीं)।

फ़ाइलनाम रणनीति:

• रिलीज़: pi_natives.<platform>-<arch>.node
• x64 वेरिएंट रिलीज़: pi_natives.<platform>-<arch>-modern.node और/या ...-baseline.node
• PI_DEV लोडर डायग्नोस्टिक्स सक्षम करता है लेकिन addon फ़ाइलनाम नहीं बदलता

प्लेटफ़ॉर्म-विशिष्ट वेरिएंट डिटेक्शन

x64 के लिए, वेरिएंट चयन उपयोग करता है:

• Linux: /proc/cpuinfo
• macOS: sysctl machdep.cpu.leaf7_features / machdep.cpu.features
• Windows: System.Runtime.Intrinsics.X86.Avx2 के लिए PowerShell जाँच

PI_NATIVE_VARIANT स्पष्ट रूप से modern या baseline को बाध्य कर सकता है।

बाइनरी वितरण और एक्सट्रैक्शन मॉडल

packages/natives/package.json प्रकाशित फ़ाइलों में src और native दोनों शामिल करता है। native/ डायरेक्टरी प्रीबिल्ट प्लेटफ़ॉर्म आर्टिफ़ैक्ट्स स्टोर करती है।

कंपाइल्ड बाइनरीज़ (PI_COMPILED या Bun एम्बेडेड रनटाइम मार्कर्स) के लिए, लोडर व्यवहार है:

1. वर्शन्ड यूज़र कैश पथ जाँचें: <getNativesDir()>/<packageVersion>/...
2. लीगेसी कंपाइल्ड-बाइनरी लोकेशन जाँचें:
   • Windows: %LOCALAPPDATA%/xcsh (फ़ॉलबैक %USERPROFILE%/AppData/Local/xcsh)
   • गैर-Windows: ~/.local/bin
3. पैकेज्ड native/ और एक्ज़ीक्यूटेबल डायरेक्टरी कैंडिडेट्स पर फ़ॉलबैक करें

यदि एक एम्बेडेड addon मैनिफ़ेस्ट मौजूद है (embedded-addon.ts जो scripts/embed-native.ts द्वारा जेनरेट किया गया), तो native.ts लोडिंग से पहले मैचिंग एम्बेडेड बाइनरी को वर्शन्ड कैश डायरेक्टरी में मटीरियलाइज़ कर सकता है।

वैलिडेशन और विफलता मोड

require(candidate) के बाद, validateNative(...) आवश्यक एक्सपोर्ट्स की पुष्टि करता है (उदाहरण के लिए grep, glob, highlightCode, PtySession, Shell, getSystemInfo, getWorkProfile, invalidateFsScanCache)।

विफलता पथ स्पष्ट हैं:

• असमर्थित प्लेटफ़ॉर्म टैग: समर्थित प्लेटफ़ॉर्म सूची के साथ त्रुटि फेंकता है
• कोई लोड करने योग्य कैंडिडेट नहीं: सभी प्रयास किए गए पथों और सुधार संकेतों के साथ त्रुटि फेंकता है
• गायब एक्सपोर्ट्स: सटीक गायब नामों और रीबिल्ड कमांड के साथ त्रुटि फेंकता है
• एम्बेडेड एक्सट्रैक्शन त्रुटियाँ: डायरेक्टरी/राइट विफलताओं को रिकॉर्ड करता है और उन्हें अंतिम लोड डायग्नोस्टिक्स में शामिल करता है

गारंटीड कॉन्ट्रैक्ट (API-फेसिंग): addon लोड या तो वैलिडेटेड बाइंडिंग सेट के साथ सफल होता है या कार्रवाई योग्य त्रुटि टेक्स्ट के साथ तुरंत विफल होता है।

इम्प्लीमेंटेशन डिटेल (बदल सकता है): सटीक कैंडिडेट खोज क्रम और कंपाइल्ड-बाइनरी फ़ॉलबैक पथ क्रम।

लेयर 3: Rust N-API मॉड्यूल लेयर

crates/pi-natives/src/lib.rs Rust एंट्री मॉड्यूल है जो एक्सपोर्टेड मॉड्यूल स्वामित्व घोषित करता है:

• clipboard
• fd
• fs_cache
• glob
• glob_util
• grep
• highlight
• html
• image
• keys
• prof
• ps
• pty
• shell
• system_info
• task
• text

ये मॉड्यूल native.ts द्वारा उपभोग और वैलिडेट किए जाने वाले N-API सिम्बल्स को इम्प्लीमेंट करते हैं। JS-स्तरीय नाम packages/natives/src में TS रैपर्स के माध्यम से प्रदर्शित किए जाते हैं।

गारंटीड कॉन्ट्रैक्ट (API-फेसिंग): Rust मॉड्यूल एक्सपोर्ट्स को validateNative और रैपर मॉड्यूल्स द्वारा अपेक्षित बाइंडिंग नामों से मेल खाना चाहिए।

इम्प्लीमेंटेशन डिटेल (बदल सकता है): आंतरिक Rust मॉड्यूल विभाजन और हेल्पर मॉड्यूल सीमाएँ (glob_util, task, आदि)।

स्वामित्व सीमाएँ

आर्किटेक्चर स्तर पर, स्वामित्व निम्नानुसार विभाजित है:

• TS wrapper/API स्वामित्व (packages/natives/src)
  • पब्लिक API ग्रुपिंग, ऑप्शन टाइपिंग, और स्थिर JS एर्गोनॉमिक्स
  • कॉलर्स को एक्सपोज़ किया गया कैंसिलेशन सरफ़ेस (timeoutMs, AbortSignal)
• लोडर स्वामित्व (packages/natives/src/native.ts)
  • रनटाइम बाइनरी चयन
  • CPU वेरिएंट चयन और ओवरराइड हैंडलिंग
  • कंपाइल्ड-बाइनरी एक्सट्रैक्शन और कैंडिडेट प्रोबिंग
  • आवश्यक नेटिव एक्सपोर्ट्स की कठोर वैलिडेशन
• Rust स्वामित्व (crates/pi-natives/src)
  • एल्गोरिदमिक और सिस्टम-स्तरीय इम्प्लीमेंटेशन
  • प्लेटफ़ॉर्म-नेटिव व्यवहार और परफ़ॉर्मेंस-संवेदनशील लॉजिक
  • N-API सिम्बल इम्प्लीमेंटेशन जिसे TS रैपर्स उपभोग करते हैं

रनटाइम फ़्लो (उच्च स्तरीय)

1. उपभोक्ता @f5-sales-demo/pi-natives से इम्पोर्ट करता है।
2. रैपर मॉड्यूल सिंगलटन native बाइंडिंग में कॉल करता है।
3. native.ts प्लेटफ़ॉर्म/आर्च/वेरिएंट के लिए कैंडिडेट बाइनरी चुनता है।
4. कंपाइल्ड डिस्ट्रीब्यूशन के लिए वैकल्पिक एम्बेडेड बाइनरी एक्सट्रैक्शन होता है।
5. Addon लोड किया जाता है और एक्सपोर्ट सेट वैलिडेट किया जाता है।
6. रैपर कॉलर को टाइप्ड रिज़ल्ट्स लौटाता है।

शब्दावली

• Native addon: एक .node बाइनरी जो Node-API (N-API) के माध्यम से लोड की जाती है।
• प्लेटफ़ॉर्म टैग: रनटाइम ट्यूपल platform-arch (उदाहरण के लिए darwin-arm64)।
• वेरिएंट: x64 CPU-विशिष्ट बिल्ड फ़्लेवर (modern AVX2, baseline फ़ॉलबैक)।
• रैपर: TS फ़ंक्शन/क्लास जो रॉ नेटिव एक्सपोर्ट्स पर टाइप्ड API प्रदान करता है।
• डिक्लेरेशन मर्जिंग: TS तकनीक जो मॉड्यूल types.ts फ़ाइलों द्वारा NativeBindings को विस्तारित करने के लिए उपयोग की जाती है।
• कंपाइल्ड बाइनरी मोड: रनटाइम मोड जहाँ CLI बंडल किया जाता है और नेटिव addons केवल पैकेज-लोकल पथों के बजाय एक्सट्रैक्टेड/कैश पथों से रिज़ॉल्व किए जाते हैं।
• एम्बेडेड addon: बिल्ड आर्टिफ़ैक्ट मेटाडेटा और फ़ाइल संदर्भ जो embedded-addon.ts में जेनरेट किए जाते हैं ताकि कंपाइल्ड बाइनरीज़ मैचिंग .node पेलोड्स एक्सट्रैक्ट कर सकें।
• वैलिडेशन गेट: validateNative(...) जाँच जो आवश्यक एक्सपोर्ट्स गायब होने पर पुरानी/बेमेल बाइनरीज़ को अस्वीकार करती है।