प्लगइन फ्रंटएंड SDK संदर्भ

प्लगइन का फ्रंटएंड कोड सैंडबॉक्स किए गए iframe के भीतर चलता है। यह दस्तावेज़ निम्न-स्तरीय संदर्भ है। उच्च-स्तरीय परिचय के लिए README.md देखें।

सुरक्षा मॉडल

गुण	मान
iframe सैंडबॉक्स	केवल `allow-scripts` (`allow-same-origin` नहीं)
CSP `script-src`	nonce द्वारा नियंत्रित; केवल प्रवेश बिंदु का स्क्रिप्ट लोड होता है
CSP `connect-src`	`'self'` - प्लगइन `/plugins/{id}/api/*` पर POST कर सकता है और `/plugins/{id}/events/poll` को पोल कर सकता है
CSP `default-src`	`'none'`
पैरेंट DOM तक पहुँच	अवरुद्ध (`allow-same-origin` नहीं)
Ogma सत्र की कुकी	प्लगइन के लिए पहुँच योग्य नहीं
प्लगइन के बीच संचार	उपलब्ध नहीं

डेटा ब्रिज कॉल की अनुमति हर अनुरोध पर सर्वर में जाँची जाती है; प्रदर्शन और नेविगेशन की कार्रवाइयाँ होस्ट UI संभालता है। अनुमतियाँ टैब में दिखाया गया अनुमति कैश केवल प्रदर्शन के लिए है; यह डेटा तक पहुँच को नियंत्रित नहीं करता।

ब्रिज प्रोटोकॉल

प्लगइन का JS, postMessage के ज़रिए Ogma होस्ट से संवाद करता है। होस्ट PluginsView.vue में है और bridge_request संदेश संभालता है।

अनुरोध एनवेलप

interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}

संदेश का अधिकतम कुल आकार: 65 536 बाइट।

प्रतिक्रिया एनवेलप

interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}

SDK का उपयोग (अनुशंसित)

कच्चे postMessage ब्रिज अनुरोध हाथ से न भेजें। ग्लोबल ogmaSDK का उपयोग करें:

ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});

SDK पूरे ब्रिज संचार को समेटता है और अनुरोधों का मिलान, sessionId प्रबंधन तथा Promise समाधान संभालता है।

कमांड संदर्भ

`ogma.meta.get`

कोई पेलोड आवश्यक नहीं।

{ pluginId, packageId, name, version, ogmaVersion } लौटाता है।

`ogma.requests.get`

पेलोड: { id: string }

चुनिंदा फ़ील्ड वाला HTTP रिकॉर्ड लौटाता है। फ़ील्ड: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at। इस रूप में हेडर या बॉडी के बाइट शामिल नहीं हैं।

आवश्यक अनुमति: read_http_history (अपने-आप प्रदान की जाती है)।

`ogma.requests.getRaw`

पेलोड: { id: string }। इसे sdk.requests.getRaw(id) के ज़रिए कॉल करें।

