Overview

Tsumugi is a job management system designed for Cloudflare Workers.
You define job processing as a performer and submit jobs with enqueue.
Tsumugi handles job delivery, execution, and state recording.
It also provides a management dashboard and a REST API.

What problems does it solve?

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

Job state is hard to manage, and successful jobs are not retained

Queues does not provide an API for querying the state of a message you have submitted.
Successful messages are not retained either, so there is no way to review past executions later.

Tsumugi's dashboard and REST API provide listing, search, and aggregation for both running jobs and finished jobs.
When you configure the TSUMUGI_METRICS binding, the failure rate and execution time are recorded as metrics.

Exclusive control and deduplication are hard to implement

Queues does not manage dependencies or relationships between messages.
As a result, you must implement on your own the prevention of concurrent execution for the same customer and the elimination of duplicate submissions.

In Tsumugi, jobs that specify a concurrencyKey are executed one at a time, in order, among jobs with the same key.
When you specify a uniqueKey, a job submitted with the same key within a certain period is treated as a duplicate, and the existing job ID is returned without creating a new job.

The more job types you have, the more branching you need

With Queues, you can set only one consumer for each queue.
As a result, as job types increase, you must either add more queues or deal with increasingly complex branching inside the consumer.

Tsumugi distinguishes job types by using the export name of each performer as the binding name, so you do not need to write branching in a consumer.
The relationship between binding names and payload types is described in binding名.

Messages are occasionally lost

Queues does not provide a way to detect messages that were lost without being processed.

When a job that has started execution does not report a result, Tsumugi determines that the job is unresponsive.
With at-least-once semantics, an unresponsive job is re-enqueued.
With at-most-once semantics, an unresponsive job transitions to the STALLED state and is not executed until it is retried manually.

The code you write

You write code in only two places: the job processing definition and the submission.

import { defineTsumugi } from 'tsumugi';
import { Performer } from 'tsumugi/performer';

// 1. Define the job processing as a performer and export it
export class SendMail extends Performer<{ to: string }, void, {}, Env> {
  async perform(payload: { to: string }): Promise<void> {
    await this.env.MAILER.send(payload.to);
  }
}

const tsumugi = defineTsumugi({ performers: { SendMail } });

// 2. Submit the job. The binding name is the exported name
const id = await tsumugi.enqueue(env, { binding: 'SendMail', payload: { to: 'a@example.com' } });

You do not need to write the queue configuration, consumer branching, or state recording.
Each feature is described in Enqueueing jobs, Controlling execution, Scheduled execution, and Dashboard and authentication.

Prerequisites

You need the Workers Paid plan and a compatibility_date of 2025-11-17 or later.
Create the required resources and configuration with npx tsumugi init.
For the steps, see Getting Started.

Inspiration

The design of a job queue built entirely on Cloudflare services, bundled with a dashboard, was inspired by Kiribi.
Tsumugi also shares Kiribi's policy of minimizing the setup steps and keeping the internal architecture hidden from users.

Tsumugi provides execution volume limits, per-job execution guarantees, retry control, multi-stage execution with Flow, and scheduled execution.
Because of these features, the resources and configuration you must prepare are greater than with Kiribi.