Версия 1.0.0-alpha.1последно
Глава 2.21
Пакетът Plugin SDK
Инсталиране на Plugin SDK (пакет за разработка на софтуер), неговите инструменти за командния ред, преглед на шаблона за пълна услуга, манифестът v2 поле по поле и двадесет и двете проверки, които следят плъгинът да спазва правилата.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Вторият ми плъгин отне една трета от времето на първия, а почти цялото спестено време се дължеше на SDK (комплект за разработка на софтуер). Първия път написах проверка на обхвата, инструмент за зареждане на конфигурацията и изпълнител на миграции, а рецензентът върна всеки един от тях. Втория път стартирах една команда за генериране на шаблон (scaffold), изтрих примерно умение за анализ на настроенията и прекарах дните си върху записите за преглед на аномалии, от които екипът ни по динамика на полета всъщност се нуждаеше.
@adverant-nexus/plugin-sdk е един npm пакет. Той съдържа схемата на манифеста v2 и валидаторите, които я четат (definePlugin, defineSkill), модулите за среда на изпълнение (runtime), които вашият плъгин импортира за обхват, база данни, диспечиране и останалото, помощни средства за тестване, контролните точки за съответствие (adherence gates) и инструментите за команден ред. Тази глава разглежда инсталирането му, инструментите, шаблона, манифеста и контролните точки. Глава 2.22, Средата на изпълнение на плъгина, разглежда модулите за среда на изпълнение във вашия работещ код.
Инсталиране
Пакетът идва от регистъра на Adverant на адрес https://registry.adverant.ai/npm/, никога от публичния npm регистър, и се нуждаете от токена за изтегляне (pull token) от страницата „Токени за изтегляне и команди за инсталиране“ на вашия акаунт. Насочете обхвата @adverant-nexus към регистъра във файла .npmrc на вашето хранилище:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> е токенът от страницата на вашия акаунт. В конвейер (pipeline) го подайте от тайна (secret) и никога не го комитвайте; Dockerfile на шаблона отказва да компилира без него и изтрива .npmrc от етапа на изграждане, след като npm ci завърши, така че токенът никога не попада в готов образ (image).
След това фиксирайте точно версията:
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) на вашата схема от манифеста: роли, права, шаблон за сигурност на ниво ред (RLS) и таблиците на графа |
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 разминаване или нарушение на линтера · 2 неправилна употреба |
help |
Отпечатва начина на употреба | 0 |
Генериране на начална структура и трите нива
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier по подразбиране е full-service. Генераторът на шаблони отказва да записва в директория, която вече съществува, а манифестът, който записва, вече преминава валидация; той никога не издава невалиден манифест.
Изберете нивото според това какво съдържа вашият плъгин.
| Ниво | Съдържа | Трябва да декларира |
|---|---|---|
skills-only |
Умения в манифеста и нищо друго | skills[], с поне един запис |
ui-only |
Фронтенд интерфейс вътре в обвивката (shell) | frontend |
full-service |
Бекенд и фронтенд, обикновено със собствена схема | backend и frontend; и тъй като има бекенд, runtime.healthCheck |
Ако не сте сигурни, генерирайте шаблон с full-service и изтрийте това, което не ви трябва. Обратният подход означава да пишете частите, които шаблонът би ви дал наготово.
Преглед на шаблона за пълна услуга
Шаблонът е референтният плъгин, изграден по строгия модел, който всяка следваща глава предполага. Клонирайте неговата форма, а не примерната му логика.
| Път | Какво представлява |
|---|---|
nexus.manifest.json |
Манифестът v2: трите закона, формулирани отново, таблицата с маршрути и нейният регистър на правата |
src/config.ts |
Инструментът за зареждане на конфигурация. Една спецификация, прочетена веднъж, като всеки проблем се събира, преди процесът да откаже да стартира |
src/scope.ts |
Единственият файл, който превръща заявката в обхват, със строгия верификатор на токени на SDK и два режима: токен на приносител (bearer token) на лице и сервизно повикване на платформата |
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/ |
Тестове за обхват, маршрути, база данни, диспечиране и стартиране, с дубликатите на обхват, които всеки тест инжектира |
Dockerfile |
Образ без root права (потребителски ID 10001) с миграциите вътре в него |
Няколко от тези файлове заслужават по-внимателен поглед.
src/config.ts следва две правила. Той събира всеки проблем, преди да хвърли грешка, така че едно рестартиране назовава всичките пет липсващи променливи, вместо пет рестартирания да назовават по една. И задава стойност по подразбиране само когато грешна стойност не може да доведе до тих грешен отговор: PORT може да бъде по подразбиране 8080, защото грешен порт се проваля видимо при свързване (bind), докато 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) се вписва в лимита за връзки на ролята и че таблицата на регистъра на отказите може да приеме ред. Отказ от което и да е от трите се отпечатва изцяло и процесът завършва с код 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[]. Таблицата с маршрути е най-силната идея в схемата: контролна точка я сравнява с маршрутите, които вашият код реално регистрира, и в двете посоки, така че манифестът е проверим договор, а не документация.
Всяка крайна точка се нуждае от method (GET, POST, PUT, PATCH или DELETE) и path. Останалото:
| Поле | Какво гласи |
|---|---|
auth |
Един от пет класа: 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: параметрите на заявката (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 |
Най-големият брой подове, държащи пул едновременно – репликите плюс пика при постепенно обновяване (rolling update). Лимитът за връзки на всяка роля се изчислява като maxConnections × pods; ако го пропуснете, definePlugin предупреждава с DB_PODS_UNDECLARED |
statementTimeoutMs |
Един израз |
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), влизане (sign-in) и настройките, от които администраторът се нуждае, за да поправи правата.
Контрол на промените: 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 схемата определя формата; 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[] и отказва да измисли входна точка, която не сте имали. Той валидира резултата преди да отпечата или запише каквото и да било, така че миграцията никога не прехвърля грешка от инструмента във вашето хранилище.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeПрочетете разликите (diff), преди да ги комитнете. Изреченията за законите, които добавя, са формулировката, която валидаторът изисква; за вашата собствена инсталация задайте 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Генерираният файл създава пет роли за схемата, всяка с това, което не трябва да притежава: мигратор, който може само да стане собственик, собственик, който не може да влиза в системата, роля на приложение за пътя на заявката, роля за отчети, която вижда само агрегати, и роля за регистър, която може само да добавя записи. Никоя роля не притежава 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> е частна директория. Провизирането прилага базовия файл за многоабонатен режим и всяка ревизия по ред, записва migrator.url и app.url (и seat.url, след като ревизия 2 съществува) в <dir> с режим 0600 и не отпечатва нищо тайно. То задава лимита за връзки на всяка роля от db.maxConnections × db.pods при всяко изпълнение. Повторното изпълнение запазва съществуващите пароли, освен ако не поискате друго: --passwords <dir> ги задава от файлове, а --rotate <roles> дава нови на назованите роли. Превърнете файловете в тайни (secrets) на вашето внедряване.
След това прилагането се свързва с низа за връзка на мигратора, който провизирането е записало:
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, преди да се изпълни първият, така че отказът оставя базата данни непокътната. Единственият заглавен ред (header), който един файл може да носи, е -- nexus-migration: transaction=file|per-statement, с незадължителни времена на изчакване за заключване и израз; per-statement е за CREATE INDEX CONCURRENTLY.
Проверките
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 |
Списък с параметри на заявката на обработчик (handler), който не съвпада с декларираните query на маршрута |
Директорията gates/ съдържа петте файла с изключения, които една контролна точка може да чете (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json и invariant-seams.json), по една причина на запис. Празна причина се брои като липса на запис, а запис, назоваващ нещо, което вече не съществува, проваля контролната точка. Можете също така да пуснете свои собствени модули за контролни точки там и nexus-gates ги разпознава наред с вградените.
Конвейерът на шаблона
Шаблонът не доставя ръчно написан работен процес (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 за маршрут, който бях регистрирал и забравил да декларирам. Беше прав; маршрутът беше незащитен. Очаквайте първият плъгин да се усеща бавен и очаквайте вторият да отнеме една трета от времето.

