Automatizzare la fatturazione e il provisioning HestiaCP

Un prodotto di hosting automatizzato ha esattamente tre momenti in cui il denaro e le macchine si toccano:

1. 01L’ordine viene pagato. Un account deve esistere, con il pacchetto giusto, nel giro di pochi secondi.
2. 02La fattura è scaduta. L’account deve spegnersi e tornare nel momento in cui viene pagata.
3. 03L’abbonamento termina. L’account deve essere rimosso, davvero, dati compresi.

HestiaCP ha un comando per ognuno di questi. Ciò che non ha è qualcosa che decida quando eseguirli. Questa pagina parla di come collegare le due metà, e dei punti precisi in cui l’API di HestiaCP risponde in un modo che rompe in silenzio un primo tentativo.

I tre momenti e i comandi che li sostengono

Si osservi la colonna delle risposte. Una mutazione riuscita su HestiaCP è HTTP 204 con nulla nel corpo. Non 200. Un client scritto partendo dal presupposto che il successo sia 200 rifiuta ogni chiamata che ha funzionato, e poi di solito riprova. Ed è così che un’integrazione che funziona si trasforma in una bloccata (vedi più sotto).

La vera risposta vive in un’intestazione di risposta, Hestia-Exit-Code, che porta un numero preso da una tabella fissa. Lo stato HTTP ne deriva e ripiega una ventina di codici su quattro stati. Leggere l’intestazione; trattare lo stato come un indizio.

La sospensione non è simmetrica, e qui conta più che altrove

Questa è la trappola che colpisce in modo specifico un’integrazione di fatturazione, perché un’integrazione di fatturazione è l’unica cosa che sospende due volte lo stesso account.

Misurato, sullo stesso account:

v-suspend-user   su un account attivo    → 204, uscita 0
v-suspend-user   su un account sospeso   → 401, uscita 5   («user X is suspended»)
v-unsuspend-user su un account sospeso   → 204, uscita 0
v-unsuspend-user su un account attivo    → 204, uscita 0

Riattivare è idempotente. Sospendere no. E l’errore che produce è HTTP 401, lo stesso stato che si ottiene per un secret errato, una chiave fuori dal suo ambito e un indirizzo bloccato.

Quindi un ciclo di solleciti che sospende tutto ciò che è scaduto, incluse le cose che ha già sospeso ieri, segnalerà errori di autenticazione per account che sono esattamente nello stato voluto. Il codice di uscita 5 su v-suspend-user significa «era già così» e va letto come un successo.

Non riprovare mai dopo un errore di autenticazione

HestiaCP blocca un indirizzo dopo cinque accessi rifiutati, usando fail2ban con maxretry = 5 e un DROP di iptables. Una volta che questo scatta, le chiamate smettono di andare in timeout a livello applicativo e cominciano ad andarci a livello di rete: il monitoraggio dice che il pannello è irraggiungibile, e nulla nei log punta a un problema di credenziali.

Per un’integrazione di fatturazione questo conta più che per qualsiasi altra cosa, perché un’integrazione di fatturazione è ciò che gira senza sorveglianza di notte. Due conseguenze:

• I codici di uscita 9, 10 e 21 non devono mai innescare un nuovo tentativo automatico. Sono rispettivamente secret errato, permesso negato e API disattivata. Nessuno di essi è un guasto transitorio, e tutti e tre contano per il blocco.
• Un comando fuori dalle autorizzazioni della chiave conta anch’esso come accesso fallito. Non è ovvio: la stessa riga di log viene scritta per un secret errato e per una chiave valida che tende la mano verso un comando che non ha il permesso di eseguire. Una chiave limitata al set di autorizzazioni billing fornito con HestiaCP non ha v-list-user-packages né v-list-web-domains, quindi un ciclo di polling che legge pacchetti e domini consuma il contatore del blocco come da programma. Usare una chiave senza ambito, quella dell’amministratore.

Rimuovere un blocco richiede una shell sull’host del pannello: v-delete-firewall-ban <address> HESTIA. Se il software che si costruisce non sa dire questa frase, chi è di reperibilità alle tre di notte passerà la notte sul problema sbagliato.

Un ordine pagato richiede due chiamate, quindi serve un rollback

HestiaCP non ha alcun comando che crei un utente e agganci un dominio in una volta sola. Questo lascia una finestra:

v-add-user       provibrtest1 …                        → 204, uscita 0
v-add-web-domain provibrtest1 "non un dominio valido"   → 422, uscita 2
v-list-user      provibrtest1                           → l’account esiste, con zero domini

