nemo-relay-plugin-build

プラグインを構築する

ユーザーが、再利用可能な NeMo Relay ランタイムの動作をプラグイン設定で提供したい場合に、このスキルを使用します。 再利用可能なプラグインの動作は、単発のアプリケーション起動コードと分けてください。

こんな場合に使用

共有設定によって動作を有効化し、アプリケーション、チーム、またはプロセスの起動経路をまたいで再利用する場合に、このスキルを使用します。

一般的なケース：

• サブスクライバー、ガードレール、インターセプト、または関連するランタイム動作の小さなセットを登録する。
• ランタイムの動作を変更する前に、オペレーターが指定した設定を検証する。
• 再利用可能な動作に、安定したプラグイン kind と有効化のライフサイクルを与える。
• アプリケーション起動コードを繰り返すのではなく、プラグイン設定で有効化、無効化、または段階的に展開する動作をパッケージ化する。

こんな場合には使用しない

より限定的な NeMo Relay の機能で十分な場合は、プラグインを構築しないでください。

• 1 つのリクエストまたはテナントだけに一時的な動作が必要な場合 → スコープローカルのミドルウェアを使用します。
• 初回のスコープ、ツール呼び出し、または LLM 呼び出しだけが必要な場合 → nemo-relay-instrument-calls を使用します。
• エクスポーターのパスを選択するだけでよい場合 → nemo-relay-plugin-observability を使用します。
• 動作が、設定内の実行時の呼び出し可能オブジェクト、プロバイダークライアント、ファイルハンドル、認証情報、またはフレームワークオブジェクトに依存する場合。

配布モデルを選択する

設定や登録を設計する前に、配布モデルを選択してください。

• 組み込みコンポーネント： 動作を Relay ホストアプリケーションとともに配布する場合は、共有プラグインドキュメントを使用します。以下の組み込みコンポーネントモデルに従ってください。
• 動的に検出可能なパッケージ： プラグインをホストとは独立して配布する場合は、relay-plugin.toml マニフェストを使用します。信頼できるプロセス内のネイティブ Rust ライブラリには rust_dynamic を、ローカルの grpc-v1 ワーカーには worker を使用します。パッケージの境界を設計する前に、公開されているネイティブ動的プラグインまたは gRPC ワーカーのガイドを参照してください。ネイティブ ABI やワーカープロトコルの詳細を記憶に頼って再現しないでください。

ネイティブプラグインは、Relay プロセス内で実行される信頼済みの C-ABI 拡張機能であり、サンドボックス化されません。ワーカープラグインはプロセス分離を提供しますが、セキュリティサンドボックスではありません。

組み込みコンポーネントモデル

• プラグインは、再利用可能なプロセスレベルの動作をパッケージ化します。
• プラグインは安定した kind 文字列を公開し、共有プラグインドキュメントからコンポーネント固有の設定を受け取ります。
• プラグイン設定は、Rust、Python、Node.js、ファイル、テスト、デプロイシステム間で互換性のある JSON 形式でなければなりません。
• 検証は決定論的で、副作用がありません。設定を調べ、ランタイムの動作が変更される前に構造化された診断情報を返します。
• 登録は検証後に実行され、サブスクライバー、ガードレール、リクエストインターセプト、実行インターセプト、ストリーム実行インターセプトなど、PluginContext を通じて実際の動作を組み込みます。
• PluginContext により、プラグインシステムはランタイム名を適切に修飾し、有効化に失敗した場合に部分的なセットアップをロールバックできるだけの所有権を得られます。
• 可能な場合は無効化されたコンポーネントも検証し、オペレーターが展開前に設定の問題を見つけられるようにしてください。

既定の手順

