PrijavaRezervirajte prezentaciju

Poglavlje 2.21

Plugin SDK

Instaliranje kompleta Plugin SDK (komplet za razvoj softvera), njegovi alati naredbenog retka, obilazak predloška pune usluge, manifest v2 polje po polje i dvadeset dvije kontrolne točke koje drže dodatak u okvirima pravila.

Ovu je stranicu s engleskog izvornika preveo AI. Ako je išta nejasno, mjerodavna je stranica na engleskom jeziku. Pročitajte ovu stranicu na engleskom jeziku

22 min čitanja

Za svoj drugi dodatak trebalo mi je trećinu vremena u odnosu na prvi, a gotovo sva ušteda došla je od SDK-a (kompleta za razvoj softvera). Prvi sam put napisao provjeru dosega, učitavač konfiguracije i izvršitelj migracija, a recenzent je svaki od njih vratio. Drugi sam put pokrenuo jednu naredbu za generiranje kostura, izbrisao oglednu vještinu za analizu sentimenta i proveo dane radeći na zapisima za pregled anomalija koje je naš tim za dinamiku leta zaista trebao.

@adverant-nexus/plugin-sdk je jedan npm paket. Sadrži v2 shemu manifesta i validatore koji je čitaju (definePlugin, defineSkill), izvršne module koje vaš dodatak uvozi za doseg, bazu podataka, otpremu i ostalo, pomoćne alate za testiranje, kontrolne točke usklađenosti (adherence gates) te alate naredbenog retka. Ovo poglavlje obrađuje njegovu instalaciju, alate, predložak, manifest i kontrolne točke. Poglavlje 2.22, Izvršno okruženje dodatka, obrađuje izvršne module u vašem aktivnom kodu.

Instaliranje

Paket dolazi iz Adverantova registra na https://registry.adverant.ai/npm/, nikada iz javnog npm registra, te vam je potreban token za povlačenje (pull token) sa stranice "Pull tokens and install commands" na vašem računu. Usmjerite doseg @adverant-nexus na registar u datoteci .npmrc vašeg repozitorija:

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

<pull-token> je token sa stranice vašeg računa. U cjevovodu ga proslijedite iz tajne (secret) i nikada ga ne pohranjujte u repozitorij (commit); Dockerfile predloška odbija izgradnju bez njega i briše .npmrc iz faze izgradnje nakon što se izvrši npm ci, tako da se token nikada ne isporučuje u slici (image).

Zatim fiksirajte točnu verziju:

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

Pohranite package-lock.json u repozitorij pri prvoj instalaciji. Izgradnja slike predloška pokreće npm ci i odbija se vratiti na npm install: datoteka zaključavanja (lockfile) predstavlja ugovor. Minimalni zahtjev samog SDK-a je Node 18; predložak cilja na Node 20.

Alati naredbenog retka isporučuju se unutar paketa, pa svaka naredba u ovoj dokumentaciji navodi paket i njegovu verziju pomoću npx -p. Samostalno se npx create-nexus-plugin traži u javnom registru, a to ime nije ovaj paket.

Alati naredbenog retka

Alat Što radi
create-nexus-plugin Generira kostur dodatka, validira manifest, migrira v1 manifest na v2 i iscrtava vodič za korisnike za vašeg frontend razvojnog inženjera
nexus-tenancy Iscrtava SQL za višezakupništvo vaše sheme iz manifesta: uloge, ovlaštenja, predložak sigurnosti na razini retka (RLS) i tablice grafa
nexus-migrate Primjenjuje vaše migracije: jednom dodjeljuje uloge, a zatim pokreće svaku numeriranu datoteku u ulozi migratora
nexus-gates Pokreće svaku kontrolnu točku usklađenosti i vlastito samotestiranje svake kontrolne točke

create-nexus-plugin ne upućuje mrežne pozive i ne učitava udaljeni kod. Pokreće iste validatore unutar procesa koje pokreće i uvođenje (onboarding) na platformu, tako da nema odstupanja između "prošlo je validaciju na mom računalu" i "platforma je prihvatila".

