Eklenti frontend SDK başvurusu

Eklentinin frontend kodu, korumalı bir iframe içinde çalışır. Bu belge düşük seviyeli bir başvuru kaynağıdır. Daha genel bir giriş için README.md sayfasına bakın.

---

Güvenlik modeli

Özellik	Değer
Iframe korumalı alanı	Yalnızca allow-scripts (allow-same-origin yok)
CSP script-src	Nonce ile sınırlandırılır; yalnızca giriş noktası betiği yüklenir
CSP connect-src	'self' — eklenti /plugins/{id}/api/* adresine POST isteği gönderebilir ve /plugins/{id}/events/poll adresini düzenli olarak sorgulayabilir
CSP default-src	'none'
Üst öğenin DOM'una erişim	Engellenir (allow-same-origin yok)
Ogma oturum çerezleri	Eklenti tarafından erişilemez
Eklentiler arası iletişim	Kullanılamaz

Veri köprüsü çağrıları her istekte sunucu tarafında yetkilendirilir; görüntüleme ve gezinme işlemlerini ana uygulamanın arayüzü yürütür. İzinler sekmesinde gösterilen izin önbelleği yalnızca bilgi amaçlıdır; veri erişimini denetlemez.

---

Köprü protokolü

Eklenti JS kodu, Ogma ana uygulamasıyla postMessage üzerinden iletişim kurar. Ana uygulama tarafındaki kod PluginsView.vue içinde bulunur ve bridge_request mesajlarını işler.

İstek zarfı

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
}

Toplam mesaj boyutu en fazla 65 536 bayttır.

Yanıt zarfı

interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}

SDK kullanımı (önerilen)

Ham postMessage köprü isteklerini elle göndermeyin. Global ogmaSDK nesnesini kullanın:

ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});

SDK, tüm köprü iletişimini sarmalar; isteklerin eşleştirilmesini, sessionId yönetimini ve Promise'lerin sonuçlandırılmasını üstlenir.

---

Komut başvurusu

ogma.meta.get

İstek verisi gerekmez.

{ pluginId, packageId, name, version, ogmaVersion } döndürür.

ogma.requests.get

İstek verisi: { id: string }

Seçilmiş alanlardan oluşan bir HTTP kaydı döndürür. Alanlar: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Bu görünüm başlıkları veya gövde baytlarını içermez.

Gerekli izin: read_http_history (otomatik verilir).

ogma.requests.getRaw

İstek verisi: { id: string }. sdk.requests.getRaw(id) üzerinden çağırın.

requestBodyBase64, responseBodyBase64, bunların çözülmüş uzunlukları (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated ve maxBodyBytes döndürür. Adına rağmen bu işlem, tam bir ham HTTP mesajı yerine gövde baytlarını döndürür. Desteklenen içerik kodlamaları, alanlar seçilmeden önce çözülür. Her gövde 256 KiB ile sınırlıdır; bir varlığın tamamını işlemeden önce kesilme bayraklarını kontrol edin.

Gerekli izin: read_http_history (otomatik verilir).

ogma.requests.search

İstek verisi: { limit?: number, offset?: number, query?: string }

query, HTTPQL filtre ifadelerini destekler. En büyük limit: 20. { items: [...], total: number, limit: number, offset: number } döndürür.

Gerekli izin: read_http_history (otomatik verilir).

ogma.findings.list

İstek verisi: { limit?: number, offset?: number }

Sayfa başına en fazla 20 bulguyla { items: [...], total: number, limit: number, offset: number } döndürür. Öğeler özet niteliğindedir; alanlar arasında id, title, severity, status, reporter, tags ve created_at bulunur.

Gerekli izin: read_findings (otomatik verilir).

ogma.scope.getActive

İstek verisi yoktur. Etkin kapsam ön ayarını veya null döndürür.

Gerekli izin: read_scope (otomatik verilir).

ogma.projects.getCurrent

İstek verisi yoktur. { id, name, status } veya null döndürür.

Gerekli izin: read_projects (otomatik verilir).

ogma.log

İstek verisi: { message: string }

Eklentinin günlük tamponuna yazar.

ogma.ui.resize

İstek verisi: { height: number } (en fazla 2000)

Ana uygulamadan iframe yüksekliğini ayarlamasını ister.

ogma.ui.sidebar.registerItem

İstek verisi: { name: string, path: string } (ad en fazla 64, yol en fazla 256 karakter)

Eklenti paneli içinde bir gezinme öğesi kaydeder. Eklenti başına en fazla 20 öğe kullanılabilir. Eşleşen sayfa gövdelerini sdk.navigation.addPage(path, { title, body }) ile kaydedin; öğe seçildiğinde bu sayfa iframe içinde gösterilir, Ogma çalışma alanında yeni bir üst düzey rota açılmaz.

ogma.backend.call

İstek verisi: { method: string, args: unknown[] }

sdk.api.register(method, fn) ile kaydedilmiş bir backend RPC işleyicisini çağırır. Metot adının uzunluğu en fazla 64 karakterdir.

Backend işleyicisinin döndürdüğü değeri JSON olarak serileştirip döndürür.

ogma.backend.onEvent

İstek verisi gerekmez.

Yalnızca alındı onayı verir. Olayları gerçekten almak için ogma.events.poll kullanın.

ogma.events.poll

İstek verisi: { since: number } (son sorgudaki indeks; 0 ile başlayın)

{ events: [{ event: string, args: unknown[] }], next_since: number } döndürür.

ogma.navigation.addPage

İstek verisi: { path: string, title?: string }

Köprü, sayfa yolunun alındığını onaylar. Enjekte edilen SDK ayrıca sdk.navigation.addPage(path, options) çağrısında { body: HTMLElement } seçeneğini kabul eder, gövdeyi iframe içine ekler ve ana uygulama eşleşen kenar çubuğu öğesini seçtiğinde sayfa görünürlüğünü değiştirir. DOM düğümü yerel kalır; köprü üzerinden serileştirilmez.

ogma.window.showToast

İstek verisi: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Eklenti panelinde geçici bir bildirim gösterir. Süre milisaniye cinsindendir (en fazla 10000, varsayılan 3000).

ogma.commands.register

İstek verisi: { id: string, name: string }

Eklenti komutunu ana uygulamanın komut deposuna kaydeder. Ana uygulamada çalıştırılması, commandId ve bağlam içeren bir plugin_command mesajını iframe'e geri gönderir; eklenti buna karşılık gelen geri çağırma işlevini sağlamalıdır. Yalnızca kaydetmek komutu çalıştırmaz.

ogma.menu.registerItem

İstek verisi: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Bir eklenti komutuna bağlı bağlam menüsü öğesi kaydeder. Önce komutu kaydedin. Etiket varsayılan olarak komutun kayıtlı adını, yoksa kimliğini kullanır; belirtilmeyen type için varsayılan Request olur. leadingIcon, ana uygulama köprüsü tarafından kullanılmaz.

Tema yardımcıları

Enjekte edilen SDK, sdk.theme.get() ve sdk.theme.onChange(callback) işlevlerini de sağlar. Bunlar ayrı bir veri köprüsü komutu olmadan iframe temasını okur ve ana uygulamanın tema güncellemelerine abone olur. Eklenti arayüzünü Ogma'nın açık/koyu görünümüyle uyumlu tutmak için kullanın.

---

Hata kodları

Kod	Anlamı
PERMISSION_DENIED	Eklentinin gerekli izni yoktur.
PLUGIN_DISABLED	Eklenti şu anda etkin değildir.
UNKNOWN_COMMAND	Komut desteklenenler listesinde değildir.
INVALID_PAYLOAD	Gerekli bir istek verisi alanı eksiktir veya türü yanlıştır.
NOT_FOUND	İstenen kaynak mevcut değildir.
LIMIT_EXCEEDED	Eklenti başına sayı sınırına ulaşılmıştır (örneğin kenar çubuğu öğeleri).
SERVER_ERROR	Dahili hata. Eklenti günlüklerini kontrol edin.

---

Desteklenen komutların listesi

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.