Ciclo de vida do provedor: plugar, drenar, desplugar¶

Para: Dev · Adm — Conferido em 2026-10-31.

O que é¶

Um provedor de liquidação (PSP, gateway, provedor cripto) é um processo à parte, falando o SPP v1 em loopback com o executor. O registro de provedores do executor guarda, para cada provedor, um estado. O estado decide se ele recebe trabalho novo, se aceita callbacks e se ainda é consultado sobre o que ficou em voo.

Plugar e desplugar um provedor não exigem deploy do núcleo: são operações do dracma_ops sobre o registro. Esta página descreve os estados, o passo a passo de plugar, o que acontece ao desplugar com dinheiro em andamento, failover, breaker, saúde e o que fazer quando o parceiro cai sem ninguém desplugar nada.

Quando usar¶

• Você vai entrar com um provedor novo (nosso ou de terceiro) e quer saber exatamente o que o ops faz.
• Você vai sair de um parceiro (ou apenas pausá-lo) sem perder dinheiro em voo.
• Um provedor caiu e você precisa saber o que o sistema faz sozinho e o que cabe ao operador.
• Para a troca completa de um parceiro por outro, com canário e rollback, siga o runbook de troca de parceiro.

Como funciona¶

Estados e transições¶

Em palavras: registered → enabled, enabled ↔ draining → disabled ↔ enabled, disabled → unplugged e unplugged → registered. O unplug --force com trabalho em voo é o único atalho, e é break-glass auditado (veja Desplugar). O unregister, que apagaria o registro, é recusado enquanto existir conexão de tenant; dado financeiro nunca é apagado.

Tabela de estados¶

Pré-condições para enabled (todas verificadas pelo registro):

1. Descriptor válido, spp_version compatível e name sem colisão.
2. health igual a ok.
3. Egress e ingress aplicados pelo ops e conferidos.
4. Certificação válida para o descriptor_sha256 atual em hml e prd. Em dev basta o harness local.
5. Se o provedor não é sintético: política de ambiente satisfeita (guarda de ambiente do SPP).

Plugar¶

Plugar é uma sequência de cinco fases, todas pelo ops. Cada fase é idempotente: repetir não duplica nada.

1. Instalar (usuário, unit, porta, par HMAC, egress, ingress). O comando lê o descriptor do pacote do adaptador e faz tudo de uma vez:

dracma_ops provider install --name exemplo --env hml --jobs "$(nproc)"

Saída esperada (exemplo):

[install] provedor exemplo (dracma_psp_exemplo) versão 0.3.1, spp 1.0
[install] usuário linux: dracma-psp-exemplo (uid 9211, sem shell, sem home)
[install] unit systemd: dracma_psp_exemplo.service (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, ProtectHome)
[install] porta loopback: 127.0.0.1:9411
[install] par HMAC: semeado no seeder da aplicação (chamador executor, chamado exemplo)
[install] egress: 2 hosts liberados para o uid 9211 (api.exemplo-psp.example:443, sandbox.exemplo-psp.example:443)
[install] ingress: rota de callbacks genérica já cobre o provedor (nenhuma edição de rota)
[install] subindo unit ... ok
[install] GET /spp/v1/health -> ok

O que cada item significa:

A instalação é paralela, com o número de jobs igual ao de cores (nproc). Se uma instalação em paralelo falhar por colisão (porta, usuário, regra), os serviços não estão independentes: o ops expõe a colisão e não serializa para mascarar; corrija a independência antes de seguir.

2. Registrar. O executor lê o descriptor pela URL de loopback, valida e grava a cópia versionada. O estado inicial é registered.

dracma_ops provider register --name exemplo --url http://127.0.0.1:9411/spp/v1

[register] GET http://127.0.0.1:9411/spp/v1/descriptor -> 200
[register] descriptor válido; spp_version 1.0 (comum com o executor: 1.0)
[register] descriptor_sha256 = 3f9a...c1d2
[register] estado: registered

3. Certificar. A suíte de conformidade do SPP roda contra o adaptador e o ops grava o resultado, amarrado ao descriptor_sha256:

dracma_ops provider certify --name exemplo

[certify] suite spp-conformance 1.0 contra http://127.0.0.1:9411/spp/v1
[certify] passou 58 de 58
[certify] resultado gravado para descriptor_sha256 3f9a...c1d2

4. Habilitar. O registro confere as pré-condições e muda o estado:

