Přihlásit seDomluvit prezentaci

Kapitola 2.21

Plugin SDK

Instalace sady Plugin SDK (sada pro vývoj softwaru), její nástroje příkazového řádku, prohlídka šablony plnohodnotné služby, manifest v2 pole po poli a dvacet dva bran, které zajišťují, že plugin dodržuje pravidla.

Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

22 min čtení

Můj druhý plugin mi zabral třetinu času oproti prvnímu a téměř celá úspora spočívala v použití sady SDK (software development kit). Poprvé jsem psal kontrolu rozsahu (scope), zavaděč konfigurace a spouštěč migrací, a revizor mi každý z nich vrátil k přepracování. Podruhé jsem spustil jeden příkaz pro vygenerování kostry (scaffold), smazal ukázkovou dovednost pro analýzu sentimentu a věnoval svůj čas záznamům pro kontrolu anomálií, které náš tým letové dynamiky skutečně potřeboval.

@adverant-nexus/plugin-sdk je jeden balíček npm. Obsahuje schéma manifestu v2 a validátory, které jej čtou (definePlugin, defineSkill), běhové moduly, které váš plugin importuje pro rozsah, databázi, odesílání (dispatch) a zbytek, pomocné testovací nástroje, kontrolní brány (adherence gates) a nástroje příkazového řádku. Tato kapitola popisuje jeho instalaci, nástroje, šablonu, manifest a kontrolní brány. Kapitola 2.22, Běhové prostředí pluginu, se věnuje běhovým modulům ve vašem spuštěném kódu.

Instalace

Balíček pochází z registru společnosti Adverant na adrese https://registry.adverant.ai/npm/, nikdy z veřejného registru npm, a potřebujete k němu stahovací token (pull token) ze stránky „Pull tokens and install commands“ ve vašem účtu. Nasměrujte rozsah @adverant-nexus na tento registr v souboru .npmrc vašeho repozitáře:

@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>

<pull-token> je token ze stránky vašeho účtu. V pipeline jej předávejte z tajného úložiště (secret) a nikdy jej neukládejte do repozitáře (commit); Dockerfile šablony bez něj odmítne sestavení a po proběhnutí npm ci smaže .npmrc z fáze sestavení, takže se token nikdy nedostane do výsledného obrazu (image).

Poté připněte přesnou verzi:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Při první instalaci uložte package-lock.json do repozitáře. Sestavení obrazu šablony spouští npm ci a odmítne přejít k záložnímu npm install: soubor zámku (lockfile) je závaznou smlouvou. Minimální požadavek samotné sady SDK je Node 18; šablona cílí na Node 20.

Nástroje příkazového řádku jsou součástí balíčku, takže každý příkaz v této dokumentaci uvádí název balíčku a jeho verzi pomocí npx -p. Samotný npx create-nexus-plugin se vyhledává ve veřejném registru a tento název neodpovídá tomuto balíčku.

Nástroje příkazového řádku

Nástroj Co dělá
create-nexus-plugin Vygeneruje kostru pluginu, zvaliduje manifest, migruje manifest z v1 na v2 a vygeneruje uživatelskou příručku pro vašeho frontendového vývojáře
nexus-tenancy Vygeneruje z manifestu SQL pro správu tenantů vašeho schématu: role, oprávnění, šablonu zabezpečení na úrovni řádků (RLS) a grafové tabulky
nexus-migrate Aplikuje vaše migrace: jednou vytvoří role a poté spustí každý očíslovaný soubor pod rolí migrátora
nexus-gates Spustí každou kontrolní bránu dodržování pravidel a vlastní autotest každé brány

create-nexus-plugin neprovádí žádná síťová volání a nenačítá žádný vzdálený kód. Spouští stejné vnitroprocesové validátory, jaké spouští proces nasazení (onboarding) na platformu, takže nedochází k žádnému rozdílu mezi „u mě na stroji to prošlo validací“ a „platforma to přijala“.

