Automatizar a faturação com o WISP

O WISP suspende um servidor por si, e faz com que essa suspensão se mantenha: um cliente que ainda tenha credenciais do painel não consegue carregar em iniciar. O que o WISP não tem, e nunca afirmou ter, é a mínima ideia de se esse cliente lhe pagou.

Esta página trata da camada que fica pelo meio. Trata também da única coisa que distingue o WISP de todos os outros painéis de jogo aqui presentes, e que nada tem a ver com a sua API: o painel não é seu.

O painel é alojado, o nó é seu

O WISP é vendido como um serviço alojado. O wisp.gg faz correr o painel; o nó que carrega os seus servidores de jogos corre no seu próprio equipamento. Um agente dentro da sua rede liga para o exterior, ao painel através da sua API e ao daemon do seu nó para a consola, pelo que nada tem de ser aberto à internet.

Para uma integração de faturação, essa divisão tem uma consequência real: não há nada que possa atualizar nem nada que possa fixar. O WISP pode alterar a sua API sem uma versão que o próprio controle. O Provibr é testado contra a v3.7.5 e lê a versão em execução a partir do próprio painel, pelo que um desvio aparece no teste de ligação em vez de aparecer numa encomenda falhada às duas da manhã.

Um pormenor relacionado que vale a pena conhecer antes de culpar o seu próprio código. A porta de entrada do painel está atrás de um desafio da Cloudflare; todos os caminhos /api/… passam diretamente. Isso foi medido com três agentes de utilizador diferentes e os três responderam 200. É uma definição no wisp.gg, não do seu lado nem do nosso, por isso, se o WISP alguma vez puser o mesmo desafio na API, todas as integrações WISP param ao mesmo tempo e não há nada a corrigir localmente. A falha tem uma forma reconhecível (403, um cabeçalho Cf-Mitigated: challenge e HTML em vez de JSON) e merece uma mensagem própria, para que o painel diga não nos deixa entrar em vez de chave errada.

O ciclo de vida, em correspondência

Cinco ações, e as cinco respondem com um 204 vazio. Não há literalmente nada no corpo, pelo que a regra da casa se aplica sem exceção: nenhuma mutação confia na sua própria resposta. Volte a ler o servidor depois.

Suspender é a sério, e é idempotente

Essa combinação é mais rara do que devia ser entre os painéis de jogo, e é toda a razão pela qual um ciclo de cobrança no WISP é aborrecido no bom sentido.

Uma segunda suspensão num servidor já suspenso responde 204 outra vez. Nada para tratar como caso especial, nada para tratar como «já estava assim», nenhum erro para engolir. Compare isso com painéis de controlo onde suspender duas vezes é um erro de autenticação, e percebe-se quanto de uma integração de cobrança se gasta habitualmente a pedir desculpa pelo painel.

Eliminar também funciona num servidor suspenso, o que importa para o cancelamento que chega um mês depois da suspensão. Uma segunda eliminação responde 404, que é o desfecho correto para um gancho de rescisão: não sobrou nada para limpar.

As regras de estado do lado do Provibr são mais estritas do que as do painel, de propósito:

Leia a linha do suspend duas vezes. É possível suspender um servidor que já está parado, e um que ainda está a instalar. Se a suspensão só funcionasse em servidores a correr, um cliente poderia parar o seu próprio servidor, deixar de pagar e ficar intocável. Uma imposição que se pode contornar carregando em stop não é uma imposição, e um cancelamento que aterra a meio da instalação não deve ter de esperar que a instalação termine.

Duas chaves, sem prefixo, e o erro que daí resulta

O WISP mantém a divisão do Pterodactyl entre duas superfícies de API, e nenhuma chave sozinha cobre as duas. A chave de aplicação constrói, suspende, reinstala e remove; a chave de cliente trata da energia, das estatísticas em direto e da consola. Ambas são criadas numa conta de administrador.

Eis a armadilha. As chaves do WISP não têm prefixo nenhum, ao contrário do ptla_ do Pterodactyl ou do papp_ do Pelican: são 48 caracteres sem cabeça reconhecível, pelo que nada lhe pode dizer que as colou trocadas. Nem nós, nem o painel, porque o WISP responde a uma chave errada com 403 e uma mensagem vazia. Um 403 significa normalmente esta chave não tem autorização para fazer isso, pelo que um cliente que trocou duas chaves entra no painel e começa a assinalar permissões que nunca foram o problema. Se o teste de ligação falhar, troque as duas chaves antes de mudar seja o que for.

A outra metade dessa credencial merece uma frase no seu próprio manual de operações: a chave de aplicação não é apenas gestão de servidores. A mesma listagem de nós que uma integração lê transporta também a chave de licença do seu nó e o token do daemon. Trate-a como uma credencial para todo o painel, e revogue-a no WISP se alguma vez desligar a integração.

