Single Executable Applications

Como Criar Aplicações Executáveis Únicas com Node.js

by

Há alguns meses, uma pergunta aparentemente inocente de um cliente me levou a explorar profundamente o mundo das Single Executable Applications (SEA), também conhecidas como binários executáveis. A equipe deles usava o PKG para empacotar aplicações Node.js em executáveis independentes, mas encontraram um obstáculo: o PKG foi descontinuado. Eles criaram um fork do PKG, que se tornou a solução por anos, mas ao migrar para o Node.js v22, surgiu outro problema: o PKG não acompanhava o runtime mais recente.

O PKG precisa patchar o Node.js, criando um desafio contínuo de manutenção. Cada nova versão do Node.js exige atualizações no PKG, levando a um inevitável atraso e dores de cabeça de configuração, como meu cliente estava enfrentando. Foi então que me lembrei das Single Executable Applications (SEA) do Node.js, um recurso nativo. Como alguém que passou anos otimizando pipelines de implantação e estratégias de contêineres, eu sabia que tinha que explorar essa alternativa promissora.

Neste artigo, compartilho o que aprendi sobre SEA, um recurso que muda fundamentalmente a forma como empacotamos e distribuímos aplicações Node.js. Se você já enfrentou:

  • Atrasos esperando que ferramentas de empacotamento suportem novas versões do Node.js
  • Requisitos de configuração complexos para módulos nativos
  • O fardo de manutenção de manter as versões de dependências e ferramentas de construção sincronizadas com o runtime
  • A busca por artefatos de implantação mais leves e portáteis

…então você achará esta exploração valiosa.

Vou guiá-lo através dos fundamentos técnicos e da implementação prática do SEA, mostrando como ele pode simplificar sua estratégia de implantação, tornando suas aplicações mais portáteis e seguras.

Dois Mundos da Distribuição de Aplicações

Primeiro, quero distinguir entre cada método de distribuição.

Implantação Tradicional do Node.js

A abordagem convencional para a implantação do Node.js tem várias limitações:

  • Distribuição Fragmentada: Arquivos de origem, dependências e runtime são todos peças separadas
  • Dependências de Ambiente: As aplicações só funcionam quando o ambiente de destino tem a configuração exata
  • Fragilidade de Configuração: Os arquivos de configurações devem ser corretamente colocados e formatados
  • Restrições de Versão: A versão correta do Node.js deve estar presente

Isso cria um pipeline de implantação frágil, onde uma pequena configuração incorreta pode fazer com que tudo falhe.

Implantação de Single Executable Applications

As Single Executable Applications (SEA) representam uma mudança fundamental de paradigma:

  • Autossuficiência Completa: Código, dependências, ativos e runtime agrupados em um único binário
  • Independência de Ambiente: A aplicação carrega seu ambiente consigo
  • Configuração Protegida: Configurações incorporadas e protegidas dentro do executável
  • Simplicidade de Implantação: Um arquivo para implantar, um arquivo para executar

Esta abordagem representa um shift-left na entrega de aplicações, movendo as preocupações de implantação das equipes de operações para o processo de desenvolvimento. Com o SEA, os desenvolvedores assumem a responsabilidade de empacotar todo o ambiente da aplicação durante o desenvolvimento, em vez de deixar para o momento da implantação.

O resultado? Aplicações que são mais confiáveis, mais seguras e significativamente mais fáceis de implantar. Além disso, com o aumento da popularidade dos dispositivos móveis, os consumidores estão buscando por aparelhos mais rápidos e eficientes, com mais recursos e conectividade.

Fundamentos Técnicos

Como um desenvolvedor Node.js de longa data, eu estava curioso sobre como este recurso foi implementado. Vamos espiar sob o capô!

A Anatomia de um SEA

Uma Single Executable Application é construída em três estágios distintos:

  1. Estágio de Coleta

