Vai al contenuto
JoeCMS Scarica 3.1.5
Manuale · 03

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

  1. use_cache(false) in cima. Senza, il CMS può servire una risposta vecchia. (use_cache() è definita in library/gallery/common.php.)
  2. Controllo accessi esplicito: checkUserRights(false) per la sessione (hook.php), il token Bearer per l'API, il secret condiviso per i webhook, is_admin per l'admin.
  3. Il proprietario dei dati si ricava dalla sessione o dal token, mai dal body.
  4. echo ffCommon_jsonenc($data, true) — il secondo parametro manda anche l'header Content-Type: application/json (ff/common.php:1090).
  5. exit finale. 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:

AspettoCome si fa
Autenticazionesecret condiviso in query string (?secret=…) confrontato con hash_equals, oppure firma HMAC dell'header se il provider la espone
Metodosolo POST; qualunque altro verbo → 405
Idempotenzai 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%
Diagnosticauna riga di log per ogni chiamata, con esito: hit / unauthorized / no-refs / rows:0. Senza, il triage è impossibile

Triage tipico, con quel log:

SintomoSignificato
nessun hitil provider non sta chiamando l'URL
unauthorizedil secret non combacia
rows:0 / no-refsarriva 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_id del tipo entita_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:

CasoEsecutore
opt.async = trueJobs::getInstance()->add(...) — accodato, poi Jobs::async("/api/jobs/tools/run")
tipo srvJobs::srv($path, $params) — servizio interno
tipo apiJobs::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
adminprocess_admin_toolbar(...) — la barra di modifica in hover sul frontend
cacheJobs::async("/api/cache/refresh")
notify / notifyDeliveredNotifier::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:

MetodoCosa 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) e exit
  • [ ] 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)