Falcon: O Chassi Por Trás de Cada Serviço da Xeni

Antes que um microsserviço possa fazer algo útil, ele precisa fazer as mesmas dezena de coisas que todo outro serviço já faz: ler configuração, autenticar o chamador, acessar um banco de dados, cachear um resultado, publicar um evento, buscar um segredo, emitir métricas e logs. Escrito uma vez por serviço, essa infraestrutura básica é duplicada, se desvia e envelhece mal.

A resposta da Xeni é o Falcon — um framework interno em Go sobre o qual cada serviço backend é construído. O Falcon cuida da infraestrutura para que cada serviço cuide apenas do seu domínio. É a razão pela qual uma equipe pequena pode operar muitos serviços sem montar um grupo de plataforma atrás de cada um.

Esta publicação é um tour do que o Falcon faz, como ele é montado e as compensações que assumimos para construir uma base compartilhada em vez de muitas sob medida.

O custo de não ter um

Escrito uma vez por serviço, essa mesma infraestrutura é duplicada e silenciosamente se desvia. Sem um chassi compartilhado, esses custos se repetem em cada serviço:

O Falcon existe para que equipes de produto escrevam lógica de domínio, enquanto a plataforma cuida da correção de infraestrutura uma vez — versionada, testada e reutilizada em todos os lugares.

Um chassi, cada serviço

A plataforma não é nem um monolito nem um conjunto disperso de apps não relacionados. Cada vertical de produto e cada serviço de suporte — supply, payments, identity, AI — é um serviço separado construído no mesmo chassi Falcon. Novos produtos e capacidades são aditivos: herdam a fundação em vez de reconstruí-la.

O mesmo vale em toda a frota. Além dos produtos, a plataforma em si roda no Falcon — identity, configuration, accounts, reporting, operator tooling, payments, subscriptions, data migration, notifications, AI — e, para cada vertical, serviços de agregação que unificam dezenas de serviços conector de provedores. Cada um deles é um serviço Falcon no mesmo chassi:

Uma chamada, e a infraestrutura básica está pronta

Um novo serviço Falcon começa com quase nenhum código de infraestrutura. Você cria o servidor, registra as rotas e entrega o controle ao framework:

As rotas ficam em um routers.go — um único falcon.Add por endpoint, declarando o método, versão da API, caminho, os papéis permitidos para chamá-lo, o corpo da solicitação para vincular e validar, e o handler. O main.go quase não faz nada: criar o servidor, registrar as rotas e voar.

Cada handler tem a mesma assinatura — func(ctx) (interface{}, *APIError) — para que o framework possa centralizar serialização, mapeamento de erro para HTTP, recuperação de pânico, propagação de request-id e correlação, e negociação de conteúdo. Tudo que um handler precisa — configuração, clientes de banco de dados e cache, clientes de saída — fica no context da solicitação, recuperado com helpers server.Get*(ctx) em vez de passado manualmente. O handler em si não faz o trabalho inline; compõe a solicitação a partir de workers pequenos e independentes — onde vive a lógica de domínio real.

Do lado do engenheiro de produto, isso torna uma nova funcionalidade uma checklist curta e previsível:

1. 01Defina o modelo de solicitação — o Falcon vincula e valida a partir do corpo.
2. 02Adicione uma linha de rota em routers.go — método, versão, caminho, papéis, corpo, handler.
3. 03Escreva um handler fino que compõe um fluxo de trabalho.
4. 04Escreva os workers — unidades pequenas e independentes de lógica de domínio (um validator, uma policy, os passos).
5. 05Conecte qualquer dependência nova — um banco de dados, cache ou serviço de saída — via config, não código.

Todo o resto — autenticação, autorização, logging estruturado, métricas, tracing, IDs de correlação, envelopes de erro, serialização, recuperação de pânico, e endpoints de health / metrics — o framework já cuida. Essa é a habilitação: um engenheiro gasta seu tempo na funcionalidade, não na infraestrutura básica.

Trabalho em background é igualmente leve: falcon.AddBatch(name, fn) registra um job de inicialização que roda em sua própria goroutine — a mesma fiação, sem uma rota HTTP.

Config é a fiação