requestBodyBase64, responseBodyBase64, डिकोड किए जाने के बाद उनकी लंबाई (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated और maxBodyBytes लौटाता है। नाम के बावजूद, यह संचालन बॉडी के बाइट लौटाता है, पूरा कच्चा HTTP संदेश नहीं। चुनिंदा डेटा प्रस्तुत करने से पहले समर्थित कंटेंट एन्कोडिंग डिकोड की जाती हैं। हर बॉडी की सीमा 256 KiB है; पूरे एसेट को प्रोसेस करने से पहले ट्रंकेशन फ़्लैग जाँचें।

आवश्यक अनुमति: read_http_history (अपने-आप प्रदान की जाती है)।

`ogma.requests.search`

पेलोड: { limit?: number, offset?: number, query?: string }

query, HTTPQL फ़िल्टर एक्सप्रेशन का समर्थन करता है। अधिकतम limit: 20। { items: [...], total: number, limit: number, offset: number } लौटाता है।

आवश्यक अनुमति: read_http_history (अपने-आप प्रदान की जाती है)।

`ogma.findings.list`

पेलोड: { limit?: number, offset?: number }

{ items: [...], total: number, limit: number, offset: number } लौटाता है, जिसमें प्रति पेज अधिकतम 20 निष्कर्ष होते हैं। आइटम सारांश हैं; फ़ील्ड में id, title, severity, status, reporter, tags और created_at शामिल हैं।

आवश्यक अनुमति: read_findings (अपने-आप प्रदान की जाती है)।

`ogma.scope.getActive`

कोई पेलोड नहीं। परीक्षण के सक्रिय दायरे का प्रीसेट या null लौटाता है।

आवश्यक अनुमति: read_scope (अपने-आप प्रदान की जाती है)।

`ogma.projects.getCurrent`

कोई पेलोड नहीं। { id, name, status } या null लौटाता है।

आवश्यक अनुमति: read_projects (अपने-आप प्रदान की जाती है)।

`ogma.log`

पेलोड: { message: string }

प्लगइन के लॉग बफ़र में लिखता है।

`ogma.ui.resize`

पेलोड: { height: number } (अधिकतम 2000)

होस्ट से iframe की ऊँचाई सेट करने का अनुरोध करता है।

`ogma.ui.sidebar.registerItem`

पेलोड: { name: string, path: string } (नाम अधिकतम 64 वर्ण, पथ अधिकतम 256 वर्ण)

प्लगइन पैनल के भीतर नेविगेशन रजिस्टर करता है। प्रति प्लगइन अधिकतम 20 आइटम। sdk.navigation.addPage(path, { title, body }) से संबंधित पेज की बॉडी रजिस्टर करें; आइटम चुनने पर वह पेज iframe के भीतर दिखता है, Ogma कार्यक्षेत्र का नया शीर्ष-स्तरीय रूट नहीं बनता।

`ogma.backend.call`

पेलोड: { method: string, args: unknown[] }

sdk.api.register(method, fn) से रजिस्टर किए गए बैकएंड RPC हैंडलर को कॉल करता है। मेथड नाम की अधिकतम लंबाई 64 वर्ण है।

बैकएंड हैंडलर ने जो लौटाया था, उसे JSON में सीरियलाइज़ करके लौटाता है।

`ogma.backend.onEvent`

पेलोड: आवश्यक नहीं।

केवल स्वीकृति दी जाती है। इवेंट वास्तव में प्राप्त करने के लिए ogma.events.poll का उपयोग करें।

`ogma.events.poll`

पेलोड: { since: number } (पिछले पोल का इंडेक्स; 0 से शुरू करें)

{ events: [{ event: string, args: unknown[] }], next_since: number } लौटाता है।

`ogma.navigation.addPage`

पेलोड: { path: string, title?: string }

ब्रिज पेज के पथ की स्वीकृति देता है। इंजेक्ट किया गया SDK, { body: HTMLElement } को भी sdk.navigation.addPage(path, options) के विकल्प के रूप में स्वीकार करता है, बॉडी को iframe के भीतर जोड़ता है और होस्ट द्वारा संबंधित साइडबार आइटम चुने जाने पर पेज की दृश्यता बदलता है। DOM नोड स्थानीय रहता है; इसे ब्रिज के ज़रिए सीरियलाइज़ नहीं किया जाता।

`ogma.window.showToast`

पेलोड: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

प्लगइन पैनल में टोस्ट सूचना दिखाता है। अवधि मिलीसेकंड में है (अधिकतम 10000, डिफ़ॉल्ट 3000)।

`ogma.commands.register`

पेलोड: { id: string, name: string }

प्लगइन कमांड को होस्ट के कमांड स्टोर में रजिस्टर करता है। होस्ट पर निष्पादन होने पर plugin_command संदेश iframe को वापस भेजा जाता है, जिसमें commandId और संदर्भ शामिल होते हैं; प्लगइन को संबंधित कॉलबैक देना होगा। केवल रजिस्टर करने से कमांड नहीं चलती।

`ogma.menu.registerItem`

पेलोड: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

प्लगइन कमांड से जुड़ा संदर्भ मेनू आइटम रजिस्टर करता है। पहले कमांड रजिस्टर करें। लेबल डिफ़ॉल्ट रूप से कमांड का रजिस्टर किया गया नाम होता है, और उसके न होने पर उसका ID; type न देने पर डिफ़ॉल्ट Request है। होस्ट ब्रिज leadingIcon का उपयोग नहीं करता।

थीम सहायक

इंजेक्ट किया गया SDK, sdk.theme.get() और sdk.theme.onChange(callback) भी उपलब्ध कराता है। ये iframe की थीम पढ़ते हैं और अलग डेटा ब्रिज कमांड के बिना होस्ट की थीम अपडेट के लिए सब्सक्राइब करते हैं। प्लगइन UI को Ogma के हल्के/गहरे रंग के स्वरूप के अनुरूप रखने के लिए इनका उपयोग करें।

त्रुटि कोड

कोड	अर्थ
`PERMISSION_DENIED`	प्लगइन के पास आवश्यक अनुमति नहीं है।
`PLUGIN_DISABLED`	प्लगइन अभी चालू नहीं है।
`UNKNOWN_COMMAND`	कमांड समर्थित सूची में नहीं है।
`INVALID_PAYLOAD`	पेलोड का कोई आवश्यक फ़ील्ड मौजूद नहीं है या उसका प्रकार गलत है।
`NOT_FOUND`	अनुरोधित संसाधन मौजूद नहीं है।
`LIMIT_EXCEEDED`	प्रति प्लगइन आइटम की अधिकतम संख्या की सीमा तक पहुँच गए हैं (जैसे साइडबार आइटम)।
`SERVER_ERROR`	आंतरिक त्रुटि। प्लगइन लॉग जाँचें।

समर्थित कमांड की सूची

ogma.meta.get, ogma.log, ogma.ui.resize, ogma.ui.sidebar.registerItem, ogma.requests.get, ogma.requests.getRaw, ogma.requests.search, ogma.findings.list, ogma.scope.getActive, ogma.projects.getCurrent, ogma.backend.call, ogma.backend.onEvent, ogma.events.poll, ogma.navigation.addPage, ogma.window.showToast, ogma.commands.register, ogma.menu.registerItem.

प्लगइन फ्रंटएंड SDK संदर्भ ​

सुरक्षा मॉडल ​

ब्रिज प्रोटोकॉल ​

अनुरोध एनवेलप ​

प्रतिक्रिया एनवेलप ​

SDK का उपयोग (अनुशंसित) ​

कमांड संदर्भ ​

ogma.meta.get ​

ogma.requests.get ​

ogma.requests.getRaw ​

ogma.requests.search ​

ogma.findings.list ​

ogma.scope.getActive ​

ogma.projects.getCurrent ​

ogma.log ​

ogma.ui.resize ​

ogma.ui.sidebar.registerItem ​

ogma.backend.call ​

ogma.backend.onEvent ​

ogma.events.poll ​

ogma.navigation.addPage ​

ogma.window.showToast ​

ogma.commands.register ​

ogma.menu.registerItem ​

थीम सहायक ​

त्रुटि कोड ​

समर्थित कमांड की सूची ​

प्लगइन फ्रंटएंड SDK संदर्भ

सुरक्षा मॉडल

ब्रिज प्रोटोकॉल

अनुरोध एनवेलप

प्रतिक्रिया एनवेलप

SDK का उपयोग (अनुशंसित)

कमांड संदर्भ

`ogma.meta.get`

`ogma.requests.get`

`ogma.requests.getRaw`

`ogma.requests.search`

`ogma.findings.list`

`ogma.scope.getActive`

`ogma.projects.getCurrent`

`ogma.log`

`ogma.ui.resize`

`ogma.ui.sidebar.registerItem`

`ogma.backend.call`

`ogma.backend.onEvent`

`ogma.events.poll`

`ogma.navigation.addPage`

`ogma.window.showToast`

`ogma.commands.register`

`ogma.menu.registerItem`

थीम सहायक

त्रुटि कोड

समर्थित कमांड की सूची