Versión 1.0.0-alpha.1 más reciente
Capítulo 2.21
El SDK de complementos
Instalación del SDK (kit de desarrollo de software) de complementos, sus herramientas de línea de comandos, un recorrido por la plantilla de servicio completo, el manifiesto v2 campo por campo y los veintidós controles que obligan a un complemento a cumplir las reglas.
Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

Mi segundo complemento me llevó un tercio del tiempo que el primero, y casi todo el ahorro se debió al SDK (kit de desarrollo de software). La primera vez, escribí una comprobación de ámbito, un cargador de configuración y un ejecutor de migraciones, y un revisor me devolvió cada uno de ellos. La segunda vez, ejecuté un único comando de generación de estructura base, eliminé la habilidad de sentimiento de ejemplo y dediqué mis días a los registros de revisión de anomalías que nuestro equipo de dinámica de vuelo realmente necesitaba.
@adverant-nexus/plugin-sdk es un único paquete npm. Contiene el esquema del manifiesto v2 y los validadores que lo leen (definePlugin, defineSkill), los módulos de tiempo de ejecución que su complemento importa para el ámbito, la base de datos, el despacho y el resto, asistentes de pruebas, las puertas de cumplimiento y las herramientas de línea de comandos. Este capítulo abarca su instalación, las herramientas, la plantilla, el manifiesto y las puertas. El Capítulo 2.22, El entorno de ejecución del complemento, aborda los módulos de tiempo de ejecución en su código en ejecución.
Instalación
El paquete proviene del registro de Adverant en https://registry.adverant.ai/npm/, nunca del registro público de npm, y necesita el token de extracción de la página "Pull tokens and install commands" de su cuenta. Apunte el ámbito @adverant-nexus al registro en el archivo .npmrc de su repositorio:
@adverant-nexus:registry=https://registry.adverant.ai/npm/
//registry.adverant.ai/npm/:_authToken=<pull-token>
<pull-token> es el token de la página de su cuenta. En una canalización, páselo desde un secreto y nunca lo confirme en el repositorio; el Dockerfile de la plantilla se niega a compilar sin él y elimina .npmrc de la etapa de compilación una vez que npm ci se ha ejecutado, por lo que el token nunca se incluye en una imagen.
A continuación, fije la versión exactamente:
npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0Confirme package-lock.json en la primera instalación. La compilación de la imagen de la plantilla ejecuta npm ci y se niega a recurrir a npm install: el archivo de bloqueo es el contrato. El requisito mínimo del propio SDK es Node 18; la plantilla apunta a Node 20.
Las herramientas de línea de comandos se incluyen dentro del paquete, por lo que cada comando de esta documentación nombra el paquete y su versión con npx -p. Por sí solo, npx create-nexus-plugin se busca en el registro público, y ese nombre no corresponde a este paquete.
Las herramientas de línea de comandos
| Herramienta | Qué hace |
|---|---|
create-nexus-plugin |
Genera la estructura base de un complemento, valida un manifiesto, migra un manifiesto v1 a v2 y genera la guía del consumidor para su desarrollador de frontend |
nexus-tenancy |
Genera el SQL de tenencia de su esquema a partir del manifiesto: roles, concesiones, la plantilla de seguridad a nivel de fila y las tablas de grafos |
nexus-migrate |
Aplica sus migraciones: aprovisiona los roles una vez y luego ejecuta cada archivo numerado con el rol de migrador |
nexus-gates |
Ejecuta cada puerta de cumplimiento y la autoprueba propia de cada puerta |
create-nexus-plugin no realiza llamadas de red ni carga código remoto. Ejecuta los mismos validadores en proceso que ejecuta la incorporación de la plataforma, por lo que no hay discrepancias entre "se validó en mi máquina" y "la plataforma lo aceptó".
| Verbo | Indicadores | Qué hace | Códigos de salida |
|---|---|---|---|
scaffold <name> |
--tier full-service\|ui-only\|skills-only, --dir <path>, --print |
Escribe un nuevo directorio de complemento; --print imprime solo el manifiesto |
0 escrito · 1 se negó a sobrescribir · 2 uso incorrecto |
validate <file> |
Valida un nexus.manifest.json, o un módulo .ts o .js que exporte uno |
0 válido · 1 inválido o ilegible · 2 uso incorrecto | |
migrate <file> |
--write |
Eleva un manifiesto v1 a v2 y lo imprime, o lo sobrescribe en su lugar | 0 · 1 · 2, como arriba |
guide |
--manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint |
Genera la guía del consumidor a partir del manifiesto y su narrativa; --check compara con la copia confirmada y no escribe nada |
0 · 1 discrepancia o infracción de lint · 2 uso incorrecto |
help |
Imprime el modo de uso | 0 |
Generación de estructuras base y los tres niveles
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin scaffold anomaly-review --tier full-service--tier toma por defecto el valor full-service. El generador de estructura base se niega a escribir en un directorio que ya existe, y el manifiesto que escribe ya supera la validación; nunca emite uno inválido.
Elija el nivel según lo que tenga su complemento.
| Nivel | Tiene | Debe declarar |
|---|---|---|
skills-only |
Habilidades de manifiesto y nada más | skills[], con al menos una entrada |
ui-only |
Una superficie de frontend dentro del shell | frontend |
full-service |
Un backend y un frontend, generalmente con su propio esquema | backend y frontend; y como tiene un backend, runtime.healthCheck |
Si no está seguro, genere la estructura base con full-service y elimine lo que no necesite. Hacerlo al revés implica escribir las partes que la plantilla le habría proporcionado.
Un recorrido por la plantilla de servicio completo
La plantilla es el complemento de referencia, construido según el patrón estricto que asume cada capítulo posterior. Clone su forma, no su lógica de ejemplo.
| Ruta | Qué es |
|---|---|
nexus.manifest.json |
El manifiesto v2: las tres leyes reafirmadas, la tabla de rutas y su registro de derechos |
src/config.ts |
El cargador de configuración. Una especificación, leída una vez, con todos los problemas recopilados antes de que el proceso se niegue a arrancar |
src/scope.ts |
El único archivo que convierte una solicitud en un ámbito, con el verificador estricto de tokens del SDK y dos regímenes: el token portador de una persona y la llamada de servicio de la plataforma |
src/db.ts |
Cada instrucción compone tenantFence() y se ejecuta dentro de withScopedTx |
src/uno.ts |
El único archivo de despacho: una URL, un cliente, una lista blanca cerrada |
src/routes/*.ts |
health (anónimo, ruta exacta), las rutas /api (con ámbito) y la llamada de retorno /internal (protegida por servicio) |
src/skills/sentiment.ts |
Una habilidad host_callback determinista; reemplace el léxico con su propia lógica |
src/server.ts |
La raíz de composición: instala el libro mayor de rechazos una vez, espera a la base de datos (con límite de tiempo) y luego ejecuta las comprobaciones de aislamiento y del libro mayor antes de escuchar |
migrations/000_tenancy.sql |
Generado por nexus-tenancy render al crear la estructura base: roles, esquema, la plantilla de seguridad a nivel de fila |
migrations/001_init.sql |
Dos tablas con una clave compuesta encabezada por el inquilino y una clave foránea compuesta que incluye al inquilino |
migrations/002_refusal_ledger.sql |
La tabla en la que escribe el libro mayor de rechazos |
scripts/ci/required-env |
Imprime los nombres de las variables de entorno requeridas en el arranque como JSON |
scripts/ci/shadow-migrate-*.sh |
El simulacro de migración de la canalización, a través de nexus-migrate |
gates/ |
El directorio de exenciones de las puertas: vacío, que es el estado correcto para un complemento nuevo |
test/ |
Pruebas para el ámbito, las rutas, la base de datos, el despacho y el arranque, con los dobles de ámbito que inyecta cada prueba |
Dockerfile |
Una imagen sin privilegios de root (ID de usuario 10001) con las migraciones en su interior |
Algunos de esos archivos merecen una mirada más detallada.
src/config.ts sigue dos reglas. Recopila todos los problemas antes de lanzar una excepción, por lo que un solo reinicio nombra las cinco variables faltantes en lugar de cinco reinicios que nombren una cada uno. Y asigna un valor por defecto solo cuando un valor incorrecto no puede producir una respuesta errónea silenciosa: PORT puede tomar por defecto el valor 8080, porque un puerto incorrecto hace fallar la vinculación de forma visible, mientras que DATABASE_URL y UNO_DISPATCH_URL son obligatorios y deben ser direcciones internas del clúster. Una dirección pública se rechaza en el arranque.
node scripts/ci/required-env["DATABASE_URL","PLATFORM_JWT_SECRET","PLATFORM_SERVICE_KEY","UNO_DISPATCH_URL"]
La propia prueba de la plantilla ejecuta ese archivo y compara su salida con los nombres que la especificación de configuración marca como obligatorios, por lo que añadir una variable obligatoria sin actualizar la lista hace fallar npm test.
src/server.ts no escucha hasta que la base de datos responde, y limita la espera a 120 segundos, registrando cada intento fallido con su causa. Luego demuestra, en orden, que el rol de aplicación no puede revincular al inquilino y que cada tabla está forzada bajo seguridad a nivel de fila, que el grupo de conexiones de cada pod se ajusta al límite de conexiones del rol, y que la tabla del libro mayor de rechazos puede aceptar una fila. Un rechazo de cualquiera de los tres se imprime completo y el proceso termina con el código 2.
El manifiesto v2, campo por campo
El manifiesto es el contrato legible por máquina del complemento con la plataforma. Se valida cuando lo redacta, cuando la plataforma lo incorpora y de forma continua a partir de entonces. El esquema es additionalProperties: false en todos los niveles: si su complemento tiene una sección, hay una propiedad para ella, y una clave no declarada se rechaza. La solución es siempre usar la propiedad opcional correcta.
El núcleo obligatorio
| Campo | Regla |
|---|---|
manifestVersion |
Exactamente "2". Un documento v1 se migra, nunca se revalida en su lugar |
name |
^[a-z0-9]+([-.][a-z0-9]+)*$, como máximo 64 caracteres. El id del complemento utilizado en el registro, los espacios de nombres de despacho y las filas con ámbito de inquilino. Un complemento que declara habilidades también necesita un nombre sin punto y sin dígito inicial |
displayName |
De 1 a 120 caracteres |
version |
Versión semántica; su propio tren de lanzamientos |
description, author, license |
Al menos un carácter cada uno |
tier |
skills-only, ui-only o full-service |
trust |
core, verified, community o untrusted |
runtime |
Obligatorio: executionMode, isolationLevel (de 1 a 4), entrypoint. Opcional: nodeVersion, healthCheck, readinessCheck, livenessCheck, cada uno una ruta que comienza con /. El modo se deriva del nivel: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker |
architecture |
compute, ai y deploy, las tres leyes de la plataforma reafirmadas. El validador fija la redacción exacta |
Para un complemento que construya para su propia instalación, las tres frases se leen de la siguiente manera. La frase ai abarca la inteligencia artificial (IA) y es el lugar para indicar que el complemento no posee credenciales de modelos.
"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 tabla de rutas: api y rights
api necesita version y basePath, y opcionalmente websocket (path, auth) y endpoints[]. La tabla de rutas es la idea más sólida del esquema: una puerta compara sus diferencias frente a las rutas que su código realmente registra, en ambas direcciones, por lo que el manifiesto es un contrato verificable y no simple documentación.
Cada punto de conexión necesita method (GET, POST, PUT, PATCH o DELETE) y path. El resto:
| Campo | Qué indica |
|---|---|
auth |
Una de cinco clases: scope (la ruta de una persona, detrás de la guarda de ámbito), service-key y internal (de servidor a servidor, nunca accesibles desde un navegador), public (siempre únicamente una ruta exacta con allowAnonymous) y device (una máquina con una credencial propia, detrás de la guarda de dispositivo) |
right |
Obligatorio en cada ruta que sirve la guarda de ámbito, y rechazado en cualquier otra: el nombre de un derecho en el registro rights |
needsUnit |
La ruta rechaza la solicitud cuando no se puede resolver la unidad del llamante |
allowAnonymous |
Solo lista blanca de coincidencia exacta. Una regla de prefijo es la forma en que /health-of-tenant-42 termina siendo público |
group, serves, screens |
Bajo un bloque release: el grupo de capacidades al que sirve la ruta, qué responde cuando la función con licencia de ese grupo está bloqueada (data, teaser, sighting o ask) y las pantallas a las que sirve |
query |
required (cada nombre con un valor de ejemplo) y allowed: los parámetros de consulta que lee la ruta |
body |
example: el cuerpo de ejemplo de una ruta de escritura, uno que su propio validador acepta. Nunca en un GET |
rights es el registro que nombran esas rutas. Cada derecho tiene roles (el límite máximo) y opcionalmente summary, never (roles que nunca pueden ejercerlo, independientemente de lo que posean), barred (las propias palabras del producto para rechazar un rol never), seat (también se necesita una plaza activa), self (toda persona verificada lo posee, para derechos sobre su propia sesión), grants (los titulares otorgan plazas; como máximo un derecho lo indica), licence (una función con licencia que debe incluir la licencia de la organización), installation (poseído solo por los propios administradores de la instalación) y platform (poseído solo por los administradores de la plataforma de Adverant; no nombra roles). Los nombres de derechos tienen al menos un punto: 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 rechaza una ruta de ámbito sin derecho (ENDPOINT_RIGHT_MISSING), un derecho del que carece el registro (ENDPOINT_RIGHT_NOT_REGISTERED) y un derecho en una ruta que ninguna guarda sirve (ENDPOINT_RIGHT_UNGUARDED). También rechaza un registro que se contradice a sí mismo, y dos formas de escribir una misma ruta (:id y :recordId) como DUPLICATE_ENDPOINT.
Sus datos: databases, schema y db
schema es el único esquema de Postgres que posee el complemento. public, plugins, auth y nexus están prohibidos, y si databases[] también nombra un esquema de Postgres, ambos deben coincidir.
databases[] declara cada almacén por motor: postgresql (schema, tables, migrations y granted, las tablas que otra organización puede leer bajo una concesión registrada), neo4j (schemas), qdrant (collections) o redis (purpose).
db contiene los límites de sesión para cada conexión que abre el complemento, declarados aquí en lugar de en el código para que tanto un revisor como el despliegue puedan leerlos:
| Campo | Qué limita |
|---|---|
maxConnections |
El grupo de conexiones por réplica |
pods |
El máximo de pods que mantienen un grupo de conexiones a la vez, las réplicas más el incremento de una actualización continua. El límite de conexiones de cada rol se calcula como maxConnections × pods; si lo omite, definePlugin advierte DB_PODS_UNDECLARED |
statementTimeoutMs |
Una instrucción |
idleInTransactionTimeoutMs |
Una transacción abierta que no está ejecutando nada |
workMemKB |
Un nodo de ordenación o hash, por nodo, no por consulta |
piiMask[] |
Entradas de table.column que contienen datos personales, enmascaradas en la consola SQL gobernada y en los registros |
Habilidades y herramientas: skills, mcpTools, entitlements
skills[] contiene las habilidades de manifiesto; el capítulo 2.20, Habilidades, abarca sus campos y niveles. mcpTools[] contiene las herramientas MCP (Model Context Protocol) que publica el complemento, cada una con un name, un description y un inputSchema sin oneOf, allOf ni anyOf de nivel superior.
entitlements requiere featureIdPattern y acepta alwaysOn[], source y store. El patrón nombra el espacio de nombres en el que viven sus identificadores de funciones, convencionalmente el name del complemento más un segmento que su código completa por superficie. alwaysOn[] es la lista corta y exacta que debe responder incluso cuando no se puede obtener un veredicto de derechos: salud, disponibilidad, inicio de sesión y la configuración que un administrador necesita para reparar el derecho.
Control de cambios: changePolicy
"changePolicy": {
"enabled": true,
"classes": ["website", "bff", "migration"],
"approvals": { "website": 1, "bff": 1, "migration": 2 }
}Las aprobaciones se cuentan en personas distintas, y la persona que propuso el cambio nunca es una de ellas; sin ambas condiciones, "dos aprobaciones" se convierte en una persona haciendo clic dos veces. enabled: true requiere classes, y cada clase nombrada necesita su propio recuento. Una clase que omita queda sin gobierno, lo cual es una elección legítima que el esquema le obliga a dejar por escrito.
Quién es usted: domains, branding, routing
domains[] (cada uno con primary y aliases[]; domain es la forma de dominio único) enumera dónde responde el complemento. branding requiere appName y acepta tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId y gaId. Todo en branding es público: la página de inicio de sesión lo lee antes de que nadie tenga una credencial, por lo que nunca contiene un secreto ni una dirección interna. routing (type, gateway, virtualService) es para complementos que describen su propio enrutamiento.
Dimensionamiento y el resto
resources requiere cpuMillicores (de 10 a 64,000) y memoryMB (de 16 a 262,144), y acepta diskGB, timeoutMs, port y wsPort. backend contiene port, healthPath, apiPrefix, framework y platformClients[], los clientes del SDK que su backend importa por nombre. La lista es cerrada y una puerta la comprueba frente a sus importaciones. El esquema permite catorce nombres: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin y uno, más uno para el cliente que responde a los rechazos de derechos de plan, que mantiene un nombre interno. El cliente de derechos de funciones, runtime/entitlements, no es uno de ellos y nunca va en la lista, porque su bloque entitlements ya lo declara, y un backend que lo importe sin un bloque entitlements falla en la misma puerta. frontend contiene basePath, mountPath y framework. nexus contiene minVersion, maxVersion, capabilities[] y permissions[].
Los bloques restantes están ahí cada uno para una tarea:
| Bloque | Para |
|---|---|
settings |
Su configuración en el marco compartido: groups y keys, establecidos en los niveles que cada uno nombra |
people |
sweep (service, port): los miembros de la organización, sincronizados desde el servicio de identidad, con las plazas desactivadas cuando alguien se va |
ontology |
entityTypes y relationshipTypes: el grafo tipado mantenido en su propio esquema |
release |
groups y frame: los grupos de capacidades en los que se organizan por etapas sus rutas, lanzados primero como versión canaria |
cells[] |
Un complemento que consta de varios desplegables: name, kind, entrypoint, port, wsPort cada uno |
pricing |
model, currency, tiers[] para su ficha en el catálogo |
marketplace |
category, icon, screenshots, documentation, featured |
compliance |
instruments[], dataResidency, sovereignty |
developer, repository, keywords |
Quién lo publica y dónde reside su código |
metrics, atlas |
Los dos objetos deliberadamente abiertos, para sus propios nombres de métricas y la generación de documentación de arquitectura |
Lo que el esquema no puede expresar
El esquema JSON define la forma; definePlugin añade las reglas que un esquema no puede expresar. El classification de una habilidad no puede superar el límite máximo de confianza. Solo los complementos core y verified pueden declarar habilidades tool_using y llm_only. Cada ruta declarada debe ser relativa y del mismo origen, sin esquema, sin // y sin barra invertida, porque el analizador de URL convierte \ en / y /\evil.example/x se resuelve como de origen cruzado. Cada regla que la sincronización del registro aplica a una habilidad se aplica aquí primero, con el propio código de la sincronización, por lo que validate y la sincronización nombran una regla infringida de la misma manera.
Validación y migración desde 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 fallo imprime la ruta precisa y, para una regla de sincronización, el código primero. Conviértalo en un hook de confirmación.
Un manifiesto v1 se eleva mecánicamente. migrate añade las tres frases de ley, mueve domain a domains[] y se niega a inventar un punto de entrada que usted no tenía. Valida el resultado antes de imprimir o escribir nada, por lo que una migración nunca traslada un fallo de la herramienta a su repositorio.
npx -p @adverant-nexus/plugin-sdk@2.50.0 create-nexus-plugin migrate nexus.manifest.json --writeLea las diferencias antes de confirmarlas. Las frases de ley que añade son la redacción exacta que fija el validador; para su propia instalación, establezca deploy con la frase mostrada anteriormente.
Representación de la tenencia y aprovisionamiento de los roles
Usted nunca escribe a mano sus concesiones de roles ni la plantilla de seguridad a nivel de fila. nexus-tenancy render las escribe a partir de schema y db del manifiesto:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --out migrations/000_tenancy.sqlEl archivo generado crea cinco roles para el esquema, cada uno con lo que no debe poseer: un migrador que solo puede convertirse en el propietario, un propietario que no puede iniciar sesión, un rol de aplicación para la ruta de solicitud, un rol de informes que solo ve agregados y un rol de libro mayor que solo puede añadir registros. Ningún rol posee BYPASSRLS. La única forma de vincular un inquilino es mediante una función de base de datos, y set_config se revoca de todos los roles excepto del propietario.
Un archivo de tenencia aplicado nunca se edita. Un cambio es una revisión con su propio archivo número 0, y la plaza de lectura para concesiones entre organizaciones llega de esa manera, como la revisión 2. --graph genera las dos tablas del grafo tipado que su ontology declara como su siguiente migración numerada.
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.sqlEl archivo de tenencia crea los mismos roles con los que se conecta el ejecutor, por lo que lo aplica el propietario de la base de datos con 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> es una cadena de conexión para el propietario de la base de datos, y <dir> es un directorio privado. El aprovisionamiento aplica el archivo de tenencia base y cada revisión en orden, escribe migrator.url y app.url (y seat.url una vez que existe la revisión 2) en <dir> con el modo 0600, y no imprime nada secreto. Establece el límite de conexiones de cada rol a partir de db.maxConnections × db.pods en cada ejecución. Una nueva ejecución mantiene las contraseñas existentes a menos que lo solicite: --passwords <dir> las establece a partir de archivos y --rotate <roles> asigna contraseñas nuevas a los roles nombrados. Convierta los archivos en los secretos de su despliegue.
Después de eso, la aplicación se conecta con la cadena de conexión del migrador que escribió el aprovisionamiento:
DATABASE_URL="$(cat <dir>/migrator.url)" npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-migrate apply --manifest nexus.manifest.jsonEjecuta los archivos del 001 en adelante como el migrador, cada archivo bajo SET ROLE <schema>_owner, una transacción por archivo. Mantiene un libro mayor, <schema>.schema_migrations, con la suma de comprobación de cada archivo; un archivo aplicado cuyos bytes hayan cambiado es rechazado por su nombre (CHECKSUM_DRIFT), nunca se vuelve a ejecutar y nunca se omite. Cada archivo pendiente se analiza con la gramática real de Postgres antes de que se ejecute el primero, por lo que un rechazo deja la base de datos intacta. El único encabezado que puede llevar un archivo es -- nexus-migration: transaction=file|per-statement, con tiempos de espera opcionales de bloqueo y de instrucción; per-statement es para CREATE INDEX CONCURRENTLY.
Los controles
nexus-gates ejecuta veintidós puertas. Cada una codifica una clase de defecto para que no pueda distribuirse dos veces, y cada una tiene una autoprueba que demuestra que falla ante un escenario de prueba construido para activarla. Ejecútelas antes de subir sus cambios:
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test| Puerta | Qué detecta |
|---|---|
scope-adherence |
Una ruta /api sin la guarda de ámbito; una ruta anónima que no sea una ruta exacta declarada; una ruta de dispositivo sin la guarda de dispositivo, o con la guarda de una persona junto a ella |
one-fence |
Un predicado de inquilino definido en cualquier lugar que no sea un único sitio, incluida una barrera de plaza o de concesión creada manualmente |
sql-fence |
Una instrucción que lee o actualiza una tabla con ámbito sin la barrera, en cualquier destino FROM, JOIN, USING o UPDATE |
migrations-are-scoped |
Una tabla a la que le falta un eje, una clave compuesta encabezada por el inquilino, una clave foránea que incluye al inquilino o la columna de demostración |
migrations-commit-what-they-open |
Una migración cuyo recuento de BEGIN no coincide con su recuento de COMMIT y ROLLBACK |
no-direct-compute |
Una llamada directa a un proveedor de modelos, motor, cola o host de flujo de trabajo; un segundo lector de la URL de despacho |
no-credentials |
Una credencial de proveedor de modelos legible en el repositorio o en el entorno |
crud-adherence |
Una ruta mutadora cuya comprobación de derechos no nombra nada en el registro |
blocked-backends |
Una ruta que ni se sirve, ni se bloquea por nombre, ni se rechaza por ley, ni pertenece a otro lugar |
every-test-runs |
Pruebas a las que el patrón glob del script de pruebas nunca llega |
tiles-are-invariant |
Una unión en caché invariante respecto al inquilino que lee un valor de inquilino u omite la autenticación |
api-contract |
Una ruta registrada que el manifiesto no declara, o una declarada que el código nunca registra |
rls-present |
Una tabla sin seguridad a nivel de fila forzada; una función SECURITY DEFINER sin un search_path fijado |
no-set-config |
Código del complemento que vincula el parámetro de inquilino por sí mismo |
db-role-honest |
Una ruta de solicitud que se conecta como propietario o migrador, o que solicita SUPERUSER o BYPASSRLS |
platform-clients |
Un cliente del SDK importado pero no incluido en backend.platformClients, o incluido pero nunca importado |
rights-register |
Una ruta de ámbito sin un derecho declarado; una comprobación de derechos al margen del registro |
refusal-ledger |
Una tabla de rechazos declarada sin libro mayor instalado, o un cuerpo de rechazo enviado eludiéndolo |
grants-declared |
Una tabla concedida que el manifiesto no declara; privilegios de plaza de lectura otorgados a mano |
people-declared |
Un bloque people sin su ruta de barrido, guarda y tablas |
functions-closure |
Un complemento de Azure Functions cuyas rutas servidas y rutas declaradas no coinciden |
declared-input |
Una lista de parámetros de consulta de un manejador que no coincide con los query declarados de la ruta |
El directorio gates/ contiene los cinco archivos de exención que una puerta puede leer (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json y invariant-seams.json), un motivo por entrada. Un motivo en blanco cuenta como ninguna entrada, y una entrada que nombra algo que ya no existe hace fallar la puerta. También puede colocar allí sus propios módulos de puerta, y nexus-gates los recogerá junto con los integrados.
La canalización de la plantilla
La plantilla no incluye ningún flujo de trabajo escrito a mano. Su configuración de canalización nombra el Dockerfile, el único argumento de compilación (el token del registro), el simulacro de migración y la sonda de arranque, y la puerta que ejecuta la cola de fusión. El orden es el orden en el que usted querría que fallara.
npm cinpm run typechecknpm run buildnpm testnpm run validate:manifest, que escreate-nexus-plugin validate nexus.manifest.jsonnpm run gates, que esnexus-gates --self-testnode scripts/ci/required-env
Dos comprobaciones más se ejecutan en torno a la imagen. El simulacro de migración aplica cada archivo a un Postgres desechable antes de que se pueda publicar la imagen, con el mismo ejecutor que utiliza producción: nexus-migrate provision una vez como superusuario y luego cada archivo numerado como migrador. La sonda de arranque inicia la imagen compilada con su propio punto de entrada y cada variable que required-env imprime, apuntando a sustitutos que aceptan conexiones y nunca responden. El servidor espera a la base de datos dentro de su ventana acotada, y esa espera es la señal de aprobación; un cargador de configuración que se niega a arrancar hace que la compilación falle allí y no en producción.
Cuánto cuesta
El SDK toma decisiones por usted, y algunas de ellas las habría tomado de otra manera. El manifiesto rechaza las claves que desconoce, la tabla de rutas tiene que coincidir exactamente con su código, los roles de la base de datos no le corresponde diseñarlos a usted y los controles hacen que falle una compilación si falta un permiso en una lectura. En mi primer complemento pasé un día discutiendo con api-contract sobre una ruta que había registrado y olvidado declarar. Tenía razón; la ruta estaba desprotegida. Espere que el primer complemento resulte lento, y espere que el segundo le lleve un tercio del tiempo.

