AnmeldenBriefing buchen

Kapitel 2.21

Das Plugin SDK

Installation des Plugin SDK (Software Development Kit), seine Befehlszeilen-Tools, ein Rundgang durch die Full-Service-Vorlage, das v2-Manifest Feld für Feld und die zweiundzwanzig Gates, die ein Plugin an die Regeln binden.

Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

22 Minuten Lesezeit

Mein zweites Plugin benötigte nur ein Drittel der Zeit meines ersten, und fast die gesamte Zeitersparnis war dem SDK (Software Development Kit) zu verdanken. Beim ersten Mal schrieb ich eine Bereichsprüfung (Scope Check), einen Konfigurationslader und einen Migrations-Runner, und ein Prüfer wies jeden einzelnen davon zurück. Beim zweiten Mal führte ich einen einzigen Scaffolding-Befehl aus, löschte den Beispiel-Sentiment-Skill und widmete meine Zeit den Datensätzen zur Anomalieprüfung, die unser Flugdynamik-Team tatsächlich benötigte.

@adverant-nexus/plugin-sdk ist ein einziges npm-Paket. Es enthält das v2-Manifest-Schema und die Validatoren, die es lesen (definePlugin, defineSkill), die Laufzeitmodule, die Ihr Plugin für Bereich, Datenbank, Dispatch und den Rest importiert, Testhilfen, die Einhaltungsschranken (Adherence Gates) sowie die Befehlszeilen-Tools. Dieses Kapitel behandelt die Installation, die Tools, die Vorlage, das Manifest und die Gates. Kapitel 2.22, Die Plugin-Laufzeitumgebung, behandelt die Laufzeitmodule in Ihrem ausgeführten Code.

Die Installation

Das Paket stammt aus der Registry von Adverant unter https://registry.adverant.ai/npm/, niemals aus der öffentlichen npm-Registry, und Sie benötigen das Pull-Token von der Seite „Pull tokens and install commands“ Ihres Kontos. Verweisen Sie den Bereich @adverant-nexus in der .npmrc Ihres Repositorys auf die Registry:

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

<pull-token> ist das Token von Ihrer Kontoseite. Übergeben Sie es in einer Pipeline aus einem Secret und committen Sie es niemals; das Dockerfile der Vorlage verweigert den Build ohne dieses Token und löscht .npmrc aus der Build-Stage, sobald npm ci durchgelaufen ist, sodass das Token niemals in einem Image ausgeliefert wird.

Fixieren Sie anschließend die exakte Version:

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

Committen Sie package-lock.json bei der ersten Installation. Der Image-Build der Vorlage führt npm ci aus und weigert sich, auf npm install zurückzufallen: Die Lockfile ist der Vertrag. Die Mindestvoraussetzung des SDK selbst ist Node 18; die Vorlage zielt auf Node 20 ab.

Die Befehlszeilen-Tools werden innerhalb des Pakets ausgeliefert, weshalb jeder Befehl in dieser Dokumentation das Paket und seine Version mit npx -p benennt. Alleinstehend wird npx create-nexus-plugin in der öffentlichen Registry nachgeschlagen, und dieser Name steht nicht für dieses Paket.

Die Befehlszeilen-Tools

Werkzeug Aufgabe
create-nexus-plugin Erstellt das Grundgerüst (Scaffolding) für ein Plugin, validiert ein Manifest, migriert ein v1-Manifest auf v2 und generiert den Leitfaden für Ihren Frontend-Entwickler
nexus-tenancy Generiert das Mandanten-SQL Ihres Schemas aus dem Manifest: Rollen, Berechtigungen (Grants), die Vorlage für Sicherheit auf Zeilenebene (Row-Level Security) und die Graphentabellen
nexus-migrate Wendet Ihre Migrationen an: stellt die Rollen einmalig bereit und führt dann jede nummerierte Datei unter der Migrator-Rolle aus
nexus-gates Führt jedes Adherence Gate sowie den eigenen Selbsttest jedes Gates aus

create-nexus-plugin führt keine Netzwerkaufrufe durch und lädt keinen Remote-Code. Es führt dieselben prozessinternen Validatoren aus, die auch beim Onboarding der Plattform laufen, sodass es keine Abweichung zwischen „auf meiner Maschine validiert“ und „von der Plattform akzeptiert“ gibt.