Příkaz Příznaky Co dělá Návratové kódy
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Zapíše nový adresář pluginu; --print vypíše pouze manifest 0 zapsáno · 1 odmítnuto přepsání · 2 chybné použití
validate <file> Zvaliduje nexus.manifest.json nebo modul .ts či .js, který jej exportuje 0 platné · 1 neplatné nebo nečitelné · 2 chybné použití
migrate <file> --write Povýší manifest v1 na v2 a vypíše jej, nebo jej přepíše na místě 0 · 1 · 2, viz výše
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Vygeneruje uživatelskou příručku z manifestu a vašeho popisu; --check provede porovnání s uloženou kopií a nic nezapisuje 0 · 1 odchylka nebo chyba linteru · 2 chybné použití
help Vypíše nápovědu k použití 0

Příprava kostry (scaffolding) a tři úrovně

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service

--tier má výchozí hodnotu full-service. Nástroj pro generování kostry odmítne zapisovat do adresáře, který již existuje, a manifest, který zapíše, již prochází validací; nikdy nevygeneruje neplatný manifest.

Vyberte úroveň (tier) podle toho, co váš plugin obsahuje.

Úroveň Obsahuje Musí deklarovat
skills-only Dovednosti manifestu a nic jiného skills[], s alespoň jednou položkou
ui-only Frontendové rozhraní uvnitř prostředí (shell) frontend
full-service Backend a frontend, obvykle s vlastním schématem backend a frontend; a protože má backend, také runtime.healthCheck

Pokud si nejste jisti, vygenerujte kostru full-service a smažte to, co nepotřebujete. Opačný postup znamená dopisovat části, které by vám šablona bývala poskytla.

Prohlídka šablony plnohodnotné služby

Šablona představuje referenční plugin sestavený podle striktního vzoru, který předpokládá každá další kapitola. Klonujte její strukturu, nikoli její ukázkovou logiku.

