Iniciar sessãoAgendar apresentação

Capítulo 2.25

Construir para cada edição

O que muda quando uma extensão tem de funcionar em todas as edições, numa instalação isolada da rede (air-gapped), num pacote de missão do Nexus Edge ou sob a marca própria de um cliente. Abrange a linha de licenciamento para módulos Enterprise e a entrega offline assinada, com uma matriz do que fazer de forma diferente para cada destino.

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

17 minutos de leitura

Na Corrán Orbital, disponibilizamos software para mais destinos do que a maioria das equipas. Os nossos próprios engenheiros executam a edição Enterprise em terra. Um satélite, o CORR-3, executa um pacote de missão no Nexus Edge. Dois clientes executam a edição Community num único servidor, um executa uma instalação Enterprise isolada da rede (air-gapped) que nunca vê a Internet, e criámos um pacote para uma seguradora na sua própria instalação. O código subjacente é maioritariamente o mesmo, e as diferenças prendem-se sobretudo com os locais para onde pode ir e como lá chega.

Este capítulo analisa cada destino individualmente: a base sobre a qual desenvolve, no que não tem permissão para tocar e como o resultado chega ao cliente. Uma matriz no final resume tudo numa única página. O Capítulo 2.18, O modelo de extensão, explica como diferem as competências (skills), plugins, pacotes e módulos. O Capítulo 2.2, Edições ao detalhe, descreve as próprias edições.

Community e o núcleo aberto

A Community é o núcleo aberto, sob a Licença Apache, Versão 2.0. Pode fazer um fork e disponibilizar alterações. O ficheiro NOTICE que a acompanha refere um ponto que vale a pena saber antes de aplicar qualquer marca: a licença não concede o uso dos nomes ou marcas registadas da Adverant, além da menção à origem do trabalho.

A edição Community estende-se da mesma forma que a Enterprise. O Plugin SDK (kit de desenvolvimento de software) é o mesmo pacote em ambas as edições, e nem o modelo de serviço completo nem os 22 controlos de conformidade mudam; o capítulo 2.21, O Plugin SDK, aborda este tema. As competências também funcionam. A Community recebe todo o criador e biblioteca do Skills Engine, com versões e testes, enquanto os lançamentos canário e a aprovação por duas pessoas permanecem na Enterprise.

Construir na edição Community
Construir na edição Community
Desenvolvimento de um plugin de reservas num único servidor Community. Note o passe de acesso, que chega a Propose através do GitHub e não oferece Elevate, e a pré-visualização à direita a listar o que a edição Enterprise acrescenta.

As páginas de programador na Community oferecem os mesmos caminhos padrão (golden paths) com três diferenças que sentirá de imediato:

  1. O seu código reside no GitHub em vez de nos repositórios da própria instalação. O caminho padrão do plugin cria um repositório GitHub e um espaço de desenvolvimento a partir do mesmo modelo fixo que a Enterprise utiliza; o ecrã DV18 mostra-o a criar room-bookings.
  2. Os caminhos padrão de pacotes de domínio e de plataforma são exclusivos da Enterprise. Na Community, desenvolve plugins e competências, além de lentes e fluxos de trabalho sobre o que executa.
  3. Os passes da Community param abaixo do nível Elevate. Num único servidor não há produção para alcançar a partir de um IDE (ambiente de desenvolvimento integrado), e administra o servidor diretamente. Uma tentativa a partir do IDE é recusada com PASS_TIER_REQUIRED.

Um espaço de desenvolvimento Community num servidor pequeno é modesto. O nosso tinha 2 núcleos e 8 GiB de memória, fechado exceto para o que o manifesto declara, e terminou após 7 dias de inatividade.

Retribuir com contribuições

O Skills Engine também está sob a licença Apache-2.0 e aceita contribuições da forma habitual. Faça um fork do repositório, crie um ramo a partir de main, faça a alteração com os respetivos testes e execute as verificações antes de abrir um pull request:

git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheck

Uma contribuição que altere o comportamento precisa de um teste que falhe sem ela. Isto não é apenas uma regra interna: as próprias regras de teste do SDK ditam que cada novo teste deve demonstrar que falha na árvore antes da alteração, e os revisores pedem essa evidência.