É aqui que as coisas começam a ficar interessantes! A ferramenta SEA reúne:

  • Código da aplicação JavaScript
  • Arquivos de configuração JSON
  • Dependências de node_modules
  • Add-ons nativos
  • Ativos estáticos
  1. Estágio de Sistema de Arquivos Virtual

É aqui que a verdadeira mágica acontece. Em vez de apenas agrupar arquivos, o SEA cria um sistema de arquivos em memória em miniatura que:

  • Preserva as estruturas de diretórios exatamente como eram
  • Mantém as permissões de arquivo
  • Mantém os symlinks intactos
  • Retém os caminhos de arquivo originais
  • Permite acesso aleatório rápido
  1. Estágio de Integração Binária

A etapa final injeta nosso sistema de arquivos virtual no binário Node.js:

  • Preserva a capacidade de execução
  • Mantém a compatibilidade de assinatura de código
  • Permite a detecção de runtime
  • Suporta formatos multiplataforma (Mach-O, PE, ELF)

Internos

O maestro por trás da orquestra SEA é um pequeno trecho de código C++ na fonte do Node.js.

Nota: Esta é a parte nerd, sinta-se à vontade para pular para a Implementação Prática se estiver mais interessado em exemplos práticos.

Configuração do SEA

O node_sea.cc evolui em torno da estrutura SeaResource.

class SeaResource {
 public:
  static constexpr uint32_t kMagic = 0x1EA;  // SEA magic number
  static constexpr size_t kHeaderSize = 8;    // Size of header

  SeaFlags flags;
  std::string_view code_path;
  std::string_view main_code_or_snapshot;
  std::optional<std::string_view> code_cache;
  std::unordered_map<std::string_view, std::string_view> assets;
};

Esta estrutura nos mostra várias decisões de design críticas:

  1. Uso de um número mágico (0x1EA) para identificar o programa injetado durante a deserialização
  2. Suporte para código e snapshots
  3. Localização opcional para code cache (falaremos sobre isso mais tarde)
  4. Armazenamento de ativos em um formato de chave-valor

Processo de Geração do SEA

O processo de alto nível da criação do SEA é simples:

  1. Ler o script principal (agrupado)
  2. Gerar snapshot V8, se necessário (falarei sobre snapshot mais tarde)
  3. Gerar code cache, se solicitado (falarei sobre cache mais tarde)
  4. Processa e inclui ativos
  5. Serializa tudo em um único Blob 
ExitCode GenerateSingleExecutableBlob(const SeaConfig& config,
                                     const std::vector<std::string>& args,
                                     const std::vector<std::string>& exec_args) {
  std::string main_script;
  ReadFileSync(&main_script, config.main_path.c_str());

  if (static_cast<bool>(config.flags & SeaFlags::kUseSnapshot)) {
    GenerateSnapshotForSEA(...);
  }

  if (static_cast<bool>(config.flags & SeaFlags::kUseCodeCache)) {
    GenerateCodeCache(config.main_path, main_script);
  }

  std::unordered_map<std::string, std::string> assets;
  BuildAssets(config.assets, &assets);

  SeaSerializer serializer;
  serializer.Write(sea);
}

Injeção de Recursos

O SEA usa a biblioteca postject para adicionar nosso VFS como uma nova seção no formato de arquivo binário.

Diferentes sistemas operacionais usam diferentes formatos binários. O Node.js suporta o seguinte:

  • macOS usa Mach-O
  • Windows usa Portable Executable (PE)
  • Linux usa ELF (Executable and Linkable Format) 
std::string_view FindSingleExecutableBlob() {
#ifdef __APPLE__
  postject_options options;
  postject_options_init(&options);
  options.macho_segment_name = "NODE_SEA";
  const char* blob = static_cast<const char*>(
      postject_find_resource("NODE_SEA_BLOB", &size, &options));
#else
  const char* blob = static_cast<const char*>(
      postject_find_resource("NODE_SEA_BLOB", &size, nullptr));
#endif
  return {blob, size};
}

Ativos Somente Leitura

Um recurso de segurança importante é o acesso a ativos somente leitura.

