Logga inBoka en genomgång

Kapitel 2.21

Plugin SDK

Installera Plugin SDK (programutvecklingspaket), dess kommandoradsverktyg, en genomgång av fullservicemallen, v2-manifestet fält för fält och de tjugotvå grindarna som ser till att ett insticksprogram följer reglerna.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

22 minuters läsning

Min andra plugin tog en tredjedel av tiden jämfört med min första, och nästan hela tidsvinsten låg i SDK:t (software development kit). Första gången skrev jag en kontroll av behörighetsomfång, en konfigurationsladdare och en migreringskörare, och en granskare skickade tillbaka varenda en av dem. Andra gången körde jag ett enda genereringskommando (scaffold), raderade exempelfärdigheten för sentimentanalys och ägnade mina dagar åt de granskningsposter för avvikelser som vårt flygdynamikteam faktiskt behövde.

@adverant-nexus/plugin-sdk är ett enda npm-paket. Det innehåller manifestschemat för v2 och de validerare som läser det (definePlugin, defineSkill), körtidsmodulerna som er plugin importerar för behörighetsomfång (scope), databas, anropsförmedling (dispatch) och resten, testhjälpare, efterlevnadsgrindarna (adherence gates) samt kommandoradsverktygen. Det här kapitlet behandlar installationen av det, verktygen, mallen, manifestet och grindarna. Kapitel 2.22, Körtidsmiljön för plugins, behandlar körtidsmodulerna i er körande kod.

Installera det

Paketet hämtas från Adverants register på https://registry.adverant.ai/npm/, aldrig från det publika npm-registret, och ni behöver den hämtnings-token som finns på ert kontos sida "Pull tokens and install commands". Peka @adverant-nexus-omfånget mot registret i ert kodförråds .npmrc:

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

<pull-token> är den token som finns på er kontosida. I en pipeline skickar ni in den från en hemlighet (secret) och checkar aldrig in den; mallens Dockerfile vägrar att bygga utan den och tar bort .npmrc från byggsteget när npm ci har körts, så att denna token aldrig följer med i en avbildning.

Lås sedan versionen exakt:

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

Checka in package-lock.json vid den första installationen. Mallens avbildningsbygge kör npm ci och vägrar att falla tillbaka på npm install: låsfilen är kontraktet. SDK:ts egen lägstanivå är Node 18; mallen är avsedd för Node 20.

Kommandoradsverktygen levereras inuti paketet, så varje kommando i den här dokumentationen anger paketet och dess version med npx -p. På egen hand slås npx create-nexus-plugin upp i det publika registret, och det namnet är inte det här paketet.

Kommandoradsverktygen

Verktyg Vad den gör
create-nexus-plugin Genererar en grundstruktur (scaffolds) för en plugin, validerar ett manifest, migrerar ett v1-manifest till v2 och genererar konsumentguiden för er frontend-utvecklare
nexus-tenancy Genererar ert schemas klientorganisations-SQL (tenancy SQL) utifrån manifestet: roller, behörighetstilldelningar, mallen för säkerhet på radnivå samt graftabellerna
nexus-migrate Tillämpar era migreringar: provisionerar rollerna en gång och kör sedan varje numrerad fil som migrerarrollen
nexus-gates Kör varje efterlevnadsgrind och varje grinds eget självtest

create-nexus-plugin gör inga nätverksanrop och läser inte in någon fjärrkod. Det kör samma processinterna validerare som plattformens egen onboarding kör, så det uppstår ingen avvikelse mellan "det validerade på min maskin" och "plattformen godkände det".

