निष्पादन सिमेंटिक्स, बाधाएँ, सुरक्षा

यह पृष्ठ बताता है कि Script रनटाइम पर कैसे काम करता है (क्रम, ट्रांज़ैक्शन, एरर, लॉकिंग), सेव करते समय किन स्थैतिक बाधाओं के अधीन होता है, और इसका सुरक्षा मॉडल क्या है। सिंटैक्स के लिए Statement कैटलॉग और मान अभिव्यक्ति, और व्यावहारिक संयोजन के लिए कुकबुक देखें।

निष्पादन क्रम

• statements ऊपर से नीचे क्रमिक रूप से निष्पादित होते हैं। Return पर पहुँचते ही उसी बिंदु पर समाप्त हो जाता है।
• निष्पादन कॉल के अनुरोध को संभालने वाले पथ पर इनलाइन होता है। कॉल की प्रतिक्रिया ही निष्पादन का परिणाम है (प्रतिक्रिया का स्वरूप Script अवलोकन में अनुरोध और प्रतिक्रिया देखें), और एक निष्पादन को मिलने वाला समय नीचे समय बजट में दिया गया है।

निष्पादन सिमेंटिक्स

Guard (पूर्व शर्त)

कोई समर्पित guard statement नहीं है। इसे If और then:[Return] से व्यक्त किया जाता है। शर्त के उल्लंघन पर परिणाम लौटाया जाता है और इसके बाद के statement निष्पादित नहीं होते (guard रहित Script भी निश्चित रूप से संभव है)।

{ "type": "If", "condition": { "<": [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] },
  "then": [ { "type": "Return", "value": { "ok": false, "reason": "insufficient credit" }, "statusCode": 402 } ] }

ट्रांज़ैक्शन नहीं और best-effort क्षतिपूर्ति

Script ट्रांज़ैक्शन नहीं है। विफलता पर इंजन अब तक किए गए कार्यों की क्षतिपूर्ति (compensation) का प्रयास करता है और एरर का कारण लौटाता है, पर इसकी निम्नलिखित सीमाएँ हैं (डिज़ाइन के तहत स्वीकार्य)।

• डिलीट को पूर्ववत करना एक नया sys.id बनाता है, जिससे इसे इंगित करने वाले संदर्भ टूट जाते हैं।
• बाहरी प्रभाव (Http) अपरिवर्तनीय है (जो कॉल पहले ही जा चुकी है और उसका शुल्क वापस नहीं लिया जा सकता)।
• क्षतिपूर्ति बिल्कुल भी न चलने के कारण अप्रतिपूरित अवस्था रह सकती है।

यदि वास्तविक परमाणुता (atomicity) चाहिए, तो उपयोगकर्ता Script से सीधे क्षतिपूर्ति करता है, या अपरिवर्तनीय कार्यों (जैसे बाहरी कॉल) को सबसे अंत में रखता है। "जिसमें शृंखलन तो हो जाता है पर रोलबैक नहीं होता, और फिर भी जो सुरक्षित दिखता है" ऐसा क्रम सबसे खतरनाक है।

आशावादी लॉकिंग

update/patch की टक्कर को ResourceUpdate और ResourcePatch के version से सीमित किया जाता है। version (मान अभिव्यक्ति, Int) देने पर लक्ष्य के वर्तमान sys.version से मेल खाने पर ही अद्यतन होता है, और मेल न खाने पर वर्ज़न टकराव एरर के साथ abort हो जाता है (Try/catch से स्थानीय रूप से संभाला जा सकता है)। इसे छोड़ देने पर बिना जाँच के last-write-wins होता है। आमतौर पर ResourceRead या ResourceFind से पहले पढ़कर उसका sys.version पास किया जाता है (कुकबुक में आशावादी लॉकिंग CAS देखें)।

origin के आधार पर लेखन

लेखन हमेशा origin (draft) में परिलक्षित होता है, और delivery (CDA/ACDA) पर दृश्यता publish से नियंत्रित होती है (ResourceCreate/ResourceUpdate/ResourcePatch का publish, या ResourcePublish/ResourceUnpublish)।

किसे विफलता माना जाता है