Módulos Enterprise e a linha de licenciamento

A edição Enterprise é a Community mais módulos licenciados. Um módulo licenciado é um artefacto separado que um serviço Community carrega ao iniciar, e é a forma como as funcionalidades Enterprise, e qualquer módulo fechado que desenvolva para clientes Enterprise, se ligam ao núcleo aberto.

A regra que faz isto funcionar é a linha de licenciamento. Um módulo fechado pode alcançar a edição Community através de um único pacote, @adverant/nexus-spi, a interface de fornecedor de serviços (SPI). Está sob a licença Apache-2.0 e contém interfaces mais as guardas de tipo que um anfitrião e um módulo utilizam para se verificarem mutuamente, sem qualquer outra lógica de tempo de execução. O acoplamento através da linha é uma interface ou um protocolo de rede, nunca código-fonte.

Exportação O que é
RouteModule Um módulo de rota licenciado: id, featureGroup, bodies e register(app, ctx), que monta os seus encaminhadores na aplicação do anfitrião
SpiApp A parte da aplicação HTTP do anfitrião em que um módulo toca: use
SpiContext O que o anfitrião entrega a um módulo: o controlo de produto e a guarda de âmbito, o leitor de licenças, o conjunto de consultas de âmbito restrito, o esquema do serviço, os endereços a montante (upstream) e os clientes da plataforma
SpiRuntime Os valores do Plugin SDK que um anfitrião entrega a um módulo, para que o módulo nunca importe o tempo de execução do próprio SDK
SpiPlane O que um plano licenciado acrescenta além de rotas, como as leituras de ecrã que serve
ScreenModule Um grupo de ecrãs licenciados de uma consola: group, featureGroup, routes, screens e menu
GrantCheck (featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }>

A framework HTTP e o tipo de ecrã da consola são parâmetros de tipo, pelo que a interface não vincula nenhum deles. Eis o esqueleto de um módulo de rota, com um tipo de processador Express:

import type { GrantCheck, RouteModule, SpiApp, SpiContext } from "@adverant/nexus-spi";
import { Router, type RequestHandler } from "express";

export function auditTrail(checkGrant: GrantCheck): RouteModule<RequestHandler> {
  return {
    id: "audit-trail",
    featureGroup: "<feature-group>",
    bodies: [],
    register(app: SpiApp<RequestHandler>, ctx: SpiContext<RequestHandler>) {
      const router = Router();
      router.get("/api/audit-trail", ...ctx.requireScope, async (_req, res) => {
        const verdict = await checkGrant("<feature-group>");
        if (!verdict.entitled) {
          res.status(403).json({
            error: true,
            code: verdict.code,
            message: "This organisation's licence does not carry the audit trail.",
            troubleshooting: ["An owner or administrator can turn it on with a licence from Adverant."],
          });
          return;
        }
        res.json({ entries: [] });
      });
      app.use(router);
    },
  };
}

<feature-group> é o grupo de funcionalidades da matriz de edições que o módulo serve. Cada rota licenciada corre atrás de ctx.requireScope, o controlo de produto e guarda de âmbito do anfitrião, e o módulo também verifica a sua própria concessão antes de responder. Um módulo que não tenha direito recusa com LICENCE_LOCKED e apresenta a pré-visualização da funcionalidade, nunca os seus dados. O seu módulo também nunca importa o tempo de execução do Plugin SDK, porque o SDK é um pacote Community que a linha não admite. O anfitrião entrega-lhe os valores do SDK que ele invoca. Antes de carregar qualquer módulo, o anfitrião instala um SpiHost em globalThis sob Symbol.for(SPI_HOST_KEY), contendo o tempo de execução do SDK e o próprio kit de rotas da aplicação. Isto tem de acontecer primeiro: um módulo compilado num único pacote é avaliado como um todo, e uma chamada register chegaria demasiado tarde para o código que lê os valores do SDK enquanto carrega. Para tipos, @adverant/nexus-spi/sdk/<module> reexporta as declarações do SDK, integradas (vendored) sem alterações a partir de um lançamento do SDK e fixadas por soma de verificação (checksum), para que o seu módulo verifique os tipos contra os mesmos corpos de recusa e clientes que um plugin utiliza.

