Ogma

ظاهر

مرجع 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افزونه به آن‌ها دسترسی ندارد
ارتباط بین افزونه‌هادر دسترس نیست

مجوز فراخوانی‌های پل داده در هر درخواست در سمت سرور بررسی می‌شود؛ اقدامات نمایش و پیمایش را رابط کاربری میزبان مدیریت می‌کند. حافظهٔ نهان مجوزها که در زبانهٔ مجوزها نمایش داده می‌شود فقط برای نمایش است و دسترسی به داده را کنترل نمی‌کند.

پروتکل پل ​

کد JS افزونه از طریق postMessage با میزبان Ogma ارتباط برقرار می‌کند. میزبان در 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 }

فرمان افزونه را در مخزن فرمان‌های میزبان ثبت می‌کند. اجرای میزبان یک پیام plugin_command شامل commandId و زمینه را به iframe برمی‌گرداند؛ افزونه باید تابع فراخوانی برگشتی متناظر را ارائه کند. ثبت به‌تنهایی فرمان را اجرا نمی‌کند.

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