Skip to content

About

User registration service with welcome email delivery via AWS SES, using the Transactional Outbox Pattern with Debezium (CDC) to ensure consistent delivery without double writing.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Outbox Notifier

Serviço de cadastro de usuários com envio de e-mail de boas-vindas, construído sobre o Transactional Outbox Pattern para garantir entrega consistente do e-mail sem depender de transações distribuídas entre banco de dados e AWS.

Stack:

  • Java 21
  • Spring Boot 3 (Web, Data JPA, Validation)
  • PostgreSQL
  • Debezium (Embedded Engine) para CDC — Change Data Capture
  • AWS SES para o envio do e-mail de boas-vindas
  • Lombok

O caso de uso é simples: ao cadastrar um usuário, o sistema precisa enviar um e-mail de boas-vindas. O ponto central deste serviço é como essa notificação é entregue de forma confiável, resolvendo o problema da dupla escrita (dual write problem) que aparece sempre que uma mesma operação de negócio precisa atualizar o banco de dados e chamar um serviço externo (aqui, o SES).

O problema: dual write

Uma implementação "ingênua" do cadastro de usuário faria algo assim:

userRepository.save(user);      // 1) grava no Postgres
sesClient.sendEmail(...);       // 2) chama a AWS diretamente

O problema é que são duas operações contra dois sistemas diferentes, sem nenhuma garantia atômica entre elas:

  • Se o processo cair, ou a rede falhar, ou o SES estiver fora do ar depois do passo 1 e antes/durante o passo 2, o usuário fica cadastrado e nunca recebe o e-mail — e não há como saber que isso aconteceu, pois do ponto de vista do banco a transação foi um sucesso.
  • Se você inverter a ordem (enviar o e-mail primeiro), corre o risco inverso: o usuário recebe o e-mail de boas-vindas para um cadastro que acabou não sendo persistido (ex.: violação de constraint, rollback etc.).

Não existe transação distribuída de verdade entre "commit no Postgres" e "chamada HTTP para a AWS" — por isso o nome dual write: duas escritas que deveriam ser atômicas, mas não são.

A solução: Transactional Outbox Pattern

Em vez de chamar o SES diretamente dentro da mesma requisição, o serviço grava dois registros na mesma transação de banco de dados:

  1. a linha na tabela users;
  2. um "evento" na tabela outbox_users, descrevendo o que precisa acontecer depois (NEW_USER_REGISTERED, com o payload necessário para montar o e-mail).
@Transactional
public User registerUser(CreateUserRequest request) {
    User user = userRepository.save(...);
    outboxEventRepository.save(outboxEvent); // mesma transação
    return user;
}

Como as duas tabelas fazem parte da mesma transação do Postgres, ou as duas linhas existem, ou nenhuma existe — a atomicidade que faltava entre "banco" e "efeito colateral" passa a existir entre "banco" e "banco".

O envio do e-mail em si deixa de ser responsabilidade da requisição HTTP. Quem cuida disso é um processo assíncrono e desacoplado, que só existe depois que a transação já foi confirmada com sucesso:

Service --> Postgres (transação: INSERT users + INSERT outbox_users)
                 |
                 v
        WAL (write-ahead log)
                 |
                 v
      Debezium (lê o WAL via replicação lógica)
                 |
                 v
        Outbox Consumer (nossa aplicação)
                 |
                 v
             AWS SES --> e-mail entregue

Por que Debezium (CDC) em vez de um SELECT com polling?

Uma alternativa mais simples seria ter um job que faz SELECT * FROM outbox_users WHERE status = 'PENDING' de tempos em tempos. Funciona, mas tem dois problemas: gera carga extra no banco o tempo todo (mesmo quando não há nada novo) e introduz atraso proporcional ao intervalo do polling.

O Debezium, em vez de "perguntar" ao banco se há novidade, se conecta como um réplica lógica do Postgres e é notificado assim que uma transação com um INSERT em outbox_users é confirmada — sem select, sem polling, com latência mínima. Ele lê diretamente o WAL (write-ahead log), o mesmo mecanismo que o Postgres usa para replicação física.

Neste serviço o Debezium roda como uma Embedded Engine — ou seja, dentro do próprio processo Java, sem precisar de Kafka Connect nem de um broker de mensagens dedicado (classe OutboxDebeziumConsumer).

Escopo atual x evolução recomendada

A versão atual roda com Debezium Embedded Engine no mesmo processo da API, o que já resolve o problema de dupla escrita e atende bem a um volume moderado de eventos. Para cargas maiores ou múltiplos serviços consumindo os mesmos eventos, a evolução natural é:

Atual Próximo passo
Debezium Embedded Engine, no mesmo processo da API Debezium Server ou Kafka Connect, publicando em um tópico Kafka
Consumidor chama o SES diretamente ao receber o evento Serviço consumidor dedicado, lendo do Kafka, desacoplado da API
Offset da leitura salvo em arquivo local (outbox-offsets.dat) Offset gerenciado pelo próprio Kafka Connect / tópico de offsets
Sem deduplicação explícita de e-mail enviado Consumidor idempotente (chave de deduplicação, tabela de eventos já processados)

