Skip to content

Scheduler In progress

Send a message at a set time or on a repeating rule, without running a timer yourself.

A schedule says when to send, where to send and what to send. When its time comes, the message is published on the NATS subject you named, and anything subscribed to that subject receives it.

In progress, not running yet

The scheduling logic is written and tested, but no service runs it yet, so there is nothing to call today. Where it stands has the detail.

Four ways to say when ​

Pick the timing rule that fits the job. A schedule uses exactly one.

NATS keeps the timerThe scheduler hands the rule to NATS, and NATS sends your message every time it comes due.
  • One time2026-12-01T09:00:00ZSend once, at an exact instant.
  • Fixed intervalevery 15mSend again after the same gap, counted from when the schedule starts.
  • Cron expression0 0 9 * * MON-FRISend on a calendar pattern, here 09:00 on weekdays, in the time zone you name. The first field is seconds.
The scheduler sets each timerNATS cannot read a recurrence rule. The scheduler works out the next date and sets one timer for it. When that timer fires, it sends your message and sets the next.
  • Recurrence ruleFREQ=WEEKLY;BYDAY=MO,WE,FRSend on an iCalendar rule, with a start, an optional end or count, dates to skip and extra dates, in the time zone you name.
A timer held by NATS Message sent Skipped date Extra date

From a schedule to a message ​

The scheduler keeps no timer of its own. It records what you asked for and hands the waiting to NATS, so no timer lives in a process's memory.

  1. YouSay when, where and what
  2. SchedulerRecords every change
  3. NATSHolds the timer
  4. Your subjectSubscribers receive it
  1. You say when, where and whatA timing rule, one NATS subject, and a message with a content type, a body and headers.
  2. The change is recordedCreate, pause, resume and remove each become an event in that schedule's log.
  3. NATS holds the timerThe scheduler turns the event into a NATS scheduled message. Nothing waits in the scheduler's memory.
  4. The message arrives on your subjectAnything subscribed there receives it. A one-time, interval or cron schedule can send the latest message from another subject instead of a fixed body.

Pause, resume, remove ​

A schedule moves through a few explicit states, and each state says whether it still fires.

  1. Scheduled FiresPauseRemoveFires on its timing rule. A schedule can also be created paused.
  2. Paused Does not fireResumeRemoveKept, with its timer cleared. Resume sets the timer again.
  3. Completed Does not fireRemoveA recurrence rule that has run out of occurrences. It cannot be resumed.
  4. Removed Does not fireNo further changesFinal. Its id is never reused, and its history stays.
A definition never changes. To send something different, or on a different rule, remove the schedule and create a new one under a new id.

What we promise ​

  • Safe to retryA repeated command is recognized, so a retry never records the same change twice.
  • Changes apply in orderChanges to one schedule are applied one at a time, so a pause never overtakes the create it follows. Other schedules keep moving.
  • Nothing is rewrittenEvery change is an event in the schedule's log, and removing a schedule keeps its history. The scheduler refuses to start on a log that could drop events.
  • A definition stays putPause, resume and remove only change whether a schedule runs. When, where and what it sends never change.
  • Removed is finalA removed schedule stops firing, and its id is never handed to a new schedule.
  • Overdue is marked, not firedA one-time schedule that is already five minutes or more overdue is marked expired instead of firing late.
  • One exact destinationA schedule delivers to one exact subject, never a wildcard and never one of the scheduler's own subjects.

Where it stands ​

  • Schedule commands, events and stateProtobuf schemas define every command, event and state a schedule can have.Built
  • Create, pause, resume and removeThe decision logic runs natively and as a WebAssembly module, and tests check that both give the same answers.Built
  • Schedule log and read modelChanges are stored as events on NATS JetStream with snapshots, and a view answers get and list. Available as a library.Built
  • Processor metrics and tracesThe processor counts the changes it handled, the timers it set and cleared and its redeliveries, and traces each change.Built
  • Firing through NATS scheduled messagesThe processor that sets and clears NATS timers is written and tested against stand-ins. Its tests against a live NATS server run outside CI.In progress
  • Recurrence rulesThe scheduler works out each next occurrence and records it when it fires. Written and tested, with nothing running it yet.In progress
  • Postgres read modelAn optional view stored in Postgres exists behind a build flag. Nothing selects it yet.In progress
  • Console screensScreens to list, create, pause, resume and remove schedules exist, running against a stand-in backend.In progress
  • Commands over the networkA NATS binding that carries commands to the scheduler is drafted.Designed
  • AuthorizationThe platform's command authorizer is decided, and the scheduler does not go through it yet. Schedules carry no tenant or project today.Designed

No service runs the scheduler yet, and the processor expects a single active instance. A NATS subject is the only delivery target.

Learn more ​

Understand the design

Check its behavior

Released under the Apache License 2.0.