Servizi HTTP e webhook
Tutto ciò che risponde dati invece di HTML: endpoint JSON per il frontend, orchestrazione di più chiamate in una sola request, ricezione di webhook da provider esterni.
1. /srv/<area>/<azione>: l'endpoint di progetto
Il modulo cms-common riscrive /srv/(.*) su /applets/services/$1 (modules/cms-common/conf/routing_table.xml). Quindi:
applets/services/liste/elenco.php → POST /srv/liste/elenco
Senza quella regola /srv/... finirebbe nei servizi di sistema del CMS (conf/gallery/sys/services, §3) e risponderebbe con la pagina d'errore.
Un servizio è un file incluso che stampa JSON e termina. Non è una classe, non ha un'interfaccia: la forma la garantiscono le convenzioni.
<?php
/**
* Elenco delle voci dell'utente corrente.
* Output (JSON): { ok, rows: [ ... ], error }
*/
use_cache(false); // 1
$db = ffDB_Sql::factory();
$ID = checkUserRights(false); // 2 — false = non redirigere: rispondi JSON
$ok = false; $rows = array(); $error = '';
if ($ID) {
// 3 — il proprietario dei dati viene dalla sessione, MAI dal body
// ... logica ...
$ok = true;
} else {
$error = 'non_autenticato';
}
echo ffCommon_jsonenc(array('ok' => $ok, 'rows' => $rows, 'error' => $error), true); // 4
exit; // 5
Le cinque regole non negoziabili
use_cache(false)in cima. Senza, il CMS può servire una risposta vecchia. (use_cache()è definita inlibrary/gallery/common.php.)- Controllo accessi esplicito:
checkUserRights(false)per la sessione (hook.php), il token Bearer per l'API, il secret condiviso per i webhook,is_adminper l'admin. - Il proprietario dei dati si ricava dalla sessione o dal token, mai dal body.
echo ffCommon_jsonenc($data, true)— il secondo parametro manda anche l'headerContent-Type: application/json(ff/common.php:1090).exitfinale. Senza, il CMS continua il ciclo di pagina e appende il layout HTML dopo il JSON.
Codici di errore stabili
Conviene che error sia un codice (non_autenticato, limite_raggiunto, dati_non_validi, non_trovato), non una frase: il testo visibile si decide lato interfaccia, e cambia con la lingua.
Endpoint condivisi con l'API pubblica
Gli endpoint dell'API pubblica possono essere gli stessi file (applets/services/api/*.php), raggiungibili anche da /api/1.0/<endpoint> grazie al front controller in api/1.0/index.php: una sola implementazione, due porte d'ingresso. Nel repo c'è già applets/services/api/auth.php. Vedi 04 — API pubblica.
2. Webhook: un servizio con un'autenticazione diversa
Un webhook è un /srv/<provider>/webhook con quattro differenze rispetto a un endpoint di sessione:
| Aspetto | Come si fa |
|---|---|
| Autenticazione | secret condiviso in query string (?secret=…) confrontato con hash_equals, oppure firma HMAC dell'header se il provider la espone |
| Metodo | solo POST; qualunque altro verbo → 405 |
| Idempotenza | i provider ripetono gli eventi: l'effetto va reso ripetibile. Il pattern collaudato è incrementare un contatore solo quando la riga per-destinatario transisce 0→1 (UPDATE … SET flag=1 WHERE id=? AND flag=0 + controllo di affectedRows()), altrimenti si superano i 100% |
| Diagnostica | una riga di log per ogni chiamata, con esito: hit / unauthorized / no-refs / rows:0. Senza, il triage è impossibile |
Triage tipico, con quel log:
| Sintomo | Significato |
|---|---|
nessun hit | il provider non sta chiamando l'URL |
unauthorized | il secret non combacia |
rows:0 / no-refs | arriva ma non aggiorna: i riferimenti nel payload non corrispondono a nulla |
Due accorgimenti che fanno risparmiare ore:
- correlazione self-contained: passare al provider, in fase di invio, un riferimento proprio (
X-Entity-Ref-ID,tag,correlation_iddel tipoentita_x|dettaglio_y) e leggerlo al ritorno. Dipendere solo dall'ID del provider significa non poter riconciliare quando il payload cambia; - URL di callback per-messaggio invece della configurazione nella dashboard del provider, quando il provider lo consente: l'URL viaggia col messaggio, e un ambiente di prova non ruba i report della produzione (o li ruba, se l'URL è cablato sul dominio di produzione: è un effetto da conoscere prima, non dopo).
⚠️ Un webhook non deve finire in contents/ come se fosse una pagina: la risalita del router (vedi 01 §4) farebbe rispondere 200 a percorsi sbagliati.
3. Il bus dei servizi di sistema: /srv/request
conf/gallery/sys/services/request/index.php è un orchestratore: riceve in POST params un JSON di più chiamate e le esegue in una sola request, restituendo una mappa nome_servizio → risposta.
{
"/srv/share/check-like": { "params": { "id": 12 } },
"/api/1.0/get-tag-list": { "params": {} },
"google.pagespeed": { "opt": { "url": "https://…" }, "params": { "url": "…" } }
}
Come decide cosa fare di ogni voce:
| Caso | Esecutore |
|---|---|
opt.async = true | Jobs::getInstance()->add(...) — accodato, poi Jobs::async("/api/jobs/tools/run") |
tipo srv | Jobs::srv($path, $params) — servizio interno |
tipo api | Jobs::api($path, $params) — API interna |
URL http… | Jobs::req($url, $params, $method, $response) — chiamata esterna, con possibilità di estrarre un frammento dalla risposta (response.source → response.target) |
$schema["page"]["/x"]["group"] == "shard" | system_layer_shards() — composizione di frammenti di pagina |
admin | process_admin_toolbar(...) — la barra di modifica in hover sul frontend |
cache | Jobs::async("/api/cache/refresh") |
notify / notifyDelivered | Notifier::response() / Notifier::delivered() — vedi 06 |
A cosa serve, in pratica: una pagina in cache può restare in cache e chiedere al bus, in una singola chiamata, i pochi pezzi che dipendono dall'utente (toolbar admin, notifiche, contatori, frammenti personalizzati). È il motivo per cui il bus azzera page_js/page_css: la risposta non è una pagina.
⚠️ È codice upstream, ricco di rami commentati e di parti marcate todo. Usarlo così com'è per i casi previsti (notifiche, toolbar, shard) è ragionevole; costruirci sopra una nuova architettura richiede prima di leggerlo per intero.
4. Jobs: chiamare qualcosa senza aspettarlo
vendor/hcore/jobs/Jobs.php offre quattro primitive statiche, usabili anche fuori dal bus:
| Metodo | Cosa fa |
|---|---|
Jobs::srv($path, $params) | invoca un servizio interno e ne restituisce la risposta |
Jobs::api($path, $params) | invoca un endpoint dell'API interna |
Jobs::req($url, $params, $method, $response) | chiamata HTTP esterna, con estrazione opzionale di un frammento |
Jobs::async($url, $params) | fire-and-forget: apre un socket verso il proprio host, scrive la richiesta e non aspetta la risposta |
Jobs::async() ricostruisce l'URL assoluto dal server corrente, propaga referer, locale, user agent e cookie. Costanti di guardia nella classe: SOCKET = 10 (socket concorrenti), TIMEOUT = 60, ANTIFLOOD = 4 secondi fra due esecuzioni, DELAY_SCHEDULE = 3600 per il rischedulo dopo errore, REPEAT = "1week".
C'è anche una coda persistente (->add(), ->run(), ->ps(), ->forceRun(), ->renew()) con esecutori per tipo (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj) e storage proprio. Vedi 05 — Cron, job e worker per quando conviene usarla e quando no.
Usi nel repo, oggi: library/gallery/system/trace.php (Jobs::async("/api/cache/refresh", …)) e il bus dei servizi.
5. Checklist di un endpoint nuovo
- [ ]
use_cache(false)come prima istruzione - [ ] autenticazione esplicita e dichiarata nel commento di testa
- [ ] il tenant/proprietario non arriva dal body
- [ ] metodo HTTP verificato (un GET che scrive è un problema, non una scorciatoia)
- [ ] output con
ffCommon_jsonenc($data, true)eexit - [ ] errori con codice stabile
- [ ] se scrive: transazione o guardia di idempotenza
- [ ] se è un webhook: secret con
hash_equals, log dell'esito, effetto ripetibile - [ ] provato senza sessione (deve rispondere JSON, non una pagina di login)