バージョン 1.0.0-alpha.1最新
第 2.21 章
Plugin SDK
Plugin SDK(ソフトウェア開発キット)のインストール、そのコマンドラインツール、フルサービステンプレートのツアー、v2 マニフェストのフィールドごとの解説、およびプラグインにルールを遵守させる22のゲートについて説明します。
このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

2つ目のプラグインは、1つ目の3分の1の時間で完成しましたが、短縮できた時間のほとんどはSDK(ソフトウェア開発キット)のおかげでした。1つ目のときは、スコープチェック、設定ローダー、マイグレーションランナーを自作しましたが、レビュアーからすべて差し戻されました。2つ目のときは、スキャフォールドコマンドを1つ実行し、サンプルのセンチメントスキルを削除して、フライトダイナミクスチームが本当に必要としていた異常レビューレコードの開発に日々の時間を費やすことができました。
@adverant-nexus/plugin-sdkは単一のnpmパッケージです。このパッケージには、v2マニフェストスキーマとそれを読み取るバリデーター(definePlugin、defineSkill)、プラグインがスコープ、データベース、ディスパッチなどのためにインポートするランタイムモジュール、テストヘルパー、準拠ゲート、およびコマンドラインツールが含まれています。この章では、パッケージのインストール、ツール、テンプレート、マニフェスト、およびゲートについて説明します。実行中のコード内のランタイムモジュールについては、第2.22章「プラグインランタイム」で説明します。
インストール
このパッケージはパブリックなnpmレジストリからではなく、常にhttps://registry.adverant.ai/npm/にあるAdverantのレジストリから提供されるため、アカウントの「Pull tokens and install commands」ページから取得したプルトークンが必要です。リポジトリの.npmrcで、@adverant-nexusスコープをこのレジストリに向けてください。
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token>はアカウントページから取得したトークンです。パイプラインでは、シークレットからこれを渡し、決してコミットしないでください。テンプレートのDockerfileは、このトークンがないとビルドを拒否し、npm ciの実行後にビルドステージから.npmrcを削除するため、トークンがイメージに含まれることはありません。
次に、バージョンを厳密に固定します。
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0最初のインストール時にpackage-lock.jsonをコミットしてください。テンプレートのイメージビルドはnpm ciを実行し、npm installへのフォールバックを拒否します。ロックファイルが契約となります。SDK自体の最低要件はNode 18であり、テンプレートはNode 20をターゲットとしています。
コマンドラインツールはこのパッケージ内に同梱されているため、このドキュメント内のすべてのコマンドは、npx -pを使用してパッケージとそのバージョンを指定します。単体で実行すると、npx create-nexus-pluginはパブリックレジストリで検索されますが、その名前はこのパッケージのものではありません。
コマンドラインツール
| ツール | 行うこと |
|---|---|
create-nexus-plugin |
プラグインのスキャフォールド、マニフェストの検証、v1マニフェストからv2への移行、およびフロントエンド開発者向けのコンシューマーガイドのレンダリングを行います |
nexus-tenancy |
マニフェストからスキーマのテナントSQL(ロール、権限付与、行レベルセキュリティのテンプレート、およびグラフテーブル)をレンダリングします |
nexus-migrate |
マイグレーションを適用します。ロールを一度プロビジョニングし、番号付きのファイルそれぞれをマイグレーターロールとして実行します |
nexus-gates |
すべての準拠ゲート、および各ゲート自身のセルフテストを実行します |
create-nexus-pluginはネットワーク呼び出しを行わず、リモートコードも読み込みません。プラットフォームのオンボーディングが実行するものと同じインプロセスバリデーターを実行するため、「自分のマシンでは検証を通過した」状態と「プラットフォームが承認した」状態の間にズレが生じることはありません。
| サブコマンド | フラグ | 行うこと | 終了コード |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
新しいプラグインディレクトリを書き込みます。--printはマニフェストのみを出力します |
0 書き込み完了 · 1 上書き拒否 · 2 使用方法の誤り |
validate <file> |
nexus.manifest.json、またはそれをエクスポートする.tsもしくは.jsモジュールを検証します |
0 有効 · 1 無効または読み取り不可 · 2 使用方法の誤り | |
migrate <file> |
--write |
v1マニフェストをv2にアップグレードして出力するか、その場で上書き保存します | 0 · 1 · 2(上記と同様) |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
マニフェストと説明文からコンシューマーガイドをレンダリングします。--checkはコミット済みのコピーと比較し、書き込みは行いません |
0 · 1 ズレまたはLint違反 · 2 使用方法の誤り |
help |
使用方法を出力します | 0 |
スキャフォールディングと3つのティア
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tierのデフォルトはfull-serviceです。スキャフォールダーは既存のディレクトリへの書き込みを拒否し、書き出されるマニフェストはすでに検証を通過した状態であり、無効なマニフェストが出力されることはありません。
プラグインが持つ機能に応じてティアを選択してください。
| ティア | 持つ機能 | 必須の宣言 |
|---|---|---|
skills-only |
マニフェストスキルのみ(他になし) | 少なくとも1つのエントリを持つskills[] |
ui-only |
シェル内のフロントエンドサーフェス | frontend |
full-service |
バックエンドとフロントエンド(通常は独自のスキーマを伴う) | backendおよびfrontend。また、バックエンドを持つためruntime.healthCheck |
迷った場合は、full-serviceをスキャフォールドして不要なものを削除してください。逆の方法をとると、テンプレートが提供してくれたはずの部分を自分で書くことになります。
フルサービステンプレートのツアー
このテンプレートはリファレンスプラグインであり、以降のすべての章が前提とする厳格なパターンに従って構築されています。サンプルのロジックではなく、その構造を複製してください。
| パス | その内容 |
|---|---|
nexus.manifest.json |
v2マニフェスト:再記述された3つの原則、ルートテーブルとその権限レジスター |
src/config.ts |
設定ローダー。1つの仕様を1度だけ読み取り、プロセスが起動を拒否する前にすべての問題を収集します |
src/scope.ts |
SDKの厳格なトークン検証機能と2つの方式(個人のベアラートークンとプラットフォームのサービス呼び出し)を使用して、リクエストをスコープに変換する唯一のファイル |
src/db.ts |
すべてのステートメントはtenantFence()を構成し、withScopedTxの内部で実行されます |
src/uno.ts |
唯一のディスパッチファイル:1つのURL、1つのクライアント、閉じられた許可リスト |
src/routes/*.ts |
health(匿名、完全一致パス)、/apiルート(スコープ付き)、および/internalコールバック(サービスガード付き) |
src/skills/sentiment.ts |
決定論的なhost_callbackスキル。語彙集を独自のロジックに置き換えてください |
src/server.ts |
コンポジションルート:拒否台帳を一度インストールし、データベースを(上限付きで)待機し、リッスンを開始する前に分離チェックと台帳チェックを実行します |
migrations/000_tenancy.sql |
スキャフォールド時にnexus-tenancy renderによってレンダリングされます:ロール、スキーマ、行レベルセキュリティのテンプレート |
migrations/001_init.sql |
テナントを先頭とする複合キーと、テナントを含む複合外部キーを持つ2つのテーブル |
migrations/002_refusal_ledger.sql |
拒否台帳が書き込みを行うテーブル |
scripts/ci/required-env |
起動に必須の環境変数名をJSONとして出力します |
scripts/ci/shadow-migrate-*.sh |
nexus-migrateを介したパイプラインのマイグレーションドライラン |
gates/ |
ゲートの免除ディレクトリ:空の状態(新しいプラグインにとって正しい状態) |
test/ |
スコープ、ルート、データベース、ディスパッチ、および起動のテスト(各テストが注入するスコープのテストダブルを含む) |
Dockerfile |
内部にマイグレーションを含む非rootイメージ(ユーザーID 10001) |
これらのファイルのうち、いくつかは詳しく見ておく価値があります。
src/config.tsは2つのルールに従います。例外をスローする前にすべての問題を収集するため、5回の再起動で不足している変数を1つずつ示すのではなく、1回の再起動で5つすべてを示します。また、誤った値がサイレントな誤答を生まない場合にのみ、デフォルト値を設定します。たとえば、ポートの誤りはバインドの失敗として明確に現れるため、PORTはデフォルトで8080にできますが、DATABASE_URLとUNO_DISPATCH_URLは必須であり、クラスター内のアドレスでなければなりません。パブリックなアドレスは起動時に拒否されます。
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
テンプレート自体のテストがそのファイルを実行し、その出力を設定仕様が必須としてマークしている名前と比較するため、リストを更新せずに必須変数を追加するとnpm testが失敗します。
src/server.tsはデータベースが応答するまでリッスンを開始せず、待機時間を最大120秒に制限し、失敗したすべての試行とその原因をログに記録します。その後、アプリロールがテナントを再バインドできず、すべてのテーブルに行レベルセキュリティが強制されていること、各Podのプールがロールの接続制限に収まっていること、および拒否台帳のテーブルが行を受け入れられることを順番に証明します。これら3つのいずれかから拒否された場合は、その全体が出力され、プロセスは終了コード2で終了します。
v2 マニフェストのフィールドごとの解説
マニフェストは、プラットフォームとの間で機械判読可能なプラグインの契約です。作成時、プラットフォームへのオンボーディング時、およびその後も継続的に検証されます。スキーマはすべてのレベルでadditionalProperties: falseとなっています。プラグインにセクションがある場合はそれに対応するプロパティが存在し、宣言されていないキーは拒否されます。修正方法は、常に適切なオプションプロパティを使用することです。
必須のコア項目
| フィールド | ルール |
|---|---|
manifestVersion |
厳密に"2"。v1ドキュメントは移行されるものであり、そのまま再検証されることはありません |
name |
最大64文字の^[a-z0-9]+([-.][a-z0-9]+)*$。登録、ディスパッチの名前空間、およびテナントスコープの行で使用されるプラグインIDです。スキルを宣言するプラグインには、ドットを含まず先頭が数字ではない名前も必要です |
displayName |
1〜120文字 |
version |
セマンティックバージョン(独自のリリーストレイン) |
description, author, license |
それぞれ1文字以上 |
tier |
skills-only、ui-only、またはfull-service |
trust |
core、verified、community、またはuntrusted |
runtime |
必須:executionMode、isolationLevel(1〜4)、entrypoint。オプション:nodeVersion、healthCheck、readinessCheck、livenessCheck(それぞれ/で始まるパス)。モードはレベルから導出されます:1 external_https、2 mcp_container、3 hardened_docker、4 firecracker |
architecture |
再記述されたプラットフォームの3つの原則であるcompute、ai、およびdeploy。バリデーターは文言を固定します |
独自のインストール環境向けに構築するプラグインの場合、3つの文は次のようになります。aiの文は人工知能(AI)に関するもので、プラグインがモデルの認証情報を保持しないことを明記する場所です。
"architecture": {
"compute": "All compute runs via UNO dispatch (nexus-orchestrator /api/v1/dispatch + nexus-workflows). No direct engine, queue or model-provider calls from plugin code.",
"ai": "All AI goes through the AI Provider Router, which alone owns the credential and the final provider/model decision. This plugin holds no model credentials.",
"deploy": "Deploy is through the installation's release channels only."
}ルートテーブル:apiとrights
apiにはversionとbasePathが必要であり、オプションでwebsocket(path、auth)とendpoints[]を指定できます。ルートテーブルはスキーマ内で最も強力な概念です。ゲートが、コードが実際に登録するルートとこれを双方向で差分比較するため、マニフェストは単なるドキュメントではなく検証可能な契約となります。
各エンドポイントにはmethod(GET、POST、PUT、PATCH、またはDELETE)とpathが必要です。その他の項目は以下のとおりです。
| フィールド | 記載内容 |
|---|---|
auth |
5つのクラスのいずれか:scope(スコープガードの背後にある個人のルート)、service-keyおよびinternal(サーバー間通信用で、ブラウザーからは決して到達できない)、public(常にallowAnonymousを伴う完全一致パスのみ)、およびdevice(デバイスガードの背後にある、独自の認証情報を持つマシン) |
right |
スコープガードが提供するすべてのルートで必須であり、それ以外のルートでは拒否されます:rightsレジスター内の権限の名前 |
needsUnit |
呼び出し元のユニットを解決できない場合、ルートは拒否します |
allowAnonymous |
完全一致の許可リストのみ。プレフィックスルールを使用すると、/health-of-tenant-42が公開されてしまう原因になります |
group, serves, screens |
releaseブロックの下:ルートが提供する機能グループ、そのグループのライセンス機能がロックされている場合に応答する内容(data、teaser、sighting、またはask)、およびルートが提供する画面 |
query |
required(各名前とサンプルの値)およびallowed:ルートが読み取るクエリパラメーター |
body |
example:書き込みルートのサンプルボディ(自身のバリデーターが受け入れるもの)。GETには決して使用しません |
rightsは、それらのルートが指定するレジスターです。各権限にはroles(上限)があり、オプションでsummary、never(他のどのような権限を持っていようと、決してこれを行使できないロール)、barred(neverロールを拒否するための製品独自の文言)、seat(有効なシートも必要)、self(自身のセッションに対する権限として、検証済みのすべての人が保持する)、grants(保持者がシートを付与する。これを指定できる権限は最大1つ)、licence(組織のライセンスに含まれている必要があるライセンス機能)、installation(インストール環境自身の管理者のみが保持する)、およびplatform(Adverantのプラットフォーム管理者のみが保持し、ロールは指定しない)があります。権限の名前には少なくとも1つのドットが含まれます(project.read、money.pay)。
"api": {
"version": "1",
"basePath": "/",
"endpoints": [
{ "method": "GET", "path": "/health", "summary": "Liveness", "auth": "public", "allowAnonymous": true },
{ "method": "GET", "path": "/api/projects", "summary": "List the caller's projects", "auth": "scope", "right": "project.read" },
{ "method": "POST", "path": "/api/projects", "summary": "Create a project", "auth": "scope", "right": "project.create" },
{ "method": "POST", "path": "/internal/skills/sentiment_score", "summary": "host_callback receiver", "auth": "service-key" }
]
},
"rights": {
"project.read": { "summary": "Read the organisation's projects.", "roles": ["owner", "admin", "member", "viewer"] },
"project.create": { "summary": "Open a project.", "roles": ["owner", "admin", "member"] }
}definePluginは、権限のないスコープルート(ENDPOINT_RIGHT_MISSING)、レジスターに存在しない権限(ENDPOINT_RIGHT_NOT_REGISTERED)、およびどのガードも提供しないルート上の権限(ENDPOINT_RIGHT_UNGUARDED)を拒否します。また、自己矛盾しているレジスターや、1つのルートに対する2通りの表記(:idと:recordId)もDUPLICATE_ENDPOINTとして拒否します。
データ:databases、schema、およびdb
schemaは、プラグインが所有する唯一のPostgresスキーマです。public、plugins、auth、およびnexusは禁止されており、databases[]もPostgresスキーマを指定する場合は、両者が一致している必要があります。
databases[]はエンジンごとに各ストアを宣言します:postgresql(schema、tables、migrations、および記録された権限付与のもとで別の組織が読み取れるテーブルであるgranted)、neo4j(schemas)、qdrant(collections)、またはredis(purpose)。
dbは、プラグインが開くすべての接続に対するセッション制限を保持します。レビュアーとデプロイメントの両方が読み取れるように、コード内ではなくここで宣言されます。
| フィールド | 制限対象 |
|---|---|
maxConnections |
レプリカあたりのプール |
pods |
同時にプールを保持する最大Pod数(レプリカ数+ローリングアップデートのサージ)。各ロールの接続制限はmaxConnections × podsとしてレンダリングされます。省略するとdefinePluginがDB_PODS_UNDECLAREDと警告します |
statementTimeoutMs |
1つのステートメント |
idleInTransactionTimeoutMs |
何も実行していない開いたままのトランザクション |
workMemKB |
1つのソートノードまたはハッシュノード(クエリ単位ではなくノード単位) |
piiMask[] |
個人データを保持するtable.columnエントリ(管理されたSQLコンソールおよびログ内でマスクされます) |
スキルとツール:skills、mcpTools、entitlements
skills[]はマニフェストスキルを保持します。それらのフィールドとティアについては、第2.20章「スキル」で説明します。mcpTools[]はプラグインが公開するMCP(Model Context Protocol)ツールを保持し、それぞれがname、description、およびトップレベルのoneOf、allOf、またはanyOfを持たないinputSchemaで構成されます。
entitlementsはfeatureIdPatternを必須とし、alwaysOn[]、source、およびstoreを受け入れます。このパターンは機能IDが存在する名前空間を指定するもので、慣例としてプラグインのnameに、サーフェスごとにコードが埋める1つのセグメントを加えたものになります。alwaysOn[]は、エンタイトルメントの判定が得られない場合でも応答しなければならない、短く厳密なリストです(ヘルス、レディネス、サインイン、および管理者がエンタイトルメントを修復するために必要な設定)。
変更管理:changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}承認は異なる個人の数でカウントされ、変更を提案した本人は決してその中に含まれません。この両方の条件がなければ、「2回の承認」が1人の2回クリックになってしまいます。enabled: trueにはclassesが必要であり、指定されたすべてのクラスにそれぞれのカウントが必要です。省略したクラスは管理対象外となりますが、これはスキーマが明記することを求める正当な選択肢の1つです。
アイデンティティ:domains、branding、routing
domains[](それぞれprimaryとaliases[]。domainは単一ドメイン形式)は、プラグインが応答する場所をリストします。brandingはappNameを必須とし、tagline、logo、favicon、primaryColor、accentColor、oauthClientRef、passkeyRpId、およびgaIdを受け入れます。branding内のすべての項目は公開されます。誰かが認証情報を持つ前にサインインページがこれを読み取るため、シークレットや内部アドレスを決して保持してはなりません。routing(type、gateway、virtualService)は、独自のルーティングを記述するプラグイン用です。
サイジングとその他の項目
resourcesはcpuMillicores(10〜64,000)とmemoryMB(16〜262,144)を必須とし、diskGB、timeoutMs、port、およびwsPortを受け入れます。backendは、port、healthPath、apiPrefix、framework、およびバックエンドが名前でインポートするSDKクライアントであるplatformClients[]を保持します。このリストは閉じられており、ゲートがインポート内容と照合してチェックします。スキーマは14個の名前を許可しています:access、bindings、documents、files、governance、graph、jobs、keys、memory、platform、runs、signin、およびunoに加え、プランのエンタイトルメント拒否に応答するクライアント用の1つ(内部名を維持)です。機能エンタイトルメントクライアントであるruntime/entitlementsはこれらに含まれず、リストに載ることも決してありません。なぜなら、entitlementsブロックがすでにそれを宣言しており、entitlementsブロックなしでこれをインポートするバックエンドは同じゲートで失敗するためです。frontendはbasePath、mountPath、およびframeworkを保持します。nexusはminVersion、maxVersion、capabilities[]、およびpermissions[]を保持します。
残りのブロックは、それぞれ1つの役割のために存在します。
| ブロック | 用途 |
|---|---|
settings |
共有フレームワーク上の設定:それぞれが指定するレベルで設定されるgroupsとkeys |
people |
sweep(service、port):アイデンティティサービスから同期される組織のメンバー(誰かが離脱した際にはシートがオフになります) |
ontology |
entityTypesとrelationshipTypes:独自のスキーマ内に保持される型付きグラフ |
release |
groupsとframe:ルートがステージングされる機能グループ(最初にカナリアとしてリリースされます) |
cells[] |
複数のデプロイ可能単位から成るプラグイン:それぞれにname、kind、entrypoint、port、wsPort |
pricing |
カタログ掲載用のmodel、currency、tiers[] |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
公開者とコードの保管場所 |
metrics, atlas |
独自のメトリクス名とアーキテクチャドキュメント生成のための、意図的に開かれた2つのオブジェクト |
スキーマでは表現できないこと
JSON Schemaは構造を決定し、definePluginはスキーマでは表現できないルールを追加します。スキルのclassificationは信頼の上限を超えることはできません。coreおよびverifiedプラグインのみが、tool_usingおよびllm_onlyスキルを宣言できます。宣言されるすべてのパスは相対パスかつ同一オリジンでなければならず、スキーム、//、およびバックスラッシュを含んではなりません。なぜなら、URLパーサーは\を/に変換し、/\evil.example/xはクロスオリジンで解決されるためです。レジストリ同期がスキルに適用するすべてのルールは、同期処理自身のコードを使用してここで最初に適用されるため、validateと同期処理はルール違反を同じ方法で指摘します。
検証と v1 からの移行
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin validate nexus.manifest.json✔ anomaly-review@0.3.0 · tier=full-service · trust=community · skills=1 · mcpTools=0
失敗すると正確なパスが出力され、同期ルールの場合はコードが最初に出力されます。これをコミットフックにしてください。
v1マニフェストは機械的にアップグレードされます。migrateは3つの原則の文を追加し、domainをdomains[]に移動し、存在しなかったエントリポイントを勝手に作ることを拒否します。何かを出力または書き込む前に結果を検証するため、マイグレーションによってツールからリポジトリへ失敗が持ち込まれることはありません。
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeコミットする前に差分を確認してください。追加される原則の文はバリデーターが固定する文言です。独自のインストール環境の場合は、deployを前述の文に設定してください。
テナンシーのレンダリングとロールのプロビジョニング
ロールの権限付与や行レベルセキュリティのテンプレートを手作業で記述することは決してありません。nexus-tenancy renderがマニフェストのschemaとdbからそれらを書き出します。
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlレンダリングされたファイルは、スキーマ用に5つのロールを作成し、それぞれが保持してはならないものを設定します。オーナーになることしかできないマイグレーター、ログインできないオーナー、リクエストパス用のアプリロール、集計のみを参照できるレポートロール、および追記のみが可能な台帳ロールです。どのロールもBYPASSRLSを保持しません。テナントをバインドする唯一の方法は1つのデータベース関数であり、set_configはオーナー以外のすべてのロールから剥奪されます。
適用済みのテナントファイルは決して編集されません。変更は独自の0番ファイルを持つリビジョンとして行われ、組織間の権限付与のための読み取りシートはそのようにしてリビジョン2として提供されます。--graphは、ontologyが宣言する型付きグラフの2つのテーブルを、次の番号付きマイグレーションとしてレンダリングします。
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --graph --out migrations/001_graph.sqlテナントファイルは、ランナーが接続する際に使用するロールそのものを作成するため、データベースオーナーによってnexus-migrate provisionで適用されます。
DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir><database-owner-url>はデータベースオーナー用の接続文字列であり、<dir>はプライベートディレクトリです。プロビジョニング処理は、ベースのテナントファイルとすべてのリビジョンを順番に適用し、migrator.urlとapp.url(およびリビジョン2が存在する場合はseat.url)をモード0600で<dir>に書き込み、機密情報は一切出力しません。また、実行するたびにdb.maxConnections × db.podsから各ロールの接続制限を設定します。再実行時は、要求しない限り既存のパスワードが維持されます。--passwords <dir>はファイルからパスワードを設定し、--rotate <roles>は指定されたロールに新しいパスワードを付与します。これらのファイルをデプロイメントのシークレットに変換してください。
その後、適用処理はプロビジョニング処理が書き出したマイグレーターの接続文字列を使用して接続します。
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json001以降のファイルをマイグレーターとして実行します(すべてのファイルはSET ROLE <schema>_ownerの下にあり、1ファイルにつき1トランザクション)。各ファイルのチェックサムを含む台帳<schema>.schema_migrationsを保持し、バイト列が変更された適用済みファイルは名前によって拒否され(CHECKSUM_DRIFT)、再実行もスキップも決して行われません。保留中のすべてのファイルは、最初のファイルが実行される前に実際のPostgres文法でパースされるため、拒否された場合でもデータベースは手つかずのまま残ります。ファイルが持つことのできる唯一のヘッダーは、オプションのロックタイムアウトとステートメントタイムアウトを伴う-- nexus-migration: transaction=file|per-statementです。per-statementはCREATE INDEX CONCURRENTLY用です。
ゲート
nexus-gatesは22個のゲートを実行します。各ゲートは1つのクラスの欠陥をコード化して二度と出荷されないようにしており、それを引き起こすように作られたフィクスチャで失敗することを証明するセルフテストを備えています。プッシュする前にこれらを実行してください。
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| ゲート | 検出対象 |
|---|---|
scope-adherence |
スコープガードのない/apiルート。宣言された完全一致パスではない匿名パス。デバイスガードのないデバイスルート、または個人のガードが併設されているデバイスルート |
one-fence |
定められた1か所以外の場所で定義されたテナント述語(手書きのシートや権限付与のフェンスを含む) |
sql-fence |
FROM、JOIN、USING、またはUPDATEのターゲットのいずれかにおいて、フェンスなしでスコープ付きテーブルを読み取る、または更新するステートメント |
migrations-are-scoped |
軸、テナントを先頭とする複合キー、テナントを含む外部キー、またはデモ用カラムが欠落しているテーブル |
migrations-commit-what-they-open |
BEGINの数がCOMMITおよびROLLBACKの数と一致しないマイグレーション |
no-direct-compute |
モデルプロバイダー、エンジン、キュー、またはワークフローホストへの直接呼び出し。ディスパッチURLの2つ目の読み取り元 |
no-credentials |
リポジトリ内または環境内で読み取り可能なモデルプロバイダーの認証情報 |
crud-adherence |
権限チェックがレジスター内の何も指定していない変更系ルート |
blocked-backends |
提供されておらず、名前でブロックされておらず、原則によって拒否されておらず、他の場所でも所有されていないルート |
every-test-runs |
テストスクリプトのglobが決して到達しないテスト |
tiles-are-invariant |
テナントの値を読み取るか、認証をスキップするテナント不変のキャッシュされたシーム |
api-contract |
マニフェストが宣言していない登録済みルート、またはコードが決して登録しない宣言済みルート |
rls-present |
強制された行レベルセキュリティがないテーブル。固定されたsearch_pathがないSECURITY DEFINER関数 |
no-set-config |
テナント設定を自らバインドするプラグインコード |
db-role-honest |
オーナーまたはマイグレーターとして接続する、あるいはSUPERUSERまたはBYPASSRLSを要求するリクエストパス |
platform-clients |
インポートされているがbackend.platformClientsにリストされていない、またはリストされているが決してインポートされないSDKクライアント |
rights-register |
宣言された権限がないスコープルート。レジスターを迂回する権限チェック |
refusal-ledger |
台帳がインストールされていない宣言済みの拒否テーブル、または台帳を迂回して送信される拒否ボディ |
grants-declared |
マニフェストが宣言していない権限付与済みテーブル。手作業で付与された読み取りシートの特権 |
people-declared |
スイープルート、ガード、およびテーブルを持たないpeopleブロック |
functions-closure |
提供されるルートと宣言されたルートが一致しないAzure Functionsプラグイン |
declared-input |
ルートの宣言されたqueryと一致しないハンドラーのクエリパラメーターリスト |
gates/ディレクトリは、ゲートが読み取る可能性のある5つの免除ファイル(demo-exempt.json、non-crud.json、blocked-backends.json、tenant-resolving.json、およびinvariant-seams.json)を保持し、1つのエントリにつき1つの理由を記載します。空白の理由はエントリなしとみなされ、すでに存在しないものを指定しているエントリはゲートを失敗させます。独自のゲートモジュールをそこに配置することも可能で、nexus-gatesは組み込みのゲートと並べてそれらを読み込みます。
テンプレートのパイプライン
テンプレートには手書きのワークフローは同梱されていません。そのパイプライン設定は、Dockerfile、唯一のビルド引数(レジストリトークン)、マイグレーションのドライランと起動プローブ、およびマージキューが実行するゲートを指定します。この順序は、失敗してほしい順序になっています。
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest(すなわちcreate-nexus-plugin validate nexus.manifest.json)npm run gates(すなわちnexus-gates --self-test)node scripts/ci/required-env
イメージ周辺では、さらに2つのチェックが実行されます。マイグレーションのドライランは、イメージがリリース可能になる前に、本番環境が使用するのと同じランナーを用いて、使い捨てのPostgresにすべてのファイルを適用します。まずスーパーユーザーとしてnexus-migrate provisionを1回適用し、次にマイグレーターとして番号付きのファイルをそれぞれ適用します。ブートプローブは、ビルドされたイメージをそれ自体のエントリーポイントとrequired-envが出力するすべての変数を用いて起動し、接続を受け入れるものの決して応答しない代用先へと向けます。サーバーは制限された時間枠内でデータベースを待機し、その待機が合格のシグナルとなります。起動を拒否する設定ローダーは、本番環境ではなくその場でビルドを失敗させます。
コスト
SDKはあなたから意思決定を奪いますが、その中には、あなたなら別の選択をしていたであろうものも含まれます。マニフェストは未知のキーを拒否し、ルートテーブルはコードと完全に一致していなければならず、データベースのロールはあなたが設計するものではなく、ゲートは読み取り時の権限不足を理由にビルドを失敗させます。最初のプラグインでは、登録したものの宣言し忘れていたルートをめぐって、api-contractと格闘するのに丸一日を費やしました。正しかったのは向こうであり、そのルートは無防備でした。最初のプラグインは遅く感じるものと想定してください。そして2つ目のプラグインは、その3分の1の時間で済むものと想定してください。