• वास्तविक विफलता एक statement रनटाइम एरर है: Http का अंतिम status 400 या उससे अधिक होना (4xx·5xx; ignoreStatusCode: true होने पर विफलता नहीं) या टाइमआउट, प्रतिक्रिया body का 10MiB से अधिक होना, संसाधन कार्य की विफलता (लक्ष्य न मिलना, वर्ज़न टकराव, असमर्थित संक्रिया आदि)। ऐसी विफलताओं में इंजन abort करके क्षतिपूर्ति करता है, और Try/catch/finally से स्थानीय रूप से संभाला जा सकता है।
• Return कोई एरर नहीं, बल्कि एक सामान्य समय-पूर्व समाप्ति है। यह catch का लक्ष्य नहीं है (उपयोगकर्ता throw की कोई अवधारणा नहीं है)।
• catch के भीतर /error से { message } को संदर्भित किया जाता है। यह नहीं बताया जाता कि विफलता किस statement में हुई।

सर्वर-साइड एग्रीगेशन केवल गिनती तक

गिनती ResourceCount सर्वर पर करता है। यह आइटम पढ़कर नहीं लाता, इसलिए इस पर संसाधित आइटम संख्या की ऊपरी सीमा लागू नहीं होती।

sum और group-by के लिए समर्पित कोई सर्वर कार्य नहीं है। ऐसे एग्रीगेशन के लिए ResourceForEach से पुनरावृत्ति करते हुए SetVar और JsonLogic से स्वयं गणना करनी पड़ती है, इसलिए वह संसाधित आइटम संख्या की ऊपरी सीमा से बँधी होती है (कई मिलियन रिकॉर्ड के एग्रीगेशन के लिए अनुपयुक्त)। केवल गिनती चाहिए, तो पुनरावृत्ति किए बिना ResourceCount का उपयोग करें।

प्रतीक्षा और विलंब नहीं

Script में Delay statement नहीं है। Script एक बार निष्पादित होकर समाप्त हो जाता है, और बाहरी job के समाप्त होने तक भीतर प्रतीक्षा या पोलिंग नहीं करता।

स्थैतिक बाधाएँ (सेव करते समय जाँच)

नीचे दी गई बातें Script को सेव (बनाते/संशोधित करते) करते समय जाँची जाती हैं। उल्लंघन होने पर सेव अस्वीकार कर दिया जाता है (यह रनटाइम पर नहीं, बल्कि रचना के समय की विफलता है)। कौन-सा उल्लंघन किस कोड के साथ अस्वीकृत होता है, यह त्रुटियाँ में दिया गया है।

ऊपर की तालिका में दी गई निश्चित सीमाएँ प्लेटफ़ॉर्म द्वारा तय किए गए मान हैं, इसलिए वे प्लान से निरपेक्ष रूप से समान रहती हैं। इसके विपरीत, प्रति परिभाषा कुल statement संख्या और बाहरी कॉल संख्या प्लान-आधारित सीमाएँ हैं। ये दोनों कोई वैधता त्रुटि नहीं, बल्कि प्लान सीमा हैं, इसलिए इन्हें पार करने पर सहेजना/संशोधन प्लान सीमा पार होने के कारण अस्वीकृत होता है (वही परिभाषा किसी उच्च प्लान में स्वीकार्य होती है) और अपग्रेड से खुल जाता है। प्लान-आधारित मान मूल्य योजनाएं में हैं।

Media फ़ाइल इंजेस्ट, Http·EmailSend जैसी बाहरी कॉल के विपरीत, प्रति परिभाषा बाहरी कॉल की सीमा में शामिल नहीं होती।

ResourceForEach child रखने वाला एक composite statement है, इसलिए वह स्वयं बाहरी कॉल की संख्या में नहीं गिना जाता। onEach के भीतर के बाहरी कॉल statement (Http·EmailSend) गिने जाते हैं (स्थैतिक रूप से 1 गिने जाते हैं पर पुनरावृत्ति में हर आइटम पर वास्तव में निष्पादित होते हैं)। onEach में बाहरी कॉल या Media फ़ाइल इंजेस्ट रखी जा सकती है, और यही Loop की body पर भी लागू होता है। पुनरावृत्ति वास्तव में कितने चक्कर लगाती है, यह इस गिनती में नहीं आता, बल्कि नीचे दिए समय बजट में गुणा के रूप में आता है।

