Geplande Taken (Cron)

Wat zijn geplande taken?

Een geplande taak is een gewone HTTP-handler in je project die FloopFloop op een terugkerend schema aanroept — elke 5 minuten, elk uur, dagelijks om middernacht, wat je ook configureert. Typische toepassingen: een exchange pollen voor marktdata, een cache vernieuwen, een dagelijkse digest-e-mail versturen, een strategie evalueren en een trade plaatsen.

Elke aanroep is een POST naar een route onder /api/cron/* in je project, met een projectgebonden bearer-token dat je verifieert voordat je iets doet.

De handler schrijven

Je handler is een gewone Next.js POST-route. Verifieer het bearer-token aan de hand van process.env.FLOOP_CRON_TOKEN voordat je iets doet — elk ander verzoek moet een 401 krijgen:

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

De omgevingsvariabele FLOOP_CRON_TOKEN wordt beheerd door FloopFloop — hij wordt ingebakken in de runtime van je project bij het bouwen en verschijnt niet in de Secrets-UI.

Hoe taken worden geregistreerd

Geplande taken worden door het template gedeclareerd, niet handmatig toegevoegd. Een template bevat een floop.crons.json-bestand in de root:

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

Na je eerste succesvolle deployment leest FloopFloop dit manifest en registreert de taken voor je project. Registratie is idempotent — het opnieuw deployen van hetzelfde template dupliceert taken niet en reset geen uitvoergeschiedenis.

Als je app een ander schema nodig heeft, vraag FloopFloop dan via de chat om floop.crons.json van het template bij te werken; het nieuwe interval gaat in na de volgende deployment.

Uitvoerstatus

Elke aanroep wordt geregistreerd met een status van ok, error of timeout. Geef een niet-2xx HTTP-status terug vanuit je handler om de uitvoering als mislukt te markeren — de responsebody (tot 500 tekens) wordt vastgelegd als foutmelding voor debuggingdoeleinden.

Limieten & beperkingen

• 10 geplande taken per project. Templates die meer dan 10 vermeldingen in floop.crons.json declareren, krijgen het overschot afgewezen bij registratie.
• Minimuminterval van 1 minuut. Sub-minuut cron-expressies worden afgewezen bij registratie.
• Fetch-time-out van 30 seconden per aanroep. Als je handler langer duurt, registreert de dispatcher een timeout en gaat verder.
• Aanroepen vinden alleen plaats terwijl je project is gedeployd en actief is — nieuw aangemaakte projecten en gesuspendeerde projecten worden stil overgeslagen en worden automatisch hervat bij reactivering.
• Paden moeten overeenkomen met /api/cron/<name> — de beperking houdt cron-aanroepen weg van je publiek gerichte routes.