Vale reforçar: o Debezium entrega os eventos com garantia at-least-once (pelo menos uma vez) — ou seja, o mesmo evento pode, em cenários de falha e reprocessamento, ser entregue mais de uma vez. Por isso o consumidor deve ser tratado como idempotente (checar se aquele outbox_id já foi processado antes de reenviar o e-mail). O campo status da tabela outbox_users já dá a base para essa checagem.

Estrutura do projeto

outbox-notifier/
├── docker-compose.yml          # sobe só o Postgres (wal_level=logical)
├── postgres/init.sql           # cria as tabelas users e outbox_users
├── pom.xml
└── src/main/
    ├── resources/application.yml
    └── java/com/example/outbox/
        ├── OutboxDemoApplication.java
        ├── config/
        │   ├── SecurityBeansConfig.java   # bean do PasswordEncoder
        │   └── AwsSesConfig.java          # SesClient apontando pro LocalStack
        ├── domain/
        │   ├── User.java
        │   └── OutboxEvent.java           # mapeia outbox_users
        ├── repository/
        │   ├── UserRepository.java
        │   └── OutboxEventRepository.java
        ├── dto/CreateUserRequest.java
        ├── service/UserService.java       # @Transactional: grava user + outbox juntos
        ├── controller/UserController.java # POST /api/users
        └── outbox/
            ├── OutboxDebeziumConsumer.java # lê o WAL via Debezium Embedded Engine
            └── WelcomeEmailSender.java     # envia o e-mail via SES

Pré-requisitos

  • JDK 21
  • Docker e docker-compose
  • Uma IDE com suporte a Maven (IntelliJ IDEA, por exemplo)
  • Credenciais AWS com permissão de uso do SES (ou LocalStack, em ambiente local)

Ambiente local de desenvolvimento

Para desenvolver e validar o fluxo sem depender de custos ou limites reais do SES, use o LocalStack como substituto local da AWS — é o que o application.yml já assume por padrão (aws.ses.endpoint: http://localhost:4566, credenciais fake test/test).

1. Subir o Postgres

Na raiz do projeto:

docker-compose up -d

Isso cria o container outbox-postgres, já com wal_level=logical e as tabelas users e outbox_users (via postgres/init.sql).

2. Verificar o e-mail remetente no LocalStack

awslocal ses verify-email-identity --email-address no-reply@outbox-demo.com

3. Rodar a aplicação

Abra o projeto na sua IDE (pom.xml como projeto Maven), deixe o Maven baixar as dependências e rode a classe OutboxDemoApplication.

Ao subir, além do Spring Boot, a OutboxDebeziumConsumer inicializa a engine do Debezium e começa a observar public.outbox_users.

4. Validar o fluxo completo

Cadastre um usuário:

curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Joao Silva","email":"joao@gmail.com","password":"123456"}'

O que deve acontecer, em sequência:

  1. A API responde 201 Created com o usuário criado.
  2. Nos logs da aplicação: Usuário X e evento de outbox gravados na mesma transação.
  3. Alguns instantes depois (assíncrono): Evento de outbox capturado: ... e E-mail de boas-vindas enviado para joao@gmail.com.
  4. Consultando o Postgres, a linha em outbox_users estará com status = 'SENT'.

Executando contra a AWS real

Para apontar para o SES de verdade, basta sobrescrever as propriedades de aws.* (via variáveis de ambiente, application-prod.yml ou secrets do seu orquestrador — nunca comitando credenciais):

aws:
  region: us-east-1
  ses:
    endpoint: https://email.us-east-1.amazonaws.com
    sender: no-reply@seudominio.com

Pontos de atenção antes de ir para produção:

  • Credenciais: troque StaticCredentialsProvider (usado hoje para simplificar o dev local) por DefaultCredentialsProvider, permitindo o uso de IAM Role da instância/task em vez de chaves fixas.
  • Verificação de domínio: no SES real, verifique o domínio remetente (ou o endereço específico) e, se a conta estiver em sandbox do SES, solicite a saída do sandbox para poder enviar a qualquer destinatário.
  • Réplica lógica no Postgres gerenciado: se o banco for RDS/Aurora, confirme que rds.logical_replication está habilitado e que o usuário de conexão tem permissão de replicação.

Observações sobre o schema

  • outbox_users está com REPLICA IDENTITY FULL: isso instrui o Postgres a incluir a linha inteira nos eventos de WAL — prática recomendada pela documentação do Debezium para tabelas de outbox.
  • O ddl-auto do Hibernate está como none de propósito: quem define o schema é o postgres/init.sql, garantindo que a configuração de replicação da tabela não seja perdida numa recriação automática.

About

User registration service with welcome email delivery via AWS SES, using the Transactional Outbox Pattern with Debezium (CDC) to ensure consistent delivery without double writing.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages