Справочник серверного 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 };
});

Интерфейс вызывает обработчик через Frontend SDK Ogma. См. справочник интерфейсного SDK.

Требования безопасности

• Считайте HTTP-трафик, результаты, журналы и экспорт конфиденциальными.
• Запрашивайте только нужные разрешения.
• Никогда по умолчанию не записывайте учётные данные, cookie, bearer-токены или частный трафик.
• Делайте поведение явным и понятным пользователю.