PrijavaRezervirajte predstavitev

Poglavje 2.21

Plugin SDK

Namestitev kompleta Plugin SDK (komplet za razvoj programske opreme), njegova orodja ukazne vrstice, pregled predloge polne storitve, manifest v2 polje za poljem ter dvaindvajset kontrolnih točk, ki skrbijo, da vtičnik upošteva pravila.

To stran je iz angleškega izvirnika prevedla UI. Če je karkoli nejasno, je referenca angleška stran. Preberite to stran v angleščini

22 min branja

Za svoj drugi vtičnik sem porabil tretjino časa prvega, skoraj ves prihranek pa je prinesel SDK (komplet za razvoj programske opreme). Prvič sem napisal preverjanje obsega, nalagalnik konfiguracije in zaganjalnik migracij, pregledovalec pa je prav vsakega od njih zavrnil. Drugič sem zagnal en sam ukaz za ustvarjanje ogrodja, izbrisal vzorčno veščino za analizo naklonjenosti in svoje dni namenil zapisom o pregledu anomalij, ki jih je naša ekipa za dinamiko leta dejansko potrebovala.

@adverant-nexus/plugin-sdk je en sam paket npm. Vsebuje shemo manifesta v2 in validatorje, ki jo berejo (definePlugin, defineSkill), izvajalne module, ki jih vaš vtičnik uvaža za obseg, podatkovno bazo, razpošiljanje in preostalo, pomožna orodja za testiranje, vrata skladnosti ter orodja ukazne vrstice. To poglavje obravnava njegovo namestitev, orodja, predlogo, manifest in vrata. Poglavje 2.22, Izvajalno okolje vtičnika, obravnava izvajalne module v vaši delujoči kodi.

Namestitev

Paket prihaja iz registra Adverant na naslovu https://registry.adverant.ai/npm/ in nikoli iz javnega registra npm, pri čemer potrebujete žeton za prevzem s strani »Pull tokens and install commands« v svojem računu. Usmerite obseg @adverant-nexus na register v datoteki .npmrc svojega repozitorija:

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

<pull-token> je žeton s strani vašega računa. V cevovodu ga posredujte iz skrivnosti in ga nikoli ne uveljavite v repozitoriju; datoteka Dockerfile predloge brez njega zavrne gradnjo in po izvedbi npm ci izbriše .npmrc iz faze gradnje, tako da se žeton nikoli ne vključi v sliko.

Nato natančno pripnite različico:

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

Ob prvi namestitvi uveljavite package-lock.json. Gradnja slike predloge zažene npm ci in zavrne preklop na npm install: datoteka zaklepa je pogodba. Spodnja meja samega SDK-ja je Node 18; predloga cilja na Node 20.

Orodja ukazne vrstice so vključena v paket, zato vsak ukaz v tej dokumentaciji imenuje paket in njegovo različico z npx -p. Samostojni npx create-nexus-plugin se išče v javnem registru in to ime ne pripada temu paketu.

Orodja ukazne vrstice

Orodje Kaj naredi
create-nexus-plugin Ustvari ogrodje vtičnika, potrdi manifest, migrira manifest iz v1 v v2 in izriše vodnik za odjemalce za vašega razvijalca čelnega dela
nexus-tenancy Izriše SQL za večnajemništvo vaše sheme iz manifesta: vloge, dodelitve pravic, predlogo varnosti na ravni vrstic in grafične tabele
nexus-migrate Izvede vaše migracije: enkrat zagotovi vloge, nato zažene vsako oštevilčeno datoteko v vlogi migratorja
nexus-gates Zažene vsa vrata skladnosti in lastni samotest vsakih vrat

create-nexus-plugin ne izvaja omrežnih klicev in ne nalaga oddaljene kode. Zažene iste znotrajprocesne validatorje, kot jih zažene uvajanje na platformi, zato ni razhajanj med »potrjeno v mojem računalniku« in »platforma je to sprejela«.

Ukaz Zastavice Kaj naredi Izhodne kode
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Zapiše nov imenik vtičnika; --print izpiše samo manifest 0 zapisano · 1 prepisovanje zavrnjeno · 2 napačna uporaba
validate <file> Potrdi nexus.manifest.json ali modul .ts oziroma .js, ki ga izvaža 0 veljavno · 1 neveljavno ali neberljivo · 2 napačna uporaba
migrate <file> --write Nadgradi manifest v1 na v2 in ga izpiše ali zapiše na istem mestu 0 · 1 · 2, kot zgoraj
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Izriše vodnik za odjemalce iz manifesta in vašega opisa; --check ga primerja z uveljavljeno kopijo in ne zapiše ničesar 0 · 1 odstopanje ali kršitev preverjanja · 2 napačna uporaba
help Izpiše navodila za uporabo 0