मान की लंबाई की ऊपरी सीमा (रनटाइम)

हस्ताक्षर और टेक्स्ट प्रोसेसिंग वाले statement, तथा Cache द्वारा संभाले जाने वाले मान के आकार की एक ऊपरी सीमा है। यह अभिव्यक्ति की लंबाई नहीं, बल्कि उस अभिव्यक्ति के resolve हुए मान की लंबाई है ({ /rawPayload } के सोलह अक्षर कई दसियों KB की ओर संकेत करते हैं), और इसीलिए इसकी जाँच सेव के समय नहीं, बल्कि निष्पादन के दौरान होती है।

• चारों अन्य रनटाइम विफलताओं जैसी ही हैं, इसलिए इन्हें Try/catch से स्थानीय रूप से संभाला जा सकता है।
• Signature की ऊपरी सीमा वास्तविक प्रदाताओं द्वारा भेजी जाने वाली body के आकार के अनुरूप रखी गई है (भुगतान इवेंट कुछ KB के, और ऑर्डर webhook कई दसियों KB तक के होते हैं)। Hash कुछ field जोड़ने की जगह है, इसलिए वह बहुत संकरी है।
• Regex.pattern के 128 अक्षर ऊपर स्थैतिक बाधाएँ में दी गई सेव-समय की जाँच हैं। यह लंबाई भगदड़ रोकने का उपाय नहीं है ((a+)+$ छह अक्षरों में भी खतरनाक है)। भगदड़ को रोकने वाले उपाय हैं pattern को केवल लिटरल के रूप में लिखने देने वाला नियम और नीचे दिया समय बजट; लंबाई जो वादा करती है वह केवल इतना है कि इंसान उसे पढ़कर समीक्षा कर सके।

समय बजट (रनटाइम)

एक निष्पादन को मिलने वाला समय एक ही सूत्र से तय होता है: min(30 सेकंड + statements द्वारा घोषित समय का योग, 180 सेकंड)।

• बजट उसी Script से गिना जाता है। मूल बजट में केवल वही समय जोड़ा जाता है जो परिभाषा ने घोषित किया है। घोषित समय केवल एक ही है: Http और EmailSend का timeoutMs। Http हर retry पर अपना timeoutMs दोबारा उपयोग करता है, इसलिए उसे timeoutMs × (1 + retry) के रूप में गिना जाता है, और EmailSend retry नहीं करता, इसलिए उसे एक बार गिना जाता है। timeoutMs न लिखने पर डिफ़ॉल्ट मान (Http 30 सेकंड, EmailSend 10 सेकंड) से गिना जाता है।
• जिन कार्यों का कोई घोषित समय नहीं होता, वे 30 सेकंड के मूल बजट में से ही चलते हैं। संसाधन का पठन और लेखन, Media फ़ाइल इंजेस्ट, तथा पुनरावृत्ति भीतर जो काम करती है, ये सब इसी में आते हैं। इसीलिए मूल बजट कोई औपचारिक मान नहीं, बल्कि एक वास्तविक हिस्सा है।
• जोड़ने का तरीका statement की संरचना का पालन करता है। क्रम से रखे गए statement जुड़ते जाते हैं, If दोनों शाखाओं में से बड़ी को और Parallel अपनी शाखाओं में से सबसे बड़ी को लेता है। Loop अपनी body को पुनरावृत्तियों की संख्या (maxIterations, घोषित न हो तो 10,000) से और ResourceForEach अपने onEach को संसाधित आइटम की संख्या (limit, घोषित न हो तो 10,000) से गुणा करता है।
• जिस पुनरावृत्ति में कोई बाहरी कॉल नहीं है, उसका घोषित समय 0 होता है। इसलिए 30 सेकंड का मूल बजट ही उसकी वास्तविक सीमा बन जाता है, और पुनरावृत्ति वाली Script व्यवहार में यहीं अटकती है।
• 180 सेकंड की ऊपरी सीमा सेव को नहीं रोकती, बल्कि निष्पादन को वहीं काट देती है। गणना का परिणाम ऊपरी सीमा से अधिक हो, तब भी वह Script सेव होती है और चलती है, और 180 सेकंड पर पहुँचते ही वहीं रुक जाती है।

