Tarefas Agendadas (Cron)

O que são jobs agendados?

Um job agendado é um handler HTTP normal no teu projeto que o FloopFloop invoca numa periodicidade recorrente — a cada 5 minutos, a cada hora, diariamente à meia-noite, o que configurares. Utilizações típicas: consultar uma exchange para obter dados de mercado, atualizar uma cache, enviar um e-mail de resumo diário, avaliar uma estratégia e colocar uma ordem.

Cada execução é um POST para uma rota em /api/cron/* dentro do teu projeto, com um token bearer com âmbito de projeto que verificas antes de fazer qualquer trabalho.

Escrever o handler

O teu handler é uma rota POST normal do Next.js. Verifica o token bearer contra process.env.FLOOP_CRON_TOKEN antes de fazer qualquer trabalho — qualquer outro pedido deve receber um 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 });
}

A variável de ambiente FLOOP_CRON_TOKEN é gerida pelo FloopFloop — está incorporada no runtime do teu projeto no momento da compilação e não aparece na interface de Secrets.

Como os jobs são registados

Os jobs agendados são declarados pelo template, não adicionados manualmente. Um template inclui um ficheiro floop.crons.jsonna sua raiz:

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

Após a tua primeira implementação bem-sucedida, o FloopFloop lê este manifesto e regista os jobs para o teu projeto. O registo é idempotente — reimplementar o mesmo template não duplica jobs nem repõe o histórico de execuções.

Se a tua aplicação precisar de uma periodicidade diferente, pede ao FloopFloop no chat para atualizar o floop.crons.json do template; a nova cadência entra em vigor após a próxima implementação.

Estado de execução

Cada execução é registada com um estado de ok, errorou timeout. Devolve um estado HTTP diferente de 2xx do teu handler para marcar a execução como com erro — o corpo da resposta (até 500 caracteres) é capturado como mensagem de erro para depuração.

Limites & restrições

• 10 jobs agendados por projeto. Templates que declarem mais de 10 entradas em floop.crons.json têm o excedente rejeitado no registo.
• Intervalo mínimo de 1 minuto. Expressões cron sub-minuto são rejeitadas no momento do registo.
• Timeout de fetch de 30 segundos por execução. Se o teu handler demorar mais, o dispatcher regista um timeout e avança.
• Só executa enquanto o teu projeto está implementado e ativo — projetos recém-criados e projetos suspensos são ignorados silenciosamente e retomam automaticamente na reativação.
• Os caminhos têm de corresponder a /api/cron/<name> — a restrição mantém as execuções cron afastadas das tuas rotas públicas.