Vzpostavitev ogrodja in tri ravni

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

--tier ima privzeto vrednost full-service. Orodje za ustvarjanje ogrodja zavrne pisanje v že obstoječi imenik, manifest, ki ga zapiše, pa že prestane preverjanje veljavnosti; nikoli ne ustvari neveljavnega.

Izberite raven glede na to, kaj vaš vtičnik vsebuje.

Raven Vsebuje Mora deklarirati
skills-only Veščine v manifestu in nič drugega skills[], z vsaj enim vnosom
ui-only Čelno površino znotraj lupine frontend
full-service Zaledni in čelni del, običajno z lastno shemo backend in frontend; in ker ima zaledni del, tudi runtime.healthCheck

Če niste prepričani, ustvarite ogrodje full-service in izbrišite, česar ne potrebujete. Obratna pot pomeni pisanje delov, ki bi vam jih sicer zagotovila predloga.

Pregled predloge polne storitve

Predloga je referenčni vtičnik, zgrajen po strogem vzorcu, ki ga predpostavlja vsako naslednje poglavje. Klonirajte njegovo obliko, ne njegove vzorčne logike.

Pot Kaj to je
nexus.manifest.json Manifest v2: ponovno navedeni trije zakoni, usmerjevalna tabela in njen register pravic
src/config.ts Nalagalnik konfiguracije. Ena specifikacija, prebrana enkrat, vsaka težava zbrana, preden proces zavrne zagon
src/scope.ts Edina datoteka, ki pretvori zahtevo v obseg, s strogim preverjalnikom žetonov SDK-ja in dvema režimoma: prinosniški žeton osebe in storitveni klic platforme
src/db.ts Vsak stavek sestavlja tenantFence() in se izvaja znotraj withScopedTx
src/uno.ts Edina datoteka za razpošiljanje: en URL, en odjemalec, zaprt seznam dovoljenih
src/routes/*.ts health (anonimno, natančna pot), poti /api (z omejenim obsegom) in povratni klic /internal (varovan s storitvijo)
src/skills/sentiment.ts Deterministična veščina host_callback; zamenjajte leksikon s svojo lastno logiko
src/server.ts Koren sestavljanja: enkrat namesti glavno knjigo zavrnitev, počaka na podatkovno bazo (omejeno), nato pa pred poslušanjem zažene preverjanja izolacije in glavne knjige
migrations/000_tenancy.sql Izrisano z nexus-tenancy render ob ustvarjanju ogrodja: vloge, shema, predloga varnosti na ravni vrstic
migrations/001_init.sql Dve tabeli s sestavljenim ključem z vodilnim najemnikom in sestavljenim tujim ključem, ki prenaša najemnika
migrations/002_refusal_ledger.sql Tabela, v katero piše glavna knjiga zavrnitev
scripts/ci/required-env Izpiše imena okoljskih spremenljivk, zahtevanih ob zagonu, v obliki JSON
scripts/ci/shadow-migrate-*.sh Poskusni zagon migracije v cevovodu prek nexus-migrate
gates/ Imenik izjem za vrata: prazen, kar je pravilno stanje za nov vtičnik
test/ Testi za obseg, poti, podatkovno bazo, razpošiljanje in zagon, z dvojniki obsega, ki jih vbrizga vsak test
Dockerfile Slika brez korenskih pravic (ID uporabnika 10001) z migracijami v njej

Nekaj teh datotek si zasluži podrobnejši pregled.

src/config.ts sledi dvema praviloma. Preden sproži izjemo, zbere vse težave, tako da en ponovni zagon imenuje vseh pet manjkajočih spremenljivk namesto petih ponovnih zagonov, ki bi imenovali vsak po eno. Privzeto vrednost določi le takrat, ko napačna vrednost ne more povzročiti tihega napačnega odgovora: PORT ima lahko privzeto vrednost 8080, ker napačna vrata vidno ne uspejo pri vezavi, medtem ko sta DATABASE_URL in UNO_DISPATCH_URL obvezna in morata biti naslova znotraj gruče. Javni naslov se ob zagonu zavrne.

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

Lastni test predloge zažene to datoteko in primerja njen izpis z imeni, ki jih specifikacija konfiguracije označuje kot obvezna, zato dodajanje obvezne spremenljivke brez posodobitve seznama povzroči neuspeh pri npm test.

src/server.ts ne posluša, dokler se podatkovna baza ne odzove, čakanje pa omeji na 120 sekund in zabeleži vsak neuspešen poskus skupaj z vzrokom. Nato po vrsti dokaže, da vloga aplikacije ne more ponovno vezati najemnika in je za vsako tabelo vsiljena varnost na ravni vrstic, da zaloga povezav vsakega poda ustreza omejitvi povezav vloge ter da tabela glavne knjige zavrnitev lahko sprejme vrstico. Zavrnitev katerega koli od teh treh preverjanj se izpiše v celoti in proces se konča s kodo 2.

Manifest v2, polje za poljem

Manifest je strojno berljiva pogodba vtičnika s platformo. Preveri se, ko ga napišete, ko ga platforma uvede in nato neprekinjeno. Shema ima na vsaki ravni določeno additionalProperties: false: če ima vaš vtičnik razdelek, zanj obstaja lastnost, nedeklarirani ključ pa se zavrne. Rešitev je vedno uporaba ustrezne izbirne lastnosti.

Obvezno jedro

Polje Pravilo
manifestVersion Natančno "2". Dokument v1 se migrira in se nikoli ponovno ne preverja na istem mestu
name ^[a-z0-9]+([-.][a-z0-9]+)*$, največ 64 znakov. ID vtičnika, ki se uporablja pri registraciji, določanju imenskega prostora za razpošiljanje in vrsticah, omejenih na najemnika. Vtičnik, ki deklarira veščine, potrebuje tudi ime brez pike in brez vodilne števke
displayName 1 do 120 znakov
version Semantična različica; vaš lastni cikel izdaj
description, author, license Vsak vsaj en znak
tier skills-only, ui-only ali full-service
trust core, verified, community ali untrusted
runtime Obvezno: executionMode, isolationLevel (1 do 4), entrypoint. Izbirno: nodeVersion, healthCheck, readinessCheck, livenessCheck, vsak kot pot, ki se začne z /. Način je izpeljan iz ravni: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai in deploy, ponovno navedeni trije zakoni platforme. Validator zahteva natančno ubeseditev

Za vtičnik, ki ga zgradite za lastno namestitev, se trije stavki glasijo takole. Stavek ai zajema umetno inteligenco (UI) in je mesto, kjer navedete, da vtičnik ne hrani nobenih poverilnic za modele.

"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."
}

Usmerjevalna tabela: api in rights

api potrebuje version in basePath ter izbirno websocket (path, auth) in endpoints[]. Usmerjevalna tabela je najmočnejši koncept v shemi: vrata preverjajo razlike med njo in potmi, ki jih vaša koda dejansko registrira, v obe smeri, zato je manifest preverljiva pogodba in ne dokumentacija.

Vsaka končna točka potrebuje method (GET, POST, PUT, PATCH ali DELETE) in path. Preostalo:

Polje Kaj navaja
auth Eden od petih razredov: scope (pot osebe, za varovalom obsega), service-key in internal (strežnik s strežnikom, nikoli dosegljivo iz brskalnika), public (vedno le natančna pot z allowAnonymous) ter device (stroj z lastno poverilnico, za varovalom naprave)
right Obvezno na vsaki poti, ki jo streže varovalo obsega, in zavrnjeno na vseh drugih: ime pravice v registru rights
needsUnit Pot zavrne dostop, ko enote klicatelja ni mogoče razrešiti
allowAnonymous Samo seznam dovoljenih z natančnim ujemanjem. Pravilo predpone je način, kako /health-of-tenant-42 postane javno dostopen
group, serves, screens Pod blokom release: skupina zmogljivosti, ki ji pot služi, kaj odgovori, ko je licencirana funkcionalnost te skupine zaklenjena (data, teaser, sighting ali ask), in zasloni, ki jim služi
query required (vsako ime s primerom vrednosti) in allowed: parametri poizvedbe, ki jih pot bere
body example: primer telesa zahteve za pot pisanja, takšen, ki ga sprejme njen lastni validator. Nikoli pri metodi GET

rights je register, ki ga te poti imenujejo. Vsaka pravica ima roles (zgornjo mejo) ter izbirno summary, never (vloge, ki je nikoli ne smejo uveljavljati, ne glede na to, kaj drugega imajo), barred (lastno besedilo izdelka za zavrnitev vloge never), seat (potreben je tudi aktiven sedež), self (ima jo vsaka preverjena oseba za pravice nad lastno sejo), grants (imetniki dodeljujejo sedeže; to navaja največ ena pravica), licence (licencirana funkcionalnost, ki jo mora vsebovati licenca organizacije), installation (imajo jo le skrbniki same namestitve) in platform (imajo jo le skrbniki platforme Adverant; ne imenuje nobenih vlog). Imena pravic imajo vsaj eno piko: 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 zavrne pot obsega brez pravice (ENDPOINT_RIGHT_MISSING), pravico, ki je ni v registru (ENDPOINT_RIGHT_NOT_REGISTERED), in pravico na poti, ki je ne streže nobeno varovalo (ENDPOINT_RIGHT_UNGUARDED). Zavrne tudi register, ki je v nasprotju sam s seboj, in dva zapisa iste poti (:id in :recordId) kot DUPLICATE_ENDPOINT.

Vaši podatki: databases, schema in db

schema je edina shema Postgres, ki si jo lasti vtičnik. public, plugins, auth in nexus so prepovedani, in če databases[] prav tako imenuje shemo Postgres, se morata ujemati.

databases[] deklarira vsako shrambo glede na pogon: postgresql (schema, tables, migrations in granted, tabele, ki jih druga organizacija lahko bere na podlagi zabeležene dodelitve pravic), neo4j (schemas), qdrant (collections) ali redis (purpose).

db vsebuje omejitve seje za vsako povezavo, ki jo odpre vtičnik, deklarirane tukaj namesto v kodi, tako da jih lahko prebereta tako pregledovalec kot postopek namestitve:

Polje Kaj omejuje
maxConnections Zaloga povezav na repliko
pods Največje število podov, ki imajo hkrati zalogo povezav, replike plus presežek ob postopni posodobitvi. Omejitev povezav vsake vloge se izriše kot maxConnections × pods; če jo izpustite, definePlugin opozori DB_PODS_UNDECLARED
statementTimeoutMs En stavek
idleInTransactionTimeoutMs Odprta transakcija, ki ne izvaja ničesar
workMemKB Eno vozlišče za razvrščanje ali zgoščevanje, na vozlišče, ne na poizvedbo
piiMask[] Vnosi table.column, ki vsebujejo osebne podatke, zakriti v nadzorovani konzoli SQL in v dnevnikih

Veščine in orodja: skills, mcpTools, entitlements

skills[] vsebuje veščine manifesta; poglavje 2.20, Veščine, obravnava njihova polja in ravni. mcpTools[] vsebuje orodja MCP (Model Context Protocol), ki jih objavlja vtičnik, pri čemer ima vsako name, description in inputSchema brez vrhnjih oneOf, allOf ali anyOf.

entitlements zahteva featureIdPattern ter sprejema alwaysOn[], source in store. Vzorec poimenuje imenski prostor, v katerem se nahajajo vaši ID-ji funkcionalnosti, običajno name vtičnika plus en segment, ki ga vaša koda izpolni za vsako površino. alwaysOn[] je kratek, natančen seznam, ki se mora odzvati tudi takrat, ko ni mogoče pridobiti odločitve o upravičenosti: zdravje, pripravljenost, prijava in nastavitve, ki jih skrbnik potrebuje za popravilo upravičenosti.

Nadzor sprememb: changePolicy

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

Odobritve se štejejo po različnih osebah, pri čemer oseba, ki je spremembo predlagala, ni nikoli ena izmed njih; brez obeh pogojev »dve odobritvi« postaneta ena oseba, ki klikne dvakrat. enabled: true zahteva classes, vsak imenovani razred pa potrebuje svoje število. Razred, ki ga izpustite, ni nadzorovan, kar je legitimna izbira, za katero shema zahteva, da jo zapišete.

Kdo ste: domains, branding, routing

domains[] (vsak primary in aliases[]; domain je oblika za eno domeno) navaja, kje se vtičnik odziva. branding zahteva appName ter sprejema tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId in gaId. Vse v branding je javno: prijavna stran to prebere, preden ima kdor koli poverilnico, zato nikoli ne vsebuje skrivnosti ali internega naslova. routing (type, gateway, virtualService) je namenjen vtičnikom, ki opisujejo lastno usmerjanje.

Dimenzioniranje in preostalo

resources zahteva cpuMillicores (10 do 64.000) in memoryMB (16 do 262.144) ter sprejema diskGB, timeoutMs, port in wsPort. backend vsebuje port, healthPath, apiPrefix, framework in platformClients[], odjemalce SDK, ki jih vaš zaledni del uvaža po imenu. Seznam je zaprt in vrata ga preverjajo glede na vaše uvoze. Shema dovoljuje štirinajst imen: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin in uno, ter še eno za odjemalca, ki odgovarja na zavrnitve upravičenosti paketa in ohranja interno ime. Odjemalec za upravičenost funkcionalnosti, runtime/entitlements, ni eden izmed njih in se nikoli ne uvrsti na seznam, ker ga deklarira že vaš blok entitlements, zaledni del, ki ga uvozi brez bloka entitlements, pa pade na istih vratih. frontend vsebuje basePath, mountPath in framework. nexus vsebuje minVersion, maxVersion, capabilities[] in permissions[].

Preostali bloki so tam vsak za eno nalogo:

Blok Namen
settings Vaše nastavitve v skupnem ogrodju: groups in keys, nastavljene na ravneh, ki jih vsaka imenuje
people sweep (service, port): člani organizacije, sinhronizirani iz storitve identitete, pri čemer se sedeži izklopijo, ko nekdo odide
ontology entityTypes in relationshipTypes: tipizirani graf, hranjen v vaši lastni shemi
release groups in frame: skupine zmogljivosti, v katerih so pripravljene vaše poti, izdane najprej kot kanarček
cells[] Vtičnik, ki je sestavljen iz več namestitvenih enot: za vsako name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] za vaš vnos v katalogu
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Kdo ga objavlja in kje se nahaja njegova koda
metrics, atlas Dva namerno odprta objekta za vaša lastna imena metrik in generiranje arhitekturne dokumentacije

Česa shema ne more izraziti

JSON Schema določa obliko; definePlugin pa dodaja pravila, ki jih shema ne more izraziti. classification veščine ne sme preseči zgornje meje zaupanja. Samo vtičnika core in verified lahko deklarirata veščini tool_using in llm_only. Vsaka deklarirana pot mora biti relativna in istega izvora, brez sheme, brez // in brez obratne poševnice, ker razčlenjevalnik URL-jev pretvori \ v /, /\evil.example/x pa se razreši kot navzkrižni izvor. Vsako pravilo, ki ga sinhronizacija registra uporabi za veščino, se najprej uporabi tukaj, z lastno kodo sinhronizacije, tako da validate in sinhronizacija poimenujeta kršeno pravilo na enak način.

Preverjanje veljavnosti in prehod z različice 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

Ob neuspehu se izpiše natančna pot, pri pravilu sinhronizacije pa najprej koda. Nastavite to kot kavljec ob uveljavitvi (commit hook).

Manifest v1 se nadgradi mehansko. migrate doda tri stavke zakonov, premakne domain v domains[] in zavrne izmišljanje vstopne točke, ki je niste imeli. Rezultat preveri, preden kar koli izpiše ali zapiše, tako da migracija nikoli ne prenese napake iz orodja v vaš repozitorij.

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

Pred uveljavitvijo preberite izpis razlik (diff). Stavki zakonov, ki jih doda, so ubeseditev, ki jo zahteva validator; za lastno namestitev nastavite deploy na prej prikazani stavek.

Izris večnajemništva in dodeljevanje vlog

Dodelitev vlog ali predloge varnosti na ravni vrstic nikoli ne pišete ročno. nexus-tenancy render jih zapiše iz schema in db v manifestu:

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

Izrisana datoteka ustvari pet vlog za shemo, vsako s tistim, česar ne sme imeti: migratorja, ki lahko postane le lastnik, lastnika, ki se ne more prijaviti, vlogo aplikacije za pot zahteve, vlogo za poročanje, ki vidi le agregate, in vlogo glavne knjige, ki lahko le dodaja. Nobena vloga nima BYPASSRLS. Edini način za vezavo najemnika je ena funkcija podatkovne baze, set_config pa je odvzet vsem vlogam razen lastniku.

Uveljavljena datoteka za večnajemništvo se nikoli ne ureja. Sprememba je revizija z lastno datoteko številka 0, in bralni sedež za dodelitve pravic med organizacijami prispe na ta način, kot revizija 2. --graph izriše dve tabeli tipiziranega grafa, ki ju deklarira vaš ontology, kot vašo naslednjo oštevilčeno migracijo.

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 večnajemništvo ustvari prav tiste vloge, kot katere se poveže zaganjalnik, zato jo uveljavi lastnik podatkovne baze z 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 povezovalni niz za lastnika podatkovne baze, <dir> pa je zasebni imenik. Zagotavljanje (provision) uveljavi osnovno datoteko za večnajemništvo in vsako revizijo po vrstnem redu, zapiše migrator.url in app.url (ter seat.url, ko obstaja revizija 2) v <dir> z načinom 0600 in ne izpiše nobenih skrivnosti. Ob vsakem zagonu nastavi omejitev povezav vsake vloge iz db.maxConnections × db.pods. Ponovni zagon ohrani obstoječa gesla, razen če zahtevate drugače: --passwords <dir> jih nastavi iz datotek, --rotate <roles> pa imenovanim vlogam dodeli nova. Pretvorite datoteke v skrivnosti svoje namestitve.

Po tem se uveljavljanje poveže s povezovalnim nizom migratorja, ki ga je zapisal postopek zagotavljanja:

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

Kot migrator zažene datoteke od 001 naprej, vsako datoteko pod SET ROLE <schema>_owner, po eno transakcijo na datoteko. Vzdržuje glavno knjigo, <schema>.schema_migrations, s kontrolno vsoto vsake datoteke; uveljavljena datoteka, katere bajti so se spremenili, se zavrne po imenu (CHECKSUM_DRIFT), nikoli se ne zažene ponovno in nikoli se ne preskoči. Vsaka čakajoča datoteka se pred zagonom prve razčleni z resnično slovnico Postgres, tako da zavrnitev pusti podatkovno bazo nedotaknjeno. Edina glava, ki jo datoteka lahko vsebuje, je -- nexus-migration: transaction=file|per-statement, z izbirnima časovnima omejitvama zaklepanja in stavka; per-statement je namenjen za CREATE INDEX CONCURRENTLY.

Kontrolne točke

nexus-gates zažene dvaindvajset vrat. Vsaka kodirajo en razred napak, da se ta ne more izdobaviti dvakrat, in vsaka imajo samotest, ki dokaže, da padejo na testnem primeru, zgrajenem za njihovo sprožitev. Zaženite jih pred potiskanjem kode:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Vrata Kaj ujamejo
scope-adherence Pot /api brez varovala obsega; anonimno pot, ki ni natančno deklarirana; pot naprave brez varovala naprave ali z varovalom osebe ob njej
one-fence Predikat najemnika, definiran kjer koli drugje kot na enem samem mestu, vključno z ročno napisano ograjo za sedež ali dodelitev pravic
sql-fence Stavek, ki bere ali posodablja tabelo z omejenim obsegom brez ograje, v katerem koli cilju FROM, JOIN, USING ali UPDATE
migrations-are-scoped Tabelo, ki ji manjka os, sestavljeni ključ z vodilnim najemnikom, tuji ključ, ki prenaša najemnika, ali predstavitveni stolpec
migrations-commit-what-they-open Migracijo, katere število BEGIN se ne ujema s številom njenih COMMIT in ROLLBACK
no-direct-compute Neposreden klic ponudnika modela, pogona, čakalne vrste ali gostitelja delovnega toka; drugega bralca URL-ja za razpošiljanje
no-credentials Poverilnico ponudnika modela, berljivo v repozitoriju ali okolju
crud-adherence Spreminjajočo pot, katere preverjanje pravic ne imenuje ničesar v registru
blocked-backends Pot, ki ni niti strežena, niti blokirana po imenu, niti zavrnjena po zakonu, niti v lasti drugje
every-test-runs Teste, ki jih vzorec glob testnega skripta nikoli ne doseže
tiles-are-invariant Predpomnjeni spoj, neodvisen od najemnika, ki bere vrednost najemnika ali preskoči avtentikacijo
api-contract Registrirano pot, ki je manifest ne deklarira, ali deklarirano pot, ki je koda nikoli ne registrira
rls-present Tabelo brez vsiljene varnosti na ravni vrstic; funkcijo SECURITY DEFINER brez pripetega search_path
no-set-config Kodo vtičnika, ki sama veže nastavitev najemnika
db-role-honest Pot zahteve, ki se povezuje kot lastnik ali migrator ali zahteva SUPERUSER oziroma BYPASSRLS
platform-clients Odjemalca SDK, ki je uvožen, a ni naveden v backend.platformClients, ali je naveden, a nikoli uvožen
rights-register Pot obsega brez deklarirane pravice; preverjanje pravic mimo registra
refusal-ledger Deklarirano tabelo zavrnitev brez nameščene glavne knjige ali telo zavrnitve, poslano mimo nje
grants-declared Tabelo z dodeljenimi pravicami, ki je manifest ne deklarira; ročno podeljene privilegije bralnega sedeža
people-declared Blok people brez njegove poti za čiščenje, varovala in tabel
functions-closure Vtičnik Azure Functions, katerega strežene poti in deklarirane poti se ne ujemajo
declared-input Seznam parametrov poizvedbe obravnavalnika, ki se ne ujema z deklariranimi query poti

Imenik gates/ vsebuje pet datotek z izjemami, ki jih vrata lahko berejo (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json in invariant-seams.json), z enim razlogom na vnos. Prazen razlog šteje, kot da vnosa ni, vnos, ki imenuje nekaj, kar ne obstaja več, pa povzroči padec na vratih. Tja lahko odložite tudi lastne module vrat in nexus-gates jih bo pobral poleg vgrajenih.

Združljivost
Združljivost
Združljivost prikazuje, katera različica SDK deluje s katero različico platforme, na podlagi nočnih zagonov hitrega začetka. Nepreverjen par to izrecno navede, neuspešen par pa imenuje spremembo, ki je povzročila napako.

Cevovod predloge

Predloga ne vsebuje ročno napisanega delovnega toka. Njena konfiguracija cevovoda imenuje Dockerfile, edini argument gradnje (žeton registra), poskusni zagon migracije in sondo zagona ter vrata, ki jih zažene čakalna vrsta za združevanje. Vrstni red je takšen, v kakršnem bi želeli, da se napake zgodijo.

  1. npm ci
  2. npm run typecheck
  3. npm run build
  4. npm test
  5. npm run validate:manifest, kar je create-nexus-plugin validate nexus.manifest.json
  6. npm run gates, kar je nexus-gates --self-test
  7. node scripts/ci/required-env

Okoli slike se izvedeta še dve preverjanji. Preizkusni zagon migracije pred izdajo slike uveljavi vsako datoteko na začasnem Postgresu z istim izvajalcem, kot ga uporablja produkcija: nexus-migrate provision enkrat kot naduporabnik, nato pa vsako oštevilčeno datoteko kot migrator. Zagonska sonda zažene zgrajeno sliko z njeno lastno vstopno točko in vsako spremenljivko, ki jo izpiše required-env, usmerjeno v nadomestke, ki sprejemajo povezave in nikoli ne odgovorijo. Strežnik čaka na podatkovno bazo znotraj svojega omejenega časovnega okna, in to čakanje je znak za uspeh; nalagalnik konfiguracije, ki se noče zagnati, prekine gradnjo tam in ne v produkciji.

Gradnja v izdaji Community
Gradnja v izdaji Community
V izdaji Community razvijalec dobi enake uveljavljene poti (golden paths), razvojni prostor in podatkovne veje na enem strežniku ter kodo na lastnem gostitelju Git. Predprodukcijsko okolje, pilotne enote in zakrite kopije produkcijskih podatkov so vključeni v izdajo Enterprise.

Stroški

SDK vam odvzame odločitve, in nekatere izmed njih bi sami sprejeli drugače. Manifest zavrne ključe, ki jih ne pozna, tabela poti se mora natančno ujemati z vašo kodo, vloge v podatkovni bazi niso prepuščene vašemu načrtovanju, kontrolne točke pa prekinejo gradnjo zaradi manjkajoče pravice pri branju. Pri svojem prvem vtičniku sem porabil cel dan za prerekanje s api-contract glede poti, ki sem jo registriral, a pozabil deklarirati. Imel je prav; pot je bila nezaščitena. Pričakujte, da se bo izdelava prvega vtičnika zdela počasna, pri drugem pa pričakujte, da bo vzela tretjino tega časa.