Tasks & Planificateur

Le task-executor exécute les traitements longs hors de l'isolat de rendu — il n'y a pas de deadline de rendu et toute la concurrence d'I/O est disponible. Contrairement à la Queue, les tasks disposent d'un statut, d'une progression et de résultats intégrés. Le planificateur déclenche des traitements selon un planning cron.

Le task-executor chaud

Un processus worker est lancé à chaud et réutilisé. Vous écrivez vos tasks avec defineTask et démarrez le worker avec startTaskWorker depuis @bext-stack/framework/task-worker :

import { defineTask, startTaskWorker } from "@bext-stack/framework/task-worker";

defineTask("generate-report", async (ctx, payload) => {
  ctx.log("starting", payload);

  const rows = await ctx.db.all("SELECT * FROM sales WHERE month = ?", [payload.month]);
  await ctx.progress({ pct: 50 });

  const url = await buildPdf(rows);
  await ctx.kv.set(`report:${ctx.jobId}`, { url });

  return { url }; // becomes the job's `result`
});

startTaskWorker();

Le ctx de la task

ctx étend l'intégralité de BextSdk plus des champs propres aux tasks :

Sur ctx Ce que c'est
ctx.kv, ctx.db, ctx.queue, … L'intégralité de BextSdk (tous les namespaces du SDK).
ctx.appId L'identifiant de l'application propriétaire.
ctx.jobId L'identifiant de ce job.
ctx.signal Un AbortSignal — déclenché en cas d'annulation/timeout.
ctx.progress(data) Rapporter la progression (lisible via /tasks/status).
ctx.log(...) Journaliser depuis la task.

startTaskWorker() se lie à un port loopback et affiche BEXT_TASK_READY <port> sur stdout ; le superviseur Rust le lance avec bun run et le maintient à chaud.

Exécuter une task

Invoquez une task depuis une route (ou n'importe où sur l'hôte) avec POST /__bext/sdk/tasks/run :

curl -s http://127.0.0.1/__bext/sdk/tasks/run \
  -H "X-Bext-App-Id: <app-id>" \
  -H "Content-Type: application/json" \
  -d '{"task":"generate-report","payload":{"month":"2026-06"}}'
# -> 202 {"jobId":"…","status":"queued"}
Endpoint Corps / query Notes
/tasks/run { task, payload?, timeout_secs?, trigger? } 202 { jobId, status: "queued" }
/tasks/progress { id, data } Rapporter la progression (aussi via ctx.progress).
/tasks/status ?id= Retourne l'enregistrement du job (ci-dessous).
/tasks/list ?limit= Jobs récents.
/tasks/cancel { id } Annuler un job (déclenche ctx.signal).
/tasks/worker/register — Enregistrer un task worker.
/tasks/worker/unregister — Supprimer un task worker.

/tasks/status?id= retourne :

{
  "id": "…", "task": "generate-report", "status": "…", "progress": {},
  "result": {}, "error": null, "trigger": "…",
  "createdAt": "…", "updatedAt": "…", "finishedAt": "…"
}

Le planificateur (cron)

Le planificateur enregistre des jobs récurrents. Les expressions cron sont validées — une expression erronée retourne 400.

Endpoint Corps / notes
/scheduler/register { name, schedule|cron, kind?, command|handler_url|task, payload?, cwd?, timeout_secs?, enabled? }
/scheduler/list GET
/scheduler/cancel POST

kind est déduit de ce que vous fournissez :

Ce que vous fournissez kind déduit
task task-executor (exécute un defineTask)
handler_url http (envoie un POST à l'URL)
ni l'un ni l'autre command (exécute une commande shell) 
curl -s http://127.0.0.1/__bext/sdk/scheduler/register \
  -H "X-Bext-App-Id: <app-id>" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-report","cron":"0 3 * * *","task":"generate-report","payload":{"month":"current"}}'
Astuce

Préférez le planificateur bext au cron système. Faites passer les traitements récurrents par le planificateur (ou le task-executor) plutôt que par un crontab de l'hôte — il est restreint à l'application, les expressions cron sont validées et les jobs sont visibles via /scheduler/list. Voir Jobs planifiés.

Tasks vs queue vs planificateur — lequel utiliser

Utilisez… Quand
Tasks Un traitement de longue durée que vous voulez suivre — statut, progression et résultat. Pas de deadline de rendu, toute la concurrence d'I/O.
Queue Une livraison à haut volume, fire-and-forget, vers un handler public. At-least-once, pas de store de résultat.
Planificateur Un traitement déclenché par le temps — cron. Déclenche une task, un handler HTTP ou une commande selon un planning.

Et ensuite

Page Ce qu'elle couvre
Queue Livraison fire-and-forget et workers
KV Store Persister des résultats / enregistrements de job
Jobs planifiés Exploiter les jobs cron sur la plateforme