Verzija 1.0.0-alpha.1najnovije
Poglavlje 2.21
Plugin SDK
Instaliranje kompleta Plugin SDK (komplet za razvoj softvera), njegovih alatki komandne linije, pregled šablona za kompletan servis, v2 manifest polje po polje i dvadeset dve kapije koje primoravaju plugin da poštuje pravila.
Ovu stranicu je sa engleskog originala prevela AI tehnologija. Ako nešto nije jasno, merodavna je stranica na engleskom. Pročitajte ovu stranicu na engleskom

Za moj drugi dodatak bila mi je potrebna trećina vremena koje mi je bilo potrebno za prvi, a gotovo sva ušteda potiče od SDK-a (komplet za razvoj softvera). Prvi put sam napisao proveru opsega, učitavač konfiguracije i pokretač migracija, a recenzent mi je vratio svaki od njih. Drugi put sam pokrenuo jednu komandu za generisanje kostura, obrisao primer veštine za analizu sentimenta i dane proveo na zapisima o pregledu anomalija koji su našem timu za dinamiku leta zaista bili potrebni.
@adverant-nexus/plugin-sdk je jedan npm paket. Sadrži šemu manifesta v2 i validatore koji je čitaju (definePlugin, defineSkill), runtime module koje Vaš dodatak uvozi za opseg, bazu podataka, prosleđivanje i ostalo, pomoćne alate za testiranje, kapije usklađenosti i alate komandne linije. Ovo poglavlje obuhvata njegovu instalaciju, alate, šablon, manifest i kapije. Poglavlje 2.22, Runtime dodatka, obuhvata runtime module u Vašem pokrenutom kodu.
Instaliranje
Paket dolazi iz Adverant registra na adresi https://registry.adverant.ai/npm/, nikada iz javnog npm registra, a potreban Vam je token za preuzimanje sa stranice „Pull tokens and install commands“ Vašeg naloga. Usmerite opseg @adverant-nexus na registar u datoteci .npmrc Vašeg repozitorijuma:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> je token sa stranice Vašeg naloga. U pipeline-u ga prosledite iz tajne i nikada ga ne komitujte; Dockerfile iz šablona odbija da izgradi sliku bez njega i briše .npmrc iz faze izgradnje nakon što se npm ci izvrši, tako da token nikada ne dospeva u sliku.
Zatim tačno fiksirajte verziju:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Komitujte package-lock.json pri prvoj instalaciji. Izgradnja slike iz šablona pokreće npm ci i odbija da se vrati na npm install: lockfile je ugovor. Minimalna verzija za sam SDK je Node 18; šablon cilja Node 20.
Alati komandne linije isporučuju se unutar paketa, pa svaka komanda u ovoj dokumentaciji navodi paket i njegovu verziju pomoću npx -p. Samostalno, npx create-nexus-plugin se traži u javnom registru, a to ime ne označava ovaj paket.
Alati komandne linije
| Alat | Šta radi |
|---|---|
create-nexus-plugin |
Generiše kostur dodatka, validira manifest, migrira manifest v1 na v2 i generiše vodič za korisnike za Vašeg frontend programera |
nexus-tenancy |
Generiše SQL za zakupce Vaše šeme iz manifesta: uloge, dozvole, šablon bezbednosti na nivou redova i tabele grafa |
nexus-migrate |
Primenjuje Vaše migracije: jednom obezbeđuje uloge, a zatim pokreće svaku numerisanu datoteku kao uloga migratora |
nexus-gates |
Pokreće svaku kapiju usklađenosti i samotest svake kapije |
create-nexus-plugin ne upućuje nijedan mrežni poziv i ne učitava udaljeni kod. Pokreće iste validatore unutar procesa koje pokreće i uvođenje na platformi, tako da nema odstupanja između „validiralo se na mom računaru“ i „platforma je to prihvatila“.
| Komanda | Opcije | Šta radi | Izlazni kodovi |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Kreira novi direktorijum dodatka; --print ispisuje samo manifest |
0 upisano · 1 odbijeno prepisivanje · 2 neispravna upotreba |
validate <file> |
Validira nexus.manifest.json ili .ts ili .js modul koji ga izvozi |
0 ispravno · 1 neispravno ili nečitljivo · 2 neispravna upotreba | |
migrate <file> |
--write |
Podiže manifest v1 na v2 i ispisuje ga ili ga upisuje na mestu | 0 · 1 · 2, kao gore |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Generiše vodič za korisnike iz manifesta i Vašeg opisnog teksta; --check poredi sa komitovanom kopijom i ništa ne upisuje |
0 · 1 odstupanje ili prekršaj lint provere · 2 neispravna upotreba |
help |
Ispisuje uputstvo za upotrebu | 0 |
Generisanje osnove (scaffolding) i tri nivoa
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier podrazumevano ima vrednost full-service. Generator kostura odbija da upisuje u direktorijum koji postoji, a manifest koji upisuje već prolazi validaciju; nikada ne generiše neispravan manifest.
Nivo izaberite prema tome šta Vaš dodatak sadrži.
| Nivo | Sadrži | Mora da deklariše |
|---|---|---|
skills-only |
Samo veštine iz manifesta | skills[], sa najmanje jednim unosom |
ui-only |
Frontend površinu unutar okruženja | frontend |
full-service |
Backend i frontend, obično sa sopstvenom šemom | backend i frontend; a pošto ima backend, i runtime.healthCheck |
Ako niste sigurni, generišite kostur full-service i obrišite ono što Vam nije potrebno. Obrnuti put znači da sami pišete delove koje bi Vam šablon obezbedio.
Obilazak šablona za puni servis
Šablon je referentni dodatak, izgrađen po strogom obrascu koji pretpostavlja svako naredno poglavlje. Preuzmite njegov oblik, a ne njegovu primernu logiku.
| Putanja | Šta je to |
|---|---|
nexus.manifest.json |
Manifest v2: ponovo navedena tri zakona, tabela ruta i njen registar prava |
src/config.ts |
Učitavač konfiguracije. Jedna specifikacija, pročitana jednom, svaki problem prikupljen pre nego što proces odbije da se pokrene |
src/scope.ts |
Jedina datoteka koja pretvara zahtev u opseg, sa strogim verifikatorom tokena iz SDK-a i dva režima: bearer token osobe i servisni poziv platforme |
src/db.ts |
Svaka naredba sastavlja tenantFence() i izvršava se unutar withScopedTx |
src/uno.ts |
Jedina datoteka za prosleđivanje: jedan URL, jedan klijent, zatvorena lista dozvoljenih |
src/routes/*.ts |
health (anonimno, tačna putanja), rute /api (sa opsegom) i povratni poziv /internal (zaštićen servisnom zaštitom) |
src/skills/sentiment.ts |
Deterministička veština host_callback; zamenite leksikon sopstvenom logikom |
src/server.ts |
Koren kompozicije: jednom instalira evidenciju odbijanja, čeka bazu podataka (ograničeno), a zatim pokreće provere izolacije i evidencije pre nego što počne da osluškuje |
migrations/000_tenancy.sql |
Generiše ga nexus-tenancy render u trenutku generisanja kostura: uloge, šema, šablon bezbednosti na nivou redova |
migrations/001_init.sql |
Dve tabele sa složenim ključem koji počinje zakupcem i složenim stranim ključem koji nosi zakupca |
migrations/002_refusal_ledger.sql |
Tabela u koju upisuje evidencija odbijanja |
scripts/ci/required-env |
Ispisuje nazive promenljivih okruženja obaveznih za pokretanje u JSON formatu |
scripts/ci/shadow-migrate-*.sh |
Probno izvršavanje migracija u pipeline-u, preko nexus-migrate |
gates/ |
Direktorijum izuzeća za kapije: prazan, što je ispravno stanje za novi dodatak |
test/ |
Testovi za opseg, rute, bazu podataka, prosleđivanje i pokretanje, sa zamenskim opsezima koje ubacuje svaki test |
Dockerfile |
Slika koja se ne pokreće kao root (korisnički ID 10001), sa migracijama unutar nje |
Nekoliko tih datoteka zaslužuje detaljniji pogled.
src/config.ts sledi dva pravila. Prikuplja svaki problem pre nego što baci izuzetak, tako da jedno ponovno pokretanje navodi svih pet nedostajućih promenljivih umesto pet ponovnih pokretanja koja navode po jednu. I dodeljuje podrazumevanu vrednost samo kada pogrešna vrednost ne može da proizvede tihi pogrešan odgovor: PORT može podrazumevano imati vrednost 8080, jer pogrešan port vidljivo onemogućava povezivanje, dok su DATABASE_URL i UNO_DISPATCH_URL obavezni i moraju biti adrese unutar klastera. Javna adresa se odbija pri pokretanju.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Sopstveni test šablona pokreće tu datoteku i poredi njen izlaz sa nazivima koje specifikacija konfiguracije označava kao obavezne, tako da dodavanje obavezne promenljive bez ažuriranja liste dovodi do neuspeha npm test.
src/server.ts ne počinje da osluškuje dok baza podataka ne odgovori, a čekanje ograničava na 120 sekundi, beležeći svaki neuspeli pokušaj sa njegovim uzrokom. Zatim redom dokazuje da uloga aplikacije ne može ponovo da veže zakupca i da je svaka tabela prinudno pod bezbednošću na nivou redova, da se skup konekcija svakog poda uklapa u ograničenje konekcija uloge i da tabela evidencije odbijanja može da primi red. Odbijanje bilo koje od te tri provere ispisuje se u celosti i proces se završava sa kodom 2.
Manifest v2, polje po polje
Manifest je mašinski čitljiv ugovor dodatka sa platformom. Validira se kada ga pišete, kada ga platforma uvodi i kontinuirano nakon toga. Šema je additionalProperties: false na svakom nivou: ako Vaš dodatak ima odeljak, za njega postoji svojstvo, a nedeklarisani ključ se odbija. Rešenje je uvek da koristite odgovarajuće opciono svojstvo.
Obavezno jezgro
| Polje | Pravilo |
|---|---|
manifestVersion |
Tačno "2". Dokument v1 se migrira, nikada se ne validira ponovo na mestu |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, najviše 64 znaka. ID dodatka koji se koristi pri registraciji, za imenske prostore prosleđivanja i u redovima vezanim za zakupca. Dodatku koji deklariše veštine potreban je i naziv bez tačke i bez cifre na početku |
displayName |
Od 1 do 120 znakova |
version |
Semantička verzija; Vaš sopstveni ciklus izdanja |
description, author, license |
Najmanje po jedan znak |
tier |
skills-only, ui-only ili full-service |
trust |
core, verified, community ili untrusted |
runtime |
Obavezno: executionMode, isolationLevel (od 1 do 4), entrypoint. Opciono: nodeVersion, healthCheck, readinessCheck, livenessCheck, svaka putanja koja počinje sa /. Režim se izvodi iz nivoa: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai i deploy, ponovo navedena tri zakona platforme. Validator fiksira formulaciju |
Za dodatak koji pravite za sopstvenu instalaciju, tri rečenice glase ovako. Rečenica ai obuhvata veštačku inteligenciju (AI) i predstavlja mesto gde se navodi da dodatak ne čuva akreditive modela.
"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."
}Tabela ruta: api i rights
api zahteva version i basePath, a opciono websocket (path, auth) i endpoints[]. Tabela ruta je najsnažnija ideja u šemi: kapija je poredi sa rutama koje Vaš kod zaista registruje, u oba smera, tako da je manifest proverljiv ugovor, a ne dokumentacija.
Svakoj krajnjoj tački potrebni su method (GET, POST, PUT, PATCH ili DELETE) i path. Ostalo:
| Polje | Šta navodi |
|---|---|
auth |
Jedna od pet klasa: scope (ruta osobe, iza zaštite opsega), service-key i internal (od servera do servera, nikada dostupne iz pregledača), public (uvek isključivo tačna putanja sa allowAnonymous) i device (mašina sa sopstvenim akreditivom, iza zaštite uređaja) |
right |
Obavezno na svakoj ruti koju opslužuje zaštita opsega, a odbija se na svakoj drugoj: naziv prava u registru rights |
needsUnit |
Ruta odbija zahtev kada organizaciona jedinica pozivaoca ne može da se utvrdi |
allowAnonymous |
Isključivo lista dozvoljenih sa tačnim podudaranjem. Pravilo sa prefiksom je način na koji /health-of-tenant-42 postaje javno |
group, serves, screens |
U okviru bloka release: grupa mogućnosti koju ruta opslužuje, šta odgovara kada je licencirana funkcija te grupe zaključana (data, teaser, sighting ili ask) i ekrani koje opslužuje |
query |
required (svaki naziv sa primerom vrednosti) i allowed: parametri upita koje ruta čita |
body |
example: primer tela zahteva za rutu upisa, koji prihvata njen sopstveni validator. Nikada na GET |
rights je registar koji te rute navode. Svako pravo ima roles (gornju granicu) i opciono summary, never (uloge koje ga nikada ne smeju koristiti, bez obzira na to šta još imaju), barred (sopstvene reči proizvoda za odbijanje uloge never), seat (potrebno je i aktivno mesto), self (ima ga svaka verifikovana osoba, za prava nad sopstvenom sesijom), grants (nosioci dodeljuju mesta; najviše jedno pravo to navodi), licence (licencirana funkcija koju licenca organizacije mora da sadrži) installation (imaju ga samo administratori same instalacije) i platform (imaju ga samo administratori Adverant platforme; ne navodi nijednu ulogu). Nazivi prava imaju najmanje jednu tač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 odbija rutu sa opsegom bez prava (ENDPOINT_RIGHT_MISSING), pravo koje ne postoji u registru (ENDPOINT_RIGHT_NOT_REGISTERED) i pravo na ruti koju ne opslužuje nijedna zaštita (ENDPOINT_RIGHT_UNGUARDED). Takođe odbija registar koji je sam sebi kontradiktoran, kao i dva zapisa iste rute (:id i :recordId) kao DUPLICATE_ENDPOINT.
Vaši podaci: databases, schema i db
schema je jedina Postgres šema čiji je vlasnik dodatak. public, plugins, auth i nexus su zabranjeni, a ako i databases[] navodi Postgres šemu, te dve moraju da se poklapaju.
databases[] deklariše svako skladište prema mašini za skladištenje: postgresql (schema, tables, migrations i granted, tabele koje druga organizacija može da čita na osnovu evidentirane dozvole), neo4j (schemas), qdrant (collections) ili redis (purpose).
db sadrži ograničenja sesije za svaku konekciju koju dodatak otvara, deklarisana ovde umesto u kodu kako bi ih i recenzent i implementacija mogli pročitati:
| Polje | Šta ograničava |
|---|---|
maxConnections |
Skup konekcija po replici |
pods |
Najveći broj podova koji istovremeno drže skup konekcija, replike plus višak pri postepenom ažuriranju. Ograničenje konekcija svake uloge generiše se kao maxConnections × pods; ako ga izostavite, definePlugin upozorava DB_PODS_UNDECLARED |
statementTimeoutMs |
Jednu naredbu |
idleInTransactionTimeoutMs |
Otvorenu transakciju koja ništa ne izvršava |
workMemKB |
Jedan čvor sortiranja ili heširanja, po čvoru, a ne po upitu |
piiMask[] |
Unosi table.column koji sadrže lične podatke, maskirani u kontrolisanoj SQL konzoli i u logovima |
Veštine i alati: skills, mcpTools, entitlements
skills[] sadrži veštine iz manifesta; poglavlje 2.20, Veštine, obuhvata njihova polja i nivoe. mcpTools[] sadrži MCP (Model Context Protocol) alate koje dodatak objavljuje, svaki sa name, description i inputSchema bez oneOf, allOf ili anyOf na najvišem nivou.
entitlements zahteva featureIdPattern i prihvata alwaysOn[], source i store. Obrazac navodi imenski prostor u kom se nalaze ID-jevi Vaših funkcija, po konvenciji name dodatka plus jedan segment koji Vaš kod popunjava za svaku površinu. alwaysOn[] je kratka, tačna lista koja mora da odgovara čak i kada nije moguće dobiti nikakvu odluku o pravu korišćenja: provera stanja, spremnost, prijava i podešavanja koja su administratoru potrebna da popravi pravo korišćenja.
Kontrola izmena: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Odobrenja se broje po različitim osobama, a osoba koja je predložila izmenu nikada nije jedna od njih; bez obe polovine, „dva odobrenja“ postaju jedna osoba koja klikne dvaput. enabled: true zahteva classes, a svakoj navedenoj klasi potreban je sopstveni broj. Klasa koju izostavite nije pod kontrolom, što je legitiman izbor koji Vas šema primorava da zapišete.
Ko ste: domains, branding, routing
domains[] (svaki sa primary i aliases[]; domain je oblik za jedan domen) navodi gde dodatak odgovara. branding zahteva appName i prihvata tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId i gaId. Sve u branding je javno: stranica za prijavu to čita pre nego što iko ima akreditiv, tako da nikada ne sadrži tajnu ili internu adresu. routing (type, gateway, virtualService) je namenjen dodacima koji opisuju sopstveno rutiranje.
Dimenzionisanje i ostalo
resources zahteva cpuMillicores (10 do 64,000) i memoryMB (16 do 262,144), a prihvata diskGB, timeoutMs, port i wsPort. backend sadrži port, healthPath, apiPrefix, framework i platformClients[], SDK klijente koje Vaš backend uvozi po imenu. Lista je zatvorena, a jedna provera je upoređuje sa Vašim uvozima. Šema dozvoljava četrnaest imena: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin i uno, plus jedno za klijenta koji odgovara na odbijanja zbog prava iz plana, a koji zadržava interno ime. Klijent za prava na funkcionalnosti, runtime/entitlements, nije jedan od njih i nikada se ne stavlja na listu, jer ga Vaš blok entitlements već deklariše, a backend koji ga uvozi bez bloka entitlements pada na istoj proveri. frontend sadrži basePath, mountPath i framework. nexus sadrži minVersion, maxVersion, capabilities[] i permissions[].
Svaki od preostalih blokova postoji radi jednog zadatka:
| Blok | Namena |
|---|---|
settings |
Vaša podešavanja na zajedničkom okviru: groups i keys, postavljena na nivoima koje svako od njih navodi |
people |
sweep (service, port): članovi organizacije, sinhronizovani iz servisa za identitet, pri čemu se licence isključuju kada neko ode |
ontology |
entityTypes i relationshipTypes: tipizovani graf koji se čuva u Vašoj sopstvenoj šemi |
release |
groups i frame: grupe mogućnosti u kojima se Vaše rute postepeno uvode, najpre objavljene kao canary |
cells[] |
Plugin koji se sastoji od više jedinica za isporuku: name, kind, entrypoint, port, wsPort za svaku |
pricing |
model, currency, tiers[] za Vaš unos u katalogu |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Ko ga objavljuje i gde se nalazi njegov kod |
metrics, atlas |
Dva namerno otvorena objekta, za Vaša sopstvena imena metrika i generisanje dokumentacije o arhitekturi |
Šta šema ne može da izrazi
JSON Schema određuje oblik; definePlugin dodaje pravila koja šema ne može da izrazi. Vrednost classification neke veštine ne može da premaši gornju granicu poverenja. Samo core i verified pluginovi smeju da deklarišu veštine tool_using i llm_only. Svaka deklarisana putanja mora biti relativna i istog porekla, bez šeme, bez // i bez obrnute kose crte, jer URL parser pretvara \ u /, a /\evil.example/x se razrešava na drugo poreklo. Svako pravilo koje sinhronizacija registra primenjuje na veštinu ovde se primenjuje prvo, sa sopstvenim kodom sinhronizacije, tako da validate i sinhronizacija prekršeno pravilo imenuju na isti način.
Validacija i prelazak sa verzije 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
Greška ispisuje tačnu putanju, a za pravilo sinhronizacije najpre kod. Podesite to kao commit hook.
Manifest verzije v1 prevodi se mehanički. migrate dodaje tri rečenice o pravilima, premešta domain u domains[] i odbija da izmisli ulaznu tačku koju niste imali. Rezultat validira pre nego što bilo šta ispiše ili upiše, tako da migracija nikada ne prenosi grešku iz alata u Vaš repozitorijum.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writePročitajte diff pre nego što ga commit-ujete. Rečenice o pravilima koje dodaje predstavljaju formulaciju koju validator fiksira; za sopstvenu instalaciju postavite deploy na rečenicu prikazanu ranije.
Generisanje zakupaca (tenancy) i priprema uloga
Dodele uloga ni šablon za bezbednost na nivou redova nikada ne pišete ručno. nexus-tenancy render ih piše na osnovu schema i db iz manifesta:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlGenerisana datoteka kreira pet uloga za šemu, svaku sa onim što ne sme da poseduje: migrator koji može samo da postane vlasnik, vlasnika koji ne može da se prijavi, aplikacionu ulogu za putanju zahteva, ulogu za izveštaje koja vidi samo agregate i ulogu za knjigu evidencije koja može samo da dodaje. Nijedna uloga ne poseduje BYPASSRLS. Jedini način da se veže tenant jeste jedna funkcija baze podataka, a set_config je oduzet svim ulogama osim vlasnika.
Primenjena datoteka za tenancy se nikada ne menja. Izmena je revizija sa sopstvenom datotekom broj 0, a mesto za čitanje za dodele između organizacija stiže na taj način, kao revizija 2. --graph generiše dve tabele tipizovanog grafa koji Vaš ontology deklariše kao Vašu sledeću numerisanu migraciju.
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.sqlDatoteka za tenancy kreira upravo one uloge kao koje se izvršilac povezuje, pa je primenjuje vlasnik baze podataka pomoću 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 connection string za vlasnika baze podataka, a <dir> je privatni direktorijum. Provision primenjuje osnovnu datoteku za tenancy i svaku reviziju redom, upisuje migrator.url i app.url (i seat.url kada postoji revizija 2) u <dir> sa režimom 0600 i ne ispisuje ništa tajno. Pri svakom pokretanju postavlja ograničenje konekcija za svaku ulogu na osnovu db.maxConnections × db.pods. Ponovno pokretanje zadržava postojeće lozinke osim ako ne zatražite drugačije: --passwords <dir> ih postavlja iz datoteka, a --rotate <roles> navedenim ulogama dodeljuje nove. Pretvorite datoteke u tajne Vašeg okruženja za isporuku.
Nakon toga, primena se povezuje pomoću migratorovog connection stringa koji je provision upisao:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonIzvršava datoteke od 001 nadalje kao migrator, svaku datoteku pod SET ROLE <schema>_owner, jednu transakciju po datoteci. Vodi knjigu evidencije, <schema>.schema_migrations, sa kontrolnim zbirom svake datoteke; primenjena datoteka čiji su se bajtovi promenili odbija se po imenu (CHECKSUM_DRIFT), nikada se ne izvršava ponovo i nikada se ne preskače. Svaka datoteka na čekanju parsira se pravom Postgres gramatikom pre nego što se prva izvrši, tako da odbijanje ostavlja bazu podataka netaknutom. Jedino zaglavlje koje datoteka sme da nosi je -- nexus-migration: transaction=file|per-statement, sa opcionim vremenskim ograničenjima za zaključavanje i naredbe; per-statement je za CREATE INDEX CONCURRENTLY.
Kontrolne kapije
nexus-gates pokreće dvadeset dve provere. Svaka kodira jednu klasu defekata kako ne bi mogla da bude isporučena dvaput, i svaka ima samotest koji dokazuje da pada na fixture-u napravljenom da je okine. Pokrenite ih pre nego što uradite push:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Provera | Šta otkriva |
|---|---|
scope-adherence |
/api rutu bez zaštite opsega; anonimnu putanju koja nije tačno deklarisana; rutu za uređaj bez zaštite za uređaj ili sa zaštitom za osobu pored nje |
one-fence |
Predikat za tenant definisan bilo gde osim na jednom mestu, uključujući ručno napravljenu ogradu za licencu ili dodelu |
sql-fence |
Naredbu koja čita ili ažurira tabelu sa opsegom bez ograde, u bilo kom FROM, JOIN, USING ili UPDATE cilju |
migrations-are-scoped |
Tabelu kojoj nedostaje osa, složeni ključ koji počinje tenantom, strani ključ koji nosi tenant ili demo kolona |
migrations-commit-what-they-open |
Migraciju čiji broj BEGIN ne odgovara broju COMMIT i ROLLBACK |
no-direct-compute |
Direktan poziv dobavljaču modela, engine-u, redu ili hostu za tokove rada; drugog čitaoca URL-a za dispečovanje |
no-credentials |
Kredencijal dobavljača modela čitljiv u repozitorijumu ili okruženju |
crud-adherence |
Rutu koja menja podatke čija provera prava ne navodi ništa iz registra |
blocked-backends |
Rutu koja nije ni opslužena, ni blokirana po imenu, ni odbijena po pravilu, niti je u vlasništvu nekog drugog |
every-test-runs |
Testove do kojih glob skripte za testiranje nikada ne dopire |
tiles-are-invariant |
Keširani spoj nezavisan od tenanta koji čita vrednost tenanta ili preskače autentifikaciju |
api-contract |
Registrovanu rutu koju manifest ne deklariše, ili deklarisanu koju kod nikada ne registruje |
rls-present |
Tabelu bez prinudne bezbednosti na nivou redova; SECURITY DEFINER funkciju bez fiksiranog search_path |
no-set-config |
Kod plugina koji sam vezuje podešavanje tenanta |
db-role-honest |
Putanju zahteva koja se povezuje kao vlasnik ili migrator, ili traži SUPERUSER ili BYPASSRLS |
platform-clients |
SDK klijenta koji je uvezen, a nije naveden u backend.platformClients, ili je naveden, a nikada nije uvezen |
rights-register |
Rutu sa opsegom bez deklarisanog prava; proveru prava pored registra |
refusal-ledger |
Deklarisanu tabelu odbijanja bez instalirane knjige evidencije, ili telo odbijanja poslato mimo nje |
grants-declared |
Tabelu sa dodelom koju manifest ne deklariše; privilegije mesta za čitanje dodeljene ručno |
people-declared |
Blok people bez svoje rute za čišćenje, zaštite i tabela |
functions-closure |
Azure Functions plugin čije se opslužene i deklarisane rute ne slažu |
declared-input |
Listu parametara upita handlera koja ne odgovara deklarisanom query rute |
Direktorijum gates/ sadrži pet datoteka sa izuzecima koje provera sme da čita (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json i invariant-seams.json), sa jednim razlogom po unosu. Prazan razlog se računa kao da unos ne postoji, a unos koji navodi nešto što više ne postoji obara proveru. Tamo možete smestiti i sopstvene module provera, a nexus-gates ih preuzima pored ugrađenih.
Cevovod (pipeline) šablona
Šablon ne isporučuje nijedan ručno napisan tok rada. Njegova konfiguracija pipeline-a navodi Dockerfile, jedini build argument (token registra), probnu migraciju i proveru pokretanja, kao i proveru koju pokreće red za spajanje. Redosled je onaj kojim biste želeli da greške budu otkrivene.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, što jecreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, što jenexus-gates --self-testnode scripts/ci/required-env
Oko image-a se izvršavaju još dve provere. Probna migracija primenjuje svaku datoteku na privremeni Postgres pre nego što image može da bude objavljen, istim izvršiocem koji koristi produkcija: nexus-migrate provision jednom kao superuser, a zatim svaku numerisanu datoteku kao migrator. Provera pokretanja pokreće izgrađeni image sa njegovom sopstvenom ulaznom tačkom i svakom promenljivom koju required-env ispisuje, usmeren ka zamenama koje prihvataju konekcije i nikada ne odgovaraju. Server čeka bazu podataka, unutar svog ograničenog vremenskog okvira, i to čekanje je signal uspeha; učitavač konfiguracije koji odbije da se pokrene obara build tu, a ne u produkciji.
Koliko to košta
SDK donosi odluke umesto Vas, a neke od njih biste doneli drugačije. Manifest odbija ključeve koje ne poznaje, tabela ruta mora tačno da odgovara Vašem kodu, uloge u bazi podataka niste Vi ti koji ih osmišljavate, a provere obaraju build zbog nedostajućeg prava pri čitanju. Na svom prvom pluginu proveo sam dan raspravljajući se sa api-contract oko rute koju sam registrovao i zaboravio da deklarišem. Bio je u pravu; ruta nije bila zaštićena. Očekujte da će Vam prvi plugin delovati sporo, a da će drugi oduzeti trećinu vremena.

