Cron Triggers
A Cron Trigger runs a Worker on a schedule. Cello keeps the schedule of a script in one reserved cell, so a fleet runs each occurrence once. Read the Cloudflare Cron Triggers documentation for the API.
Example
The Cron Trigger example logs the scheduled time once a minute.
API
A Worker exports a scheduled(controller, env, ctx) handler.
controller.cronholds the expression text.controller.scheduledTimeholds the occurrence in milliseconds.controller.noRetry()stops the retries of a failed occurrence.ctx.waitUntil()extends the invocation. Cello drains this work before the next invocation.
Schedules
A project declares its schedules in a triggers.crons array. cello deploy
fails on a malformed expression, and on triggers.crons without main. Cello
sets no limit on the number of expressions.
Cello reads the Cloudflare cron dialect. An expression has five fields: minute,
hour, day of month, month, and day of week. The resolution is one minute, and
the zone is UTC. Weekdays are
numbered 1 to 7 from Sunday,
so 1-5 means Sunday to Thursday.
Each field takes *, a value, an a-b range, an a,b list, and a /n step.
The month and day-of-week fields also take three-letter names in any case, such
as JAN and MON. The day-of-month field takes L, L-<n>, LW, L-<n>W,
and <d>W, and the day-of-week field takes <dow>L and <dow>#<n>. When both
day fields are restricted, they form a union, so 0 0 1 * MON fires on the
first day of each month and on every Monday. Only a literal * leaves a day
field unrestricted.
Cello refuses a descending range such as SAT-SUN and a list that contains
*, such as 1,*. Cloudflare accepts both with surprising results. A step
cannot exceed the width of its field, so */60 fails in the minute field.
Execution
controller.scheduledTime holds the scheduled occurrence and not the start of
the attempt, so a late run and a retry name the same minute. Cello runs the
handlers of one script one at a time and drains the waitUntil() work of each
before the next. A handler that takes longer than the interval delays the next
occurrence. Move long work into a queue or a
Workflow.
A handler that throws retries after 4 seconds, and the delay doubles after each
further failure. Cello gives up after six failures, or at the next occurrence,
which never waits for a retry, so a schedule faster than the
backoff never retries. controller.noRetry() stops the retries. An
ownership move loses a pending retry.
After downtime, Cello runs one missed occurrence and skips the rest. Read the
interval from controller.scheduledTime to catch up in application code.
The node that owns the reserved cell runs the occurrence, and that node can
change. A triggers.crons entry in a service-binding target never runs, and
Cello logs a warning when it loads such a target.
Differences from Cloudflare
- Cello rejects a descending range such as
SAT-SUNand a list that contains*. - Cello runs one handler for each occurrence across the fleet. After downtime, it runs one missed occurrence and skips the rest.
- Cello serializes the handlers for one script. It retries a failure until the
next occurrence unless the handler calls
noRetry(). - A service-binding target cannot run its own Cron Triggers.
The Cloudflare compatibility page lists the runtime APIs and the unsupported services.