Tâches planifiées

Le scheduler du SDK bext exécute des tâches récurrentes pour une application PRISM. Vous enregistrez une entrée nommée avec un cron/planning, et à chaque cadence le scheduler envoie une requête POST à un handler que vous possédez. Il s'atteint via le SDK loopback à http://127.0.0.1/__bext/sdk/scheduler/*, authentifié par l'en-tête X-Bext-App-Id (voir Vue d'ensemble du SDK).

Astuce

C'est la manière recommandée d'exécuter du travail de style cron. N'utilisez pas le crontab système quand le scheduler suffit — voir Préférer le scheduler au cron système.

Endpoints

Méthode Chemin Objet
POST /__bext/sdk/scheduler/register Créer ou mettre à jour une entrée de planning
GET /__bext/sdk/scheduler/list Lister les entrées de planning de cette application
POST /__bext/sdk/scheduler/cancel Annuler une entrée

Register

POST http://127.0.0.1/__bext/sdk/scheduler/register
X-Bext-App-Id: <app-id>
Content-Type: application/json

Champs du corps :

Champ Requis Notes
name oui Nom d'entrée unique pour cette application
schedule / cron oui La cadence — une expression cron (validée à l'enregistrement)
kind non Type d'entrée
command / handler_url / task oui (l'un des trois) Ce qu'il faut exécuter à chaque cadence
payload non Transmis à la cible
cwd non Répertoire de travail (pour les entrées command)
timeout_secs non Délai maximal par exécution
enabled non Mettre false pour enregistrer une entrée désactivée

L'expression cron est validée au moment de l'enregistrement — une expression invalide est rejetée.

Pour une application PRISM, la cible habituelle est handler_url : à chaque cadence le scheduler envoie une requête POST à l'URL de votre handler. Enregistrez le handler comme l'une des routes propres à votre application.

// enregistre un handler de rapport quotidien
await fetch("http://127.0.0.1/__bext/sdk/scheduler/register", {
  method: "POST",
  headers: {
    "X-Bext-App-Id": "<app-id>",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    name: "daily-report",
    cron: "0 6 * * *",
    handler_url: "https://<app>.inklura.fr/api/cron/daily-report?key=<secret>",
  }),
});

List

GET http://127.0.0.1/__bext/sdk/scheduler/list
X-Bext-App-Id: <app-id>

Renvoie les entrées enregistrées de cette application.

Cancel

POST http://127.0.0.1/__bext/sdk/scheduler/cancel
X-Bext-App-Id: <app-id>
Content-Type: application/json

{ "name": "daily-report" }

Authentifier les appels HTTP planifiés

Le scheduler envoie une requête POST à votre handler_url depuis la plateforme, votre route handler doit donc décider elle-même s'il faut faire confiance à l'appel. La convention courante est un secret partagé transporté dans la chaîne de requête : enregistrez la route cron avec ?key=<secret> et faites vérifier ce key par le handler avant tout travail.

// src/app/api/cron/daily-report/route.ts
export async function POST(req: Request) {
  const key = new URL(req.url).searchParams.get("key");
  if (key !== process.env.CRON_SECRET) {
    return new Response("forbidden", { status: 403 });
  }
  // …exécuter la tâche…
  return new Response("ok");
}

De vraies applications PRISM enregistrent leurs routes cron ainsi — par exemple daily-report, pacing-watchdog, flight-end et monthly-billing.

Attention

Le secret figure dans l'URL, alors traitez-le comme tout secret d'URL : tenez-le hors des logs, faites-le tourner s'il fuite, et exécutez toujours les routes cron via HTTPS sur votre vhost public.

Préférer le scheduler au cron système

Convention de la plateforme : n'utilisez pas le cron système — utilisez le scheduler bext (ou la queue). Le scheduler est géré par application, validé, listable et annulable via le SDK ; une entrée de crontab système est invisible pour la plateforme et survit à l'application à laquelle elle était destinée.

Travail planifié de longue durée

Le rôle du scheduler est de se déclencher à la cadence, pas de s'exécuter longtemps. Si le travail déclenché par un planning est lourd ou lent, faites en sorte que le handler alimente la queue ou délègue au task-executor à chaud plutôt que de bloquer l'appel cron — voir SDK → Tasks.

Connexe : automatisation des workflows (company-manager)

Indépendamment du scheduler bext, le backend company-manager déclare une file BullMQ workflow-scheduled (aux côtés de workflow-execution, workflow-node et workflow-webhook) qui pilote les étapes basées sur le temps dans son propre moteur d'automatisation des workflows. C'est interne à la plateforme et ce n'est pas la même surface que le scheduler orienté application décrit ici — voir Vue d'ensemble des événements.

Voir aussi