1. プラグインが本当に必要かどうかを判断します。ユースケースが再利用可能なプロセスレベルの動作ではない場合は、直接計装するか、スコープ内の動作を優先してください。
2. 埋め込みコンポーネントか、検出可能な動的パッケージを選択します。動的パッケージの場合は、動作を実装する前に、マニフェストに基づくネイティブまたはワーカーの境界を確立してください。
3. ネイティブの動的プラグインでは、コールバック API を選択する前に、パッケージの制約、ロックファイル、またはデプロイ先のバージョンから対象の Relay バージョンを特定します。
4. 最初に使用するランタイムサーフェスを 1 つ選びます。サブスクライバー指向のエクスポート、サニタイズガードレール、条件付きガードレール、リクエストインターセプト、実行インターセプト、またはストリーム実行インターセプトです。
5. 安定したプラグイン kind と、最小限の JSON 互換設定スキーマを選びます。
6. フィールドの欠落、未対応の値、不明なフィールド、安全でない設定、無効なフィールドの組み合わせに対する診断を定義します。
7. 初期化の前に設定を検証します。検証時にネットワーク接続を開いたり、クライアントを作成したり、ミドルウェアを登録したり、プロセスの状態を変更したりしてはいけません。
8. 検証でエラー診断が返された場合は、それを返して、初期化や登録を行わずに停止します。
9. アプリケーションの起動時にグローバルな動作を手動で登録するのではなく、PluginContext を通じてランタイムの動作を登録します。
10. 有効化、無効なコンポーネント、検証エラー、登録失敗時のロールバックをテストします。
11. プラグインの有効化方法、対応する設定フィールド、コンポーネントのロールバック方法を説明します。
12. 動的プラグインで nemo-relay plugins edit に構造化フィールドを提供する場合は、config_schema 機能を宣言し、relay-plugin.toml の [config_schema].path からローカルの Draft 7 または Draft 2020-12 JSON Schema ファイルを参照します。スキーマのないプラグインは、未加工の JSON オブジェクトとして引き続き編集できます。

設定スキーマ

プラグインドキュメントの最上位には、version、components、policy が含まれます。 各コンポーネントには、プラグインの kind、enabled、コンポーネント固有の config を指定します。

{
  "version": 1,
  "components": [
    {
      "kind": "redaction-policy",
      "enabled": true,
      "config": {
        "preset": "strict"
      }
    }
  ],
  "policy": {
    "unknown_component": "warn",
    "unknown_field": "warn",
    "unsupported_value": "error"
  }
}

ビジネスロジックは設定ではなくプラグインコードに記述します。機密情報を埋め込むのではなく、シークレットやエンドポイントへの参照を使用してください。

バインディングの参照先

• Python：nemo_relay.plugin
• Node.js：nemo-relay-node/plugin
• Rust：nemo_relay::plugin
• Go と raw FFI は、ソース優先または上級者向けのサーフェスです。

すべてのバインディングとファイルで、同じ正規の snake_case 設定キーを使用します。Node のヘルパー関数には camelCase を使用できますが、プラグインの設定オブジェクトは snake_case のままにします。

動的パッケージの基本事項

マニフェストのパッケージ契約と、オペレーターが使用するプラグインドキュメントは分けてください。マニフェストでは、レーン固有の kind とロード契約、通常の SemVer による Relay 互換性範囲、アーティファクトの整合性、プラグインに必要な機能のみを宣言する必要があります。構造化された CLI 編集が必要な場合にのみ、ローカルの config_schema を使用してください。

ネイティブバージョンの互換性

対象の Relay バージョンに応じてネイティブコールバックモデルを選択してください。0.8 SDK が 0.7 とソース互換であるかのように説明してはいけません。

• Relay 0.7: 型付き Rust ミドルウェアコールバックは同期処理のままにしてください。非同期処理が必要な場合に限り、ネイティブ ABI v3 の生の完了ベース登録パスを使用し、マニフェストの互換性を compat.relay = ">=0.7,<0.8" に制限してください。
• Relay 0.8: 型付き Rust SDK 経由でフューチャーを返し、マニフェストの互換性を compat.relay = ">=0.8.0,<1.0" に制限してください。SDK は SDK が所有する Tokio エグゼキューター上で型付きミドルウェアを実行します。サブスクライバーと生の同期 ABI 登録は同期処理のままです。エグゼキューターワーカーをブロックしないでください。スコープコンテキストは tokio::spawn で作成したタスクに自動的には引き継がれません。また、アンロード前に新しいコールバックを停止し、受け付け済みの処理をすべて完了させる必要があります。

