Script | Weegloo Docs

Script एक घोषणात्मक बैकएंड एंडपॉइंट है, जिसे फ्रंटएंड HTTP के ज़रिए कॉल करता है। सर्वर कोड लिखे बिना आप "क्या करना है" को JSON में घोषित करते हैं, और WEEGLOO इंजन उसे आपकी जगह निष्पादित कर देता है। प्रमाणीकरण, शर्त जाँच (guard), शृंखलाबद्ध CRUD, बाहरी API कॉल और मानों को आकार देने जैसी, फ्रंटएंड को सहारा देने वाली सामान्य बैकएंड मध्य परत (BFF, Backend-for-Frontend) को एक ही Script से बदल देना ही इसका लक्ष्य है।

यह दस्तावेज़ समूह Script सिंटैक्स का आधिकारिक संदर्भ (reference) है। अलग-अलग सिंटैक्स का विवरण नीचे इस समूह के दस्तावेज़ में बाँटकर दिया गया है।

Script को बनाने और प्रबंधित करने का काम (निर्माण·पठन·संशोधन·विलोपन) CMA (https://cma.weegloo.com/v1) पर होता है। निष्पादन की ज़िम्मेदारी समर्पित Script होस्ट (https://script.weegloo.com/v1) के निष्पादन पथ की है। यही एक निष्पादन पथ Weegloo User टोकन और उत्पाद में साइन अप कर चुके सदस्य (ServiceUser) के टोकन, दोनों को स्वीकार करता है। ACMA में Script API नहीं है, और केवल-पढ़ने वाली डिलीवरी API (CDA, ACDA) में भी नहीं है।

मेंटल मॉडल

एक Script एक HTTP एंडपॉइंट होता है। कॉल की मेथड (method) से यह मैच किया जाता है कि कौन-सा Script निष्पादित होगा।
बॉडी एक statements ऐरे है। ये ऊपर से नीचे क्रम से निष्पादित होते हैं। यह सामान्य प्रोग्रामिंग में किसी फ़ंक्शन की बॉडी जैसा ही है।
यह कोड नहीं, घोषणा है। आप कोई मनमाना कोड (FaaS) नहीं डालते, बल्कि पहले से तय statement प्रकारों को जोड़ते हैं। इसे किसी व्यक्ति द्वारा हाथ से लिखे जाने के बजाय AI एजेंट द्वारा MCP के ज़रिए जेनरेट किए जाने के हिसाब से डिज़ाइन किया गया है।
मान JSON Pointer टेम्प्लेट के ज़रिए बहते हैं। पिछले चरण का परिणाम, इनपुट payload या वेरिएबल को { /pointer } से संदर्भित करके अगले चरण में भेजा जाता है। कोई शर्त या गणना चाहिए हो तो JsonLogic ऑपरेटर उपयोग किए जाते हैं। विस्तृत नियम मान अभिव्यक्ति में दिए गए हैं।

शीर्ष-स्तरीय संरचना (ScriptDefinition)

एक Script को निम्नलिखित ScriptDefinition संरचना से परिभाषित किया जाता है।

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. कॉल के समय मैच होने वाली HTTP मेथड (आवश्यक)
  "payloadSchema": { /* ... */ }, // (वैकल्पिक) JSON Schema. मौजूद होने पर, निष्पादन से पहले अनुरोध payload को वैलिडेट करता है
  "statements": [ /* Statement[]. ऊपर से नीचे निष्पादित (आवश्यक, कम से कम 1) */ ]
}

फ़ील्ड	आवश्यक	विवरण
`method`	आवश्यक	इस Script को कॉल करने के लिए इस्तेमाल होने वाली HTTP मेथड। कॉल इसी मान से मैच किए जाते हैं।
`payloadSchema`	वैकल्पिक	एक JSON Schema है। निर्दिष्ट करने पर, अनुरोध body (payload) को निष्पादन से पहले इस स्कीमा से वैलिडेट किया जाता है, और विफल होने पर अनुरोध को बिना निष्पादित किए अस्वीकार कर दिया जाता है।
`statements`	आवश्यक	निष्पादित किए जाने वाले statements की क्रमबद्ध ऐरे। कम से कम 1।