Um módulo de ecrã segue mais uma regra: um módulo por grupo de funcionalidades, pelo que um grupo cujos ecrãs pertençam a dois grupos de funcionalidades é disponibilizado como dois módulos, e apenas um deles contém a linha de menu.

O que o controlo da linha de licenciamento recusa

O controlo da linha de licenciamento da Adverant sujeita cada módulo Enterprise a esta linha, e vale a pena sujeitar os seus próprios módulos fechados à mesma regra. A sua configuração resume-se a um ficheiro:

{
  "communityScopes": ["@adverant/", "@adverant-nexus/"],
  "allowedCommunityPackages": ["@adverant/nexus-spi"],
  "enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
  "communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
  "allowedCommunityGoModules": []
}

Cada um destes casos constitui uma ocorrência com o respetivo ficheiro e linha:

  • qualquer importação de um pacote sob um âmbito Community que não seja a interface permitida ou um pacote Enterprise, incluindo importações dinâmicas;
  • qualquer especificador, caminho de importação Go ou URL de dependência que nomeie um repositório Community, a menos que seja um módulo Go listado em allowedCommunityGoModules;
  • uma importação relativa que saia fora do repositório;
  • uma dependência package.json que seja um caminho file:, link:, portal: ou workspace: fora do repositório, ou um URL Git para um repositório Community;
  • um go.mod replace que aponte para fora do repositório.

Termina com o código 0 quando está limpo e 1 se houver ocorrências. O código de saída 2 significa que recusou, porque a sua configuração estava incorreta ou não analisou nada. O pacote de interface não é publicado num registo. Deve manter uma cópia fixada ao byte do pacote compilado dentro do seu repositório como um pacote file: local, com uma fixação SHA256SUMS e uma verificação no seu pipeline que recuse uma cópia que seja diferente. Como a cópia está dentro do repositório, o controlo aceita-a.

Duas caixas grandes lado a lado. A caixa da esquerda tem a etiqueta "Community (Apache-2.0)" e contém caixas mais pequenas para "Services", "Plugin SDK" e "@adverant/nexus-spi". A caixa da direita tem a etiqueta "Enterprise module (closed)" e contém "RouteModule", "ScreenModule" e "GrantCheck". Uma seta sólida atravessa a linha, da caixa da direita apenas para "@adverant/nexus-spi", com a etiqueta "compile against". Duas setas tracejadas da caixa da direita para "Services" e "Plugin SDK" estão riscadas e têm a etiqueta "licence-line gate: finding".
A linha de licenciamento entre a edição Community e um módulo Enterprise.

Compilações por edição

Se a sua extensão for disponibilizada para clientes em ambas as edições, deve compilá-la uma vez por edição, e cada compilação ocorre na sua própria árvore composta. Compor uma árvore significa escolher apenas os ficheiros que pertencem a essa edição. A própria exportação da Adverant faz isto a partir de uma lista de limites na qual cada ficheiro monitorizado é atribuído por regras em que a primeira correspondência ganha: uma regra nomeia uma capacidade e a edição do ficheiro decorre do nível dessa capacidade na matriz de edições, ou nomeia uma classe de ficheiro que não é disponibilizada em nenhuma das edições, com um motivo. Os ficheiros exclusivos de compilação são disponibilizados na árvore Enterprise e, quando assinalados, também na árvore Community. A cadeia de migração de um módulo consiste em dados do instalador e é disponibilizada na árvore de todas as edições.

Depois, execute toda a compilação a partir do zero em cada árvore composta. Isso significa os três comandos, sempre:

npm ci
npm test
npm run build

Aprendemos isto da forma mais dispendiosa: uma árvore Enterprise passou nos testes enquanto a árvore Community falhou na sua compilação de produção, porque um tipo de que precisava existia apenas num ficheiro Enterprise. Os testes passarem numa árvore não dizem nada sobre a outra. Os testes de uma edição podem importar apenas o que a árvore dessa edição contém, e a exportação recusa um teste que alcance fora dela.

