잡 투입

투입 방법

performer와 같은 Worker에서는 defineTsumugi의 반환값을 사용해 잡을 투입합니다.
createClient는 performer를 가지지 않는 Worker에서 잡을 투입하기 위한 클라이언트입니다.

필요한 binding이 부족하면 tsumugi.enqueue, tsumugi.enqueueMany, tsumugi.jobs(env)는 예외를 발생시킵니다.
예외에는 부족한 binding의 목록이 포함됩니다.
JOB_SHARD, TSUMUGI_DB, TSUMUGI_QUEUE는 항상 필수입니다.
flows를 사용하는 경우에는 RUN을, schedules를 사용하는 경우에는 SCHEDULER를 추가합니다.
remote() performer에는 대응하는 Service Binding을 준비합니다.

enqueue

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

반환값은 잡 ID입니다.
payload의 타입은 지정한 binding의 값에서 도출됩니다.
필수 키를 지정하지 않으면 컴파일 오류가 발생합니다.

enqueueMany

tsumugi.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' } },
]);

건수가 늘어나도 소요 시간은 거의 변하지 않습니다.
반환되는 배열에서 i번째 요소는 입력의 i번째 잡에 대응하는 ID입니다.

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를 생략한 경우와 키를 지정하지 않은 경우 모두 컴파일 오류가 발생합니다.

옵션

shard 수가 2 이상인 binding에서 partitionKey를 생략하면 예외가 발생합니다.
partitionKey로 투입 대상 shard를 선택하는 것은 bindings의 shards를 적용하는 투입 방법으로 한정됩니다.
자세한 내용은 투입 방법을 참조하십시오.

예약 실행

// 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 상태의 잡을 수동으로 재시도할 때도 기한이 적용됩니다.

중복 제거

uniqueKey를 지정하면 같은 키의 잡이 이미 존재할 때 새 잡을 생성하지 않습니다.
이때의 반환값은 기존 잡의 ID입니다.

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

중복된 투입은 오류가 되지 않습니다.
예외도 발생하지 않습니다.
uniqueForMs의 기간이 지나면 중복 판정이 해제됩니다.
같은 키로 다시 투입하면 새 잡이 생성됩니다.

직렬화

concurrencyKey가 같은 잡은 perKeyConcurrency의 건수까지 동시에 실행됩니다.
기본값은 1이므로 같은 키의 잡은 한 건씩 순서대로 실행됩니다.

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

shard 수가 2 이상인 binding에서는 이 직렬화가 partitionKey가 같은 shard 안으로 한정됩니다.
자세한 내용은 shard를 참조하십시오.

트레이스 정보

투입 시 traceparent를 지정하면 performer의 ctx.traceparent에 같은 값이 전달됩니다.
재시도 시에도 같은 값이 전달되며, 대시보드는 잡의 상세 화면에 이 값을 표시합니다.
enqueueMany는 잡별 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인 값을 지정한 경우에도 검증 오류가 발생합니다.

잡 ID

<binding>#<shard>:<localId>

예: MAIL#0:xxxxxxxxxxxxxxxxxxxxxxxx

shard 수를 변경해도 기존 잡 ID는 동일한 잡을 식별합니다.
다만 변경 전후로 partitionKey 값이 같은 잡의 투입 대상 shard가 달라질 수 있습니다.
concurrencyKey와 uniqueKey에 의한 제어는 shard별로 실행되므로, 투입 대상 shard가 다른 잡 사이에는 적용되지 않습니다.
shard 수를 줄이면 범위 밖이 된 shard에는 실행 시 설정 변경이 적용되지 않습니다.
shard에 대한 자세한 내용은 shard를 참조하십시오.

다른 Worker에서의 투입

performer를 가지지 않는 Worker에서의 투입에 대해서는 다른 Worker에서의 투입을 참조하십시오.