Tareas Programadas (Cron)

¿Qué son los trabajos programados?

Un trabajo programado es un handler HTTP normal en tu proyecto al que FloopFloop llama con una frecuencia recurrente — cada 5 minutos, cada hora, diariamente a medianoche, lo que configures. Usos típicos: sondear un exchange en busca de datos de mercado, refrescar una caché, enviar un resumen diario por email, evaluar una estrategia y colocar una orden.

Cada disparo es un POST a una ruta bajo /api/cron/* dentro de tu proyecto, con un token bearer con ámbito de proyecto que verificas antes de realizar cualquier trabajo.

Escribir el handler

Tu handler es una ruta POST normal de Next.js. Verifica el token bearer contra process.env.FLOOP_CRON_TOKEN antes de realizar cualquier trabajo — cualquier otra solicitud debe recibir 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 de entorno FLOOP_CRON_TOKEN es gestionada por FloopFloop — se integra en el runtime de tu proyecto durante la construcción y no aparece en la UI de Secrets.

Cómo se registran los trabajos

Los trabajos programados los declara la plantilla, no se añaden a mano. Una plantilla incluye un archivo floop.crons.json en su raíz:

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

Tras tu primer despliegue exitoso, FloopFloop lee este manifiesto y registra los trabajos para tu proyecto. El registro es idempotente — volver a desplegar la misma plantilla no duplicará los trabajos ni reiniciará ningún historial de ejecución.

Si tu app necesita una frecuencia diferente, pídele a FloopFloop en el chat que actualice el floop.crons.json de la plantilla; la nueva cadencia entra en vigor tras el siguiente despliegue.

Estado de ejecución

Cada disparo se registra con un estado de ok, erroro timeout. Devuelve un estado HTTP no 2xx desde tu handler para marcar la ejecución como con error — el cuerpo de la respuesta (hasta 500 caracteres) se captura como mensaje de error para depuración.

Límites y restricciones

• 10 trabajos programados por proyecto. Las plantillas que declaran más de 10 entradas en floop.crons.json tienen el exceso rechazado en el momento del registro.
• Intervalo mínimo de 1 minuto. Las expresiones cron sub-minuto se rechazan en el momento del registro.
• Timeout de fetch de 30 segundos por disparo. Si tu handler tarda más, el despachador registra un timeout y continúa.
• Los disparos solo ocurren mientras tu proyecto está desplegado y activo — los proyectos recién creados y los proyectos suspendidos se omiten silenciosamente y se reanudan automáticamente al reactivarse.
• Las rutas deben coincidir con /api/cron/<name> — la restricción mantiene el disparo de cron alejado de tus rutas públicas.