प्रति प्लान संख्या सीमा

Script की प्रति Organization संख्या प्लान के अनुसार सीमित होती है।

इससे अलग, एक Script परिभाषा जितने statement और बाहरी कॉल (Http·EmailSend) रख सकती है उसकी संख्या भी प्लान के अनुसार सीमित है। परिभाषा को सहेजते/संशोधित करते समय उस प्लान की सीमा पार होने पर अस्वीकृत हो जाता है, और ठोस मानों के लिए मूल्य योजनाएं देखें।

सीमा तक पहुँचने पर नए Script का निर्माण अस्वीकार कर दिया जाता है।

सुरक्षा मॉडल

secret हेडर

Http.headers का secret:true आइटम केवल CMA (एडमिन) के लिए होता है, यह अंतिम उपयोगकर्ता (ServiceUser) को उजागर नहीं होता और केवल भेजने से ठीक पहले डिक्रिप्ट होता है। LLM API key जैसे रहस्य यहाँ रखे जाते हैं (App Bundle में पैक होते समय भी secret मान मास्क कर दिया जाता है और मूल Space से बाहर नहीं जाता)।

Signature का secret Space के भीतर यह व्यवहार नहीं पाता। वह एन्क्रिप्ट किए बिना, परिभाषा में लिखे रूप में ही संग्रहीत होता है, इसलिए जो भूमिका उस Script को पढ़ सकती है उसे यह मान दिख जाता है। सदस्य (ServiceUser) Script की परिभाषा नहीं पढ़ सकते (पठन और रचना केवल CMA पर होते हैं, और ACMA में Script API नहीं है)। सत्यापन की key रखने वाले Script के लिए उसे पढ़ सकने वाली भूमिकाओं को सीमित रखना अधिक सुरक्षित है।

Space से बाहर जाने की बात अलग है। जब वह Script किसी App Bundle में पैक होती है, तब Signature का secret मास्क कर दिया जाता है और मूल Space से बाहर नहीं जाता। Http.headers में secret फ़्लैग वाले आइटम और Authorization हेडर छिपाए जाते हैं, जबकि Signature का secret बिना किसी शर्त छिपाया जाता है, क्योंकि वह field स्वयं ही हस्ताक्षर की key है। If·Loop·Try के भीतर नेस्ट किया गया Signature भी साथ ही छिप जाता है।

निष्पादन पहचान और प्राधिकरण

