Log indBook en briefing

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

22 minutters læsetid

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

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

Læ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.sql

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

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

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

Kompatibilitet
Kompatibilitet
Kompatibilitet viser, hvilken SDK-version der fungerer med hvilken platformsversion, ud fra natlige kørsler af quickstarten. Et utestet par angiver dette, og et fejlende par nævner den ændring, der ødelagde det.

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.

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

Udvikling på Community
Udvikling på Community
På Community får en udvikler de samme gyldne stier, et udviklingsmiljø og dataforgreninger på én server, med kode hos deres egen Git-udbyder. Staging, pilotenheder og maskerede kopier af livedata følger med Enterprise.

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.