Befehl Markierungen Aufgabe Exit-Codes
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Schreibt ein neues Plugin-Verzeichnis; --print gibt nur das Manifest aus 0 geschrieben · 1 Überschreiben verweigert · 2 fehlerhafte Verwendung
validate <file> Validiert ein nexus.manifest.json oder ein .ts- bzw. .js-Modul, das eines exportiert 0 gültig · 1 ungültig oder unlesbar · 2 fehlerhafte Verwendung
migrate <file> --write Hebt ein v1-Manifest auf v2 an und gibt es aus oder überschreibt es an Ort und Stelle 0 · 1 · 2, wie oben
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Generiert den Konsumentenleitfaden aus dem Manifest und Ihrer Beschreibung; --check vergleicht ihn mit der committeten Kopie und schreibt nichts 0 · 1 Abweichung oder Linting-Verstoß · 2 fehlerhafte Verwendung
help Gibt die Verwendungshinweise aus 0

Scaffolding und die drei Stufen

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

--tier ist standardmäßig auf full-service eingestellt. Der Scaffolder weigert sich, in ein bereits existierendes Verzeichnis zu schreiben, und das von ihm geschriebene Manifest besteht bereits die Validierung; er gibt niemals ein ungültiges aus.

Wählen Sie die Stufe (Tier) danach aus, was Ihr Plugin beinhaltet.

Stufe Beinhaltet Muss deklarieren
skills-only Manifest-Skills und sonst nichts skills[], mit mindestens einem Eintrag
ui-only Eine Frontend-Oberfläche innerhalb der Shell frontend
full-service Ein Backend und ein Frontend, üblicherweise mit eigenem Schema backend und frontend; und da es ein Backend hat, runtime.healthCheck

Wenn Sie sich nicht sicher sind, erstellen Sie das Grundgerüst mit full-service und löschen Sie, was Sie nicht benötigen. Der umgekehrte Weg bedeutet, dass Sie die Teile selbst schreiben müssen, die Ihnen die Vorlage abgenommen hätte.

Ein Rundgang durch die Full-Service-Vorlage

Die Vorlage ist das Referenz-Plugin, aufgebaut nach dem strikten Muster, das jedes spätere Kapitel voraussetzt. Klonen Sie seine Struktur, nicht seine Beispiellogik.