• निष्पादन पहचान: निष्पादन के दौरान सभी संसाधन कार्य उस उपयोगकर्ता की पहचान से किए जाते हैं जिसने /execute को कॉल किया। बनाए या संशोधित होने वाले संसाधन के createdBy/updatedBy कॉलर होते हैं, और createdBy: ":self" स्कोप भी कॉलर के आधार पर हल होता है। अपवाद अनाम कॉल है। /execute/anonymous से आए निष्पादन में कोई कॉलर नहीं होता, इसलिए ये दोनों बातें रचयिता के आधार पर हल होती हैं (अनाम कॉल)।
• प्राधिकरण की सीमाएँ दो हैं, और रनटाइम पर हर statement के लिए संसाधन अनुमति की पुनः जाँच नहीं होती।
  1. रचना के समय (सेव): Script को सेव करते समय जाँच होती है कि रचयिता के पास उन statement द्वारा उपयोग किए जाने वाले संसाधन और एक्शन की अनुमति वास्तव में है या नहीं। एक भी न हो, तो सेव अस्वीकार हो जाता है। यानी, बिना अनुमति वाले कार्य वाला Script शुरू से ही सेव नहीं होता। संसाधन चुनने वाला statement, चाहे वह leaf हो या block रखने वाला ResourceForEach, सभी इस जाँच से गुज़रते हैं। पहले सेव कर दी गई परिभाषा भी संशोधन के समय दोबारा जाँची जाती है, इसलिए अनुमति वापस ले लिए जाने के बाद उस परिभाषा को संशोधित करके सेव नहीं किया जा सकता।
     • सदस्य डायरेक्टरी (ServiceUser) की जाँच अनुमति map से नहीं, बल्कि सेटिंग अक्ष से होती है। पठन के तीन statement में resource: "ServiceUser" लिखने के लिए रचयिता की SpaceRole के settings में SETTING_SERVICE_LOGIN (या SETTING_ALL) होना आवश्यक है (SpaceRole का settings)। कारण यह है कि सदस्य डायरेक्टरी बाकी सभी रास्तों पर भी Space सेटिंग के अधीन आने वाला संसाधन है।
     • सदस्य को बदलने वाला statement किसी भी भूमिका से सेव नहीं होता। Script से सदस्य को बनाने, बदलने या हटाने का रास्ता ही नहीं है, इसलिए यह अनुमति की कमी (403) नहीं, बल्कि गलत लिखे गए statement (400) के रूप में अस्वीकृत होता है। अर्थात यह ऐसी रिक्तता नहीं है जिसे अनुमति जोड़कर बंद किया जा सके।
  2. कॉल के समय (/execute): केवल कॉलर की Script Execute अनुमति की जाँच होती है। अनुमति न हो, तो 403 मिलता है। पास होने पर हर statement की संसाधन अनुमति रनटाइम पर दोबारा जाँचे बिना निष्पादित होती है। यह प्रोग्रामिंग में किसी फ़ंक्शन को निष्पादित करने की अनुमति जैसा ही तरीका है। फ़ंक्शन को निष्पादित करने की अनुमति भर होने पर, उसके भीतर के अलग-अलग कार्यों की अनुमति दोबारा नहीं पूछी जाती। अनाम कॉल के पथ पर यह जाँच नहीं होती। कारण यह है कि जाँचने के लिए कोई कॉलर ही नहीं होता, और इसीलिए उस पथ को खोलना एक Script को बिना प्रमाणीकरण सार्वजनिक कर देने के बराबर है।
• सीधी कॉल पर रोक (directCallEnabled): यदि Script का directCallEnabled false है, तो /execute की सीधी कॉल स्वयं ही अस्वीकृत हो जाती है। यह गेट Execute अनुमति की जाँच पास कर लेने के बाद लगता है, इसलिए Execute अनुमति होने पर भी कॉल रुक जाती है। जिस कॉल करने वाले के पास अनुमति नहीं है, उसे इस गेट तक पहुँचने से पहले ही 403 मिल जाता है। यह गेट केवल उसी एंडपॉइंट पर है, इसलिए Webhook की लिंक्ड ऐक्शन (script) और Scheduler उसे पहले की तरह निष्पादित करते हैं। इसका डिफ़ॉल्ट मान true (सीधी कॉल की अनुमति) है।
• अनाम कॉल (anonymousCallEnabled): इसका डिफ़ॉल्ट मान false है। true करने पर केवल वही Script बिना प्रमाणीकरण वाले समर्पित पथ (/execute/anonymous) से भी निष्पादित होती है, और तब निष्पादन पहचान कॉलर नहीं, बल्कि रचयिता होती है। ऊपर दी गई दोनों सीमाओं में से कॉल के समय की जाँच (Execute अनुमति) उस पथ पर नहीं होती, इसलिए वास्तविक प्रमाणीकरण Script स्वयं करती है (प्राप्त अनुरोध के हस्ताक्षर का सत्यापन)। इसे चालू करने की शर्तें और सेव के नियम अनाम कॉल में दिए गए हैं।
• स्वामित्व स्कोप: where फ़िल्टर का createdBy: ":self" का अर्थ है "केवल वही जो वर्तमान कॉलर ने बनाया" (उदाहरण: केवल अपना वॉलेट देखना)। जिस Script में अनाम कॉल की अनुमति दी गई है, वहाँ इस फ़िल्टर का उपयोग नहीं किया जा सकता। कॉलर न होने के कारण यह रचयिता पर हल होता है, इसलिए स्वामित्व स्कोप का उसका मूल अर्थ ही नहीं बनता।
• प्रत्यायोजित अनुमति (रचना में सावधानी): ऊपर की दोनों सीमाओं को मिलाने पर, Script का निष्पादन रचयिता की अनुमति प्रत्यायोजित रूप में पाकर किए जाने जैसा है। कॉलर के पास केवल Execute भर होना चाहिए, और Script के भीतर के statement रचयिता को सेव के समय अधिकृत दायरे में ही निष्पादित होते हैं। इसलिए ऐसे संसाधन कार्य भी, जो कॉलर स्वयं नहीं कर सकता, Script के माध्यम से हो सकते हैं। रचयिता को दी गई अनुमति ही उस Script का प्रभाव-क्षेत्र है, इसलिए Script में शामिल किए जाने वाले कार्य सावधानी से तय किए जाते हैं।