dracma_ops provider enable --name exemplo

[enable] health: ok
[enable] certificação válida para 3f9a...c1d2
[enable] egress e ingress conferidos
[enable] estado: enabled

Se faltar algo, a saída diz exatamente o quê:

[enable] recusado: not_certified (descriptor_sha256 mudou desde a certificação)

5. Conferir.

dracma_ops provider list

NOME         ESTADO    SAÚDE  EM-VOO(cobr/saq/unk)  DESCRIPTOR   CERTIFICADO
maximaxpay   enabled   ok     12 / 3 / 0            a1b2...09ff  sim
exemplo      enabled   ok     0 / 0 / 0             3f9a...c1d2  sim

Habilitar um provedor não manda tráfego a ele: o roteamento é por conexão de tenant, com prioridade e direção. O provedor recém-habilitado só recebe trabalho quando existirem conexões apontando para ele (veja o runbook).

Drenar¶

drain fecha a porta de entrada e mantém a de saída: o provedor não recebe trabalho novo, mas continua recebendo callbacks e sendo consultado sobre o que ficou em voo.

dracma_ops provider drain --name maximaxpay
dracma_ops provider inflight --name maximaxpay

[drain] estado: draining
cobranças pendentes: 7
saques não terminais: 3 (desconhecidos: 0)

O que acontece com cada tipo de trabalho:

Quando o contador em-voo chega a zero, o estado passa sozinho para disabled e o executor emite o evento provider.drained. Se o dreno parar (por exemplo, um saque preso em unknown), o alerta de drain parado dispara: a causa quase sempre é um saque que precisa de consulta ao parceiro ou decisão humana.

Para desabilitar de vez:

dracma_ops provider disable --name maximaxpay

Com em-voo maior que zero, disable vira drain e o provedor passa por draining até zerar. Com em-voo zero vai direto para disabled. É reversível com enable.

Desplugar¶

unplug para e remove o adaptador. O registro, as conexões dos tenants e as credenciais cifradas permanecem, de modo que re-plugar é barato e nada se perde.

dracma_ops provider unplug --name maximaxpay

Sem --force, com trabalho em voo, a operação é recusada:

[unplug] recusado: in_flight_work (cobranças 7, saques 3). Drene antes ou use --force com motivo.

Com --force (break-glass auditado, exige motivo de 10 a 1000 caracteres):

dracma_ops provider unplug --name maximaxpay --force --reason "parceiro encerrou o contrato em 2026-11-30; ver incidente 4471"

O efeito sobre o que estava em voo:

Um saque em needs_reconciliation é resolvido por um humano: consulte o parceiro pelo canal dele (painel, extrato, suporte) usando a chave de idempotência do saque, e conclua como liquidado ou falho. Veja o plano completo no runbook.

Re-plugar¶

unplugged → registered: suba o adaptador de novo (install) e rode register. O registro valida o descriptor outra vez e compara o descriptor_sha256. As conexões dos tenants que estavam provider_unavailable reativam sozinhas quando o provedor chega a enabled.

dracma_ops provider install --name maximaxpay --env hml --jobs "$(nproc)"
dracma_ops provider register --name maximaxpay --url http://127.0.0.1:9412/spp/v1
dracma_ops provider certify --name maximaxpay
dracma_ops provider enable --name maximaxpay

Se o adaptador voltou com um descriptor diferente, vale a regra da seção seguinte.

Mudança de descriptor¶

O registro compara o descriptor_sha256 a cada novo register.

Como a certificação vale para um descriptor_sha256 específico, qualquer mudança de descriptor exige certificar de novo antes de habilitar em hml e prd.

Failover de depósito¶

Criar uma cobrança não move dinheiro, então trocar de provedor quando a criação falha por indisponibilidade é seguro. O failover de depósito obedece a regras fixas, que não dependem de qual provedor é.

Breaker¶

O breaker é do núcleo e protege o parceiro e o jogador sem consultar o provedor.

Breaker aberto responde CircuitOpen sem chamar o provedor. O estado aparece em dracma_psp_circuit_state.

Saúde¶

O executor consulta a rota de saúde de cada provedor a cada 10 s.

As verificações de saúde nunca criam efeito no parceiro nem usam credencial de tenant. Os estados possíveis são ok, degraded (opera com restrição) e down.

Falha do provedor sem desplugar¶