payload केवल JSON ऑब्जेक्ट स्वीकार करता है। कॉल की body को /payload context रूट से एक्सेस किया जाता है ({ /payload/... }), और पार्स करने से पहले की मूल string चाहिए हो तो /rawPayload से (हस्ताक्षर सत्यापन की तरह, जब गणना भेजे गए bytes पर होती है)। कॉल के अनुरोध HTTP हेडर को /headers रूट से संदर्भित किया जाता है ({ /headers/... }, keys लोअरकेस में)। निष्पादन शुरू होने का समय /now रूट में है। पूरे context रूट सेट के बारे में मान अभिव्यक्ति में बताया गया है।

अनुरोध और प्रतिक्रिया

अंततः Script अपने Return statement का मान कॉलर को लौटाता है। प्रतिक्रिया का स्वरूप इस प्रकार है।

{
  "requestId": "…",     // निष्पादन पहचानकर्ता
  "durationMs": 1234,   // निष्पादन में लगा समय (ms)
  "statusCode": 200,    // पहुँचे गए Return का statusCode (डिफ़ॉल्ट 200)
  "return": <value>     // सिर्फ़ तब जब Return.isError false हो. मान null होने पर ""
  // "error": <value>   // तब जब Return.isError true हो, या निष्पादन विफल हो गया हो (इस स्थिति में "return" नहीं होता). मान null होने पर ""
}

requestId इस निष्पादन का पहचानकर्ता है। वही मान उस निष्पादन द्वारा छोड़े गए ScriptLog के sys.requestId में जाता है, इसलिए यह लॉग में इस निष्पादन को खोजने की कुंजी बनता है।
return और error एक साथ कभी नहीं आते। Return statement का isError तय करता है कि यह कौन-सा होगा।
अगर निष्पादन किसी Return statement तक पहुँचे बिना अंत तक चल जाए, तो return और error दोनों ही नहीं होते और statusCode डिफ़ॉल्ट (200) रहता है।
निष्पादन विफल होने पर Return के बिना भी error भर जाता है। गलत payload की तरह कॉल की ओर के किसी कारण से विफलता हो और Try उसे न पकड़े, तो error में विफलता का कारण आता है और statusCode उस विफलता से मेल खाने वाला कोड बन जाता है (गलत payload पर 4xx, और बाहरी कॉल या मेल भेजना विफल होने पर 502)। व्यवहार में सबसे अधिक मिलने वाली एरर प्रतिक्रिया इसी स्वरूप की होती है। समय बजट पार कर जाने वाला निष्पादन इस envelope के बजाय 408 के साथ उत्तर देता है।
अगर कोई मान null हो, तो वह फ़ील्ड खाली string "" के रूप में निकलता है।

Return के value, isError और statusCode से प्रतिक्रिया की body और स्टेटस कोड नियंत्रित किए जाते हैं। विस्तार के लिए Statement कैटलॉग में Return देखें।

एक निष्पादन को मिलने वाला समय

Script कॉल के अनुरोध को संभालने वाले पथ पर इनलाइन निष्पादित होता है। काम को बैकग्राउंड में सौंपने या पहले स्वीकृति की प्रतिक्रिया लौटाने जैसा कोई प्रवाह नहीं है, और कॉल की प्रतिक्रिया की body ही निष्पादन का परिणाम है। परिणाम को बाद में जाकर लेने वाला पोलिंग पथ भी नहीं है।

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

