Automatização da faturação para o Pelican Panel

O Pelican tem um indicador suspended em cada servidor. Nada no Pelican alguma vez o define. Essa única frase é toda a razão de ser desta página: o painel é capaz de parar o servidor de um cliente, mas não faz a mínima ideia se o cliente pagou.

Esta página descreve o aspeto de uma automatização que funciona: o caminho da encomenda, o caminho da cobrança, e as partes que são genuinamente mais difíceis do que parecem.

Duas camadas de faturação, e não são a mesma coisa

Antes de tudo, separe-as. As pessoas confundem constantemente estas duas e depois discutem o problema errado.

O que cobra aos seus próprios clientes, e como, fica inteiramente dentro do seu sistema de faturação. O Provibr nunca vê uma fatura de cliente, nunca define um preço por si, e nunca fala com os seus clientes; fatura-lhe a capacidade reservada por tipo de recurso, a um preço unitário que desce por escalões à medida que a contagem sobe.

É essa separação que torna a automatização tratável. O seu sistema de faturação detém a decisão; a camada de aprovisionamento detém a execução.

O ciclo de vida, em correspondência

Eis a correspondência de que toda a automatização de alojamento de jogos precisa, sejam quais forem as ferramentas usadas:

O Pelican está à vontade aqui, e vale a pena dizê-lo com clareza, porque nem todos os painéis de jogos estão. O Pelican tem uma verdadeira primitiva de suspensão. Um servidor suspenso está suspenso no painel: alguém com acesso direto ao Pelican não pode simplesmente voltar a iniciá-lo. Quando a imposição conta (e para a cobrança conta), essa é a diferença entre uma política e um desejo.

(Por contraste: o PufferPanel não tem suspensão própria, pelo que uma suspensão ali é uma noção de plataforma que o painel não impõe.)

A regra que molda tudo: nada é instantâneo

É esta a parte em que se erra ao ligar uma API por conta própria.

O seu painel vive na sua própria rede, e uma plataforma sensata alcança-o através de um agente que se liga para o exterior: sem porta de entrada, sem buraco no firewall. A consequência é inevitável: um ponto de acesso que altera uma máquina não pode responder com o resultado. Responde que a encomenda foi aceite e entrega-lhe algo para seguir:

POST /v1/servers/{serverId}/actions/suspend
Authorization: Bearer pvk_...
Idempotency-Key: dunning-inv-10482

{
  "command": {
    "id": "cmd_...",
    "kind": "game.suspend",
    "status": "pending"
  }
}

Obtém 202 Accepted, não 200. Depois lê esse comando até que o seu estado seja definitivo: done, failed, timed_out ou cancelled. Um comando que falhou transporta o código de erro do próprio agente, com os seus argumentos.

A leitura nunca funciona assim: um inventário, um endereço ou uma fatura responde imediatamente, porque essa resposta vem de uma base de dados e não do seu anfitrião.

Desenhe os seus ganchos de faturação em torno disto. Um gancho que trata «a API respondeu» como «o trabalho está feito» reportará êxito para uma suspensão que nunca aconteceu, precisamente no dia em que isso importava.

Repetir um pedido em segurança

Tudo o que cria algo aceita um cabeçalho Idempotency-Key da sua própria autoria. Repita o mesmo pedido com o mesmo valor e obtém de volta o primeiro resultado, em vez de um segundo servidor, um segundo comando ou uma segunda cobrança.

Para a cobrança, isto não é um luxo. Um cron de quinze minutos, um webhook reenviado, um administrador que clica duas vezes: os três são normais e os três devem ser inofensivos. Indexe o pedido em algo estável do seu lado: o ID da fatura, o ID do serviço, a etapa de cobrança. Reutilizar esse valor para um pedido diferente é recusado de propósito: uma chave que significa duas coisas não significa nada.

Os verbos, e quando são permitidos

Um servidor de jogos aceita seis ações através da API:

start · stop · restart · kill · suspend · resume

São protegidas pelo estado atual do servidor, que é mais estrito do que parece:

A linha suspend é a interessante, e é deliberada: é possível suspender um servidor que já está parado. Se a suspensão só funcionasse em servidores a correr, um cliente poderia parar o seu próprio servidor, deixar de pagar e ficar imune: o painel recusaria a suspensão porque nada estava a correr. Uma imposição que se pode contornar carregando em «stop» não é uma imposição.

