Tsumugi Docs

What Tsumugi solves

Using Cloudflare Queues directly as a job queue causes several problems.

01
Job state is hard to track, and succeeded jobs are not kept
Queues
Queues provides no API to query the state of an enqueued message.
Tsumugi
The Tsumugi dashboard and REST API list, search, and aggregate both running and finished jobs.
02
Mutual exclusion and deduplication are hard to implement
Queues
Queues does not manage dependencies or relationships between messages.
Tsumugi
In Tsumugi, jobs with the same concurrencyKey run one at a time, in order.
03
More job types mean more branching
Queues
Queues allows only one consumer per queue.
Tsumugi
Tsumugi distinguishes job types by binding name, which is the export name of the performer, so the consumer needs no branching.
04
Messages are occasionally lost
Queues
Queues provides no way to detect messages that were lost without being processed.
Tsumugi
Tsumugi marks a job as unresponsive when a job that has started does not report its result.

The code you write

You write code in only two places: the job handler and the enqueue call.

1 Define the job handler as a performer

src/performers/send-mail.ts
import { Performer } from 'tsumugi/performer';export class SendMail extends Performer<{ to: string }, void, {}, Env> {  async perform(payload: { to: string }): Promise<void> {    await this.env.MAILER.send(payload.to);  }}

2 Enqueue a job

src/index.ts
import { defineTsumugi } from 'tsumugi';import { SendMail } from './performers/send-mail.js';const tsumugi = defineTsumugi({ performers: { SendMail } });const id = await tsumugi.enqueue(env, { binding: 'SendMail', payload: { to: 'a@example.com' } });

Features

Built from performers and enqueue

You define the job handler as a performer and call enqueue where you submit the job. Tsumugi handles delivery, execution, and state tracking.

Retries
Backoff
Delayed jobs
Scheduled jobs
Priority
Concurrency
Rate limits
Deduplication
Dashboard

Job management built in

Retries, backoff, delayed jobs, scheduled jobs, priority, concurrency and rate limits, deduplication, and a dashboard are standard features of Tsumugi.

Finished jobs stay visible

The dashboard and REST API list and search every job, including succeeded and failed ones. With the TSUMUGI_METRICS binding configured, Tsumugi also records failure rate and duration metrics.

Workflows with dependencies

Declare nodes and their dependencies, and each node's return value is passed to the next node as its payload. With fan-out, a child node is created for each element of an array and runs in parallel.

Asynchronous work with a method call

Calling enqueue(env, { binding, payload }) enqueues a job. The call returns the job ID and completes immediately.

Per-job execution guarantees

A job with guarantee set to at-most-once never runs twice. The default guarantee is at-least-once.

Performers in another Worker

Tsumugi runs performers even when they live in another Worker connected through a Service Binding.

Tsumugi

What Tsumugi solves

Job state is hard to track, and succeeded jobs are not kept

Mutual exclusion and deduplication are hard to implement

More job types mean more branching

Messages are occasionally lost