Zamanlanmış İşler (Cron)

Zamanlanmış işler nedir?

Zamanlanmış iş, FloopFloop'un belirli aralıklarla çağırdığı — her 5 dakikada bir, her saat, yapılandırdığınıza göre gece yarısı günlük vb. — projenizde normal bir HTTP işleyicisidir. Tipik kullanımlar: borsa için piyasa verisi çekme, önbellek yenileme, günlük özet e-postası gönderme, strateji değerlendirip işlem gerçekleştirme.

Her çalışma, herhangi bir iş yapmadan önce doğrulamanız gereken proje kapsamlı bir taşıyıcı tokenla projenizin /api/cron/* altındaki bir rotaya yapılan bir POST isteğidir.

İşleyici yazma

İşleyiciniz normal bir Next.js POST rotasıdır. Herhangi bir iş yapmadan önce taşıyıcı tokeni process.env.FLOOP_CRON_TOKEN ile doğrulayın — diğer istekler 401 almalıdır:

// 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 });
}

FLOOP_CRON_TOKEN ortam değişkeni FloopFloop tarafından yönetilir — derleme sırasında projenizin çalışma zamanına eklenir ve Gizli Anahtarlar arayüzünde görünmez.

İşler nasıl kaydedilir

Zamanlanmış işler elle eklenmez, şablon tarafından tanımlanır. Bir şablon, kök dizininde bir floop.crons.json dosyası içerir:

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

İlk başarılı dağıtımın ardından FloopFloop bu manifesti okur ve projeniz için işleri kaydeder. Kayıt idempotent'tır — aynı şablonu yeniden dağıtmak işleri çoğaltmaz veya çalıştırma geçmişini sıfırlamaz.

Uygulamanızın farklı bir zamanlamaya ihtiyacı varsa FloopFloop'a sohbetten şablonun floop.crons.json dosyasını güncellemesini isteyin; yeni kadans bir sonraki dağıtımdan itibaren geçerli olur.

Çalıştırma durumu

Her çalışma ok, error veya timeoutdurumuyla kaydedilir. Çalışmayı hatalı olarak işaretlemek için işleyicinizden 2xx dışı bir HTTP durumu döndürün — yanıt gövdesi (en fazla 500 karakter) hata ayıklama için hata mesajı olarak yakalanır.

Sınırlar & kısıtlamalar

• Proje başına 10 zamanlanmış iş. floop.crons.jsoniçinde 10'dan fazla giriş bildiren şablonlar, kayıt sırasında fazla olanlar reddedilerek işlenir.
• En az 1 dakikalık aralık. Alt dakika cron ifadeleri kayıt sırasında reddedilir.
• Çalışma başına 30 saniyelik getirme zaman aşımı. İşleyiciniz daha uzun sürerse dağıtıcı bir timeoutkaydeder ve devam eder.
• Yalnızca projeniz dağıtılmış ve etkin durumdayken çalışır — yeni oluşturulan ve askıya alınan projeler sessizce atlanır ve yeniden etkinleştirildiğinde otomatik olarak devam eder.
• Yollar /api/cron/<name> ile eşleşmelidir — bu kısıtlama, cron tetiklemelerini herkese açık rotalarınızdan uzak tutar.