ジョブの投入

投入経路

投入には3つの経路があります。

経路	型	bindingsの設定
tsumugi.enqueue / tsumugi.jobs(env)	bindingごとにpayloadと必須キーが決まる	反映される
enqueue(env, input)	bindingはstring、payloadはunknown	反映されない
createClient(bindings)	同上	引数の内容が反映される

推奨はdefineTsumugiの戻り値を使う経路です。
トップレベルのenqueueはdefineTsumugiの設定を参照しないため、bindingsで指定した分割数、流量制御、保持期間が反映されず、partitionKeyも無効です。
また、wranglerのbindingが不足している場合、tsumugi.enqueueとtsumugi.jobsでは不足の一覧を含む例外が発生することがあります。

enqueue

const id = await tsumugi.enqueue(env, {
  binding: 'MAIL',
  payload: { to: 'a@example.com', subject: 'hi' },
});

戻り値はジョブIDです。
bindingからpayloadの型が決まり、必須キーの渡し忘れはコンパイルエラーになります。

enqueueMany

複数件をまとめて投入する場合はenqueueManyを使用します。

const ids = await tsumugi.enqueueMany(env, [
  { binding: 'MAIL', payload: { to: 'a@example.com', subject: 'hi' } },
  { binding: 'MAIL', payload: { to: 'b@example.com', subject: 'hi' } },
]);

件数が増えた場合も所要時間の増加は限定的です。

戻り値は入力と同じ並び順になります。

jobs

tsumugi.jobs(env)は、envを渡して作る型付きの投入用オブジェクトです。

const jobs = tsumugi.jobs(env);

const id = await jobs.enqueue('MAIL', { to: 'a@example.com', subject: 'hi' });
await jobs.enqueue('CHARGE', { customerId: 'c1', amountJpy: 1200 }, { concurrencyKey: 'customer:c1' });

投入の内容はtsumugi.enqueueと同様で、引数の形式のみ異なります。
キーを必須にしたperformerでは、optionsの省略とキー漏れがコンパイルエラーになります。

オプション

名前	既定	内容
priority	0	数値の優先度、大きいほど先に投入される
maxAttempts	3	試行回数の上限
backoff	指数、1秒起点、係数2、上限1時間、ジッタあり	リトライ間隔
timeoutMs	60000	結果を待つ時間の上限
delayMs	なし	実行開始を遅らせる
runAt	なし	絶対時刻での予約、delayMsとは排他
expiresInMs	なし	投入時刻からの相対の期限
expiresAt	なし	絶対時刻での期限、expiresInMsより優先
guarantee	at-least-once	実行保証
concurrencyKey	なし	キー単位の直列化に使う
uniqueKey	なし	重複排除に使う
uniqueForMs	24時間	uniqueKeyの予約を保持する期間
partitionKey	なし	分割している場合の投入先の決定に使う
traceparent	なし	投入元のW3C Trace Context

partitionKeyが有効なのはbindingsの設定を参照する経路のみです。詳細は投入経路を参照してください。

トレース情報

直接のジョブ投入でtraceparentを指定すると、performerのctx.traceparentへ同じ値が渡されます。

await tsumugi.enqueue(env, {
  binding: 'MAIL',
  payload: { to: 'a@example.com', subject: 'hi' },
  traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
});

W3C Trace Contextのversion 00に対応する55文字の形式を受け付けます。
各項目には小文字の16進数を使用し、trace-idとparent-idには全桁が0の値を指定できません。不正な値は投入時に検証エラーになります。
未指定の場合はctx.traceparentがnullになります。

リトライでも同値を引き継ぎ、ジョブの詳細画面に表示されます。
enqueueManyではジョブ単位で指定可能です。

予約実行

// 1時間後
await tsumugi.enqueue(env, { binding: 'MAIL', payload, delayMs: 60 * 60 * 1000 });

// 指定時刻
await tsumugi.enqueue(env, { binding: 'MAIL', payload, runAt: Date.parse('2026-08-01T09:00:00+09:00') });

有効期限

expiresInMsまたはexpiresAtを指定すると、期限を過ぎたジョブは実行されずCANCELLEDになります。
これにより、一時停止や滞留からの復帰時に、既に意味の無くなった通知などがまとめて実行されるのを防ぎます。

// 5分以内に開始できなければ実行しない
await tsumugi.enqueue(env, { binding: 'NOTIFY', payload, expiresInMs: 5 * 60 * 1000 });

判定は実行開始の直前に行われ、実行中のジョブは期限が過ぎても中断されることはありません。
リトライの予定が期限を越える場合、失敗した時点でCANCELLEDになります。
FAILEDやSTALLEDからの手動リトライも期限の対象です。

なお、実行の抑止は開始前のジョブに対するものです。at-least-onceの重複配送が期限をまたいだ場合、実行されたジョブがCANCELLEDと記録されることがあります。

重複排除

uniqueKeyを指定すると、同じキーのジョブが既に存在する場合は新規作成せず、既存のジョブIDを返すようになります。

const id = await tsumugi.enqueue(env, {
  binding: 'SYNC',
  payload: { sku: 'X-1' },
  uniqueKey: 'sku:X-1',
});

重複した投入は異常として扱わないため、原則として例外は発生しません。

予約はuniqueForMsの経過後に削除され、それ以降は同一キーであっても新しいジョブとして扱われます

直列化

concurrencyKeyが同じジョブは、perKeyConcurrencyの上限まで同時に実行されます。
既定値は1であり、同一キーのジョブは1件ずつ順次実行されます。

await tsumugi.enqueue(env, {
  binding: 'CHARGE',
  payload: { customerId: 'c1', amountJpy: 1200 },
  concurrencyKey: 'customer:c1',
});

また、この保証が成立するのはshard数が1の場合に限り、2以上に設定した場合、shardを同じキーで決定しない限り、エラーにならないまま保証が無効になります。詳細はshardを参照してください。

ジョブID

<binding>#<shard>:<localId>

例: MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx

shard数を後から変えると既存のIDの参照先が変更されます。後方互換性のため、古いshardは残すことを推奨します。

別Workerからの投入

投入だけを行うWorkerからはtsumugi/clientが利用可能です。createClientでbindingを指定し、enqueueやenqueueManyを呼び出すことができます。

詳細は別Workerからの投入を参照してください。