Versjon 1.0.0-alpha.1nyeste
Kapittel 2.21
Plugin SDK
Installere Plugin SDK (programvareutviklingssett), kommandolinjeverktøyene, en gjennomgang av fullservicemalen, v2-manifestet felt for felt, og de tjueto portene som sikrer at et programtillegg følger reglene.
Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

Det andre programtillegget mitt tok en tredjedel av tiden det første tok, og nesten hele besparelsen kom fra SDK-et (programvareutviklingssettet). Den første gangen skrev jeg en omfangssjekk, en konfigurasjonsinnleser og en migreringskjører, og en kontrollør sendte hver eneste en av dem i retur. Den andre gangen kjørte jeg én stillaskommando, slettet eksempelferdigheten for sentimentanalyse, og brukte dagene på de avviksgjennomgangspostene som flydynamikkteamet vårt faktisk trengte.
@adverant-nexus/plugin-sdk er én npm-pakke. Den inneholder v2-manifestskjemaet og validatorene som leser det (definePlugin, defineSkill), kjøretidsmodulene som programtillegget ditt importerer for omfang, database, utsendelse og resten, testhjelpere, etterlevelsesportene og kommandolinjeverktøyene. Dette kapittelet dekker installasjon av den, verktøyene, malen, manifestet og portene. Kapittel 2.22, Kjøretidsmiljøet for programtillegg, dekker kjøretidsmodulene i den kjørende koden din.
Installere det
Pakken kommer fra Adverants register på https://registry.adverant.ai/npm/, aldri fra det offentlige npm-registeret, og du trenger pull-tokenet fra kontoens side «Pull-tokener og installasjonskommandoer». Pek @adverant-nexus-omfanget mot registeret i kodelagerets .npmrc:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> er tokenet fra kontosiden din. I en pipeline sender du det inn fra en hemmelighet og sjekker det aldri inn; malens Dockerfile nekter å bygge uten det og sletter .npmrc fra byggetrinnet så snart npm ci har kjørt, slik at tokenet aldri sendes ut i et avtrykk.
Lås deretter versjonen nøyaktig:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Sjekk inn package-lock.json ved første installasjon. Malens avtrykksbygging kjører npm ci og nekter å falle tilbake til npm install: låsefilen er kontrakten. SDK-ets egen nedre grense er Node 18; malen er rettet mot Node 20.
Kommandolinjeverktøyene leveres inne i pakken, så hver kommando i denne dokumentasjonen navngir pakken og dens versjon med npx -p. Alene blir npx create-nexus-plugin slått opp i det offentlige registeret, og det navnet er ikke denne pakken.
Kommandolinjeverktøyene
| Verktøy | Hva den gjør |
|---|---|
create-nexus-plugin |
Setter opp et stillas for et programtillegg, validerer et manifest, migrerer et v1-manifest til v2, og genererer forbrukerveiledningen for frontend-utvikleren din |
nexus-tenancy |
Genererer skjemaets leietaker-SQL fra manifestet: roller, tildelinger, malen for sikkerhet på radnivå og graftabellene |
nexus-migrate |
Tar i bruk migreringene dine: klargjør rollene én gang, og kjører deretter hver nummererte fil som migratorrollen |
nexus-gates |
Kjører hver etterlevelsesport og hver ports egen selvtest |
create-nexus-plugin gjør ingen nettverkskall og laster ingen ekstern kode. Det kjører de samme interne prosessvalidatorene som plattformens innrullering kjører, slik at det ikke oppstår noe avvik mellom «det validerte på maskinen min» og «plattformen godtok det».
| Kommandoord | Flagg | Hva den gjør | Avslutningskoder |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Skriver en ny katalog for programtillegget; --print skriver bare ut manifestet |
0 skrevet · 1 nektet å overskrive · 2 feil bruk |
validate <file> |
Validerer en nexus.manifest.json, eller en .ts- eller .js-modul som eksporterer en |
0 gyldig · 1 ugyldig eller uleselig · 2 feil bruk | |
migrate <file> |
--write |
Løfter et v1-manifest til v2 og skriver det ut, eller skriver det på stedet | 0 · 1 · 2, som ovenfor |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genererer forbrukerveiledningen fra manifestet og teksten din; --check sammenligner med den innsjekkede kopien og skriver ingenting |
0 · 1 avvik eller et lint-brudd · 2 feil bruk |
help |
Skriver ut bruksanvisning | 0 |
Stillasbygging og de tre nivåene
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier har full-service som standard. Stillasverktøyet nekter å skrive til en katalog som allerede finnes, og manifestet det skriver, består allerede valideringen; det produserer aldri et ugyldig manifest.
Velg nivået ut fra hva programtillegget ditt inneholder.
| Nivå | Har | Må deklarere |
|---|---|---|
skills-only |
Manifestferdigheter og ingenting annet | skills[], med minst én oppføring |
ui-only |
En frontend-flate inne i skallet | frontend |
full-service |
En backend og en frontend, vanligvis med sitt eget skjema | backend og frontend; og fordi den har en backend, runtime.healthCheck |
Hvis du ikke er sikker, generer stillas for full-service og slett det du ikke trenger. Å gå den andre veien betyr at du må skrive delene malen ville ha gitt deg.
En gjennomgang av fullservicemalen
Malen er referanseprogramtillegget, bygget etter det strenge mønsteret som hvert senere kapittel forutsetter. Klon formen, ikke eksempellogikken.
| Sti | Hva det er |
|---|---|
nexus.manifest.json |
v2-manifestet: de tre lovene gjengitt, rutetabellen og dens rettighetsregister |
src/config.ts |
Konfigurasjonsinnleseren. Én spesifikasjon, lest én gang, hvert problem samlet inn før prosessen nekter å starte opp |
src/scope.ts |
Den ene filen som gjør en forespørsel om til et omfang, med SDK-ets strenge tokenverifikator og to regimer: en persons ihændehavertoken og plattformens tjenestekall |
src/db.ts |
Hver setning bygger opp tenantFence() og kjører inne i withScopedTx |
src/uno.ts |
Den ene utsendelsesfilen: én URL, én klient, en lukket tillatelsesliste |
src/routes/*.ts |
health (anonym, eksakt sti), /api-rutene (omfangsbegrensede) og /internal-tilbakekallet (tjenestebeskyttet) |
src/skills/sentiment.ts |
En deterministisk host_callback-ferdighet; erstatt ordlisten med din egen logikk |
src/server.ts |
Sammensetningsroten: installerer avvisningsprotokollen én gang, venter på databasen (tidsbegrenset), og kjører deretter isolasjons- og protokollsjekkene før den lytter |
migrations/000_tenancy.sql |
Generert av nexus-tenancy render da stillaset ble opprettet: roller, skjema, malen for sikkerhet på radnivå |
migrations/001_init.sql |
To tabeller med en leietakerledet sammensatt nøkkel og en sammensatt, leietakerbærende fremmednøkkel |
migrations/002_refusal_ledger.sql |
Tabellen som avvisningsprotokollen skriver til |
scripts/ci/required-env |
Skriver ut navnene på miljøvariablene som kreves ved oppstart, som JSON |
scripts/ci/shadow-migrate-*.sh |
Pipelinens prøvekjøring av migrering, gjennom nexus-migrate |
gates/ |
Portenes unntakskatalog: tom, noe som er riktig tilstand for et nytt programtillegg |
test/ |
Tester for omfang, ruter, database, utsendelse og oppstart, med omfangsdublettene som hver test injiserer |
Dockerfile |
Et ikke-rot-avtrykk (bruker-ID 10001) med migreringene innebygd |
Noen av disse filene er verdt en nærmere kikk.
src/config.ts følger to regler. Den samler inn hvert problem før den kaster et unntak, slik at én omstart navngir alle fem manglende variabler i stedet for fem omstarter som navngir én hver. Og den setter en standardverdi bare når en feil verdi ikke kan gi et stille feilsvar: PORT kan ha 8080 som standard, fordi en feil port gjør at tilknytningen mislykkes synlig, mens DATABASE_URL og UNO_DISPATCH_URL er påkrevde og må være adresser inne i klyngen. En offentlig adresse blir avvist ved oppstart.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Malens egen test kjører den filen og sammenligner utdataene med navnene som konfigurasjonsspesifikasjonen markerer som påkrevde, slik at det å legge til en påkrevd variabel uten å oppdatere listen gjør at npm test mislykkes.
src/server.ts lytter ikke før databasen svarer, og den begrenser ventetiden til 120 sekunder, mens den logger hvert mislykkede forsøk med årsak. Deretter beviser den, i rekkefølge, at applikasjonsrollen ikke kan binde leietakeren på nytt og at hver tabell er tvunget inn under sikkerhet på radnivå, at hver pods tilkoblingssamling passer innenfor rollens tilkoblingsgrense, og at avvisningsprotokollens tabell kan ta imot en rad. En avvisning fra en av de tre skrives ut i sin helhet, og prosessen avsluttes med kode 2.
v2-manifestet, felt for felt
Manifestet er programtilleggets maskinlesbare kontrakt med plattformen. Det valideres når du skriver det, når plattformen ruller det inn og kontinuerlig etter det. Skjemaet er additionalProperties: false på alle nivåer: hvis programtillegget ditt har en seksjon, finnes det en egenskap for den, og en udeklarert nøkkel blir avvist. Løsningen er alltid å bruke den riktige valgfrie egenskapen.
Den påkrevde kjernen
| Felt | Regel |
|---|---|
manifestVersion |
Nøyaktig "2". Et v1-dokument migreres, og revalideres aldri på stedet |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, høyst 64 tegn. Programtilleggs-ID-en som brukes i registrering, navneromsinndeling for utsendelse og leietakeravgrensede rader. Et programtillegg som deklarerer ferdigheter, trenger også et navn uten punktum og uten innledende siffer |
displayName |
1 til 120 tegn |
version |
Semantisk versjon; ditt eget utgivelsesløp |
description, author, license |
Minst ett tegn hver |
tier |
skills-only, ui-only eller full-service |
trust |
core, verified, community eller untrusted |
runtime |
Påkrevd: executionMode, isolationLevel (1 til 4), entrypoint. Valgfritt: nodeVersion, healthCheck, readinessCheck, livenessCheck, hver en sti som starter med /. Modusen utledes fra nivået: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai og deploy, de tre plattformlovene gjengitt. Validatoren låser ordlyden |
For et programtillegg du bygger for din egen installasjon, lyder de tre setningene som følger. ai-setningen dekker kunstig intelligens (KI) og er stedet for å oppgi at programtillegget ikke har noen modellakkreditiver.
"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 trenger version og basePath, og valgfritt websocket (path, auth) og endpoints[]. Rutetabellen er den sterkeste ideen i skjemaet: en port sammenligner den med rutene koden din faktisk registrerer, i begge retninger, slik at manifestet er en kontrollerbar kontrakt og ikke dokumentasjon.
Hvert endepunkt trenger method (GET, POST, PUT, PATCH eller DELETE) og path. Resten:
| Felt | Hva det sier |
|---|---|
auth |
Én av fem klasser: scope (en persons rute, bak omfangsvakten), service-key og internal (tjener til tjener, aldri nåbar fra en nettleser), public (kun en eksakt sti med allowAnonymous), og device (en maskin med egne akkreditiver, bak enhetsvakten) |
right |
Påkrevd på hver rute som omfangsvakten betjener, og avvist på alle andre: navnet på en rettighet i rights-registeret |
needsUnit |
Ruten avviser når innkallerens enhet ikke kan løses |
allowAnonymous |
Kun tillatelsesliste med eksakt samsvar. En prefiksregel er måten /health-of-tenant-42 ender opp som offentlig på |
group, serves, screens |
Under en release-blokk: kapabilitetsgruppen som ruten betjener, hva den svarer når denne gruppens lisensierte funksjon er låst (data, teaser, sighting eller ask), og skjermbildene den betjener |
query |
required (hvert navn med en eksempelverdi) og allowed: spørreparameterne som ruten leser |
body |
example: et eksempel på meldingskropp for en skriverute, en som dens egen validator godtar. Aldri på en GET |
rights er registeret disse rutene navngir. Hver rettighet har roles (taket) og valgfritt summary, never (roller som aldri kan utøve den, uansett hva annet de har), barred (produktets egne ord for å avvise en never-rolle), seat (et aktivt sete trengs også), self (hver verifisert person har den, for rettigheter over sin egen økt), grants (innehavere tildeler seter; høyst én rettighet oppgir dette), licence (en lisensiert funksjon som organisasjonens lisens må inneholde) installation (kun holdt av installasjonens egne administratorer) og platform (kun holdt av Adverants plattformadministratorer; den navngir ingen roller). Rettighetsnavn har minst ett 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 avviser en omfangsrute uten rettighet (ENDPOINT_RIGHT_MISSING), en rettighet som registeret mangler (ENDPOINT_RIGHT_NOT_REGISTERED) og en rettighet på en rute som ingen vakt betjener (ENDPOINT_RIGHT_UNGUARDED). Den avviser også et register som motsier seg selv, og to skrivemåter av én rute (:id og :recordId) som DUPLICATE_ENDPOINT.
Dine data: databases, schema og db
schema er det ene Postgres-skjemaet som programtillegget eier. public, plugins, auth og nexus er forbudt, og hvis databases[] også navngir et Postgres-skjema, må de to samsvare.
databases[] deklarerer hvert lager etter motor: postgresql (schema, tables, migrations og granted, tabellene en annen organisasjon kan lese under en registrert tildeling), neo4j (schemas), qdrant (collections) eller redis (purpose).
db inneholder øktgrensene for hver tilkobling programtillegget åpner, deklarert her i stedet for i kode, slik at både en kontrollør og utrullingen kan lese dem:
| Felt | Hva den begrenser |
|---|---|
maxConnections |
Tilkoblingssamlingen per replika |
pods |
Det høyeste antallet poder som holder en tilkoblingssamling samtidig, replikaer pluss toppbelastningen ved en rullende oppdatering. Hver rolles tilkoblingsgrense genereres som maxConnections × pods; utelater du den, advarer definePlugin med DB_PODS_UNDECLARED |
statementTimeoutMs |
Én setning |
idleInTransactionTimeoutMs |
En åpen transaksjon som ikke kjører noe |
workMemKB |
Én sorterings- eller hash-node, per node, ikke per spørring |
piiMask[] |
table.column-oppføringer som inneholder personopplysninger, maskert i den styrte SQL-konsollen og i logger |
Ferdigheter og verktøy: skills, mcpTools, entitlements
skills[] inneholder manifestferdigheter; kapittel 2.20, Ferdigheter, dekker feltene og nivåene deres. mcpTools[] inneholder MCP-verktøyene (Model Context Protocol) som programtillegget publiserer, hver med en name, en description og et inputSchema uten oneOf, allOf eller anyOf på toppnivå.
entitlements krever featureIdPattern og godtar alwaysOn[], source og store. Mønsteret navngir navnerommet funksjons-ID-ene dine lever i, konvensjonelt programtilleggets name pluss ett segment som koden din fyller ut per flate. alwaysOn[] er den korte, eksakte listen som må svare selv når ingen rettighetsavgjørelse kan oppnås: helse, klarhet, pålogging og innstillingene en administrator trenger for å reparere rettigheten.
Endringskontroll: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Godkjenninger telles i ulike personer, og personen som foreslo endringen, er aldri en av dem; uten begge halvdeler blir «to godkjenninger» til én person som klikker to ganger. enabled: true krever classes, og hver navngitt klasse trenger sitt eget antall. En klasse du utelater, er ustyrt, noe som er et legitimt valg skjemaet tvinger deg til å skrive ned.
Hvem du er: domains, branding, routing
domains[] (hver med primary og aliases[]; domain er formen for ett enkelt domene) lister opp hvor programtillegget svarer. branding krever appName og godtar tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId og gaId. Alt i branding er offentlig: påloggingssiden leser det før noen har et akkreditiv, så det inneholder aldri en hemmelighet eller en intern adresse. routing (type, gateway, virtualService) er for programtillegg som beskriver sin egen ruting.
Dimensjonering og resten
resources krever cpuMillicores (10 til 64 000) og memoryMB (16 til 262 144), og godtar diskGB, timeoutMs, port og wsPort. backend inneholder port, healthPath, apiPrefix, framework og platformClients[], SDK-klientene som backenden din importerer ved navn. Listen er lukket, og en port sjekker den mot importene dine. Skjemaet tillater fjorten navn: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin og uno, pluss ett for klienten som besvarer avvisninger av planrettigheter, som beholder et internt navn. Klienten for funksjonsrettigheter, runtime/entitlements, er ikke en av dem og står aldri på listen, fordi entitlements-blokken din allerede deklarerer den, og en backend som importerer den uten en entitlements-blokk, mislykkes i den samme porten. frontend inneholder basePath, mountPath og framework. nexus inneholder minVersion, maxVersion, capabilities[] og permissions[].
De gjenværende blokkene er der for én bestemt oppgave hver:
| Blokk | For |
|---|---|
settings |
Innstillingene dine på det delte rammeverket: groups og keys, satt på nivåene hver av dem navngir |
people |
sweep (service, port): organisasjonens medlemmer, synkronisert fra identitetstjenesten, der seter slås av når noen slutter |
ontology |
entityTypes og relationshipTypes: den typede grafen som holdes i ditt eget skjema |
release |
groups og frame: kapabilitetsgruppene rutene dine er trinnvis delt inn i, utgitt først som en kanariutgivelse |
cells[] |
Et programtillegg som består av flere utrullbare enheter: name, kind, entrypoint, port, wsPort hver |
pricing |
model, currency, tiers[] for katalogoppføringen din |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Hvem som publiserer det og hvor koden lever |
metrics, atlas |
De to bevisst åpne objektene, for dine egne måleverdier og generering av arkitekturdokumentasjon |
Hva skjemaet ikke kan uttrykke
JSON-skjemaet fastsetter formen; definePlugin legger til reglene et skjema ikke kan uttrykke. En ferdighets classification kan ikke overstige tillitstaket. Kun core- og verified-programtillegg kan deklarere tool_using- og llm_only-ferdigheter. Hver deklarert sti må være relativ og av samme opprinnelse, uten skjema, uten // og uten omvendt skråstrek, fordi URL-tolkeren slår sammen \ til / og /\evil.example/x løses på tvers av opprinnelser. Hver regel som registersynkroniseringen bruker på en ferdighet, brukes her først, med synkroniseringens egen kode, slik at validate og synkroniseringen navngir en brutt regel på samme måte.
Validere og gå over 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 feil skriver ut den nøyaktige stien og, for en synkroniseringsregel, koden først. Gjør det til en innsjekkingskrok (commit hook).
Et v1-manifest løftes mekanisk. migrate legger til de tre lovsetningene, flytter domain til domains[] og nekter å finne opp et inngangspunkt du ikke hadde. Det validerer resultatet før det skriver ut eller lagrer noe, slik at en migrering aldri flytter en feil fra verktøyet og inn i kodelageret ditt.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLes diff-en før du sjekker den inn. Lovsetningene den legger til, har den ordlyden som validatoren låser; for din egen installasjon setter du deploy til setningen som ble vist tidligere.
Gjengi leietakerstrukturen og klargjøre rollene
Du skriver aldri rolletildelingene dine eller malen for sikkerhet på radnivå for hånd. nexus-tenancy render skriver dem 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 genererte filen oppretter fem roller for skjemaet, hver med det den ikke har lov til å ha: en migrator som bare kan bli eieren, en eier som ikke kan logge inn, en applikasjonsrolle for forespørselsstien, en rapportrolle som bare ser aggregater, og en protokollrolle som bare kan legge til. Ingen rolle har BYPASSRLS. Den eneste måten å binde en leietaker på er én databasefunksjon, og set_config er trukket tilbake fra alle roller unntatt eieren.
En leietakerfil som er tatt i bruk, redigeres aldri. En endring er en revisjon med sin egen nummer 0-fil, og lesesetet for tildelinger på tvers av organisasjoner kommer på den måten, som revisjon 2. --graph genererer de to tabellene i den typede grafen som din ontology deklarerer, som din neste nummererte 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.sqlLeietakerfilen oppretter nettopp de rollene kjøreren kobler til som, så den tas i bruk av databaseeieren 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 tilkoblingsstreng for databaseeieren, og <dir> er en privat katalog. Klargjøringen tar i bruk grunnleietakerfilen og hver revisjon i rekkefølge, skriver migrator.url og app.url (og seat.url så snart revisjon 2 finnes) inn i <dir> med modus 0600, og skriver ikke ut noe hemmelig. Den setter hver rolles tilkoblingsgrense fra db.maxConnections × db.pods ved hver kjøring. En ny kjøring beholder eksisterende passord med mindre du ber om annet: --passwords <dir> setter dem fra filer og --rotate <roles> gir de navngitte rollene nye passord. Gjør filene om til utrullingens hemmeligheter.
Etter det kobler bruken seg til med migratorens tilkoblingsstreng som klargjøringen skrev:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonDen kjører filene fra 001 og utover som migratoren, hver fil under SET ROLE <schema>_owner, én transaksjon per fil. Den fører en protokoll, <schema>.schema_migrations, med hver fils kontrollsum; en brukt fil der bytene er endret, blir avvist ved navn (CHECKSUM_DRIFT), aldri kjørt på nytt og aldri hoppet over. Hver ventende fil tolkes med den ekte Postgres-grammatikken før den første kjører, slik at en avvisning lar databasen være urørt. Den ene headerlinjen en fil kan ha, er -- nexus-migration: transaction=file|per-statement, med valgfrie tidsavbrudd for lås og setning; per-statement er for CREATE INDEX CONCURRENTLY.
Portene
nexus-gates kjører tjueto porter. Hver av dem koder én klasse av feil slik at den ikke kan leveres to ganger, og hver har en selvtest som beviser at den feiler på en testfikstur som er bygget for å utløse den. Kjør dem før du dytter (push) koden:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Port | Hva den fanger opp |
|---|---|
scope-adherence |
En /api-rute uten omfangsvakten; en anonym sti som ikke er en eksakt deklarert sti; en enhetsrute uten enhetsvakten, eller med en persons vakt ved siden av seg |
one-fence |
Et leietakerpredikat definert hvor som helst ellers enn på ett sted, inkludert et håndlaget sete- eller tildelingsgjerde |
sql-fence |
En setning som leser eller oppdaterer en omfangsbegrenset tabell uten gjerdet, i ethvert FROM-, JOIN-, USING- eller UPDATE-mål |
migrations-are-scoped |
En tabell som mangler en akse, en leietakerledet sammensatt nøkkel, en leietakerbærende fremmednøkkel eller demokolonnen |
migrations-commit-what-they-open |
En migrering der antallet BEGIN ikke samsvarer med antallet COMMIT og ROLLBACK |
no-direct-compute |
Et direkte kall til en modelleverandør, motor, kø eller arbeidsflytvert; en ekstra leser av utsendelses-URL-en |
no-credentials |
Et akkreditiv for en modelleverandør som er lesbart i kodelageret eller miljøet |
crud-adherence |
En endrende rute der rettighetssjekken ikke navngir noe i registeret |
blocked-backends |
En rute som verken er betjent, blokkert ved navn, avvist etter loven eller eid et annet sted |
every-test-runs |
Tester som testskriptets glob-mønster aldri når |
tiles-are-invariant |
Et leietakerinvariant hurtigbufret grensesnitt som leser en leietakerverdi eller hopper over autentisering |
api-contract |
En registrert rute som manifestet ikke deklarerer, eller en deklarert rute som koden aldri registrerer |
rls-present |
En tabell uten tvungen sikkerhet på radnivå; en SECURITY DEFINER-funksjon uten en låst search_path |
no-set-config |
Programtilleggskode som selv binder leietakerinnstillingen |
db-role-honest |
En forespørselssti som kobler til som eieren eller migratoren, eller som ber om SUPERUSER eller BYPASSRLS |
platform-clients |
En SDK-klient som er importert, men ikke oppført i backend.platformClients, eller oppført, men aldri importert |
rights-register |
En omfangsrute uten en deklarert rettighet; en rettighetssjekk ved siden av registeret |
refusal-ledger |
En deklarert avvisningstabell uten en installert protokoll, eller en avvisningskropp som sendes utenom den |
grants-declared |
En tildelt tabell som manifestet ikke deklarerer; leseseterettigheter delt ut for hånd |
people-declared |
En people-blokk uten sin oppryddingsrute, vakt og tabeller |
functions-closure |
Et Azure Functions-programtillegg der betjente ruter og deklarerte ruter ikke stemmer overens |
declared-input |
En behandlers liste over spørreparametere som ikke samsvarer med rutens deklarerte query |
gates/-katalogen inneholder de fem unntaksfilene en port kan lese (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json og invariant-seams.json), én begrunnelse per oppføring. En tom begrunnelse teller som ingen oppføring, og en oppføring som navngir noe som ikke lenger finnes, gjør at porten feiler. Du kan også legge dine egne portmoduler der, så plukker nexus-gates dem opp ved siden av de innebygde.
Malens pipeline
Malen leveres uten noen håndskrevet arbeidsflyt. Pipelinekonfigurasjonen navngir Dockerfile, det ene byggeargumentet (registertokenet), prøvekjøringen av migreringen og oppstartsproben, samt porten som flettingskøen kjører. Rekkefølgen er den rekkefølgen du ønsker at det skal feile i.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, som ercreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, som ernexus-gates --self-testnode scripts/ci/required-env
To kontroller til kjøres rundt imaget. En prøvekjøring av migreringen bruker hver fil på en midlertidig Postgres-instans før imaget kan frigis, med den samme kjøreren som produksjonsmiljøet bruker: nexus-migrate provision én gang som superbruker, og deretter hver nummererte fil som migrator. En oppstartsprobe starter det bygde imaget med sitt eget inngangspunkt og hver variabel required-env skriver ut, rettet mot plassholdere som godtar tilkoblinger og aldri svarer. Serveren venter på databasen innenfor sitt avgrensede tidsvindu, og denne ventingen er signalet på at kontrollen er bestått; en konfigurasjonslaster som nekter å starte opp, gjør at bygget feiler der og ikke i produksjon.
Hva det koster
SDK-et tar beslutninger for deg, og noen av dem ville du ha tatt annerledes. Manifestet avviser nøkler det ikke kjenner til, rutetabellen må samsvare nøyaktig med koden din, databaserollene er ikke opp til deg å utforme, og kontrollpunktene lar et bygg feile hvis det mangler en rettighet på en leseoperasjon. På mitt første programtillegg brukte jeg en dag på å krangle med api-contract om en rute jeg hadde registrert og glemt å deklarere. Den hadde rett; ruten var ubeskyttet. Regn med at det første programtillegget føles tregt å lage, og regn med at det andre tar en tredjedel av tiden.

