Версія 1.0.0-alpha.1найновіша
Розділ 2.21
Plugin SDK
Встановлення Plugin SDK (набору засобів розробки), його інструменти командного рядка, огляд шаблону повноцінного сервісу, детальний розбір усіх полів маніфесту v2, а також двадцять два контрольні рубежі, які перевіряють плагін на відповідність правилам.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

На створення мого другого плагіна пішла третина часу, витраченого на перший, і майже всю цю економію забезпечив SDK (набір засобів розробки ПЗ). Першого разу я написав перевірку області дії (scope), завантажувач конфігурації та виконавець міграцій, і рецензент повернув кожен із них на доопрацювання. Другого разу я виконав одну команду генерації каркаса (scaffold), видалив демонстраційну навичку аналізу тональності й присвятив свій час записам перевірки аномалій, які насправді були потрібні нашій команді динаміки польоту.
@adverant-nexus/plugin-sdk — це єдиний пакет npm. Він містить схему маніфесту версії v2 та валідатори, які її читають (definePlugin, defineSkill), модулі середовища виконання, які ваш плагін імпортує для роботи з областю дії, базою даних, диспетчеризацією та іншим, допоміжні засоби для тестування, контрольні гейти відповідності (adherence gates) та інструменти командного рядка. У цьому розділі описано його встановлення, інструменти, шаблон, маніфест і гейти. Розділ 2.22, «Середовище виконання плагіна», присвячено модулям середовища виконання у вашому робочому коді.
Встановлення
Пакет надходить із реєстру Adverant за адресою https://registry.adverant.ai/npm/, і ніколи — з публічного реєстру npm, а для завантаження вам знадобиться токен зі сторінки «Pull tokens and install commands» вашого облікового запису. Спрямуйте область @adverant-nexus на цей реєстр у файлі .npmrc вашого репозиторію:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> — це токен зі сторінки вашого облікового запису. У конвеєрі (pipeline) передавайте його зі сховища секретів і ніколи не додавайте в коміти; Dockerfile шаблону відмовляється збирати образ без нього й видаляє .npmrc з етапу збирання після виконання npm ci, тож токен ніколи не потрапляє в готовий образ.
Потім чітко зафіксуйте версію:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Зафіксуйте в коміті файл package-lock.json під час першого встановлення. Під час збирання образа з шаблону виконується npm ci без можливості відкату до npm install: файл блокування (lockfile) є контрактом. Мінімальна вимога самого SDK — Node 18; шаблон орієнтований на Node 20.
Інструменти командного рядка постачаються всередині пакета, тому кожна команда в цій документації вказує назву пакета та його версію за допомогою npx -p. Сам по собі npx create-nexus-plugin шукається в публічному реєстрі, і ця назва не відповідає даному пакету.
Інструменти командного рядка
| Інструмент | Що він робить |
|---|---|
create-nexus-plugin |
Генерує каркас плагіна, валідує маніфест, мігрує маніфест із версії v1 на v2 та формує посібник користувача для вашого фронтенд-розробника |
nexus-tenancy |
Формує з маніфесту SQL-код багатоорендності (tenancy) для вашої схеми: ролі, привілеї (grants), шаблон безпеки на рівні рядків (RLS) і таблиці графа |
nexus-migrate |
Застосовує ваші міграції: одноразово створює ролі, а потім виконує кожен пронумерований файл від імені ролі мігратора |
nexus-gates |
Запускає кожен гейт відповідності та власний самотест кожного гейта |
create-nexus-plugin не здійснює мережевих викликів і не завантажує віддалений код. Він запускає ті самі внутрішньопроцесні валідатори, що й процедура підключення (onboarding) до платформи, тож немає жодних розбіжностей між «валідація пройшла на моїй машині» та «платформа прийняла це».
| Команда | Прапорці | Що він робить | Коди виходу |
|---|---|---|---|
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 розбіжність або помилка лінтера · 2 неправильне використання |
help |
Виводить довідку щодо використання | 0 |
Генерація каркаса та три рівні
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-serviceЗа замовчуванням --tier має значення full-service. Генератор каркаса відмовляється записувати дані в каталог, який уже існує, а створений ним маніфест одразу проходить валідацію — інструмент ніколи не генерує невалідний маніфест.
Обирайте рівень (tier) залежно від того, що містить ваш плагін.
| Рівень | Містить | Має оголошувати |
|---|---|---|
skills-only |
Лише навички маніфесту і нічого більше | skills[], щонайменше з одним записом |
ui-only |
Фронтенд-інтерфейс усередині оболонки | frontend |
full-service |
Бекенд і фронтенд, зазвичай із власною схемою БД | backend та frontend; а оскільки є бекенд — ще й runtime.healthCheck |
Якщо ви не впевнені, згенеруйте каркас full-service і видаліть те, що вам не потрібно. Піти протилежним шляхом означає вручну писати ті частини, які міг би надати шаблон.
Огляд шаблону повноцінного сервісу
Шаблон — це еталонний плагін, побудований за суворим зразком, на який спираються всі наступні розділи. Клонуйте його структуру, а не демонстраційну логіку.
| Шлях | Що це таке |
|---|---|
nexus.manifest.json |
Маніфест v2: підтвердження трьох законів, таблиця маршрутів та її реєстр прав |
src/config.ts |
Завантажувач конфігурації. Єдина специфікація, читається один раз; усі проблеми збираються до того, як процес відмовиться запускатися |
src/scope.ts |
Єдиний файл, що перетворює запит на область дії (scope) за допомогою суворого верифікатора токенів SDK і двох режимів: bearer-токена користувача та сервісного виклику платформи |
src/db.ts |
Кожен вираз формує tenantFence() і виконується всередині withScopedTx |
src/uno.ts |
Єдиний файл диспетчеризації: один URL, один клієнт, закритий список дозволеного (allow-list) |
src/routes/*.ts |
health (анонімний, точний шлях), маршрути /api (в межах області дії) та зворотний виклик /internal (захищений на рівні сервісу) |
src/skills/sentiment.ts |
Детермінована навичка host_callback; замініть словник власною логікою |
src/server.ts |
Корінь композиції (composition root): одноразово встановлює журнал відмов, очікує на базу даних (обмежений час), а потім виконує перевірки ізоляції та журналу перед початком прослуховування портів |
migrations/000_tenancy.sql |
Згенеровано інструментом nexus-tenancy render під час створення каркаса: ролі, схема, шаблон безпеки на рівні рядків |
migrations/001_init.sql |
Дві таблиці зі складеним ключем, де першим іде ідентифікатор орендаря (tenant), та складеним зовнішнім ключем, що містить ідентифікатор орендаря |
migrations/002_refusal_ledger.sql |
Таблиця, у яку здійснює запис журнал відмов |
scripts/ci/required-env |
Виводить у форматі JSON імена змінних середовища, необхідних для запуску |
scripts/ci/shadow-migrate-*.sh |
Пробний прогін міграції в конвеєрі за допомогою nexus-migrate |
gates/ |
Каталог винятків для гейтів: порожній, що є правильним станом для нового плагіна |
test/ |
Тести для області дії, маршрутів, бази даних, диспетчеризації та запуску, з тестовими дублерами (doubles) області дії, які впроваджує кожен тест |
Dockerfile |
Образ без прав root (ID користувача 10001) із міграціями всередині |
Кілька з цих файлів варті детальнішого розгляду.
src/config.ts дотримується двох правил. Він збирає всі проблеми, перш ніж викинути виняток, тому один перезапуск покаже всі п’ять відсутніх змінних замість п’яти перезапусків, кожен із яких вказуватиме лише на одну. Крім того, він підставляє значення за замовчуванням лише тоді, коли неправильне значення не може призвести до непомітної хибної відповіді: 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 секундами, записуючи в лог кожну невдалу спробу та її причину. Потім він послідовно перевіряє, що роль застосунку не може переприв’язати орендаря і до кожної таблиці примусово застосовано безпеку на рівні рядків, що пул кожного пода вкладається в ліміт з’єднань ролі, і що таблиця журналу відмов може прийняти рядок. Відмова на будь-якому з цих трьох етапів виводиться повністю, а процес завершується з кодом 2.
Маніфест v2: поле за полем
Маніфест — це машиночитаний контракт плагіна з платформою. Він проходить валідацію під час написання, під час підключення до платформи та безперервно після цього. Схема має параметр additionalProperties: false на кожному рівні: якщо у вашому плагіні передбачено певний розділ, для нього існує відповідна властивість, а неоголошений ключ відхиляється. Рішення завжди полягає у використанні правильної необов’язкової властивості.
Обов’язкове ядро
| Поле | Правило |
|---|---|
manifestVersion |
Точне значення "2". Документ версії v1 підлягає міграції і ніколи не проходить повторну валідацію на місці |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, щонайбільше 64 символи. Ідентифікатор плагіна, що використовується під час реєстрації, формування простору імен диспетчеризації та в рядках, обмежених областю дії орендаря. Плагін, який оголошує навички, також потребує назви без крапок і без цифри на початку |
displayName |
Від 1 до 120 символів |
version |
Семантичне версіонування; ваш власний цикл випусків |
description, author, license |
Щонайменше по одному символу в кожному |
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 |
compute, ai та deploy — підтвердження трьох законів платформи. Валідатор вимагає точного формулювання |
Для плагіна, який ви створюєте для власної інсталяції, ці три речення мають такий вигляд. Речення 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[]. Таблиця маршрутів — це найпотужніша ідея в схемі: контрольний гейт звіряє її в обох напрямках із маршрутами, які ваш код фактично реєструє, тож маніфест є контрактом, що піддається перевірці, а не просто документацією.
Кожна кінцева точка (endpoint) потребує method (GET, POST, PUT, PATCH або DELETE) та path. Решта параметрів:
| Поле | Що це означає |
|---|---|
auth |
Один із п’яти класів: scope (маршрут користувача, захищений охоронцем області дії — scope guard), service-key та internal (міжсерверна взаємодія, ніколи не доступна з браузера), public (завжди лише точний шлях із allowAnonymous) і device (машина з власними обліковими даними, захищена охоронцем пристрою — device guard) |
right |
Обов’язково для кожного маршруту, який обслуговує охоронець області дії, і заборонено для будь-яких інших: назва права в реєстрі rights |
needsUnit |
Маршрут відхиляє запит, якщо не вдається визначити підрозділ ініціатора виклику |
allowAnonymous |
Лише список дозволеного з точним збігом. Правило за префіксом — це саме те, через що /health-of-tenant-42 стає публічним |
group, serves, screens |
У блоці release: група можливостей, яку обслуговує маршрут, що саме він відповідає, коли ліцензовану функцію цієї групи заблоковано (data, teaser, sighting або ask), та екрани, які він обслуговує |
query |
required (кожна назва з прикладом значення) та allowed: параметри запиту (query parameters), які читає маршрут |
body |
example: приклад тіла запиту для маршруту запису, який приймається його власним валідатором. Ніколи не використовується для GET |
rights — це реєстр, на який посилаються ці маршрути. Кожне право має roles (верхню межу) та необов’язково summary, never (ролі, які ніколи не можуть скористатися цим правом, незалежно від інших наявних у них прав), barred (власне формулювання продукту для відмови ролі з never), seat (також потрібне активне робоче місце — seat), self (має кожна верифікована особа для прав щодо власної сесії), grants (власники надають робочі місця; це може бути вказано щонайбільше для одного права), licence (ліцензована функція, яка має бути в ліцензії організації), installation (мають лише власні адміністратори інсталяції) та platform (мають лише адміністратори платформи Adverant; ролі не вказуються). Назви прав містять щонайменше одну крапку: 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). Він також відхиляє реєстр, який суперечить сам собі, і два варіанти написання одного маршруту (: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 |
Максимальна кількість подів, що одночасно утримують пул: репліки плюс перевищення (surge) під час поступового оновлення. Ліміт з’єднань для кожної ролі формується як maxConnections × pods; якщо пропустити цей параметр, definePlugin видасть попередження DB_PODS_UNDECLARED |
statementTimeoutMs |
Один вираз (statement) |
idleInTransactionTimeoutMs |
Відкрита транзакція, яка нічого не виконує |
workMemKB |
Один вузол сортування або хешування (на вузол, а не на весь запит) |
piiMask[] |
Записи table.column, що містять персональні дані, які маскуються в керованій SQL-консолі та в логах |
Навички та інструменти: skills, mcpTools, entitlements
skills[] містить навички маніфесту; їхні поля та рівні описано в розділі 2.20, «Навички». mcpTools[] містить інструменти MCP (Model Context Protocol), які публікує плагін, кожен із яких має name, description та inputSchema без oneOf, allOf або anyOf на верхньому рівні.
entitlements вимагає featureIdPattern і приймає alwaysOn[], source та store. Шаблон задає простір імен, у якому містяться ідентифікатори ваших функцій — зазвичай це name плагіна плюс один сегмент, який ваш код заповнює для кожного інтерфейсу. alwaysOn[] — це короткий, точний список маршрутів, які повинні відповідати навіть тоді, коли неможливо отримати вердикт щодо прав доступу (entitlement): перевірка працездатності (health), готовності (readiness), вхід у систему та налаштування, необхідні адміністратору для відновлення прав доступу.
Керування змінами: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Погодження рахуються за різними людьми, і особа, яка запропонувала зміну, ніколи не входить до їх числа; без обох цих умов «два погодження» перетворюються на одну людину, яка двічі натиснула кнопку. enabled: true вимагає classes, і для кожного вказаного класу потрібна власна кількість погоджень. Клас, який ви пропустите, залишається некерованим — це допустимий вибір, який схема змушує вас зафіксувати явно.
Хто ви: 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 та platformClients[] — клієнти SDK, які ваш бекенд імпортує за назвою. Цей список є закритим, і контрольний гейт звіряє його з вашими імпортами. Схема дозволяє чотирнадцять назв: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin і uno, плюс одна для клієнта, який відповідає на відмови щодо прав доступу за тарифним планом (зберігає внутрішню назву). Клієнт перевірки прав на функції, runtime/entitlements, не входить до цього переліку і ніколи не додається до списку, оскільки його вже оголошує ваш блок entitlements, а бекенд, який імпортує його без блока entitlements, не пройде той самий контрольний гейт. frontend містить basePath, mountPath та framework. nexus містить minVersion, maxVersion, capabilities[] та permissions[].
Кожен із решти блоків відповідає за одне конкретне завдання:
| Блок | Призначення |
|---|---|
settings |
Ваші налаштування у спільному фреймворку: groups та keys, що задаються на рівнях, які вказує кожен із них |
people |
sweep (service, port): учасники організації, синхронізовані зі службою ідентифікації, з автоматичним вимкненням робочих місць у разі звільнення співробітника |
ontology |
entityTypes та relationshipTypes: типізований граф, що зберігається у вашій власній схемі |
release |
groups та frame: групи можливостей, за якими розподілено ваші маршрути, що спочатку випускаються як канаркові релізи (canary) |
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 |
Два свідомо відкриті об’єкти для назв ваших власних метрик і генерації архітектурної документації |
Чого не може виразити схема
JSON Schema визначає структуру, а definePlugin додає правила, які схема виразити не здатна. Значення classification навички не може перевищувати верхню межу довіри. Лише плагіни рівнів core та verified можуть оголошувати навички tool_using і llm_only. Кожен оголошений шлях має бути відносним і належати до того самого джерела (same-origin), без схеми, без // і без зворотної скісної риски, оскільки парсер URL-адрес перетворює \ на /, а /\evil.example/x розпізнається як міждоменний (cross-origin) перехід. Кожне правило, яке синхронізація реєстру застосовує до навички, спочатку застосовується тут із власним кодом синхронізації, тож і 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
У разі збою виводиться точний шлях, а для правила синхронізації спочатку виводиться код. Зробіть цю перевірку перехоплювачем комітів (commit hook).
Маніфест версії v1 оновлюється механічно. migrate додає три речення законів, переміщує domain у domains[] і відмовляється вигадувати точку входу (entrypoint), якої у вас не було. Інструмент валідує результат перед тим, як вивести або записати будь-що, тож міграція ніколи не перенесе помилку з інструмента до вашого репозиторію.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeПерегляньте різницю (diff) перед тим, як зафіксувати зміни в коміті. Речення законів, які додає інструмент, мають те саме формулювання, якого вимагає валідатор; для власної інсталяції замініть значення deploy на речення, наведене раніше.
Формування конфігурації тенантів і налаштування ролей
Ви ніколи не пишете призначення ролей (grants) або шаблон безпеки на рівні рядків вручну. 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Згенерований файл створює для схеми п’ять ролей, кожна з яких позбавлена прав, яких вона не повинна мати: мігратор, який може лише ставати власником; власник, який не може входити в систему; роль застосунку для обробки запитів; роль звітності, яка бачить лише агреговані дані; та роль журналу, яка може лише додавати записи. Жодна роль не має привілею BYPASSRLS. Єдиний спосіб прив’язати орендаря — це одна функція бази даних, а право set_config відкликано в усіх ролей, крім власника.
Застосований файл багатоорендності ніколи не редагується. Зміна оформлюється як ревізія з власним файлом під номером 0; саме так, у вигляді ревізії 2, додається робоче місце з правом читання для міжорганізаційних дозволів. --graph генерує дві таблиці типізованого графа, які оголошує ваш ontology, як вашу наступну пронумеровану міграцію.
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> — приватний каталог. Команда provision послідовно застосовує базовий файл багатоорендності та кожну ревізію, записує migrator.url і app.url (а також seat.url, щойно з’явиться ревізія 2) у каталог <dir> із режимом доступу 0600 і не виводить на екран жодних секретних даних. Під час кожного запуску вона встановлює ліміт з’єднань для кожної ролі на основі db.maxConnections × db.pods. Повторний запуск зберігає наявні паролі, якщо ви не вкажете інше: --passwords <dir> встановлює їх із файлів, а --rotate <roles> генерує нові паролі для вказаних ролей. Перетворіть ці файли на секрети вашого середовища розгортання.
Після цього застосування міграцій підключається за допомогою рядка підключення мігратора, який було записано на етапі підготовки (provision):
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonІнструмент виконує файли, починаючи з 001, від імені мігратора; кожен файл виконується під SET ROLE <schema>_owner, по одній транзакції на файл. Він веде журнал <schema>.schema_migrations із контрольною сумою кожного файлу; уже застосований файл, байти якого змінилися, відхиляється за назвою (CHECKSUM_DRIFT) і ніколи не виконується повторно й не пропускається. Кожен файл у черзі перед запуском першого аналізується за допомогою справжньої граматики Postgres, тож у разі відмови база даних залишається недоторканою. Єдиний заголовок, який може містити файл, — це -- nexus-migration: transaction=file|per-statement із необов’язковими таймаутами блокування та виконання виразу; per-statement призначено для CREATE INDEX CONCURRENTLY.
Контрольні рубежі (gates)
nexus-gates запускає двадцять два контрольні гейти. Кожен із них кодує один клас дефектів, щоб унеможливити його повторну появу в релізі, і кожен має самотест, який доводить, що гейт спрацьовує на спеціально створеному для цього тестовому прикладі (fixture). Запускайте їх перед відправленням коду (push):
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Гейт | Що виявляє |
|---|---|
scope-adherence |
Маршрут /api без охоронця області дії; анонімний шлях, який не збігається точно з оголошеним; маршрут пристрою без охоронця пристрою або з охоронцем користувача поруч із ним |
one-fence |
Предикат орендаря, визначений будь-де, крім одного дозволеного місця, включно із самописним бар’єром (fence) для робочих місць або дозволів |
sql-fence |
Вираз, який читає або оновлює таблицю, обмежену областю дії, без захисного бар’єра в будь-якій цілі FROM, JOIN, USING або UPDATE |
migrations-are-scoped |
Таблицю, у якій відсутня вісь, складений ключ із першим полем орендаря, зовнішній ключ із полем орендаря або демонстраційний стовпець |
migrations-commit-what-they-open |
Міграцію, у якій кількість BEGIN не збігається з кількістю COMMIT та ROLLBACK |
no-direct-compute |
Прямий виклик постачальника моделей, рушія, черги або хоста робочих процесів; другий компонент, що читає URL-адресу диспетчеризації |
no-credentials |
Облікові дані постачальника моделей, доступні для читання в репозиторії або середовищі |
crud-adherence |
Маршрут зміни даних, перевірка прав якого не посилається на жоден запис у реєстрі |
blocked-backends |
Маршрут, який не обслуговується, не заблокований за назвою, не відхилений за законом і не належить іншому компоненту |
every-test-runs |
Тести, які ніколи не охоплюються glob-шаблоном тестового скрипту |
tiles-are-invariant |
Кешований стик (seam), інваріантний щодо орендаря, який читає значення орендаря або пропускає автентифікацію |
api-contract |
Зареєстрований маршрут, який не оголошено в маніфесті, або оголошений маршрут, який код ніколи не реєструє |
rls-present |
Таблицю без примусової безпеки на рівні рядків; функцію SECURITY DEFINER без зафіксованого search_path |
no-set-config |
Код плагіна, який самостійно прив’язує параметр орендаря |
db-role-honest |
Шлях обробки запиту, що підключається від імені власника чи мігратора або запитує SUPERUSER чи BYPASSRLS |
platform-clients |
Клієнт SDK, який імпортовано, але не вказано в backend.platformClients, або вказано в списку, але ніколи не імпортовано |
rights-register |
Маршрут області дії без оголошеного права; перевірку права в обхід реєстру |
refusal-ledger |
Оголошену таблицю відмов без установленого журналу або тіло відповіді про відмову, надіслане в обхід нього |
grants-declared |
Таблицю з наданим доступом, яку не оголошує маніфест; привілеї робочого місця на читання, роздані вручну |
people-declared |
Блок people без його маршруту очищення (sweep), охоронця та таблиць |
functions-closure |
Плагін Azure Functions, у якого обслуговувані маршрути не збігаються з оголошеними |
declared-input |
Список параметрів запиту обробника, який не відповідає оголошеному в маршруті query |
Каталог gates/ містить п’ять файлів винятків, які може читати контрольний гейт (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json та invariant-seams.json), по одному обґрунтуванню на запис. Порожнє обґрунтування прирівнюється до відсутності запису, а запис, що вказує на елемент, якого більше не існує, призводить до помилки гейта. Ви також можете додати туди власні модулі гейтів, і nexus-gates підхопить їх разом із вбудованими.
Конвеєр (pipeline) шаблону
Шаблон не постачається з написаним вручну робочим процесом (workflow). Конфігурація його конвеєра визначає Dockerfile, єдиний аргумент збирання (токен реєстру), пробний прогін міграції, перевірку запуску (boot probe) та контрольний гейт, який запускає черга злиття (merge queue). Порядок виконання відповідає порядку, у якому ви б хотіли виявляти збої якнайшвидше.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, що єcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, що єnexus-gates --self-testnode scripts/ci/required-env
Навколо образу виконуються ще дві перевірки. Пробний запуск міграції застосовує кожен файл до тимчасового екземпляра Postgres перед тим, як образ можна буде випустити, за допомогою того самого виконавця, який використовується в промисловому середовищі: nexus-migrate provision один раз від імені суперкористувача, а потім кожен пронумерований файл від імені мігратора. Перевірка завантаження запускає зібраний образ із власною точкою входу та кожною змінною, яку виводить required-env, спрямованою на заглушки, що приймають з’єднання, але ніколи не відповідають. Сервер очікує на базу даних у межах свого обмеженого часового вікна, і це очікування є сигналом успішного проходження; завантажувач конфігурації, який відмовляється запускатися, перериває збірку на цьому етапі, а не в промисловому середовищі.
Вартість
SDK бере прийняття рішень на себе, і деякі з них ви б прийняли інакше. Маніфест відхиляє невідомі йому ключі, таблиця маршрутів має точно збігатися з вашим кодом, ролі бази даних проєктуєте не ви, а контрольні перевірки переривають збірку через відсутність права на читання. Під час роботи над своїм першим плагіном я витратив день на суперечки з api-contract щодо маршруту, який я зареєстрував, але забув оголосити. Він мав рацію: маршрут був незахищеним. Будьте готові до того, що розробка першого плагіна здаватиметься повільною, а другий займе третину цього часу.

