Tugas Terjadwal (Cron)

Apa itu pekerjaan terjadwal?

Pekerjaan terjadwal adalah handler HTTP biasa dalam proyek Anda yang dipanggil FloopFloop pada jadwal berulang — setiap 5 menit, setiap jam, setiap hari tengah malam, apa pun yang Anda konfigurasi. Penggunaan umum: polling exchange untuk data pasar, memperbarui cache, mengirim email ringkasan harian, mengevaluasi strategi dan menempatkan perdagangan.

Setiap panggilan adalah POST ke rute di bawah /api/cron/* di dalam proyek Anda, dengan token bearer yang dibatasi ke proyek yang Anda verifikasi sebelum melakukan pekerjaan apa pun.

Menulis handler

Handler Anda adalah rute POST Next.js biasa. Verifikasi token bearer terhadap process.env.FLOOP_CRON_TOKEN sebelum melakukan pekerjaan apa pun — permintaan lain harus mendapat respons 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 });
}

Environment variable FLOOP_CRON_TOKEN dikelola oleh FloopFloop — ia di-bake ke dalam runtime proyek Anda saat build time dan tidak muncul di UI Secrets.

Cara pekerjaan didaftarkan

Pekerjaan terjadwal dideklarasikan oleh template, bukan ditambahkan secara manual. Sebuah template menyertakan file floop.crons.json di root-nya:

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

Setelah deployment pertama yang berhasil, FloopFloop membaca manifes ini dan mendaftarkan pekerjaan untuk proyek Anda. Pendaftaran bersifat idempoten — men-deploy ulang template yang sama tidak akan menduplikasi pekerjaan atau mereset riwayat run.

Jika aplikasi Anda membutuhkan jadwal yang berbeda, minta FloopFloop di obrolan untuk memperbarui floop.crons.json template; jadwal baru berlaku setelah deployment berikutnya.

Status run

Setiap panggilan dicatat dengan status ok, error, atau timeout. Kembalikan status HTTP non-2xx dari handler Anda untuk menandai run sebagai error — badan respons (hingga 500 karakter) diambil sebagai pesan error untuk debugging.

Batas & batasan

• 10 pekerjaan terjadwal per proyek. Template yang mendeklarasikan lebih dari 10 entri dalam floop.crons.json akan mengalami penolakan kelebihan saat pendaftaran.
• Interval minimum 1 menit. Ekspresi cron sub-menit ditolak saat pendaftaran.
• Timeout fetch 30 detik per panggilan. Jika handler Anda membutuhkan waktu lebih lama, dispatcher mencatat timeout dan melanjutkan.
• Hanya berjalan saat proyek Anda di-deploy dan aktif — proyek yang baru dibuat dan proyek yang ditangguhkan dilewati secara diam-diam dan dilanjutkan secara otomatis saat diaktifkan kembali.
• Path harus cocok dengan /api/cron/<name> — pembatasan ini memisahkan panggilan cron dari rute publik Anda.