AWS Emulator no localhost: desenvolvimento local de APIs com TypeScript
Entenda a instalação, os requisitos e os cuidados para desenvolver e testar uma API Node.js com TypeScript no AWS Emulator sem atingir a AWS real.
O que é o AWS Emulator
Neste artigo, “localhost” descreve o desenvolvimento na própria máquina; nos exemplos, use o endpoint HTTPS com o endereço literal 127.0.0.1, não localhost. Alguns SDKs podem colocar o nome do bucket no host quando se usa localhost. Lançado pela AWS em 11 de novembro de 2026, o AWS Emulator é um programa de linha de comando que atende localmente às APIs conhecidas pela AWS CLI e pelos SDKs. Assim, uma API Node.js com TypeScript pode trabalhar com S3, DynamoDB, SQS e até Lambda sem criar recursos na nuvem nem exigir uma conta AWS para executar o emulador. A ferramenta serve para construir e testar; não é indicada para produção nem para validar a segurança da aplicação.
O processo escuta HTTPS na máquina, por padrão em 127.0.0.1:9297. Ao iniciar, gera novas credenciais, um arquivo de configuração e um certificado, que ficam em ~/.aws/emulator/. As solicitações precisam usar Signature Version 4 com as chaves daquela execução. A conta exposta é sempre 000000000000, e o ARN de identidade é arn:aws:iam::000000000000:user/emulator. As access key IDs começam com EMULATOR, o que ajuda a distingui-las de chaves reais.
Além da execução como programa local, há um modo embedded para testes em Rust, que roda dentro do processo de teste. Esse modo fica fora do escopo deste fluxo, voltado ao trabalho cotidiano com uma API Node.js e TypeScript. No Linux, a instalação usa um pacote RPM ou Debian; para macOS e Windows, o caminho oficial descrito é Docker.
Estado local e cobertura das APIs
Os recursos ficam na memória e desaparecem quando o emulador para. Não há uma rota administrativa para limpar o estado; para recomeçar, reinicie o processo ou configure --idle-timeout para encerrá-lo depois de um período sem chamadas. Portanto, o fluxo de desenvolvimento deve recriar os dados de teste com um seed, em vez de depender de persistência que a documentação não descreve.
A cobertura das APIs é baseada nos modelos publicados pela AWS, que também alimentam os SDKs. Quando uma operação está implementada, o emulador busca produzir o mesmo resultado e erro da AWS. Quando ainda não está, responde com HTTP 501 e o código NotImplemented. A fidelidade varia por serviço e entre operações de plano de controle e plano de dados.
As pontuações de fidelidade são publicadas a cada release no repositório aws/aws-emulator, no arquivo scores.json.gz. Consulte-as para verificar se o fluxo que você pretende testar está coberto. Essa checagem é importante porque o emulador não garante que todas as operações necessárias ao seu caso já estejam implementadas.
Pré-requisitos, instalação e assinatura
No Linux, o requisito descrito é um sistema de 64 bits, x86_64 ou aarch64, com glibc 2.17 ou posterior. O laboratório foi testado em Debian 13 x86_64 com glibc 2.41, Node.js 24.22.1 e AWS CLI 2.40.2. A versão testada do AWS Emulator foi 1.0.322, publicada em 10 de novembro de 2026 como pacote aws-emulator 1.0.322-1 no canal LTS/latest.
Para baixar no Debian ou Ubuntu, o guia fornece o comando abaixo, que busca o pacote do canal LTS/latest. A página oficial de versões descreve o padrão para escolher uma versão específica e consultar o arquivo versions.json. Fixar uma versão pode ajudar a repetir testes com resultados consistentes.
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
Antes de instalar, confira a assinatura publicada em um arquivo .sig ao lado do pacote e a chave pública disponível em https://downloads.aws.com/keys/gpg/current.asc. No laboratório, a chave ssm-publishing@amazon.com apresentou a impressão digital exigida pelo guia: 98BC F336 A3BE 53B7 34E9 67C5 2E5B F49B D940 F624. O GPG informou uma assinatura válida.
Também apareceu um aviso de que a chave não tem uma assinatura confiável. Segundo o guia, esse aviso pode ser ignorado depois de conferir a impressão digital. Se a verificação indicar BAD signature, não instale o pacote. Após verificar a assinatura, instale o arquivo baixado e confira a versão:
sudo apt-get install -y ./aws-emulator.deb aws-emulator -v
O emulador recebe atualizações muitas vezes ao dia. Se um patch mudar o resultado de um teste, a fidelidade pode ter se aproximado do comportamento da AWS ou pode haver um defeito a relatar. Considere a necessidade de repetibilidade junto com a recomendação de usar o release mais recente para obter correções de segurança, que são publicadas somente nele.
Iniciar o emulador e configurar o ambiente
O comando aws-emulator mantém o processo em primeiro plano e usa a porta 9297 por padrão. Se ela estiver ocupada, -p permite escolher outra porta; com -p 0, o sistema seleciona uma. No laboratório, o processo foi iniciado na porta 9400 com a telemetria desligada somente naquela execução.
aws-emulator -p 9400 --telemetry off
A telemetria vem ligada por padrão. O guia informa que ela não inclui o conteúdo dos pedidos, das respostas, do código nem das credenciais. É possível desativá-la com --telemetry off, EMULATOR_TELEMETRY=off ou pela configuração em config.toml. Para automação, o health check usa HTTPS e o certificado daquela execução. A resposta verificada no laboratório foi HTTP 200, com o corpo ok.
No shell da aplicação, configure o endpoint e os arquivos gerados pelo emulador, além das variáveis recomendadas para evitar chamadas inesperadas. Remova as credenciais reais do ambiente: valores como AWS_ACCESS_KEY_ID têm precedência sobre o arquivo de credenciais. A variável AWS_EC2_METADATA_DISABLED=true impede a busca de chaves nos metadados de uma instância EC2.
A variável AWS_DISABLE_HOST_PREFIX_INJECTION=true evita que a CLI e o Boto3 prefixem o host e enviem o pedido a um nome que não existe, como data-127.0.0.1. O bloco de variáveis da fonte está corrompido; por isso, não é reproduzido aqui. Mantenha o endpoint local explícito e confira a identidade antes de executar operações.
Para a AWS CLI, use AWS_CA_BUNDLE com o certificado. No Node.js, o SDK JavaScript v3 precisa também de NODE_EXTRA_CA_CERTS apontando para o mesmo arquivo ca.pem. A variável AWS_CA_BUNDLE não substitui essa configuração no Node.js, conforme a documentação do emulador.
Use 127.0.0.1 no endpoint, não localhost. Com o endereço IP, o SDK coloca o nome do bucket no caminho; com localhost, SDKs para JavaScript, Java e Go podem colocá-lo no host, formato que o emulador não aceita. Confira o destino com aws sts get-caller-identity: a conta esperada é 000000000000. Se aparecer sua conta real, as chamadas estão indo para a AWS.
Fluxo diário e configuração dos clientes
O fluxo de trabalho tem quatro etapas: iniciar o emulador e aguardar o health check; carregar as variáveis no shell e conferir a identidade; executar o seed para criar bucket, tabela e fila; e iniciar a API com tsx watch. Repita esse ciclo depois de reiniciar o emulador, pois os recursos somem com o processo. Reiniciar apenas a aplicação não apaga os recursos emulados.
O projeto de laboratório usa uma API Express na porta 3000, vinculada somente a 127.0.0.1, com rotas de saúde, pedidos no DynamoDB, recibos no S3 e mensagens SQS. As versões resolvidas em 12 de novembro de 2026 foram AWS SDK for JavaScript v3 3.1168.0, Express 5.3.0, TypeScript 7.0.2 e tsx 4.23.15. A compilação com tsc --noEmit terminou sem erros.
Definir o endpoint global não basta para os clientes do AWS SDK v3: cada um precisa de disableHostPrefix: true. O cliente SQS também requer useQueueUrlAsEndpoint: false. Sem essa opção, ele pode usar o host da URL retornada pela fila, em vez do endpoint local, e encaminhar uma solicitação para fora da máquina.
const sqs = new SQSClient({ region: config.region, disableHostPrefix: true, useQueueUrlAsEndpoint: false, });
No laboratório, a fila orders-demo retornou a URL https://sqs.us-east-1.amazonaws.com/000000000000/orders-demo. O SDK avisou que o host diferia do endpoint resolvido https://127.0.0.1:9400/ e que, por padrão, usaria o host da URL da fila. Isso mostra por que a configuração do cliente e uma proteção contra destinos inesperados são relevantes.
Com APP_TARGET=emulator, uma proteção adicional recusava qualquer solicitação cujo host não fosse 127.0.0.1. Em um teste propositalmente inseguro, o GetQueueUrl foi para o endereço local, mas o SendMessage usaria sqs.us-east-1.amazonaws.com; a proteção interrompeu o envio. Com a configuração indicada, o POST da API gravou no DynamoDB, enviou a mensagem e salvou o recibo no S3.
Seed: bucket, tabela e fila
O exemplo de criação de bucket do guia usa amzn-s3-demo-bucket, mas essa chamada falhou no laboratório com InvalidBucketName. As regras do S3 reservam o prefixo amzn-s3-demo-. O nome local-getting-started, usado no anúncio de lançamento da AWS, funcionou no teste.
Com esse bucket, o laboratório enviou 24 bytes com aws s3 cp, baixou o texto hello from the emulator e leu o mesmo conteúdo com GetObject. O resultado mostra que o seed precisa escolher nomes válidos, mesmo em um ambiente local, e que os comandos da CLI e o SDK podem ser usados para verificar o conteúdo criado.
O seed também precisa considerar a validação e o ciclo de vida da tabela no DynamoDB. O nome curto de tabela ab, usado no exemplo oficial, foi recusado com ValidationException, como esperado. Outra falha observada ocorreu quando PutItem foi chamado antes de a tabela chegar ao estado ACTIVE; aguarde esse estado antes de inserir os dados de teste.
Essas verificações tornam o seed uma parte importante da rotina, não apenas uma conveniência. Ele deve criar recursos válidos e inserir dados somente quando a tabela estiver pronta. Como o estado permanece apenas em memória, repetir esse processo depois de cada inicialização ajuda a manter o ambiente local previsível.
Limites e uso responsável
O AWS Emulator é voltado à construção e aos testes locais, não à produção nem à validação de segurança. A cobertura varia conforme o serviço e também entre operações de plano de controle e de dados. Consulte as pontuações publicadas em cada release antes de confiar no emulador para um fluxo específico.
O processo gera credenciais novas a cada execução, e os recursos desaparecem quando ele é encerrado. Por isso, mantenha o endpoint explícito, retire credenciais reais do shell usado pelos testes e confirme a identidade antes de executar operações. Essas precauções ajudam a impedir que um erro de configuração direcione chamadas locais para uma conta AWS real.
Apoie o Guia de TI
Compartilhar
Autor
Comentários
0Comece a conversa.
Seja a primeira pessoa a comentar este conteúdo.