A implementação garante que os ativos permaneçam somente leitura por meio de um design de API cuidadoso:

  1. Os ativos são armazenados como string_views imutáveis
  2. O ArrayBuffer é criado com um deleter no-op
  3. Não existe API para modificar ativos depois de agrupados
void GetAsset(const FunctionCallbackInfo<Value>& args) {
  // Validate input
  CHECK_EQ(args.Length(), 1);
  CHECK(args[0]->IsString());

  Utf8Value key(args.GetIsolate(), args[0]);
  SeaResource sea_resource = FindSingleExecutableResource();

  auto it = sea_resource.assets.find(*key);
  if (it == sea_resource.assets.end()) {
    return;
  }

  std::unique_ptr<v8::BackingStore> store = ArrayBuffer::NewBackingStore(
      const_cast<char*>(it->second.data()),
      it->second.size(),
      [](void*, size_t, void*) {},  // No-op deleter prevents modifications
      nullptr);

  Local<ArrayBuffer> ab = ArrayBuffer::New(args.GetIsolate(), std::move(store));
  args.GetReturnValue().Set(ab);
}

Carregar o SEA

A etapa final é carregar o SEA e executar o código agrupado:

  1. Obtém o contexto e o ambiente V8 atuais
  2. Encontra o recurso SEA usando FindSingleExecutableResource()
  3. Verifica se não está usando um snapshot (CHECK(!sea.use_snapshot()))
  4. Converte o código principal em um valor V8 usando ToV8Value
  5. Chama o callback de execução CJS (CommonJS) com o código convertido (a partir disso, você pode adivinhar que apenas CJS é suportado!) 
MaybeLocal<Value> LoadSingleExecutableApplication(
    const StartExecutionCallbackInfo& info) {
  Local<Context> context = Isolate::GetCurrent()->GetCurrentContext();
  Environment* env = Environment::GetCurrent(context);
  SeaResource sea = FindSingleExecutableResource();

  CHECK(!sea.use_snapshot());
  Local<Value> main_script =
      ToV8Value(env->context(), sea.main_code_or_snapshot).ToLocalChecked();
  return info.run_cjs->Call(
      env->context(), Null(env->isolate()), 1, &main_script);
}

Implementação Prática

Eu construí um serviço de gerenciamento de arquivos usando Fastify para demonstrar as capacidades do SEA no mundo real. O código fonte completo está disponível no repositório Node-SEA Demo.

Espero que Liran Tal não me envergonhe com este aplicativo de exemplo, sem validação de entrada, sem limite de taxa, sem autenticação, pelo menos há uma verificação de path traversal 😉

Estrutura do Projeto

A estrutura do projeto é simples, ao mesmo tempo em que representa uma aplicação típica de API HTTP do Node.js:

node-sea-demo/
├── src/
│   ├── main.ts                 # Entry point with SEA detection
│   ├── app/
│   │   ├── app.ts             # Fastify setup
│   │   ├── helpers.ts         # Utilities
│   │   └── routes/
│   │       └── root.ts        # API handlers
│   └── assets/                # Static files
├── sea-config.json            # SEA configuration
└── project.json              # Build configuration

Detalhes Chave da Implementação

O primeiro desafio que encontrei foi detectar se estávamos executando em um ambiente SEA para substituir a função require.

import sea from 'node:sea';

if (sea.isSea()) {
  const { createRequire } = require('node:module');
  require = createRequire(__filename);
}

const server = Fastify({
  logger: true,
  trustProxy: true,
});

Ao executar como um SEA, require.cache é indefinido! O bug está sendo rastreado aqui.

Outro ponto problemático foi gerenciar os plugins do Fastify dentro do ambiente SEA. Descobri que o registro explícito funciona melhor do que o carregamento automático, para evitar problemas de compilação:

// app.ts

export async function app(fastify: FastifyInstance, opts: AppOptions) {

  await fastify.register(sensible);

  await fastify.

Leave a Comment

Exit mobile version