A exportação também escreve a licença de cada edição. Os ficheiros Community contêm o identificador SPDX (Software Package Data Exchange) Apache-2.0; os ficheiros Enterprise contêm LicenseRef-Adverant-Enterprise e o seu package.json indica UNLICENSED. Não edite esses campos manualmente: a exportação reescreve-os, e uma cópia que já não corresponda ao texto da licença fixada é recusada.

Team: apenas na cloud

A edição Team é a Community mais o conjunto Team, e é executada apenas na nuvem da Adverant. Não existe uma edição Team autoalojada (self-hosted). O conjunto Team acrescenta seis capacidades sobre a Community, entre elas o painel de trabalho consolidado, blocos de notas partilhados, administração da biblioteca de competências e operações de fluxo de trabalho com promoção entre ambientes.

Para um programador, ser exclusivamente na nuvem significa uma coisa: um cliente Team obtém o seu plugin como um lançamento assinado através do catálogo, nunca a partir dos seus próprios servidores. Constrói-o da mesma forma que um editor externo constrói, num cluster de editor.

Cluster de editor
Cluster de editor
O cluster virtual próprio de um editor na nuvem da Adverant, apenas com dados de exemplo. Siga o fluxo em tempo real ao longo do topo: o IDE alcança o cluster do editor e os dados de exemplo, um lançamento assinado passa por revisão até ao catálogo e não há qualquer caminho para nenhum cliente.

Um cluster de editor é um cluster virtual na nuvem da Adverant com uma quota definida pela Adverant. Contém apenas dados de exemplo e não tem rota para nenhum cliente. Pedir aí uma cópia mascarada dos dados de um cliente é recusado com TENANT_BOUNDARY; um cliente pode partilhar resultados de testes consigo, nunca os seus dados. O seu passe nesse cluster nunca alcança o ambiente de um cliente. Quando o lançamento está pronto, é assinado e revisto pela Adverant antes de ser listado no catálogo. Cada cliente escolhe então se o instala e concede-lhe apenas o que o seu manifesto declara, unidade a unidade. Uma chamada a qualquer elemento que o manifesto não tenha declarado é recusada do lado do cliente com CONNECTION_SCOPE_EXCEEDED, e a única forma de o adicionar é através de um novo lançamento que o cliente reveja.

Clientes em ambientes isolados da rede (air-gapped)

Um dos nossos clientes executa o Nexus onde nada entra ou sai através de uma rede. A sua instalação é descrita no capítulo 2.10, Instalação isolada da rede (air-gapped). Para nós, isso significou enviar o nosso plugin em suportes físicos assinados, e a ferramenta para tal é nexus-airgap, do kit de entrega soberana @adverant/nexus-sovereign.

Um pacote selado (sealed bundle) é um ficheiro tarball único, assinado e autónomo. Pode conter imagens e migrações, competências pré-assinadas e pesos de modelos, bem como uma SBOM (lista de materiais de software) com as licenças de tudo o que está no interior. O seu manifesto lista cada ficheiro com o respetivo SHA-256 e é assinado com Ed25519. Construir um a partir do código tem este aspeto:

import { SealedBundleExporter } from "@adverant/nexus-sovereign";

const { bundleDigest } = await new SealedBundleExporter().export(source, {
  outPath: "./cold-chain-0.4.0.tar.gz",
  profile: "airgap",
  signerPrivateKeyPem,
});

signerPrivateKeyPem é a sua chave de assinatura de lançamento. O comando nexus-airgap bundle faz o mesmo a partir da linha de comandos. O operador do cliente verifica-o então antes de mais nada:

nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgap

A verificação recalcula o hash de cada ficheiro contra o manifesto, rejeita qualquer ficheiro que o manifesto não liste, requer um signatário Ed25519 fidedigno e recusa qualquer pacote cuja lista de permissões de rede não esteja vazia. Um ficheiro alterado após a assinatura falha com BUNDLE_INTEGRITY_VIOLATION. Diga ao operador para parar aí e o contactar; existe um parâmetro não estrito, mas nunca o devem utilizar.

