PrijavaZakažite brifing

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

22 min čitanja

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.0

Komitujte 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 --write

Proč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.sql

Generisana 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.sql

Datoteka 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.json

Izvrš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.

Kompatibilnost
Kompatibilnost
Kompatibilnost pokazuje koja verzija SDK-a radi sa kojom verzijom platforme, na osnovu noćnih pokretanja quickstart-a. Za netestirani par to je navedeno, a za par koji ne prolazi navodi se izmena koja ga je pokvarila.

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.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, što je create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, što je nexus-gates --self-test
  7. node 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.

Razvoj na Community izdanju
Razvoj na Community izdanju
Na Community izdanju programer dobija iste proverene putanje, razvojni prostor i grane podataka na jednom serveru, sa kodom na sopstvenom Git hostu. Staging, pilot jedinice i maskirane kopije živih podataka dolaze sa Enterprise izdanjem.

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.