Dokumentacja referencyjna SDK backendu wtyczek

Kod backendu wtyczki działa w piaskownicy JavaScript Ogma i otrzymuje obiekt sdk od aplikacji hosta.

Pełny opis formatu pakietu wtyczki, pól manifestu, uprawnień i przykładów znajdziesz w przewodniku po systemie wtyczek.

Punkt wejścia

Wtyczki backendu udostępniają funkcję init:

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

Ogma wywołuje init(sdk) po włączeniu wtyczki.

Główne przestrzenie nazw

Przestrzeń nazw	Przeznaczenie
sdk.console	Zapisywanie komunikatów w buforze dziennika wtyczki.
sdk.meta	Odczytywanie metadanych wtyczki i ścieżek danych.
sdk.events	Rejestrowanie funkcji zwrotnych dla zdarzeń Ogma.
sdk.requests	Odczytywanie historii HTTP i danych żądań.
sdk.findings	Odczytywanie lub tworzenie ustaleń, jeśli pozwalają na to uprawnienia.
sdk.scope	Odczytywanie informacji o aktywnym zakresie testów.
sdk.storage	Trwałe przechowywanie stanu wtyczki w postaci par klucz/wartość.
sdk.fs	Operacje na plikach w prywatnym katalogu danych wtyczki.
sdk.path	Funkcje pomocnicze do tworzenia ścieżek w katalogu danych wtyczki.
sdk.api	Udostępnianie procedur obsługi backendu frontendowi wtyczki.

Zapisywanie dzienników

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

Komunikaty są widoczne w interfejsie dzienników wtyczki. Pisz zwięzłe komunikaty i unikaj zapisywania sekretów.

Metadane

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

Używaj sdk.meta.path() do danych przypisanych do wtyczki. Nie zakładaj, że kod wtyczki działający w piaskownicy ma dostęp do dowolnych ścieżek systemu plików.

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")

Zdarzenia

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")
})

Funkcje zwrotne powinny wykonywać się szybko. Długotrwałe operacje należy uruchamiać przez jawne działania użytkownika lub procedury obsługi API backendu.

Procedury obsługi mostu frontendu

Wtyczki backendu mogą udostępniać procedury obsługi panelom frontendu wtyczek:

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

Frontend wywołuje procedurę obsługi za pośrednictwem SDK frontendu Ogma. Zobacz dokumentację referencyjną SDK frontendu.

Wymagania dotyczące bezpieczeństwa

• Traktuj ruch HTTP, ustalenia, dzienniki i eksporty jako dane wrażliwe.
• Żądaj tylko uprawnień potrzebnych wtyczce.
• Nigdy nie zapisuj domyślnie w dziennikach danych uwierzytelniających, ciasteczek, tokenów typu bearer ani prywatnego ruchu.
• Dbaj o to, aby działanie wtyczki było jawne i zrozumiałe dla użytkownika.