Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 05

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

ServeStrumentoPerché
"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::asyncl'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é

  1. Secret in query string confrontato con hash_equals. Un job senza secret è un endpoint di scrittura pubblico.
  2. GET_LOCK MySQL con timeout 0. 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.
  3. 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.
  4. 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 20 deve 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 (abilitato on/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.

JobScopoFrequenzaSe non gira
(nessuno nel repo base)

3. I job di sistema ereditati

conf/gallery/job/ contiene quattro job dell'upstream VGallery:

JobCosa faStato
pingnotifica i motori di ricerca della sitemap aggiornatalegacy: parecchi dei servizi pingati non esistono più
updateinterroga l'updater remotoinerte: MASTER_SITE è neutralizzata
diagnosticverifica cache, dizionario, config, uploads, thumbutile come check manuale
reset_cartspulizia carrelli abbandonatirilevante 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 include library/gallery/common.php, che presuppone un'istanza di cm.
  • HTTP_HOST va predisposto prima di config.php: è lui a decidere se caricare config.local.php o config.remote.php, e mezzo framework legge $_SERVER senza 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 cm a 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=always lo 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=55 più 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_log non è 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.