Aller au contenu
JoeCMS Télécharger 3.1.5
Manuel · 03

Services HTTP et webhooks

Tout ce qui répond des données au lieu du HTML : endpoints JSON pour le front-end, orchestration de plusieurs appels en une seule requête, réception de webhooks de fournisseurs externes.

1. /srv/<zone>/<action> : l'endpoint de projet

Le module cms-common réécrit /srv/(.*) vers /applets/services/$1 (modules/cms-common/conf/routing_table.xml). Donc :

applets/services/liste/elenco.php   →   POST /srv/liste/elenco

Sans cette règle /srv/... finirait dans les services système du CMS (conf/gallery/sys/services, §3) et répondrait avec la page d'erreur.

Un service est un fichier inclus qui imprime du JSON et se termine. Ce n'est pas une classe, il n'a pas d'interface : sa forme est garantie par les conventions.

<?php
/**
 * Liste des éléments de l'utilisateur courant.
 * Output (JSON) : { ok, rows: [ ... ], error }
 */
use_cache(false);                              // 1

$db  = ffDB_Sql::factory();
$ID  = checkUserRights(false);                 // 2 — false = ne pas rediriger : répondre en JSON
$ok  = false; $rows = array(); $error = '';

if ($ID) {
    // 3 — le propriétaire des données vient de la session, JAMAIS du body
    // ... logique ...
    $ok = true;
} else {
    $error = 'non_autenticato';
}

echo ffCommon_jsonenc(array('ok' => $ok, 'rows' => $rows, 'error' => $error), true);   // 4
exit;                                                                                   // 5

Les cinq règles non négociables

  1. use_cache(false) en tête. Sans lui, le CMS peut servir une réponse périmée. (use_cache() est définie dans library/gallery/common.php.)
  2. Contrôle d'accès explicite : checkUserRights(false) pour la session (hook.php), le token Bearer pour l'API, le secret partagé pour les webhooks, is_admin pour l'admin.
  3. Le propriétaire des données se déduit de la session ou du token, jamais du body.
  4. echo ffCommon_jsonenc($data, true) — le second paramètre envoie aussi l'en-tête Content-Type: application/json (ff/common.php:1090).
  5. exit final. Sans lui, le CMS continue le cycle de page et ajoute le layout HTML après le JSON.

Codes d'erreur stables

Il vaut mieux que error soit un code (non_autenticato, limite_raggiunto, dati_non_validi, non_trovato), pas une phrase : le texte visible se décide côté interface, et change avec la langue.

Endpoints partagés avec l'API publique

Les endpoints de l'API publique peuvent être les mêmes fichiers (applets/services/api/*.php), accessibles aussi depuis /api/1.0/<endpoint> grâce au front controller de api/1.0/index.php : une seule implémentation, deux portes d'entrée. Le dépôt contient déjà applets/services/api/auth.php. Voir 04 — API publique.

2. Webhooks : un service avec une authentification différente

Un webhook est un /srv/<fournisseur>/webhook avec quatre différences par rapport à un endpoint de session :

AspectComment faire
Authentificationsecret partagé dans la query string (?secret=…) comparé avec hash_equals, ou signature HMAC de l'en-tête si le fournisseur en expose une
MéthodePOST uniquement ; tout autre verbe → 405
Idempotenceles fournisseurs répètent les événements : l'effet doit être répétable. Le schéma éprouvé consiste à incrémenter un compteur seulement quand la ligne par destinataire passe de 0→1 (UPDATE … SET flag=1 WHERE id=? AND flag=0 + contrôle de affectedRows()), sinon on dépasse les 100 %
Diagnosticune ligne de log par appel, avec le résultat : hit / unauthorized / no-refs / rows:0. Sans elle, le tri est impossible

Tri typique, avec ce log :

SymptômeSignification
aucun hitle fournisseur n'appelle pas l'URL
unauthorizedle secret ne correspond pas
rows:0 / no-refsça arrive mais ne met rien à jour : les références du payload ne correspondent à rien

Deux astuces qui font gagner des heures :

  • corrélation autonome : transmettre au fournisseur, à l'envoi, une référence propre (X-Entity-Ref-ID, tag, correlation_id du type entite_x|detail_y) et la relire au retour. Dépendre seulement de l'ID du fournisseur, c'est ne pas pouvoir réconcilier quand le payload change ;
  • URL de callback par message plutôt que la configuration dans le tableau de bord du fournisseur, quand il le permet : l'URL voyage avec le message, et un environnement de test ne vole pas les rapports de la production (ou les vole, si l'URL est fixée sur le domaine de production : c'est un effet à connaître avant, pas après).

