Cron, job e worker
Tre modi di far lavorare il sistema quando nessuno sta guardando: un cron HTTP, una coda di job interna, un processo longevo. Servono a cose diverse, e sceglierne uno sbagliato si paga.
1. Quale dei tre
| Serve | Strumento | Perché |
|---|---|---|
| "ogni N minuti fai X" | cron HTTP (§2) | non richiede accesso shell: funziona su qualunque hosting con schedulatore curl |
| "fai X, ma non adesso e non davanti all'utente" | coda job (§4) o Jobs::async | l'utente non aspetta; l'effetto arriva poco dopo |
| "stai sempre in ascolto / polla un servizio esterno a cadenza sub-minuto" | worker CLI (§5) | il cron ha granularità di 1 minuto e paga il bootstrap a ogni giro |
Regola pratica: partire dal cron. Un worker è un servizio da installare, sorvegliare e riavviare; va introdotto quando il cron dimostra di non bastare, non prima.
2. Cron HTTP: un job è una pagina
I job schedulati sono pagine come le altre (vedi 02 §1):
contents/cronjob/<nome>.php → GET /cronjob/<nome>?key=<secret>
La cartella contents/cronjob/ esiste già nel repo, vuota: è il posto previsto.
Pattern da replicare:
<?php
use_cache(false);
// 1 — SECRET: il job è raggiungibile via HTTP, quindi da chiunque
$cronSecret = (string) (defined("JC_CRON_SECRET") ? JC_CRON_SECRET : "");
if ($cronSecret === "" || !hash_equals($cronSecret, (string)($_GET["key"] ?? ""))) {
http_response_code(403); echo "forbidden"; exit;
}
$db = ffDB_Sql::factory();
// 2 — LOCK: due esecuzioni sovrapposte sono la norma, non l'eccezione
$db->query("SELECT GET_LOCK('jc_coda', 0) AS l");
$db->nextRecord();
if ((int)$db->getField("l", "Number", true) !== 1) { echo "busy"; exit; }
try {
// 3 — BATCH limitato: mai "tutto quello che c'è"
$limite = 200;
// ... lavoro ...
// 4 — LOG dell'esito
// INSERT INTO cm_jc_cron_log (job, esito, elementi, eseguito_il) VALUES (...)
} finally {
$db->query("SELECT RELEASE_LOCK('jc_coda')");
}
echo "ok";
exit;
I quattro presidi, e perché
- Secret in query string confrontato con
hash_equals. Un job senza secret è un endpoint di scrittura pubblico. GET_LOCKMySQL con timeout0. Se il giro precedente non ha finito, il nuovo esce subito invece di raddoppiare il lavoro. Un lock per job, non uno globale: job diversi non devono contendere.- Batch limitato con
LIMIT. Un job che prova a smaltire l'arretrato intero va in timeout, e il timeout lo lascia a metà. Meglio N giri corti. - Log su tabella con esito e conteggio. Senza, alla domanda "il cron gira?" non si sa rispondere.
SELECT * FROM <tabella_log> ORDER BY ID DESC LIMIT 20deve bastare.
Altri accorgimenti che si imparano in esercizio
- Skip esplicito se la migration non è applicata. Un job che gira su uno schema vecchio deve uscire con "migration mancante", non andare in fatal ogni minuto.
- Degradare, non bloccare. Se un provider esterno non risponde, si logga e si riprova al giro dopo.
- Quiet hours, se il job manda comunicazioni: non spedire alle 3 di notte.
- Interruttore di spegnimento in configurazione (
abilitatoon/off), che non richieda un deploy. - Idempotenza: il job può essere rieseguito sullo stesso intervallo (riavvio, doppia schedulazione, retry dello schedulatore). Un registro anti-duplicato (una riga per
(destinatario, tipo, periodo)con chiave unica) è più affidabile di un "conta e confronta".
Schedulare
Dal pannello dell'hosting (cron via curl):
*/5 * * * * curl -fsS "https://TUO-DOMINIO/cronjob/<nome>?key=<secret>" > /dev/null
Documentare in una tabella, nel repo, quali job esistono, con che frequenza e cosa succede se non girano: è l'informazione che serve il giorno del trasloco su un altro hosting.
| Job | Scopo | Frequenza | Se non gira |
|---|---|---|---|
| (nessuno nel repo base) |
3. I job di sistema ereditati
conf/gallery/job/ contiene quattro job dell'upstream VGallery:
| Job | Cosa fa | Stato |
|---|---|---|
ping | notifica i motori di ricerca della sitemap aggiornata | legacy: parecchi dei servizi pingati non esistono più |
update | interroga l'updater remoto | inerte: MASTER_SITE è neutralizzata |
diagnostic | verifica cache, dizionario, config, uploads, thumb | utile come check manuale |
reset_carts | pulizia carrelli abbandonati | rilevante solo con e-commerce attivo |
Non sono schedulati di default e scrivono il loro esito come notifica di backend (write_notification). Esiste anche un meccanismo di autoload per convenzione: check_function("job_<nome>") carica library/gallery/job/<nome>.php oppure modules/<modulo>/library/job/<nome>.php (library/gallery/common.php, righe ~138-146).
4. La coda di job interna (Jobs)
vendor/hcore/jobs/Jobs.php implementa una coda persistente con schedulazione e ripetizione.
Jobs::getInstance()->add($source, $params, $schedule, $repeat, $priority);
Jobs::getInstance()->run(); // esegue i job dovuti
Jobs::getInstance()->ps(); // stato della coda
Jobs::getInstance()->forceRun($kid); // forza un job
Jobs::setScript($callback, $schedule, $repeat);
Esecutori per tipo: API interna, servizio, richiesta HTTP, script, funzione, oggetto (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj).
Guardie nella classe: SOCKET = 10, TIMEOUT = 60, ANTIFLOOD = 4 secondi fra due esecuzioni, DELAY_SCHEDULE = 3600 per il rischedulo dopo errore, REPEAT = "1week".
E la primitiva fire-and-forget:
Jobs::async("/api/cache/refresh", array("url" => $_SERVER["HTTP_REFERER"]));
apre un socket verso il proprio host, scrive la richiesta e non aspetta la risposta. Nel repo è usata da library/gallery/system/trace.php e dal bus dei servizi (vedi 03 §4).
Quando usarla e quando no.
Jobs::asyncè perfetta per "rinfresca la cache dopo aver risposto". Per il lavoro che deve essere fatto — invii, addebiti, notifiche — serve qualcosa che lasci traccia e sia riprovabile: la coda persistente, o una tabella di coda propria smaltita da un cron. Il socket fire-and-forget non garantisce niente: se il processo chiamato muore, nessuno se ne accorge.
C'è anche library/rabbitMQ/ fra le librerie: broker esterno, non cablato in questo repo. Un progetto che ne ha davvero bisogno lo aggancia, ma per la stragrande maggioranza dei casi una tabella di coda + cron è più semplice da gestire e più facile da ispezionare.
5. Worker longevo (CLI)
Quando serve una cadenza sotto il minuto, o uno stato in memoria fra un giro e l'altro, si esce dal web: uno script PHP in bin/ avviato da systemd (o da un cron di ripiego).
Lezioni che valgono per qualunque worker su questo stack:
- Un bootstrap CLI dedicato. Da riga di comando il ciclo di pagina non gira: le classi arrivano dall'autoloader, ma le funzioni di
ff/common.php(ffCommon_dirname,ffCommon_jsonenc) no. Vanno incluse esplicitamente. Non si includelibrary/gallery/common.php, che presuppone un'istanza dicm. HTTP_HOSTva predisposto prima diconfig.php: è lui a decidere se caricareconfig.local.phpoconfig.remote.php, e mezzo framework legge$_SERVERsenza verificare le chiavi.FF_DISK_PATHè il percorso del server. L'installer ci scrive/var/www/…, che in locale non esiste: un worker che costruisce path su quella costante fallisce fuori dal server. Meglio una costante propria ricavata da__DIR__, preferita quando c'è.- Caricare solo il modulo che serve: gli altri agganciano eventi al ciclo di pagina e da CLI non trovano un
cma cui agganciarsi. - Le cache statiche vanno scartate periodicamente. Le classi di configurazione sono pensate per la durata di una richiesta HTTP: in un processo che vive un'ora resterebbero congelate al valore letto all'avvio, e cambiare una soglia da backend non avrebbe effetto.
- Il worker esce da sé dopo un tempo massimo (es. un'ora) e
Restart=alwayslo rialza. Un'uscita con codice 0 ogni ora è il comportamento previsto: è il modo più semplice di non avere un problema di memoria fra due mesi in un processo PHP longevo. - Non gira come root: gli serve leggere
config.remote.php(0640, dell'utente del sito). Girare come quell'utente fa tornare i permessi senza allargarli. - Ripiego cron identico nel codice:
--durata=55piùflock -n.flockè la parte che conta: due worker in parallelo raddoppiano le chiamate.
Se il worker mantiene uno stato letto dal frontend (cache di stato in tabella), due accorgimenti ripagano subito:
- battito e lettura nella stessa chiamata: un unico endpoint che dice "questo schermo è aperto" e restituisce lo stato. Separarli è il doppio del traffico per la stessa informazione;
- restituire sempre
letto_il+ora_server: senza sapere quando è stato letto, un dato di tre secondi prima è inutilizzabile per un client che deve interpolare.
6. Manutenzione: cosa si pota e cosa no
Un sistema che gira accumula. Vale la pena avere un job di manutenzione che pota, con criterio:
- si potano i log applicativi (dalla coda, tenendo le ultime N righe), gli stati temporanei scaduti, i token OAuth scaduti, le cache di contenuti esterni;
- non si potano i registri anti-duplicato (un
email_lognon è uno storico: è ciò che impedisce di rimandare la stessa comunicazione), gli audit di movimenti e pagamenti, le righe a cui punta un'altra tabella; - non si chiudono d'ufficio gli oggetti in stato intermedio (ordini abbandonati, bozze): si contano e si mostrano. La decisione è di chi gestisce, non del job.
⚠️ AUTO_INCREMENT: cancellare righe non fa tornare indietro il contatore. Un test che crea e cancella mille righe lascia il prossimo ID a 1001. Non è un problema, ma è una domanda che prima o poi arriva.