Plugin
Plugin は、コンテンツアドレス指定された WebAssembly プラグインです。これは sha256 ダイジェストで固定された、OCI 上でホストされる .wasm アーティファクトであり、実装するソケットタイプ、対象とする ABI バージョン、任意の署名ポインタ、および任意のランタイムブロックを宣言します。このエンティティは、プラグインのオーサリングとメタデータのための面です。依存関係の解決によってアーティファクトはダイジェストで固定され、レジストリごとのトラストポリシーがプル時にその署名を検証します。コンパイラはプラグインの動作を解釈しません。コンパイラは固定された参照をルーティングし、WebAssembly ランタイムがそのバイト列を実行します。
このページでは、Plugin カタログのオーサリング面をフィールドごとに説明します。プラグインとは何か、describe() による自己申告、公開→プル→ビルドのライフサイクル、署名、バージョニングといった、作成者のエンドツーエンドのワークフローについては、Wasm プラグイン開発者ガイドを参照してください。プラグインが接続するソケットポイントと、その入出力の形については、Wasm プラグインコントラクトを参照してください。
Plugin の役割
Plugin は、論理的なプラグインの識別子を具体的な .wasm アーティファクトに結び付け、さらにホストがそれを安全にロードして実行するために必要なケイパビリティおよびランタイムのメタデータに結び付けます。パイプラインステップやプラグインソケットは、この エンティティを URI で参照します。エンティティは宣言されたケイパビリティ、ランタイムの制限、署名ポインタを保持し、解決済みのコンテンツダイジェストはリリースのロックファイルに格納されます。.wasm の場所はプラグインの識別子、すなわちアドレス可能な座標 plugin/<pluginType>/<name>(これ自体は metadata.pluginType と接頭辞のない metadata.name から構成されます)と、設定されたレジストリから導出され、記述するフィールドではありません。エンティティを介した間接参照は必須です。素の .wasm やアーティファクト参照は、一致するエンティティがないため、ロード時に拒否されます。
Plugin の宣言はソケットタイプごとにグループ化されており、エンティティを読むときはこのグループ化から始めます。
- ソケットタイプごとに 1 つのブロック —
spec.provider、spec.pipelineStep、spec.parser、spec.importer。プラグインは、そのmetadata.pluginTypeが示す 1 つのブロックを持ち、各ブロックはcapabilities:リストを保持します。このリストはaggrega plugin gen-catalogがプラグイン自身のdescribe()から記録したもので、その意味はそのブロックだけに属します。プロバイダーのリストは提供するケイパビリティを示し、パイプラインステップのリストはそのステップが互換性を持つプロバイダーのケイパビリティを示し、パーサーとインポーターのリストはソース形式を示し、それぞれparse:<format>およびimport:<format>と記述します。意味を担うのは包含関係です。ケイパビリティのエントリには、それがどの種類の主張であるかを示すブロックを先に読まずに到達することはできません。 - プロバイダーブロックはリスト以上のものを持ちます —
spec.providerは、プラグインが Workload の種類をどのように変換するか、どのプラットフォームネイティブのアノテーションを読み取るか、およびレンダリング動作の契約(spec.provider.contract:入力の種類、境界の組み立て、アーティファクトの区切り文字、インスタンスの再利用)も宣言します。これらは提供されるディメンションではなくレンダリングの動作を記述するため、プロバイダーのケイパビリティリストの中ではなく、その横に置かれます。 - 横断的なソケットはケイパビリティを宣言しません —
linter、governance、cliのプラグインは、レンダリングのディメンションもソース形式も提供しないため、4 つのブロックのいずれも持ちません。
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: aws-secrets-manager version: 1.2.0 pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: # capabilities is recorded by `aggrega plugin gen-catalog` from the plugin's describe(); an author may narrow it. capabilities: - helm - compose signature: type: sigstore-cosign runtime: maxMemoryPages: 256 timeoutMs: 5000 # hostFunctions is recorded by `aggrega plugin sync` from the .wasm — do not author it. exports: - name: fetch operates: emit scope: own selector: external-secret resources for the bound credentialmetadata
標準のカタログメタデータです。name、version、pluginType は必須です。version は厳密なセマンティックバージョン(例: 1.2.0)です。任意のフィールド(description、maintainers、license、repository、home、keywords)は、すべてのカタログエンティティが持つものと同じ形に従い、metadata はそれ以外のキーを受け付けません。公開されたバージョンは変更できません。既存のバージョンを再公開すると、公開ゲートで拒否されます。
metadata.name は修飾なしの名前であり、ソケットのプレフィックスを持ちません。プラグインのアドレス指定可能な座標 plugin/<pluginType>/<name> は、metadata.pluginType と修飾なしの metadata.name から導出されます。名前に書き込むものではありません。
metadata.pluginType
このプラグインが実装するソケットタイプです。これはプラグインの識別情報の一部であるため、アドレス指定ブロック内で name および version と並んで置かれます。導出される plugin/<pluginType>/<name> 座標の <pluginType> セグメントを供給します。プラグインはちょうど 1 つのソケットタイプを実装し、そのソケットタイプはランタイムが認識するプラグインタイプの分類から選ばれます。
provider— IR ノードをプロバイダーネイティブなアーティファクトにレンダリングします。linter— 記述されたコンテンツを検査し、診断を発行します。pipeline-step— FeatureRecipe または Recipe のpipeline:内のステップで、レンダリングされたドキュメントセットにパッチを適用します。governance— ビルドパイプラインのガバナンスロールを担います。トポロジー構築時には、トポロジーグラフのノードラベルを自動タグ付けし、ホストがグラフのラベルのみの射影に適用する JSON Patch ドキュメントを返します。静的解析時またはレンダーステージでは、IR グラフまたはレンダリングされたアーティファクトを評価し、受理/拒否の判定を返します。失敗したルールはビルドを停止させます。何を出力できるかを決めるのは、その種類ではなく、アタッチされるロールです。parser— 外部のソース形式(HCL、TOML、YAML、JSON、…)を構造化された JSON ツリーにパースします。これにより、コンパイラがネイティブにパースしない形式を読む必要があるコンシューマーは、生のテキストではなくパース済みのツリーを扱えます。importer— 外部のインフラストラクチャまたはエージェント定義のソースを、Aggrega の記述ファイルの下書きに変換します。扱う形式はimport:<format>ケイパビリティとして公開されます。cli— オペレーターがコマンドラインで呼び出すランタイムのaggrega <cmd>サブコマンドを提供します。コンパイル時のレンダーソケットやパイプラインソケットとは異なる、ランタイムソケットです。
必須です。
spec.abiVersion
プラグインが対象とするホスト/ゲスト ABI のバージョンです。受け付けられる値は v1beta1 で、新しい ABI 改訂で値が 1 つ追加されます。必須です。
ケイパビリティの宣言:ソケット種別ごとに 1 つのブロック
ケイパビリティとは、利用側がプラグインに求めるものです。Recipe が要求するレンダリングケイパビリティや、ビルドが読み込む必要のあるソース形式がこれにあたります。プラグインのケイパビリティは、そのソケットタイプに属するブロック内に記録されます。したがって、リストがどのブロックに置かれているかによって、そのエントリの意味が決まります。
metadata.pluginType | ケイパビリティを宣言する場所 | エントリが示すもの |
|---|---|---|
provider | spec.provider.capabilities | このプラグインが提供するレンダリングケイパビリティ(helm や compose など)。 |
pipeline-step | spec.pipelineStep.capabilities | このプラグインのステップが互換性を持つ、レンダリング出力を生成するプロバイダー。 |
parser | spec.parser.capabilities | このプラグインが読み込むソース形式。parse:<format> と記述します。 |
importer | spec.importer.capabilities | このプラグインがエンティティの下書きを作成する元となる外部ソース形式。import:<format> と記述します。 |
linter, governance, cli | — | なし。これらのソケットはケイパビリティを提供しないため、4 つのブロックのいずれも持ちません。 |
プラグインはちょうど 1 つのソケットタイプを実装するため、そのエンティティは 1 つのブロックを持ちます。リストはプラグイン自身の報告です。aggrega plugin gen-catalog がプラグインの describe() を読み取り、報告された各ケイパビリティをブロックに書き込みます。作成者は公開前にリストを絞り込み、プラグインが報告するケイパビリティのうち、公開するエンティティが提供すべきでないものを除くことができます。aggrega validate <entity> --plugin <file.wasm> と aggrega push は絞り込まれたリストを受け付け、プラグインが報告するケイパビリティのうちリストが除いているものをそれぞれ示す通知を出力します。どちらも、プラグインが報告しないケイパビリティを含むリストは受け付けません。どちらもそのリストを拒否し、該当する各ケイパビリティとプラグインが実際に報告するケイパビリティを示します。そのため、公開されたリストがプラグインの提供する以上のものを提供することはありません。プラグインが helm と helm-chart を報告するのに compose も列挙している pipeline-step エンティティは、次のように拒否されます。
[E0080] entity "probe-step:1.0.0-rc.1" lists capabilities ["compose"], which the plugin's describe() does not report (it reports ["helm" "helm-chart"]); remove them from the list, which may name only capabilities the plugin reports: wasm: entity contract claim does not match plugin describe()利用側は、列挙されているものだけに対して解決します。
spec.provider
pluginType: provider プラグインのプロバイダーソケットブロックです。提供する機能、プラットフォームが所有する aggrega.ai/v1beta1 Workload kind をどのように変換するか、どのプラットフォームネイティブなアノテーションを読み取るか、そしてレンダリング動作の契約を記述します。このブロックはプロバイダーとしてレンダリングするすべてのプラグインに存在し、それ以外のプラグインタイプには存在しません。Workload の合成を行わず、ソースまたはアーティファクトのコンテンツのみをレンダリングするプロバイダーもこのブロックを持ちます。その場合は機能と契約をここで宣言し、workloadSchema を省略するだけです。
spec.provider.capabilities
このプロバイダーが提供する機能、つまり helm や compose などの機能名で、プロバイダーはその出力形状をレンダリングします。プロバイダーは、ある機能の出力形状を共有するアーティファクト全体にわたって汎用的ですが、すべての機能にわたって汎用的なわけではありません。そのため、このリストはプラグイン自身が報告する機能を示します。aggrega plugin gen-catalog がプラグインの describe() からリストを記録し、作成者は公開前にそれを絞り込むことができます。エントリは記録された順序を保持します。
Recipe が要求するプロバイダーターゲット(spec.capability: helm)は、そのターゲットをリストに含むプロバイダープラグインに解決されます。複数のプロバイダープラグインが同じターゲットをリストに含む場合は、ワークスペースが選択します。ワークスペース設定の plugins.providers の選択が使用するプラグインを指定し、これは aggrega pull の時点で解決されてロックファイルに記録されます。選択がなく候補がちょうど 1 つの場合はその候補が使用され、選択がなく候補が複数ある場合はビルドが停止し、すべての候補を示します。曖昧さは、カタログ全体での一意性の規則ではなく、使用する時点でワークスペースごとに解決されます。リストが空または存在しない場合は機能の主張を宣言しないため、そのプラグインはどのターゲットも提供しません。
ここでの機能名にはコロンを含めません。Recipe の spec.capability は、最後のコロンまでが機能、その後がバージョン固定として読み取られるため、コロンを含む名前は要求できません。describe() がそのような名前を報告するプラグインは読み込み時に拒否され、そこから公開用のエンティティは生成されません。pipeline-step プラグインがリストするプロバイダー機能についても同様です。パーサーの parse:<format> やインポーターの import:<format> のコロンはそれらの名前の一部であり、そのまま残ります。
spec.provider.workloadSchema
このプロバイダーが aggrega.ai/v1beta1 Workload kind をプロバイダーネイティブなマニフェストにどのように変換するかを文書化する JSON Schema 2020-12 の宣言です。合成を行うプロバイダーでは慣例により宣言されます。そのようなプロバイダーは、文書化された変換の契約として workloadSchema を宣言し、プロバイダーが消費する Workload フィールド、各列挙型フィールドが受け付ける閉じた集合、適用される範囲の制約を記述します。
本体は Plugin の読み込み時に JSON Schema 2020-12 にコンパイルされます。これは、不正な形式のスキーマをレンダリング時ではなく読み込み時に拒否する構造上のガードレールです。workload: Recipe がサポートされるかどうかは、このフィールドの有無ではなく、バインドされたプロバイダーの合成機能によって決まります。合成できないプロバイダーにバインドされた合成モードの Recipe は、レンダリング時に明示的に停止します。標準ライブラリのカタログは workloadSchema をプロバイダーの機能と同期させています。このフィールドは文書化された契約であり、それ以外にこれを読むものはありません。Workload の本体自体は、このプロバイダーごとのフィールドではなく、プラットフォームが所有する組み込みの Workload スキーマに対して検証されます。
spec.provider.wellKnownAnnotations
このプロバイダーが読み取るプラットフォームネイティブなウェルノウンアノテーションキー(予約済みの aggrega.ai/ 名前空間の下にあるもの)と、それぞれが存在しない場合に適用される動作を列挙する順序付き配列です。各エントリは、key(プロバイダーが読み取るアノテーション。例: aggrega.ai/namespace)、purpose(アノテーションが存在する場合に制御する内容)、省略可能な defaultBehavior(アノテーションが存在しない場合のプロバイダーの動作)、および省略可能な scope(プロバイダーがキーを読み取る場所の一覧。Recipe の入力種別である sourced、synthesized、artifactsStandalone、または境界ごとに 1 回読み取られるキーの場合は boundary)を持ちます。key と purpose は必須で、エントリは作成者が記述した順序を保持します。
このフィールドはプロバイダーのサポートの主張であり、コンパイラはこれを 2 つの方法で読みます。scope が、ブロック自身の contract.inputKinds が主張していない入力種別を指定しているエントリはその主張と矛盾するため、Plugin は拒否され、キーとスコープが示されます。また、ビルドがこのプロバイダーを通じてレンダリングするとき、そのレンダリングが宣言するどの入力種別についてもエントリがカバーしていない aggrega.ai/ アノテーションは、キー、プロバイダー、それらの入力種別を示す警告を発生させます。値はそのまま渡され、ビルドは停止しません。フィールドがない場合は何も主張せず、このプロバイダーについてそのような警告は発生しません。スキーマ検証は各エントリの形状(キーが aggrega.ai/ 名前空間の下にあること、purpose が存在すること)のみを確認します。これは、予約済みの名前空間に値をバインドすることを管理する実行時のチェックとは別のものです。
metadata: pluginType: providerspec: abiVersion: v1beta1 provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm workloadSchema: | # how the Workload kind translates to this provider's native output ... wellKnownAnnotations: - key: aggrega.ai/namespace purpose: Overrides the target namespace the provider renders into. defaultBehavior: Renders into the boundary's default namespace.標準ライブラリのプロバイダーが提供するプロバイダーごとのアノテーションセットと workloadSchema の内容は、../providers/well-known-annotations.md、../providers/helm.md、../providers/helm-chart.md、../providers/compose.md に記載されています。
spec.provider.readsNoWellKnownAnnotations
このプロバイダーがプラットフォームネイティブの既知のアノテーションキーを 1 つも読み取らないことを宣言します。これはどのキーもカバーしないサポートの主張であり、これと wellKnownAnnotations の両方を省略した場合には伝わらないことを伝えます。主張がないことは沈黙ですが、こちらは予約済みの aggrega.ai/ 名前空間の下にあるものを何も読み取らないというプロバイダー自身の表明です。そのようなプロバイダーを通じてレンダリングするビルドは、レンダリングに到達するすべての aggrega.ai/ アノテーションについて、キー、プロバイダー、レンダリングが宣言する入力種別を示して警告します。値はそのまま渡され、ビルドは停止しません。
書けるのは true だけなので、何も表明しない方法は引き続きフィールドを省略することだけです。wellKnownAnnotations と一緒に書くことはできません。キーの一部を読み取るプロバイダーは、代わりにそれらのキーをそちらに列挙します。どちらの拒否もスキーマレベルであるため、Plugin は読み込まれた時点で拒否されます。
spec: provider: capabilities: - terraform readsNoWellKnownAnnotations: true標準ライブラリの terraform プロバイダーはこれを宣言しています。これを通じてレンダリングされる Release にとってそれが何を意味するかは、../providers/terraform.md で説明しています。
spec.provider.contract
provider をレンダリングするプラグインが自ら宣言する、コンパイル時のレンダリング動作の契約です。レンダリングする入力の種類、ディスパッチグループのノードごとの出力をどう組み立てるか、インポートされたアーティファクトファイルに適用するテンプレート区切り文字の組、ロードした 1 つのインスタンスがすべての呼び出しを処理できるかどうか、omit エントリを尊重するかどうか、そして Recipe がそのバウンダリの共有出力に提供するファイルを受け入れるかどうかを表します。同じブロック内で capabilities の隣に置かれますが、答える問いは異なります。capability のリストはこのプラグインがどの capability を提供するかを示し、契約はそれらをどのようにレンダリングするかを示します。aggrega plugin gen-catalog がプラグイン自身の describe() による自己申告からこれを記録し、ホストは公開時とロード時にその自己申告と照合します。不一致があると停止します。省略した場合はレンダリング動作の契約を宣言しないことになり、照合ではエクスポートごとの主張のみが比較されます。すべてのフィールドは任意です。
| フィールド | 効果 |
|---|---|
inputKinds | 3 種類の Recipe 入力のうちプラグインがどれをレンダリングするかを、それぞれ独立した真偽値の主張として示します。sourced(ソースとなるファイルセット。チャート、モジュール、compose ファイルなど)、synthesized(合成された Workload)、artifactsStandalone(インポートされたアーティファクトドキュメントを持ち、ソースも workload も持たないスタンドアロンのノード)です。ホストはノードの入力の種類をこのセットに照らして判定します。 |
boundaryAssembly | プラグインがディスパッチグループのノードごとのレンダリング出力をどう結合するかを示します。none は各ノードの出力をディスパッチパスに直接書き込みます。merge はノードごとの断片を 1 つのドキュメントにまとめます。nest は各ノードの出力を包括的な構造の中のそれぞれの位置に配置します。省略した場合は組み立てに関する主張を持ちません。 |
artifactDelimiters | プラグインがインポートされたアーティファクトファイルに適用する Go テンプレートの区切り文字の組で、left と right で指定します。省略した場合はデフォルトの {{/}} の組になります。対象の構文がこの組と衝突するプラグインは、別の組(たとえば [[/]])を宣言します。 |
reusableInstance | 呼び出しごとに新しいインスタンスを使うのではなく、ロードした 1 つのプラグインインスタンスがビルド中のすべての render、assemble、validate の呼び出しを処理できるかどうかを示します。true を宣言するのは、プラグインが呼び出しをまたいで状態を保持せず、単一のインスタンスが再利用時も新規ロード時もバイト単位で同一の出力を生成する場合に限ります。省略した場合(false)は呼び出しごとに新しいインスタンスをロードし、構造上状態を持つプラグインを分離します。aggrega build --verify-determinism は各ノードを 2 回レンダリングし、差異があれば停止することで、再利用可能なプラグインの出力が安定していることを検証します。 |
omits | プラグインが omit エントリ(ノードの出力から除外するレンダリング単位を指定するエントリ)を尊重するかどうかを示します。尊重する場合、エントリに一致するすべての単位をレンダリング結果から除外し、各エントリがいくつの単位に一致したかを報告します。この値はプラグインの describe() が報告する主張を記録するものなので、true が正しいのはそれを報告するプラグインに限られ、報告と異なる値の場合は停止します。省略した場合(false)はそのようなサポートを宣言しません。 |
boundaryArtifacts | Recipe の spec.boundary.artifacts のもとで、Recipe がレンダリング先のバウンダリの共有出力に提供するファイルを、プラグインの対象が受け入れるかどうかを示します。コンパイラはそのような各ファイルを、プラグインがバウンダリ用に組み立てるものの隣に 1 回だけ書き込み、対象はそれをその出力の一部として読み込みます。この値はプラグインの describe() が報告する主張を記録するもので、報告と異なる値の場合は停止します。省略した場合(false)はそのようなサポートを宣言せず、このプラグインに対してこのブロックを宣言した Recipe は、何もレンダリングされる前に拒否されます。 |
metadata: pluginType: providerspec: provider: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm-chart contract: inputKinds: sourced: true synthesized: false artifactsStandalone: false boundaryAssembly: nest artifactDelimiters: left: "[[" right: "]]" reusableInstance: truespec.pipelineStep
pluginType: pipeline-step プラグインのためのパイプラインステップブロックです。唯一のフィールドである capabilities は、プラグインのステップが変換方法を知っているレンダリング出力を持つプロバイダーを、helm や compose などの capability 名で指定します。ステップは一度に 1 つのプロバイダーの出力形式に対して書かれるため、このリストはプラグイン自身が報告するプロバイダーを示します。エントリは記録された順序を保持します。このブロックはパイプラインステッププラグインにのみ存在します。
このブロックは、その主張をカタログから読み取れる形で記録したものです。aggrega plugin gen-catalog がプラグイン自身の describe() による自己報告から記録し、作成者は公開前にそれを絞り込むことができます。強制は同じ主張をプラグインから読み取ります。ステップがあるスコープに触れるとき、そのスコープのドキュメントをレンダリングするプロバイダーがプラグインの主張するプロバイダーに含まれていなければ、ビルドは停止します。リストが空または存在しない場合は互換性の主張を宣言しないため、どのスコープもそのステップを受け入れません。
metadata: pluginType: pipeline-stepspec: abiVersion: v1beta1 pipelineStep: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - helm - composespec.parser
pluginType: parser プラグインのパーサーブロックです。唯一のフィールドである capabilities は、プラグインが正規の構造化ツリーに変換するソース形式を指定し、各エントリは parse:<format> と記述します。接頭辞はエントリの一部であるため、複数の形式を読み込むプラグインは形式ごとに 1 つのエントリを列挙します。aggrega plugin gen-catalog がプラグイン自身の describe() からリストを記録し、作成者は公開前にそれを絞り込むことができ、エントリは記録された順序を保持します。このブロックはパーサープラグインにのみ存在します。
要求された形式は、一致するエントリをリストに含むパーサーに解決されます。どのパーサーも公開していない形式はビルドを停止させ、複数のパーサープラグインが公開している形式は、候補を挙げたうえで曖昧として停止します。フォールバックはありません。パーサーには、フォールバック先となる設定不要のデフォルトがないためです。リストが空または存在しない場合は形式の主張を宣言しないため、そのプラグインは何も解析しません。
metadata: pluginType: parserspec: abiVersion: v1beta1 parser: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - parse:hcl - parse:tomlspec.importer
pluginType: importer プラグインのための importer ブロックです。その capabilities フィールドは、プラグインが Aggrega の下書きオーサリングファイルに変換する外部ソース形式を列挙し、それぞれ import:<format> と記述します。接頭辞はエントリの一部であるため、複数の形式を扱うプラグインは形式ごとに 1 つのエントリを列挙します。aggrega plugin gen-catalog がプラグイン自身の describe() からリストを記録し、作成者は公開前にそれを絞り込むことができ、エントリは記録された順序を保持します。このブロックは importer プラグインにのみ存在します。
要求されたインポート形式は、一致するエントリをリストに含む importer に解決されます。どの importer も公開していない形式はインポートを停止させます。複数の importer プラグインが公開している形式は、候補を挙げて曖昧として停止します。ただし、ワークスペース設定の plugins.importer エントリがそのうちの 1 つを割り当てている場合は、その importer が実行されます。リストが空または存在しない場合は形式を主張しないことを宣言するため、そのプラグインは何もインポートしません。
detect フィールドは、インポートが形式を指定しない場合に、それらの形式のソースを認識するためのシグネチャを記録します。これはホスト関数やコマンドの記録と同様に機械が管理するものです。エンティティがプラグインから生成される際に、プラグインの describe() が報告する内容から、プラグインがシグネチャを宣言した順序で導出され、作成者は記述しません。各シグネチャは次を指定します。
syntax— ソースを解析する構文形式です。parser プラグインがparse:<syntax>として公開する形式で、jsonやyamlなどです。files— 省略可能なファイル名パターンで、ソース名の末尾と照合されます。1 セグメントのパターンはファイル自体の名前と、スラッシュで区切られた複数セグメントのパターンはパスの末尾の同数のセグメントと照合されるため、.vscode/mcp.jsonは.vscodeという名前のディレクトリにあるmcp.jsonという名前のファイルに一致します。*、?、[...]はセグメント内で一致します。指定がない場合、シグネチャは名前にかかわらず 1 つのファイルであるソースに適用され、ディレクトリ内のファイルには適用されません。importer のシグネチャのパターンは、aggrega importがディレクトリ内のどのファイルをその importer に渡すかを決めるものでもあります。match— 解析済みツリーが満たさなければならない述語で、すべてを満たす必要があります。各述語は、ツリーの最上位からキーをドットで連結したpath(整数のセグメントは配列の位置を選択します)、present、absent、object、array、string、number、booleanのいずれかであるis、および省略可能な、値と一致すべき文字列equalsまたは値の先頭となるべき文字列prefix(2 つのうち最大 1 つ)を持ちます。
インポートが形式を指定しない場合、ワークスペースのカタログが保持するすべての importer(すべてのバージョンを含む)とコンパイラのコア importerのシグネチャがソースと照合されます。ソースは、その名前に適用されるシグネチャが読み取る構文ごとに 1 回、ワークスペースのカタログがその構文に提供する parser を通じて解析されます。カタログが parser を提供しない構文の場合は、コンパイラ自身が持つ parser が使われます。ある構文で解析できないソースは、その構文を指定するどのシグネチャにも一致しません。ディレクトリはそのファイルを通じて照合されます。各シグネチャは、そのパターンが選択するディレクトリ内のファイルに対して名前順に試され、パターンを宣言しないシグネチャはどのファイルにも適用されません。シグネチャが一致したソースは、その importer が公開するすべての形式として認識されます。認識された形式がちょうど 1 つであれば、ソースはその形式として読み込まれます。どのシグネチャにも一致しないソースは拒否され、形式の指定を求めるとともに importer が公開する形式を挙げます。ただし、ディレクトリの場合は、そのファイルのいずれか 1 つを単独で指定するか、ファイルパターンを宣言する importer の形式を指定するよう求め、それらの形式だけを挙げます。複数の形式として認識されたソースは、それらを挙げて More than one importer recognises the source(複数の importer がソースを認識しています) の条件で拒否されます。したがって、複数の形式を公開する importer は、そのシグネチャが一致するすべてのソースが曖昧として拒否されるため、ソースを認識させたい importer は 1 つの形式を提供します。
エンティティが detect を記録している場合、それはプラグインの describe() が報告する内容とシグネチャごとに順序どおり等しくなければなりません。報告が異なるプラグインは、importer の読み込み時に importer.detect を挙げて拒否され、公開時も同様です。detect を記録しないエンティティは何も主張せず比較もされないため、プラグインの describe() が報告するシグネチャをそのまま読み込みます。その場合、その importer の形式には名前を指定することでのみ到達できます。
metadata: pluginType: importerspec: abiVersion: v1beta1 importer: capabilities: # recorded by `aggrega plugin gen-catalog` from describe() - import:langflow detect: - syntax: json match: - path: data.nodes is: arrayspec.signature
プラグインに添付された署名を指す、任意の説明用ポインタです。このブロックはドキュメントとしてのみ機能します。署名がどこにあり、どのように作成されたかをカタログの読者のために記録するもので、ブロック自体がプラグインを受け入れるわけではありません。実際に強制されるチェックは、pull 時に適用されるレジストリごとの信頼ポリシーです。署名は OCI referrer として取得され、レジストリの信頼済みアイデンティティまたは固定された鍵に対して検証され、検証済みの事実としてロックファイルに記録されます。署名を必須とするレジストリでは、必須の署名が欠落している、信頼されていない、または無効である場合に pull が停止します。
type— 署名方式です。サポートされている方式はsigstore-cosignです。ブロックが存在する場合は必須です。signatureRef— 添付された署名バンドルの OCI referrer 参照で、ドキュメントと検出のために使われます。署名をここで固定せず、pull 時に referrer の列挙によって検出する場合は省略します。publicKeyRef— 鍵付き署名の場合に、署名の作成に使われた公開鍵を指すポインタです。省略されている場合はキーレス(OIDC アイデンティティ)署名を示し、レジストリの信頼済みアイデンティティに対して検証されます。
spec.runtime
プラグインの読み込みと実行時にホストが適用する、任意の実行制約です。外向きのネットワークアクセスは記述するフィールドではありません。プラグインはビルド時にネットワークへアクセスすることはなく(これが事前コンパイルの境界です)、そのためここにはホスト許可リストのフィールドはありません。プラグインが必要とするリモートコンテンツは、Release のロックファイルに記録される、ホストが仲介しダイジェストで固定された外部入力チャネルを通じて届き、環境のネットワークアクセスを通じて届くことはありません。フェッチラッパーと固定の運用については開発者ガイドで説明しています。
| フィールド | 効果 |
|---|---|
maxMemoryPages | プラグインのリニアメモリの上限を Wasm ページ単位(1 ページあたり 64 KiB)で設定します。0 または未指定の場合はプラットフォームの既定の上限が適用されるため、読み込みが無制限になることはありません。より多くのメモリを必要とするアタッチメントでは、この値を引き上げます。 |
timeoutMs | 1 回の呼び出し中にプラグイン自身のコードが実行できる時間の上限をミリ秒単位で設定します。プラグインが呼び出すホスト関数内で費やされた時間は含みません。Linux では計測対象はプロセッサ時間であるため、負荷の高いマシンでプロセッサを待つ時間は含まれません。その他のシステムでは経過時間です。新しく読み込まれたプラグインへの最初の呼び出しには、プラグイン自身の起動時間も含まれます。0 または未指定の場合はプラットフォームの既定の上限が適用されるため、呼び出しがキャンセル不能になることはありません。より長く実行されるアタッチメントでは、この値を引き上げます。 |
hostFunctions | プラグインがインポートするホスト関数の名前です。機械的に導出される読み取り専用の値であり、記述しないでください。aggrega plugin sync は .wasm のインポートセクションからホスト関数を読み取ってこのフィールドに記録し、publish はバイナリと異なる記録を拒否します。値は公開されたバイナリを反映し、厳選された許可リストに照らして検証されます。ホストはまさにこの集合だけを登録し、各プラグインにそのバイナリが必要とする最小権限のホスト機能面を与えます。pull はこの値を再導出し、バイナリに照らして検証します。公開前に値を確認するには、aggrega inspect --plugin <file.wasm> を実行します。 |
configKV | Plugin 固有の設定で、ランタイムが起動時にプラグインへ渡す文字列から文字列へのキー/値ペアです。エントリは作成者が記述した順序を保持するため、出力されるレコードは実行ごとにバイト単位で同一になります。省略した場合は、ランタイムのデフォルトの空の設定が有効になります。 |
spec.exports
プラグインが提供するエクスポートを、それぞれ宣言された機能とともに、作成者の記述順を保持する順序付きリストとして記述します。エクスポートとは、ホストがディスパッチ先とする名前付きのエントリポイント 1 つです(例: render_node、lint_naming、step)。エクスポートごとの機能ブロックは、そのエクスポートが何を行うかを示し、aggrega plugin gen-catalog がプラグインの describe() による自己申告からこれを記録します。ホストは公開時とロード時に、その自己申告と照合します。省略した場合、作成者が記述したエクスポートはないことを宣言します。
| フィールド | 効果 |
|---|---|
name | エクスポートの ABI 名です。ホストがディスパッチ先とする名前です。各エントリで必須です。 |
operates | エクスポートが実行するパイプライン操作です。patch(既存のレンダリング済みドキュメントを変更)または emit(新しいドキュメントを追加)を指定します。ホストはこの値をプラグインの自己申告と照合します。これは検証される機能の宣言であり、ディスパッチの切り替えではありません。ステップが実行する操作は、ゲストが返す結果によって決まります。省略した場合、操作の宣言はありません。 |
scope | エクスポートが操作対象とするドキュメントのルートです。own(ノード自身のレンダリング済みドキュメント)または host(コンポーネントスコープの FeatureRecipe がアタッチされているコンポーネントのドキュメント)を指定します。ホストはステップの前に宣言されたスコープを読み取り、そのスコープをレンダリングするプロバイダーとの互換性を検証します。省略した場合、既定値は own です。 |
selector | エクスポートが何に作用するかを記述する、人が読むための自由形式の説明です(例: workloads carrying a pod template)。カタログの読者と inspect の出力向けのドキュメントであり、コンパイラはこれを解釈しません。 |
spec.commands
cli プラグインが追加するトップレベルの aggrega <command> コマンドを、プラグインの describe() による自己申告が宣言する順序を保持する順序付きリストとして記述します。機械が所有する読み取り専用のフィールドです。作成者は記述しないでください。 aggrega plugin sync がプラグインの describe() による自己申告からコマンドの一覧を読み取ってここに記録するため、CLI プラグインがインストールするコマンドは .wasm をロードせずにエンティティから読み取れます。cli 以外のプラグインはコマンドを追加せず、空のリストを記録します。ホストはまさにこのセットをインストールします。記録されたセットがプラグインの describe() による自己申告と異なる場合はロード時に停止し、公開時にはバイナリと同期していないセットを拒否して、作成者に再記録を指示します。プラグインを変更した後に記録を再同期するには、aggrega plugin sync を実行します。
各コマンドのエントリには次の項目があります。
| フィールド | 効果 |
|---|---|
name | ホストが登録するコマンド名です。オペレーターが実行する aggrega <name> のトークンであり、ホストが呼び出し時にプラグインへ渡す識別子でもあります。これにより、複数のコマンドを担う単一のプラグインは、どのコマンドが呼び出されたかに応じて処理を振り分けられます。各エントリで必須です。 |
description | コマンドの 1 行の短いヘルプテキストで、コマンド一覧とヘルプ出力に表示されます。ドキュメント専用であり、ホストはこれに基づいて動作しません。 |
flags | コマンドのフラグを宣言順に記述します。各エントリはコマンドにフラグを 1 つ登録し、aggrega help <command> がコアコマンドのフラグと同様に表示できるようにします。フラグのないコマンドでは空のままにします。 |
各 flags エントリはフラグを 1 つ宣言します。
| フィールド | 効果 |
|---|---|
name | フラグの長い名前です。オペレーターがコマンドラインで渡す --name のトークンです。各エントリで必須です。 |
shorthand | フラグの省略可能な短い別名です。長い名前の代わりにオペレーターが渡せる -x 形式で、ASCII の英字または数字 1 文字で指定します。省略した場合、そのフラグには短い別名がありません。 |
description | フラグの 1 行のヘルプテキストで、コマンドのヘルプ出力に表示されます。省略可能なドキュメントであり、ホストはこれを検証せず、これに基づいて動作もしません。 |
type | フラグの値の型(string、bool、int のいずれか)であり、ヘルプがそのフラグをどの種類として表示するかを決めます。省略した場合は文字列フラグとして表示されます。 |
default | オペレーターがフラグを渡さない場合の既定値で、文字列として記述します。bool または int のフラグでは、その型の値です。省略した場合、フラグは既定値を宣言しません。 |
CLI プラグインは describe() でコマンドとそのフラグを宣言します。ホストはまさにその内容を登録し、組み込みコマンドのフラグと同じ方法で、各コマンドのフラグを aggrega help <command> に表示します。
ホストはプラグインのコマンドを追加する際に、プラグインが宣言するすべてのフラグを検査します。宣言が不正なプラグインは追加されずにスキップされます。そのコマンドは 1 つも登録されず、プラグイン、コマンド、フラグ、および問題点を示す警告が出され、組み込みのものか他のプラグインのものかにかかわらず、他のすべてのコマンドは引き続き動作します。宣言が不正となるのは次の場合です。
- フラグに名前がない、またはコマンドが同じ名前を 2 回宣言している。
- 短い別名が ASCII の英字または数字 1 文字以外である、またはコマンドが 2 つのフラグに同じ短い別名を宣言している。
- 名前または短い別名が、すべての
aggregaコマンドが既に持つフラグ(--help、その-h、および--offlineや--configなどのグローバルフラグ)を再利用している。 - 型が
string、bool、int以外である。 - 既定値がフラグの型として解析できない(
boolに対するmaybe、intに対するthreeなど)。
shorthand が 1 文字であることと type の 3 つの値は、このエンティティのスキーマの一部でもあるため、それ以外の値を記録した Plugin エンティティはカタログのロード時に拒否されます。名前または短い別名がコマンドごとに 1 回だけ現れること、すべてのコマンドが持つフラグを再利用していないこと、および既定値がその型として解析できることは、ホストのみが検査します。この検査は、記述されたとおりにホストがヘルプ用のフラグを宣言できるかどうかを対象とします。プラグインは自身の引数を自分で解析するため、プラグインが宣言したフラグを実際に読み取るかどうかは検査されません。
metadata: pluginType: clispec: abiVersion: v1beta1 # commands is recorded by `aggrega plugin sync` from the plugin's describe() — do not author it. commands: - name: greet description: Print a friendly greeting flags: - name: name shorthand: n description: Who to greet type: string default: worldPlugin の検査
aggrega inspect <path-to-Plugin.yaml> は Plugin ファイルを表示します。表示されるのは、その識別情報とソケットタイプ、そのブロックが宣言するケイパビリティ、作成者の記述順によるエクスポートごとのケイパビリティ表、ランタイムの制約、そして --detail 指定時には署名ポインタとランタイム設定キーです。Plugin はファイルパスで指定するか、カタログに対する <pluginType>/<name> 座標で指定できます。../cli/aggrega-inspect.md を参照してください。
相互参照
- Wasm プラグイン開発者ガイド — 作成者のエンドツーエンドのワークフロー:
describe()、ケイパビリティの宣言、ランタイム制限、ライフサイクル、署名、バージョニング。 - Wasm プラグインコントラクト — プラグインが接続するソケットポイントと、その入出力の形状。
entities/featurerecipe.md— エンティティ URI でプラグインを参照する FeatureRecipe のpipeline:サーフェス。cli/aggrega-lint.md—Pluginの公開を管理する公開リンター、バージョン引き上げの基準、および不変性の強制。