設定

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を呼び出した場合も、同様に例外が発生します。
投入方法ごとの違いは、ジョブの投入を参照してください。

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は、ジョブの投入ごとに実行オプションの既定値を設定する関数です。
利用者が明示した値は、常に優先されます。
対象となる投入方法と、既定値が適用されるオプションの詳細は、投入時の既定値を参照してください。

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を持たず、ジョブの投入に限って使用するWorkerに必要なbindingは、JOB_SHARDに限られます。

サブパス

公開しているnpmパッケージはtsumugiです。
セットアップ用のCLIはnpx tsumugiで実行します。
コマンドの一覧はCLIを参照してください。