Version 1.0.0-alpha.1senaste
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

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.0Checka 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 --writeLä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.sqlDen 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.sqlKlientorganisationsfilen 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.jsonDen 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.
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.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, vilket ärcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, vilket ärnexus-gates --self-testnode 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.
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.

