Iniciar sessãoAgendar apresentação

Capítulo 2.21

O Plugin SDK

Instalar o Plugin SDK (kit de desenvolvimento de software), as suas ferramentas de linha de comandos, uma visita guiada ao modelo de serviço completo, o manifesto v2 campo a campo e as vinte e duas barreiras de controlo que obrigam um plugin a cumprir as regras.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

22 minutos de leitura

O meu segundo plugin demorou um terço do tempo do primeiro, e quase toda a poupança deveu-se ao SDK (kit de desenvolvimento de software). Na primeira vez, escrevi uma verificação de âmbito, um carregador de configuração e um executor de migrações, e um revisor devolveu cada um deles. Na segunda vez, executei um comando de criação de estrutura (scaffold), eliminei a competência de sentimento de exemplo e dediquei os meus dias aos registos de revisão de anomalias de que a nossa equipa de dinâmica de voo realmente precisava.

@adverant-nexus/plugin-sdk é um pacote npm. Contém o esquema do manifesto v2 e os validadores que o leem (definePlugin, defineSkill), os módulos de tempo de execução que o seu plugin importa para âmbito, base de dados, envio (dispatch) e o restante, auxiliares de teste, as barreiras de conformidade (adherence gates) e as ferramentas de linha de comandos. Este capítulo aborda a respetiva instalação, as ferramentas, o modelo, o manifesto e as barreiras. O Capítulo 2.22, O tempo de execução do plugin, aborda os módulos de tempo de execução no seu código em execução.

Instalação

O pacote provém do registo da Adverant em https://registry.adverant.ai/npm/, nunca do registo público do npm, e necessita do token de extração (pull token) disponível na página "Pull tokens and install commands" da sua conta. Aponte o âmbito @adverant-nexus para o registo no ficheiro .npmrc do seu repositório:

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

<pull-token> é o token da página da sua conta. Num pipeline, transmita-o a partir de um segredo e nunca o submeta (commit); o Dockerfile do modelo recusa compilar sem ele e elimina o .npmrc da etapa de compilação assim que o npm ci é executado, para que o token nunca seja enviado numa imagem.

Em seguida, fixe a versão exata:

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

Submeta o package-lock.json na primeira instalação. A compilação da imagem do modelo executa npm ci e recusa recorrer a npm install: o ficheiro de bloqueio (lockfile) é o contrato. O requisito mínimo do próprio SDK é o Node 18; o modelo destina-se ao Node 20.

As ferramentas de linha de comandos são fornecidas dentro do pacote, pelo que cada comando nesta documentação indica o nome do pacote e a respetiva versão com npx -p. Por si só, npx create-nexus-plugin é procurado no registo público, e esse nome não corresponde a este pacote.

As ferramentas de linha de comandos

Ferramenta O que faz
create-nexus-plugin Cria a estrutura de um plugin, valida um manifesto, migra um manifesto v1 para v2 e gera o guia do consumidor para o seu programador de frontend
nexus-tenancy Gera o SQL de multi-inquilino (tenancy) do seu esquema a partir do manifesto: funções (roles), concessões (grants), o modelo de segurança ao nível da linha (row-level security) e as tabelas de grafos
nexus-migrate Aplica as suas migrações: aprovisiona as funções uma vez e, em seguida, executa cada ficheiro numerado com a função de migrador
nexus-gates Executa todas as barreiras de conformidade e o autoteste de cada barreira

create-nexus-plugin não efetua chamadas de rede nem carrega código remoto. Executa os mesmos validadores no processo que a integração (onboarding) da plataforma executa, pelo que não há divergência entre "validou na minha máquina" e "a plataforma aceitou-o".