Kommando Flaggor Vad den gör Avslutningskoder
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Skriver en ny plugin-katalog; --print skriver endast ut manifestet 0 skriven · 1 vägrade skriva över · 2 felaktig användning
validate <file> Validerar en nexus.manifest.json, eller en .ts- eller .js-modul som exporterar en sådan 0 giltig · 1 ogiltig eller oläsbar · 2 felaktig användning
migrate <file> --write Lyfter ett v1-manifest till v2 och skriver ut det, eller skriver det på plats 0 · 1 · 2, enligt ovan
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Genererar konsumentguiden utifrån manifestet och er beskrivande text; --check jämför med den incheckade kopian och skriver ingenting 0 · 1 avvikelse eller lint-fel · 2 felaktig användning
help Skriver ut användningsinstruktioner 0

Kodgenerering och de tre nivåerna

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

--tier har standardvärdet full-service. Genereringsverktyget vägrar att skriva till en katalog som redan finns, och manifestet som det skriver klarar redan valideringen; det genererar aldrig ett ogiltigt sådant.

Välj nivå utifrån vad er plugin innehåller.

Nivå Innehåller Måste deklarera
skills-only Manifestfärdigheter och ingenting annat skills[], med minst en post
ui-only En frontend-yta inuti skalet frontend
full-service En backend och en frontend, vanligtvis med ett eget schema backend och frontend; och eftersom den har en backend, runtime.healthCheck

Om ni är osäkra, generera full-service och ta bort det ni inte behöver. Att gå åt andra hållet innebär att ni själva måste skriva de delar som mallen skulle ha gett er.

En genomgång av fullservicemallen

Mallen är referens-pluginen, byggd enligt det strikta mönster som alla senare kapitel förutsätter. Klona dess struktur, inte dess exempellogik.