Pfad Was es ist
nexus.manifest.json Das v2-Manifest: die drei Gesetze neu formuliert, die Routentabelle und ihr Rechteregister
src/config.ts Der Konfigurationslader. Eine Spezifikation, einmal gelesen, jedes Problem wird gesammelt, bevor der Prozess den Start verweigert
src/scope.ts Die eine Datei, die eine Anfrage in einen Bereich (Scope) umwandelt, mit dem strikten Token-Prüfer des SDK und zwei Regimen: dem Bearer-Token einer Person und dem Dienstaufruf der Plattform
src/db.ts Jede Anweisung bindet tenantFence() ein und läuft innerhalb von withScopedTx
src/uno.ts Die eine Dispatch-Datei: eine URL, ein Client, eine geschlossene Positivliste (Allow-List)
src/routes/*.ts health (anonym, exakter Pfad), die /api-Routen (bereichsgebunden) und der /internal-Callback (dienstgeschützt)
src/skills/sentiment.ts Ein deterministischer host_callback-Skill; ersetzen Sie das Lexikon durch Ihre eigene Logik
src/server.ts Die Kompositionswurzel (Composition Root): installiert einmalig das Ablehnungs-Ledger (Refusal Ledger), wartet auf die Datenbank (zeitlich begrenzt) und führt dann die Isolations- und Ledger-Prüfungen durch, bevor sie auf Anfragen lauscht
migrations/000_tenancy.sql Beim Scaffolding durch nexus-tenancy render generiert: Rollen, Schema, die Vorlage für Sicherheit auf Zeilenebene
migrations/001_init.sql Zwei Tabellen mit einem mandantenführenden zusammengesetzten Schlüssel und einem zusammengesetzten, mandantentragenden Fremdschlüssel
migrations/002_refusal_ledger.sql Die Tabelle, in die das Ablehnungs-Ledger schreibt
scripts/ci/required-env Gibt die Namen der für den Start erforderlichen Umgebungsvariablen als JSON aus
scripts/ci/shadow-migrate-*.sh Der Migrations-Trockenlauf der Pipeline über nexus-migrate
gates/ Das Ausnahmeverzeichnis der Gates: leer, was der korrekte Zustand für ein neues Plugin ist
test/ Tests für Bereich, Routen, Datenbank, Dispatch und den Startvorgang, mit den Bereichs-Doubles, die jeder Test injiziert
Dockerfile Ein Non-Root-Image (Benutzer-ID 10001) mit den darin enthaltenen Migrationen

Einige dieser Dateien lohnen einen genaueren Blick.

src/config.ts folgt zwei Regeln. Es sammelt jedes Problem, bevor es einen Fehler wirft, sodass ein einziger Neustart alle fünf fehlenden Variablen benennt, anstatt dass fünf Neustarts jeweils eine benennen. Und es setzt nur dann einen Standardwert, wenn ein falscher Wert keine stillschweigend falsche Antwort erzeugen kann: PORT darf standardmäßig 8080 sein, da ein falscher Port das Binden sichtbar fehlschlagen lässt, während DATABASE_URL und UNO_DISPATCH_URL erforderlich sind und Cluster-interne Adressen sein müssen. Eine öffentliche Adresse wird beim Start abgelehnt.

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

Der eigene Test der Vorlage führt diese Datei aus und vergleicht ihre Ausgabe mit den Namen, die in der Konfigurationsspezifikation als erforderlich markiert sind, sodass das Hinzufügen einer erforderlichen Variable ohne Aktualisierung der Liste dazu führt, dass npm test fehlschlägt.

src/server.ts lauscht erst auf Anfragen, wenn die Datenbank antwortet, und begrenzt die Wartezeit auf 120 Sekunden, wobei jeder fehlgeschlagene Versuch mit seiner Ursache protokolliert wird. Danach weist es der Reihe nach nach, dass die App-Rolle den Mandanten nicht neu binden kann und jede Tabelle zwingend der Sicherheit auf Zeilenebene unterliegt, dass der Pool jedes Pods in das Verbindungslimit der Rolle passt und dass die Tabelle des Ablehnungs-Ledgers eine Zeile aufnehmen kann. Eine Ablehnung bei einem der drei Punkte wird vollständig ausgegeben und der Prozess mit Code 2 beendet.

Das v2-Manifest, Feld für Feld

Das Manifest ist der maschinenlesbare Vertrag des Plugins mit der Plattform. Es wird validiert, wenn Sie es verfassen, wenn die Plattform es per Onboarding einbindet und danach fortlaufend. Das Schema lautet auf jeder Ebene additionalProperties: false: Wenn Ihr Plugin einen Abschnitt hat, gibt es dafür eine Eigenschaft, und ein nicht deklarierter Schlüssel wird abgelehnt. Die Lösung besteht immer darin, die richtige optionale Eigenschaft zu verwenden.

Der erforderliche Kern

Feld Regel
manifestVersion Exakt "2". Ein v1-Dokument wird migriert, niemals an Ort und Stelle neu validiert
name ^[a-z0-9]+([-.][a-z0-9]+)*$, höchstens 64 Zeichen. Die Plugin-ID, die bei der Registrierung, dem Dispatch-Namespacing und mandantengebundenen Zeilen verwendet wird. Ein Plugin, das Skills deklariert, benötigt außerdem einen Namen ohne Punkt und ohne führende Ziffer
displayName 1 bis 120 Zeichen
version Semantische Versionierung; Ihr eigener Release-Zyklus
description, author, license Jeweils mindestens ein Zeichen
tier skills-only, ui-only oder full-service
trust core, verified, community oder untrusted
runtime Erforderlich: executionMode, isolationLevel (1 bis 4), entrypoint. Optional: nodeVersion, healthCheck, readinessCheck, livenessCheck, jeweils ein Pfad, der mit / beginnt. Der Modus leitet sich aus der Stufe ab: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai und deploy, die drei Plattformgesetze neu formuliert. Der Validator gibt den Wortlaut fest vor

Für ein Plugin, das Sie für Ihre eigene Installation erstellen, lauten die drei Sätze wie folgt. Der Satz ai deckt künstliche Intelligenz (KI) ab und ist der Ort, um festzuhalten, dass das Plugin keine Modell-Anmeldedaten speichert.

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

Die Routentabelle: api und rights

api benötigt version und basePath sowie optional websocket (path, auth) und endpoints[]. Die Routentabelle ist das stärkste Konzept im Schema: Ein Gate gleicht sie in beide Richtungen mit den Routen ab, die Ihr Code tatsächlich registriert, sodass das Manifest ein überprüfbarer Vertrag und keine bloße Dokumentation ist.

Jeder Endpunkt benötigt method (GET, POST, PUT, PATCH oder DELETE) und path. Der Rest:

Feld Bedeutung
auth Eine von fünf Klassen: scope (die Route einer Person, hinter dem Scope Guard), service-key und internal (Server-zu-Server, niemals über einen Browser erreichbar), public (immer nur ein exakter Pfad mit allowAnonymous) und device (eine Maschine mit eigenen Anmeldedaten, hinter dem Device Guard)
right Erforderlich für jede Route, die der Scope Guard bedient, und auf jeder anderen abgelehnt: der Name eines Rechts im rights-Register
needsUnit Die Route verweigert den Dienst, wenn die Organisationseinheit des Aufrufers nicht aufgelöst werden kann
allowAnonymous Nur Positivliste mit exakter Übereinstimmung. Eine Präfixregel führt dazu, dass /health-of-tenant-42 versehentlich öffentlich wird
group, serves, screens Unter einem release-Block: die Fähigkeitsgruppe, die die Route bedient, was sie antwortet, wenn die lizenzierte Funktion dieser Gruppe gesperrt ist (data, teaser, sighting oder ask), und die Ansichten, die sie bedient
query required (jeder Name mit einem Beispielwert) und allowed: die Abfrageparameter (Query Parameters), die die Route liest
body example: ein Beispiel-Body einer Schreibroute, den ihr eigener Validator akzeptiert. Niemals bei einem GET

rights ist das Register, auf das sich diese Routen beziehen. Jedes Recht hat roles (die Obergrenze) und optional summary, never (Rollen, die es niemals ausüben dürfen, unabhängig davon, was sie sonst besitzen), barred (der produkteigene Wortlaut für die Ablehnung einer never-Rolle), seat (ein aktiver Arbeitsplatz (Seat) ist ebenfalls erforderlich), self (jede verifizierte Person besitzt es, für Rechte über ihre eigene Sitzung), grants (Inhaber vergeben Arbeitsplätze; höchstens ein Recht gibt dies an), licence (eine lizenzierte Funktion, die die Lizenz der Organisation enthalten muss), installation (nur im Besitz der Administratoren der jeweiligen Installation) und platform (nur im Besitz der Plattformadministratoren von Adverant; es benennt keine Rollen). Rechtsnamen enthalten mindestens einen 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 verweigert eine Bereichsroute ohne Recht (ENDPOINT_RIGHT_MISSING), ein Recht, das im Register fehlt (ENDPOINT_RIGHT_NOT_REGISTERED), und ein Recht auf einer Route, die kein Guard bedient (ENDPOINT_RIGHT_UNGUARDED). Es verweigert auch ein Register, das sich selbst widerspricht, sowie zwei Schreibweisen derselben Route (:id und :recordId) als DUPLICATE_ENDPOINT.

Ihre Daten: databases, schema und db

schema ist das eine Postgres-Schema, das dem Plugin gehört. public, plugins, auth und nexus sind verboten, und wenn databases[] ebenfalls ein Postgres-Schema benennt, müssen die beiden übereinstimmen.

databases[] deklariert jeden Speicher nach Engine: postgresql (schema, tables, migrations und granted, die Tabellen, die eine andere Organisation unter einer erfassten Berechtigung (Grant) lesen darf), neo4j (schemas), qdrant (collections) oder redis (purpose).

db enthält die Sitzungslimits für jede Verbindung, die das Plugin öffnet; sie werden hier deklariert statt ausprogrammiert, damit sowohl ein Prüfer als auch das Deployment sie lesen können:

Feld Was es begrenzt
maxConnections Den Pool pro Replikat
pods Die maximale Anzahl von Pods, die gleichzeitig einen Pool halten, also Replikate plus der Überschuss (Surge) eines Rolling Updates. Das Verbindungslimit jeder Rolle wird als maxConnections × pods generiert; lassen Sie es weg, warnt definePlugin mit DB_PODS_UNDECLARED
statementTimeoutMs Eine einzelne Anweisung
idleInTransactionTimeoutMs Eine offene Transaktion, die nichts ausführt
workMemKB Einen Sortier- oder Hash-Knoten, pro Knoten, nicht pro Abfrage
piiMask[] table.column-Einträge mit personenbezogenen Daten, die in der verwalteten SQL-Konsole und in Protokollen maskiert werden

Skills und Tools: skills, mcpTools, entitlements

skills[] enthält Manifest-Skills; Kapitel 2.20, Skills, behandelt deren Felder und Stufen. mcpTools[] enthält die MCP-Tools (Model Context Protocol), die das Plugin veröffentlicht, jeweils ein name, eine description und ein inputSchema ohne oneOf, allOf oder anyOf auf oberster Ebene.

entitlements erfordert featureIdPattern und akzeptiert alwaysOn[], source und store. Das Muster benennt den Namespace, in dem Ihre Funktions-IDs leben, üblicherweise die name des Plugins plus ein Segment, das Ihr Code pro Oberfläche ausfüllt. alwaysOn[] ist die kurze, exakte Liste, die selbst dann antworten muss, wenn kein Berechtigungsurteil (Entitlement Verdict) eingeholt werden kann: Systemzustand (Health), Betriebsbereitschaft (Readiness), Anmeldung und die Einstellungen, die ein Administrator benötigt, um die Berechtigung zu reparieren.

Änderungskontrolle: changePolicy

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

Genehmigungen werden nach unterschiedlichen Personen gezählt, und die Person, die die Änderung vorgeschlagen hat, zählt niemals dazu; ohne diese beiden Bedingungen wird aus „zwei Genehmigungen“ eine Person, die zweimal klickt. enabled: true erfordert classes, und jede genannte Klasse benötigt ihre eigene Anzahl. Eine Klasse, die Sie weglassen, unterliegt keiner Steuerung (ungoverned), was eine legitime Entscheidung ist, die Sie laut Schema aber explizit festhalten müssen.

Wer Sie sind: domains, branding, routing

domains[] (jeweils primary und aliases[]; domain ist die Form für eine einzelne Domain) listet auf, wo das Plugin antwortet. branding erfordert appName und akzeptiert tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId und gaId. Alles in branding ist öffentlich: Die Anmeldeseite liest es, bevor jemand Anmeldedaten besitzt, daher enthält es niemals ein Secret oder eine interne Adresse. routing (type, gateway, virtualService) ist für Plugins gedacht, die ihr eigenes Routing beschreiben.

Dimensionierung und der Rest

resources erfordert cpuMillicores (10 bis 64.000) und memoryMB (16 bis 262.144) und akzeptiert diskGB, timeoutMs, port und wsPort. backend enthält port, healthPath, apiPrefix, framework und platformClients[], die SDK-Clients, die Ihr Backend namentlich importiert. Die Liste ist geschlossen, und ein Gate gleicht sie mit Ihren Importen ab. Das Schema erlaubt vierzehn Namen: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin und uno sowie einen für den Client, der Ablehnungen von Tarifberechtigungen (Plan-Entitlements) beantwortet und einen internen Namen behält. Der Client für Funktionsberechtigungen (Feature-Entitlements), runtime/entitlements, gehört nicht dazu und steht niemals auf der Liste, da Ihr entitlements-Block ihn bereits deklariert, und ein Backend, das ihn ohne entitlements-Block importiert, fällt durch dasselbe Gate. frontend enthält basePath, mountPath und framework. nexus enthält minVersion, maxVersion, capabilities[] und permissions[].

Die verbleibenden Blöcke erfüllen jeweils genau eine Aufgabe:

Blockieren Für
settings Ihre Einstellungen auf dem gemeinsamen Framework: groups und keys, festgelegt auf den jeweils genannten Ebenen
people sweep (service, port): die Mitglieder der Organisation, synchronisiert vom Identitätsdienst, wobei Arbeitsplätze (Seats) abgeschaltet werden, wenn jemand das Unternehmen verlässt
ontology entityTypes und relationshipTypes: der typisierte Graph, der in Ihrem eigenen Schema gehalten wird
release groups und frame: die Fähigkeitsgruppen, in denen Ihre Routen bereitgestellt werden, zuerst veröffentlicht als Canary-Release
cells[] Ein Plugin, das aus mehreren bereitstellbaren Einheiten (Deployables) besteht: jeweils name, kind, entrypoint, port, wsPort
pricing model, currency, tiers[] für Ihren Katalogeintrag
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Wer es veröffentlicht und wo sein Code liegt
metrics, atlas Die zwei bewusst offenen Objekte für Ihre eigenen Metriknamen und die Generierung der Architektur-Dokumentation

Was das Schema nicht ausdrücken kann

Das JSON-Schema legt die Form fest; definePlugin fügt die Regeln hinzu, die ein Schema nicht ausdrücken kann. Das classification eines Skills darf die Vertrauensobergrenze (Trust Ceiling) nicht überschreiten. Nur core- und verified-Plugins dürfen tool_using- und llm_only-Skills deklarieren. Jeder deklarierte Pfad muss relativ und gleichen Ursprungs (Same-Origin) sein, ohne Schema, ohne // und ohne Backslash, da der URL-Parser \ zu / umwandelt und /\evil.example/x ursprungsübergreifend (Cross-Origin) auflöst. Jede Regel, die die Registry-Synchronisierung auf einen Skill anwendet, wird hier zuerst angewendet, und zwar mit dem eigenen Code der Synchronisierung, sodass validate und die Synchronisierung eine verletzte Regel auf dieselbe Weise benennen.

Validierung und Wechsel von 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

Ein Fehler gibt den genauen Pfad und, bei einer Synchronisierungsregel, zuerst den Code aus. Machen Sie dies zu einem Commit-Hook.

Ein v1-Manifest lässt sich mechanisch anheben. migrate fügt die drei Gesetzessätze hinzu, verschiebt domain nach domains[] und weigert sich, einen Einstiegspunkt (Entrypoint) zu erfinden, den Sie nicht hatten. Es validiert das Ergebnis, bevor es etwas ausgibt oder schreibt, sodass eine Migration niemals einen Fehler vom Tool in Ihr Repository überträgt.

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

Lesen Sie das Diff, bevor Sie es committen. Die hinzugefügten Gesetzessätze entsprechen dem Wortlaut, den der Validator fest vorgibt; setzen Sie für Ihre eigene Installation deploy auf den weiter oben gezeigten Satz.

Rendern des Mandanten und Bereitstellen der Rollen

Sie schreiben Ihre Rollenberechtigungen (Role Grants) oder die Vorlage für Sicherheit auf Zeilenebene niemals von Hand. nexus-tenancy render schreibt sie aus dem schema und den db des Manifests:

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

Die generierte Datei erstellt fünf Rollen für das Schema, jede mit dem, was sie nicht besitzen darf: einen Migrator, der nur zum Owner werden kann, einen Owner, der sich nicht anmelden kann, eine App-Rolle für den Anfragepfad, eine Report-Rolle, die nur Aggregate sieht, und eine Ledger-Rolle, die nur Daten anhängen (append) kann. Keine Rolle besitzt BYPASSRLS. Der einzige Weg, einen Mandanten zu binden, führt über eine einzige Datenbankfunktion, und set_config wird jeder Rolle außer dem Owner entzogen.

Eine angewendete Mandantendatei wird niemals bearbeitet. Eine Änderung ist eine Revision mit ihrer eigenen Nummer-0-Datei, und der Lese-Arbeitsplatz (Read Seat) für organisationsübergreifende Berechtigungen (Grants) wird auf diese Weise als Revision 2 eingeführt. --graph generiert die zwei Tabellen des typisierten Graphen, den Ihr ontology deklariert, als Ihre nächste nummerierte Migration.

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

Die Mandantendatei erstellt genau die Rollen, als die sich der Runner verbindet, weshalb sie vom Datenbank-Owner mit nexus-migrate provision angewendet wird:

DATABASE_URL=<database-owner-url> npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate provision --state <dir>

<database-owner-url> ist eine Verbindungszeichenfolge (Connection String) für den Datenbank-Owner, und <dir> ist ein privates Verzeichnis. Die Bereitstellung (Provision) wendet die Basis-Mandantendatei und jede Revision der Reihe nach an, schreibt migrator.url und app.url (sowie seat.url, sobald Revision 2 existiert) mit dem Modus 0600 nach <dir> und gibt keinerlei geheime Daten aus. Sie legt bei jedem Durchlauf das Verbindungslimit jeder Rolle aus db.maxConnections × db.pods fest. Ein erneuter Durchlauf behält bestehende Passwörter bei, sofern Sie nichts anderes anfordern: --passwords <dir> setzt sie aus Dateien und --rotate <roles> vergibt für die genannten Rollen neue. Wandeln Sie die Dateien in die Secrets Ihres Deployments um.

Danach verbindet sich der Anwendungsvorgang mit der Verbindungszeichenfolge des Migrators, die bei der Bereitstellung geschrieben wurde:

DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.json

Er führt die Dateien ab 001 als Migrator aus, jede Datei unter SET ROLE <schema>_owner, eine Transaktion pro Datei. Er führt ein Ledger, <schema>.schema_migrations, mit der Prüfsumme jeder Datei; eine bereits angewendete Datei, deren Bytes sich geändert haben, wird namentlich abgelehnt (CHECKSUM_DRIFT), niemals erneut ausgeführt und niemals übersprungen. Jede ausstehende Datei wird mit der echten Postgres-Grammatik geparst, bevor die erste ausgeführt wird, sodass eine Ablehnung die Datenbank unberührt lässt. Der einzige Header, den eine Datei tragen darf, ist -- nexus-migration: transaction=file|per-statement, mit optionalen Sperr- und Anweisungs-Timeouts; per-statement ist für CREATE INDEX CONCURRENTLY vorgesehen.

Die Gates

nexus-gates führt zweiundzwanzig Gates aus. Jedes codiert eine Fehlerklasse, damit sie nicht zweimal ausgeliefert werden kann, und jedes hat einen Selbsttest, der beweist, dass es bei einer Testumgebung (Fixture), die zum Auslösen des Fehlers gebaut wurde, fehlschlägt. Führen Sie sie vor dem Pushen aus:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Freigabe Was es abfängt
scope-adherence Eine /api-Route ohne den Scope Guard; einen anonymen Pfad, der kein exakt deklarierter ist; eine Geräteroute ohne den Device Guard oder mit dem Guard einer Person daneben
one-fence Ein Mandantenprädikat, das an mehr als einer einzigen Stelle definiert ist, einschließlich einer selbstgeschriebenen Arbeitsplatz- oder Berechtigungsschranke (Seat/Grant Fence)
sql-fence Eine Anweisung, die eine bereichsgebundene Tabelle ohne die Schranke (Fence) liest oder aktualisiert, in einem beliebigen FROM-, JOIN-, USING- oder UPDATE-Ziel
migrations-are-scoped Eine Tabelle, der eine Achse, ein mandantenführender zusammengesetzter Schlüssel, ein mandantentragender Fremdschlüssel oder die Demo-Spalte fehlt
migrations-commit-what-they-open Eine Migration, deren BEGIN-Anzahl nicht mit ihrer COMMIT- und ROLLBACK-Anzahl übereinstimmt
no-direct-compute Einen direkten Aufruf an einen Modellanbieter, eine Engine, eine Warteschlange (Queue) oder einen Workflow-Host; einen zweiten Leser der Dispatch-URL
no-credentials Anmeldedaten eines Modellanbieters, die im Repository oder in der Umgebung lesbar sind
crud-adherence Eine mutierende Route, deren Rechteprüfung nichts im Register benennt
blocked-backends Eine Route, die weder bedient noch namentlich blockiert, per Gesetz abgelehnt oder an anderer Stelle verwaltet wird
every-test-runs Tests, die das Glob-Muster des Testskripts niemals erreicht
tiles-are-invariant Eine mandanteninvariante zwischengespeicherte Schnittstelle (Cached Seam), die einen Mandantenwert liest oder die Authentifizierung überspringt
api-contract Eine registrierte Route, die das Manifest nicht deklariert, oder eine deklarierte Route, die der Code niemals registriert
rls-present Eine Tabelle ohne erzwungene Sicherheit auf Zeilenebene; eine SECURITY DEFINER-Funktion ohne fest vorgegebenen search_path
no-set-config Plugin-Code, der die Mandanteneinstellung selbst bindet
db-role-honest Einen Anfragepfad, der sich als Owner oder Migrator verbindet oder SUPERUSER bzw. BYPASSRLS anfordert
platform-clients Einen SDK-Client, der importiert, aber nicht in backend.platformClients aufgeführt ist, oder aufgeführt, aber niemals importiert wird
rights-register Eine Bereichsroute ohne deklariertes Recht; eine Rechteprüfung am Register vorbei
refusal-ledger Eine deklarierte Ablehnungstabelle ohne installiertes Ledger oder einen Ablehnungs-Body, der daran vorbei gesendet wird
grants-declared Eine freigegebene Tabelle (Granted Table), die das Manifest nicht deklariert; von Hand vergebene Berechtigungen für Lese-Arbeitsplätze (Read-Seat Privileges)
people-declared Einen people-Block ohne seine Sweep-Route, seinen Guard und seine Tabellen
functions-closure Ein Azure-Functions-Plugin, dessen bediente Routen und deklarierte Routen nicht übereinstimmen
declared-input Die Liste der Abfrageparameter eines Handlers, die nicht mit den für die Route deklarierten query übereinstimmt

Das Verzeichnis gates/ enthält die fünf Ausnahmedateien, die ein Gate lesen darf (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json und invariant-seams.json), eine Begründung pro Eintrag. Eine leere Begründung zählt als fehlender Eintrag, und ein Eintrag, der etwas benennt, das nicht mehr existiert, lässt das Gate fehlschlagen. Sie können dort auch Ihre eigenen Gate-Module ablegen, und nexus-gates erfasst diese zusammen mit den integrierten.

Kompatibilität
Kompatibilität
Die Kompatibilität zeigt basierend auf nächtlichen Durchläufen des Quickstarts, welche SDK-Version mit welcher Plattformversion funktioniert. Ein ungetestetes Paar wird als solches ausgewiesen, und ein fehlschlagendes Paar benennt die Änderung, die den Fehler verursacht hat.

Die Pipeline der Vorlage

Die Vorlage liefert keinen handgeschriebenen Workflow aus. Ihre Pipeline-Konfiguration benennt das Dockerfile, das eine Build-Argument (das Registry-Token), den Migrations-Trockenlauf und die Startprüfung (Boot Probe) sowie das Gate, das die Merge-Warteschlange (Merge Queue) ausführt. Die Reihenfolge entspricht genau der Reihenfolge, in der ein eventuelles Fehlschlagen auftreten soll.

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

Zwei weitere Prüfungen laufen rund um das Image. Der Migrations-Testlauf wendet jede Datei auf eine temporäre Postgres-Instanz an, bevor das Image freigegeben werden kann, und zwar mit demselben Runner, den auch die Produktion nutzt: nexus-migrate provision einmal als Superuser, dann jede nummerierte Datei als Migrator. Die Boot-Probe startet das gebaute Image mit seinem eigenen Entrypoint und jeder Variable, die required-env ausgibt, ausgerichtet auf Platzhalter, die Verbindungen annehmen und niemals antworten. Der Server wartet innerhalb seines begrenzten Zeitfensters auf die Datenbank, und dieses Warten ist das Signal für das Bestehen; ein Konfigurations-Loader, der das Booten verweigert, lässt den Build dort fehlschlagen und nicht erst in der Produktion.

Entwickeln mit Community
Entwickeln mit Community
In der Community-Edition erhält ein Entwickler dieselben Golden Paths, eine Entwicklungsumgebung und Daten-Branches auf einem Server, wobei der Code auf dem eigenen Git-Host liegt. Staging, Pilot-Einheiten und maskierte Kopien von Live-Daten sind in der Enterprise-Edition enthalten.

Was es kostet

Das SDK nimmt Ihnen Entscheidungen ab, und einige davon hätten Sie anders getroffen. Das Manifest lehnt ihm unbekannte Schlüssel ab, die Routentabelle muss exakt mit Ihrem Code übereinstimmen, die Datenbankrollen können Sie nicht selbst entwerfen, und die Gates lassen einen Build wegen eines fehlenden Rechts bei einem Lesezugriff fehlschlagen. Bei meinem ersten Plugin habe ich einen Tag lang mit api-contract über eine Route gestritten, die ich registriert, aber vergessen hatte zu deklarieren. Es hatte recht; die Route war ungeschützt. Rechnen Sie damit, dass sich das erste Plugin langsam anfühlt, und dass das zweite nur noch ein Drittel der Zeit in Anspruch nimmt.