Довідник SDK серверної частини плагінів

Серверний код плагіна виконується в ізольованому середовищі JavaScript Ogma й отримує об’єкт sdk від головного застосунку.

Повний формат пакета, поля маніфеста, дозволи й приклади наведено в посібнику системи плагінів.

Точка входу

Серверні плагіни надають функцію init:

async function init(sdk) {
  sdk.console.log("plugin started");
}

Ogma викликає init(sdk) під час увімкнення плагіна.

Основні простори імен

Простір імен	Призначення
sdk.console	Запис повідомлень до буфера журналу плагіна.
sdk.meta	Читання метаданих плагіна й шляхів даних.
sdk.events	Реєстрація обробників подій Ogma.
sdk.requests	Запити до історії HTTP й даних запитів.
sdk.findings	Пошук або створення знахідок, якщо дозволи це допускають.
sdk.scope	Читання відомостей про активну область.
sdk.storage	Постійне зберігання стану плагіна як ключів і значень.
sdk.fs	Файлові операції в приватному каталозі даних плагіна.
sdk.path	Допоміжні функції складання шляхів у каталозі даних плагіна.
sdk.api	Надання серверних обробників інтерфейсу плагіна.

Журналювання

sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")

Повідомлення видимі в інтерфейсі журналів плагіна. Пишіть стисло й не записуйте секретів.

Метадані

sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()

Використовуйте sdk.meta.path() для даних конкретного плагіна. Не припускайте доступу до довільних шляхів файлової системи з ізольованого коду плагіна.

sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()

sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")

Події

sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})

Обробники мають бути швидкими. Тривалу роботу слід переносити до явних дій користувача або серверних обробників API.

Обробники мосту інтерфейсу

Серверні плагіни можуть надавати обробники панелям інтерфейсу плагіна:

sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});

Інтерфейс викликає обробник через SDK інтерфейсу Ogma. Див. довідник SDK інтерфейсу.

Вимоги безпеки

• Вважайте HTTP-трафік, знахідки, журнали й експорти конфіденційними.
• Запитуйте лише потрібні плагіну дозволи.
• Ніколи не записуйте облікові дані, cookie, bearer-токени або приватний трафік за замовчуванням.
• Робіть поведінку плагіна явною й зрозумілою користувачу.