Ogma

מראה

מדריך העזר ל-SDK של צד הלקוח בתוספים ​

קוד צד הלקוח של התוסף רץ בתוך iframe מבודד. מסמך זה הוא מדריך עזר ברמה נמוכה. למבוא ברמה גבוהה יותר, ראו README.md.

מודל אבטחה ​

מאפייןערך
בידוד iframeallow-scripts בלבד (ללא allow-same-origin)
הוראת CSP‏ script-srcמוגבלת באמצעות nonce; רק סקריפט נקודת הכניסה נטען
הוראת CSP‏ connect-src'self' - התוסף יכול לשלוח POST אל /plugins/{id}/api/* ולתשאל במחזוריות את /plugins/{id}/events/poll
הוראת CSP‏ default-src'none'
גישה ל-DOM של ההורהחסומה (ללא allow-same-origin)
עוגיות ההפעלה של Ogmaאינן נגישות לתוסף
תקשורת בין תוספיםאינה זמינה

ההרשאות לקריאות גשר הנתונים נבדקות בצד השרת בכל בקשה; פעולות תצוגה וניווט מטופלות בממשק המשתמש של המארח. מטמון ההרשאות המוצג בלשונית הרשאות מיועד לתצוגה בלבד; הוא אינו קובע את הגישה לנתונים.

פרוטוקול הגשר ​

קוד ה-JS של התוסף מתקשר עם מארח Ogma דרך postMessage. המארח נמצא ב-PluginsView.vue ומטפל בהודעות bridge_request.

מעטפת בקשה ​

ts
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 בתים.

מעטפת תשובה ​

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

אל תשלחו ידנית בקשות גשר גולמיות של postMessage. השתמשו באובייקט הגלובלי ogmaSDK:

js
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 (מוענקת אוטומטית).

מטען נתונים: { 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[] }

קוראת לפונקציית טיפול RPC בצד השרת שנרשמה באמצעות sdk.api.register(method, fn). אורך שם המתודה המרבי הוא 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 }

רושמת את פקודת התוסף במאגר הפקודות של המארח. ביצוע במארח שולח בחזרה ל-iframe הודעת plugin_command הכוללת commandId והקשר; התוסף חייב לספק את פונקציית הקריאה החוזרת המתאימה. רישום בלבד אינו מבצע את הפקודה.

ogma.menu.registerItem ​

מטען נתונים: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

רושמת פריט בתפריט הקשר המקושר לפקודת תוסף. רשמו תחילה את הפקודה. התווית היא כברירת מחדל השם הרשום של הפקודה, ואם אין שם, המזהה שלה; כאשר type אינו מצוין, ברירת המחדל היא Request. גשר המארח אינו משתמש ב-leadingIcon.

כלי עזר לערכת הנושא ​

ה-SDK המוזרק מספק גם את sdk.theme.get() ואת sdk.theme.onChange(callback). הם קוראים את ערכת הנושא של ה-iframe ונרשמים לעדכוני ערכת הנושא של המארח ללא פקודה נפרדת בגשר הנתונים. השתמשו בהם כדי להתאים את ממשק התוסף למראה הבהיר/הכהה של 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.

תוכנה קניינית. כל הזכויות שמורות.

זכויות יוצרים © 2024 ועד היום OgmaBox