मूल बजट 30 सेकंड है। इसमें प्रत्येक statement द्वारा घोषित समय जुड़ता जाता है।
जो statement कुछ घोषित नहीं करता, वह 0 सेकंड गिना जाता है। वह statement वास्तव में जितना समय लेता है, वह 30 सेकंड के मूल बजट से जाता है।
योग 180 सेकंड से अधिक हो जाए, तो सेव अस्वीकार नहीं होता, बल्कि बजट 180 सेकंड पर काट दिया जाता है।

प्रति statement घोषणा के नियम का सार इस प्रकार है।

statement	घोषित होने वाला समय
`Http`	(`timeoutMs` न हो तो 30 सेकंड) × (1 + `retry`)
`EmailSend`	`timeoutMs`, न हो तो 10 सेकंड
`Loop`	body के statements का योग × (`maxIterations`, न हो तो 10,000)
`ResourceForEach`	`onEach` के statements का योग × (`limit`, न हो तो 10,000)
`If`	`then` पक्ष और `else` पक्ष में से बड़ा मान
`Parallel`	शाखाओं में से सबसे बड़ा मान

पुनरावृत्ति गुणा है। Loop और ResourceForEach अपनी body (onEach) द्वारा घोषित समय को पुनरावृत्ति की ऊपरी सीमा से गुणा करते हैं।
जिस पुनरावृत्ति में कोई बाहरी कॉल नहीं है, उसकी body का घोषित समय 0 होता है, इसलिए 30 सेकंड का मूल बजट ही वास्तविक सीमा है।

प्रति statement विस्तृत नियम और प्लान सीमाएँ निष्पादन सिमेंटिक्स, बाधाएँ, सुरक्षा में दी गई हैं।

न्यूनतम उदाहरण

यह अनुरोध payload के शीर्षक और body से एक पोस्ट Content बनाता है, उसे तुरंत publish करता है, और फिर बनाई गई sys.id लौटाता है।

{
  "method": "Post",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

ResourceCreate Content बनाता है और परिणाम को post नाम से बाइंड करता है।
Return { "id": <नई Content id> } को 201 के साथ लौटाता है।
Content के fields मान locale map ({ "en-US": ... }) क्यों होते हैं, यह मान अभिव्यक्ति में locale map में बताया गया है।

और भी विविध परिदृश्य कुकबुक में मिलेंगे।

इस समूह के दस्तावेज़

मान अभिव्यक्ति: { /pointer } संदर्भ, लिटरल, JsonLogic संक्रिया और शर्त, context रूट, तथा locale map को कवर करता है। यह सिंटैक्स का केंद्र है।
Statement कैटलॉग: 25 प्रकार के statements (संसाधन CRUD और पठन, Http, EmailSend, SetVar, Cache, ParseJson, Signature, Hash, Regex, If, Loop, Parallel, Try, Return) के फ़ील्ड और परिणाम को कवर करता है।
निष्पादन सिमेंटिक्स, बाधाएँ, सुरक्षा: निष्पादन क्रम, guard, क्षतिपूर्ति, आशावादी लॉकिंग, एरर, स्थैतिक बाधाएँ और प्लान सीमाएँ, तथा सुरक्षा मॉडल को कवर करता है।
कुकबुक: upsert, क्रेडिट guard, LLM प्रॉक्सी, पेजिनेशन, समानांतर निष्पादन, भुगतान सागा, webhook हस्ताक्षर सत्यापन जैसे पूर्ण उदाहरणों को कवर करता है।
Script संसाधन और एंडपॉइंट: Script संसाधन की sys संरचना और रचना, निष्पादन (/execute) के HTTP एंडपॉइंट के स्पेसिफ़िकेशन, तथा निष्पादन लॉग ScriptLog को कवर करता है।

अगर यह आपकी पहली बार है, तो इस पेज से शुरू करके मान अभिव्यक्ति, फिर Statement कैटलॉग के क्रम में पढ़ने की सलाह है। कुकबुक को पूरा एक बार सरसरी तौर पर देखना भी अच्छा रहेगा।