Três regras orientaram a nossa entrega:

  1. A chave fidedigna viaja separadamente do pacote. Enviamos a chave pública e o SHA-256 do pacote por uma via diferente da do suporte físico, para que um pacote não possa atestar por si próprio.
  2. Nada no pacote pode precisar da rede na instalação. Sem obtenção de pacotes, sem transferência de modelos, sem chamada de licença. Se o plugin precisar de um modelo, o próprio servidor de modelos do cliente fornece-o através do Encaminhador de Fornecedores de IA (inteligência artificial).
  3. Após a verificação, o operador introduz o lançamento através dos canais de lançamento da própria instalação, exatamente como faria um cliente ligado à rede. O pacote é a forma como os bytes chegam, não uma forma de contornar os controlos de promoção.

O trabalho isolado da rede é mais lento, e não há forma de resolver isso do nosso lado. Um byte errado custa um novo conjunto de suportes físicos e outra viagem, pelo que nós próprios verificamos o pacote numa máquina limpa com o mesmo comando antes de sair do edifício.

Pacotes de missão do Nexus Edge

O Nexus Edge é um Nexus mais pequeno que é executado em satélites e drones, em computadores de missão mantidos separados do computador de voo. É um suplemento (add-on) com uma licença por plataforma ou frota. O que muda de uma missão para a seguinte é o pacote de missão, e construí-los é uma boa parte do meu trabalho.

Um pacote de missão contém o que a carga útil (payload) precisa para uma missão. Juntamente com os seus modelos e adaptadores, contém a ontologia com um grafo inicial, passos de agente, regras de alerta, as prioridades para o que é transferido primeiro para terra, uma tabela de alocação a indicar que computador executa o quê, os níveis de degradação para os quais a plataforma pode descer quando um computador falha, e os casos de teste que tem de passar a bordo.

Construir um pacote de missão
Construir um pacote de missão
Construção do Maritime watch 1.5 a partir do 1.4. Note os casos de teste a bordo (48, todos têm de passar) e a tabela de alocação, que indica o que é executado em cada uma das duas placas GPU (unidade de processamento gráfico) e na placa CPU (unidade central de processamento) em cada nível de degradação.

Os pacotes são construídos e assinados em terra. Algumas regras práticas das nossas compilações:

  • Mantenha as partes grandes estáveis. O Maritime watch 1.5 adicionou um adaptador de localização de navios e duas regras de alerta; o modelo de linguagem e a ontologia não mudaram, pelo que o pacote ficou com 412 MB em vez de 9.8 GB. A ligação ascendente (uplink) é estreita e os modelos base são carregados antes do lançamento.
  • Utilize um único modelo de incorporação (embedding) para toda a família da missão, tanto em terra como na carga útil, para que as alterações ao grafo que são transferidas para terra possam ser fundidas com o grafo em terra.
  • A carga útil nunca envia um comando para os sistemas de voo. Envia pedidos tipados através do supervisor para o computador de voo, que responde a cada um com uma justificação.
  • Cada tipo de hardware precisa da sua própria verificação do pacote. A instalação de um pacote não verificado para o hardware de um dispositivo é recusada com PACK_NOT_CHECKED_FOR_HARDWARE.
Assinar e enviar um pacote
Assinar e enviar um pacote
Lançamento do Maritime watch 1.5 para o CORR-3. São necessárias duas de três assinaturas, para que uma chave roubada não possa lançar um pacote, e o plano mostra o pacote a ser ativado apenas após os seus 48 testes passarem a bordo.

O lançamento requer duas de três assinaturas. A nossa e a da Adverant são o par habitual, e a terceira é uma chave offline que guardamos num cofre para quando uma das outras duas se perde. O pacote sobe para a ranhura inativa (idle slot), é verificado, executa os seus casos de teste nas placas reais e só é ativado se todos passarem, com um contador que impede a reinstalação de um pacote mais antigo. Se um teste falhar, a plataforma permanece no pacote anterior e a falha é enviada para terra na passagem seguinte. Implementamos numa plataforma de cada vez, cada uma após uma semana sem problemas. Os pacotes permanecem válidos enquanto uma plataforma está sem contacto, pelo que um satélite sem ligação continua a trabalhar com o pacote que tem.

