InloggenBriefing plannen

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

22 minuten leestijd

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

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

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

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

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

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

Compatibiliteit
Compatibiliteit
Compatibiliteit laat zien welke SDK-versie werkt met welke platformversie, op basis van nachtelijke uitvoeringen van de snelstartgids (quickstart). Een ongetest paar geeft dit aan, en een falend paar noemt de wijziging waardoor het niet meer werkt.

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.

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

Bouwen op Community
Bouwen op Community
Op Community krijgt een ontwikkelaar dezelfde golden paths, een ontwikkelomgeving en datavertakkingen op één server, met code in hun eigen Git-host. Staging, pilot-units en gemaskeerde kopieën van live data zijn inbegrepen bij Enterprise.

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.