Logg innBestill en gjennomgang

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

22 minutter å lese

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

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

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

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

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

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

Kompatibilitet
Kompatibilitet
Kompatibilitet viser hvilken SDK-versjon som fungerer med hvilken plattformversjon, fra nattlige kjøringer av hurtigstarten. Et utestet par oppgir dette, og et par som feiler, navngir endringen som ødela det.

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.

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

Bygge på Community
Bygge på Community
På Community får en utvikler de samme anbefalte arbeidsflytene, et utviklingsområde og datagrener på én server, med kode hos sin egen Git-leverandør. Testmiljø (staging), pilotenheter og maskerte kopier av produksjonsdata følger med Enterprise.

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.