Naredba Zastavice Što radi Izlazni kodovi
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Zapisuje novi direktorij dodatka; --print ispisuje samo manifest 0 zapisano · 1 odbijeno prepisivanje · 2 pogrešna upotreba
validate <file> Validira nexus.manifest.json ili modul .ts odnosno .js koji ga izvozi 0 valjano · 1 nevaljano ili nečitljivo · 2 pogrešna upotreba
migrate <file> --write Podiže v1 manifest na v2 i ispisuje ga ili ga zapisuje na isto mjesto 0 · 1 · 2, kao gore
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Iscrtava vodič za korisnike iz manifesta i vašeg opisnog teksta; --check uspoređuje s pohranjenom kopijom i ništa ne zapisuje 0 · 1 odstupanje ili prekršaj provjere koda (lint) · 2 pogrešna upotreba
help Ispisuje upute za upotrebu 0

Izrada početne strukture i tri razine

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

--tier prema zadanim postavkama iznosi full-service. Alat za generiranje kostura odbija zapisivati u postojeći direktorij, a manifest koji zapiše već prolazi validaciju; nikada ne generira nevaljani manifest.

Odaberite razinu (tier) prema onome što vaš dodatak sadrži.

Razina Sadrži Mora deklarirati
skills-only Vještine u manifestu i ništa drugo skills[], s najmanje jednim unosom
ui-only Frontend sučelje unutar ljuske (shell) frontend
full-service Backend i frontend, obično s vlastitom shemom backend i frontend; a budući da ima backend, i runtime.healthCheck

Ako niste sigurni, generirajte kostur full-service i izbrišite ono što vam ne treba. Obrnuti pristup znači pisanje dijelova koje bi vam predložak inače dao.

Obilazak predloška pune usluge

Predložak je referentni dodatak, izgrađen prema strogom obrascu koji svako sljedeće poglavlje podrazumijeva. Klonirajte njegov oblik, a ne njegovu oglednu logiku.