O Falcon é orientado por configuração. Quase toda capacidade — um banco de dados, um cache, um cliente HTTP de saída, um stream, um provedor de nuvem — é instanciada a partir de um group de config nomeado com um tipo declarado. Adicionar uma dependência downstream é uma mudança de configuração, não código novo.

A configuração é um formato plano de chaves com pontos — <service>.<group>.<key>=<value> — carregado de um arquivo local ou de um serviço de config central (autenticado com um token de serviço a serviço). O Falcon descobre groups por esse segmento do meio, que é como um único serviço pode conectar vários bancos de dados tipados (por exemplo groups separados tenantdb e coredb), múltiplos streams ou muitos clientes de saída puramente via config. Getters tipados retornam valores com defaults sensatos, para que o mesmo binário se comporte corretamente em cada ambiente — e operadores podem até alterar a verbosidade de logs em tempo de execução com PUT /loglevel/:level, sem reinício necessário.

Baterias incluídas

O Falcon inclui a infraestrutura que um serviço em produção precisa, cada peça atrás de uma interface limpa:

Nada disso é novo por si só — o valor é que é uniforme. Cada serviço acessa um banco de dados, emite uma métrica ou assina um payload da mesma forma, para que um engenheiro que trabalhou em um serviço Falcon seja imediatamente produtivo no próximo.

Também é opt-in: cada capacidade é ativada por serviço na configuração (falcon.<feature>.enabled=true), para que um serviço enxuto carregue apenas o que realmente usa e não pague nada pelo resto.

Como uma solicitação flui

De ponta a ponta, cada solicitação passa pelas mesmas etapas ordenadas, para que o comportamento seja previsível independentemente de qual serviço a trata:

1. 01Ingress. A cadeia de middleware carimba um request e correlation ID e aplica timeout, métricas e CORS.
2. 02Autenticar. O token do chamador é validado — um token OAuth Bearer verificado contra um serviço de auth central, ou um JWT verificado localmente — e seus scopes são extraídos.
3. 03Autorizar. Uma verificação multi-estratégia resolve identidade e permissões do chamador, com buscas de política por tenant cacheadas no Redis — a Xeni está consolidando essas estratégias no IDAM.
4. 04Montar contexto. O context limitado à solicitação é enriquecido com config, clientes de banco de dados e cache, clientes de saída, identidade de tenant e usuário, e IDs de correlação.
5. 05Tratar. O handler de produto roda — tipicamente compondo o pipeline de fluxo de trabalho abaixo.
6. 06Responder. A saída é negociada por conteúdo — JSON por padrão, HTML e PDF para documentos voltados a humanos, e bytes brutos para arquivos — com formatação automática de envelope de erro. Respostas streaming (SSE, NDJSON) estão no roadmap; XML permanece disponível para consumidores legacy.
7. 07Auditar. Eventos de solicitação e fluxo de trabalho, com campos sensíveis mascarados, são publicados no stream de notificações.

Cada solicitação roda a mesma forma

Serviços Falcon tratam solicitações como um pipeline explícito em vez de um emaranhado de código de handler:

Um handler compõe esse pipeline como uma cadeia fluente — o motor de fluxos de trabalho do Falcon:

Seu verdadeiro poder é que workers são unidades de trabalho independentes. Cada um implementa uma interface pequena — IsEligible, Skip e Execute — e o mesmo worker pode ser composto em diferentes fluxos de trabalho para resolver diferentes necessidades de negócio. Um worker Payment escrito uma vez é reutilizado em uma reserva, um reembolso e uma renovação de assinatura; um validator ou fraud policy encaixa em qualquer fluxo que precise dele.

O motor encadeia as saídas dos workers, rastreia status por tarefa em um WorkFlowStatus, emite um evento de fluxo de trabalho a cada passo e roteia qualquer falha para o ErrorHandler registrado — dando a cada serviço estrutura de handler consistente e lógica de negócio observável, testável e composável.

É o mesmo padrão por trás do serviço de identidade da Xeni: uma nova capacidade é questão de escrever um worker e conectar uma rota.

Troque o fornecedor, não o código

Como as tecnologias de suporte ficam atrás de interfaces, elas podem mudar sem tocar o código de produto. O provedor de nuvem (AWS ou GCP), o cache (Redis ou DAX) e a espinha dorsal de streaming (Kafka, Kinesis ou Pub/Sub) são selecionados por configuração e resolvidos por uma factory. Uma troca de fornecedor acontece dentro do framework.