⚠️ Un webhook ne doit pas finir dans contents/ comme s'il était une page : la remontée du routeur (voir 01 §4) ferait répondre 200 à des chemins erronés.

3. Le bus des services système : /srv/request

conf/gallery/sys/services/request/index.php est un orchestrateur : il reçoit dans POST params un JSON de plusieurs appels et les exécute en une seule requête, en renvoyant une table nom_service → réponse.

{
  "/srv/share/check-like": { "params": { "id": 12 } },
  "/api/1.0/get-tag-list": { "params": {} },
  "google.pagespeed":      { "opt": { "url": "https://…" }, "params": { "url": "…" } }
}

Comment il décide quoi faire de chaque entrée :

CasExécuteur
opt.async = trueJobs::getInstance()->add(...) — mis en file, puis Jobs::async("/api/jobs/tools/run")
type srvJobs::srv($path, $params) — service interne
type apiJobs::api($path, $params) — API interne
URL http…Jobs::req($url, $params, $method, $response) — appel externe, avec possibilité d'extraire un fragment de la réponse (response.source → response.target)
$schema["page"]["/x"]["group"] == "shard"system_layer_shards() — composition de fragments de page
adminprocess_admin_toolbar(...) — la barre d'édition au survol sur le front-end
cacheJobs::async("/api/cache/refresh")
notify / notifyDeliveredNotifier::response() / Notifier::delivered() — voir 06

À quoi ça sert, en pratique : une page en cache peut rester en cache et demander au bus, en un seul appel, les quelques morceaux qui dépendent de l'utilisateur (toolbar admin, notifications, compteurs, fragments personnalisés). C'est pourquoi le bus vide page_js/page_css : la réponse n'est pas une page.

⚠️ C'est du code upstream, plein de branches commentées et de parties marquées todo. L'utiliser tel quel pour les cas prévus (notifications, toolbar, shards) est raisonnable ; construire dessus une nouvelle architecture demande d'abord de le lire en entier.

4. Jobs : appeler quelque chose sans l'attendre

vendor/hcore/jobs/Jobs.php offre quatre primitives statiques, utilisables aussi hors du bus :

MéthodeCe qu'elle fait
Jobs::srv($path, $params)invoque un service interne et renvoie sa réponse
Jobs::api($path, $params)invoque un endpoint de l'API interne
Jobs::req($url, $params, $method, $response)appel HTTP externe, avec extraction optionnelle d'un fragment
Jobs::async($url, $params)fire-and-forget : ouvre un socket vers son propre hôte, écrit la requête et n'attend pas la réponse

Jobs::async() reconstruit l'URL absolue à partir du serveur courant, propage referer, locale, user agent et cookies. Constantes de garde dans la classe : SOCKET = 10 (sockets concurrents), TIMEOUT = 60, ANTIFLOOD = 4 secondes entre deux exécutions, DELAY_SCHEDULE = 3600 pour la replanification après erreur, REPEAT = "1week".

Il y a aussi une file persistante (->add(), ->run(), ->ps(), ->forceRun(), ->renew()) avec des exécuteurs par type (controller_api, controller_service, controller_request, controller_script, controller_func, controller_obj) et son propre stockage. Voir 05 — Cron, jobs et workers pour savoir quand l'utiliser et quand non.

Usages dans le dépôt aujourd'hui : library/gallery/system/trace.php (Jobs::async("/api/cache/refresh", …)) et le bus des services.

5. Checklist d'un nouvel endpoint

  • [ ] use_cache(false) comme première instruction
  • [ ] authentification explicite et déclarée dans le commentaire d'en-tête
  • [ ] le tenant/propriétaire n'arrive pas du body
  • [ ] méthode HTTP vérifiée (un GET qui écrit est un problème, pas un raccourci)
  • [ ] sortie avec ffCommon_jsonenc($data, true) et exit
  • [ ] erreurs avec un code stable
  • [ ] s'il écrit : transaction ou garde d'idempotence
  • [ ] si c'est un webhook : secret avec hash_equals, log du résultat, effet répétable
  • [ ] testé sans session (il doit répondre en JSON, pas une page de connexion)