설정

defineTsumugi

const tsumugi = defineTsumugi({
  performers,
  flows,
  schedules,
  runs,
  bindings,
  auth,
  ui,
  retention,
  metrics,
  onFailure,
  onSettled,
  onEnqueue,
});

defineTsumugi에는 타입 인자를 지정할 필요가 없습니다.
binding별 payload 타입과 Env는 performers의 내용에서 자동으로 추론됩니다.

반환값

flows를 지정하지 않은 경우에도 반환값에는 start, runFor, runClass가 포함됩니다.
flows에 정의되지 않은 Flow 이름을 start에 전달하면 예외가 발생합니다.
RUN binding이 없는 상태에서 runFor를 호출한 경우에도 마찬가지로 예외가 발생합니다.
enqueue 방법별 차이는 잡 투입을 참조하세요.

auth

auth에는 직접 작성한 인증 함수를 지정할 수 있습니다.
함수의 인자는 request와 env이고, 반환값은 Response 또는 undefined입니다.
자세한 내용은 대시보드와 인증을 참조하세요.
auth를 설정하지 않으면 REST API와 대시보드에 대한 모든 요청에 404로 응답합니다.
unsafeNoAuth의 영향은 대시보드와 인증을 참조하세요.

metrics

const tsumugi = defineTsumugi({
  performers,
  auth: bearerAuth((env: Env) => env.TSUMUGI_TOKEN),
  metrics: (env: Env) =>
    env.CF_ACCOUNT_ID && env.CF_API_TOKEN
      ? { accountId: env.CF_ACCOUNT_ID, apiToken: env.CF_API_TOKEN, dataset: 'tsumugi_jobs' }
      : undefined,
});

metrics는 기록한 메트릭을 대시보드와 REST API에서 조회하기 위한 설정입니다.
apiToken은 Account Analytics 읽기 권한을 가진 API 토큰이며, Secret으로 설정하세요.
dataset은 wrangler 설정 파일의 analytics_engine_datasets에 기술한 데이터셋 이름입니다.
metrics를 지정하지 않으면 GET /api/metrics는 501로 응답하고, 대시보드 사이드바에 메트릭 항목이 표시되지 않습니다.

onFailure

const tsumugi = defineTsumugi({
  performers,
  onFailure: 'NotifyFailure',
});

onFailure는 실패한 잡을 알리는 performer의 binding 이름입니다.
알림을 받는 performer는 FailureNotice를 수신하는 것으로 한정됩니다.
알림 조건과 FailureNotice의 내용은 실패 알림을 참조하세요.

onSettled

const tsumugi = defineTsumugi({
  performers,
  onSettled: { binding: 'NotifySettled', states: ['COMPLETED', 'FAILED'] },
});

onSettled는 종료된 잡을 알리는 performer의 binding 이름과 알릴 상태입니다.
binding은 SettledNotice를 수신하는 performer로 한정됩니다.
states는 필수이며 COMPLETED, FAILED, CANCELLED, STALLED 중에서 선택합니다.
빈 배열이나 잘못된 상태를 지정하면 defineTsumugi에서 예외가 발생합니다.
알림 조건과 SettledNotice의 내용은 종료 알림을 참조하세요.

onEnqueue

const tsumugi = defineTsumugi({
  performers,
  onEnqueue: (input) => (input.binding === 'SlowJob' ? { timeoutMs: 300_000 } : undefined),
});

onEnqueue는 잡을 enqueue할 때마다 실행 옵션의 기본값을 설정하는 함수입니다.
사용자가 명시한 값이 항상 우선합니다.
대상이 되는 enqueue 방법과 기본값이 적용되는 옵션의 자세한 내용은 enqueue 시의 기본값을 참조하세요.

RunSettings

BindingConfig

Policy

EnqueueInput

옵션의 자세한 내용은 잡 투입을 참조하세요.

createClient의 enqueue는 EnqueueInput을 인자로 받습니다.
defineTsumugi의 enqueue가 받는 입력에서는 binding별로 payload와 필수 키의 타입이 도출됩니다.

backoff 기본값

{ kind: 'exponential', baseMs: 1_000, factor: 2, maxMs: 3_600_000, jitter: true }

SweepOptions

cron 트리거를 설정하면 olderThanMs가 경과한 후 종료된 잡과 Run이 목록에서 삭제됩니다.

Run을 재개할 수 있는 기간은 runs에서 설정합니다.
FAILED 상태의 Run은 olderThanMs와 runs.failedRetentionMs 중 더 긴 기간이 경과한 후 목록에서 삭제됩니다.
FAILED와 STALLED 상태의 잡도 olderThanMs와 binding의 failedRetentionMs 중 더 긴 기간이 경과한 후 목록에서 삭제됩니다.

wrangler의 binding

TSUMUGI_METRICS가 없으면 메트릭은 기록되지 않습니다.
그 밖의 동작은 달라지지 않습니다.
다른 필수 binding이 부족하면 REST API는 503으로 응답하며, 부족한 binding의 목록이 본문에 포함됩니다.

remote()를 지정한 performer에는 Service Binding이 필요합니다.
binding 이름에는 고정된 이름을 사용하지 않고, performers의 키를 그대로 지정합니다.

"services": [
  { "binding": "MAIL", "service": "my-mailer", "entrypoint": "SendMail" },
]

performer 없이 잡 enqueue에만 사용하는 Worker에 필요한 binding은 JOB_SHARD뿐입니다.

서브패스

공개된 npm 패키지는 tsumugi입니다.
셋업용 CLI는 npx tsumugi로 실행합니다.
명령어 목록은 CLI를 참조하세요.