O piso de independência (S12) vale nos dois sentidos: o executor sobe e funciona sem o provedor, e o provedor sobe sozinho, sem o executor. Quando um provedor cai ou o parceiro fica fora, sem ninguém desplugar, o sistema faz sozinho:

1. Persiste. Nada é perdido: cobranças e saques em curso ficam gravados com o estado conhecido.
2. Loga com trace_id. Cada falha tem rastro correlacionável do executor ao provedor.
3. Alerta. Provedor down, breaker aberto, resposta unrecognized_response e dreno parado são alertas versionados no Grafana.
4. Protege. O breaker abre; depósitos usam failover (se ligado e houver outro provedor); saques não trocam de provedor.
5. Retoma. Quando o provedor volta, a saúde reabilita, o breaker fecha na sonda e o reconciliador reconsulta o que ficou unknown.

O que o operador faz: acompanhar o alerta, confirmar a causa (processo, rede, parceiro) e, se o parceiro está fora por tempo prolongado, decidir entre esperar, drenar ou trocar de parceiro.

Trocar de parceiro sem downtime¶

Visão geral (o passo a passo completo, com comandos, métricas e rollback, está no runbook de troca de parceiro):

1. Obter ou escrever o adaptador do novo parceiro e certificá-lo em hml.
2. Instalar em paralelo, registrar e habilitar o novo provedor ao lado do antigo.
3. Criar conexões dos tenants no novo provedor e mover o roteamento por tenant e operação, em canário.
4. Observar métricas e alertas; recuar se algo sair do esperado.
5. Drenar o provedor antigo, tratar os saques em voo e só então desplugar.

Como o antigo continua enabled até a drenagem e o novo entra por roteamento, em nenhum momento há janela sem provedor.

API de registro do executor¶

O ops fala com o registro por rotas do executor, só para o chamador ops (HMAC interno v2). Todas as mutações vão para a auditoria. Estas são as rotas, que o dracma_ops provider encapsula:

GET  /internal/v1/providers
GET  /internal/v1/providers/{name}
POST /internal/v1/providers
GET  /internal/v1/providers/{name}/inflight
POST /internal/v1/providers/{name}/enable
POST /internal/v1/providers/{name}/drain
POST /internal/v1/providers/{name}/disable
POST /internal/v1/providers/{name}/unplug
POST /internal/v1/providers/{name}/certify

Registrar (o url precisa ser http://127.0.0.1:<porta>/spp/v1, só loopback):

{ "url": "http://127.0.0.1:9411/spp/v1" }

Resposta 201:

{
  "name": "exemplo",
  "state": "registered",
  "health": "ok",
  "url": "http://127.0.0.1:9411/spp/v1",
  "descriptor_sha256": "3f9a5d0e7b1c4a28e6f0d93b52c7a1840be9d6f3a27c5d81e04b9a6c7f30c1d2",
  "certification": null,
  "inflight": { "charges_pending": 0, "payouts_non_terminal": 0, "payouts_unknown": 0 },
  "registered_at": "2026-10-31T12:00:00Z",
  "changed_at": "2026-10-31T12:00:00Z"
}

Certificar (corpo certification; o descriptor_sha256 precisa ser o do registro):

{
  "certification": {
    "descriptor_sha256": "3f9a5d0e7b1c4a28e6f0d93b52c7a1840be9d6f3a27c5d81e04b9a6c7f30c1d2",
    "suite_version": "1.0",
    "passed": 58,
    "total": 58,
    "at": "2026-10-31T12:05:00Z",
    "report_sha256": "9c1e0f2a47d38b65a1f0c2e9d4b7a3685f10e2c4d7a9b3f6180e5c2a4d7b9f01"
  }
}

Em voo (GET .../inflight):

{ "charges_pending": 7, "payouts_non_terminal": 3, "payouts_unknown": 0 }

Desplugar com força:

{ "force": true, "reason": "parceiro encerrou o contrato; ver incidente 4471" }

Recusas comuns, todas 409 com corpo application/problem+json: transição inválida, in_flight_work (desplugar sem force), not_certified e not_healthy (habilitar). Um register com descriptor inválido, versão incompatível (incompatible_spp_version) ou host de egress inconsistente responde 422.

Situação e comportamento¶

Erros comuns¶

Próximos passos¶

• Execute a troca completa com canário e rollback: runbook de troca de parceiro.
• Se o parceiro sumiu: parceiro que rompe de repente.