O efeito estratégico se compõe: um novo serviço começa com zero código de infraestrutura, e o custo marginal do próximo serviço — e do próximo fornecedor, mercado ou produto — continua caindo à medida que o framework absorve mais do trabalho comum.

Um padrão, serviços de propriedade cruzada

Infraestrutura básica comum é apenas metade do que o Falcon compra. A outra metade é disciplina: porque o framework fixa a forma de um serviço — um contrato de handler, um pipeline de solicitações, uma forma de alcançar cada dependência, um modelo de erro e logging — cada serviço acaba parecendo com todos os outros.

Essa uniformidade muda como a equipe trabalha. Engenheiros não ficam isolados no serviço que aconteceu de construir; qualquer um que conhece um serviço Falcon pode ler, estender e depurar o próximo. Serviços são de propriedade cruzada em vez de guardados — o que espalha conhecimento, remove pontos únicos de falha na equipe e encurta a integração para dias.

Isso importa mais quando algo quebra. Os mesmos logs, as mesmas métricas e as mesmas etapas de pipeline em cada serviço significam que quem estiver de plantão pode se orientar dentro de um serviço desconhecido e consertá-lo rapidamente — troubleshooting ao vivo não espera a única pessoa que o escreveu. Infraestrutura básica compartilhada mais padrões aplicados transformam "quem é o dono disso?" em "qualquer um de nós pode."

O resultado é alavancagem: uma equipe pequena constrói e opera uma plataforma ampla, e a relação de serviços por engenheiro continua melhorando à medida que o framework absorve mais do trabalho comum.

As compensações que assumimos

Uma fundação compartilhada é uma aposta deliberada, e não é de graça:

• Risco concentrado. Um bug no Falcon pode alcançar cada serviço de uma vez. Isso eleva o padrão: o framework carrega um padrão mais alto de revisão, testes e versionamento cuidadoso do que qualquer serviço individual.
• Exige profundidade. O Falcon precisa de expertise real em Go e uma equipe que trate o framework como um produto com seu próprio roadmap — não um projeto paralelo.
• Precisa estar à frente. O framework deve antecipar o que equipes de produto precisarão em seguida; quando fica para trás, cada equipe sente a fricção.

Assumimos isso porque a alternativa é pior. Deixar cada equipe re-resolver configuração, auth, acesso a dados e observabilidade produz entregas mais lentas, comportamento inconsistente e uma postura de segurança impossível de raciocinar uniformemente. Centralizar as partes difíceis é o que permite ao resto se mover rápido.

Por que se sustenta

1. 01Isolar infraestrutura do produto. Um serviço deve conter lógica de domínio e pouco mais.
2. 02Fazer cada serviço parecer igual. Um contrato de handler, um pipeline de solicitações, uma forma de alcançar cada dependência.
3. 03Colocar topologia na configuração. Adicionar um banco de dados ou um cliente downstream é uma mudança de config, não uma reescrita.
4. 04Esconder fornecedores atrás de ports. Nuvem, cache e streaming podem mudar sem o código de produto perceber.
5. 05Tratar o framework como produto. Aceitar o risco concentrado e pagá-lo com revisão, testes e versionamento.

Valor estratégico em resumo

Recuando da mecânica, o benefício de negócio é direto:

Encerramento

O Falcon é fácil de subestimar porque, quando funciona, você não o vê: serviços simplesmente começam com a infraestrutura básica já resolvida. Mas é a razão silenciosa pela qual a Xeni pode operar uma plataforma ampla — identity, payments, search e as verticais de produto — em um chassi comum em vez de uma pilha de soluções únicas.

Em termos simples, o Falcon é o tecido conectivo da plataforma: transforma o que de outra forma seriam dezenas de decisões de infraestrutura independentes por serviço em um contrato único, versionado e orientado por config. Por isso o tratamos como um produto interno de primeira classe — com maintainers dedicados, uma cadência de release estável e uma política clara de depreciação para caminhos legacy — não uma utilidade compartilhada que ninguém possui.

O framework é a alavancagem: resolver infraestrutura uma vez e herdá-la em todos os lugares. O exemplo mais claro de um serviço construído inteiramente sobre essa alavancagem é a camada de identidade da Xeni — o assunto da publicação complementar, Dentro do IDAM.