Iniciar sesiónReservar sesión

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

22 minutos de lectura

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

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

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

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

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

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

Compatibilidad
Compatibilidad
La compatibilidad muestra qué versión del SDK funciona con qué versión de la plataforma, a partir de las ejecuciones nocturnas de la guía de inicio rápido. Un par no probado lo indica así, y un par que falla nombra el cambio que lo rompió.

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.

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

Desarrollo en Community
Desarrollo en Community
En Community, un desarrollador obtiene las mismas rutas recomendadas, un espacio de desarrollo y ramas de datos en un servidor, con el código en su propio alojamiento Git. El entorno de preproducción, las unidades piloto y las copias enmascaradas de datos reales se incluyen con Enterprise.

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.