Verbo Parâmetros (Flags) O que faz Códigos de saída
scaffold <name> --tier full-service\|ui-only\|skills-only, --dir <path>, --print Cria um novo diretório de plugin; --print imprime apenas o manifesto 0 escrito · 1 recusou substituir · 2 utilização incorreta
validate <file> Valida um nexus.manifest.json, ou um módulo .ts ou .js que exporte um 0 válido · 1 inválido ou ilegível · 2 utilização incorreta
migrate <file> --write Atualiza um manifesto v1 para v2 e imprime-o, ou grava-o no mesmo local 0 · 1 · 2, conforme indicado acima
guide --manifest <file>, --narrative <dir>, --out <guide.md>, --check, --lint Gera o guia do consumidor a partir do manifesto e da sua narrativa; --check compara com a cópia submetida e não grava nada 0 · 1 divergência ou infração de lint · 2 utilização incorreta
help Imprime as instruções de utilização 0

Estruturação inicial e os três níveis

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

--tier assume por predefinição full-service. O gerador de estrutura recusa gravar num diretório já existente e o manifesto que grava já passa na validação; nunca emite um manifesto inválido.

Escolha o nível consoante o que o seu plugin contém.

Nível Contém Deve declarar
skills-only Competências de manifesto e nada mais skills[], com pelo menos uma entrada
ui-only Uma superfície de frontend dentro da shell frontend
full-service Um backend e um frontend, geralmente com o seu próprio esquema backend e frontend; e, por ter um backend, runtime.healthCheck

Se não tiver a certeza, crie a estrutura com full-service e elimine o que não precisar. Seguir o caminho inverso implica escrever as partes que o modelo lhe teria fornecido.

Uma visita guiada ao modelo de serviço completo

O modelo é o plugin de referência, construído segundo o padrão estrito que todos os capítulos seguintes pressupõem. Clone a sua estrutura, não a sua lógica de exemplo.