Sökväg Vad det är
nexus.manifest.json v2-manifestet: de tre lagarna återgivna, ruttabellen och dess rättighetsregister
src/config.ts Konfigurationsladdaren. En specifikation, inläst en gång, där varje problem samlas in innan processen vägrar att starta
src/scope.ts Den enda fil som omvandlar en begäran till ett behörighetsomfång (scope), med SDK:ts strikta token-verifierare och två regimer: en persons innehavar-token (bearer token) och plattformens tjänsteanrop
src/db.ts Varje sats sammansätter tenantFence() och körs inuti withScopedTx
src/uno.ts Den enda filen för anropsförmedling (dispatch): en URL, en klient, en sluten tillåtelselista (allow-list)
src/routes/*.ts health (anonym, exakt sökväg), /api-rutterna (med behörighetsomfång) och /internal-återanropet (skyddat för tjänster)
src/skills/sentiment.ts En deterministisk host_callback-färdighet; ersätt lexikonet med er egen logik
src/server.ts Kompositionsroten: installerar avvisningsliggaren (refusal ledger) en gång, väntar på databasen (med tidsgräns) och kör sedan isolerings- och liggarkontrollerna innan den börjar lyssna
migrations/000_tenancy.sql Genererad av nexus-tenancy render vid genereringstillfället: roller, schema, mallen för säkerhet på radnivå
migrations/001_init.sql Två tabeller med en sammansatt nyckel som inleds med klientorganisation (tenant) och en sammansatt främmande nyckel som bär klientorganisationen
migrations/002_refusal_ledger.sql Tabellen som avvisningsliggaren skriver till
scripts/ci/required-env Skriver ut namnen på de miljövariabler som krävs vid uppstart som JSON
scripts/ci/shadow-migrate-*.sh Pipelinens torrkörning av migreringar, genom nexus-migrate
gates/ Grindarnas undantagskatalog: tom, vilket är det korrekta tillståndet för en ny plugin
test/ Tester för behörighetsomfång, rutter, databas, anropsförmedling och uppstart, med de testdubbler för behörighetsomfång som varje test injicerar
Dockerfile En avbildning utan root-behörighet (användar-ID 10001) med migreringarna inuti sig

Några av dessa filer är värda en närmare titt.

src/config.ts följer två regler. Den samlar in varje problem innan den kastar ett undantag, så att en omstart anger alla fem saknade variabler i stället för att fem omstarter anger en vardera. Och den sätter ett standardvärde endast när ett felaktigt värde inte kan ge ett tyst felaktigt svar: PORT får ha standardvärdet 8080, eftersom en felaktig port gör att bindningen misslyckas synligt, medan DATABASE_URL och UNO_DISPATCH_URL är obligatoriska och måste vara klusterinterna adresser. En publik adress avvisas vid uppstart.

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

Mallens eget test kör den filen och jämför dess utdata med de namn som konfigurationsspecifikationen markerar som obligatoriska, så om man lägger till en obligatorisk variabel utan att uppdatera listan misslyckas npm test.

src/server.ts börjar inte lyssna förrän databasen svarar, och den begränsar väntetiden till 120 sekunder medan den loggar varje misslyckat försök och dess orsak. Därefter bevisar den, i tur och ordning, att applikationsrollen inte kan binda om klientorganisationen och att varje tabell tvingas under säkerhet på radnivå, att varje pods pool ryms inom rollens anslutningsgräns samt att avvisningsliggarens tabell kan ta emot en rad. En avvisning från någon av de tre skrivs ut i sin helhet och processen avslutas med kod 2.

v2-manifestet, fält för fält

Manifestet är pluginens maskinläsbara kontrakt med plattformen. Det valideras när ni skriver det, när plattformen onboardar det och kontinuerligt därefter. Schemat är additionalProperties: false på varje nivå: om er plugin har en sektion finns det en egenskap för den, och en odeklarerad nyckel avvisas. Lösningen är alltid att använda rätt valfri egenskap.

Den obligatoriska kärnan

Fält Regel
manifestVersion Exakt "2". Ett v1-dokument migreras och omvalideras aldrig på plats
name ^[a-z0-9]+([-.][a-z0-9]+)*$, högst 64 tecken. Det plugin-id som används vid registrering, namnrymdsindelning för anropsförmedling och rader som är avgränsade per klientorganisation. En plugin som deklarerar färdigheter behöver också ett namn utan punkt och utan inledande siffra
displayName 1 till 120 tecken
version Semantisk version; er egen utgivningscykel
description, author, license Minst ett tecken vardera
tier skills-only, ui-only eller full-service
trust core, verified, community eller untrusted
runtime Obligatoriska: executionMode, isolationLevel (1 till 4), entrypoint. Valfria: nodeVersion, healthCheck, readinessCheck, livenessCheck, var och en är en sökväg som börjar med /. Läget härleds från nivån: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai och deploy, de tre plattformslagarna återgivna. Valideraren låser formuleringen

För en plugin som ni bygger för er egen installation lyder de tre meningarna som följer. Meningen ai behandlar artificiell intelligens (AI) och är platsen där man anger att pluginen inte innehåller några modellautentiseringsuppgifter.

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

Ruttabellen: api och rights

api kräver version och basePath, och valfritt websocket (path, auth) samt endpoints[]. Ruttabellen är den starkaste idén i schemat: en grind jämför den med de rutter som er kod faktiskt registrerar, i båda riktningarna, så att manifestet är ett kontrollerbart kontrakt och inte dokumentation.

Varje slutpunkt behöver method (GET, POST, PUT, PATCH eller DELETE) och path. Resten:

Fält Vad det anger
auth En av fem klasser: scope (en persons rutt, bakom omfångsskyddet), service-key och internal (server till server, aldrig nåbara från en webbläsare), public (alltid enbart en exakt sökväg med allowAnonymous) samt device (en maskin med egna autentiseringsuppgifter, bakom enhetsskyddet)
right Obligatorisk på varje rutt som omfångsskyddet betjänar, och avvisas på alla andra: namnet på en rättighet i rights-registret
needsUnit Rutten avvisar när anroparens enhet inte kan slås upp
allowAnonymous Endast tillåtelselista med exakt matchning. En prefixregel är hur /health-of-tenant-42 slutar som publik
group, serves, screens Under ett release-block: den kapabilitetsgrupp som rutten betjänar, vad den svarar när den gruppens licensierade funktion är låst (data, teaser, sighting eller ask) samt de vyer den betjänar
query required (varje namn med ett exempelvärde) och allowed: de frågeparametrar som rutten läser
body example: en exempelkropp för en skrivrutt, en som dess egen validerare godkänner. Aldrig på en GET

rights är det register som dessa rutter namnger. Varje rättighet har roles (taket) och valfritt summary, never (roller som aldrig får utöva den, oavsett vad de i övrigt innehar), barred (produktens egna ord för att avvisa en never-roll), seat (en aktiv platslicens behövs också), self (varje verifierad person innehar den, för rättigheter över sin egen session), grants (innehavare tilldelar platslicenser; högst en rättighet anger detta), licence (en licensierad funktion som organisationens licens måste innehålla) installation (innehas endast av installationens egna administratörer) och platform (innehas endast av Adverants plattformsadministratörer; den anger inga roller). Rättighetsnamn har minst en punkt: 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 avvisar en omfångsrutt utan rättighet (ENDPOINT_RIGHT_MISSING), en rättighet som saknas i registret (ENDPOINT_RIGHT_NOT_REGISTERED) och en rättighet på en rutt som inget skydd betjänar (ENDPOINT_RIGHT_UNGUARDED). Den avvisar också ett register som säger emot sig självt, samt två stavningar av samma rutt (:id och :recordId) som DUPLICATE_ENDPOINT.

Era data: databases, schema och db

schema är det enda Postgres-schema som pluginen äger. public, plugins, auth och nexus är förbjudna, och om databases[] också anger ett Postgres-schema måste de två stämma överens.

databases[] deklarerar varje datalager per motor: postgresql (schema, tables, migrations och granted, de tabeller som en annan organisation får läsa enligt en registrerad behörighetstilldelning), neo4j (schemas), qdrant (collections) eller redis (purpose).

db innehåller sessionsgränserna för varje anslutning som pluginen öppnar, deklarerade här i stället för hårdkodade så att både en granskare och driftsättningen kan läsa dem:

Fält Vad den begränsar
maxConnections Poolen per replik
pods Det högsta antalet poddar som håller en pool samtidigt, repliker plus överskottet vid en rullande uppdatering. Varje rolls anslutningsgräns genereras som maxConnections × pods; utelämnas den varnar definePlugin med DB_PODS_UNDECLARED
statementTimeoutMs En enskild sats
idleInTransactionTimeoutMs En öppen transaktion som inte kör någonting
workMemKB En sorterings- eller hashnod, per nod, inte per fråga
piiMask[] table.column-poster som innehåller personuppgifter, maskerade i den styrda SQL-konsolen och i loggar

Färdigheter och verktyg: skills, mcpTools, entitlements

skills[] innehåller manifestfärdigheter; kapitel 2.20, Färdigheter, behandlar deras fält och nivåer. mcpTools[] innehåller de MCP-verktyg (Model Context Protocol) som pluginen publicerar, vart och ett med ett name, en description och ett inputSchema utan oneOf, allOf eller anyOf på toppnivå.

entitlements kräver featureIdPattern och accepterar alwaysOn[], source samt store. Mönstret anger den namnrymd som era funktions-id:n lever i, konventionellt pluginens name plus ett segment som er kod fyller i per yta. alwaysOn[] är den korta, exakta lista som måste svara även när inget avgörande om berättigande (entitlement) kan fås: hälsa, beredskap, inloggning och de inställningar en administratör behöver för att reparera berättigandet.

Ändringshantering: changePolicy

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

Godkännanden räknas i unika personer, och den person som föreslog ändringen är aldrig en av dem; utan båda halvorna blir "två godkännanden" en person som klickar två gånger. enabled: true kräver classes, och varje namngiven klass behöver sitt eget antal. En klass som ni utelämnar är ostyrd, vilket är ett legitimt val som schemat tvingar er att skriva ner.

Vem ni är: domains, branding, routing

domains[] (var och en med primary och aliases[]; domain är formen för en enskild domän) listar var pluginen svarar. branding kräver appName och accepterar tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId och gaId. Allt i branding är publikt: inloggningssidan läser det innan någon har autentiseringsuppgifter, så det innehåller aldrig en hemlighet eller en intern adress. routing (type, gateway, virtualService) är till för plugins som beskriver sin egen routning.

Dimensionering och resten

resources kräver cpuMillicores (10 till 64 000) och memoryMB (16 till 262 144), och accepterar diskGB, timeoutMs, port samt wsPort. backend innehåller port, healthPath, apiPrefix, framework och platformClients[], de SDK-klienter som er backend importerar vid namn. Listan är sluten, och en grind kontrollerar den mot era importer. Schemat tillåter fjorton namn: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin och uno, plus ett för den klient som besvarar avvisningar gällande planberättiganden, vilken behåller ett internt namn. Klienten för funktionsberättiganden, runtime/entitlements, är inte en av dem och sätts aldrig upp på listan, eftersom ert entitlements-block redan deklarerar den, och en backend som importerar den utan ett entitlements-block underkänns av samma grind. frontend innehåller basePath, mountPath och framework. nexus innehåller minVersion, maxVersion, capabilities[] och permissions[].

De återstående blocken finns vart och ett där för en enda uppgift:

Blockera För
settings Era inställningar på det delade ramverket: groups och keys, satta på de nivåer som var och en anger
people sweep (service, port): organisationens medlemmar, synkroniserade från identitetstjänsten, där platslicenser stängs av när någon slutar
ontology entityTypes och relationshipTypes: den typade graf som hålls i ert eget schema
release groups och frame: de kapabilitetsgrupper som era rutter grupperas i för stegvis utrullning, där de först släpps som en kanariefågel (canary)
cells[] En plugin som består av flera driftsättningsbara enheter: name, kind, entrypoint, port, wsPort vardera
pricing model, currency, tiers[] för er kataloglistning
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Vem som publicerar den och var dess kod finns
metrics, atlas De två avsiktligt öppna objekten, för era egna mätvärdesnamn och generering av arkitekturdokumentation

Vad schemat inte kan uttrycka

JSON-schemat fastställer formen; definePlugin lägger till de regler som ett schema inte kan uttrycka. En färdighets classification kan inte överstiga förtroendetaket. Endast core- och verified-plugins får deklarera tool_using- och llm_only-färdigheter. Varje deklarerad sökväg måste vara relativ och ha samma ursprung (same-origin), utan schema, utan // och utan omvänt snedstreck, eftersom URL-tolken viker ihop \ till / och /\evil.example/x slås upp mot ett annat ursprung (cross-origin). Varje regel som registersynkroniseringen tillämpar på en färdighet tillämpas här först, med synkroniseringens egen kod, så att validate och synkroniseringen namnger en bruten regel på samma sätt.

Validera och flytta från 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

Ett fel skriver ut den exakta sökvägen och, för en synkroniseringsregel, koden först. Gör det till en commit-hook.

Ett v1-manifest lyfts mekaniskt. migrate lägger till de tre lagmeningarna, flyttar domain till domains[] och vägrar att hitta på en startpunkt (entrypoint) som ni inte hade. Det validerar resultatet innan det skriver ut eller sparar någonting, så en migrering flyttar aldrig ett fel från verktyget in i ert kodförråd.

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

Läs diffen innan ni checkar in den. De lagmeningar som den lägger till har den formulering som valideraren låser; för er egen installation sätter ni deploy till den mening som visades tidigare.

Rendera klientorganisationen och provisionera rollerna

Ni skriver aldrig era rollbehörigheter eller mallen för säkerhet på radnivå för hand. nexus-tenancy render skriver dem utifrån manifestets schema och db:

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

Den genererade filen skapar fem roller för schemat, var och en med vad den inte får inneha: en migrerare som endast kan bli ägaren, en ägare som inte kan logga in, en applikationsroll för anropsvägen, en rapportroll som endast ser aggregeringar samt en liggarroll som endast kan lägga till (append). Ingen roll innehar BYPASSRLS. Det enda sättet att binda en klientorganisation är en enda databasfunktion, och set_config återkallas från varje roll utom ägaren.

En tillämpad klientorganisationsfil (tenancy file) redigeras aldrig. En ändring är en revidering med sin egen nummer-0-fil, och läsplatsen för organisationsöverskridande behörighetstilldelningar kommer på det sättet, som revidering 2. --graph genererar de två tabellerna för den typade graf som er ontology deklarerar som er nästa numrerade 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

Klientorganisationsfilen skapar just de roller som köraren ansluter som, så den tillämpas av databasägaren 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> är en anslutningssträng för databasägaren, och <dir> är en privat katalog. Provisioneringen tillämpar den grundläggande klientorganisationsfilen och varje revidering i tur och ordning, skriver migrator.url och app.url (samt seat.url när revidering 2 finns) till <dir> med läget 0600 och skriver inte ut någonting hemligt. Den sätter varje rolls anslutningsgräns utifrån db.maxConnections × db.pods vid varje körning. En omkörning behåller befintliga lösenord om ni inte ber om annat: --passwords <dir> sätter dem från filer och --rotate <roles> ger de namngivna rollerna nya. Omvandla filerna till er driftsättnings hemligheter (secrets).

Därefter ansluter tillämpningen med migrerarens anslutningssträng 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ör filerna från 001 och framåt som migreraren, varje fil under SET ROLE <schema>_owner, en transaktion per fil. Den för en liggare, <schema>.schema_migrations, med varje fils kontrollsumma; en tillämpad fil vars byte har ändrats avvisas vid namn (CHECKSUM_DRIFT), körs aldrig om och hoppas aldrig över. Varje väntande fil tolkas med den riktiga Postgres-grammatiken innan den första körs, så en avvisning lämnar databasen orörd. Det enda sidhuvud en fil får ha är -- nexus-migration: transaction=file|per-statement, med valfria tidsgränser för lås och satser; per-statement är till för CREATE INDEX CONCURRENTLY.

Grindarna

nexus-gates kör tjugotvå grindar. Var och en kodar in en klass av defekter så att den inte kan skeppas två gånger, och var och en har ett självtest som bevisar att den misslyckas på en fixtur som byggts för att utlösa den. Kör dem innan ni pushar:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Grind Vad den fångar
scope-adherence En /api-rutt utan omfångsskyddet; en anonym sökväg som inte är en exakt deklarerad sådan; en enhetsrutt utan enhetsskyddet, eller med en persons skydd bredvid sig
one-fence Ett klientorganisationspredikat som definieras någon annanstans än på ett enda ställe, inklusive ett handskrivet stängsel (fence) för platslicenser eller behörighetstilldelningar
sql-fence En sats som läser eller uppdaterar en omfångsavgränsad tabell utan stängslet, i något mål för FROM, JOIN, USING eller UPDATE
migrations-are-scoped En tabell som saknar en axel, en sammansatt nyckel som inleds med klientorganisation, en främmande nyckel som bär klientorganisationen eller demokolumnen
migrations-commit-what-they-open En migrering vars antal BEGIN inte stämmer överens med dess antal COMMIT och ROLLBACK
no-direct-compute Ett direktanrop till en modelleverantör, motor, kö eller arbetsflödesvärd; en andra läsare av URL:en för anropsförmedling
no-credentials En autentiseringsuppgift för en modelleverantör som är läsbar i kodförrådet eller i miljön
crud-adherence En muterande rutt vars rättighetskontroll inte namnger någonting i registret
blocked-backends En rutt som varken betjänas, blockeras vid namn, avvisas enligt lag eller ägs någon annanstans
every-test-runs Tester som testskriptets glob-mönster aldrig når
tiles-are-invariant En klientorganisationsinvariant cachad skarv (seam) som läser ett klientorganisationsvärde eller hoppar över autentisering
api-contract En registrerad rutt som manifestet inte deklarerar, eller en deklarerad rutt som koden aldrig registrerar
rls-present En tabell utan tvingad säkerhet på radnivå; en SECURITY DEFINER-funktion utan en låst search_path
no-set-config Plugin-kod som själv binder klientorganisationsinställningen
db-role-honest En anropsväg som ansluter som ägaren eller migreraren, eller som begär SUPERUSER eller BYPASSRLS
platform-clients En SDK-klient som importeras men inte listas i backend.platformClients, eller som listas men aldrig importeras
rights-register En omfångsrutt utan en deklarerad rättighet; en rättighetskontroll vid sidan av registret
refusal-ledger En deklarerad avvisningstabell utan installerad liggare, eller en avvisningskropp som skickas förbi den
grants-declared En tilldelad tabell som manifestet inte deklarerar; läsplatsbehörigheter som delats ut för hand
people-declared Ett people-block utan sin sveprutt (sweep route), sitt skydd och sina tabeller
functions-closure En Azure Functions-plugin vars betjänade rutter och deklarerade rutter inte stämmer överens
declared-input En hanterares lista över frågeparametrar som inte stämmer överens med ruttens deklarerade query

Katalogen gates/ innehåller de fem undantagsfiler som en grind kan läsa (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json och invariant-seams.json), med en motivering per post. En tom motivering räknas som ingen post, och en post som namnger något som inte längre finns gör att grinden underkänner. Ni kan också lägga era egna grindmoduler där, så plockar nexus-gates upp dem vid sidan av de inbyggda.

Kompatibilitet
Kompatibilitet
Kompatibilitet visar vilken SDK-version som fungerar med vilken plattformsversion, utifrån nattliga körningar av snabbstarten. Ett otestat par anger detta, och ett par som misslyckas anger den ändring som gjorde att det slutade fungera.

Mallens pipeline

Mallen levereras utan något handskrivet arbetsflöde. Dess pipelinekonfiguration anger Dockerfile-filen, det enda byggargumentet (registrets token), torrkörningen av migreringar och uppstartsproben samt den grind som sammanslagningskön (merge queue) kör. Ordningen är den ordning i vilken ni skulle vilja att ett fel uppstår.

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

Ytterligare två kontroller körs kring avbilden. Testkörningen av migreringen applicerar varje fil på en tillfällig Postgres innan avbilden kan släppas, med samma exekverare som används i produktion: nexus-migrate provision en gång som superanvändare, och därefter varje numrerad fil som migrerare. Uppstartsproben startar den byggda avbilden med dess egen startpunkt och varje variabel som required-env skriver ut, riktad mot attrapper som accepterar anslutningar men aldrig svarar. Servern väntar på databasen inom sitt avgränsade tidsfönster, och denna väntan är signalen för godkänt; en konfigurationsladdare som vägrar att starta stoppar bygget där och inte i produktion.

Bygga på Community
Bygga på Community
I Community får en utvecklare samma standardiserade arbetsflöden, en utvecklingsmiljö och datagrenar på en server, med koden hos sin egen Git-värd. Staging, pilotenheter och maskerade kopior av skarp data ingår i Enterprise.

Vad det kostar

SDK:t tar över beslut åt dig, och vissa av dem hade du fattat annorlunda. Manifestet avvisar nycklar det inte känner igen, ruttabellen måste matcha din kod exakt, databasrollerna är inte dina att utforma och kontrollgrindarna stoppar ett bygge om det saknas en rättighet vid en läsning. Med mitt första insticksprogram ägnade jag en dag åt att argumentera med api-contract om en rutt som jag hade registrerat men glömt att deklarera. Det hade rätt; rutten var oskyddad. Räkna med att det första insticksprogrammet känns långsamt, och räkna med att det andra tar en tredjedel av tiden.