Verzia 1.0.0-alpha.1najnovšia
Kapitola 2.21
Plugin SDK
Inštalácia sady Plugin SDK (sada nástrojov na vývoj softvéru), jej nástroje príkazového riadka, prehliadka šablóny plnohodnotnej služby, manifest v2 pole po poli a dvadsaťdva brán, ktoré dohliadajú na to, aby zásuvný modul dodržiaval pravidlá.
Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

Môj druhý zásuvný modul mi zabral tretinu času oproti prvému a takmer celú túto úsporu priniesla súprava SDK (software development kit). Prvýkrát som napísal kontrolu rozsahu (scope check), zavádzač konfigurácie a spúšťač migrácií a revízor mi každý jeden z nich vrátil späť. Druhýkrát som spustil jeden príkaz na vygenerovanie kostry (scaffold), odstránil ukážkovú zručnosť na analýzu sentimentu a celé dni som venoval záznamom o revízii anomálií, ktoré náš tím letovej dynamiky skutočne potreboval.
@adverant-nexus/plugin-sdk je jeden balík npm. Obsahuje schému manifestu v2 a validátory, ktoré ju čítajú (definePlugin, defineSkill), behové moduly (runtime modules), ktoré váš zásuvný modul importuje pre rozsah (scope), databázu, odosielanie (dispatch) a zvyšok, pomocné nástroje pre testy, kontrolné brány dodržiavania pravidiel (adherence gates) a nástroje príkazového riadka. Táto kapitola sa venuje jeho inštalácii, nástrojom, šablóne, manifestu a kontrolným bránam. Kapitola 2.22, Behové prostredie zásuvného modulu, sa venuje behovým modulom vo vašom spustenom kóde.
Inštalácia
Balík pochádza z registra spoločnosti Adverant na adrese https://registry.adverant.ai/npm/, nikdy nie z verejného registra npm, a potrebujete token na sťahovanie (pull token) zo stránky „Pull tokens and install commands“ vášho účtu. Nasmerujte rozsah @adverant-nexus na register v súbore .npmrc vášho repozitára:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> je token zo stránky vášho účtu. V pipeline ho odovzdajte z tajného úložiska (secret) a nikdy ho neodošlite do repozitára (commit); Dockerfile šablóny sa bez neho odmietne zostaviť a po dobehnutí npm ci odstráni .npmrc z fázy zostavenia, takže token sa nikdy nedostane do obrazu (image).
Potom presne zafixujte verziu:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Pri prvej inštalácii odošlite package-lock.json do repozitára (commit). Zostavenie obrazu šablóny spúšťa npm ci a odmieta sa prepnúť späť na npm install: súbor zámku (lockfile) je zmluva. Samotné minimum súpravy SDK je Node 18; šablóna cieli na Node 20.
Nástroje príkazového riadka sa dodávajú vo vnútri balíka, takže každý príkaz v tejto dokumentácii uvádza názov balíka a jeho verziu pomocou npx -p. Samotný príkaz npx create-nexus-plugin sa vyhľadáva vo verejnom registri a tento názov nepatrí tomuto balíku.
Nástroje príkazového riadka
| Nástroj | Čo robí |
|---|---|
create-nexus-plugin |
Vygeneruje kostru zásuvného modulu, zvaliduje manifest, zmigruje manifest v1 na v2 a vygeneruje príručku spotrebiteľa pre vášho frontendového vývojára |
nexus-tenancy |
Vygeneruje SQL pre viacnásobný prenájom (tenancy) vašej schémy z manifestu: roly, oprávnenia (grants), šablónu zabezpečenia na úrovni riadkov (RLS) a grafové tabuľky |
nexus-migrate |
Aplikuje vaše migrácie: raz zriadi roly a potom spustí každý očíslovaný súbor pod rolou migrátora |
nexus-gates |
Spustí každú kontrolnú bránu dodržiavania pravidiel a vlastný autotest každej brány |
create-nexus-plugin nevykonáva žiadne sieťové volania a nenačítava žiadny vzdialený kód. Spúšťa tie isté interné validátory procesu, ktoré spúšťa aj proces nasadenia (onboarding) platformy, takže nedochádza k žiadnemu posunu medzi „zvalidovalo sa to na mojom stroji“ a „platforma to prijala“.
| Príkaz | Príznaky | Čo robí | Návratové kódy |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Zapíše nový adresár zásuvného modulu; --print vypíše iba manifest |
0 zapísané · 1 odmietnuté prepísanie · 2 nesprávne použitie |
validate <file> |
Zvaliduje nexus.manifest.json, prípadne modul .ts alebo .js, ktorý ho exportuje |
0 platné · 1 neplatné alebo nečitateľné · 2 nesprávne použitie | |
migrate <file> |
--write |
Povýši manifest v1 na v2 a vypíše ho, alebo ho zapíše na pôvodné miesto | 0 · 1 · 2, ako je uvedené vyššie |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Vygeneruje príručku spotrebiteľa z manifestu a vášho sprievodného textu; --check ju porovná s verziou odoslanou v repozitári a nič nezapíše |
0 · 1 odchýlka alebo porušenie pravidiel linteru · 2 nesprávne použitie |
help |
Vypíše návod na použitie | 0 |
Príprava kostry (scaffolding) a tri úrovne
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier má predvolenú hodnotu full-service. Nástroj na generovanie kostry odmietne zapisovať do adresára, ktorý už existuje, a manifest, ktorý zapíše, už prechádza validáciou; nikdy nevygeneruje neplatný manifest.
Vyberte úroveň (tier) podľa toho, čo váš zásuvný modul obsahuje.
| Úroveň | Obsahuje | Musí deklarovať |
|---|---|---|
skills-only |
Zručnosti v manifeste a nič iné | skills[], s aspoň jednou položkou |
ui-only |
Frontendové rozhranie vo vnútri prostredia (shell) | frontend |
full-service |
Backend a frontend, zvyčajne s vlastnou schémou | backend a frontend; a pretože má backend, aj runtime.healthCheck |
Ak si nie ste istí, vygenerujte kostru full-service a odstráňte to, čo nepotrebujete. Opačný postup znamená dopisovať časti, ktoré by vám šablóna poskytla.
Prehliadka šablóny plnohodnotnej služby
Šablóna je referenčný zásuvný modul, zostavený podľa prísneho vzoru, ktorý predpokladá každá ďalšia kapitola. Klonujte jej tvar, nie jej ukážkovú logiku.
| Cesta | Čo to je |
|---|---|
nexus.manifest.json |
Manifest v2: zopakované tri zákony, tabuľka smerovania (route table) a jej register práv |
src/config.ts |
Zavádzač konfigurácie. Jedna špecifikácia, prečítaná raz, všetky problémy zozbierané predtým, než sa proces odmietne spustiť |
src/scope.ts |
Jediný súbor, ktorý mení požiadavku na rozsah (scope), s prísnym overovačom tokenov zo súpravy SDK a dvoma režimami: doručiteľský token (bearer token) osoby a servisné volanie platformy |
src/db.ts |
Každý príkaz skladá tenantFence() a beží vo vnútri withScopedTx |
src/uno.ts |
Jediný súbor odosielania (dispatch): jedna adresa URL, jeden klient, uzavretý zoznam povolených položiek (allow-list) |
src/routes/*.ts |
health (anonymná, presná cesta), trasy /api (s obmedzeným rozsahom) a spätné volanie /internal (chránené službou) |
src/skills/sentiment.ts |
Deterministická zručnosť host_callback; nahraďte lexikón vlastnou logikou |
src/server.ts |
Koreň kompozície: raz nainštaluje účtovnú knihu odmietnutí (refusal ledger), počká na databázu (časovo ohraničené) a pred spustením počúvania vykoná kontroly izolácie a účtovnej knihy |
migrations/000_tenancy.sql |
Vygenerované nástrojom nexus-tenancy render v čase vytvárania kostry: roly, schéma, šablóna zabezpečenia na úrovni riadkov |
migrations/001_init.sql |
Dve tabuľky so zloženým kľúčom začínajúcim nájomcom (tenant) a zloženým cudzím kľúčom nesúcim nájomcu |
migrations/002_refusal_ledger.sql |
Tabuľka, do ktorej zapisuje účtovná kniha odmietnutí |
scripts/ci/required-env |
Vypíše názvy premenných prostredia vyžadovaných pri štarte ako JSON |
scripts/ci/shadow-migrate-*.sh |
Skúšobný beh (dry run) migrácie v pipeline, cez nexus-migrate |
gates/ |
Adresár výnimiek pre kontrolné brány: prázdny, čo je správny stav pre nový zásuvný modul |
test/ |
Testy pre rozsah, trasy, databázu, odosielanie a štart, s dvojníkmi rozsahu (scope doubles), ktorých vstrekuje každý test |
Dockerfile |
Obraz bez oprávnení správcu (non-root, ID používateľa 10001) s migráciami vo vnútri |
Niekoľko z týchto súborov si zaslúži bližší pohľad.
src/config.ts sa riadi dvoma pravidlami. Pred vyvolaním výnimky zozbiera každý problém, takže jeden reštart vymenuje všetkých päť chýbajúcich premenných namiesto piatich reštartov, z ktorých každý pomenuje jednu. A predvolenú hodnotu priradí len vtedy, keď nesprávna hodnota nemôže spôsobiť tichú nesprávnu odpoveď: PORT môže mať predvolenú hodnotu 8080, pretože nesprávny port viditeľne zlyhá pri naviazaní (bind), zatiaľ čo DATABASE_URL a UNO_DISPATCH_URL sú povinné a musia byť adresami v rámci klastra. Verejná adresa je pri štarte odmietnutá.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Vlastný test šablóny spustí tento súbor a porovná jeho výstup s názvami, ktoré špecifikácia konfigurácie označuje ako povinné, takže pridanie povinnej premennej bez aktualizácie zoznamu spôsobí zlyhanie npm test.
src/server.ts nezačne počúvať, kým sa neozve databáza, a čakanie ohraničí na 120 sekúnd, pričom zaznamená každý neúspešný pokus aj s jeho príčinou. Potom v uvedenom poradí preukáže, že aplikačná rola nedokáže premapovať nájomcu a každá tabuľka má vynútené zabezpečenie na úrovni riadkov, že oblasť pripojení (pool) každého podu sa zmestí do limitu pripojení danej roly a že tabuľka účtovnej knihy odmietnutí dokáže prijať riadok. Odmietnutie v ktoromkoľvek z týchto troch bodov sa vypíše v celom rozsahu a proces sa ukončí s kódom 2.
Manifest v2, pole po poli
Manifest je strojovo čitateľná zmluva zásuvného modulu s platformou. Validuje sa, keď ho vytvárate, keď ho platforma nasadzuje (onboarduje) a následne nepretržite. Schéma má nastavené additionalProperties: false na každej úrovni: ak má váš zásuvný modul sekciu, existuje pre ňu vlastnosť, a nedeklarovaný kľúč je odmietnutý. Riešením je vždy použiť správnu voliteľnú vlastnosť.
Povinné jadro
| Pole | Pravidlo |
|---|---|
manifestVersion |
Presne "2". Dokument verzie v1 sa migruje, nikdy sa opätovne nevaliduje na pôvodnom mieste |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, najviac 64 znakov. ID zásuvného modulu používané pri registrácii, menných priestoroch odosielania (dispatch) a riadkoch viazaných na nájomcu. Zásuvný modul, ktorý deklaruje zručnosti, potrebuje aj názov bez bodky a bez úvodnej číslice |
displayName |
1 až 120 znakov |
version |
Sémantická verzia; váš vlastný cyklus vydaní |
description, author, license |
Každá položka aspoň jeden znak |
tier |
skills-only, ui-only alebo full-service |
trust |
core, verified, community alebo untrusted |
runtime |
Povinné: executionMode, isolationLevel (1 až 4), entrypoint. Voliteľné: nodeVersion, healthCheck, readinessCheck, livenessCheck, každá položka je cesta začínajúca znakom /. Režim sa odvodzuje od úrovne: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai a deploy, tri zopakované zákony platformy. Validátor vyžaduje presné znenie |
Pre zásuvný modul, ktorý vytvárate pre svoju vlastnú inštaláciu, znejú tieto tri vety nasledovne. Veta ai pokrýva umelú inteligenciu (AI) a je miestom, kde sa uvádza, že zásuvný modul neuchováva žiadne prihlasovacie údaje modelov.
"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."
}Tabuľka smerovania: api a rights
api vyžaduje version a basePath, a voliteľne websocket (path, auth) a endpoints[]. Tabuľka smerovania je najsilnejšou myšlienkou v schéme: kontrolná brána ju obojsmerne porovnáva s trasami, ktoré váš kód skutočne registruje, takže manifest je kontrolovateľnou zmluvou a nie iba dokumentáciou.
Každý koncový bod vyžaduje method (GET, POST, PUT, PATCH alebo DELETE) a path. Zvyšok:
| Pole | Čo uvádza |
|---|---|
auth |
Jedna z piatich tried: scope (trasa osoby, za strážcom rozsahu), service-key a internal (server na server, nikdy nedosiahnuteľné z prehliadača), public (vždy iba presná cesta s allowAnonymous) a device (stroj s vlastným poverením, za strážcom zariadenia) |
right |
Povinné na každej trase, ktorú obsluhuje strážca rozsahu, a odmietnuté na akejkoľvek inej: názov práva v registri rights |
needsUnit |
Trasa odmietne požiadavku, keď nie je možné vyriešiť jednotku volajúceho |
allowAnonymous |
Iba zoznam povolených položiek s presnou zhodou. Pravidlo prefixu je spôsob, akým sa /health-of-tenant-42 stane verejným |
group, serves, screens |
Pod blokom release: skupina schopností (capability group), ktorú trasa obsluhuje, čo odpovie, keď je licencovaná funkcia danej skupiny uzamknutá (data, teaser, sighting alebo ask), a obrazovky, ktoré obsluhuje |
query |
required (každý názov s ukážkovou hodnotou) a allowed: parametre dopytu, ktoré trasa číta |
body |
example: ukážkové telo trasy pre zápis, také, ktoré jej vlastný validátor prijme. Nikdy nie pri metóde GET |
rights je register, na ktorý sa tieto trasy odvolávajú. Každé právo má roles (strop) a voliteľne summary, never (roly, ktoré ho nikdy nesmú uplatniť, bez ohľadu na to, čo iné majú), barred (vlastné slová produktu pre odmietnutie roly never), seat (je potrebné aj aktívne miesto – live seat), self (má ho každá overená osoba pre práva nad svojou vlastnou reláciou), grants (držitelia udeľujú miesta; uvádza to najviac jedno právo), licence (licencovaná funkcia, ktorú musí obsahovať licencia organizácie) installation (majú ho iba vlastní administrátori inštalácie) a platform (majú ho iba administrátori platformy Adverant; neuvádza žiadne roly). Názvy práv obsahujú aspoň jednu bodku: 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 odmietne trasu rozsahu bez práva (ENDPOINT_RIGHT_MISSING), právo, ktoré v registri chýba (ENDPOINT_RIGHT_NOT_REGISTERED), a právo na trase, ktorú neobsluhuje žiadny strážca (ENDPOINT_RIGHT_UNGUARDED). Taktiež odmietne register, ktorý si protirečí, a dva rôzne zápisy jednej trasy (:id a :recordId) ako DUPLICATE_ENDPOINT.
Vaše údaje: databases, schema a db
schema je jediná schéma databázy Postgres, ktorú zásuvný modul vlastní. Hodnoty public, plugins, auth a nexus sú zakázané, a ak databases[] taktiež uvádza schému databázy Postgres, tieto dve sa musia zhodovať.
databases[] deklaruje každé úložisko podľa enginu: postgresql (schema, tables, migrations a granted, tabuľky, ktoré môže čítať iná organizácia na základe zaznamenaného oprávnenia), neo4j (schemas), qdrant (collections) alebo redis (purpose).
db uchováva limity relácií pre každé pripojenie, ktoré zásuvný modul otvorí; sú deklarované tu a nie v kóde, aby si ich mohol prečítať revízor aj proces nasadenia:
| Pole | Čo ohraničuje |
|---|---|
maxConnections |
Oblasť pripojení (pool) na jednu repliku |
pods |
Najväčší počet podov držiacich oblasť pripojení naraz, teda repliky plus nárazové navýšenie (surge) pri postupnej aktualizácii (rolling update). Limit pripojení každej roly sa vygeneruje ako maxConnections × pods; ak ho vynecháte, definePlugin vypíše varovanie DB_PODS_UNDECLARED |
statementTimeoutMs |
Jeden príkaz |
idleInTransactionTimeoutMs |
Otvorená transakcia, v ktorej nič nebeží |
workMemKB |
Jeden uzol triedenia (sort) alebo hašovania (hash), na uzol, nie na dopyt |
piiMask[] |
Položky table.column obsahujúce osobné údaje, maskované v riadenej konzole SQL a v záznamoch (logoch) |
Zručnosti a nástroje: skills, mcpTools, entitlements
skills[] uchováva zručnosti manifestu; kapitola 2.20, Zručnosti, pokrýva ich polia a úrovne. mcpTools[] uchováva nástroje MCP (Model Context Protocol), ktoré zásuvný modul publikuje, pričom každý má name, description a inputSchema bez oneOf, allOf alebo anyOf na najvyššej úrovni.
entitlements vyžaduje featureIdPattern a prijíma alwaysOn[], source a store. Vzor určuje menný priestor, v ktorom sa nachádzajú vaše identifikátory funkcií, konvenčne name zásuvného modulu plus jeden segment, ktorý váš kód dopĺňa pre každé rozhranie (surface). alwaysOn[] je krátky, presný zoznam, ktorý musí odpovedať, aj keď nie je možné získať verdikt o oprávnení (entitlement): stav zdravia (health), pripravenosť (readiness), prihlásenie a nastavenia, ktoré administrátor potrebuje na opravu oprávnenia.
Riadenie zmien: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Schválenia sa počítajú v rôznych osobách a osoba, ktorá zmenu navrhla, nikdy nie je jednou z nich; bez oboch týchto podmienok sa „dve schválenia“ zmenia na jednu osobu, ktorá klikne dvakrát. enabled: true vyžaduje classes a každá uvedená trieda potrebuje svoj vlastný počet. Trieda, ktorú vynecháte, nie je riadená, čo je legitímna voľba, ktorú vás schéma prinúti zapísať.
Kto ste: domains, branding, routing
domains[] (každá má primary a aliases[]; domain je forma pre jednu doménu) uvádza, kde zásuvný modul odpovedá. branding vyžaduje appName a prijíma tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId a gaId. Všetko v branding je verejné: prihlasovacia stránka to číta skôr, než má ktokoľvek prihlasovacie údaje, takže nikdy neobsahuje tajomstvo ani internú adresu. routing (type, gateway, virtualService) je pre zásuvné moduly, ktoré opisujú svoje vlastné smerovanie.
Dimenzovanie a zvyšok
resources vyžaduje cpuMillicores (10 až 64 000) a memoryMB (16 až 262 144) a prijíma diskGB, timeoutMs, port a wsPort. backend uchováva port, healthPath, apiPrefix, framework a platformClients[], klientov SDK, ktorých váš backend importuje podľa názvu. Zoznam je uzavretý a kontrolná brána ho porovnáva s vašimi importmi. Schéma povoľuje štrnásť názvov: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin a uno, plus jeden pre klienta, ktorý odpovedá na odmietnutia oprávnení plánu, ktorý si ponecháva interný názov. Klient oprávnení funkcií, runtime/entitlements, nie je jedným z nich a nikdy sa do zoznamu nezapisuje, pretože ho už deklaruje váš blok entitlements, a backend, ktorý ho importuje bez bloku entitlements, neprejde tou istou kontrolnou bránou. frontend uchováva basePath, mountPath a framework. nexus uchováva minVersion, maxVersion, capabilities[] a permissions[].
Zostávajúce bloky sú tam každý na jednu úlohu:
| Blok | Účel |
|---|---|
settings |
Vaše nastavenia na zdieľanom frameworku: groups a keys, nastavené na úrovniach, ktoré každé z nich menuje |
people |
sweep (service, port): členovia organizácie, synchronizovaní zo služby identity, s vypnutím miest (seats), keď niekto odíde |
ontology |
entityTypes a relationshipTypes: typovaný graf udržiavaný vo vašej vlastnej schéme |
release |
groups a frame: skupiny schopností, v ktorých sú vaše trasy fázované, vydávané najprv ako kanárikové nasadenie (canary) |
cells[] |
Zásuvný modul, ktorý pozostáva z niekoľkých nasaditeľných celkov (deployables): každý má name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] pre váš záznam v katalógu |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Kto ho publikuje a kde sa nachádza jeho kód |
metrics, atlas |
Dva zámerne otvorené objekty pre vaše vlastné názvy metrík a generovanie dokumentácie architektúry |
Čo schéma nedokáže vyjadriť
Schéma JSON určuje tvar; definePlugin pridáva pravidlá, ktoré schéma nedokáže vyjadriť. Hodnota classification zručnosti nemôže prekročiť strop dôveryhodnosti. Iba zásuvné moduly core a verified môžu deklarovať zručnosti tool_using a llm_only. Každá deklarovaná cesta musí byť relatívna a rovnakého pôvodu (same-origin), bez schémy, bez // a bez spätného lomítka, pretože analyzátor URL prevádza \ na / a /\evil.example/x sa vyhodnotí ako cudzí pôvod (cross-origin). Každé pravidlo, ktoré synchronizácia registra uplatňuje na zručnosť, sa uplatní najprv tu, s vlastným kódom synchronizácie, takže validate a synchronizácia pomenujú porušené pravidlo rovnakým spôsobom.
Validácia a prechod z verzie 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
Zlyhanie vypíše presnú cestu a v prípade pravidla synchronizácie najprv kód. Urobte z toho háčik odoslania (commit hook).
Manifest v1 sa povýši mechanicky. migrate pridá tri vety zákonov, presunie domain do domains[] a odmietne si vymyslieť vstupný bod, ktorý ste nemali. Pred vypísaním alebo zapísaním čohokoľvek zvaliduje výsledok, takže migrácia nikdy nepresunie chybu z nástroja do vášho repozitára.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writePred odoslaním do repozitára (commit) si prečítajte rozdiely (diff). Vety zákonov, ktoré pridáva, sú znením, ktoré vyžaduje validátor; pre svoju vlastnú inštaláciu nastavte deploy na vetu uvedenú vyššie.
Vykreslenie tenanta a zriadenie rolí
Oprávnenia rolí ani šablónu zabezpečenia na úrovni riadkov nikdy nepíšete ručne. nexus-tenancy render ich zapíše z položiek schema a db v manifeste:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlVygenerovaný súbor vytvorí pre schému päť rolí, každú s tým, čo nesmie mať: migrátora, ktorý sa môže stať iba vlastníkom, vlastníka, ktorý sa nemôže prihlásiť, aplikačnú rolu pre cestu požiadavky, reportovaciu rolu, ktorá vidí iba agregáty, a rolu účtovnej knihy (ledger), ktorá môže iba pridávať záznamy. Žiadna rola nemá BYPASSRLS. Jediný spôsob, ako naviazať nájomcu, je jedna databázová funkcia a set_config je odobraté každej role okrem vlastníka.
Aplikovaný súbor viacnásobného prenájmu (tenancy) sa nikdy neupravuje. Zmena je revíziou s vlastným súborom s číslom 0 a miesto na čítanie (read seat) pre oprávnenia medzi organizáciami prichádza týmto spôsobom ako revízia 2. --graph vygeneruje dve tabuľky typovaného grafu, ktoré deklaruje váš ontology, ako vašu ďalšiu očíslovanú migráciu.
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.sqlSúbor viacnásobného prenájmu vytvára práve tie roly, pod ktorými sa spúšťač pripája, takže ho aplikuje vlastník databázy pomocou 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 pripojovací reťazec pre vlastníka databázy a <dir> je súkromný adresár. Zriadenie (provision) aplikuje základný súbor viacnásobného prenájmu a každú revíziu v príslušnom poradí, zapíše migrator.url a app.url (a seat.url, keď už existuje revízia 2) do <dir> s režimom 0600 a nevypíše nič tajné. Pri každom behu nastaví limit pripojení každej roly z db.maxConnections × db.pods. Opätovné spustenie zachová existujúce heslá, pokiaľ nepožiadate o zmenu: --passwords <dir> ich nastaví zo súborov a --rotate <roles> pridelí uvedeným rolám nové heslá. Premeňte tieto súbory na tajomstvá (secrets) vášho nasadenia.
Potom sa aplikovanie migrácií pripojí pomocou pripojovacieho reťazca migrátora, ktorý zapísalo zriadenie:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonSpúšťa súbory od 001 ďalej ako migrátor, každý súbor pod SET ROLE <schema>_owner, jedna transakcia na súbor. Udržiava účtovnú knihu, <schema>.schema_migrations, s kontrolným súčtom každého súboru; aplikovaný súbor, ktorého bajty sa zmenili, je odmietnutý podľa názvu (CHECKSUM_DRIFT), nikdy sa nespustí znova a nikdy sa nepreskočí. Každý čakajúci súbor je pred spustením prvého z nich analyzovaný skutočnou gramatikou databázy Postgres, takže odmietnutie ponechá databázu nedotknutú. Jediná hlavička, ktorú môže súbor niesť, je -- nexus-migration: transaction=file|per-statement, s voliteľnými časovými limitmi zámku a príkazu; per-statement je pre CREATE INDEX CONCURRENTLY.
Brány
nexus-gates spúšťa dvadsaťdva kontrolných brán. Každá kóduje jednu triedu chýb, aby sa nemohla nasadiť dvakrát, a každá má autotest, ktorý dokazuje, že zlyhá na testovacej vzorke (fixture) zostavenej tak, aby ju spustila. Spustite ich pred odoslaním zmien (push):
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Kontrolná brána | Čo zachytáva |
|---|---|
scope-adherence |
Trasu /api bez strážcu rozsahu; anonymnú cestu, ktorá nie je presne deklarovanou cestou; trasu zariadenia bez strážcu zariadenia alebo so strážcom osoby vedľa neho |
one-fence |
Predikát nájomcu definovaný kdekoľvek inde ako na jednom mieste, vrátane ručne napísaného ohraničenia (fence) miesta alebo oprávnenia |
sql-fence |
Príkaz čítajúci alebo aktualizujúci tabuľku s obmedzeným rozsahom bez ohraničenia, v akomkoľvek cieli FROM, JOIN, USING alebo UPDATE |
migrations-are-scoped |
Tabuľku, ktorej chýba os, zložený kľúč začínajúci nájomcom, cudzí kľúč nesúci nájomcu alebo stĺpec demo |
migrations-commit-what-they-open |
Migráciu, ktorej počet BEGIN sa nezhoduje s jej počtom COMMIT a ROLLBACK |
no-direct-compute |
Priame volanie poskytovateľa modelu, enginu, frontu alebo hostiteľa pracovných postupov (workflow); druhého čitateľa adresy URL odosielania (dispatch) |
no-credentials |
Prihlasovacie údaje poskytovateľa modelu čitateľné v repozitári alebo v prostredí |
crud-adherence |
Modifikujúcu trasu, ktorej kontrola práv neuvádza nič z registra |
blocked-backends |
Trasu, ktorá nie je ani obsluhovaná, ani blokovaná podľa názvu, ani odmietnutá zo zákona, ani vlastnená niekde inde |
every-test-runs |
Testy, na ktoré vzor (glob) testovacieho skriptu nikdy nedosiahne |
tiles-are-invariant |
Spoj (seam) vo vyrovnávacej pamäti nemenný voči nájomcovi, ktorý číta hodnotu nájomcu alebo preskakuje autentifikáciu |
api-contract |
Zaregistrovanú trasu, ktorú manifest nedeklaruje, alebo deklarovanú trasu, ktorú kód nikdy nezaregistruje |
rls-present |
Tabuľku bez vynúteného zabezpečenia na úrovni riadkov; funkciu SECURITY DEFINER bez zafixovanej search_path |
no-set-config |
Kód zásuvného modulu, ktorý si sám nastavuje väzbu nájomcu |
db-role-honest |
Cestu požiadavky pripájajúcu sa ako vlastník alebo migrátor, alebo žiadajúcu o SUPERUSER či BYPASSRLS |
platform-clients |
Klienta SDK, ktorý je importovaný, ale nie je uvedený v backend.platformClients, alebo je uvedený, ale nikdy nie je importovaný |
rights-register |
Trasu rozsahu bez deklarovaného práva; kontrolu práva mimo registra |
refusal-ledger |
Deklarovanú tabuľku odmietnutí bez nainštalovanej účtovnej knihy, alebo telo odmietnutia odoslané mimo nej |
grants-declared |
Tabuľku s udeleným oprávnením, ktorú manifest nedeklaruje; privilégiá miesta na čítanie (read-seat) rozdané ručne |
people-declared |
Blok people bez jeho čistiacej trasy (sweep route), strážcu a tabuliek |
functions-closure |
Zásuvný modul Azure Functions, ktorého obsluhované trasy a deklarované trasy sa nezhodujú |
declared-input |
Zoznam parametrov dopytu obslužnej rutiny (handler), ktorý sa nezhoduje s deklarovaným query trasy |
Adresár gates/ uchováva päť súborov výnimiek, ktoré môže kontrolná brána čítať (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json a invariant-seams.json), jeden dôvod na položku. Prázdny dôvod sa počíta ako žiadna položka a položka pomenúvajúca niečo, čo už neexistuje, spôsobí zlyhanie kontrolnej brány. Môžete tam tiež vložiť svoje vlastné moduly kontrolných brán a nexus-gates ich načíta popri tých vstavaných.
Potrubie (pipeline) šablóny
Šablóna nedodáva žiadny ručne písaný pracovný postup (workflow). Jej konfigurácia pipeline menuje Dockerfile, jediný argument zostavenia (token registra), skúšobný beh migrácie a sondu štartu, a kontrolnú bránu, ktorú spúšťa front zlučovania (merge queue). Poradie zodpovedá poradiu, v akom by ste chceli zachytiť prípadné zlyhanie.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, čo jecreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, čo jenexus-gates --self-testnode scripts/ci/required-env
Okolo obrazu bežia ešte dve kontroly. Skúšobný beh migrácie aplikuje každý súbor na jednorazový Postgres predtým, než môže byť obraz vydaný, s tým istým spúšťačom, aký používa produkcia: nexus-migrate provision raz ako superpoužívateľ, potom každý očíslovaný súbor ako migrátor. Štartovacia sonda spustí zostavený obraz s jeho vlastným vstupným bodom a každou premennou, ktorú required-env vypíše, nasmerovaný na náhrady, ktoré prijímajú spojenia a nikdy neodpovedajú. Server čaká na databázu v rámci svojho ohraničeného okna a toto čakanie je signálom úspešného prechodu; zavádzač konfigurácie, ktorý odmietne naštartovať, zhodí zostavenie tam a nie v produkcii.
Koľko to stojí
SDK vám berie rozhodnutia z rúk a niektoré z nich by ste urobili inak. Manifest odmieta kľúče, ktoré nepozná, tabuľka smerovania sa musí presne zhodovať s vaším kódom, databázové roly nenavrhujete vy a kontrolné brány zhodia zostavenie pre chýbajúce oprávnenie pri čítaní. Pri mojom prvom zásuvnom module som strávil deň dohadovaním sa s api-contract o trase, ktorú som zaregistroval a zabudol deklarovať. Mal pravdu; trasa bola nechránená. Očakávajte, že prvý zásuvný modul sa bude zdať pomalý, a očakávajte, že ten druhý zaberie tretinu času.

