Versie 1.0.0-alpha.1nieuwste
Hoofdstuk 2.21
De Plugin SDK
Het installeren van de Plugin SDK (software development kit), de opdrachtregelprogramma's, een rondleiding door de full-service-sjabloon, het v2-manifest veld voor veld, en de tweeëntwintig poorten die een plug-in aan de regels houden.
Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

Mijn tweede plug-in kostte een derde van de tijd van mijn eerste, en bijna de volledige besparing kwam door de SDK (software development kit). De eerste keer schreef ik een scopecontrole, een configuratielader en een migratierunner, en een reviewer stuurde ze stuk voor stuk terug. De tweede keer voerde ik één scaffold-opdracht uit, verwijderde ik de voorbeeldvaardigheid voor sentimentanalyse en besteedde ik mijn dagen aan de records voor anomaliebeoordeling die ons vluchtdynamicateam daadwerkelijk nodig had.
@adverant-nexus/plugin-sdk is één npm-pakket. Het bevat het v2-manifestschema en de validators die het lezen (definePlugin, defineSkill), de runtimemodules die uw plug-in importeert voor scope, database, dispatch en de rest, testhulpmiddelen, de nalevingspoorten (adherence gates) en de opdrachtregelprogramma's. Dit hoofdstuk behandelt de installatie ervan, de hulpmiddelen, de template, het manifest en de poorten. Hoofdstuk 2.22, De plug-in-runtime, behandelt de runtimemodules in uw draaiende code.
Installatie
Het pakket is afkomstig uit het register van Adverant op https://registry.adverant.ai/npm/, nooit uit het openbare npm-register, en u hebt het pull-token nodig van de pagina "Pull tokens and install commands" van uw account. Laat de scope @adverant-nexus verwijzen naar het register in het bestand .npmrc van uw repository:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> is het token van uw accountpagina. Geef het in een pijplijn door vanuit een secret en leg het nooit vast in een commit; de Dockerfile van de template weigert te bouwen zonder dit token en verwijdert .npmrc uit de bouwfase zodra npm ci is uitgevoerd, zodat het token nooit in een image wordt meegeleverd.
Zet de versie vervolgens exact vast:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Leg package-lock.json bij de eerste installatie vast in een commit. Het bouwen van het image van de template voert npm ci uit en weigert terug te vallen op npm install: het lockfile is het contract. De ondergrens van de SDK zelf is Node 18; de template richt zich op Node 20.
De opdrachtregelprogramma's worden binnen het pakket meegeleverd, dus elke opdracht in deze documentatie noemt het pakket en de bijbehorende versie met npx -p. Op zichzelf wordt npx create-nexus-plugin opgezocht in het openbare register, en die naam verwijst niet naar dit pakket.
De opdrachtregelprogramma's
| Hulpmiddel | Wat deze doet |
|---|---|
create-nexus-plugin |
Genereert de basisstructuur (scaffold) van een plug-in, valideert een manifest, migreert een v1-manifest naar v2 en genereert de gebruikershandleiding voor uw frontend-ontwikkelaar |
nexus-tenancy |
Genereert de tenancy-SQL van uw schema vanuit het manifest: rollen, rechten (grants), de template voor beveiliging op rijniveau (row-level security) en de graaftabellen |
nexus-migrate |
Past uw migraties toe: richt de rollen eenmalig in en voert vervolgens elk genummerd bestand uit als de migratorrol |
nexus-gates |
Voert elke nalevingspoort uit, evenals de eigen zelftest van elke poort |
create-nexus-plugin maakt geen netwerkaanroepen en laadt geen externe code. Het voert dezelfde in-process validators uit die de onboarding van het platform uitvoert, zodat er geen afwijking (drift) ontstaat tussen "het is gevalideerd op mijn machine" en "het platform heeft het geaccepteerd".
| Opdracht | Vlaggen | Wat deze doet | Exitcodes |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Schrijft een nieuwe plug-inmap; --print drukt alleen het manifest af |
0 geschreven · 1 overschrijven geweigerd · 2 onjuist gebruik |
validate <file> |
Valideert een nexus.manifest.json, of een .ts- of .js-module die er een exporteert |
0 geldig · 1 ongeldig of onleesbaar · 2 onjuist gebruik | |
migrate <file> |
--write |
Zet een v1-manifest om naar v2 en drukt het af, of overschrijft het ter plaatse | 0 · 1 · 2, zoals hierboven |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genereert de gebruikershandleiding vanuit het manifest en uw toelichting; --check vergelijkt met het vastgelegde exemplaar en schrijft niets |
0 · 1 afwijking of een lint-overtreding · 2 onjuist gebruik |
help |
Drukt gebruiksinstructies af | 0 |
Scaffolding en de drie lagen
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier staat standaard op full-service. De scaffolder weigert te schrijven naar een map die al bestaat, en het manifest dat wordt geschreven, doorstaat de validatie al; er wordt nooit een ongeldig manifest geproduceerd.
Kies het niveau (tier) op basis van wat uw plug-in bevat.
| Niveau | Bevat | Moet declareren |
|---|---|---|
skills-only |
Alleen manifestvaardigheden en niets anders | skills[], met ten minste één vermelding |
ui-only |
Een frontend-oppervlak binnen de shell | frontend |
full-service |
Een backend en een frontend, doorgaans met een eigen schema | backend en frontend; en omdat het een backend heeft, runtime.healthCheck |
Als u twijfelt, genereer dan de basisstructuur met full-service en verwijder wat u niet nodig hebt. Andersom betekent dat u zelf de onderdelen moet schrijven die de template u anders had gegeven.
Een rondleiding door de full-service-sjabloon
De template is de referentie-plug-in, gebouwd volgens het strikte patroon waar elk volgend hoofdstuk van uitgaat. Kloon de vorm ervan, niet de voorbeeldlogica.
| Pad | Wat het is |
|---|---|
nexus.manifest.json |
Het v2-manifest: de drie wetten herhaald, de routetabel en het bijbehorende rechtenregister |
src/config.ts |
De configuratielader. Eén specificatie, eenmalig gelezen, elk probleem verzameld voordat het proces weigert op te starten |
src/scope.ts |
Het enige bestand dat een verzoek omzet in een scope, met de strikte tokenverificatie van de SDK en twee regimes: het bearer-token van een persoon en de serviceaanroep van het platform |
src/db.ts |
Elk statement stelt tenantFence() samen en wordt uitgevoerd binnen withScopedTx |
src/uno.ts |
Het enige dispatch-bestand: één URL, één client, een gesloten allowlist |
src/routes/*.ts |
health (anoniem, exact pad), de /api-routes (binnen een scope) en de /internal-callback (beveiligd voor services) |
src/skills/sentiment.ts |
Een deterministische host_callback-vaardigheid; vervang het lexicon door uw eigen logica |
src/server.ts |
De compositiewortel (composition root): installeert eenmalig het weigeringsgrootboek (refusal ledger), wacht op de database (begrensd) en voert vervolgens de isolatie- en grootboekcontroles uit voordat het gaat luisteren |
migrations/000_tenancy.sql |
Gegenereerd door nexus-tenancy render tijdens het maken van de basisstructuur: rollen, schema, de template voor beveiliging op rijniveau |
migrations/001_init.sql |
Twee tabellen met een samengestelde sleutel waarin de tenant vooropstaat en een samengestelde, tenant-bevattende vreemde sleutel (foreign key) |
migrations/002_refusal_ledger.sql |
De tabel waarin het weigeringsgrootboek schrijft |
scripts/ci/required-env |
Drukt de namen van de voor het opstarten vereiste omgevingsvariabelen af als JSON |
scripts/ci/shadow-migrate-*.sh |
De proefuitvoering (dry run) van de migratie in de pijplijn, via nexus-migrate |
gates/ |
De vrijstellingsmap van de poorten: leeg, wat de juiste status is voor een nieuwe plug-in |
test/ |
Tests voor scope, routes, database, dispatch en het opstarten, met de scope-doubles die elke test injecteert |
Dockerfile |
Een non-root image (gebruikers-ID 10001) met de migraties erin |
Een aantal van die bestanden is een nadere blik waard.
src/config.ts volgt twee regels. Het verzamelt elk probleem voordat het een fout opwerpt, zodat één herstart alle vijf ontbrekende variabelen noemt in plaats van vijf herstarts die er elk één noemen. En het gebruikt alleen een standaardwaarde wanneer een verkeerde waarde geen stilzwijgend fout antwoord kan opleveren: PORT mag standaard op 8080 staan, omdat een verkeerde poort het binden zichtbaar laat mislukken, terwijl DATABASE_URL en UNO_DISPATCH_URL vereist zijn en adressen binnen het cluster moeten zijn. Een openbaar adres wordt bij het opstarten geweigerd.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
De eigen test van de template voert dat bestand uit en vergelijkt de uitvoer ervan met de namen die de configuratiespecificatie als vereist markeert, zodat het toevoegen van een vereiste variabele zonder de lijst bij te werken ervoor zorgt dat npm test mislukt.
src/server.ts luistert pas wanneer de database antwoordt en begrenst de wachttijd op 120 seconden, waarbij elke mislukte poging met de oorzaak wordt gelogd. Vervolgens bewijst het, op volgorde, dat de app-rol de tenant niet opnieuw kan binden en dat elke tabel verplicht onder beveiliging op rijniveau valt, dat de pool van elke pod binnen de verbindingslimiet van de rol past, en dat de tabel van het weigeringsgrootboek een rij kan opnemen. Een weigering bij een van de drie wordt volledig afgedrukt en het proces sluit af met code 2.
Het v2-manifest, veld voor veld
Het manifest is het machineleesbare contract van de plug-in met het platform. Het wordt gevalideerd wanneer u het schrijft, wanneer het platform het onboardt en daarna voortdurend. Het schema is op elk niveau additionalProperties: false: als uw plug-in een sectie heeft, is daar een eigenschap voor, en een niet-gedeclareerde sleutel wordt geweigerd. De oplossing is altijd om de juiste optionele eigenschap te gebruiken.
De vereiste kern
| Veld | Regel |
|---|---|
manifestVersion |
Exact "2". Een v1-document wordt gemigreerd, nooit ter plaatse opnieuw gevalideerd |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, maximaal 64 tekens. De plug-in-ID die wordt gebruikt bij registratie, dispatch-namespacing en rijen binnen een tenant-scope. Een plug-in die vaardigheden declareert, heeft ook een naam zonder punt en zonder voorloopcijfer nodig |
displayName |
1 tot 120 tekens |
version |
Semantische versie; uw eigen releasetrein |
description, author, license |
Elk ten minste één teken |
tier |
skills-only, ui-only of full-service |
trust |
core, verified, community of untrusted |
runtime |
Vereist: executionMode, isolationLevel (1 tot 4), entrypoint. Optioneel: nodeVersion, healthCheck, readinessCheck, livenessCheck, elk een pad dat begint met /. De modus wordt afgeleid van het niveau: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai en deploy, de drie platformwetten herhaald. De validator legt de exacte formulering vast |
Voor een plug-in die u voor uw eigen installatie bouwt, luiden de drie zinnen als volgt. De zin ai behandelt kunstmatige intelligentie (AI) en is de plek om te vermelden dat de plug-in geen modelinloggegevens bevat.
"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."
}De routetabel: api en rights
api vereist version en basePath, en optioneel websocket (path, auth) en endpoints[]. De routetabel is het sterkste concept in het schema: een poort vergelijkt deze in beide richtingen met de routes die uw code daadwerkelijk registreert, zodat het manifest een controleerbaar contract is en geen documentatie.
Elk eindpunt vereist method (GET, POST, PUT, PATCH of DELETE) en path. De rest:
| Veld | Wat erin staat |
|---|---|
auth |
Een van de vijf klassen: scope (de route van een persoon, achter de scope-guard), service-key en internal (server-naar-server, nooit bereikbaar vanuit een browser), public (altijd uitsluitend een exact pad met allowAnonymous), en device (een machine met een eigen inloggegeven, achter de device-guard) |
right |
Vereist op elke route die door de scope-guard wordt bediend, en geweigerd op elke andere: de naam van een recht in het rights-register |
needsUnit |
De route weigert wanneer de eenheid van de aanroeper niet kan worden herleid |
allowAnonymous |
Alleen een allowlist met exacte overeenkomsten. Een prefixregel is de manier waarop /health-of-tenant-42 onbedoeld openbaar wordt |
group, serves, screens |
Onder een release-blok: de capaciteitsgroep die de route bedient, wat deze antwoordt wanneer de gelicentieerde functie van die groep vergrendeld is (data, teaser, sighting of ask), en de schermen die deze bedient |
query |
required (elke naam met een voorbeeldwaarde) en allowed: de queryparameters die de route leest |
body |
example: de voorbeeldbody van een schrijfroute, een die door de eigen validator wordt geaccepteerd. Nooit op een GET |
rights is het register waar die routes naar verwijzen. Elk recht heeft roles (het plafond) en optioneel summary, never (rollen die het nooit mogen uitoefenen, wat ze verder ook bezitten), barred (de eigen bewoordingen van het product voor het weigeren van een never-rol), seat (er is ook een actieve seat nodig), self (elke geverifieerde persoon bezit het, voor rechten over de eigen sessie), grants (houders kennen seats toe; hoogstens één recht vermeldt dit), licence (een gelicentieerde functie die de licentie van de organisatie moet bevatten), installation (alleen in het bezit van de eigen beheerders van de installatie) en platform (alleen in het bezit van de platformbeheerders van Adverant; het noemt geen rollen). Namen van rechten bevatten ten minste één punt: 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 weigert een scoperoute zonder recht (ENDPOINT_RIGHT_MISSING), een recht dat in het register ontbreekt (ENDPOINT_RIGHT_NOT_REGISTERED) en een recht op een route die door geen enkele guard wordt bediend (ENDPOINT_RIGHT_UNGUARDED). Het weigert ook een register dat zichzelf tegenspreekt, en twee schrijfwijzen van één route (:id en :recordId) als DUPLICATE_ENDPOINT.
Uw gegevens: databases, schema en db
schema is het enige Postgres-schema waarvan de plug-in eigenaar is. public, plugins, auth en nexus zijn verboden, en als databases[] ook een Postgres-schema noemt, moeten de twee overeenkomen.
databases[] declareert elke opslag per engine: postgresql (schema, tables, migrations, en granted, de tabellen die een andere organisatie mag lezen onder een vastgelegde toekenning), neo4j (schemas), qdrant (collections) of redis (purpose).
db bevat de sessielimieten voor elke verbinding die de plug-in opent, hier gedeclareerd in plaats van gecodeerd, zodat zowel een reviewer als de deployment ze kan lezen:
| Veld | Wat het begrenst |
|---|---|
maxConnections |
De pool per replica |
pods |
Het maximale aantal pods dat tegelijkertijd een pool vasthoudt, replica's plus de piek (surge) van een rolling update. De verbindingslimiet van elke rol wordt gegenereerd als maxConnections × pods; laat u dit weg, dan waarschuwt definePlugin met DB_PODS_UNDECLARED |
statementTimeoutMs |
Eén statement |
idleInTransactionTimeoutMs |
Een open transactie die niets uitvoert |
workMemKB |
Eén sorteer- of hash-node, per node, niet per query |
piiMask[] |
table.column-vermeldingen die persoonsgegevens bevatten, gemaskeerd in de beheerde SQL-console en in logboeken |
Vaardigheden en hulpmiddelen: skills, mcpTools, entitlements
skills[] bevat manifestvaardigheden; hoofdstuk 2.20, Vaardigheden, behandelt hun velden en niveaus. mcpTools[] bevat de MCP-hulpmiddelen (Model Context Protocol) die de plug-in publiceert, elk een name, een description en een inputSchema zonder oneOf, allOf of anyOf op het hoogste niveau.
entitlements vereist featureIdPattern en accepteert alwaysOn[], source en store. Het patroon benoemt de namespace waarin uw functie-ID's zich bevinden, gebruikelijk de name van de plug-in plus één segment dat uw code per oppervlak invult. alwaysOn[] is de korte, exacte lijst die moet antwoorden, zelfs wanneer er geen rechtenoordeel (entitlement verdict) kan worden verkregen: status (health), gereedheid (readiness), aanmelding en de instellingen die een beheerder nodig heeft om het recht te herstellen.
Wijzigingsbeheer: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Goedkeuringen worden geteld in afzonderlijke personen, en de persoon die de wijziging heeft voorgesteld, is nooit een van hen; zonder beide voorwaarden wordt "twee goedkeuringen" één persoon die twee keer klikt. enabled: true vereist classes, en elke genoemde klasse heeft een eigen aantal nodig. Een klasse die u weglaat, valt niet onder het beheer (ungoverned), wat een legitieme keuze is die het schema u dwingt op te schrijven.
Wie u bent: domains, branding, routing
domains[] (elk primary en aliases[]; domain is de vorm voor één domein) vermeldt waar de plug-in antwoordt. branding vereist appName en accepteert tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId en gaId. Alles in branding is openbaar: de aanmeldingspagina leest dit voordat iemand inloggegevens heeft, dus het bevat nooit een secret of een intern adres. routing (type, gateway, virtualService) is voor plug-ins die hun eigen routering beschrijven.
Dimensionering en de rest
resources vereist cpuMillicores (10 tot 64.000) en memoryMB (16 tot 262.144), en accepteert diskGB, timeoutMs, port en wsPort. backend bevat port, healthPath, apiPrefix, framework en platformClients[], de SDK-clients die uw backend op naam importeert. De lijst is gesloten en een poort controleert deze aan de hand van uw imports. Het schema staat veertien namen toe: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin en uno, plus één voor de client die weigeringen van planrechten (plan-entitlement) beantwoordt, die een interne naam behoudt. De client voor functierechten (feature-entitlement), runtime/entitlements, hoort daar niet bij en komt nooit op de lijst te staan, omdat uw entitlements-blok deze al declareert, en een backend die deze importeert zonder een entitlements-blok, loopt vast op dezelfde poort. frontend bevat basePath, mountPath en framework. nexus bevat minVersion, maxVersion, capabilities[] en permissions[].
De overige blokken zijn er elk voor één taak:
| Blok | Voor |
|---|---|
settings |
Uw instellingen op het gedeelde framework: groups en keys, ingesteld op de niveaus die elk noemt |
people |
sweep (service, port): de leden van de organisatie, gesynchroniseerd vanuit de identiteitsservice, waarbij seats worden uitgeschakeld wanneer iemand vertrekt |
ontology |
entityTypes en relationshipTypes: de getypeerde graaf die in uw eigen schema wordt bijgehouden |
release |
groups en frame: de capaciteitsgroepen waarin uw routes gefaseerd zijn ondergebracht, en die als eerste als canary worden vrijgegeven |
cells[] |
Een plug-in die uit meerdere deployables bestaat: elk name, kind, entrypoint, port, wsPort |
pricing |
model, currency, tiers[] voor uw catalogusvermelding |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Wie het publiceert en waar de bijbehorende code zich bevindt |
metrics, atlas |
De twee bewust open objecten, voor uw eigen metrieknamen en het genereren van architectuurdocumentatie |
Wat het schema niet kan uitdrukken
Het JSON-schema bepaalt de vorm; definePlugin voegt de regels toe die een schema niet kan uitdrukken. De classification van een vaardigheid mag het vertrouwensplafond niet overschrijden. Alleen core- en verified-plug-ins mogen tool_using- en llm_only-vaardigheden declareren. Elk gedeclareerd pad moet relatief en van dezelfde herkomst (same-origin) zijn, zonder schema, zonder // en zonder backslash, omdat de URL-parser \ omzet naar / en /\evil.example/x cross-origin wordt herleid. Elke regel die de registersynchronisatie op een vaardigheid toepast, wordt hier als eerste toegepast, met de eigen code van de synchronisatie, zodat validate en de synchronisatie een geschonden regel op dezelfde manier benoemen.
Valideren en overstappen vanaf 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
Bij een fout wordt het exacte pad afgedrukt en, voor een synchronisatieregel, eerst de code. Maak er een commit-hook van.
Een v1-manifest wordt mechanisch omgezet. migrate voegt de drie wetzinnen toe, verplaatst domain naar domains[] en weigert een startpunt (entrypoint) te verzinnen dat u niet had. Het valideert het resultaat voordat er iets wordt afgedrukt of geschreven, zodat een migratie nooit een fout vanuit het hulpmiddel naar uw repository verplaatst.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLees de diff voordat u deze vastlegt in een commit. De wetzinnen die worden toegevoegd, hebben de exacte formulering die de validator vereist; stel voor uw eigen installatie deploy in op de eerder getoonde zin.
De tenancy genereren en de rollen inrichten
U schrijft uw roltoekenningen (role grants) of de template voor beveiliging op rijniveau nooit met de hand. nexus-tenancy render schrijft ze vanuit schema en db van het manifest:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlHet gegenereerde bestand maakt vijf rollen voor het schema aan, elk zonder wat het niet mag bezitten: een migrator die alleen de eigenaar (owner) kan worden, een eigenaar die niet kan inloggen, een app-rol voor het verzoekpad, een rapportrol die alleen aggregaten ziet, en een grootboekrol die alleen kan toevoegen (append). Geen enkele rol bezit BYPASSRLS. De enige manier om een tenant te binden is via één databasefunctie, en set_config wordt ingetrokken voor elke rol behalve de eigenaar.
Een toegepast tenancy-bestand wordt nooit bewerkt. Een wijziging is een revisie met een eigen nummer-0-bestand, en de leesseat voor toekenningen tussen organisaties (cross-organisation grants) wordt op die manier geleverd, als revisie 2. --graph genereert de twee tabellen van de getypeerde graaf die uw ontology declareert als uw volgende genummerde migratie.
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.sqlHet tenancy-bestand maakt precies de rollen aan waarmee de runner verbinding maakt, dus het wordt door de database-eigenaar toegepast met 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> is een verbindingsreeks voor de database-eigenaar en <dir> is een privémap. Provision past het basis-tenancy-bestand en elke revisie op volgorde toe, schrijft migrator.url en app.url (en seat.url zodra revisie 2 bestaat) naar <dir> met modus 0600, en drukt niets geheims af. Het stelt bij elke uitvoering de verbindingslimiet van elke rol in vanuit db.maxConnections × db.pods. Een heruitvoering behoudt bestaande wachtwoorden, tenzij u daarom vraagt: --passwords <dir> stelt ze in vanuit bestanden en --rotate <roles> geeft de genoemde rollen nieuwe wachtwoorden. Zet de bestanden om in de secrets van uw deployment.
Daarna maakt het toepassen verbinding met de verbindingsreeks van de migrator die door provision is geschreven:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonHet voert de bestanden vanaf 001 uit als de migrator, elk bestand onder SET ROLE <schema>_owner, één transactie per bestand. Het houdt een grootboek bij, <schema>.schema_migrations, met de controlesom (checksum) van elk bestand; een toegepast bestand waarvan de bytes zijn gewijzigd, wordt op naam geweigerd (CHECKSUM_DRIFT), nooit opnieuw uitgevoerd en nooit overgeslagen. Elk wachtend bestand wordt geparseerd met de echte Postgres-grammatica voordat het eerste wordt uitgevoerd, zodat een weigering de database ongemoeid laat. De enige header die een bestand mag bevatten is -- nexus-migration: transaction=file|per-statement, met optionele lock- en statement-time-outs; per-statement is voor CREATE INDEX CONCURRENTLY.
De poorten
nexus-gates voert tweeëntwintig poorten uit. Elke poort codeert één klasse van defecten zodat deze niet twee keer kan worden meegeleverd, en elke poort heeft een zelftest die bewijst dat deze faalt op een testopstelling (fixture) die is gebouwd om de poort te laten aanslaan. Voer ze uit voordat u pusht:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Poort | Wat het onderschept |
|---|---|
scope-adherence |
Een /api-route zonder de scope-guard; een anoniem pad dat geen exact gedeclareerd pad is; een apparaatroute zonder de device-guard, of met de guard van een persoon ernaast |
one-fence |
Een tenant-predicaat dat elders dan op die ene plek is gedefinieerd, inclusief een zelfgeschreven seat- of grant-afscherming (fence) |
sql-fence |
Een statement dat een tabel binnen een scope leest of bijwerkt zonder de afscherming, in een FROM-, JOIN-, USING- of UPDATE-doel |
migrations-are-scoped |
Een tabel waarin een as, een samengestelde sleutel waarin de tenant vooropstaat, een tenant-bevattende vreemde sleutel of de demokolom ontbreekt |
migrations-commit-what-they-open |
Een migratie waarvan het aantal BEGIN niet overeenkomt met het aantal COMMIT en ROLLBACK |
no-direct-compute |
Een directe aanroep naar een modelprovider, engine, wachtrij of workflow-host; een tweede lezer van de dispatch-URL |
no-credentials |
Een inloggegeven van een modelprovider dat leesbaar is in de repository of de omgeving |
crud-adherence |
Een muterende route waarvan de rechtencontrole niets in het register noemt |
blocked-backends |
Een route die noch wordt bediend, noch op naam wordt geblokkeerd, noch volgens de wet wordt geweigerd, noch elders in eigendom is |
every-test-runs |
Tests die het glob-patroon van het testscript nooit bereikt |
tiles-are-invariant |
Een gecachete tenant-invariante overgang (seam) die een tenantwaarde leest of authenticatie overslaat |
api-contract |
Een geregistreerde route die het manifest niet declareert, of een gedeclareerde route die de code nooit registreert |
rls-present |
Een tabel zonder verplichte beveiliging op rijniveau; een SECURITY DEFINER-functie zonder een vastgezette search_path |
no-set-config |
Plug-incode die zelf de tenant-instelling bindt |
db-role-honest |
Een verzoekpad dat verbinding maakt als de eigenaar of migrator, of vraagt om SUPERUSER of BYPASSRLS |
platform-clients |
Een SDK-client die is geïmporteerd maar niet is vermeld in backend.platformClients, of wel is vermeld maar nooit is geïmporteerd |
rights-register |
Een scoperoute zonder een gedeclareerd recht; een rechtencontrole buiten het register om |
refusal-ledger |
Een gedeclareerde weigeringstabel zonder geïnstalleerd grootboek, of een weigeringsbody die eromheen wordt gestuurd |
grants-declared |
Een toegekende tabel die het manifest niet declareert; leesseat-privileges die handmatig zijn uitgedeeld |
people-declared |
Een people-blok zonder de bijbehorende sweep-route, guard en tabellen |
functions-closure |
Een Azure Functions-plug-in waarvan de bediende routes en gedeclareerde routes niet overeenkomen |
declared-input |
De lijst met queryparameters van een handler die niet overeenkomt met de gedeclareerde query van de route |
De map gates/ bevat de vijf vrijstellingsbestanden die een poort mag lezen (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json en invariant-seams.json), één reden per vermelding. Een lege reden telt als geen vermelding, en een vermelding die iets noemt dat niet meer bestaat, laat de poort falen. U kunt daar ook uw eigen poortmodules plaatsen, en nexus-gates pikt ze op naast de ingebouwde modules.
De pijplijn van de sjabloon
De template levert geen handgeschreven workflow mee. De pijplijnconfiguratie ervan benoemt de Dockerfile, het enige bouwargument (het registertoken), de proefuitvoering van de migratie en de opstartprobe, en de poort die de merge-wachtrij uitvoert. De volgorde is de volgorde waarin u zou willen dat het bij problemen mislukt.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, watcreate-nexus-plugin validate nexus.manifest.jsonisnpm run gates, watnexus-gates --self-testisnode scripts/ci/required-env
Er worden nog twee controles rond de image uitgevoerd. De migratie-dry-run past elk bestand toe op een tijdelijke Postgres voordat de image kan worden vrijgegeven, met dezelfde runner die productie gebruikt: nexus-migrate provision één keer als de superuser, en vervolgens elk genummerd bestand als de migrator. De boot-probe start de gebouwde image met zijn eigen entrypoint en elke variabele die required-env afdrukt, gericht op vervangers die verbindingen accepteren en nooit antwoorden. De server wacht op de database, binnen zijn begrensde tijdvenster, en dat wachten is het slaagsignaal; een configuratielader die weigert op te starten laat de build daar mislukken en niet in productie.
Wat het kost
De SDK neemt beslissingen uit uw handen, en sommige daarvan zou u anders hebben genomen. Het manifest weigert sleutels die het niet kent, de routetabel moet exact overeenkomen met uw code, de databaserollen zijn niet aan u om te ontwerpen, en de poorten laten een build mislukken bij een ontbrekend recht op een leesactie. Bij mijn eerste plug-in ben ik een dag in discussie geweest met api-contract over een route die ik had geregistreerd maar was vergeten te declareren. Het had gelijk; de route was onbeveiligd. Reken erop dat de eerste plug-in traag aanvoelt, en dat de tweede een derde van de tijd kost.