सारांश चेकलिस्ट

सेव करने से पहले निम्नलिखित की पुष्टि करें।

• अनाम कॉल (anonymousCallEnabled) चालू की हो, तो where में createdBy: ":self" नहीं है, और प्राप्त अनुरोध का सत्यापन करने वाला statement (Signature आदि) सबसे आगे रखा है।
• बाहरी कॉल (Http·EmailSend) और कुल statement संख्या प्लान सीमा के भीतर हैं, तथा SetVar 10 या उससे कम और Cache 5 या उससे कम है।
• Cache का उपयोग किया हो, तो key को लिटरल के रूप में लिखा है और उसे Loop या ResourceForEach के भीतर नहीं रखा है।
• ResourceForEach से किसी बड़े समुच्चय पर पुनरावृत्ति करते हों, तो limit घोषित किया है या पूरा हो सकने योग्य आकार होने की पुष्टि की है।
• पुनरावृत्ति (Loop·ResourceForEach) शामिल की हो, तो यह पुष्टि कर ली है कि वह पुनरावृत्ति गुणा के रूप में समय बजट में आती है (कोई बाहरी कॉल न हो, तो 30 सेकंड का मूल बजट ही सीमा है)।
• secret मान केवल Http.headers के secret:true से ही डाले हैं (Signature.secret एन्क्रिप्ट होकर संग्रहीत नहीं होता, इसलिए उस Script को पढ़ सकने वाली भूमिकाओं की पुष्टि कर ली है)।
• हस्ताक्षर सत्यापन में उपयोग होने वाला संदेश /payload से नहीं, बल्कि { /rawPayload } से लिया है।
• सदस्य (ServiceUser) को पढ़ने वाला statement हो, तो रचयिता के पास SETTING_SERVICE_LOGIN है, और उस संसाधन को बदलने वाला statement नहीं डाला है।
• अपरिवर्तनीय कार्य (बाहरी कॉल) यथासंभव बाद में रखे हैं।
• update/patch की टक्कर की चिंता हो, तो ResourceUpdate या ResourcePatch के version का उपयोग करते हैं।
• परिणाम लौटाना हो, तो Return.value निर्दिष्ट किया है।

त्रुटियाँ

ये कोड तब मिलते हैं जब परिभाषा का रूप स्थैतिक बाधाओं को तोड़ता है और सेव करना अस्वीकृत हो जाता है। मान अभिव्यक्ति के नियम तोड़ने वाले कोड मान अभिव्यक्ति की त्रुटियाँ में हैं, और कॉल करते या हटाते समय मिलने वाले कोड एंडपॉइंट की त्रुटियाँ में हैं। हर संसाधन में समान रूप से मिलने वाले कोड के लिए सामान्य त्रुटियाँ देखें।

संबंधित दस्तावेज़

• मान अभिव्यक्ति: मान और शर्त के नियम।
• Statement कैटलॉग: प्रत्येक statement के फ़ील्ड और परिणाम।
• कुकबुक: पूर्ण उदाहरणों का संग्रह।
• Script संसाधन और एंडपॉइंट: Script संसाधन संरचना और /execute जैसे HTTP एंडपॉइंट।
• Script अवलोकन: शीर्ष-स्तरीय संरचना और एक निष्पादन को मिलने वाला समय।