0.8 の型付き SDK では、ネイティブコンポーネントが正の値を持つ executor.worker_threads を設定して、エグゼキューターを構成できます。マニフェストで config_schema を公開する場合は、この SDK 所有のオブジェクトとフィールドをスキーマに含めてください。ネイティブ ABI の詳細、コールバックの完了処理またはキャンセル、完全なワーカープロトコルについては、このスキルを拡張するのではなく、該当する公開ダイナミックプラグインガイドを参照してください。

避けるべき失敗パターン

• 呼び出し可能なオブジェクト、クライアント、認証情報、フレームワークオブジェクト、ファイルハンドル、キャッシュをプラグイン設定に含めないでください。
• 検証中にランタイム登録を実行しないでください。
• 無効化されたコンポーネントの検証を省略しないでください。
• ランタイムの動作を PluginContext に任せるべき場合に、グローバルな起動コードから直接登録しないでください。
• 1 つの設定ドキュメントが明確に一括管理している場合を除き、無関係なサブスクライバー、リクエスト変換、ポリシーチェックを最初のプラグインにまとめないでください。
• 本番環境の生ペイロードやシークレットをエクスポートしないでください。データがプロセス外に出る前にテレメトリーをサニタイズしてください。
• アクティベーションの部分的な失敗を無視しないでください。ロールバックするか、明確な診断情報を提示してください。
• ネイティブプロセスの分離をセキュリティ境界とみなしたり、ワーカーがサンドボックス化されていると主張したりしないでください。
• 0.8 の型付き非同期コールバック契約を Relay 0.7 に適用したり、0.7 の生の完了契約を型付き 0.8 ミドルウェアに適用したりしないでください。
• 0.8 SDK が所有するエグゼキューターをブロックしないでください。

検証チェックリスト

• 安定したプラグイン kind を選択している。
• 配信モデル（組み込みコンポーネント、rust_dynamic、または worker）を選択している。
• 設定の形式が JSON 互換で、snake_case を使用している。
• 必須フィールドと未対応の値に対して、安定した診断情報を返す。
• 不明なフィールドが設定済みのポリシーに従う。
• 可能な場合は、無効化されたコンポーネントについても設定の問題を報告する。
• 初期化時に PluginContext を通じて動作をインストールする。
• 登録を強制的に失敗させても、ランタイムの動作が部分的に有効なまま残らない。
• プラグインの有効化とロールバックの方法をドキュメントまたは例で示す。
• 構造化された CLI 編集が必要なダイナミックプラグインは、有効なローカル JSON Schema をパッケージに含め、relay-plugin.toml で config_schema を宣言する。
• ダイナミックマニフェストが、レーン固有の kind、ロード契約、SemVer 互換性、整合性、無効化レコードの動作を検証する。
• ネイティブコールバック API と互換性制約が対象の Relay バージョンに一致している。0.7 では同期型の型付きコールバックと生の ABI v3 による完了処理が使用でき、0.8 では型付き非同期 SDK ミドルウェアとエグゼキューター設定が使用できる。
• 非同期のネイティブ処理で、キャンセル、完了処理、アンロード前のドレイン動作に対応する。

別のスキルを使う場合

• 直接的なツール呼び出しまたは LLM 呼び出しをラップするだけの場合 → nemo-relay-instrument-calls
• プラグインをパッケージ化せずにトレースまたはエクスポーターを設定する場合 → nemo-relay-plugin-observability
• プラグインのアクティベーション、イベントの欠落、ロード失敗をデバッグする場合 → nemo-relay-debug-runtime-integration