Em veículos e embarcações, o Edge pode ser executado em k3s. Uma nave espacial executa um supervisor com imagens assinadas ou binários estáticos e uma tabela de alocação fixa em vez de Kubernetes, e é por isso que a tabela de alocação viaja dentro do pacote.

Montras de marca branca

O suplemento Storefront / marca branca (white-label) permite que um cliente coloque a sua própria marca e domínio no que os seus utilizadores veem, com os seus próprios ecrãs de início de sessão, e receba pagamentos através dos seus próprios gateways. Os dados dos cartões nunca tocam no Nexus.

Um plugin desenvolvido para um cliente de marca branca nunca deve mostrar a Adverant. O manifesto contém tudo o que é específico da marca, e a plataforma resolve o resto a partir da própria marca da organização, em vez de algo fixo (hard-coded) no seu código:

{
  "domains": [
    { "primary": "<app-domain>", "aliases": ["www.<app-domain>"] }
  ],
  "branding": {
    "appName": "<app name>",
    "tagline": "<one line>",
    "primaryColor": "<hex>",
    "accentColor": "<hex>",
    "passkeyRpId": "<app-domain>",
    "oauthClientRef": "brand:<plugin name>:google"
  }
}

<app-domain> é o domínio próprio do cliente, e passkeyRpId tem de coincidir com ele, porque as chaves de acesso (passkeys) estão vinculadas ao domínio onde uma pessoa inicia sessão. Uma aplicação web na sua própria origem autentica as pessoas através dos auxiliares de início de sessão do SDK, cujas duas rotas públicas são as únicas rotas /api desprotegidas que o controlo de âmbito aceita, e apenas quando o manifesto as declara auth: public com allowAnonymous: true. As chamadas de frontend passam pelo proxy da lista de permissões de backend para frontend (BFF), nunca diretamente para um endereço de serviço. O administrador do cliente configura a vertente de pagamentos, desde os gateways até ao checkout com a marca. O seu plugin não o faz.

A matriz

Destino de compilação Desenvolver sobre O que faz de diferente Como chega ao cliente
Community Plugin SDK, Skills Engine Código no GitHub; sem caminhos de pacotes de domínio ou plataforma; sem Elevate O cliente instala-o; não é necessária revisão de catálogo
Enterprise (a sua própria instalação) Plugin SDK, Skills Engine, modelos de pacotes Espaços de desenvolvimento, ramos de dados, cópias mascaradas com o proprietário dos dados; pacotes e lentes Promoção de pré-produção (staging) para uma unidade piloto, e depois para todo o lado
Módulo Enterprise (fechado) Apenas @adverant/nexus-spi Regra da linha de licenciamento; verificação de concessão no seu próprio grupo de funcionalidades; LICENCE_LOCKED quando não tem direito Carregado por um serviço Community no arranque, em instalações licenciadas
Ambas as edições Plugin SDK Compor a árvore de cada edição; npm ci, testes e compilação de produção em cada uma Um lançamento por edição
Team Plugin SDK num cluster de editor Apenas dados de exemplo; apenas na nuvem Lançamento assinado, revisão pela Adverant, catálogo
Isolado da rede (air-gapped) Plugin SDK, @adverant/nexus-sovereign Pacote selado; chave e soma de verificação enviadas separadamente; nada é obtido na instalação Suporte físico assinado, verificado, e depois através dos canais de lançamento da instalação
Nexus Edge Conteúdo do pacote de missão Tabela de alocação, níveis de degradação, testes a bordo, verificações de hardware Duas de três assinaturas, ranhura inativa, ativado após os testes passarem
Marca branca Plugin SDK domains e branding no manifesto; sem o nome Adverant em lado nenhum Tal como na Enterprise, no domínio próprio do cliente

Qualquer que seja o destino, a implementação é feita apenas através dos canais de lançamento da instalação. O Capítulo 2.28, Lançar a sua extensão, aborda esses canais. O Capítulo 2.27, Cenários de compilação, tem uma receita para cada linha acima.