suspend a partir de installing também importa: um cancelamento que chega a meio da instalação não deve esperar que a instalação termine.

Fazê-lo a partir de um painel de faturação em vez de código

Se já usa o WHMCS, não precisa de escrever nada do que está acima. O Provibr fornece um módulo de aprovisionamento para o WHMCS como um simples zip que instala por si próprio: um produto do WHMCS aponta para um plano do Provibr, e o fluxo de encomenda normal do WHMCS trata de criar, suspender, reativar e rescindir.

Duas decisões de conceção nesse módulo valem a pena reaproveitar, mesmo que escreva a sua própria ponte:

Uma entrega que ainda está a decorrer conta como êxito. Se o orçamento de espera se esgotar enquanto o instalador ainda trabalha, o módulo reporta êxito. A encomenda foi aceite: a linha do servidor existe, o endereço está atribuído, o comando está com o agente. E o WHMCS não tem um estado «em instalação» (Pending ali significa ainda não aconteceu nada, o que é comprovadamente falso). Um comando que falha verdadeiramente é diferente: o serviço fica Pending, o administrador vê porquê, e um clique repetido é inofensivo graças à chave de idempotência.

Um servidor que já desapareceu é uma rescisão bem-sucedida. Um 404 numa eliminação significa quatro coisas ao mesmo tempo (ID desconhecido, outra conta, não atribuído a este membro, ou já eliminado) e, para um gancho de rescisão, a ação correta é idêntica nos quatro casos: não há nada para limpar. Tratá-lo como um erro deixa um serviço preso em «terminating» para sempre.

O que não é automatizado deliberadamente

Fronteiras honestas, porque estas são as perguntas que chegam depois de já se ter vendido algo:

• Sem faturação baseada no uso. As métricas por servidor são recolhidas e mostradas no painel, mas ainda não estão expostas através da API. Sem um ponto de acesso, não há faturação medida. Se o seu produto é «pague a RAM que consumiu», isto não o faz hoje.
• Sem mudança de plano numa só chamada. Trocar de plano também não é uma única chamada de API ao nível do Pelican: é uma reinstalação ou uma mudança de recursos, com consequências diferentes para os dados do cliente.
• Sem reposição de palavra-passe através da API. As credenciais circulam de forma transitória e nunca são guardadas, pelo que não há nada para reenviar.
• Sem autenticação única do seu painel de faturação para o painel do Provibr.
• Sem ciclo de reconciliação de inventário: uma recusa, não uma lacuna. A sincronização _ListAccounts do WHMCS rescinde qualquer serviço ausente da resposta, e «ausente» tem causas inocentes: um âmbito de API mais estreito, um membro restrito a parte do inventário, uma limitação de débito, uma página curta cujo cursor não foi seguido. Cada uma eliminaria máquinas de clientes. Em vez disso, a área de cliente lê o estado em direto a cada apresentação de página, o que não é sincronização e não finge sê-lo.

Contar a capacidade, e como isso se cruza com a cobrança

A faturação da plataforma conta a capacidade, não o uso, com uma regra que apanha toda a gente no primeiro mês: cada servidor conta, esteja a correr ou não. Só um servidor suspenso não conta, e um servidor eliminado também não. Parar uma máquina não liberta um lugar.

Isto encaixa-se bem com a cobrança. Um cliente que suspende por falta de pagamento deixa de contar para a sua capacidade enquanto estiver suspenso, e volta a contar assim que paga e o reativa, pelo que não está a pagar capacidade de plataforma por um cliente que não lhe paga.

Ultrapassar o seu limite não é bloqueado no momento em que o faz. É detetado, é-lhe dito, e tem um dia útil completo. Se esse prazo de graça expirar, os servidores mais recentes acima do limite são suspensos, os mais recentes primeiro, para que o que construiu mais cedo sobreviva.

O Pelican a par de tudo o resto

Um alojador de jogos que cresce raramente permanece num só painel. O Provibr cobre os seus painéis de controlo, os seus hipervisores e os seus painéis de jogo num único painel de controlo, com uma única API e um único número de capacidade para todos eles.

POST /v1/servers/{id}/actions/suspend faz a mesma coisa quer por baixo esteja um servidor Pelican, um servidor Pterodactyl ou uma conta de alojamento DirectAdmin. As diferenças vivem no fornecedor, não no seu código de integração.