Caminho O que é
nexus.manifest.json O manifesto v2: as três leis reafirmadas, a tabela de rotas e o respetivo registo de direitos
src/config.ts O carregador de configuração. Uma especificação, lida uma única vez, com todos os problemas recolhidos antes de o processo se recusar a arrancar
src/scope.ts O único ficheiro que transforma um pedido num âmbito, com o verificador estrito de tokens do SDK e dois regimes: o token portador (bearer token) de uma pessoa e a chamada de serviço da plataforma
src/db.ts Cada instrução compõe tenantFence() e é executada dentro de withScopedTx
src/uno.ts O único ficheiro de envio (dispatch): um URL, um cliente, uma lista de permissões fechada
src/routes/*.ts health (anónimo, caminho exato), as rotas /api (com âmbito) e o callback /internal (protegido por serviço)
src/skills/sentiment.ts Uma competência host_callback determinística; substitua o léxico pela sua própria lógica
src/server.ts A raiz de composição: instala o registo de recusas (refusal ledger) uma vez, aguarda pela base de dados (com limite de tempo) e, em seguida, executa as verificações de isolamento e de registo antes de ficar à escuta
migrations/000_tenancy.sql Gerado por nexus-tenancy render no momento da criação da estrutura: funções, esquema, o modelo de segurança ao nível da linha
migrations/001_init.sql Duas tabelas com uma chave composta iniciada pelo inquilino (tenant) e uma chave estrangeira composta que inclui o inquilino
migrations/002_refusal_ledger.sql A tabela onde o registo de recusas grava
scripts/ci/required-env Imprime os nomes das variáveis de ambiente necessárias para o arranque em formato JSON
scripts/ci/shadow-migrate-*.sh A execução de teste (dry run) de migração do pipeline, através de nexus-migrate
gates/ O diretório de isenções das barreiras: vazio, que é o estado correto para um novo plugin
test/ Testes para âmbito, rotas, base de dados, envio e arranque, com os substitutos de âmbito (scope doubles) que cada teste injeta
Dockerfile Uma imagem sem privilégios de root (ID de utilizador 10001) com as migrações incluídas

Alguns desses ficheiros merecem uma análise mais detalhada.

src/config.ts segue duas regras. Recolhe todos os problemas antes de gerar uma exceção, pelo que um único reinício indica todas as cinco variáveis em falta, em vez de cinco reinícios indicarem uma de cada vez. E apenas atribui um valor predefinido quando um valor incorreto não pode produzir uma resposta errada silenciosa: PORT pode ter o valor predefinido 8080, porque uma porta errada falha a associação (bind) de forma visível, ao passo que DATABASE_URL e UNO_DISPATCH_URL são obrigatórios e têm de ser endereços internos do cluster. Um endereço público é recusado no arranque.

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

O próprio teste do modelo executa esse ficheiro e compara o seu resultado com os nomes que a especificação de configuração marca como obrigatórios, pelo que adicionar uma variável obrigatória sem atualizar a lista faz falhar npm test.

src/server.ts não fica à escuta até que a base de dados responda, e limita a espera a 120 segundos, registando cada tentativa falhada com a respetiva causa. Em seguida, comprova, por ordem, que a função da aplicação não pode reassociar o inquilino e que cada tabela está sujeita a segurança ao nível da linha, que o conjunto de ligações (pool) de cada pod cabe no limite de ligações da função e que a tabela do registo de recusas pode receber uma linha. Uma recusa de qualquer um dos três é impressa na íntegra e o processo termina com o código 2.

O manifesto v2, campo a campo

O manifesto é o contrato legível por máquina do plugin com a plataforma. É validado quando o cria, quando a plataforma o integra e continuamente após esse momento. O esquema é additionalProperties: false em todos os níveis: se o seu plugin tiver uma secção, existe uma propriedade para ela, e uma chave não declarada é recusada. A solução passa sempre por utilizar a propriedade opcional correta.

O núcleo obrigatório

Campo Regra
manifestVersion Exatamente "2". Um documento v1 é migrado, nunca revalidado no mesmo local
name ^[a-z0-9]+([-.][a-z0-9]+)*$, no máximo 64 caracteres. O ID do plugin utilizado no registo, na atribuição de espaços de nomes de envio (dispatch namespacing) e nas linhas com âmbito de inquilino. Um plugin que declare competências também necessita de um nome sem pontos e sem um dígito inicial
displayName 1 a 120 caracteres
version Versão semântica; o seu próprio ciclo de lançamentos
description, author, license Pelo menos um carácter cada
tier skills-only, ui-only ou full-service
trust core, verified, community ou untrusted
runtime Obrigatório: executionMode, isolationLevel (1 a 4), entrypoint. Opcional: nodeVersion, healthCheck, readinessCheck, livenessCheck, sendo cada um deles um caminho que começa por /. O modo é derivado do nível: 1 external_https, 2 mcp_container, 3 hardened_docker, 4 firecracker
architecture compute, ai e deploy, as três leis da plataforma reafirmadas. O validador exige a redação exata

Para um plugin que construa para a sua própria instalação, as três frases têm a seguinte redação. A frase ai abrange a inteligência artificial (IA) e é o local para indicar que o plugin não detém credenciais 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."
}

A tabela de rotas: api e rights

api necessita de version e basePath, e opcionalmente de websocket (path, auth) e endpoints[]. A tabela de rotas é o conceito mais forte do esquema: uma barreira compara-a com as rotas que o seu código realmente regista, em ambas as direções, pelo que o manifesto é um contrato verificável e não mera documentação.

Cada endpoint necessita de method (GET, POST, PUT, PATCH ou DELETE) e path. O restante:

Campo O que indica
auth Uma de cinco classes: scope (a rota de uma pessoa, protegida pelo guarda de âmbito), service-key e internal (servidor para servidor, nunca acessível a partir de um navegador), public (apenas um caminho exato com allowAnonymous) e device (uma máquina com uma credencial própria, protegida pelo guarda de dispositivo)
right Obrigatório em todas as rotas servidas pelo guarda de âmbito, e recusado em qualquer outra: o nome de um direito no registo rights
needsUnit A rota recusa quando a unidade do autor da chamada não pode ser resolvida
allowAnonymous Apenas lista de permissões de correspondência exata. Uma regra de prefixo é a forma como /health-of-tenant-42 acaba por ficar público
group, serves, screens Sob um bloco release: o grupo de capacidades que a rota serve, o que responde quando a funcionalidade licenciada desse grupo está bloqueada (data, teaser, sighting ou ask) e os ecrãs que serve
query required (cada nome com um valor de exemplo) e allowed: os parâmetros de consulta (query parameters) que a rota lê
body example: o corpo de exemplo de uma rota de escrita, que o seu próprio validador aceite. Nunca num GET

rights é o registo que essas rotas nomeiam. Cada direito tem roles (o teto) e, opcionalmente, summary, never (funções que nunca o podem exercer, independentemente do que mais detenham), barred (as próprias palavras do produto para recusar uma função never), seat (também é necessário um lugar ativo), self (toda a pessoa verificada o detém, para direitos sobre a sua própria sessão), grants (os titulares concedem lugares; no máximo, um direito o indica), licence (uma funcionalidade licenciada que a licença da organização deve incluir), installation (detido apenas pelos próprios administradores da instalação) e platform (detido apenas pelos administradores da plataforma da Adverant; não nomeia funções). Os nomes de direitos têm pelo menos um ponto: 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 recusa uma rota de âmbito sem direito (ENDPOINT_RIGHT_MISSING), um direito que falte no registo (ENDPOINT_RIGHT_NOT_REGISTERED) e um direito numa rota que nenhuma guarda sirva (ENDPOINT_RIGHT_UNGUARDED). Também recusa um registo que se contradiga a si mesmo e duas grafias de uma mesma rota (:id e :recordId) como DUPLICATE_ENDPOINT.

Os seus dados: databases, schema e db

schema é o único esquema Postgres que o plugin detém. public, plugins, auth e nexus são proibidos e, se databases[] também nomear um esquema Postgres, os dois têm de coincidir.

databases[] declara cada armazenamento por motor: postgresql (schema, tables, migrations e granted, as tabelas que outra organização pode ler ao abrigo de uma concessão registada), neo4j (schemas), qdrant (collections) ou redis (purpose).

db contém os limites de sessão para cada ligação que o plugin abre, declarados aqui em vez de codificados, para que tanto um revisor como a implementação os possam ler:

Campo O que limita
maxConnections O pool por réplica
pods O máximo de pods a deter um pool em simultâneo, réplicas mais o pico de uma atualização contínua. O limite de ligações de cada função é processado como maxConnections × pods; se o omitir, definePlugin avisa DB_PODS_UNDECLARED
statementTimeoutMs Uma instrução
idleInTransactionTimeoutMs Uma transação aberta que não está a executar nada
workMemKB Um nó de ordenação ou de hash, por nó, não por consulta
piiMask[] Entradas table.column que contêm dados pessoais, mascaradas na consola SQL governada e nos registos

Competências e ferramentas: skills, mcpTools, entitlements

skills[] contém as competências do manifesto; o capítulo 2.20, Competências, abrange os seus campos e níveis. mcpTools[] contém as ferramentas MCP (Model Context Protocol) que o plugin publica, sendo cada uma um name, um description e um inputSchema sem oneOf, allOf ou anyOf de nível superior.

entitlements requer featureIdPattern e aceita alwaysOn[], source e store. O padrão nomeia o espaço de nomes onde residem os seus identificadores de funcionalidades, convencionalmente o name do plugin mais um segmento que o seu código preenche por superfície. alwaysOn[] é a lista curta e exata que tem de responder mesmo quando não é possível obter uma decisão de atribuição de direitos: estado de saúde, prontidão, início de sessão e as definições de que um administrador necessita para reparar a atribuição de direitos.

Controlo de alterações: changePolicy

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

As aprovações são contadas em pessoas distintas, e a pessoa que propôs a alteração nunca é uma delas; sem ambas as partes, "duas aprovações" torna-se numa pessoa a clicar duas vezes. enabled: true requer classes, e cada classe nomeada necessita da sua própria contagem. Uma classe que deixe de fora não é governada, o que é uma escolha legítima que o esquema o obriga a registar por escrito.

Quem é: domains, branding, routing

domains[] (cada um primary e aliases[]; domain é a forma de domínio único) lista onde o plugin responde. branding requer appName e aceita tagline, logo, favicon, primaryColor, accentColor, oauthClientRef, passkeyRpId e gaId. Tudo em branding é público: a página de início de sessão lê-o antes de alguém ter uma credencial, pelo que nunca contém um segredo ou um endereço interno. routing (type, gateway, virtualService) destina-se a plugins que descrevem o seu próprio encaminhamento.

Dimensionamento e o restante

resources requer cpuMillicores (10 a 64 000) e memoryMB (16 a 262 144), e aceita diskGB, timeoutMs, port e wsPort. backend contém port, healthPath, apiPrefix, framework e platformClients[], os clientes SDK que o seu backend importa pelo nome. A lista é fechada e uma barreira de controlo verifica-a em relação às suas importações. O esquema permite catorze nomes: access, bindings, documents, files, governance, graph, jobs, keys, memory, platform, runs, signin e uno, mais um para o cliente que responde a recusas de direitos de plano, que mantém um nome interno. O cliente de direitos de funcionalidades, runtime/entitlements, não é um deles e nunca entra na lista, porque o seu bloco entitlements já o declara, e um backend que o importe sem um bloco entitlements falha na mesma barreira de controlo. frontend contém basePath, mountPath e framework. nexus contém minVersion, maxVersion, capabilities[] e permissions[].

Os restantes blocos existem cada um para uma função:

Bloco Para
settings As suas definições na estrutura partilhada: groups e keys, definidas nos níveis que cada uma nomeia
people sweep (service, port): os membros da organização, sincronizados a partir do serviço de identidade, com lugares desativados quando alguém sai
ontology entityTypes e relationshipTypes: o grafo tipado mantido no seu próprio esquema
release groups e frame: os grupos de capacidades em que as suas rotas são preparadas, lançados primeiro como canary
cells[] Um plugin composto por vários elementos implementáveis: name, kind, entrypoint, port, wsPort cada
pricing model, currency, tiers[] para a sua listagem no catálogo
marketplace category, icon, screenshots, documentation, featured
compliance instruments[], dataResidency, sovereignty
developer, repository, keywords Quem o publica e onde reside o seu código
metrics, atlas Os dois objetos deliberadamente abertos, para os seus próprios nomes de métricas e geração de documentação de arquitetura

O que o esquema não pode dizer

O JSON Schema define a forma; definePlugin adiciona as regras que um esquema não consegue expressar. O classification de uma competência não pode exceder o teto de confiança. Apenas plugins core e verified podem declarar competências tool_using e llm_only. Cada caminho declarado tem de ser relativo e da mesma origem, sem esquema, sem // e sem barra invertida, porque o analisador de URL converte \ em / e /\evil.example/x resolve entre origens cruzadas. Cada regra que a sincronização do registo aplica a uma competência é aplicada aqui primeiro, com o próprio código da sincronização, para que validate e a sincronização nomeiem uma regra violada da mesma forma.

Validar e migrar a partir da 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

Uma falha imprime o caminho exato e, para uma regra de sincronização, o código primeiro. Torne-o num hook de commit.

Um manifesto v1 é atualizado mecanicamente. migrate adiciona as três frases de lei, move domain para domains[] e recusa-se a inventar um ponto de entrada que não tinha. Valida o resultado antes de imprimir ou escrever o que quer que seja, para que uma migração nunca mova uma falha da ferramenta para o seu repositório.

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

Leia o diff antes de fazer o commit. As frases de lei que adiciona são a redação que o validador fixa; para a sua própria instalação, defina deploy com a frase mostrada anteriormente.

Renderizar a tenência e aprovisionar os papéis

Nunca escreve as suas concessões de funções nem o modelo de segurança ao nível da linha manualmente. nexus-tenancy render escreve-os a partir de schema e db do manifesto:

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

O ficheiro processado cria cinco funções para o esquema, cada uma com o que não deve deter: um migrador que apenas se pode tornar no proprietário, um proprietário que não pode iniciar sessão, uma função de aplicação para o caminho do pedido, uma função de relatório que vê apenas agregados e uma função de livro-razão que apenas pode anexar. Nenhuma função detém BYPASSRLS. A única forma de vincular um inquilino é uma função da base de dados, e set_config é revogado de todas as funções exceto a do proprietário.

Um ficheiro de inquilinato aplicado nunca é editado. Uma alteração é uma revisão com o seu próprio ficheiro de número 0, e o lugar de leitura para concessões entre organizações chega dessa forma, como revisão 2. --graph processa as duas tabelas do grafo tipado que o seu ontology declara como a sua próxima migração 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

O ficheiro de inquilinato cria as próprias funções com as quais o executor se liga, pelo que é aplicado pelo proprietário da base de dados com 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> é uma cadeia de ligação para o proprietário da base de dados, e <dir> é um diretório privado. O aprovisionamento aplica o ficheiro de inquilinato base e cada revisão por ordem, escreve migrator.url e app.url (e seat.url assim que a revisão 2 existir) em <dir> com o modo 0600, e não imprime nada secreto. Define o limite de ligações de cada função a partir de db.maxConnections × db.pods em cada execução. Uma nova execução mantém as palavras-passe existentes, a menos que o solicite: --passwords <dir> define-as a partir de ficheiros e --rotate <roles> atribui novas palavras-passe às funções nomeadas. Transforme os ficheiros nos segredos da sua implementação.

Depois disso, a aplicação liga-se com a cadeia de ligação do migrador que o aprovisionamento escreveu:

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

Executa os ficheiros de 001 em diante como o migrador, cada ficheiro sob SET ROLE <schema>_owner, uma transação por ficheiro. Mantém um livro-razão, <schema>.schema_migrations, com a soma de verificação de cada ficheiro; um ficheiro aplicado cujos bytes tenham mudado é recusado pelo nome (CHECKSUM_DRIFT), nunca é reexecutado e nunca é ignorado. Cada ficheiro pendente é analisado com a verdadeira gramática do Postgres antes de o primeiro ser executado, pelo que uma recusa deixa a base de dados intocada. O único cabeçalho que um ficheiro pode conter é -- nexus-migration: transaction=file|per-statement, com limites de tempo opcionais de bloqueio e de instrução; per-statement é para CREATE INDEX CONCURRENTLY.

As barreiras de controlo

nexus-gates executa vinte e duas barreiras de controlo. Cada uma codifica uma classe de defeito para que não possa ser expedida duas vezes, e cada uma tem um autoteste que prova que falha num cenário de teste construído para a acionar. Execute-as antes de fazer push:

npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-gates --self-test
Barreira de controlo O que deteta
scope-adherence Uma rota /api sem a guarda de âmbito; um caminho anónimo que não seja exatamente um caminho declarado; uma rota de dispositivo sem a guarda de dispositivo, ou com a guarda de uma pessoa ao lado dela
one-fence Um predicado de inquilino definido em qualquer outro lugar que não num único local, incluindo uma barreira de lugar ou de concessão feita manualmente
sql-fence Uma instrução a ler ou atualizar uma tabela com âmbito sem a barreira, em qualquer destino FROM, JOIN, USING ou UPDATE
migrations-are-scoped Uma tabela sem um eixo, uma chave composta liderada pelo inquilino, uma chave estrangeira com o inquilino ou a coluna de demonstração
migrations-commit-what-they-open Uma migração cuja contagem de BEGIN não coincide com a sua contagem de COMMIT e ROLLBACK
no-direct-compute Uma chamada direta a um fornecedor de modelos, motor, fila ou anfitrião de fluxo de trabalho; um segundo leitor do URL de expedição
no-credentials Uma credencial de fornecedor de modelos legível no repositório ou no ambiente
crud-adherence Uma rota de mutação cuja verificação de direitos não nomeia nada no registo
blocked-backends Uma rota que não é servida, nem bloqueada pelo nome, nem recusada por lei, nem detida noutro local
every-test-runs Testes que o glob do script de teste nunca alcança
tiles-are-invariant Uma junção em cache invariante ao inquilino que lê um valor de inquilino ou ignora a autenticação
api-contract Uma rota registada que o manifesto não declara, ou uma declarada que o código nunca regista
rls-present Uma tabela sem segurança ao nível da linha forçada; uma função SECURITY DEFINER sem um search_path fixado
no-set-config Código de plugin a vincular a definição de inquilino por si mesmo
db-role-honest Um caminho de pedido a ligar-se como o proprietário ou migrador, ou a pedir SUPERUSER ou BYPASSRLS
platform-clients Um cliente SDK importado mas não listado em backend.platformClients, ou listado mas nunca importado
rights-register Uma rota de âmbito sem um direito declarado; uma verificação de direitos ao lado do registo
refusal-ledger Uma tabela de recusa declarada sem livro-razão instalado, ou um corpo de recusa enviado a contorná-la
grants-declared Uma tabela concedida que o manifesto não declara; privilégios de lugar de leitura distribuídos manualmente
people-declared Um bloco people sem a sua rota de varrimento, guarda e tabelas
functions-closure Um plugin Azure Functions cujas rotas servidas e rotas declaradas divergem
declared-input Uma lista de parâmetros de consulta de um processador que não coincide com o query declarado da rota

O diretório gates/ contém os cinco ficheiros de isenção que uma barreira de controlo pode ler (demo-exempt.json, non-crud.json, blocked-backends.json, tenant-resolving.json e invariant-seams.json), um motivo por entrada. Um motivo em branco conta como nenhuma entrada, e uma entrada que nomeie algo que já não existe faz falhar a barreira de controlo. Também pode colocar lá os seus próprios módulos de barreira de controlo, e o nexus-gates recolhe-os juntamente com os integrados.

Compatibilidade
Compatibilidade
A compatibilidade mostra que versão do SDK funciona com que versão da plataforma, a partir de execuções noturnas do início rápido. Um par não testado indica-o, e um par com falha nomeia a alteração que o quebrou.

O pipeline do modelo

O modelo não inclui nenhum fluxo de trabalho escrito manualmente. A sua configuração de pipeline nomeia o Dockerfile, o único argumento de compilação (o token de registo), a execução de teste da migração e a sonda de arranque, bem como a barreira de controlo que a fila de fusão executa. A ordem é a ordem pela qual desejaria que ocorresse uma falha.

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

Mais duas verificações são executadas em torno da imagem. A execução de teste de migração aplica cada ficheiro a um Postgres descartável antes que a imagem possa ser lançada, com o mesmo executor que a produção utiliza: nexus-migrate provision uma vez como superutilizador e, em seguida, cada ficheiro numerado como migrador. A sonda de arranque inicia a imagem compilada com o seu próprio ponto de entrada e cada variável que required-env imprime, apontada para substitutos que aceitam ligações e nunca respondem. O servidor aguarda pela base de dados, dentro da sua janela limitada, e essa espera é o sinal de aprovação; um carregador de configuração que se recuse a arrancar faz falhar a compilação ali mesmo e não em produção.

Construir na edição Community
Construir na edição Community
Na edição Community, um programador obtém os mesmos caminhos padrão, um espaço de desenvolvimento e ramos de dados num único servidor, com o código no seu próprio alojamento Git. O ambiente de preparação, as unidades piloto e as cópias mascaradas de dados reais estão incluídos na edição Enterprise.

Quanto custa

O SDK retira-lhe a necessidade de tomar decisões, e algumas delas tê-las-ia tomado de forma diferente. O manifesto recusa chaves que desconhece, a tabela de rotas tem de corresponder exatamente ao seu código, as funções da base de dados não lhe cabem a si desenhar, e os controlos fazem falhar uma compilação por falta de uma permissão numa leitura. No meu primeiro plugin, passei um dia a discutir com api-contract sobre uma rota que tinha registado e me tinha esquecido de declarar. Tinha razão; a rota estava desprotegida. Espere que o primeiro plugin pareça lento, e espere que o segundo demore um terço do tempo.