[bpamiri]

Refs #4481 (recurring schedules, merged in #4493). This is the follow-up that runs them.

Problem

Since #4493 an app can define schedules (config/schedules.cfm, schedule()), but nothing called JobScheduler.enqueueDue(). Due slots were only enqueued if the app called it itself.

Change

Due schedule slots are now enqueued from the normal job processing:

• Worker poll. JobWorker.processNext() checks right after its reap, so wheels jobs work, processQueue() and JobRunner.tick() all cover it.
• Tick. JobRunner.tick() checks before it dispatches, so a slot due now can run in the same tick. It reports the slots it enqueued as scheduled.

Throttle. At most one check every jobsScheduleCheckSeconds, default 15; 0 turns it off. The throttle is per application, under a short exclusive lock, so concurrent polls on one server don't stack checks.

Several servers. Any number of servers can check at once: each slot is enqueued exactly once, through its uniqueKey (#4493).

Apps without schedules. They are unaffected: the check only runs when the schedules table exists, so it never creates one.

Never breaks a poll. A failing check, or a schedule error, is logged and the poll carries on. It also skips inside a Wheels transaction.

Tests

JobScheduleRunnerSpec (4):

• a worker poll enqueues a due slot;
• tick() enqueues it and reports scheduled = 1;
• a second check inside jobsScheduleCheckSeconds does nothing;
• 0 turns it off.

On develop:

• 1 fails: the poll doesn't enqueue anything.
• 2 error: there is no scheduled key and no throttled check.

Local results:

• Full core suite, Lucee 7 + SQLite: 7229 pass, 0 fail, 0 error.
• Jobs specs, Lucee 7: green on all seven databases; PostgreSQL and CockroachDB also green on a second run against the same database.
• Jobs specs, BoxLang: green on SQLite, PostgreSQL and CockroachDB.
• Jobs specs, Adobe 2023: green on SQLite and MySQL.
• Jobs specs, Adobe 2025: green on SQLite and SQL Server.
• Complexity gate: passes.

Docs

The guide's schedules section (#4485) says that schedules run from the worker or a tick and covers jobsScheduleCheckSeconds. Changelog fragment included.

🤖 Generated with Claude Code

[github-actions]

Wheels Test Results

147 895 tests   145 177 ✅  59m 21s ⏱️
 11 880 suites    2 718 💤
     20 files          0 ❌

Results for commit 4e4fac2.

♻️ This comment has been updated with latest results.

[bpamiri]

Review: head db35dcf. APPROVE (ready to merge). Two LOW, two INFO.

Verified

• No double enqueue across hosts.
  • $enqueueDueSchedules() calls JobScheduler.enqueueDue(), whose per-slot uniqueKey ("<name>:<UTC ISO>") plus the monotonic lastEnqueuedFor guard (feat(job): recurring schedules (cron and intervals) with one job per slot #4493) gives one job per slot however many servers check.
  • The new code adds a throttle, not another enqueue path.
• Interval and memo.
  • jobsScheduleCheckSeconds defaults to 15 and is registered at app start; ≤ 0 turns it off.
  • The memo lives per application in application.wheels.$jobsScheduleCheckedAt, compared as tick-count differences only. It's re-checked inside lock name = "wheels.jobs.scheduleCheck" … throwOnTimeout = "false", so concurrent polls in one app check once and never throw.
  • The write goes to a var gate struct inside the lock body, not in a catch.
• No schedules table. It runs only when $schedulesTableExists(). It never creates the table, so apps without schedules are unaffected, with or without jobsAutoCreateTables. It's skipped inside a Wheels transaction, so the probe never touches a transaction.
• Errors never break the poll. The scheduler call is wrapped in try/catch and logged, and enqueueDue's per-schedule errors are logged.
• Wiring.
  • processNext() calls it after the reap and before the drain/cap checks, so processQueue() gets it too.
  • tick() calls it before running jobs, so a slot that's due now can run in the same tick, and reports scheduled. The second call, inside processNext(), is throttled away.
• Cross-engine. The script lock block and var struct state are fine.

Matrix 37849380151 at db35dcf:

• 32/32 legs green, 0 fail / 0 error;
• JobScheduleRunnerSpec 4/4 and JobSchedulerSpec 23 + 1 expected skip on every leg;
• RustCFML 7204/0/0.

PR CI: 23 pass, 0 fail, 2 skipped.

LOW

1. Spec gaps. JobScheduleRunnerSpec covers enqueue from a poll, tick().scheduled, the throttle and 0. It doesn't cover:

   • an enqueueDue() that throws (the poll must still return normally);
   • no schedules table (no check, no table created);
   • a draining host.

   Two short specs would pin the "never breaks the poll" and "never creates the table" promises.

2. The default differs from the guide's placeholder. The code default is 15 s, but docs(web): add the 4.2 "Running Jobs on Multiple Servers" guide #4501's "Planned: automatic schedule runner" aside says jobsScheduleCheckSeconds (default 30). The guide fold should use 15. I'm passing this to the guide author.

INFO

• A draining host still enqueues due slots, because the schedule check runs before the drain check in processNext(). That's harmless (enqueueing runs nothing, and the slot runs on whichever host isn't draining), and arguably right: a deploy that drains every server doesn't lose slots. Worth one sentence in the guide.
• An app without a schedules table pays one failing probe SELECT per app every 15 s. That's cheap and outside transactions; fine.

[bpamiri]

Final review: head 4e4fac2. APPROVE (ready to merge).

• The LOW spec gaps are closed (b4366e7). JobScheduleRunnerSpec now covers:

  • an enqueueDue() that throws (mocked through the new $newScheduler() seam): the poll returns normally and the failure is logged;
  • no schedules table: no check and no table created;
  • a draining host: tick() reports draining = true and scheduled = 1.

  The seam is a one-line factory, so production behaviour is unchanged.

• Develop merge (c284bc0, feat(cli): wheels jobs install and jobsAutoCreateTables #4499). The change set against the new base is the approved db35dcf plus that seam and the specs (Job.cfc +54 = 47 + 7; spec +132 = 95 + 37). Both conflicts were additive and both sides were kept:

  • Job.cfc: $newScheduler / $enqueueDueSchedules beside $throwJobSchemaMissing / $jobSchema;
  • onapplicationstart: jobsScheduleCheckSeconds = 15 beside jobsAutoCreateTables and jobsHeartbeatGraceSeconds.

• Interaction with feat(cli): wheels jobs install and jobsAutoCreateTables #4499. $ensureSchedulesTable() honours jobsAutoCreateTables, and $enqueueDueSchedules() checks that the table exists before calling the scheduler. With auto-create off and no schedules table, the check is a quiet skip; it never throws and never creates anything.

• Matrix 37859520416 at 4e4fac2 (5 engines × sqlite/postgres/cockroachdb/sqlserver):

  • 20/20 legs green, 0 fail / 0 error, 594 bundles;
  • JobScheduleRunnerSpec 7/7 and JobSchemaSpec 8/8 on every leg;
  • RustCFML 7225/0/0.

• Earlier evidence: the full matrix 37849380151 (32/32) at db35dcf.

• PR CI at 4e4fac2: 23 pass, 0 fail, 2 skipped. Merge state is clean.