Version 1.0.0-alpha.1seneste
Kapitel 2.21
Plugin SDK'et
Installation af Plugin SDK'et (softwareudviklingssættet), dets kommandolinjeværktøjer, en gennemgang af skabelonen til fuld tjeneste, v2-manifestet felt for felt og de 22 kontrolporte, der sikrer, at et plugin overholder reglerne.
Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

Mit andet plugin tog en tredjedel af den tid, mit første tog, og næsten hele besparelsen skyldtes SDK'et (softwareudviklingssættet). Den første gang skrev jeg et scope-tjek, en konfigurationsindlæser og en migreringskørsel, og en reviewer sendte dem alle sammen retur. Den anden gang kørte jeg én scaffold-kommando, slettede den medfølgende eksempel-skill til sentimentanalyse og brugte mine dage på de registreringer til anomaligennemgang, som vores flydynamikteam rent faktisk havde brug for.
@adverant-nexus/plugin-sdk er én samlet npm-pakke. Den indeholder v2-manifestskemaet og de validatorer, der læser det (definePlugin, defineSkill), de runtime-moduler, som dit plugin importerer til scope, database, dispatch og alt det øvrige, testhjælpere, overholdelses-gates (adherence gates) samt kommandolinjeværktøjerne. Dette kapitel dækker installation af pakken, værktøjerne, skabelonen, manifestet og gates. Kapitel 2.22, Plugin-runtime, dækker runtime-modulerne i din kørende kode.
Installation
Pakken kommer fra Adverants registry på https://registry.adverant.ai/npm/, aldrig fra det offentlige npm-registry, og du skal bruge det pull-token, der findes på din kontos side "Pull tokens and install commands". Peg @adverant-nexus-scopet mod dette registry i dit repositorys .npmrc:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> er det token, du henter fra din kontoside. I en pipeline skal du sende det ind fra en hemmelighed (secret) og aldrig committe det; skabelonens Dockerfile nægter at bygge uden det og sletter .npmrc fra byggetrinnet, så snart npm ci har kørt, så dette token aldrig leveres i et image.
Fastlås derefter versionen præcist:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Commit package-lock.json ved den første installation. Skabelonens image-build kører npm ci og nægter at falde tilbage på npm install: låsefilen er kontrakten. SDK'ets eget minimumskrav er Node 18; skabelonen er målrettet Node 20.
Kommandolinjeværktøjerne leveres inde i pakken, så enhver kommando i denne dokumentation angiver pakken og dens version med npx -p. Alene bliver npx create-nexus-plugin slået op i det offentlige registry, og det navn er ikke denne pakke.
Kommandolinjeværktøjerne
| Værktøj | Hvad den gør |
|---|---|
create-nexus-plugin |
Scaffolder et plugin, validerer et manifest, migrerer et v1-manifest til v2 og genererer brugervejledningen til din frontend-udvikler |
nexus-tenancy |
Genererer dit skemas tenant-SQL ud fra manifestet: roller, tildelinger (grants), skabelonen til sikkerhed på rækkeniveau (row-level security) og graftabellerne |
nexus-migrate |
Anvender dine migreringer: provisionerer rollerne én gang og kører derefter hver nummereret fil som migrator-rollen |
nexus-gates |
Kører hver overholdelses-gate samt hver gates egen selvtest |
create-nexus-plugin foretager ingen netværkskald og indlæser ingen ekstern kode. Det kører de samme interne validatorer i processen, som platformens onboarding kører, så der ikke opstår uoverensstemmelse mellem "det validerede på min maskine" og "platformen accepterede det".
| Kommando | Flag | Hvad den gør | Afslutningskoder |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Skriver en ny plugin-mappe; --print udskriver kun manifestet |
0 skrevet · 1 nægtede at overskrive · 2 forkert brug |
validate <file> |
Validerer en nexus.manifest.json eller et .ts- eller .js-modul, der eksporterer en |
0 gyldig · 1 ugyldig eller ulæselig · 2 forkert brug | |
migrate <file> |
--write |
Løfter et v1-manifest til v2 og udskriver det eller skriver det på stedet | 0 · 1 · 2, som ovenfor |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genererer brugervejledningen ud fra manifestet og din beskrivelse; --check sammenligner med den committede kopi og skriver intet |
0 · 1 afvigelse (drift) eller en lint-fejl · 2 forkert brug |
help |
Udskriver brugsvejledning | 0 |
Stilladsopbygning og de tre niveauer
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier har full-service som standard. Scaffolderen nægter at skrive til en mappe, der allerede findes, og det manifest, den skriver, består allerede valideringen; den udsteder aldrig et ugyldigt manifest.
Vælg niveau (tier) ud fra, hvad dit plugin indeholder.
| Niveau | Indeholder | Skal deklarere |
|---|---|---|
skills-only |
Manifest-skills og intet andet | skills[], med mindst én post |
ui-only |
En frontend-flade inde i skallen | frontend |
full-service |
En backend og en frontend, normalt med sit eget skema | backend og frontend; og fordi det har en backend, runtime.healthCheck |
Hvis du er i tvivl, så scaffold full-service og slet det, du ikke har brug for. At gå den modsatte vej betyder, at du selv skal skrive de dele, som skabelonen ville have givet dig.
En gennemgang af skabelonen til fuld tjeneste
Skabelonen er reference-pluginet, bygget efter det strikse mønster, som alle efterfølgende kapitler forudsætter. Klon dens form, ikke dens eksempellogik.
| Sti | Hvad det er |
|---|---|
nexus.manifest.json |
v2-manifestet: de tre love gentaget, rutetabellen og dens rettighedsregister |
src/config.ts |
Konfigurationsindlæseren. Én specifikation, læst én gang, hvor ethvert problem indsamles, før processen nægter at starte op |
src/scope.ts |
Den ene fil, der omdanner en forespørgsel til et scope, med SDK'ets strikse token-verifikator og to regimer: en persons ihændehaver-token (bearer token) og platformens servicekald |
src/db.ts |
Hvert udtryk (statement) sammensætter tenantFence() og kører inden i withScopedTx |
src/uno.ts |
Den ene dispatch-fil: én URL, én klient, en lukket tilladelsesliste (allow-list) |
src/routes/*.ts |
health (anonym, eksakt sti), /api-ruterne (i scope) og /internal-callbacket (service-beskyttet) |
src/skills/sentiment.ts |
En deterministisk host_callback-skill; erstat ordlisten med din egen logik |
src/server.ts |
Kompositionsroden: installerer afvisningsprotokollen (refusal ledger) én gang, venter på databasen (tidsbegrænset) og kører derefter isolations- og protokol-tjekkene, før den lytter |
migrations/000_tenancy.sql |
Genereret af nexus-tenancy render på scaffold-tidspunktet: roller, skema, skabelonen til sikkerhed på rækkeniveau (row-level security) |
migrations/001_init.sql |
To tabeller med en sammensat nøgle med tenant forrest og en sammensat, tenant-bærende fremmednøgle |
migrations/002_refusal_ledger.sql |
Den tabel, som afvisningsprotokollen skriver til |
scripts/ci/required-env |
Udskriver navnene på de miljøvariabler, der kræves ved opstart, som JSON |
scripts/ci/shadow-migrate-*.sh |
Pipelinens prøvekørsel (dry run) af migrering, gennem nexus-migrate |
gates/ |
Gates' undtagelsesmappe: tom, hvilket er den korrekte tilstand for et nyt plugin |
test/ |
Tests for scope, ruter, database, dispatch og opstart, med de scope-attrapper (doubles), som hver test injicerer |
Dockerfile |
Et ikke-root-image (bruger-ID 10001) med migreringerne indeni |
Et par af disse filer er værd at se nærmere på.
src/config.ts følger to regler. Den indsamler ethvert problem, før den kaster en fejl, så én genstart nævner alle fem manglende variabler i stedet for fem genstarter, der nævner én hver. Og den angiver kun en standardværdi, når en forkert værdi ikke kan frembringe et tavst forkert svar: PORT må gerne have standardværdien 8080, fordi en forkert port fejler bindingen synligt, mens DATABASE_URL og UNO_DISPATCH_URL er påkrævede og skal være interne klyngeadresser. En offentlig adresse afvises ved opstart.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Skabelonens egen test kører den pågældende fil og sammenligner dens output med de navne, som konfigurationsspecifikationen markerer som påkrævede, så hvis man tilføjer en påkrævet variabel uden at opdatere listen, fejler npm test.
src/server.ts lytter ikke, før databasen svarer, og den begrænser ventetiden til 120 sekunder, idet hvert mislykket forsøg logges med sin årsag. Derefter beviser den i rækkefølge, at app-rollen ikke kan genbinde tenanten, og at hver tabel er tvunget under sikkerhed på rækkeniveau (row-level security), at hver pods pulje passer inden for rollens forbindelsesgrænse, og at afvisningsprotokollens tabel kan modtage en række. En afvisning fra en hvilken som helst af de tre udskrives i sin helhed, og processen afslutter med kode 2.
v2-manifestet, felt for felt
Manifestet er pluginets maskinlæsbare kontrakt med platformen. Det valideres, når du skriver det, når platformen onboarder det, og løbende derefter. Skemaet er additionalProperties: false på hvert niveau: hvis dit plugin har en sektion, er der en egenskab (property) til den, og en ikke-deklareret nøgle afvises. Løsningen er altid at bruge den rette valgfrie egenskab.
Den påkrævede kerne
| Felt | Regel |
|---|---|
manifestVersion |
Præcis "2". Et v1-dokument migreres og genvalideres aldrig på stedet |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, højst 64 tegn. Det plugin-id, der bruges ved registrering, dispatch-namespacing og tenant-afgrænsede rækker. Et plugin, der deklarerer skills, skal også have et navn uden punktum og uden foranstillet ciffer |
displayName |
1 til 120 tegn |
version |
Semantisk version; dit eget udgivelsesforløb |
description, author, license |
Mindst ét tegn hver |
tier |
skills-only, ui-only eller full-service |
trust |
core, verified, community eller untrusted |
runtime |
Påkrævet: executionMode, isolationLevel (1 til 4), entrypoint. Valgfrit: nodeVersion, healthCheck, readinessCheck, livenessCheck, hver især en sti, der starter med /. Tilstanden udledes af niveauet: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai og deploy, de tre platformslove gentaget. Validatoren fastlåser ordlyden |
For et plugin, du bygger til din egen installation, lyder de tre sætninger som følger. ai-sætningen dækker kunstig intelligens (AI) og er det sted, hvor det angives, at pluginet ikke ligger inde med nogen model-legitimationsoplysninger.
"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."
}Rutetabellen: api og rights
api kræver version og basePath, og valgfrit websocket (path, auth) samt endpoints[]. Rutetabellen er den stærkeste idé i skemaet: en gate sammenligner den (differ) med de ruter, din kode reelt registrerer, i begge retninger, så manifestet er en kontrollerbar kontrakt og ikke dokumentation.
Hvert endpoint kræver method (GET, POST, PUT, PATCH eller DELETE) og path. Resten:
| Felt | Hvad der står i den |
|---|---|
auth |
En af fem klasser: scope (en persons rute, bag scope-guarden), service-key og internal (server til server, kan aldrig nås fra en browser), public (altid kun en eksakt sti med allowAnonymous) og device (en maskine med sine egne legitimationsoplysninger, bag enheds-guarden) |
right |
Påkrævet på enhver rute, som scope-guarden betjener, og afvist på alle andre: navnet på en rettighed i rights-registret |
needsUnit |
Ruten afviser, når kalderens enhed (unit) ikke kan bestemmes |
allowAnonymous |
Kun tilladelsesliste med eksakt match. En præfiksregel er måden, hvorpå /health-of-tenant-42 ender med at blive offentlig |
group, serves, screens |
Under en release-blok: den kapabilitetsgruppe, ruten betjener, hvad den svarer, når den pågældende gruppes licenserede funktion er låst (data, teaser, sighting eller ask), og de skærmbilleder, den betjener |
query |
required (hvert navn med en eksempelværdi) og allowed: de forespørgselsparametre (query parameters), som ruten læser |
body |
example: en skriverutes eksempel-body, som dens egen validator accepterer. Aldrig på en GET |
rights er det register, som disse ruter henviser til. Hver rettighed har roles (loftet) og valgfrit summary, never (roller, der aldrig må udøve den, uanset hvad de ellers har), barred (produktets egne ord for at afvise en never-rolle), seat (et aktivt sæde (seat) er også nødvendigt), self (enhver verificeret person har den, for rettigheder over deres egen session), grants (indehavere tildeler sæder; højst én rettighed angiver dette), licence (en licenseret funktion, som organisationens licens skal indeholde) installation (indehaves kun af installationens egne administratorer) og platform (indehaves kun af Adverants platformsadministratorer; den angiver ingen roller). Rettighedsnavne har mindst ét punktum: 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 afviser en scope-rute uden rettighed (ENDPOINT_RIGHT_MISSING), en rettighed, som mangler i registret (ENDPOINT_RIGHT_NOT_REGISTERED), og en rettighed på en rute, som ingen guard betjener (ENDPOINT_RIGHT_UNGUARDED). Den afviser også et register, der modsiger sig selv, samt to stavemåder af samme rute (:id og :recordId) som DUPLICATE_ENDPOINT.
Dine data: databases, schema og db
schema er det ene Postgres-skema, som pluginet ejer. public, plugins, auth og nexus er forbudte, og hvis databases[] også angiver et Postgres-skema, skal de to stemme overens.
databases[] deklarerer hvert datalager efter motor: postgresql (schema, tables, migrations og granted, de tabeller, en anden organisation må læse under en registreret tildeling), neo4j (schemas), qdrant (collections) eller redis (purpose).
db indeholder sessionsgrænserne for hver forbindelse, pluginet åbner, deklareret her frem for kodet, så både en reviewer og udrulningen (deployment) kan læse dem:
| Felt | Hvad den begrænser |
|---|---|
maxConnections |
Puljen pr. replika |
pods |
Det højeste antal pods, der holder en pulje på én gang, replikaer plus en rullende opdaterings spidsbelastning (surge). Hver rolles forbindelsesgrænse genereres som maxConnections × pods; udelades den, advarer definePlugin med DB_PODS_UNDECLARED |
statementTimeoutMs |
Ét udtryk (statement) |
idleInTransactionTimeoutMs |
En åben transaktion, der intet kører |
workMemKB |
Én sorterings- eller hash-node, pr. node, ikke pr. forespørgsel |
piiMask[] |
table.column-poster, der indeholder persondata, maskeret i den styrede SQL-konsol og i logfiler |
Skills og værktøjer: skills, mcpTools, entitlements
skills[] indeholder manifest-skills; kapitel 2.20, Skills, dækker deres felter og niveauer. mcpTools[] indeholder de MCP-værktøjer (Model Context Protocol), som pluginet udgiver, hver med en name, en description og en inputSchema uden oneOf, allOf eller anyOf på øverste niveau.
entitlements kræver featureIdPattern og accepterer alwaysOn[], source og store. Mønstret navngiver det namespace, dine funktions-id'er (feature ids) bor i, konventionelt pluginets name plus ét segment, som din kode udfylder pr. flade. alwaysOn[] er den korte, eksakte liste, der skal svare, selv når der ikke kan opnås en rettighedsafgørelse (entitlement verdict): sundhed (health), parathed (readiness), log-ind og de indstillinger, en administrator har brug for til at reparere rettigheden.
Ændringsstyring: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Godkendelser tælles i forskellige personer, og den person, der foreslog ændringen, er aldrig en af dem; uden begge dele bliver "to godkendelser" til én person, der klikker to gange. enabled: true kræver classes, og hver nævnt klasse kræver sit eget antal. En klasse, du udelader, er ureguleret, hvilket er et legitimt valg, som skemaet tvinger dig til at skrive ned.
Hvem du er: domains, branding, routing
domains[] (hver med primary og aliases[]; domain er formen til et enkelt domæne) angiver, hvor pluginet svarer. branding kræver appName og accepterer tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId og gaId. Alt i branding er offentligt: log-ind-siden læser det, før nogen har legitimationsoplysninger, så det indeholder aldrig en hemmelighed (secret) eller en intern adresse. routing (type, gateway, virtualService) er til plugins, der beskriver deres egen routing.
Dimensionering og resten
resources kræver cpuMillicores (10 til 64.000) og memoryMB (16 til 262.144), og accepterer diskGB, timeoutMs, port og wsPort. backend indeholder port, healthPath, apiPrefix, framework og platformClients[], de SDK-klienter, din backend importerer ved navn. Listen er lukket, og en gate tjekker den op imod dine importer. Skemaet tillader fjorten navne: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin og uno, plus ét for den klient, der besvarer afvisninger af abonnementsrettigheder (plan-entitlement), som beholder et internt navn. Klienten til funktionsrettigheder (feature-entitlement), runtime/entitlements, er ikke en af dem og kommer aldrig på listen, fordi din entitlements-blok allerede deklarerer den, og en backend, der importerer den uden en entitlements-blok, fejler den samme gate. frontend indeholder basePath, mountPath og framework. nexus indeholder minVersion, maxVersion, capabilities[] og permissions[].
De resterende blokke er der hver især til én opgave:
| Blok | Til |
|---|---|
settings |
Dine indstillinger på det delte framework: groups og keys, indstillet på de niveauer, hver især nævner |
people |
sweep (service, port): organisationens medlemmer, synkroniseret fra identitetstjenesten, hvor sæder slås fra, når nogen forlader organisationen |
ontology |
entityTypes og relationshipTypes: den typede graf, der opbevares i dit eget skema |
release |
groups og frame: de kapabilitetsgrupper, dine ruter er inddelt i, og som frigives først som en canary |
cells[] |
Et plugin, der består af flere udrulningsenheder (deployables): name, kind, entrypoint, port, wsPort hver |
pricing |
model, currency, tiers[] til din katalogvisning |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Hvem der udgiver det, og hvor dets kode bor |
metrics, atlas |
De to bevidst åbne objekter, til dine egne metriknavne og generering af arkitekturdokumentation |
Hvad skemaet ikke kan udtrykke
JSON-skemaet fastlægger formen; definePlugin tilføjer de regler, et skema ikke kan udtrykke. En skills classification kan ikke overstige tillidsloftet (trust ceiling). Kun core- og verified-plugins må deklarere tool_using- og llm_only-skills. Enhver deklareret sti skal være relativ og af samme oprindelse (same-origin), uden protokol (scheme), uden // og uden omvendt skråstreg (backslash), fordi URL-parseren folder \ til /, og /\evil.example/x fortolkes på tværs af oprindelser (cross-origin). Enhver regel, som registry-synkroniseringen anvender på en skill, anvendes her først med synkroniseringens egen kode, så validate og synkroniseringen navngiver en brudt regel på samme måde.
Validering og overgang fra 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
En fejl udskriver den præcise sti og, for en synkroniseringsregel, koden først. Gør det til et commit-hook.
Et v1-manifest løftes mekanisk. migrate tilføjer de tre lovsætninger, flytter domain til domains[] og nægter at opfinde et entrypoint, du ikke havde. Det validerer resultatet, før det udskriver eller skriver noget som helst, så en migrering aldrig flytter en fejl fra værktøjet ind i dit repository.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLæs diff'en, før du committer den. De lovsætninger, den tilføjer, er den ordlyd, validatoren fastlåser; for din egen installation skal du sætte deploy til den sætning, der blev vist tidligere.
Rendering af lejerforholdet og klargøring af rollerne
Du skriver aldrig dine rolletildelinger (role grants) eller skabelonen til sikkerhed på rækkeniveau (row-level security) i hånden. nexus-tenancy render skriver dem ud fra manifestets schema og db:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlDen genererede fil opretter fem roller til skemaet, hver med det, den ikke må indeholde: en migrator, der kun kan blive ejer, en ejer, der ikke kan logge ind, en app-rolle til forespørgselsstien, en rapportrolle, der kun ser aggregeringer, og en protokolrolle (ledger role), der kun kan tilføje (append). Ingen rolle har BYPASSRLS. Den eneste måde at binde en tenant på er én databasefunktion, og set_config er tilbagekaldt fra alle roller undtagen ejeren.
En anvendt tenant-fil redigeres aldrig. En ændring er en revision med sin egen nummer-0-fil, og læsesædet til tildelinger på tværs af organisationer ankommer på den måde, som revision 2. --graph genererer de to tabeller i den typede graf, som din ontology deklarerer, som din næste nummererede migrering.
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.sqlTenant-filen opretter netop de roller, som migreringskørslen forbinder som, så den anvendes af databaseejeren med 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> er en forbindelsesstreng for databaseejeren, og <dir> er en privat mappe. Provisioneringen anvender basis-tenant-filen og hver revision i rækkefølge, skriver migrator.url og app.url (samt seat.url, når revision 2 findes) ind i <dir> med tilstanden 0600 og udskriver intet hemmeligt. Den indstiller hver rolles forbindelsesgrænse ud fra db.maxConnections × db.pods ved hver kørsel. En genkørsel beholder eksisterende adgangskoder, medmindre du beder om andet: --passwords <dir> indstiller dem fra filer, og --rotate <roles> giver de nævnte roller friske adgangskoder. Omdan filerne til din udrulnings hemmeligheder (secrets).
Derefter forbinder selve anvendelsen med migratorens forbindelsesstreng, som provisioneringen skrev:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonDen kører filerne fra 001 og fremefter som migrator, hver fil under SET ROLE <schema>_owner, én transaktion pr. fil. Den fører en protokol, <schema>.schema_migrations, med hver fils kontrolsum; en anvendt fil, hvis bytes er ændret, afvises ved navn (CHECKSUM_DRIFT), genkøres aldrig og springes aldrig over. Hver ventende fil parses med den ægte Postgres-grammatik, før den første kører, så en afvisning efterlader databasen uberørt. Den eneste header, en fil må bære, er -- nexus-migration: transaction=file|per-statement, med valgfrie låse- og udtryks-timeouts (statement timeouts); per-statement er til CREATE INDEX CONCURRENTLY.
Kontrolportene
nexus-gates kører toogtyve gates. Hver indkoder én klasse af defekter, så den ikke kan leveres to gange, og hver har en selvtest, der beviser, at den fejler på en testopstilling (fixture), der er bygget til at udløse den. Kør dem, før du pusher:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Kontrolpunkt | Hvad den fanger |
|---|---|
scope-adherence |
En /api-rute uden scope-guarden; en anonym sti, der ikke er en eksakt deklareret sti; en enhedsrute uden enheds-guarden eller med en persons guard ved siden af |
one-fence |
Et tenant-prædikat defineret et hvilket som helst andet sted end ét bestemt sted, herunder et hjemmelavet sæde- eller tildelingshegn (grant fence) |
sql-fence |
Et udtryk, der læser eller opdaterer en tabel i scope uden hegnet, i et hvilket som helst FROM-, JOIN-, USING- eller UPDATE-mål |
migrations-are-scoped |
En tabel, der mangler en akse, en sammensat nøgle med tenant forrest, en tenant-bærende fremmednøgle eller demokolonnen |
migrations-commit-what-they-open |
En migrering, hvis antal af BEGIN ikke matcher dens antal af COMMIT og ROLLBACK |
no-direct-compute |
Et direkte kald til en modeludbyder, motor, kø eller workflow-vært; en ekstra læser af dispatch-URL'en |
no-credentials |
En legitimationsoplysning til en modeludbyder, der kan læses i repositoryet eller miljøet |
crud-adherence |
En muterende rute, hvis rettighedstjek ikke nævner noget i registret |
blocked-backends |
En rute, der hverken betjenes, blokeres ved navn, afvises ved lov eller ejes andetsteds |
every-test-runs |
Tests, som testscriptets glob-mønster aldrig når |
tiles-are-invariant |
En tenant-invariant cachet samling (seam), der læser en tenant-værdi eller springer autentificering over |
api-contract |
En registreret rute, som manifestet ikke deklarerer, eller en deklareret rute, som koden aldrig registrerer |
rls-present |
En tabel uden tvungen sikkerhed på rækkeniveau (row-level security); en SECURITY DEFINER-funktion uden en fastlåst search_path |
no-set-config |
Plugin-kode, der selv binder tenant-indstillingen |
db-role-honest |
En forespørgselssti, der forbinder som ejer eller migrator, eller som beder om SUPERUSER eller BYPASSRLS |
platform-clients |
En SDK-klient, der er importeret, men ikke opført i backend.platformClients, eller opført, men aldrig importeret |
rights-register |
En scope-rute uden en deklareret rettighed; et rettighedstjek ved siden af registret |
refusal-ledger |
En deklareret afvisningstabel uden en installeret protokol (ledger), eller en afvisnings-body sendt uden om den |
grants-declared |
En tildelt tabel, som manifestet ikke deklarerer; læsesæde-privilegier uddelt i hånden |
people-declared |
En people-blok uden dens oprydningsrute (sweep route), guard og tabeller |
functions-closure |
Et Azure Functions-plugin, hvis betjente ruter og deklarerede ruter er uenige |
declared-input |
En handlers liste over forespørgselsparametre, der ikke matcher rutens deklarerede query |
Mappen gates/ indeholder de fem undtagelsesfiler, en gate må læse (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json og invariant-seams.json), én begrundelse pr. post. En tom begrundelse tæller som ingen post, og en post, der nævner noget, der ikke længere eksisterer, får gaten til at fejle. Du kan også lægge dine egne gate-moduler der, hvorefter nexus-gates samler dem op sammen med de indbyggede.
Skabelonens pipeline
Skabelonen leveres uden noget håndskrevet workflow. Dens pipeline-konfiguration angiver Dockerfilen, det ene byggeargument (registry-tokenet), prøvekørslen af migreringen samt opstartsproben og den gate, som merge-køen kører. Rækkefølgen er den rækkefølge, du ønsker at fejle i.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, hvilket ercreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, hvilket ernexus-gates --self-testnode scripts/ci/required-env
To yderligere tjek kører omkring imaget. Prøvekørslen af migreringen anvender hver fil på en midlertidig Postgres, før imaget kan frigives, med den samme runner som produktionen bruger: nexus-migrate provision én gang som superbruger, derefter hver nummereret fil som migrator. Boot-proben starter det byggede image med sit eget entrypoint og hver variabel, som required-env udskriver, rettet mod attrapper, der accepterer forbindelser og aldrig svarer. Serveren venter på databasen inden for sit afgrænsede tidsvindue, og denne ventetid er signalet for en bestået test; en konfigurationsindlæser, der nægter at boote, får buildet til at fejle dér og ikke i produktion.
Hvad det koster
SDK'et tager beslutninger fra dig, og nogle af dem ville du have truffet anderledes. Manifestet afviser nøgler, det ikke kender, rutetabellen skal matche din kode nøjagtigt, databaserollerne er ikke dine at designe, og kontrollerne dumper et build ved en manglende rettighed på en læsning. På mit første plugin brugte jeg en dag på at diskutere med api-contract om en rute, jeg havde registreret og glemt at deklarere. Den havde ret; ruten var ubeskyttet. Forvent, at det første plugin føles langsomt, og forvent, at det andet tager en tredjedel af tiden.

