Version 1.0.0-alpha.1dernière version
Chapitre 2.21
Le SDK de plugin
L'installation du SDK (kit de développement logiciel) de plugin, ses outils en ligne de commande, une présentation du modèle complet, le manifeste v2 champ par champ, et les vingt-deux portes de contrôle qui soumettent un plugin aux règles.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

Mon deuxième plugin m'a pris le tiers du temps du premier, et la quasi-totalité de ce gain venait du SDK (kit de développement logiciel). La première fois, j'ai écrit un contrôle de périmètre, un chargeur de configuration et un exécuteur de migrations, et un examinateur a renvoyé chacun d'eux. La deuxième fois, j'ai exécuté une seule commande d'échafaudage, supprimé la compétence d'analyse de sentiment fournie en exemple, et consacré mes journées aux enregistrements d'examen des anomalies dont notre équipe de dynamique du vol avait réellement besoin.
@adverant-nexus/plugin-sdk est un unique paquet npm. Il contient le schéma de manifeste v2 et les validateurs qui le lisent (definePlugin, defineSkill), les modules d'exécution que votre plugin importe pour le périmètre, la base de données, l'acheminement et le reste, des utilitaires de test, les portes de conformité et les outils en ligne de commande. Ce chapitre couvre son installation, les outils, le modèle, le manifeste et les portes. Le chapitre 2.22, L'environnement d'exécution du plugin, couvre les modules d'exécution dans votre code en cours d'exécution.
Installation
Le paquet provient du registre d'Adverant à l'adresse https://registry.adverant.ai/npm/, jamais du registre npm public, et vous avez besoin du jeton d'extraction disponible sur la page « Pull tokens and install commands » de votre compte. Faites pointer le périmètre @adverant-nexus vers le registre dans le fichier .npmrc de votre dépôt :
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> est le jeton issu de la page de votre compte. Dans un pipeline, transmettez-le depuis un secret et ne le validez jamais dans le dépôt ; le Dockerfile du modèle refuse de compiler sans lui et supprime .npmrc de l'étape de construction une fois npm ci exécuté, de sorte que le jeton n'est jamais livré dans une image.
Épinglez ensuite la version exacte :
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Validez package-lock.json dès la première installation. La construction d'image du modèle exécute npm ci et refuse de se replier sur npm install : le fichier de verrouillage constitue le contrat. Le seuil minimal du SDK lui-même est Node 18 ; le modèle cible Node 20.
Les outils en ligne de commande étant livrés à l'intérieur du paquet, chaque commande de cette documentation nomme le paquet et sa version avec npx -p. Seul, npx create-nexus-plugin est recherché sur le registre public, et ce nom ne correspond pas à ce paquet.
Les outils en ligne de commande
| Outil | Ce qu'il fait |
|---|---|
create-nexus-plugin |
Échafaude un plugin, valide un manifeste, migre un manifeste v1 vers v2 et génère le guide du consommateur pour votre développeur frontend |
nexus-tenancy |
Génère le SQL de cloisonnement des locataires de votre schéma à partir du manifeste : les rôles, les droits d'accès, le modèle de sécurité au niveau des lignes et les tables de graphe |
nexus-migrate |
Applique vos migrations : provisionne les rôles une seule fois, puis exécute chaque fichier numéroté sous le rôle de migrateur |
nexus-gates |
Exécute chaque porte de conformité, ainsi que l'autotest propre à chacune |
create-nexus-plugin n'effectue aucun appel réseau et ne charge aucun code distant. Il exécute en mémoire les mêmes validateurs que le processus d'intégration de la plateforme, de sorte qu'il n'y a aucun écart entre « cela a été validé sur ma machine » et « la plateforme l'a accepté ».
| Verbe | Options | Ce qu'il fait | Codes de sortie |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Écrit un nouveau répertoire de plugin ; --print affiche uniquement le manifeste |
0 écrit · 1 refus d'écraser · 2 mauvaise utilisation |
validate <file> |
Valide un nexus.manifest.json, ou un module .ts ou .js qui en exporte un |
0 valide · 1 invalide ou illisible · 2 mauvaise utilisation | |
migrate <file> |
--write |
Convertit un manifeste v1 en v2 et l'affiche, ou l'écrit sur place | 0 · 1 · 2, comme ci-dessus |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Génère le guide du consommateur à partir du manifeste et de votre texte descriptif ; --check le compare à la copie validée et n'écrit rien |
0 · 1 dérive ou erreur de lint · 2 mauvaise utilisation |
help |
Affiche l'aide d'utilisation | 0 |
Génération de squelette et les trois niveaux
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-serviceLa valeur par défaut de --tier est full-service. L'outil d'échafaudage refuse d'écrire dans un répertoire existant, et le manifeste qu'il génère réussit déjà la validation ; il n'en produit jamais d'invalide.
Choisissez le niveau selon ce que contient votre plugin.
| Palier | Contient | Doit déclarer |
|---|---|---|
skills-only |
Des compétences de manifeste et rien d'autre | skills[], avec au moins une entrée |
ui-only |
Une surface frontend à l'intérieur du shell | frontend |
full-service |
Un backend et un frontend, généralement avec son propre schéma | backend et frontend ; et parce qu'il comporte un backend, runtime.healthCheck |
En cas de doute, échafaudez full-service et supprimez ce dont vous n'avez pas besoin. Procéder dans le sens inverse implique d'écrire vous-même les éléments que le modèle vous aurait fournis.
Présentation du modèle complet
Le modèle est le plugin de référence, construit selon le schéma strict que tous les chapitres suivants supposent. Clonez sa structure, pas sa logique d'exemple.
| Chemin | En quoi cela consiste |
|---|---|
nexus.manifest.json |
Le manifeste v2 : les trois lois réénoncées, la table de routage et son registre des droits |
src/config.ts |
Le chargeur de configuration. Une seule spécification, lue une seule fois, chaque problème étant collecté avant que le processus ne refuse de démarrer |
src/scope.ts |
L'unique fichier qui transforme une requête en un périmètre, avec le vérificateur de jeton strict du SDK et deux régimes : le jeton au porteur d'une personne et l'appel de service de la plateforme |
src/db.ts |
Chaque instruction compose tenantFence() et s'exécute à l'intérieur de withScopedTx |
src/uno.ts |
L'unique fichier d'acheminement : une URL, un client, une liste d'autorisation fermée |
src/routes/*.ts |
health (anonyme, chemin exact), les routes /api (soumises au périmètre) et le rappel /internal (protégé par la garde de service) |
src/skills/sentiment.ts |
Une compétence host_callback déterministe ; remplacez le lexique par votre propre logique |
src/server.ts |
La racine de composition : installe le grand livre des refus une seule fois, attend la base de données (attente bornée), puis exécute les vérifications d'isolation et de grand livre avant d'écouter |
migrations/000_tenancy.sql |
Généré par nexus-tenancy render au moment de l'échafaudage : les rôles, le schéma, le modèle de sécurité au niveau des lignes |
migrations/001_init.sql |
Deux tables avec une clé composite commençant par le locataire et une clé étrangère composite portant le locataire |
migrations/002_refusal_ledger.sql |
La table dans laquelle écrit le grand livre des refus |
scripts/ci/required-env |
Affiche au format JSON les noms des variables d'environnement requises au démarrage |
scripts/ci/shadow-migrate-*.sh |
L'exécution à blanc des migrations du pipeline, via nexus-migrate |
gates/ |
Le répertoire d'exemptions des portes : vide, ce qui est l'état correct pour un nouveau plugin |
test/ |
Des tests pour le périmètre, les routes, la base de données, l'acheminement et le démarrage, avec les doublures de périmètre que chaque test injecte |
Dockerfile |
Une image non-root (ID utilisateur 10001) contenant les migrations |
Quelques-uns de ces fichiers méritent un examen plus attentif.
src/config.ts suit deux règles. Il collecte tous les problèmes avant de lever une exception, de sorte qu'un seul redémarrage nomme les cinq variables manquantes au lieu de cinq redémarrages en nommant une chacun. Et il n'attribue une valeur par défaut que lorsqu'une valeur erronée ne peut pas produire silencieusement une réponse fausse : PORT peut prendre 8080 par défaut, car un mauvais port fait échouer la liaison de manière visible, tandis que DATABASE_URL et UNO_DISPATCH_URL sont obligatoires et doivent être des adresses internes au cluster. Une adresse publique est refusée au démarrage.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
Le test propre au modèle exécute ce fichier et compare sa sortie aux noms que la spécification de configuration marque comme obligatoires ; ainsi, l'ajout d'une variable obligatoire sans mettre à jour la liste fait échouer npm test.
src/server.ts n'écoute pas tant que la base de données ne répond pas, et il limite l'attente à 120 secondes, en journalisant chaque tentative échouée avec sa cause. Puis il prouve, dans l'ordre, que le rôle applicatif ne peut pas réassocier le locataire et que chaque table est soumise de force à la sécurité au niveau des lignes, que le pool de chaque pod respecte la limite de connexions du rôle, et que la table du grand livre des refus peut accepter une ligne. Un refus de l'un des trois est affiché intégralement et le processus se termine avec le code 2.
Le manifeste v2, champ par champ
Le manifeste est le contrat lisible par machine que le plugin passe avec la plateforme. Il est validé lorsque vous le rédigez, lorsque la plateforme l'intègre, puis en continu par la suite. Le schéma applique additionalProperties: false à chaque niveau : si votre plugin comporte une section, une propriété est prévue à cet effet, et toute clé non déclarée est refusée. La solution consiste toujours à utiliser la bonne propriété facultative.
Le socle obligatoire
| Champ | Règle |
|---|---|
manifestVersion |
Exactement "2". Un document v1 est migré, jamais revalidé sur place |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, 64 caractères au maximum. L'identifiant du plugin utilisé lors de l'enregistrement, dans l'espace de noms d'acheminement et dans les lignes rattachées au locataire. Un plugin qui déclare des compétences doit également avoir un nom sans point et ne commençant pas par un chiffre |
displayName |
De 1 à 120 caractères |
version |
Version sémantique ; votre propre cycle de publication |
description, author, license |
Au moins un caractère chacun |
tier |
skills-only, ui-only ou full-service |
trust |
core, verified, community ou untrusted |
runtime |
Obligatoires : executionMode, isolationLevel (de 1 à 4), entrypoint. Facultatifs : nodeVersion, healthCheck, readinessCheck, livenessCheck, chacun étant un chemin commençant par /. Le mode découle du niveau : 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai et deploy, les trois lois de la plateforme réénoncées. Le validateur impose la formulation exacte |
Pour un plugin que vous développez pour votre propre installation, les trois phrases se lisent comme suit. La phrase ai couvre l'intelligence artificielle (IA) et constitue l'endroit où indiquer que le plugin ne détient aucun identifiant de modèle.
"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."
}La table de routage : api et rights
api requiert version et basePath, et accepte en option websocket (path, auth) et endpoints[]. La table de routage est le concept le plus fort du schéma : une porte la compare dans les deux sens aux routes que votre code enregistre réellement, de sorte que le manifeste constitue un contrat vérifiable et non une simple documentation.
Chaque point de terminaison requiert method (GET, POST, PUT, PATCH ou DELETE) et path. Le reste :
| Champ | Ce qu'il indique |
|---|---|
auth |
L'une des cinq classes : scope (la route d'une personne, derrière la garde de périmètre), service-key et internal (de serveur à serveur, jamais accessible depuis un navigateur), public (uniquement un chemin exact avec allowAnonymous), et device (une machine dotée de son propre identifiant, derrière la garde d'appareil) |
right |
Obligatoire sur chaque route servie par la garde de périmètre, et refusé sur toute autre : le nom d'un droit figurant dans le registre rights |
needsUnit |
La route oppose un refus lorsque l'unité de l'appelant ne peut pas être résolue |
allowAnonymous |
Liste d'autorisation par correspondance exacte uniquement. C'est avec une règle de préfixe que /health-of-tenant-42 finit par devenir public |
group, serves, screens |
Sous un bloc release : le groupe de capacités que sert la route, ce qu'elle répond lorsque la fonctionnalité sous licence de ce groupe est verrouillée (data, teaser, sighting ou ask), et les écrans qu'elle dessert |
query |
required (chaque nom accompagné d'une valeur d'exemple) et allowed : les paramètres de requête que lit la route |
body |
example : un exemple de corps de requête pour une route d'écriture, que son propre validateur accepte. Jamais sur un GET |
rights est le registre que nomment ces routes. Chaque droit possède roles (le plafond) et, en option, summary, never (les rôles qui ne peuvent jamais l'exercer, quels que soient leurs autres droits), barred (la formulation propre au produit pour refuser un rôle never), seat (un siège actif est également requis), self (toute personne vérifiée le détient, pour les droits portant sur sa propre session), grants (les détenteurs attribuent des sièges ; un droit au maximum le déclare), licence (une fonctionnalité sous licence que la licence de l'organisation doit comporter), installation (détenu uniquement par les administrateurs propres à l'installation) et platform (détenu uniquement par les administrateurs de la plateforme d'Adverant ; il ne nomme aucun rôle). Les noms de droits comportent au moins un point : 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 refuse une route de périmètre sans droit (ENDPOINT_RIGHT_MISSING), un droit absent du registre (ENDPOINT_RIGHT_NOT_REGISTERED) et un droit sur une route qu'aucune garde ne sert (ENDPOINT_RIGHT_UNGUARDED). Il refuse également un registre qui se contredit lui-même, ainsi que deux écritures d'une même route (:id et :recordId) sous le code DUPLICATE_ENDPOINT.
Vos données : databases, schema et db
schema est l'unique schéma Postgres que possède le plugin. public, plugins, auth et nexus sont interdits, et si databases[] nomme également un schéma Postgres, les deux doivent correspondre.
databases[] déclare chaque magasin par moteur : postgresql (schema, tables, migrations et granted, les tables qu'une autre organisation peut lire en vertu d'une autorisation enregistrée), neo4j (schemas), qdrant (collections) ou redis (purpose).
db contient les limites de session pour chaque connexion qu'ouvre le plugin, déclarées ici plutôt que codées en dur afin qu'un examinateur comme le déploiement puissent les lire :
| Champ | Ce qu'elle limite |
|---|---|
maxConnections |
Le pool par réplica |
pods |
Le nombre maximal de pods détenant un pool simultanément, soit les réplicas plus le pic d'une mise à jour progressive. La limite de connexions de chaque rôle est calculée selon maxConnections × pods ; si vous l'omettez, definePlugin émet l'avertissement DB_PODS_UNDECLARED |
statementTimeoutMs |
Une seule instruction |
idleInTransactionTimeoutMs |
Une transaction ouverte qui n'exécute rien |
workMemKB |
Un nœud de tri ou de hachage, par nœud et non par requête |
piiMask[] |
Des entrées table.column contenant des données personnelles, masquées dans la console SQL gouvernée et dans les journaux |
Compétences et outils : skills, mcpTools, entitlements
skills[] contient les compétences de manifeste ; le chapitre 2.20, Compétences, couvre leurs champs et leurs niveaux. mcpTools[] contient les outils MCP (Model Context Protocol) que publie le plugin, chacun étant composé d'un name, d'une description et d'un inputSchema sans oneOf, allOf ni anyOf de premier niveau.
entitlements requiert featureIdPattern et accepte alwaysOn[], source et store. Le motif nomme l'espace de noms dans lequel résident vos identifiants de fonctionnalités, par convention le name du plugin suivi d'un segment que votre code renseigne par surface. alwaysOn[] est la liste courte et exacte des chemins qui doivent répondre même lorsqu'aucun verdict de droits d'accès ne peut être obtenu : la santé, la disponibilité, la connexion et les paramètres dont un administrateur a besoin pour rétablir les droits d'accès.
Contrôle des changements : changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Les approbations se comptent en personnes distinctes, et la personne qui a proposé le changement n'en fait jamais partie ; sans ces deux conditions, « deux approbations » se résume à une seule personne cliquant deux fois. enabled: true requiert classes, et chaque classe nommée doit avoir son propre décompte. Une classe que vous omettez n'est pas gouvernée, ce qui est un choix légitime que le schéma vous oblige à formuler par écrit.
Qui vous êtes : domains, branding, routing
domains[] (chacun avec primary et aliases[] ; domain est la forme à domaine unique) répertorie les adresses où répond le plugin. branding requiert appName et accepte tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId et gaId. Tout ce qui figure dans branding est public : la page de connexion le lit avant même que quiconque ne dispose d'un identifiant, de sorte qu'il ne contient jamais de secret ni d'adresse interne. routing (type, gateway, virtualService) est destiné aux plugins qui décrivent leur propre routage.
Dimensionnement et autres paramètres
resources requiert cpuMillicores (de 10 à 64 000) et memoryMB (de 16 à 262 144), et accepte diskGB, timeoutMs, port et wsPort. backend contient port, healthPath, apiPrefix, framework et platformClients[], les clients du SDK que votre backend importe par leur nom. La liste est fermée, et une porte la vérifie par rapport à vos importations. Le schéma autorise quatorze noms : access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin et uno, plus un pour le client qui répond aux refus de droits liés au forfait, lequel conserve un nom interne. Le client de droits d'accès aux fonctionnalités, runtime/entitlements, n'en fait pas partie et ne figure jamais sur la liste, car votre bloc entitlements le déclare déjà, et un backend qui l'importe sans bloc entitlements échoue à la même porte. frontend contient basePath, mountPath et framework. nexus contient minVersion, maxVersion, capabilities[] et permissions[].
Les blocs restants remplissent chacun une fonction précise :
| Bloc | Fonction |
|---|---|
settings |
Vos paramètres sur le cadre partagé : groups et keys, définis aux niveaux que chacun nomme |
people |
sweep (service, port) : les membres de l'organisation, synchronisés depuis le service d'identité, avec désactivation des sièges lorsqu'une personne quitte l'organisation |
ontology |
entityTypes et relationshipTypes : le graphe typé conservé dans votre propre schéma |
release |
groups et frame : les groupes de capacités dans lesquels vos routes sont réparties, publiés d'abord en version canari |
cells[] |
Un plugin composé de plusieurs unités déployables : name, kind, entrypoint, port, wsPort pour chacune |
pricing |
model, currency, tiers[] pour votre fiche de catalogue |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Qui le publie et où réside son code |
metrics, atlas |
Les deux objets délibérément ouverts, pour vos propres noms de métriques et la génération de documentation d'architecture |
Ce que le schéma ne peut pas exprimer
Le schéma JSON fixe la structure ; definePlugin ajoute les règles qu'un schéma ne peut pas exprimer. Le classification d'une compétence ne peut pas dépasser le plafond de confiance. Seuls les plugins core et verified peuvent déclarer des compétences tool_using et llm_only. Chaque chemin déclaré doit être relatif et de même origine, sans schéma, sans // et sans barre oblique inverse, car l'analyseur d'URL convertit \ en / et /\evil.example/x se résout en une autre origine. Chaque règle que la synchronisation du registre applique à une compétence est appliquée ici en premier, avec le code même de la synchronisation, de sorte que validate et la synchronisation désignent une règle enfreinte de la même manière.
Validation et passage depuis la 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
Un échec affiche le chemin précis et, pour une règle de synchronisation, le code en premier. Faites-en un hook de validation (commit hook).
Un manifeste v1 se convertit mécaniquement. migrate ajoute les trois phrases des lois, déplace domain vers domains[] et refuse d'inventer un point d'entrée que vous n'aviez pas. Il valide le résultat avant d'afficher ou d'écrire quoi que ce soit, de sorte qu'une migration ne transfère jamais un échec de l'outil vers votre dépôt.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeRelisez les différences (diff) avant de les valider. Les phrases des lois qu'il ajoute correspondent à la formulation qu'impose le validateur ; pour votre propre installation, définissez deploy sur la phrase présentée plus haut.
Rendu du cloisonnement et provisionnement des rôles
Vous n'écrivez jamais vos attributions de rôles ni le modèle de sécurité au niveau des lignes à la main. nexus-tenancy render les génère à partir de schema et db du manifeste :
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlLe fichier généré crée cinq rôles pour le schéma, chacun défini par ce qu'il ne doit pas détenir : un migrateur qui peut uniquement endosser le rôle de propriétaire, un propriétaire qui ne peut pas se connecter, un rôle applicatif pour le chemin de requête, un rôle de rapport qui ne voit que des agrégats, et un rôle de grand livre qui peut uniquement ajouter des entrées. Aucun rôle ne détient BYPASSRLS. Le seul moyen d'associer un locataire est une fonction unique de base de données, et set_config est révoqué de tous les rôles à l'exception du propriétaire.
Un fichier de cloisonnement des locataires déjà appliqué n'est jamais modifié. Tout changement fait l'objet d'une révision dotée de son propre fichier numéroté 0, et le siège de lecture pour les autorisations inter-organisations est introduit de cette manière, en tant que révision 2. --graph génère les deux tables du graphe typé que déclare votre ontology sous la forme de votre prochaine migration numérotée.
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.sqlLe fichier de cloisonnement des locataires crée les rôles mêmes sous lesquels l'exécuteur se connecte ; il est donc appliqué par le propriétaire de la base de données avec 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> est une chaîne de connexion pour le propriétaire de la base de données, et <dir> est un répertoire privé. Le provisionnement applique dans l'ordre le fichier de base de cloisonnement des locataires ainsi que chaque révision, écrit migrator.url et app.url (ainsi que seat.url dès que la révision 2 existe) dans <dir> avec le mode 0600, et n'affiche aucun secret. Il définit la limite de connexions de chaque rôle à partir de db.maxConnections × db.pods à chaque exécution. Une réexécution conserve les mots de passe existants, sauf demande contraire de votre part : --passwords <dir> les définit à partir de fichiers et --rotate <roles> en attribue de nouveaux aux rôles nommés. Transformez ces fichiers en secrets pour votre déploiement.
Par la suite, l'application des migrations se connecte à l'aide de la chaîne de connexion du migrateur générée lors du provisionnement :
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonElle exécute les fichiers à partir de 001 en tant que migrateur, chaque fichier sous SET ROLE <schema>_owner, à raison d'une transaction par fichier. Elle tient un grand livre, <schema>.schema_migrations, contenant la somme de contrôle de chaque fichier ; un fichier déjà appliqué dont les octets ont changé est refusé nommément (CHECKSUM_DRIFT), et n'est jamais réexécuté ni ignoré. Chaque fichier en attente est analysé avec la véritable grammaire Postgres avant l'exécution du premier d'entre eux, de sorte qu'un refus laisse la base de données intacte. Le seul en-tête qu'un fichier peut comporter est -- nexus-migration: transaction=file|per-statement, avec des délais d'expiration facultatifs pour les verrous et les instructions ; per-statement est destiné à CREATE INDEX CONCURRENTLY.
Les portes de contrôle
nexus-gates exécute vingt-deux portes. Chacune encode une classe de défaut afin qu'il ne puisse pas être livré deux fois, et chacune dispose d'un autotest prouvant qu'elle échoue sur un jeu d'essai conçu pour la déclencher. Exécutez-les avant de pousser vos modifications :
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Porte | Ce qu'elle détecte |
|---|---|
scope-adherence |
Une route /api dépourvue de la garde de périmètre ; un chemin anonyme qui ne correspond pas exactement à un chemin déclaré ; une route d'appareil sans la garde d'appareil, ou accompagnée de la garde d'une personne |
one-fence |
Un prédicat de locataire défini ailleurs qu'à l'unique endroit prévu, y compris une barrière de siège ou d'autorisation écrite à la main |
sql-fence |
Une instruction lisant ou mettant à jour une table soumise au périmètre sans la barrière, dans toute cible FROM, JOIN, USING ou UPDATE |
migrations-are-scoped |
Une table à laquelle il manque un axe, une clé composite commençant par le locataire, une clé étrangère portant le locataire ou la colonne de démonstration |
migrations-commit-what-they-open |
Une migration dont le nombre de BEGIN ne correspond pas à son nombre de COMMIT et de ROLLBACK |
no-direct-compute |
Un appel direct à un fournisseur de modèles, un moteur, une file d'attente ou un hôte de flux de travail ; un second lecteur de l'URL d'acheminement |
no-credentials |
Un identifiant de fournisseur de modèles lisible dans le dépôt ou dans l'environnement |
crud-adherence |
Une route de modification dont la vérification des droits ne nomme aucune entrée du registre |
blocked-backends |
Une route qui n'est ni servie, ni bloquée nommément, ni refusée par la loi, ni détenue ailleurs |
every-test-runs |
Des tests que le motif glob du script de test n'atteint jamais |
tiles-are-invariant |
Une jonction mise en cache invariante par rapport au locataire qui lit une valeur de locataire ou contourne l'authentification |
api-contract |
Une route enregistrée que le manifeste ne déclare pas, ou une route déclarée que le code n'enregistre jamais |
rls-present |
Une table sans sécurité au niveau des lignes forcée ; une fonction SECURITY DEFINER sans search_path épinglé |
no-set-config |
Du code de plugin qui associe lui-même le paramètre de locataire |
db-role-honest |
Un chemin de requête se connectant en tant que propriétaire ou migrateur, ou demandant SUPERUSER ou BYPASSRLS |
platform-clients |
Un client du SDK importé mais non répertorié dans backend.platformClients, ou répertorié mais jamais importé |
rights-register |
Une route de périmètre sans droit déclaré ; une vérification des droits effectuée en dehors du registre |
refusal-ledger |
Une table de refus déclarée sans grand livre installé, ou un corps de refus envoyé en le contournant |
grants-declared |
Une table faisant l'objet d'une autorisation que le manifeste ne déclare pas ; des privilèges de siège de lecture attribués à la main |
people-declared |
Un bloc people dépourvu de sa route de balayage, de sa garde et de ses tables |
functions-closure |
Un plugin Azure Functions dont les routes servies et les routes déclarées ne concordent pas |
declared-input |
Une liste de paramètres de requête d'un gestionnaire qui ne correspond pas aux query déclarés de la route |
Le répertoire gates/ contient les cinq fichiers d'exemption qu'une porte peut lire (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json et invariant-seams.json), à raison d'un motif par entrée. Un motif vide équivaut à l'absence d'entrée, et une entrée nommant un élément qui n'existe plus fait échouer la porte. Vous pouvez également y déposer vos propres modules de porte, et nexus-gates les prend en compte aux côtés des portes intégrées.
Le pipeline du modèle
Le modèle ne livre aucun flux de travail écrit à la main. Sa configuration de pipeline nomme le Dockerfile, l'unique argument de construction (le jeton du registre), l'exécution à blanc des migrations et la sonde de démarrage, ainsi que la porte qu'exécute la file de fusion. L'ordre retenu correspond à celui dans lequel vous souhaiteriez voir survenir un échec.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, qui correspond àcreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, qui correspond ànexus-gates --self-testnode scripts/ci/required-env
Deux contrôles supplémentaires s'exécutent autour de l'image. La simulation de migration applique chaque fichier à une base Postgres éphémère avant que l'image ne puisse être publiée, avec le même exécuteur que celui utilisé en production : nexus-migrate provision une fois en tant que superutilisateur, puis chaque fichier numéroté en tant que migrateur. La sonde de démarrage lance l'image construite avec son propre point d'entrée et chaque variable que required-env affiche, en pointant vers des substituts qui acceptent les connexions sans jamais répondre. Le serveur attend la base de données, dans sa fenêtre impartie, et cette attente constitue le signal de réussite ; un chargeur de configuration qui refuse de démarrer fait échouer le build à ce stade et non en production.
Ce que cela coûte
Le SDK prend des décisions à votre place, et vous en auriez pris certaines différemment. Le manifeste refuse les clés qu'il ne connaît pas, la table de routage doit correspondre exactement à votre code, la conception des rôles de base de données ne vous appartient pas, et les contrôles font échouer un build s'il manque un droit sur une lecture. Lors de mon premier plugin, j'ai passé une journée à me battre avec api-contract au sujet d'une route que j'avais enregistrée mais oublié de déclarer. Il avait raison : la route n'était pas protégée. Attendez-vous à ce que le premier plugin semble lent à développer, et à ce que le deuxième prenne trois fois moins de temps.

