Tâches Planifiées (Cron)

Que sont les tâches planifiées ?

Une tâche planifiée est un gestionnaire HTTP ordinaire dans votre projet que FloopFloop appelle selon un calendrier récurrent — toutes les 5 minutes, toutes les heures, chaque jour à minuit, selon votre configuration. Utilisations typiques : interroger une place d'échange pour des données de marché, actualiser un cache, envoyer un email de résumé quotidien, évaluer une stratégie et passer un ordre.

Chaque déclenchement est un POST vers une route sous /api/cron/*à l'intérieur de votre projet, avec un jeton bearer limité au projet que vous vérifiez avant d'effectuer tout travail.

Écriture du gestionnaire

Votre gestionnaire est une route POST Next.js normale. Vérifiez le jeton bearer par rapport à process.env.FLOOP_CRON_TOKEN avant d'effectuer tout travail — toute autre requête doit recevoir un 401 :

// src/app/api/cron/rebalance/route.ts
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";

export async function POST(request: NextRequest) {
  const expected = `Bearer ${process.env.FLOOP_CRON_TOKEN ?? ""}`;
  if (request.headers.get("authorization") !== expected) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Do your work here — query data, call APIs, etc.
  return NextResponse.json({ ok: true });
}

La variable d'environnement FLOOP_CRON_TOKENest gérée par FloopFloop — elle est intégrée dans le runtime de votre projet au moment de la compilation et n'apparaît pas dans l'interface des Secrets.

Enregistrement des tâches

Les tâches planifiées sont déclarées par le modèle, pas ajoutées manuellement. Un modèle inclut un fichier floop.crons.jsonà sa racine :

{
  "jobs": [
    {
      "name": "evaluate-strategy",
      "cron": "*/5 * * * *",
      "path": "/api/cron/evaluate-strategy",
      "enabled": true
    }
  ]
}

Après votre premier déploiement réussi, FloopFloop lit ce manifeste et enregistre les tâches pour votre projet. L'enregistrement est idempotent — redéployer le même modèle ne dupliquera pas les tâches ni ne réinitialisera l'historique d'exécution.

Si votre application nécessite un calendrier différent, demandez à FloopFloop dans le chat de mettre à jour le fichier floop.crons.jsondu modèle ; la nouvelle cadence prend effet après le prochain déploiement.

Statut d'exécution

Chaque déclenchement est enregistré avec un statut ok, error ou timeout. Retournez un statut HTTP non-2xx depuis votre gestionnaire pour marquer l'exécution comme erreur — le corps de la réponse (jusqu'à 500 caractères) est capturé comme message d'erreur pour le débogage.

Limites & contraintes

• 10 tâches planifiées par projet. Les modèles déclarant plus de 10 entrées dans floop.crons.json voient le surplus rejeté lors de l'enregistrement.
• Intervalle minimum d'1 minute.Les expressions cron inférieures à la minute sont rejetées lors de l'enregistrement.
• Délai d'attente de 30 secondes par déclenchement. Si votre gestionnaire prend plus de temps, le dispatcher enregistre un timeout et passe à la suite.
• Se déclenche uniquement lorsque votre projet est déployé et actif — les projets nouvellement créés et les projets suspendus sont ignorés silencieusement et reprennent automatiquement lors de la réactivation.
• Les chemins doivent correspondre à /api/cron/<name> — cette restriction empêche les déclenchements cron d'atteindre vos routes publiques.