Ogma

外観

プラグインフロントエンド SDK リファレンス ​

プラグインのフロントエンドコードは、サンドボックス化された iframe 内で実行されます。このドキュメントは低レベルのリファレンスです。概要については README.md をご覧ください。

セキュリティモデル ​

項目値
iframe サンドボックスallow-scripts のみ（allow-same-origin なし）
CSP script-srcnonce による制限。エントリポイントのスクリプトのみを読み込みます
CSP connect-src'self'：プラグインは /plugins/{id}/api/* に POST し、/plugins/{id}/events/poll をポーリングできます
CSP default-src'none'
親 DOM へのアクセスブロック（allow-same-origin なし）
Ogma セッション Cookieプラグインからはアクセス不可
プラグイン間の通信利用不可

データブリッジの呼び出しは、リクエストごとにサーバー側で認可されます。表示やナビゲーション操作はホスト UI が処理します。権限タブに表示される権限キャッシュは表示専用で、データアクセスの制御には使用されません。

ブリッジプロトコル ​

プラグインの JS は postMessage で Ogma ホストと通信します。ホスト側の処理は PluginsView.vue にあり、bridge_request メッセージを扱います。

リクエストエンベロープ ​

ts
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 バイト。

レスポンスエンベロープ ​

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

生の postMessage ブリッジリクエストを手動で送信しないでください。グローバルの ogmaSDK を使用します。

js
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 を返します。名前に Raw が含まれますが、返すのはボディのバイト列であり、生の HTTP メッセージ全体ではありません。サポートされるコンテンツエンコーディングは、抽出前にデコードされます。各ボディの上限は 256 KiB です。完全なアセットとして処理する前に、切り詰めフラグを確認してください。

必要な権限：read_http_history（自動付与）。

ペイロード：{ 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 }（name は最大 64 文字、path は最大 256 文字）

プラグインパネル内のナビゲーションを登録します。プラグインあたり最大 20 項目です。対応するページの内容は sdk.navigation.addPage(path, { title, body }) で登録します。項目を選択すると iframe 内にそのページが表示され、Ogma ワークスペースの新しいトップレベルルートにはなりません。

ogma.backend.call ​

ペイロード：{ method: string, args: unknown[] }

sdk.api.register(method, fn) で登録したバックエンド RPC ハンドラーを呼び出します。メソッド名は最大 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 は、sdk.navigation.addPage(path, options) のオプションとして { body: HTMLElement } も受け付けます。ボディを iframe 内に追加し、ホストが対応するサイドバー項目を選択すると、ページの表示を切り替えます。DOM ノードはローカルに留まり、ブリッジ経由でシリアライズされることはありません。

ogma.window.showToast ​

ペイロード：{ message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

プラグインパネルにトーストを表示します。表示時間の単位はミリ秒です（最大 10000、既定値 3000）。

ogma.commands.register ​

ペイロード：{ id: string, name: string }

ホストのコマンドストアにプラグインコマンドを登録します。ホストが実行すると、commandId とコンテキストを含む plugin_command メッセージが 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 のテーマを読み取り、ホストのテーマ更新を購読します。プラグイン UI を 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.

プロプライエタリソフトウェア。すべての権利を保有します。

著作権 © 2024 年から現在 OgmaBox