Verze 1.0.0-alpha.1nejnovější
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ě

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.0Př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 --writePř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.sqlVygenerovaný 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.sqlSoubor 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.jsonSpouš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.
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.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, což jecreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, což jenexus-gates --self-testnode 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.
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.