Putanja Što je to
nexus.manifest.json Manifest v2: ponovljena tri zakona, tablica ruta i njezin registar prava
src/config.ts Učitavač konfiguracije. Jedna specifikacija, pročitana jednom, pri čemu se svi problemi prikupljaju prije nego što se proces odbije pokrenuti
src/scope.ts Jedina datoteka koja pretvara zahtjev u doseg, uz strogi verifikator tokena iz SDK-a i dva režima: token donositelja (bearer token) osobe i servisni poziv platforme
src/db.ts Svaki izraz sastavlja tenantFence() i izvršava se unutar withScopedTx
src/uno.ts Jedina datoteka za otpremu (dispatch): jedan URL, jedan klijent, zatvoreni popis dopuštenih (allow-list)
src/routes/*.ts health (anonimno, točna putanja), rute /api (s definiranim dosegom) i povratni poziv /internal (zaštićen servisom)
src/skills/sentiment.ts Deterministička vještina host_callback; zamijenite leksikon vlastitom logikom
src/server.ts Korijen kompozicije: jednom instalira glavnu knjigu odbijanja (refusal ledger), čeka bazu podataka (ograničeno vrijeme), a zatim pokreće provjere izolacije i glavne knjige prije nego što počne slušati
migrations/000_tenancy.sql Iscrtava nexus-tenancy render u vrijeme generiranja kostura: uloge, shema, predložak sigurnosti na razini retka
migrations/001_init.sql Dvije tablice sa složenim ključem koji počinje zakupcem i složenim stranim ključem koji nosi zakupca
migrations/002_refusal_ledger.sql Tablica u koju zapisuje glavna knjiga odbijanja
scripts/ci/required-env Ispisuje nazive varijabli okruženja potrebnih za pokretanje kao JSON
scripts/ci/shadow-migrate-*.sh Probno pokretanje migracije u cjevovodu, kroz nexus-migrate
gates/ Direktorij izuzeća od kontrolnih točaka: prazan, što je ispravno stanje za novi dodatak
test/ Testovi za doseg, rute, bazu podataka, otpremu i pokretanje, s dvojnicima dosega (scope doubles) koje svaki test umeće
Dockerfile Slika bez root ovlasti (ID korisnika 10001) s migracijama unutar nje

Nekoliko tih datoteka vrijedi pobliže proučiti.

src/config.ts slijedi dva pravila. Prikuplja svaki problem prije nego što izbaci pogrešku, tako da jedno ponovno pokretanje navodi svih pet varijabli koje nedostaju umjesto pet ponovnih pokretanja od kojih svako navodi po jednu. Vrijednost postavlja na zadanu samo kada pogrešna vrijednost ne može proizvesti tihi pogrešan odgovor: PORT može imati zadanu vrijednost 8080, jer pogrešan priključak vidljivo ruši povezivanje (bind), dok su DATABASE_URL i UNO_DISPATCH_URL obavezni i moraju biti adrese unutar klastera. Javna se adresa odbija pri pokretanju.

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

Vlastiti test predloška pokreće tu datoteku i uspoređuje njezin izlaz s nazivima koje specifikacija konfiguracije označava kao obavezne, pa dodavanje obavezne varijable bez ažuriranja popisa ruši npm test.

src/server.ts ne počinje slušati dok baza podataka ne odgovori, te ograničava čekanje na 120 sekundi, bilježeći svaki neuspjeli pokušaj s njegovim uzrokom. Zatim redom dokazuje da uloga aplikacije ne može ponovno vezati zakupca i da je svaka tablica prisilno pod sigurnošću na razini retka, da skup veza (pool) svakog poda stane u ograničenje veza te uloge i da tablica glavne knjige odbijanja može primiti redak. Odbijanje bilo kojeg od ta tri uvjeta ispisuje se u cijelosti i proces izlazi s kodom 2.

Manifest v2, polje po polje

Manifest je strojno čitljiv ugovor dodatka s platformom. Validira se kada ga pišete, kada ga platforma uvodi i neprekidno nakon toga. Shema ima postavljeno additionalProperties: false na svakoj razini: ako vaš dodatak ima odjeljak, za njega postoji svojstvo, a nedeklarirani se ključ odbija. Rješenje je uvijek upotreba odgovarajućeg neobaveznog svojstva.

Obavezna jezgra

Polje Pravilo
manifestVersion Točno "2". Dokument verzije v1 se migrira, nikada se ponovno ne validira na istom mjestu
name ^[a-z0-9]+([-.][a-z0-9]+)*$, najviše 64 znaka. ID dodatka koji se koristi pri registraciji, odvajanju imenskog prostora za otpremu i recima ograničenim na zakupca. Dodatak koji deklarira vještine također treba naziv bez točke i bez početne znamenke
displayName 1 do 120 znakova
version Semantička verzija; vaš vlastiti ciklus izdanja
description, author, license Najmanje po jedan znak za svako
tier skills-only, ui-only ili full-service
trust core, verified, community ili untrusted
runtime Obavezno: executionMode, isolationLevel (1 do 4), entrypoint. Neobavezno: nodeVersion, healthCheck, readinessCheck, livenessCheck, pri čemu je svako putanja koja počinje s /. Način rada izvodi se iz razine: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai i deploy, ponovljena tri zakona platforme. Validator fiksira točnu formulaciju

Za dodatak koji gradite za vlastitu instalaciju, tri rečenice glase kako slijedi. Rečenica ai pokriva umjetnu inteligenciju (AI) i mjesto je na kojem se navodi da dodatak ne posjeduje vjerodajnice 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."
}

Tablica ruta: api i rights

api zahtijeva version i basePath, a neobavezno websocket (path, auth) i endpoints[]. Tablica ruta najsnažnija je ideja u shemi: kontrolna točka uspoređuje njezine razlike u odnosu na rute koje vaš kod zaista registrira, u oba smjera, pa je manifest provjerljiv ugovor, a ne dokumentacija.

Svaka krajnja točka treba method (GET, POST, PUT, PATCH ili DELETE) i path. Ostalo:

Polje Što u njemu piše
auth Jedan od pet razreda: scope (ruta osobe, iza čuvara dosega), service-key i internal (poslužitelj prema poslužitelju, nikada dostupno iz preglednika), public (uvijek isključivo točna putanja s allowAnonymous) te device (stroj s vlastitom vjerodajnicom, iza čuvara uređaja)
right Obavezno na svakoj ruti koju poslužuje čuvar dosega, a odbija se na svim ostalima: naziv prava u registru rights
needsUnit Ruta odbija zahtjev kada se jedinica pozivatelja ne može razriješiti
allowAnonymous Isključivo popis dopuštenih s točnim podudaranjem. Pravilo prefiksa je način na koji /health-of-tenant-42 završi kao javno dostupno
group, serves, screens Pod blokom release: grupa sposobnosti koju ruta poslužuje, što odgovara kada je licencirana značajka te grupe zaključana (data, teaser, sighting ili ask) te zasloni koje poslužuje
query required (svaki naziv s primjerom vrijednosti) i allowed: parametri upita koje ruta čita
body example: primjer tijela zahtjeva za rutu pisanja, onakav kakav prihvaća njezin vlastiti validator. Nikada na metodi GET

rights je registar koji te rute navode. Svako pravo ima roles (gornju granicu) te neobavezno summary, never (uloge koje ga nikada ne smiju iskoristiti, bez obzira na to što drugo posjeduju), barred (vlastite riječi proizvoda za odbijanje uloge never), seat (potrebno je i aktivno mjesto, tj. seat), self (posjeduje ga svaka verificirana osoba, za prava nad vlastitom sesijom), grants (nositelji dodjeljuju mjesta; najviše jedno pravo to navodi), licence (licencirana značajka koju licenca organizacije mora sadržavati), installation (posjeduju samo administratori same instalacije) i platform (posjeduju samo Adverantovi administratori platforme; ne navodi nikakve uloge). Nazivi prava imaju najmanje jednu toč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 dosega bez prava (ENDPOINT_RIGHT_MISSING), pravo koje nedostaje u registru (ENDPOINT_RIGHT_NOT_REGISTERED) i pravo na ruti koju ne poslužuje nijedan čuvar (ENDPOINT_RIGHT_UNGUARDED). Također odbija registar koji proturječi sam sebi, kao i dva načina zapisa iste rute (:id i :recordId) kao DUPLICATE_ENDPOINT.

Vaši podaci: databases, schema i db

schema je jedina Postgres shema u vlasništvu dodatka. public, plugins, auth i nexus su zabranjeni, a ako databases[] također navodi Postgres shemu, one se moraju podudarati.

databases[] deklarira svako spremište prema pogonu (engine): postgresql (schema, tables, migrations i granted, tablice koje druga organizacija može čitati na temelju zabilježenog ovlaštenja), neo4j (schemas), qdrant (collections) ili redis (purpose).

db sadrži ograničenja sesije za svaku vezu koju dodatak otvara, deklarirana ovdje umjesto u kodu, tako da ih i recenzent i sustav za postavljanje (deployment) mogu pročitati:

Polje Što ograničava
maxConnections Skup veza (pool) po replici
pods Najveći broj podova koji istovremeno drže skup veza, replike plus skok (surge) pri postupnom ažuriranju. Ograničenje veza svake uloge iscrtava se kao maxConnections × pods; ako ga izostavite, definePlugin izdaje upozorenje DB_PODS_UNDECLARED
statementTimeoutMs Jedan izraz (statement)
idleInTransactionTimeoutMs Otvorena transakcija koja ništa ne izvršava
workMemKB Jedan čvor sortiranja ili sažimanja (hash), po čvoru, a ne po upitu
piiMask[] Unosi table.column koji sadrže osobne podatke, maskirani u upravljanoj SQL konzoli i u zapisnicima (logs)

Vještine i alati: skills, mcpTools, entitlements

skills[] sadrži vještine manifesta; poglavlje 2.20, Vještine, obrađuje njihova polja i razine. mcpTools[] sadrži MCP (Model Context Protocol) alate koje dodatak objavljuje, od kojih je svaki name, description i inputSchema bez oneOf, allOf ili anyOf na najvišoj razini.

entitlements zahtijeva featureIdPattern te prihvaća alwaysOn[], source i store. Obrazac imenuje imenski prostor u kojem se nalaze vaši ID-jevi značajki, što je uobičajeno name dodatka plus jedan segment koji vaš kod popunjava po sučelju. alwaysOn[] je kratak, točan popis koji mora odgovarati čak i kada se ne može dobiti odluka o pravima (entitlement verdict): zdravlje (health), spremnost (readiness), prijava i postavke koje administrator treba za popravak prava.

Kontrola promjena: changePolicy

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

Odobrenja se broje prema različitim osobama, a osoba koja je predložila promjenu nikada nije jedna od njih; bez oba uvjeta, "dva odobrenja" postaju jedna osoba koja klikne dvaput. enabled: true zahtijeva classes, a svaki navedeni razred treba vlastiti broj. Razred koji izostavite nije upravljan, što je legitiman odabir koji vas shema tjera da izričito zapišete.

Tko ste vi: domains, branding, routing

domains[] (svaki s primary i aliases[]; domain je oblik za jednu domenu) navodi gdje dodatak odgovara. branding zahtijeva appName i prihvaća tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId i gaId. Sve u branding je javno: stranica za prijavu čita te podatke prije nego što itko ima vjerodajnicu, stoga nikada ne sadrži tajnu ili internu adresu. routing (type, gateway, virtualService) je za dodatke koji opisuju vlastito usmjeravanje.

Dimenzioniranje i ostalo

resources zahtijeva cpuMillicores (10 do 64.000) i memoryMB (16 do 262.144) te prihvaća diskGB, timeoutMs, port i wsPort. backend sadrži port, healthPath, apiPrefix, framework i platformClients[], klijente SDK-a koje vaš backend uvozi prema nazivu. Popis je zatvoren, a kontrolna točka ga provjerava u odnosu na vaše uvoze. Shema dopušta četrnaest naziva: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin i uno, plus jedan za klijenta koji odgovara na odbijanja prava iz plana, a koji zadržava interni naziv. Klijent za prava na značajke, runtime/entitlements, nije jedan od njih i nikada ne ide na taj popis, jer ga vaš blok entitlements već deklarira, a backend koji ga uvozi bez bloka entitlements pada na istoj kontrolnoj točki. frontend sadrži basePath, mountPath i framework. nexus sadrži minVersion, maxVersion, capabilities[] i permissions[].

Preostali blokovi služe svaki za po jedan zadatak:

Blok Za
settings Vaše postavke na dijeljenom radnom okviru: groups i keys, postavljene na razinama koje svaka navodi
people sweep (service, port): članovi organizacije, sinkronizirani iz servisa za identitet, s mjestima (seats) koja se isključuju kada netko ode
ontology entityTypes i relationshipTypes: tipizirani graf koji se čuva u vašoj vlastitoj shemi
release groups i frame: grupe sposobnosti u kojima su vaše rute pripremljene, a koje se prvo puštaju kao kanarinac (canary)
cells[] Dodatak koji se sastoji od nekoliko jedinica za postavljanje (deployables): svaka ima name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] za vaš unos u katalogu
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Tko ga objavljuje i gdje se nalazi njegov kod
metrics, atlas Dva namjerno otvorena objekta, za vaše vlastite nazive metrika i generiranje dokumentacije o arhitekturi

Što shema ne može izraziti

JSON shema određuje oblik; definePlugin dodaje pravila koja shema ne može izraziti. classification vještine ne može premašiti gornju granicu povjerenja. Samo dodaci core i verified smiju deklarirati vještine tool_using i llm_only. Svaka deklarirana putanja mora biti relativna i istog podrijetla (same-origin), bez sheme, bez // i bez obrnute kose crte, jer parser URL-a pretvara \ u /, a /\evil.example/x se razrješuje kao različito podrijetlo (cross-origin). Svako pravilo koje sinkronizacija registra primjenjuje na vještinu ovdje se primjenjuje prvo, s vlastitim kodom sinkronizacije, tako da validate i sinkronizacija imenuju prekršeno pravilo na isti način.

Provjera valjanosti i prelazak s 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

Neuspjeh ispisuje točnu putanju, a za pravilo sinkronizacije najprije kod. Postavite to kao commit hook.

Manifest verzije v1 podiže se mehanički. migrate dodaje tri rečenice zakona, premješta domain u domains[] i odbija izmisliti ulaznu točku koju niste imali. Validira rezultat prije ispisa ili zapisivanja bilo čega, tako da migracija nikada ne prenosi pogrešku iz alata u vaš repozitorij.

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

Pročitajte razlike (diff) prije nego što ih pohranite u repozitorij. Rečenice zakona koje dodaje predstavljaju formulaciju koju validator fiksira; za vlastitu instalaciju postavite deploy na ranije prikazanu rečenicu.

Iscrtavanje zakupa i dodjeljivanje uloga

Ovlaštenja uloga ili predložak sigurnosti na razini retka nikada ne pišete ručno. nexus-tenancy render ih zapisuje iz svojstava schema i db u manifestu:

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

Iscrtana datoteka stvara pet uloga za shemu, svaku s onim što ne smije posjedovati: migratora koji može postati samo vlasnik, vlasnika koji se ne može prijaviti, ulogu aplikacije za putanju zahtjeva, ulogu za izvješća koja vidi samo agregate i ulogu glavne knjige koja može samo dodavati na kraj (append). Nijedna uloga ne posjeduje BYPASSRLS. Jedini način za vezanje zakupca je jedna funkcija baze podataka, a set_config je opozvan svim ulogama osim vlasnika.

Primijenjena datoteka višezakupništva nikada se ne uređuje. Promjena je revizija s vlastitom datotekom s brojem 0, a mjesto za čitanje (read seat) za ovlaštenja između organizacija stiže na taj način, kao revizija 2. --graph iscrtava dvije tablice tipiziranog grafa koje vaš ontology deklarira kao vašu sljedeću numeriranu 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 višezakupništva stvara upravo one uloge pod kojima se izvršitelj povezuje, pa je primjenjuje 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 niz za povezivanje (connection string) za vlasnika baze podataka, a <dir> je privatni direktorij. Dodjeljivanje (provision) primjenjuje osnovnu datoteku višezakupništva i svaku reviziju po redu, zapisuje migrator.url i app.url (te seat.url kada postoji revizija 2) u <dir> s načinom 0600 i ne ispisuje nikakve tajne. Pri svakom pokretanju postavlja ograničenje veza svake uloge iz db.maxConnections × db.pods. Ponovno pokretanje zadržava postojeće lozinke osim ako to ne zatražite: --passwords <dir> ih postavlja iz datoteka, a --rotate <roles> navedenim ulogama daje nove. Pretvorite te datoteke u tajne vašeg sustava za postavljanje.

Nakon toga, primjena se povezuje pomoću niza za povezivanje migratora koji je zapisao korak dodjeljivanja:

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

Pokreće datoteke od 001 nadalje kao migrator, svaku datoteku pod SET ROLE <schema>_owner, jedna transakcija po datoteci. Vodi glavnu knjigu, <schema>.schema_migrations, s kontrolnim zbrojem svake datoteke; primijenjena datoteka čiji su se bajtovi promijenili odbija se po nazivu (CHECKSUM_DRIFT), nikada se ne pokreće ponovno i nikada se ne preskače. Svaka datoteka na čekanju parsira se stvarnom Postgres gramatikom prije nego što se pokrene prva, tako da odbijanje ostavlja bazu podataka netaknutom. Jedino zaglavlje koje datoteka smije nositi je -- nexus-migration: transaction=file|per-statement, s neobaveznim vremenskim ograničenjima zaključavanja i izraza; per-statement služi za CREATE INDEX CONCURRENTLY.

Kontrolne točke

nexus-gates pokreće dvadeset i dvije kontrolne točke. Svaka kodira jedan razred nedostatka kako se ne bi mogao isporučiti dvaput, i svaka ima samotestiranje koje dokazuje da pada na testnom predlošku (fixture) izgrađenom da je aktivira. Pokrenite ih prije slanja (push) u repozitorij:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Kontrolna točka Što hvata
scope-adherence Rutu /api bez čuvara dosega; anonimnu putanju koja nije točno deklarirana; rutu uređaja bez čuvara uređaja ili s čuvarom osobe pokraj njega
one-fence Predikat zakupca definiran bilo gdje osim na jednom mjestu, uključujući ručno izrađenu ogradu (fence) za mjesto ili ovlaštenje
sql-fence Izraz koji čita ili ažurira tablicu ograničenu dosegom bez ograde, u bilo kojem cilju FROM, JOIN, USING ili UPDATE
migrations-are-scoped Tablicu kojoj nedostaje os, složeni ključ koji počinje zakupcem, strani ključ koji nosi zakupca ili demo stupac
migrations-commit-what-they-open Migraciju čiji se broj BEGIN ne podudara s njezinim brojem COMMIT i ROLLBACK
no-direct-compute Izravan poziv pružatelju modela, pogonu, redu čekanja ili poslužitelju tijeka rada; drugog čitača URL-a za otpremu
no-credentials Vjerodajnicu pružatelja modela čitljivu u repozitoriju ili okruženju
crud-adherence Mutirajuću rutu čija provjera prava ne navodi ništa iz registra
blocked-backends Rutu koja se niti poslužuje, niti je blokirana po nazivu, niti odbijena po zakonu, niti je u vlasništvu negdje drugdje
every-test-runs Testove do kojih glob skripte za testiranje nikada ne dolazi
tiles-are-invariant Predmemorirani spoj neovisan o zakupcu koji čita vrijednost zakupca ili preskače autentifikaciju
api-contract Registriranu rutu koju manifest ne deklarira ili deklariranu rutu koju kod nikada ne registrira
rls-present Tablicu bez prisilne sigurnosti na razini retka; funkciju SECURITY DEFINER bez fiksiranog search_path
no-set-config Kod dodatka koji sam veže postavku zakupca
db-role-honest Putanju zahtjeva koja se povezuje kao vlasnik ili migrator, ili traži SUPERUSER ili BYPASSRLS
platform-clients Klijenta SDK-a koji je uvezen, ali nije naveden u backend.platformClients, ili je naveden, ali nikada uvezen
rights-register Rutu dosega bez deklariranog prava; provjeru prava mimo registra
refusal-ledger Deklariranu tablicu odbijanja bez instalirane glavne knjige ili tijelo odbijanja poslano mimo nje
grants-declared Ovlaštenu tablicu koju manifest ne deklarira; ručno podijeljene privilegije mjesta za čitanje
people-declared Blok people bez njegove rute za čišćenje (sweep), čuvara i tablica
functions-closure Dodatak Azure Functions čije se posluživane rute i deklarirane rute ne slažu
declared-input Popis parametara upita rukovatelja (handler) koji se ne podudara s deklariranim query rute

Direktorij gates/ sadrži pet datoteka izuzeća koje kontrolna točka smije čitati (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json i invariant-seams.json), po jedan razlog za svaki unos. Prazan razlog računa se kao nepostojeći unos, a unos koji imenuje nešto što više ne postoji ruši kontrolnu točku. Tamo također možete ubaciti vlastite module kontrolnih točaka, a nexus-gates će ih preuzeti uz one ugrađene.

Kompatibilnost
Kompatibilnost
Kompatibilnost pokazuje koja verzija SDK-a radi s kojom verzijom platforme, na temelju noćnih pokretanja brzog početka (quickstart). Netestirani par to izričito navodi, a par koji ne prolazi navodi promjenu koja ga je srušila.

Cjevovod predloška

Predložak ne isporučuje ručno pisani tijek rada. Njegova konfiguracija cjevovoda navodi Dockerfile, jedini argument izgradnje (token registra), probno pokretanje migracije i sondu za pokretanje te kontrolnu točku koju pokreće red čekanja za spajanje (merge queue). Redoslijed odgovara redoslijedu kojim biste željeli da proces padne u slučaju pogreške.

  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

Još dvije provjere izvode se oko slike. Probno izvođenje migracije primjenjuje svaku datoteku na privremeni Postgres prije nego što se slika može izdati, s istim pokretačem koji koristi produkcija: nexus-migrate provision jednom kao superkorisnik, a zatim svaku numeriranu datoteku kao migrator. Sonda za pokretanje pokreće izgrađenu sliku s vlastitom ulaznom točkom i svakom varijablom koju required-env ispisuje, usmjerenu na zamjene koje prihvaćaju veze i nikada ne odgovaraju. Poslužitelj čeka bazu podataka unutar svog ograničenog vremenskog okvira, i to čekanje je prolazni signal; učitavač konfiguracije koji se odbije pokrenuti ruši izgradnju ondje, a ne u produkciji.

Izgradnja u izdanju Community
Izgradnja u izdanju Community
Na izdanju Community razvojni inženjer dobiva iste zlatne putove, razvojni prostor i grane podataka na jednom poslužitelju, s kodom na vlastitom Git poslužitelju. Staging, pilot-jedinice i maskirane kopije produkcijskih podataka dolaze s izdanjem Enterprise.

Koliko to stoji

SDK donosi odluke umjesto vas, a neke od njih biste donijeli drugačije. Manifest odbija ključeve koje ne prepoznaje, tablica ruta mora se točno podudarati s vašim kodom, uloge baze podataka nisu na vama da ih dizajnirate, a kontrolne točke ruše izgradnju zbog nedostatka prava pri čitanju. Na svom prvom dodatku proveo sam dan raspravljajući s api-contract o ruti koju sam registrirao, a zaboravio deklarirati. Bio je u pravu; ruta je bila nezaštićena. Očekujte da će se izrada prvog dodatka činiti sporom, a da će drugi oduzeti trećinu tog vremena.