Nada é instantâneo, e a API di-lo

O seu painel vive na sua própria rede e o agente liga para o exterior, pelo que 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"
  }
}

Isso é 202 Accepted, não 200. Depois lê o comando até que o seu estado seja definitivo: done, failed, timed_out ou cancelled. A leitura nunca funciona assim, porque um inventário ou uma fatura vem de uma base de dados e não do seu anfitrião.

Tudo o que cria algo aceita uma Idempotency-Key da sua própria autoria. Indexe-a em algo estável do seu lado, como o identificador da fatura mais a etapa de cobrança, e um cron de quinze minutos, um webhook reenviado e um administrador que clica duas vezes tornam-se todos inofensivos.

Duas formas que quebraram esta integração antes de a conhecer

Ambas valem a leitura mesmo que nunca toque no WISP, porque ambas são o tipo de falha que reporta êxito.

Cada identidade é uma cadeia de caracteres com prefixo, não um número. Um servidor WISP é server_01m0n8m94afcj2kk5mzt9z379q; os nós, os eggs e as alocações têm o mesmo aspeto. A plataforma tinha uma verificação de que o identificador externo de um servidor de jogos era letras e algarismos, o que é verdade em todos os outros painéis de jogo e falso aqui. O resultado não foi uma mensagem de erro: os clientes WISP acima do limite eram reportados ao trabalhador de imposição e depois ignorados, em cada ronda, para sempre. Eram assinalados e nunca suspensos. Uma única verificação de identidade partilhada cobre agora as duas formas.

Um peso de disco de zero é recusado. O WISP exige limits.io e obriga a um valor entre 10 e 1000. O campo de plano da plataforma tem zero por omissão, pelo que todas as encomendas WISP teriam terminado num 422 sobre um campo de que a maioria das pessoas nunca ouviu falar. Há agora duas barreiras: o formulário do plano recusa um zero e diz porquê, e o agente eleva um zero até ao peso predefinido antes de enviar. Duas barreiras para o mesmo erro é deliberado, porque uma delas está do lado que consegue ver.

O que não consegue ver, e não deve fingir que vê

Esta é a parte honesta, e é curta.

• Não há campo de estado num servidor WISP. O Pterodactyl tem um, com installing e install_failed lá dentro. O WISP tem suspended e container.installed, ambos booleanos. Uma instalação falhada parece por isso exatamente uma instalação bem-sucedida: installed fica em falso nos dois casos. A ser construído e avariado são a mesma imagem nesta superfície, e um produto que afirme o contrário está a adivinhar.
• Um nó não reporta a sua própria ocupação. O campo que os outros painéis usam para isso está ausente, incluindo quando se pergunta explicitamente por ele. A ocupação é somada a partir dos servidores, o que funciona e custa mais uma chamada.
• Não há uptime nas estatísticas em direto. Um contentor que reiniciou entre duas sondagens não pode ser reconhecido com certeza. Em contrapartida, o WISP não guarda essas estatísticas em cache durante vinte segundos como o Pterodactyl faz, pelo que os gráficos não inventam uma quebra que nunca aconteceu. No conjunto é melhor, com uma aresta afiada.

A capacidade, e como se cruza com a cobrança

O Provibr fatura-lhe a capacidade, não os seus clientes. O que cobra por um servidor de jogos fica inteiramente dentro do seu próprio sistema de faturação; nunca vemos uma fatura de cliente e nunca falamos com os seus clientes.

A regra que apanha toda a gente no primeiro mês: cada servidor conta, esteja a correr ou não. Um servidor suspenso não conta, e um eliminado também não. Parar uma máquina não liberta nada.

Isso encaixa-se com a cobrança de forma bastante limpa. Suspenda um cliente por falta de pagamento e ele deixa de contar para a sua capacidade nesse momento; reative-o quando pagar e volta a contar. Não está a pagar capacidade de plataforma por alguém que não lhe está a pagar.

O que não é automatizado deliberadamente

O Provibr gere servidores, não o painel. Não instala o WISP, não toca no daemon do seu nó para além da consola, e não gere cópias de segurança, regras de firewall nem atribuição de IP neste fornecedor: essas capacidades estão desligadas no registo em vez de meio implementadas. Não há faturação medida sobre o uso do WISP, porque as estatísticas por servidor são mostradas no painel e não estão expostas através da API, e um ponto de acesso que não existe não pode ser faturado.

Se ainda está a escolher, a comparação que vale a pena ler primeiro é Escolher um painel de jogos pela sua API, que mede seis painéis exatamente numa pergunta: se uma suspensão faz alguma coisa. A ligação em si, as duas chaves e o campo da impressão digital estão cobertos na página da integração WISP.