Blog ·
Automatizzare la fatturazione ISPConfig
ISPConfig risponde HTTP 200 a tutto, guasti compresi. Cosa comporta per un hook di fatturazione e come il ciclo di vita dell’account si mappa sull’API remota.
Di Provibr
ISPConfig ha un comando per ogni momento in cui il denaro e le macchine si toccano: creare l’account, sospenderlo, spostarlo su un altro pacchetto, rimuoverlo. Ciò che non ha è qualcosa che decida quando eseguirli.
Collegare le due metà è per lo più lavoro ordinario. Due cose di ISPConfig non lo sono, ed entrambe rompono in silenzio un primo tentativo: il codice di stato di una chiamata non dice assolutamente nulla, e un account non è un cliente.
Il codice di stato non dice nulla
Tutto torna indietro come HTTP 200. Errori di validazione, «questo non esiste», una password errata, un metodo che l’utente remoto non è autorizzato a chiamare: tutti, 200. Il verdetto è un campo code all’interno del corpo JSON.
code | Significato |
|---|---|
ok | Ha funzionato; response porta l’esito |
remote_fault | È fallita: validazione, oggetto mancante, autenticazione, permesso. message spiega |
invalid_method | Metodo sconosciuto, o un metodo non presente in quella classe |
permission_denied | All’utente remoto manca quella funzione |
Classificare in base a code e al testo, mai in base allo stato. Il motivo per cui questo conta più per un’integrazione di fatturazione che per qualsiasi altra cosa è il polling: un client che tratta il 200 come successo legge un fallimento di autenticazione come un inventario vuoto riuscito, e poi contrassegna come spariti tutti gli account di quel cliente. Una sola sessione scaduta, e la sua riconciliazione elimina un’attività di hosting.
Il campo message arriva in due varianti, e la differenza è utile. Gli errori di validazione provenienti dal livello dei moduli del pannello sono un elenco di chiavi di traduzione separate da <br>, non frasi: domain_error_unique per un dominio già ospitato. I controlli nella libreria remota sono normali frasi in inglese: Invalid client_id 99999. Confrontare le chiavi, citare le frasi.
Un account è un sito web, non un cliente
ISPConfig separa due cose che la maggior parte dei pannelli di controllo fonde insieme. Un client è un accesso al pannello con limiti validi per l’intero account. Un web_domain è un singolo sito ospitato. Un client può possedere più siti web.
Un account di hosting Provibr è un sito web, identificato dal suo dominio. Crearne uno richiede quindi un proprietario, perciò l’agente crea un client nuovo e un sito web sotto di esso, e ricava l’accesso del client dal dominio, così da poter sempre ritrovare il proprietario.
È questa scelta a rendere sicuro il percorso di eliminazione, e il percorso di eliminazione è il punto in cui questa integrazione è quasi andata storta. Più sotto i dettagli.
Il ciclo di vita, in corrispondenza
| Evento di fatturazione | Chiamata ISPConfig | Risposta in caso di successo |
|---|---|---|
| Ordine pagato | client_add, poi sites_web_domain_add | code: ok, due volte |
| Fattura scaduta | sites_web_domain_set_status(id, "inactive") | code: ok |
| Pagamento ricevuto | sites_web_domain_set_status(id, "active") | code: ok |
| Upgrade / downgrade | client_update con un nuovo client template | code: ok |
| Cancellazione | sites_web_domain_delete, poi forse il client | code: ok |
La sospensione è idempotente in entrambe le direzioni
La sospensione fa passare il flag active del sito web tra y e n. Non ci sono maschere di bit né stati parziali: un sito è acceso oppure è spento.
Una seconda sospensione su un sito già sospeso risponde code: ok con una risposta di 0, cioè zero righe modificate. Non è un errore, e un ciclo di solleciti che sospende tutto ciò che è scaduto, incluso ciò che ha sospeso ieri, non ha nulla di cui scusarsi. Vale la pena apprezzare quanto sia raro: su HestiaCP la stessa seconda sospensione è un HTTP 401, indistinguibile da un secret errato, su un pannello che blocca il suo indirizzo dopo cinque accessi rifiutati, come racconta Automatizzare la fatturazione HestiaCP.
Una cosa da sapere, anche se l’integrazione non la usa: ISPConfig ha anche un blocco a livello di client, e impostarlo porta tutti i siti web di quel client su inactive in una volta sola. Un cliente che si blocca da solo nel pannello, o un blocco del rivenditore sopra di lui, compare quindi nel polling come sospeso. È corretto, e non è qualcosa che ha fatto il suo sistema di fatturazione.
Cambiare pacchetto qui è un’azione vera
Un pacchetto ISPConfig è un client template: un insieme di limiti con un nome, costruito da un amministratore nel pannello. L’API remota non può crearne uno, e va bene così, perché un piano dovrebbe fare riferimento a un pacchetto anziché inventarlo. Provibr passa il nome del pacchetto e l’agente ne cerca l’ID del template.
Questo fa di ISPConfig uno dei pannelli di controllo in cui un cambio di piano è davvero un cambio di piano. CloudPanel e CyberPanel devono rifiutarlo del tutto; qui accade e i limiti si spostano subito.
Due avvertenze misurate se lo scrive da sé. Inviare un aggiornamento minimo, che non porti altro che il nuovo template: un aggiornamento con l’intero record del client è tornato come remote_fault senza un messaggio utilizzabile, e lo stesso ha fatto uno che combinava un template esplicito con limiti espliciti. E sappia che il template ha la precedenza sui limiti che invia insieme a esso, cosa giusta nel verso ma che la prima volta sorprende.
Il segnale di pronto è globale per server
Creare un sito web risponde in millisecondi, e quella risposta significa accettato, non fatto. La riga nel database esiste; il virtual host e la document root vengono posati in modo asincrono dal daemon del server.
Il segnale da attendere è il conteggio della coda di lavori per quel server, che è stato misurato scendere da tre a zero in circa otto secondi su una macchina tranquilla, e in circa ventitré secondi in una prova precedente. È un contatore globale, non uno per comando. Su un server multi-tenant carico può restare sopra lo zero a causa dei lavori di altri clienti, o raggiungere lo zero mentre il suo lavoro è ancora in sospeso.
Quindi la regola è un timeout con un messaggio veritiero anziché un’attesa infinita: si legge finché la coda non è vuota o finché non si esaurisce il budget di creazione di 180 secondi, e poi si segnala l’account come creato, perché lo è. «Il sito è ancora in fase di configurazione» è una cosa migliore da dire a un cliente pagante rispetto a una rotellina che non si ferma mai.
L’eliminazione è una questione di privacy, non di pulizia
Questa è la parte dell’articolo da conservare se non se ne conserva nessun’altra, e non riguarda davvero ISPConfig.
Il percorso di eliminazione aveva un difetto che nessuna fixture poteva vedere: confrontava due campi che non sono mai davvero uguali, quindi il ramo che rimuoveva il client proprietario era codice morto. Ogni eliminazione lasciava dietro di sé un accesso al pannello con il nome del cliente, il suo indirizzo e-mail, i suoi recapiti e la sua password. Il comando rispondeva ok, il sito web spariva, il contatore andava a zero, e i dati personali di una persona che aveva chiesto di andarsene restavano sul nodo.
Nulla al di sopra del pannello può vederlo. Un worker di cancellazione e un’esportazione per l’interessato ripuliscono il nostro lato; non hanno alcuna visione di ciò che resta sul suo nodo di hosting. Vale la pena rubare la regola che ne è uscita:
> Misurare un percorso di eliminazione contro il database del pannello stesso, e mai contro «il comando ha restituito ok».
Su ISPConfig sono quattro conteggi, e tutti e quattro devono essere zero: siti web, client, accessi di sistema e la directory del client su disco. E lo si misuri con il pannello anziché con l’helper di pulizia del proprio test, perché l’helper può portarsi dietro lo stesso malinteso e allora la macchina sembra pulita mentre l’integrazione perde.
La regola di eliminazione sicura in sé è una riga sola: rimuovere il sito web; rimuovere il client proprietario solo se non gli resta alcun sito web. ISPConfig ha una chiamata che elimina un client e tutto ciò che sta sotto di lui, e su un account importato porterebbe con sé gli altri siti del cliente. Non eliminare mai più di quanto è stato chiesto.
Nulla è istantaneo
Il suo pannello è raggiungibile solo attraverso l’agente all’interno della sua 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 finché il suo stato non è definitivo: completato, fallito, scaduto o annullato. La lettura non funziona mai così, perché un inventario o una fattura viene da un database e non dal suo host.
La conseguenza pratica per un hook di fatturazione: non segnare l’ordine come completato sulla risposta di accettazione. Tutto ciò che crea qualcosa accetta anche una chiave di idempotenza di propria composizione, quindi un webhook rinviato e un doppio clic non costano nulla.
Dove vive la fattura
Provibr non fattura ai suoi clienti, non li sollecita e non sa quanto addebita loro. Quella relazione è sua.
Ciò che Provibr fattura è la capacità che lei riserva: quanti account di hosting può far girare contemporaneamente, a un prezzo unitario che cala a fasce man mano che il numero cresce. Per un account di hosting non esiste lo stato «arrestato»: esistono attivo e sospeso, e un account sospeso non conta. Quindi l’azione di sollecito che voleva già eseguire per ragioni commerciali è anche quella che libera lo slot che sta pagando.
Ciò che non è automatizzato
Provibr gestisce gli account, non il pannello. Non installa ISPConfig, non lo aggiorna e non tocca caselle di posta, database o DNS: un cliente che elimina la propria casella di posta lo fa senza che nulla al di sopra del pannello lo sappia o se ne curi. Non c’è console per un account di hosting, non c’è reinstallazione e non c’è sospensione parziale.
Se si trova a uno stadio precedente rispetto alla parte di fatturazione, il pezzo di accompagnamento è Vendere hosting web con ISPConfig, che tratta l’utente remoto, la delimitazione dei permessi e il modello con un pannello e più server. Le credenziali, il certificato e la schermata dei pacchetti sono documentati sulla pagina di documentazione di ISPConfig.
Domande frequenti
Perché ogni chiamata all’API di ISPConfig restituisce HTTP 200?
Perché la sua API remota porta il verdetto nel corpo anziché nella riga di stato. Il campo code dice ok, remote_fault, invalid_method o permission_denied. Un client che si fida dello stato legge un fallimento di autenticazione come una risposta vuota riuscita.
Un account ISPConfig è un cliente o un sito web?
Un sito web. ISPConfig tiene separati il client, che è un accesso al pannello con dei limiti, e il web_domain, che è un sito ospitato, e un client può possedere più siti. Un account di hosting qui è identificato dal suo dominio.
Un sistema di fatturazione può sospendere due volte lo stesso sito ISPConfig?
Sì. La seconda chiamata risponde ok con zero righe modificate, il che non è un errore. Anche la riattivazione è idempotente, quindi un ciclo notturno di solleciti non ha bisogno di uno stato proprio.
L’eliminazione di un account ISPConfig rimuove l’accesso al pannello del cliente?
Deve farlo, e vale la pena verificarlo sulla propria installazione. Il comportamento corretto è rimuovere il sito web e poi il client proprietario solo quando a quel client non resta alcun sito web. Un’eliminazione che lascia dietro il client lascia sul nodo il nome, l’indirizzo e la password del cliente.
Posso cambiare un pacchetto ISPConfig da un sistema di fatturazione?
Sì. Un pacchetto è un client template, e assegnarne uno diverso sposta i limiti immediatamente. Inviare nell’aggiornamento solo il nuovo template; un payload più completo è stato misurato fallire senza un messaggio di errore utilizzabile.
