Serviço de carteira para provedores de jogos: processa BET, WIN, LOSS,
REFUND e ROLLBACK por HTTP e por SQS, com as mesmas garantias financeiras
nas duas entradas.
Go 1.27 · Uber Fx · PostgreSQL · AWS SQS (LocalStack) · Keycloak
Precisa de Docker e Go 1.27. Nada mais.
docker compose up -d --build # ~1 min: Postgres, LocalStack, Keycloak e 3 instâncias
make verificar # ~2 min: roda os 284 testes e confere o enunciadoO segundo comando percorre as exigências do desafio e imprime a evidência de cada uma — o teste que passou, a constraint que existe no banco, a rota que recusa, a integridade dos dados naquele instante. Nada ali é afirmação: são comandos executados na hora.
A saída termina assim:
OS 8 CENÁRIOS OBRIGATÓRIOS
✓ 1 · mesma aposta 50x em paralelo (TestCinquentaEnviosDaMesmaApostaDebitamUmaVez)
✓ 2 · 100.00 com duas apostas de 80.00 (TestDuasApostasDisputandoOMesmoSaldo)
…
RESULTADO
40 verificações OK, 0 falharam
Tudo confere.
Se alguma linha vier com ✗, ela diz qual teste falhou ou não foi executado —
um teste ausente conta como falha, porque um cenário obrigatório que não
roda não prova nada.
Ao terminar:
docker compose down -vRodar as suítes separadamente
make test # 235 unitários, sem dependência externa
make race # os mesmos com -race
make test-integration # 23, contra PostgreSQL real
make test-e2e # 26, contra as 3 instâncias com Keycloak real
make test-all # tudo acimamake verificar já executa todas elas — estes alvos servem para isolar uma
suíte durante o desenvolvimento.
- Docker e Docker Compose
- Go 1.27 (só para rodar os testes fora do container)
cp .env.example .env # opcional: o compose já traz os valores locais
docker compose up --buildIsso sobe PostgreSQL, LocalStack, Keycloak e três instâncias do serviço atrás do mesmo banco. As migrations rodam num serviço à parte, como dono do schema; as filas e o realm do Keycloak são provisionados automaticamente.
| Serviço | Endereço |
|---|---|
| app-1 | http://localhost:8080 |
| app-2 | http://localhost:8082 |
| app-3 | http://localhost:8083 |
| Keycloak | http://localhost:8081 (admin/admin) |
| PostgreSQL | localhost:5432 (wallet/dev) |
| LocalStack | http://localhost:4566 |
Três instâncias não é enfeite: o enunciado pede que as garantias sejam demonstradas com pelo menos três processos independentes, e é contra elas que os testes e2e rodam.
docker compose down -v # -v também apaga o volume do PostgresVersionadas em internal/adapter/postgres/migrations/, com aplicação e
reversão separadas.
O docker compose up já aplica as migrations nos dois bancos (wallet e
wallet_test) antes de as instâncias subirem. Para exercitá-las à mão:
make migrate-up # banco wallet
make migrate-up DB=wallet_test # banco dos testes
make migrate-down # reverte — pede confirmação, apaga os dadosOu direto, contra qualquer Postgres:
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
-f internal/adapter/postgres/migrations/000001_init.up.sql
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 \
-f internal/adapter/postgres/migrations/000001_init.down.sqlA reversão derruba tabelas, funções e triggers. Com as instâncias no ar, elas
passam a errar até um migrate-up — que é o comportamento esperado de uma
reversão, não um defeito.
A reversão derruba as tabelas e funções, mas não remove o papel
wallet_app: papéis são do cluster inteiro e podem ser compartilhados. Para
removê-lo: DROP ROLE wallet_app;.
Keycloak, realm wallet, fluxo client_credentials. Provisionado por
deploy/keycloak/realm-wallet.json — não há passo manual.
| Client | Secret | Papel |
|---|---|---|
provider-a |
provider-a-secret |
provedor de jogos |
provider-b |
provider-b-secret |
provedor de jogos |
internal-wallet-service |
internal-secret |
serviço interno |
Obter um token:
TOKEN=$(curl -s -X POST \
http://localhost:8081/realms/wallet/protocol/openid-connect/token \
-d grant_type=client_credentials \
-d client_id=provider-a \
-d client_secret=provider-a-secret | jq -r .access_token)A identidade manda sobre o corpo. O providerId da requisição é conferido
contra o claim provider_id do token; divergência é 403. Um provedor não lê
nem escreve nada de outro, inclusive em replay.
Toda rota de carteira exige o escopo wallets:write, que só o cliente
interno tem — inclusive as de leitura. Uma carteira pode ser movimentada por
vários provedores, e o ledger traz valor e identificador das operações de
todos: aberto, mostraria a um provedor quanto o jogador apostou no
concorrente. O provedor continua vendo o saldo das próprias operações, que
vem na resposta de cada uma.
INTERNO=$(curl -s -X POST \
http://localhost:8081/realms/wallet/protocol/openid-connect/token \
-d grant_type=client_credentials \
-d client_id=internal-wallet-service \
-d client_secret=internal-secret | jq -r .access_token)
curl -X POST http://localhost:8080/wallets \
-H "Authorization: Bearer $INTERNO" \
-H 'Content-Type: application/json' \
-d '{
"playerId": "0192f28f-5dc0-7d58-bdb2-814ad6a0f4a1",
"initialBalance": { "amount": "1000.00", "currency": "BRL" }
}'curl -X POST http://localhost:8080/wagering/transactions \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: provider-a:transaction-123' \
-d '{
"providerId": "provider-a",
"externalTransactionId": "transaction-123",
"playerId": "0192f28f-5dc0-7d58-bdb2-814ad6a0f4a1",
"walletId": "0192f291-27dd-7d3f-8071-5f8685deef37",
"roundId": "round-987",
"gameId": "fortune-chimp",
"kind": "BET",
"money": { "amount": "25.00", "currency": "BRL" }
}'aws --endpoint-url http://localhost:4566 sqs send-message \
--queue-url http://localhost:4566/000000000000/wager-transactions.fifo \
--message-group-id 0192f291-27dd-7d3f-8071-5f8685deef37 \
--message-deduplication-id msg-123 \
--message-body '{
"messageId": "msg-123",
"type": "WagerTransactionRequested",
"occurredAt": "2026-09-23T12:00:00Z",
"data": {
"providerId": "provider-a",
"externalTransactionId": "transaction-124",
"idempotencyKey": "provider-a:transaction-124",
"playerId": "0192f28f-5dc0-7d58-bdb2-814ad6a0f4a1",
"walletId": "0192f291-27dd-7d3f-8071-5f8685deef37",
"roundId": "round-987",
"gameId": "fortune-chimp",
"kind": "BET",
"money": { "amount": "25.00", "currency": "BRL" }
}
}'curl -X POST http://localhost:8080/wallets/$WALLET/reconciliation \
-H "Authorization: Bearer $TOKEN"| Método | Rota | Acesso |
|---|---|---|
POST |
/wallets |
interno |
GET |
/wallets/{walletId} |
interno |
GET |
/wallets/{walletId}/ledger?cursor=&limit= |
interno |
POST |
/wallets/{walletId}/reconciliation |
interno |
POST |
/wagering/transactions |
provedor |
GET |
/wagering/transactions/{transactionId} |
dono da transação |
GET |
/providers/{providerId}/wagering/transactions/{externalTransactionId} |
o próprio provedor |
GET |
/health/live · /health/ready |
público |
GET |
/metrics |
público |
As quatro situações que precisam ser distinguíveis têm código próprio:
| Situação | HTTP | code |
|---|---|---|
| Sucesso | 200 | — |
| Carteira criada | 201 | — |
| Aceito, esperando referência | 202 | — |
| Entrada inválida | 400 | INVALID_REQUEST |
| Sem credencial ou credencial inválida | 401 | UNAUTHENTICATED |
| Provedor sem permissão | 403 | FORBIDDEN |
| Não encontrado | 404 | NOT_FOUND |
| Chave reutilizada com outro conteúdo | 409 | IDEMPOTENCY_CONFLICT |
| Operação já registrada com outra chave | 409 | DUPLICATE_EXTERNAL_TRANSACTION |
| Rejeição de negócio | 422 | ver failureCode |
| Conflito de concorrência persistente | 503 | CONCURRENCY_CONFLICT |
| Dependência indisponível | 503 | DEPENDENCY_UNAVAILABLE |
Rejeição de negócio é 422, não 400 nem 500: o pedido foi entendido e
processado, e a recusa ficou registrada e auditável. Respostas 503 trazem
Retry-After.
| Código | Significado | Corrigível? |
|---|---|---|
INSUFFICIENT_FUNDS |
aposta não cabe no saldo | sim, com mais saldo |
REVERSAL_INSUFFICIENT_FUNDS |
reversão debitaria além do saldo | incidente operacional |
REFERENCE_NOT_FOUND |
referência não chegou no prazo | não |
REFERENCE_NOT_PROCESSED |
referência terminou sem sucesso | não |
REFERENCE_MISMATCH |
referência de outro contexto | não |
REFERENCE_KIND_INVALID |
tipo referenciado não admite a reversão | não |
ALREADY_REVERSED |
referência já revertida uma vez | não |
REVERSAL_AMOUNT_MISMATCH |
reversão parcial, fora do escopo | sim |
CURRENCY_MISMATCH |
moeda diferente da carteira | sim |
INVALID_AMOUNT |
valor fora da política do tipo | sim |
INTERNAL_FAILURE |
falha permanente de infraestrutura | não |
INSUFFICIENT_FUNDS e REVERSAL_INSUFFICIENT_FUNDS são separados
deliberadamente: o primeiro é o jogador sem dinheiro, rotina; o segundo é
dinheiro que já saiu da carteira, que é incidente.
Para apenas avaliar, use make verificar (veja o topo). Esta seção detalha o
que cada suíte cobre.
docker compose up -d --build # já cria o banco `wallet_test`
go test -race -tags integration ./test/integration/Os testes usam o banco wallet_test, separado do wallet das instâncias.
A separação importa: compartilhando o banco, os relays de outbox das
instâncias em execução publicariam os eventos que o teste acabou de criar,
antes de o teste poder observá-los. Aponte para outro lugar com
TEST_DATABASE_URL.
docker compose up -d --build
go test -tags e2e ./test/e2e/ -v -timeout 20mmake test-all # vet + unitários + -race + integração + e2emake verificarPercorre as exigências do desafio uma a uma e imprime a evidência de cada uma — o teste que roda, a constraint que existe, a rota que recusa. Nada é afirmação: tudo é comando executado na hora.
ELIMINATÓRIOS
✓ dinheiro nunca passa por float (varredura da AST)
✓ idempotência sobrevive ao reinício dos processos
✓ provedor não navega em carteira alheia
…
INVARIANTES IMPOSTAS PELO BANCO
✓ ledger é append-only (triggers)
✓ runtime sem UPDATE no ledger
…
40 verificações OK, 0 falharam
Os testes e2e usam as três instâncias e tokens reais do Keycloak.
Alguns deles derrubam e reiniciam containers de propósito (os cenários de
recuperação), e um espera até 90 s — mais que o VisibilityTimeout de 60 s da
fila, porque depois de matar uma instância as mensagens que ela tinha em mãos
só voltam a ficar visíveis quando esse prazo expira. Use -short para pular os
que mexem nos containers.
Total: 235 unitários · 23 de integração · 26 ponta a ponta = 284. Nenhum é pulado quando o ambiente está de pé: um cenário obrigatório pulando em silêncio passaria por aprovado sem nunca ter rodado, então o teste falha em vez de pular.
Todo pacote tem teste dedicado, menos internal/bootstrap — que é a
composição do Fx, exercitada de verdade por TestComposicaoFxIniciaEEncerra
no e2e, onde a aplicação inteira é montada, iniciada e encerrada.
A cobertura por linha é baixa em postgres, sqs e worker de propósito: o
que eles têm é SQL e chamada de rede, e o valor está em exercitá-los contra
PostgreSQL e LocalStack de verdade, na suíte de integração — não em substituir
a infraestrutura por mock para inflar o número.
| Cenário | Onde |
|---|---|
Money: escala, overflow, NaN, exponente, moedas incompatíveis |
internal/domain/money |
| Nenhum float no caminho do dinheiro (varredura da AST) | internal/domain/guard |
| Invariantes do schema: 24 recusas esperadas | test/integration |
| 100.00 com duas apostas simultâneas de 80.00 | test/integration, test/e2e |
| Mesma aposta 50× em paralelo → um débito | test/integration |
| Carteiras distintas em paralelo | test/integration |
| Três instâncias independentes | test/e2e |
| Reversão antes da referência | test/integration |
| Expiração da pendência | test/integration |
| Dois publishers disputando a outbox | test/integration |
Republicação preservando o eventId |
test/integration |
| Idempotência sobrevivendo a reinício | test/integration |
| Isolamento entre provedores, inclusive em replay | test/e2e |
| Mesma operação por HTTP e por fila, deduplicada | test/e2e |
| Mensagem repetida absorvida pela inbox | test/e2e |
OPENING pela fila indo direto à DLQ |
test/e2e |
| Reinício completo preservando idempotência e pendências | test/e2e |
| Queda de uma instância sem perder operação | test/e2e |
| Consumidor interrompido entre o commit e a remoção | test/integration |
Mesmo messageId com conteúdo diferente → DLQ |
test/integration |
| Falha transitória devolvendo a mensagem à fila | test/integration |
| Composição Fx iniciando e encerrando, com liberação de recursos | test/e2e |
| Ciclo completo repetido (prova que nada vazou) | test/e2e |
| Configuração inválida impedindo a subida | test/e2e |
Logs JSON com correlationId, messageId, transactionId, walletId e
providerId. Credencial e payload financeiro completo não são
registrados.
Métricas em /metrics:
| Métrica | O que mostra |
|---|---|
wagering_transactions_total{kind,status,source} |
resultados por tipo e origem |
wagering_duplicates_total{source} |
repetições reconhecidas |
wagering_retries_total{component} |
novas tentativas |
wagering_dead_letter_total{component} |
o que foi para a DLQ |
wallet_lock_conflicts_total |
conflitos de concorrência |
wagering_processing_seconds{source} |
latência |
outbox_pending_age_seconds |
atraso da outbox |
reconciliation_divergences_total |
divergências de reconciliação |
outbox_pending_age_seconds é o alarme mais útil: ele cresce quando a
publicação para, mesmo com todo o resto parecendo saudável.
Todas em .env.example. As obrigatórias:
| Variável | Para quê |
|---|---|
DATABASE_URL |
conexão com o PostgreSQL |
OIDC_ISSUER_URL |
realm do Keycloak; a autenticação não é opcional |
O serviço recusa subir com configuração inválida, e reporta todos os problemas de uma vez em vez de um por deploy.
Em ARCHITECTURE.md: dinheiro, transações, idempotência,
locks, referências pendentes, reversões, inbox/outbox, autenticação,
autorização, uso do Fx, shutdown, e as limitações assumidas.