बहु-सेवा Rust बैकएंड के लिए कार्गो कार्यस्थान

एक कार्यस्थान कार्गो एक एकल Cargo.lock और एक एकल लक्ष्य निर्देशिका के तहत कई क्रेटों को समूहित करता है - वही कार्यक्षमता जो रस्ट का पैकेज प्रबंधक इस मामले के लिए प्रदान करता है। ग्यारह अलग-अलग रस्ट बायनेरिज़, प्रत्येक अपने स्वयं के भंडार में, पहली नज़र में अधिक स्वतंत्र लगते हैं। व्यवहार में, इसका मतलब है ग्यारह अलग-अलग Cargo.lock, ग्यारह संस्करण रिज़ॉल्यूशन जो समय के साथ भिन्न हो सकते हैं, और कोई गारंटी नहीं है कि दो सेवाएँaxum या sqlxके एक ही संस्करण को संकलित करती हैं।

A Cargo workspace solves this at the package manager level, not the team discipline level. All members share a single Cargo.lock at the root: a common dependency is resolved once, to an identical version, for the entire graph. This is also what makes a cross-service refactor (changing a signature in aura-core, for example) visible to a single cargo build --workspace, rather than discovered service by service in production. This is one of the choices that distinguishes our 100% unified Rust core from a heterogeneous stack assembled service by service.

