Configuration

defineTsumugi

const tsumugi = defineTsumugi({
  performers,
  flows,
  schedules,
  runs,
  bindings,
  auth,
  ui,
  retention,
  metrics,
  onFailure,
  onSettled,
  onEnqueue,
});

defineTsumugi does not need type arguments.
The payload type for each binding and Env are inferred automatically from the contents of performers.

Return value

Even when flows is not specified, the return value includes start, runFor, and runClass.
Passing a Flow name that is not defined in flows to start throws an exception.
Calling runFor when the RUN binding does not exist also throws an exception.
For the differences between enqueue methods, see Enqueueing jobs.

auth

You can pass a custom authentication function to auth.
The function takes request and env and returns a Response or undefined.
For details, see Dashboard and authentication.
When auth is not set, all requests to the REST API and the dashboard receive a 404 response.
For the effects of unsafeNoAuth, see Dashboard and authentication.

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 configures how the recorded metrics are read from the dashboard and the REST API.
apiToken is an API token with read permission for Account Analytics. Set it as a Secret.
dataset is the dataset name written in analytics_engine_datasets in the wrangler configuration file.
When metrics is not specified, GET /api/metrics responds with 501, and the dashboard sidebar does not show the metrics item.

onFailure

const tsumugi = defineTsumugi({
  performers,
  onFailure: 'NotifyFailure',
});

onFailure is the binding name of the performer that is notified of failed jobs.
The performer that receives the notification must be one that accepts FailureNotice.
For the notification conditions and the contents of FailureNotice, see Failure notifications.

onSettled

const tsumugi = defineTsumugi({
  performers,
  onSettled: { binding: 'NotifySettled', states: ['COMPLETED', 'FAILED'] },
});

onSettled specifies the binding name of the performer that is notified of finished jobs, and the states to notify.
binding must be a performer that accepts SettledNotice.
states is required. Choose from COMPLETED, FAILED, CANCELLED, and STALLED.
Specifying an empty array or an invalid state throws an exception in defineTsumugi.
For the notification conditions and the contents of SettledNotice, see Completion notifications.

onEnqueue

const tsumugi = defineTsumugi({
  performers,
  onEnqueue: (input) => (input.binding === 'SlowJob' ? { timeoutMs: 300_000 } : undefined),
});

onEnqueue is a function that sets default execution options each time a job is enqueued.
Values explicitly specified by the caller always take precedence.
For the enqueue methods it applies to and the options that receive the defaults, see Defaults at enqueue time.

RunSettings

BindingConfig

Policy

EnqueueInput

For details on the options, see Enqueueing jobs.

enqueue of createClient takes EnqueueInput as its argument.
For the input accepted by enqueue of defineTsumugi, the payload and required-key types are derived for each binding.

Default value of backoff

{ kind: 'exponential', baseMs: 1_000, factor: 2, maxMs: 3_600_000, jitter: true }

SweepOptions

When a cron trigger is configured, jobs and Runs that have finished are deleted from lists after olderThanMs has elapsed.

The period during which a Run can be resumed is set in runs.
A FAILED Run is deleted from lists after the longer of olderThanMs and runs.failedRetentionMs has elapsed.
FAILED and STALLED jobs are also deleted from lists after the longer of olderThanMs and the binding's failedRetentionMs has elapsed.

wrangler bindings

When TSUMUGI_METRICS does not exist, metrics are not recorded.
Nothing else changes.
If other required bindings are missing, the REST API responds with 503, and the response body includes the list of missing bindings.

A performer specified with remote() requires a Service Binding.
Do not use a fixed name for the binding name; use the key in performers as is.

"services": [
  { "binding": "MAIL", "service": "my-mailer", "entrypoint": "SendMail" },
]

A Worker that has no performers and is used only to enqueue jobs needs only the JOB_SHARD binding.

Subpaths

The published npm package is tsumugi.
Run the setup CLI with npx tsumugi.
For the list of commands, see CLI.