Single Executable Applications

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

by

Há alguns meses, quem imaginaria que uma pergunta aparentemente inocente de um cliente me levaria tão a fundo no mundo dos Single Executable Applications, também conhecidos como SEA, ou binários executáveis?

A equipe deles estava usando 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 ideal por anos, mas, ao planejar a migração para o Node.js v22, surgiu outro problema: o PKG não acompanhava o runtime mais recente.

O PKG precisa corrigir o Node.js, o que cria um desafio contínuo de manutenção. Cada nova versão do Node.js exige atualizações no PKG, causando um atraso inevitável e dores de cabeça de configuração, como meu cliente estava enfrentando.

Foi então que me lembrei de ter ouvido falar dos 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, compartilharei o que aprendi sobre SEA, um recurso que muda fundamentalmente a forma como empacotamos e distribuímos aplicações Node.js. Se você já se deparou com:

  • Atrasos aguardando que as ferramentas de empacotamento suportem novas versões do Node.js
  • Requisitos de configuração complexos para módulos nativos
  • O fardo da manutenção de 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 pelas bases técnicas e pela 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

Primeiramente, 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 elementos separados
  • Dependências de Ambiente: As aplicações só funcionam quando o ambiente de destino tem a configuração exata
  • Fragilidade da 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 causar a falha de tudo. É como construir um castelo de cartas: basta um pequeno erro para que tudo desmorone.

Implantação de Single Executable Applications

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

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

Essa 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 deixá-lo para o momento da implantação. Falando nisso, você sabe o que é automação de marketing?

O resultado? Aplicações mais confiáveis, mais seguras e significativamente mais fáceis de implantar. É como ter um contêiner completo, pronto para ser executado em qualquer lugar.

Fundamentos Técnicos

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

A Anatomia de um SEA

Um Single Executable Applications é construído 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
  • Complementos nativos
  • Ativos estáticos
  1. Estágio do Sistema de Arquivos Virtual

É aqui que a mágica realmente 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ório exatamente como estavam
  • Mantém as permissões de arquivo
  • Mantém os links simbólicos 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 do SEA é um pequeno trecho de código C++ na origem 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;
};

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

  1. Uso de um número mágico (0x1EA) para identificar o programa injetado durante a desserialização
  2. Suporte para código e snapshots
  3. Localização opcional para cache de código (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 cache de código, se solicitado (falarei sobre cache mais tarde)
  4. Processar e incluir ativos
  5. Serializar 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.

Sistemas operacionais diferentes usam formatos binários diferentes. O Node.js oferece suporte ao seguinte:

  • O macOS usa Mach-O
  • O Windows usa Portable Executable (PE)
  • O 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 para Leitura

Um recurso de segurança importante é o acesso aos ativos somente para leitura.
A implementação garante que os ativos permaneçam somente para 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. Nenhuma API existe 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 V8 e o ambiente 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 retorno de chamada de execução CJS (CommonJS) com o código convertido (a partir disso, você pode adivinhar que apenas o 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 o Fastify para demonstrar os recursos 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 de API HTTP Node.js típica: 

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 Principais 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');

Leave a Comment

Exit mobile version