Lavori Pianificati (Cron)

Cosa sono i job pianificati?

Un job pianificato è un normale handler HTTP nel tuo progetto che FloopFloop chiama su una pianificazione ricorrente — ogni 5 minuti, ogni ora, ogni giorno a mezzanotte, qualunque cosa configuri. Usi tipici: interrogare un exchange per dati di mercato, aggiornare una cache, inviare un'email di digest giornaliera, valutare una strategia e piazzare un'operazione.

Ogni esecuzione è un POST a una route sotto /api/cron/*all'interno del tuo progetto, con un bearer token con scope di progetto che verifichi prima di fare qualsiasi lavoro.

Scrittura dell'handler

Il tuo handler è una normale route POST di Next.js. Verifica il bearer token contro process.env.FLOOP_CRON_TOKEN prima di fare qualsiasi lavoro — qualsiasi altra richiesta dovrebbe ricevere 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 variabile d'ambiente FLOOP_CRON_TOKENè gestita da FloopFloop — è incorporata nel runtime del tuo progetto al momento della build e non appare nell'interfaccia utente dei Secrets.

Come vengono registrati i job

I job pianificati sono dichiarati dal template, non aggiunti manualmente. Un template include un file floop.crons.json alla sua radice:

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

Dopo la prima distribuzione riuscita, FloopFloop legge questo manifesto e registra i job per il tuo progetto. La registrazione è idempotente — ridistribuire lo stesso template non duplicherà i job né azzererà la cronologia delle esecuzioni.

Se la tua app ha bisogno di una pianificazione diversa, chiedi a FloopFloop in chat di aggiornare il floop.crons.json del template; la nuova cadenza ha effetto dopo il prossimo deploy.

Stato delle esecuzioni

Ogni esecuzione viene registrata con uno stato di ok, error o timeout. Restituisci uno stato HTTP non-2xx dal tuo handler per contrassegnare l'esecuzione come errata — il corpo della risposta (fino a 500 caratteri) viene catturato come messaggio di errore per il debug.

Limiti & vincoli

• 10 job pianificati per progetto. I template che dichiarano più di 10 voci in floop.crons.json vedono il overflow rifiutato al momento della registrazione.
• Intervallo minimo di 1 minuto. Le espressioni cron sub-minuto vengono rifiutate al momento della registrazione.
• Timeout di fetch di 30 secondi per esecuzione. Se il tuo handler impiega più tempo, il dispatcher registra un timeout e va avanti.
• Le esecuzioni avvengono solo mentre il tuo progetto è distribuito e attivo — i progetti appena creati e quelli sospesi vengono saltati silenziosamente e riprendono automaticamente alla riattivazione.
• I percorsi devono corrispondere a /api/cron/<name> — la restrizione mantiene le esecuzioni cron lontane dalle tue route pubbliche.