예약 작업 (Cron)

예약 작업이란 무엇인가요?

예약 작업은 FloopFloop이 반복 일정에 따라 호출하는 프로젝트 내의 일반 HTTP 핸들러입니다 — 5분마다, 매시간, 매일 자정 등 원하는 대로 구성할 수 있습니다. 일반적인 용도: 시장 데이터를 위한 거래소 폴링, 캐시 갱신, 일일 다이제스트 이메일 발송, 전략 평가 및 거래 실행.

각 실행은 프로젝트 내 /api/cron/* 경로로의 POST 요청이며, 작업 수행 전에 검증하는 프로젝트 범위의 베어러 토큰이 함께 전송됩니다.

핸들러 작성

핸들러는 일반적인 Next.js POST 라우트입니다. 작업 수행 전에process.env.FLOOP_CRON_TOKEN에 대해 베어러 토큰을 검증합니다 — 다른 요청은 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 });
}

FLOOP_CRON_TOKEN환경 변수는 FloopFloop이 관리합니다 — 빌드 시 프로젝트's 런타임에 포함되며 시크릿 UI에는 나타나지 않습니다.

작업 등록 방법

예약 작업은 수동으로 추가하지 않고 템플릿에서 선언됩니다. 템플릿은 루트에 floop.crons.json 파일을 포함합니다:

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

첫 번째 성공적인 배포 후 FloopFloop이 이 매니페스트를 읽고 프로젝트의 작업을 등록합니다. 등록은 멱등적입니다 — 동일한 템플릿을 재배포해도 작업이 중복되거나 실행 기록이 초기화되지 않습니다.

앱에 다른 일정이 필요한 경우 FloopFloop 채팅에서 템플릿'sfloop.crons.json을 업데이트해 달라고 요청하면, 다음 배포 후 새 주기가 적용됩니다.

실행 상태

각 실행은 ok, error, 또는 timeout 상태로 기록됩니다. 핸들러에서 2xx가 아닌 HTTP 상태를 반환하면 실행이 오류로 표시됩니다 — 응답 본문 (최대 500자)은 디버깅을 위한 오류 메시지로 캡처됩니다.

제한 사항 & 제약 조건

• 프로젝트당 예약 작업 10개. floop.crons.json에 10개 이상의 항목을 선언하는 템플릿은 등록 시 초과분이 거부됩니다.
• 최소 간격 1분. 1분 미만의 크론 표현식은 등록 시 거부됩니다.
• 실행당 페치 타임아웃 30초. 핸들러가 더 오래 걸리면 디스패처가 timeout을 기록하고 다음으로 넘어갑니다.
• 프로젝트가 배포되고 활성화된 동안에만 실행됩니다 — 새로 생성된 프로젝트와 일시 중단된 프로젝트는 자동으로 건너뛰어지며 재활성화 시 자동으로 재개됩니다.
• 경로는 /api/cron/<name>과 일치해야 합니다 — 이 제한으로 크론 실행이 공개 라우트와 분리됩니다.