Un vero utente unix, con una home directory, senza sito, e una riga in ogni conteggio. Se il dominio del cliente era già occupato sul proprio pannello (cosa che accade, perché i clienti si spostano), l’ordine fallisce e resta in mano un mezzo account che nessuno noterà mai.

La regola è semplice e va integrata: se il secondo passo fallisce, eliminare l’utente e segnalare l’errore originale. Un dominio rifiutato non deve mai lasciare mezzo account dietro di sé.

Provibr fa esattamente questo, e l’errore che il cliente vede è quello che HestiaCP ha dato per il dominio, non un errore secondario relativo a una pulizia.

Dove vive davvero la fattura

Vale la pena dirlo esplicitamente, perché è il malinteso più comune: Provibr non fattura ai suoi clienti. Non invia loro una fattura, non li sollecita e non sa quanto vengono addebitati. Quella relazione è sua.

Ciò che Provibr fattura è la capacità che Lei riserva: quanti account di hosting può far girare contemporaneamente, al mese, a un prezzo unitario a fasce. Ciò che addebita ai suoi clienti per un account HestiaCP, e come, resta interamente all’interno del suo sistema di fatturazione.

Ci sono due modi per collegare le due metà:

Un modulo WHMCS. Se si utilizza già WHMCS, installare il modulo di provisioning Provibr e far puntare un prodotto WHMCS a un piano web Provibr. Un ordine pagato crea l’account; una sospensione in WHMCS lo sospende; una risoluzione lo rimuove. Il cliente mantiene un account, una fattura e un login. Il modulo è un semplice zip che si installa da sé, e gira all’interno del proprio WHMCS. Non c’è nulla da attivare dal nostro lato.

L’API REST. Se si utilizza FOSSBilling, Blesta, qualcosa di interno, o un foglio di calcolo e un cron job, la si pilota direttamente. Una chiave, un URL di base, ed esattamente le autorizzazioni che il membro dietro la chiave ha già.

L’unica regola per pilotarlo dal proprio codice

Tutto ciò che tocca una macchina è asincrono, e deve esserlo. La propria infrastruttura è raggiungibile solo attraverso l’agente all’interno della propria rete, e quell’agente si connette verso l’esterno. Quindi un endpoint che modifica un account non può rispondere con il risultato. Risponde che l’ordine è stato accettato e consegna un comando da seguire, che si legge finché il suo stato non è definitivo: completato, fallito, scaduto o annullato. Un comando fallito porta il codice di errore dell’agente stesso con i suoi argomenti, lo stesso che il pannello mostra sullo schermo.

La lettura non funziona mai così. Un inventario, un indirizzo o una fattura risponde immediatamente, perché quella risposta viene da un database e non dal proprio host.

La conseguenza pratica per un hook di fatturazione: non segnare l’ordine come completato sulla risposta di accettazione. Su HestiaCP, v-add-user richiede circa un secondo e v-delete-user circa tre, quindi l’attesa è breve. Ma la risposta che si ottiene per prima dice «l’abbiamo inviato», non «ha funzionato».

La sospensione è anche il controllo dei propri costi

Un collegamento facile da mancare. In Provibr un server sospeso non conta nella propria capacità, e per un account di hosting non esiste lo stato «arrestato»: esistono attivo e sospeso.

Quindi l’azione di sollecito che si voleva comunque eseguire per ragioni commerciali è anche quella che libera lo slot che si sta pagando. Se si sospende un account scaduto, smette subito di contare; se lo si elimina, smette anch’esso di contare; se lo si lascia in esecuzione e non pagato, lo si paga.

Cosa non automatizza

Provibr gestisce gli account, non il pannello. Non installa HestiaCP, non lo aggiorna, non modifica le impostazioni del server e non tocca DNS, caselle di posta o database. Un cliente che elimina la propria casella di posta tramite HestiaCP lo fa senza che nulla al di sopra lo sappia o se ne curi. Non c’è console per un account di hosting. E non c’è sospensione parziale: un account è attivo oppure no.

Se si vendono anche VPS, server di gioco o account cPanel, gli stessi tre momenti valgono per tutti, e possono vivere in un unico inventario. Provibr fa girare oggi i suoi pannelli di controllo, i suoi hypervisor e i suoi pannelli di gioco fianco a fianco, con un unico set di autorizzazioni e un unico registro di attività su tutto.