Довідник SDK інтерфейсу плагінів

Код інтерфейсу плагіна виконується в ізольованому iframe. Цей документ — низькорівневий довідник. Вступ вищого рівня наведено в README.md.

---

Модель безпеки

Властивість	Значення
Ізоляція iframe	Лише allow-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)
Cookie сеансу Ogma	Недоступні плагіну
Взаємодія між плагінами	Недоступна

Виклики мосту даних авторизуються на сервері для кожного запиту; дії відображення й навігації опрацьовує інтерфейс хоста. Кеш дозволів на вкладці дозволів призначено лише для показу; він не обмежує доступ до даних.

---

Протокол мосту

JavaScript плагіна взаємодіє з хостом Ogma через postMessage. Хост міститься в 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 КіБ; перевіряйте прапорці усічення перед опрацюванням повного ресурсу.

Потребує: 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[] }

Викликає серверний обробник 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 }

Реєструє елемент контекстного меню, пов’язаний із командою плагіна. Спочатку зареєструйте команду. Назва за замовчуванням — зареєстрована назва команди, потім її ID; пропущений 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.