Zadania Zaplanowane (Cron)

Czym są zaplanowane zadania?

Zaplanowane zadanie to zwykły handler HTTP w Twoim projekcie, który FloopFloop wywołuje według harmonogramu — co 5 minut, co godzinę, codziennie o północy, lub cokolwiek skonfigurujesz. Typowe zastosowania: odpytywanie giełdy w poszukiwaniu danych rynkowych, odświeżanie pamięci podręcznej, wysyłanie codziennych podsumowań e-mail, ocenianie strategii i składanie zleceń.

Każde wywołanie to żądanie POST do trasy pod adresem /api/cron/* w Twoim projekcie, z tokenem bearer ograniczonym do projektu, który weryfikujesz przed wykonaniem jakiejkolwiek pracy.

Pisanie handlera

Twój handler to zwykła trasa POST w Next.js. Zweryfikuj token bearer względem process.env.FLOOP_CRON_TOKEN przed wykonaniem jakiejkolwiek pracy — każde inne żądanie powinno otrzymać odpowiedź 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 });
}

Zmienna środowiskowa FLOOP_CRON_TOKEN jest zarządzana przez FloopFloop — jest wbudowana w środowisko uruchomieniowe projektu w czasie budowania i nie pojawia się w interfejsie sekretów.

Jak rejestrowane są zadania

Zaplanowane zadania są deklarowane przez szablon, a nie dodawane ręcznie. Szablon dostarcza plik floop.crons.json w swoim katalogu głównym:

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

Po pierwszym pomyślnym wdrożeniu FloopFloop odczytuje ten manifest i rejestruje zadania dla Twojego projektu. Rejestracja jest idempotentna — ponowne wdrożenie tego samego szablonu nie zduplikuje zadań ani nie zresetuje historii uruchomień.

Jeśli Twoja aplikacja potrzebuje innego harmonogramu, poproś FloopFloop na czacie o aktualizację pliku floop.crons.json szablonu; nowy harmonogram wchodzi w życie po następnym wdrożeniu.

Status uruchomienia

Każde wywołanie jest rejestrowane ze statusem ok, error lub timeout. Zwróć status HTTP inny niż 2xx z handlera, aby oznaczyć uruchomienie jako błędne — treść odpowiedzi (do 500 znaków) jest przechwytywana jako komunikat błędu do debugowania.

Limity i ograniczenia

• 10 zaplanowanych zadań na projekt. Szablony deklarujące więcej niż 10 wpisów w floop.crons.json mają nadmiarowe wpisy odrzucane podczas rejestracji.
• Minimalny interwał 1 minuta. Wyrażenia cron sub-minutowe są odrzucane w czasie rejestracji.
• 30-sekundowy limit czasu pobierania na wywołanie. Jeśli Twój handler działa dłużej, dyspozytor rejestruje timeout i przechodzi dalej.
• Wywołania odbywają się tylko wtedy, gdy Twój projekt jest wdrożony i aktywny — nowo utworzone i zawieszone projekty są pomijane po cichu i automatycznie wznawiają działanie po reaktywacji.
• Ścieżki muszą pasować do wzorca /api/cron/<name> — ograniczenie to utrzymuje wywoływanie cron z dala od Twoich publicznie dostępnych tras.