यह सब घोषणा [workspace] और इसकी सूची membersसे शुरू होता है। ऑराबेस में, यह सूची services/*जैसे सामान्य पैटर्न द्वारा उत्पन्न होने के बजाय, हस्तलिखित है, भूमिका - सेवाओं, उपकरणों, libs द्वारा समूहीकृत है।

[workspace]
resolver = "2"

members = [
    # सेवाएं
    "services/aura-gateway",
    "services/aura-auth",
    "services/aura-db",
    # … 8 अन्य सेवाएँ (आभा-वास्तविक समय, आभा-भंडारण, आभा-एआई,…)
    # औजार
    "aura-cli",
    # लिब्ज़
    "libs/aura-core",
    # …4 अन्य कार्य
    "aurabase-rs",
]

resolver = "2" कोई कॉस्मेटिक विवरण नहीं है. कार्गो का रिज़ॉल्वर v2 build-dependencies और लक्ष्य-विशिष्ट निर्भरता (उदाहरण के लिएtarget.'cfg(windows)') की कार्यक्षमता को बाकी ग्राफ़ से अलग करता है - वे अब अंतिम बाइनरी में लीक नहीं होते हैं। यह कार्यक्षेत्र के सभी सदस्यों के बीच समान निर्भरता के संस्करणों को भी एकीकृत करता है जो इसे साझा करते हैं: एक axum, केवल एक बार, ग्यारह स्वतंत्र संकल्प नहीं।

[workspace.package] एक बार सामान्य फ़ील्ड - संस्करण, संस्करण, लेखक, लाइसेंस - घोषित करता है कि प्रत्येक टोकरा उन्हें कॉपी करने के बजाय version.workspace = true के साथ प्राप्त कर सकता है।

[workspace.package]
version = "0.1.1"
edition = "2021"

# Services/aura-gateway/Cargo.toml
[package]
name = "aura-gateway"
version.workspace = true

ऑराबेस की सभी ग्यारह सेवाएँ इसी पैटर्न का पालन करती हैं। दो क्रेट विचलन करते हैं, और यह इस लेख को तैयार करते समय पाई गई दो विसंगतियों में से पहली है: aura-cli हार्ड कॉपी में version = "0.2.0" घोषित करता है, और lib libs/aura-migrations version = "0.1.0" घोषित करता है - दोनों कार्यक्षेत्र के 0.1.1 से भिन्न हैं।

[workspace.dependencies] कई क्रेट्स द्वारा साझा की गई निर्भरता को केंद्रीकृत करता है। प्रत्येक सेवा अपनी स्वयं की संस्करण बाधा निर्धारित करने के बजाय इसे { workspace = true } के साथ संदर्भित करती है।

[workspace.dependencies]
axum = { version = "0.8", features = ["ws", "multipart", "macros"] }
sqlx = { version = "0.8", default-features = false, features = […] }
tower_governor = { version = "0.8", features = ["axum"] }
governor = "0.10"

# Services/aura-gateway/Cargo.toml - कार्यक्षेत्र गवर्नर को इनहेरिट नहीं करता है
governor = "0.8"  # स्थानीय संस्करण, भिन्न

यह दूसरी वास्तविक विसंगति है: कार्यक्षेत्र 0.10संस्करण में governor को केंद्रीकृत करता है, लेकिन aura-gateway विरासत में मिलने के बजाय अपनी स्वयं की लाइन governor = "0.8" को पुनः घोषित करता है - गेटवे अपनी दर को नंगे governor क्रेट के साथ लागू करता है, जब aura-auth, aura-ai, aura-db और aura-functions मिडलवेयर में tower_governor से गुजरें। एक कार्यक्षेत्र विचलन को नहीं रोकता है: यह केवल इसे दृश्यमान बनाता है, अगर हम तुलना करने में परेशानी उठाते हैं।

हालाँकि, सभी निर्भरताएँ केंद्रीकृत होने के लायक नहीं हैं। wasmtime [workspace.dependencies]में कहीं भी दिखाई नहीं देता है: केवल एक टोकरा, aura-functions, इसे अपने WASM रनटाइम के लिए उपयोग करता है, इसलिए यह स्थानीय रूप से घोषित रहता है। हम जो नियम लागू करते हैं: दो या दो से अधिक क्रेट्स साझा करने के क्षण से ही कार्यस्थल स्तर पर निर्भरता बढ़ाएं, इससे पहले नहीं।

पाँच साझा कार्य (aura-core, aura-crypto, aura-db-adapters, aura-migrations, aura-telemetry) को [workspace.dependencies] - aura-core = { path = "libs/aura-core" } में पथ निर्भरता के रूप में घोषित किया जाता है - फिर प्रत्येक सेवा चुनती है कि उसे वास्तव में किनकी आवश्यकता है।

परिणामी ग्राफ़ एक फ़ाइल से दूसरी फ़ाइल में पढ़ने योग्य रहता है। aura-gateway केवल पांच आंतरिक कार्यों में से तीन पर निर्भर करता है - aura-core, aura-crypto और aura-telemetry। रूट करने के लिए पर्याप्त है, PostgREST साइडकार के लिए एक JWT पर हस्ताक्षर करें और aura-db-adapters और न ही aura-migrationsको छुए बिना, इसके निशान निर्यात करें। aura-provisioner``aura-migrationsजोड़ता है: यह एक प्रोजेक्ट के निर्माण के परिणामस्वरूप स्कीमा माइग्रेशन को दोबारा चलाता है।

सबसे संकीर्ण मामला aura-migratorहै, समर्पित बाइनरी जो सीआई/सीडी माइग्रेशन करता है। ऑराबेस के आंतरिक कार्यों में, इसके उत्पादन [dependencies] में केवलaura-migrations सूचीबद्ध है - aura-core केवल परीक्षण के लिए इसके [dev-dependencies]में दिखाई देता है। इसलिए उत्पादन के लिए वितरित बाइनरी में कोईaura-core कोड शामिल नहीं है; यह केवल cargo testके दौरान मौजूद रहता है।

हर बार जब आप एक नई तैनाती योग्य प्रक्रिया चाहते हैं तो कार्यक्षेत्र को एक नया सदस्य बनाने की आवश्यकता नहीं होती है। aura-realtime कार्यक्षेत्र का एक एकल सदस्य बना हुआ है, लेकिन इसका Cargo.toml एक ही साझा [lib]के आसपास तीन अलग-अलग [[bin]] तालिकाओं की घोषणा करता है।

[lib]
name = "aura_realtime"

[[bin]]
name = "aura-realtime"

[[bin]]
name = "aura-realtime-cdc-worker"
path = "src/bin/cdc_worker.rs"

[[bin]]
name = "aura-realtime-ws-front"
path = "src/bin/ws_front.rs"

घोषणापत्र स्वयं दोनों के बीच की सीमा का दस्तावेजीकरण करता है। cdc-worker पोलिंग द्वारा पोस्टग्रेज़ परिवर्तनों को कैप्चर करता है और पब/सब कोर (Client::publish_with_headers) में NATS पर प्रकाशित करता है, बिना वेबसॉकेट सर्वर खोले - जेटस्ट्रीम, इसी सेवा में, विशेष रूप से क्रॉस-इंस्टेंस उपस्थिति केवी की सेवा करता है, सीडीसी फैन-आउट की नहीं। ws-front केवल NATS का उपभोग करता है और WebSocket/SSE कनेक्शन रखता है, कभी भी CDC को छुए बिना - पूर्ण विवरण वास्तविक समय इंजन दस्तावेज़ में हैं। दोनों बायनेरिज़ [lib]के माध्यम से समान आरएलएस फ़िल्टरिंग कोड साझा करते हैं, लेकिन कुबेरनेट्स में स्वतंत्र रूप से तैनात और स्केल करते हैं। एक नए कार्यक्षेत्र सदस्य के बजाय एक क्रेट में कई बायनेरिज़ चुनने के लिए यह सही संकेत है: समान आंतरिक तर्क, विभिन्न परिनियोजन टोपोलॉजी।

aura-edge-runtime फ़ोल्डर ऑराबेस रिपॉजिटरी में मौजूद है। हालाँकि, इसमें कोई Cargo.toml नहीं है - केवल टाइपस्क्रिप्ट (index.ts, envelope.ts), और यह रूट वर्कस्पेस की members सूची में कहीं भी दिखाई नहीं देता है।

पाठ सामान्यीकरण करता है: services/ के सबफ़ोल्डर्स को सूचीबद्ध करके रस्ट बैकएंड की सेवाओं की गणना करने से एक गलत संख्या मिलती है। कार्यक्षेत्र में वास्तव में क्या संकलित होता है, इस पर केवल रूट Cargo.toml ही आधिकारिक है।

कार्यक्षेत्र के मूल में घोषित [profile.release] रिलीज़ मोड में संकलित सभी सदस्यों पर लागू होता है - समायोजित करने के लिए केवल एक स्थान, ग्यारह पर नहीं। कार्गो अपने संकलन प्रोफ़ाइल संदर्भमें सभी उपलब्ध कुंजियों का दस्तावेजीकरण करता है; ऑराबेस केवल पाँच को सक्रिय करता है।

[profile.release]
lto = "thin"          # एलटीओ क्रॉस-क्रेट, प्रदर्शन/निर्माण समय संतुलन
codegen-units = 1     # सर्वोत्तम समग्र इनलाइनिंग
panic = "unwind"   # टोकियो/एक्सम → 500 द्वारा अलग की गई घबराहट, वैश्विक दुर्घटना नहीं
strip = "symbols"
opt-level = 3

"abort" के बजाय panic = "unwind" का विकल्प सीधे फ़ाइल टिप्पणी में दर्ज किया गया है: एक एक्सम हैंडलर में घबराहट को टोकियो द्वारा इंटरसेप्ट किया जाता है, कार्य 500 लौटाता है, और प्रक्रिया अन्य समवर्ती अनुरोधों को पूरा करना जारी रखती है।abort का प्रदर्शन लाभ अंतर-क्वेरी अलगाव के नुकसान के लायक नहीं है।

एक एकीकृत कार्यक्षेत्र निर्भरता संस्करण सेट करता है, लेकिन कंपाइलर का संस्करण नहीं। rust-toolchain.toml, मूल रूप से, रिपॉजिटरी में cargo या rustc पर किसी भी सीधी कॉल के लिए टूलचेन (channel = "1.93" आज) को फ्रीज कर देता है।

यह फ़ाइल सटीक रूप से मौजूद है क्योंकि एक मूक बहाव हुआ: एक सीआई कार्रवाई ने दिन के stable चैनल को rust-toolchain.tomlको पढ़े बिना स्थापित किया, जबकि रिलीज डॉकर छवि जमे हुए संस्करण के साथ संकलित हुई। एक कमिट आज के स्थिर रस्ट के साथ सभी परीक्षण पास कर सकता है, फिर छवि निर्माण में सफलता प्राप्त कर सकता है - मर्ज के बाद खोजा गया, पहले नहीं। rustupकिसी भी प्रत्यक्ष कमांड के लिए इस फ़ाइल का सम्मान करता है: सीआई वर्कफ़्लो को प्रभावित किए बिना, यह एकमात्र आवश्यक फिक्स था।

# संपूर्ण कार्यक्षेत्र संकलित करें
cargo build --workspace

# एक एकल क्रेट का परीक्षण करें (संपूर्ण कार्यस्थान का नहीं)
cargo test -p aura-auth

# संपूर्ण कार्यक्षेत्र पर सख्त प्रतिबंध, चेतावनियाँ = त्रुटियाँ
cargo clippy --workspace --all-targets -- -D warnings

# का प्रारूपण
cargo fmt --all

एक आखिरी विवरण, उन लोगों के लिए जो इसे निष्पादित करने से पहले मैनिफ़ेस्ट पढ़ते हैं: aura-cli क्रेट एक बाइनरी संकलित करता है जिसकी तालिका [[bin]] इसे aurabaseनाम देती है, न कि aura। प्रकाशित एनपीएम रैपर, @aurabase/cli, दो कमांड्स को उजागर करता है - aura और aurabase दोनों एक ही स्क्रिप्ट की ओर इशारा करते हैं। [[bin]] कार्गो का नाम, टोकरे का नाम, और एनपीएम रैपर द्वारा उजागर किया गया नाम तीन अलग-अलग चीजें हैं; अन्य दो में से किसी का भी अनुमान नहीं लगाया जा सकता।

हर बार जब आप कार्गो कार्यक्षेत्र में एक टोकरा जोड़ते हैं तो पाँच निर्णय सामने आते हैं। ऊपर दिए गए ऑराबेस उदाहरण के आधार पर, यहां प्रत्येक को घोषित किया गया है।

किसी मौजूदा कार्गो कार्यक्षेत्र का ऑडिट करने के लिए - आपका या उस प्रोजेक्ट का जिसे आप संभाल रहे हैं - ऊपर दर्ज की गई विसंगतियों के प्रकार का पता लगाने के लिए चार जांचें पर्याप्त हैं:

1. प्रत्येक टोकरे के [workspace.package].version की version से तुलना करें - एक अलग मान आवश्यक रूप से एक बग नहीं है, लेकिन दस्तावेजीकरण के लायक है।
2. प्रत्येक टोकरे द्वारा स्थानीय रूप से घोषित निर्भरता के साथ [workspace.dependencies] की तुलना करें - विभिन्न संस्करणों के साथ दोनों तरफ मौजूद नामों को देखें।
3. रूट Cargo.toml में members सूची की तुलना रिपॉजिटरी में वास्तविक सबफ़ोल्डर्स से करें - members से गायब फ़ोल्डर आवश्यक रूप से एक चूक नहीं है।
4. यह मानने के बजाय कि यह क्रेट नाम या संभावित एनपीएम रैपर द्वारा उजागर नाम से मेल खाता है, प्रत्येक संकलित बाइनरी ([[bin]] name) के वास्तविक नाम की जांच करें।