Cesta Co to je
nexus.manifest.json Manifest v2: zopakování tří zákonů, směrovací tabulka (route table) a její registr oprávnění
src/config.ts Zavaděč konfigurace. Jedna specifikace, načtená jednou; všechny problémy jsou shromážděny předtím, než se proces odmítne spustit
src/scope.ts Jediný soubor, který převádí požadavek na rozsah (scope), se striktním ověřovačem tokenů ze sady SDK a dvěma režimy: doručovací (bearer) token osoby a servisní volání platformy
src/db.ts Každý příkaz skládá tenantFence() a běží uvnitř withScopedTx
src/uno.ts Jediný odesílací soubor (dispatch): jedna adresa URL, jeden klient, uzavřený seznam povolených položek (allow-list)
src/routes/*.ts health (anonymní, přesná cesta), cesty /api (s vymezeným rozsahem) a zpětné volání /internal (chráněné službou)
src/skills/sentiment.ts Deterministická dovednost host_callback; nahraďte slovník vlastní logikou
src/server.ts Kořen kompozice: jednou nainstaluje účetní knihu odmítnutí (refusal ledger), počká na databázi (časově omezeno) a před zahájením naslouchání spustí kontroly izolace a účetní knihy
migrations/000_tenancy.sql Vygenerováno nástrojem nexus-tenancy render v době vytváření kostry: role, schéma, šablona zabezpečení na úrovni řádků
migrations/001_init.sql Dvě tabulky se složeným klíčem začínajícím tenantem a složeným cizím klíčem nesoucím tenanta
migrations/002_refusal_ledger.sql Tabulka, do které zapisuje účetní kniha odmítnutí
scripts/ci/required-env Vypíše názvy proměnných prostředí vyžadovaných při startu jako JSON
scripts/ci/shadow-migrate-*.sh Zkušební běh migrace v pipeline, prostřednictvím nexus-migrate
gates/ Adresář výjimek pro kontrolní brány: prázdný, což je správný stav pro nový plugin
test/ Testy pro rozsah, cesty, databázi, odesílání a start systému, s dvojníky rozsahu (scope doubles), které vkládá každý test
Dockerfile Obraz bez oprávnění root (ID uživatele 10001) s migracemi uvnitř

Několik z těchto souborů si zaslouží bližší pohled.

src/config.ts se řídí dvěma pravidly. Shromáždí všechny problémy předtím, než vyvolá výjimku, takže jeden restart vypíše všech pět chybějících proměnných namísto pěti restartů, z nichž každý vypíše po jedné. A výchozí hodnotu použije pouze tehdy, když špatná hodnota nemůže vést k tiché chybné odpovědi: PORT může mít výchozí hodnotu 8080, protože špatný port viditelně selže při navazování (bind), zatímco DATABASE_URL a UNO_DISPATCH_URL jsou povinné a musí to být adresy uvnitř clusteru. Veřejná adresa je při startu odmítnuta.

node scripts/ci/required-env
["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]

Vlastní test šablony tento soubor spustí a porovná jeho výstup s názvy, které specifikace konfigurace označuje jako povinné, takže přidání povinné proměnné bez aktualizace seznamu způsobí selhání v npm test.

src/server.ts nenaslouchá, dokud databáze neodpoví, a omezuje čekání na 120 sekund, přičemž zaznamenává každý neúspěšný pokus i s jeho příčinou. Poté v daném pořadí prokáže, že aplikační role nemůže změnit vazbu tenanta a každá tabulka má vynucené zabezpečení na úrovni řádků, že fond (pool) každého podu se vejde do limitu připojení dané role a že tabulka účetní knihy odmítnutí dokáže přijmout řádek. Odmítnutí u kteréhokoli z těchto tří bodů se vypíše v plném znění a proces skončí s kódem 2.

Manifest v2, pole po poli

Manifest je strojově čitelná smlouva pluginu s platformou. Validuje se při jeho psaní, při nasazování na platformu a následně nepřetržitě. Schéma má na každé úrovni nastaveno additionalProperties: false: pokud má váš plugin určitou sekci, existuje pro ni vlastnost, a nedeklarovaný klíč je odmítnut. Řešením je vždy použít správnou volitelnou vlastnost.

Povinné jádro

Pole Pravidlo
manifestVersion Přesně "2". Dokument v1 se migruje, nikdy se znovu nevaliduje na místě
name ^[a-z0-9]+([-.][a-z0-9]+)*$, nejvýše 64 znaků. ID pluginu používané při registraci, jmenném prostoru odesílání a řádcích vymezených pro tenanta. Plugin, který deklaruje dovednosti, potřebuje také název bez tečky a bez úvodní číslice
displayName 1 až 120 znaků
version Sémantická verze; váš vlastní cyklus vydávání verzí (release train)
description, author, license Každý alespoň jeden znak
tier skills-only, ui-only nebo full-service
trust core, verified, community nebo untrusted
runtime Povinné: executionMode, isolationLevel (1 až 4), entrypoint. Volitelné: nodeVersion, healthCheck, readinessCheck, livenessCheck, každé jako cesta začínající znakem /. Režim je odvozen z úrovně: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai a deploy, zopakované tři zákony platformy. Validátor vyžaduje přesné znění

Pro plugin, který vytváříte pro vlastní instalaci, znějí tyto tři věty následovně. Věta ai pokrývá AI (umělou inteligenci) a je místem, kde se uvádí, že plugin neuchovává žádné přístupové údaje k modelům.

"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."
}

Směrovací tabulka: api a rights

api potřebuje version a basePath, a volitelně websocket (path, auth) a endpoints[]. Směrovací tabulka je nejsilnější myšlenkou ve schématu: kontrolní brána ji porovnává s cestami, které váš kód skutečně registruje, v obou směrech, takže manifest je kontrolovatelnou smlouvou, nikoli pouhou dokumentací.

Každý koncový bod potřebuje method (GET, POST, PUT, PATCH nebo DELETE) a path. Zbytek:

Pole Co uvádí
auth Jedna z pěti tříd: scope (cesta osoby, za strážcem rozsahu), service-key a internal (server-server, nikdy nedosažitelné z prohlížeče), public (vždy pouze přesná cesta s allowAnonymous) a device (stroj s vlastním pověřením, za strážcem zařízení)
right Povinné na každé cestě, kterou obsluhuje strážce rozsahu, a odmítnuté na jakékoli jiné: název oprávnění v registru rights
needsUnit Cesta odmítne požadavek, pokud nelze vyhodnotit jednotku volajícího
allowAnonymous Pouze seznam povolených položek s přesnou shodou. Pravidlo využívající prefix je způsob, jakým /health-of-tenant-42 skončí jako veřejné
group, serves, screens Pod blokem release: skupina schopností, kterou cesta obsluhuje, co odpoví, když je licencovaná funkce této skupiny uzamčena (data, teaser, sighting nebo ask), a obrazovky, které obsluhuje
query required (každý název s ukázkovou hodnotou) a allowed: parametry dotazu (query parameters), které cesta čte
body example: ukázkové tělo zapisovací cesty, takové, které přijme její vlastní validátor. Nikdy u metody GET

rights je registr, na který se tyto cesty odkazují. Každé oprávnění má roles (strop) a volitelně summary, never (role, které jej nikdy nesmějí uplatnit, bez ohledu na to, co dalšího drží), barred (vlastní formulace produktu pro odmítnutí role v never), seat (je zapotřebí také aktivní místo – seat), self (drží jej každá ověřená osoba, pro oprávnění nad vlastní relací), grants (držitelé udělují místa; uvádí to nejvýše jedno oprávnění), licence (licencovaná funkce, kterou musí obsahovat licence organizace), installation (drží pouze vlastní administrátoři instalace) a platform (drží pouze administrátoři platformy Adverant; nejmenuje žádné role). Názvy oprávnění obsahují alespoň jednu tečku: 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 odmítne cestu rozsahu bez oprávnění (ENDPOINT_RIGHT_MISSING), oprávnění, které v registru chybí (ENDPOINT_RIGHT_NOT_REGISTERED), a oprávnění na cestě, kterou neobsluhuje žádný strážce (ENDPOINT_RIGHT_UNGUARDED). Odmítne také registr, který si protiřečí, a dva různé zápisy téže cesty (:id a :recordId) jako DUPLICATE_ENDPOINT.

Vaše data: databases, schema a db

schema je jediné schéma databáze Postgres, které plugin vlastní. public, plugins, auth a nexus jsou zakázány, a pokud databases[] rovněž uvádí schéma Postgres, musí se obě shodovat.

databases[] deklaruje každé úložiště podle enginu: postgresql (schema, tables, migrations a granted, tabulky, které může číst jiná organizace na základě zaznamenaného udělení oprávnění), neo4j (schemas), qdrant (collections) nebo redis (purpose).

db uchovává limity relací pro každé připojení, které plugin otevře; jsou deklarovány zde namísto zakódování, aby si je mohl přečíst jak revizor, tak samotné nasazení:

Pole Co omezuje
maxConnections Fond (pool) na jednu repliku
pods Nejvyšší počet podů držících fond najednou, tedy repliky plus navýšení (surge) při postupné aktualizaci. Limit připojení každé role je vygenerován jako maxConnections × pods; pokud jej vynecháte, definePlugin vypíše varování DB_PODS_UNDECLARED
statementTimeoutMs Jeden příkaz
idleInTransactionTimeoutMs Otevřená transakce, ve které nic neběží
workMemKB Jeden řadicí (sort) nebo hašovací (hash) uzel, na uzel, nikoli na dotaz
piiMask[] Položky table.column obsahující osobní údaje, maskované v řízené konzoli SQL a v protokolech (logs)

Dovednosti a nástroje: skills, mcpTools, entitlements

skills[] uchovává dovednosti manifestu; kapitola 2.20, Dovednosti, popisuje jejich pole a úrovně. mcpTools[] uchovává nástroje MCP (Model Context Protocol), které plugin publikuje, přičemž každý má name, description a inputSchema bez oneOf, allOf nebo anyOf na nejvyšší úrovni.

entitlements vyžaduje featureIdPattern a přijímá alwaysOn[], source a store. Vzor určuje jmenný prostor, ve kterém žijí ID vašich funkcí, konvenčně name pluginu plus jeden segment, který váš kód doplní pro každé rozhraní. alwaysOn[] je krátký, přesný seznam, který musí odpovídat, i když nelze získat verdikt o nároku (entitlement): stav (health), připravenost (readiness), přihlášení a nastavení, která administrátor potřebuje k opravě nároku.

Řízení změn: changePolicy

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Schválení se počítají v různých osobách a osoba, která změnu navrhla, není nikdy jednou z nich; bez obou těchto podmínek by se „dvě schválení“ stala jednou osobou, která klikne dvakrát. enabled: true vyžaduje classes a každá uvedená třída potřebuje svůj vlastní počet. Třída, kterou vynecháte, nepodléhá řízení, což je legitimní volba, kterou vás schéma nutí výslovně zapsat.

Kdo jste: domains, branding, routing

domains[] (každé s primary a aliases[]; domain je forma pro jednu doménu) uvádí, kde plugin odpovídá. branding vyžaduje appName a přijímá tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId a gaId. Vše v branding je veřejné: přihlašovací stránka to čte ještě předtím, než má kdokoli přihlašovací údaje, takže to nikdy neobsahuje tajemství ani interní adresu. routing (type, gateway, virtualService) je pro pluginy, které popisují své vlastní směrování.

Dimenzování a zbytek

resources vyžaduje cpuMillicores (10 až 64 000) a memoryMB (16 až 262 144) a přijímá diskGB, timeoutMs, port a wsPort. backend uchovává port, healthPath, apiPrefix, framework a platformClients[], klienty sady SDK, které váš backend importuje podle názvu. Seznam je uzavřený a kontrolní brána jej ověřuje oproti vašim importům. Schéma povoluje čtrnáct názvů: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin a uno, plus jeden pro klienta, který odpovídá na odmítnutí nároku z plánu, jenž si ponechává interní název. Klient pro nároky na funkce, runtime/entitlements, mezi ně nepatří a na seznam se nikdy neuvádí, protože jej již deklaruje váš blok entitlements, a backend, který jej importuje bez bloku entitlements, neprojde stejnou kontrolní branou. frontend uchovává basePath, mountPath a framework. nexus uchovává minVersion, maxVersion, capabilities[] a permissions[].

Zbývající bloky zde mají každý jeden konkrétní úkol:

Blok Účel
settings Vaše nastavení na sdíleném frameworku: groups a keys, nastavené na úrovních, které každé z nich uvádí
people sweep (service, port): členové organizace, synchronizovaní ze služby identity, s vypnutím míst (seats), když někdo odejde
ontology entityTypes a relationshipTypes: typovaný graf udržovaný ve vašem vlastním schématu
release groups a frame: skupiny schopností, do kterých jsou vaše cesty fázovány, vydávané nejprve jako kanárkové nasazení (canary)
cells[] Plugin, který se skládá z několika nasaditelných jednotek: každá má name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] pro váš záznam v katalogu
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kdo jej publikuje a kde se nachází jeho kód
metrics, atlas Dva záměrně otevřené objekty pro vaše vlastní názvy metrik a generování dokumentace architektury

Co schéma nedokáže vyjádřit

Schéma JSON určuje tvar; definePlugin přidává pravidla, která schéma vyjádřit nedokáže. classification dovednosti nesmí překročit strop důvěryhodnosti. Pouze pluginy core a verified mohou deklarovat dovednosti tool_using a llm_only. Každá deklarovaná cesta musí být relativní a stejného původu (same-origin), bez schématu, bez // a bez zpětného lomítka, protože analyzátor URL převádí \ na / a /\evil.example/x se vyhodnotí jako cizí původ (cross-origin). Každé pravidlo, které synchronizace registru uplatňuje na dovednost, se nejprve uplatní zde, pomocí vlastního kódu synchronizace, takže validate a synchronizace označují porušené pravidlo stejným způsobem.

Validace a přechod z verze 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

Selhání vypíše přesnou cestu a u pravidla synchronizace nejprve kód. Udělejte z toho kontrolní bod při uložení (commit hook).

Manifest v1 se povyšuje mechanicky. migrate přidá tři věty zákonů, přesune domain do domains[] a odmítne si vymyslet vstupní bod (entrypoint), který jste neměli. Výsledek zvaliduje předtím, než cokoli vypíše nebo zapíše, takže migrace nikdy nepřesune chybu z nástroje do vašeho repozitáře.

npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --write

Před uložením do repozitáře (commit) si přečtěte rozdíly (diff). Věty zákonů, které přidává, mají znění vyžadované validátorem; pro vlastní instalaci nastavte deploy na větu uvedenou dříve.

Vykreslení tenanta a zřízení rolí

Oprávnění rolí ani šablonu zabezpečení na úrovni řádků nikdy nepíšete ručně. nexus-tenancy render je zapíše z položek schema a db v manifestu:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sql

Vygenerovaný soubor vytvoří pro schéma pět rolí, každou s tím, co nesmí držet: migrátora, který se může stát pouze vlastníkem, vlastníka, který se nemůže přihlásit, aplikační roli pro cestu požadavku, reportovací roli, která vidí pouze agregace, a roli účetní knihy, která může pouze připojovat záznamy. Žádná role nedrží BYPASSRLS. Jediným způsobem, jak navázat tenanta, je jedna databázová funkce a oprávnění set_config je odebráno všem rolím kromě vlastníka.

Aplikovaný soubor správy tenantů se nikdy neupravuje. Změna představuje revizi s vlastním souborem s číslem 0 a tímto způsobem, jako revize 2, přichází i čtecí místo (read seat) pro udělení oprávnění napříč organizacemi. --graph vygeneruje dvě tabulky typovaného grafu, které deklaruje vaše ontology, jako vaši další očíslovanou migraci.

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

Soubor správy tenantů vytváří právě ty role, pod kterými se připojuje spouštěč, takže jej aplikuje vlastník databáze pomocí 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> je připojovací řetězec pro vlastníka databáze a <dir> je soukromý adresář. Příkaz provision aplikuje základní soubor správy tenantů a každou revizi v daném pořadí, zapíše migrator.url a app.url (a seat.url, jakmile existuje revize 2) do <dir> s režimem 0600 a nevypíše nic tajného. Při každém spuštění nastaví limit připojení každé role podle db.maxConnections × db.pods. Opětovné spuštění zachová stávající hesla, pokud si nevyžádáte změnu: --passwords <dir> je nastaví ze souborů a --rotate <roles> přidělí jmenovaným rolím nová hesla. Převeďte tyto soubory na tajemství (secrets) vašeho nasazení.

Poté se proces aplikování připojí pomocí připojovacího řetězce migrátora, který zapsal příkaz provision:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

Spouští soubory od 001 dále pod rolí migrátora, každý soubor pod SET ROLE <schema>_owner, jedna transakce na soubor. Udržuje účetní knihu, <schema>.schema_migrations, s kontrolním součtem každého souboru; aplikovaný soubor, jehož bajty se změnily, je odmítnut podle názvu (CHECKSUM_DRIFT), nikdy se nespustí znovu a nikdy se nepřeskočí. Každý čekající soubor je před spuštěním prvního z nich analyzován skutečnou gramatikou databáze Postgres, takže odmítnutí ponechá databázi nedotčenou. Jediná hlavička, kterou může soubor nést, je -- nexus-migration: transaction=file|per-statement, s volitelnými časovými limity pro zámek a příkaz; per-statement je pro CREATE INDEX CONCURRENTLY.

Brány

nexus-gates spouští dvacet dva kontrolních bran. Každá z nich kóduje jednu třídu defektů, aby nemohla být nasazena dvakrát, a každá má autotest, který prokazuje, že selže na testovacím vzorku (fixture) sestaveném tak, aby ji aktivoval. Spusťte je před odesláním změn (push):

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Kontrolní brána Co zachytí
scope-adherence Cestu /api bez strážce rozsahu; anonymní cestu, která není přesně deklarovaná; cestu zařízení bez strážce zařízení nebo se strážcem osoby vedle něj
one-fence Predikát tenanta definovaný kdekoli jinde než na jednom místě, včetně ručně napsané ohrady (fence) pro místo nebo udělení oprávnění
sql-fence Příkaz čtoucí nebo aktualizující tabulku s vymezeným rozsahem bez ohrady, v jakémkoli cíli FROM, JOIN, USING nebo UPDATE
migrations-are-scoped Tabulku, které chybí osa, složený klíč začínající tenantem, cizí klíč nesoucí tenanta nebo demo sloupec
migrations-commit-what-they-open Migraci, jejíž počet BEGIN neodpovídá počtu COMMIT a ROLLBACK
no-direct-compute Přímé volání poskytovatele modelu, enginu, fronty nebo hostitele pracovních postupů (workflow); druhého čtenáře odesílací adresy URL
no-credentials Přístupové údaje k poskytovateli modelu čitelné v repozitáři nebo v prostředí
crud-adherence Modifikující cestu, jejíž kontrola oprávnění neodkazuje na nic v registru
blocked-backends Cestu, která není ani obsluhována, ani blokována podle názvu, ani odmítnuta ze zákona, ani vlastněna jinde
every-test-runs Testy, na které vzor (glob) testovacího skriptu nikdy nedosáhne
tiles-are-invariant Rozhraní v mezipaměti neměnné vůči tenantovi, které čte hodnotu tenanta nebo přeskakuje autentizaci
api-contract Zaregistrovanou cestu, kterou manifest nedeklaruje, nebo deklarovanou cestu, kterou kód nikdy nezaregistruje
rls-present Tabulku bez vynuceného zabezpečení na úrovni řádků; funkci SECURITY DEFINER bez připnutého search_path
no-set-config Kód pluginu, který sám nastavuje vazbu tenanta
db-role-honest Cestu požadavku připojující se jako vlastník nebo migrátor, nebo žádající o SUPERUSER či BYPASSRLS
platform-clients Klienta sady SDK, který je importován, ale není uveden v backend.platformClients, nebo je uveden, ale nikdy není importován
rights-register Cestu rozsahu bez deklarovaného oprávnění; kontrolu oprávnění mimo registr
refusal-ledger Deklarovanou tabulku odmítnutí bez nainstalované účetní knihy, nebo tělo odmítnutí odeslané mimo ni
grants-declared Tabulku s uděleným oprávněním, kterou manifest nedeklaruje; ručně rozdaná oprávnění čtecího místa
people-declared Blok people bez jeho úklidové (sweep) cesty, strážce a tabulek
functions-closure Plugin Azure Functions, jehož obsluhované cesty a deklarované cesty se neshodují
declared-input Seznam parametrů dotazu obslužné rutiny (handler), který neodpovídá deklarovanému query dané cesty

Adresář gates/ uchovává pět souborů výjimek, které může kontrolní brána číst (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json a invariant-seams.json), s jedním důvodem na položku. Prázdný důvod se počítá jako žádná položka a položka jmenující něco, co již neexistuje, způsobí selhání brány. Můžete tam také vložit své vlastní moduly bran a nexus-gates je načte vedle těch vestavěných.

Kompatibilita
Kompatibilita
Kompatibilita ukazuje, která verze sady SDK funguje se kterou verzí platformy, na základě nočních běhů rychlého startu (quickstart). Neotestovaná dvojice je takto označena a selhávající dvojice uvádí změnu, která ji rozbila.

Pipeline šablony

Šablona neobsahuje žádný ručně psaný pracovní postup (workflow). Její konfigurace pipeline uvádí Dockerfile, jediný argument sestavení (token registru), zkušební běh migrace a sondu startu (boot probe) a kontrolní bránu, kterou spouští fronta sloučení (merge queue). Pořadí odpovídá pořadí, ve kterém byste chtěli, aby proces v případě chyby selhal.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, což je create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, což je nexus-gates --self-test
  7. node scripts/ci/required-env

Kolem obrazu probíhají ještě dvě kontroly. Zkušební běh migrace aplikuje každý soubor na jednorázový Postgres dříve, než může být obraz vydán, se stejným spouštěčem, jaký používá produkce: nexus-migrate provision jednou jako superuživatel a poté každý očíslovaný soubor jako migrátor. Startovací sonda spustí sestavený obraz s jeho vlastním vstupním bodem a každou proměnnou, kterou required-env vypíše, nasměrovaný na zástupné služby, které přijímají spojení a nikdy neodpovídají. Server ve svém vymezeném okně čeká na databázi a toto čekání je signálem úspěšného průchodu; zavaděč konfigurace, který odmítne nastartovat, způsobí selhání sestavení tam, a ne v produkci.

Vývoj v edici Community
Vývoj v edici Community
V edici Community získá vývojář stejné zlaté cesty, vývojový prostor a datové větve na jednom serveru, s kódem na vlastním hostiteli Git. Staging, pilotní jednotky a maskované kopie živých dat jsou součástí edice Enterprise.

Kolik to stojí

SDK vám bere rozhodnutí z rukou a některá z nich byste udělali jinak. Manifest odmítá klíče, které nezná, směrovací tabulka musí přesně odpovídat vašemu kódu, databázové role si nenavrhujete sami a kontrolní brány zastaví sestavení kvůli chybějícímu oprávnění při čtení. U svého prvního pluginu jsem strávil den dohadováním s api-contract kvůli cestě, kterou jsem zaregistroval a zapomněl deklarovat. Měl pravdu; cesta nebyla chráněná. Počítejte s tím, že u prvního pluginu budete mít pocit, že to jde pomalu, a že ten druhý vám zabere třetinu času.