Geplante Aufgaben (Cron)

Was sind geplante Jobs?

Ein geplanter Job ist ein regulärer HTTP-Handler in Ihrem Projekt, den FloopFloop nach einem wiederkehrenden Zeitplan aufruft — alle 5 Minuten, stündlich, täglich um Mitternacht, oder was auch immer Sie konfigurieren. Typische Anwendungsfälle: Abfragen eines Exchange nach Marktdaten, Auffrischen eines Caches, Senden einer täglichen Digest-E-Mail, Auswerten einer Strategie und Platzieren eines Trades.

Jede Ausführung ist ein POST-Request an eine Route unter /api/cron/* in Ihrem Projekt, mit einem projektbezogenen Bearer-Token, den Sie vor jeder Verarbeitung verifizieren.

Den Handler schreiben

Ihr Handler ist eine normale Next.js-POST-Route. Verifizieren Sie den Bearer-Token gegen process.env.FLOOP_CRON_TOKEN, bevor Sie irgendetwas tun — alle anderen Anfragen sollten eine 401-Antwort erhalten:

// 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 });
}

Die Umgebungsvariable FLOOP_CRON_TOKEN wird von FloopFloop verwaltet — sie ist zur Build-Zeit in die Laufzeit Ihres Projekts eingebettet und erscheint nicht in der Secrets-Oberfläche.

Wie Jobs registriert werden

Geplante Jobs werden vom Template deklariert, nicht manuell hinzugefügt. Ein Template enthält eine floop.crons.json-Datei in seinem Root:

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

Nach Ihrem ersten erfolgreichen Deploy liest FloopFloop dieses Manifest und registriert die Jobs für Ihr Projekt. Die Registrierung ist idempotent — ein erneutes Deployen desselben Templates dupliziert keine Jobs und setzt keinen Ausführungsverlauf zurück.

Wenn Ihre Anwendung einen anderen Zeitplan benötigt, bitten Sie FloopFloop im Chat, die floop.crons.json des Templates zu aktualisieren; der neue Rhythmus tritt nach dem nächsten Deploy in Kraft.

Ausführungsstatus

Jede Ausführung wird mit einem Status von ok, erroroder timeout aufgezeichnet. Geben Sie einen Nicht-2xx-HTTP-Status aus Ihrem Handler zurück, um die Ausführung als fehlerhaft zu markieren — der Antwort-Body (bis zu 500 Zeichen) wird als Fehlermeldung für die Fehlersuche erfasst.

Limits & Einschränkungen

• 10 geplante Jobs pro Projekt. Templates, die mehr als 10 Einträge in floop.crons.json deklarieren, werden bei der Registrierung abgewiesen.
• Mindestintervall 1 Minute. Cron-Ausdrücke unter einer Minute werden bei der Registrierung abgelehnt.
• 30-Sekunden-Fetch-Timeout pro Ausführung. Wenn Ihr Handler länger braucht, zeichnet der Dispatcher einen timeoutauf und fährt fort.
• Ausführungen erfolgen nur, solange Ihr Projekt bereitgestellt und aktiv ist — neu erstellte und ausgesetzte Projekte werden stillschweigend übersprungen und nehmen bei Reaktivierung automatisch wieder auf.
• Pfade müssen /api/cron/<name> entsprechen — die Einschränkung hält Cron-Aufrufe von Ihren öffentlichen Routen fern.