Ambassador

Um proxy ao lado do serviço cuida das chamadas de saída: injeta credencial, aplica timeout, repete tentativas com segurança e isola o destino que está falhando. O serviço chama localhost como se fosse o destino e não tem uma linha de retry ou autenticação. Aqui o ambassador é um Envoy, como em produção. Use quando vários serviços falam com os mesmos destinos externos e a resiliência não deve ser reimplementada em cada um.

passos: 6
arquivos: 4
testes: 0
tecnologias: 5

Infraestrutura realTypeScriptBunElysiaEnvoyDocker

Cenário Relações Comparar

Baixar cartão

Cenário

O serviço de pagamentos liquida TEDs no BACEN e registra na câmara. O BACEN falha às vezes na primeira tentativa, exige token e, num incidente, sai do ar. O serviço não sabe nada disso: o Envoy ao lado dele resolve credencial, retry, prazo e isolamento do destino.

Planta

Sequência

9/9

9 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num participante para focar
Outras plantas de sequência

Como funciona

6 passos

Cliente remoto encapsulado em proxy.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

x-request-id+2

request_headers_to_add+1

Ambassador

retry_policy+1

Ambassador

outlier_detection+1

Ambassador

/stats+1

Service Mesh

01
O serviço chama http://localhost:10000/bacen/...; o Envoy reescreve o caminho e envia ao destino real
02
request_headers_to_add injeta o Authorization de cada destino — a credencial nunca passa pelo código do serviço
03
retry_policy repete em 5xx, reset e falha de conexão (2 retries, 1 s por tentativa, 3 s no total); o x-request-id gerado pelo Envoy é o mesmo em toda tentativa, e o destino liquida uma vez só
04
outlier_detection ejeta o destino após 3 respostas 5xx seguidas; com o pânico desligado, o Envoy responde no healthy upstream em ~1 ms em vez de esperar
05
Os contadores de retry, timeout e ejeção ficam no admin do Envoy (/stats), não no serviço
06
Os destinos (BACEN e câmara) são simulados em Elysia no host; o Envoy os alcança por host.docker.internal

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Resiliência e credencial fora do código, iguais para todo serviço
Configuração declarativa, trocável sem redeploy do serviço
Retry seguro com id de requisição estável
Destino falhando isolado sem derrubar o chamador

Custos

Um processo a mais por serviço para operar
Salto extra em localhost em toda chamada
Retry só é seguro se o destino deduplica pelo id
Comportamento espalhado entre código e YAML exige documentação

apps/service-design/ambassador

4 arquivos

envoy/

envoy.yamlinfraO ambassador: rotas, credencial, retry, timeout, ejeção

src/

service_payments.tsServiço de pagamentos — só chama o localhost
destination_external.tsBACEN e câmara simulados: token, idempotência por x-request-id, plano de falhas
stats_envoy.tsLeitura dos contadores do admin do Envoy

Executar · com Docker