fix(tasks): stop scheduled tasks on runtime close

[Prains]

Resolves #4415.

Problem

Scheduled Croner timers must stay referenced for custom CLI-only entries, but referenced timers also need to be released during graceful server shutdown.

Change

• Keep scheduled task timers referenced while the runtime is active.
• Retain Croner jobs and stop them from the Nitro close hook.
• Forward srvx server shutdown to the Nitro runtime close hook for Bun, Node, Node cluster, and Deno server presets.
• Cover timer ownership, close cleanup, and srvx lifecycle forwarding with unit tests.

Verification

• pnpm test
• Rollup: 900 passed, 137 skipped, 13 todo
• Rolldown: 900 passed, 137 skipped, 13 todo
• Bun 1.3.14 SIGTERM reproduction: process exits with code 0 after Server closed successfully.

[vercel]

@Prains is attempting to deploy a commit to the Nitro Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 5d1120f2-f76e-410a-a6e5-24a29e3eb0a9

📥 Commits

Reviewing files that changed from the base of the PR and between 7612a1a and 7879c6f.

📒 Files selected for processing (2)

• docs/1.docs/50.tasks.md
• test/unit/task.test.ts

 __________________
< I see dead code. >
 ------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c7b8768f-9c6a-45eb-951d-f1927c5d76c6

📥 Commits

Reviewing files that changed from the base of the PR and between 206f243 and 7612a1a.

📒 Files selected for processing (2)

• src/runtime/internal/task.ts
• test/unit/task.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• test/unit/task.test.ts
• src/runtime/internal/task.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

startScheduleRunner now retains scheduled Cron instances and stops them through Nitro’s "close" hook. Tests cover multiple jobs and continue-on-error behavior when one stop() call throws.

Changes

Runtime shutdown lifecycle

Layer / File(s)	Summary
Scheduled task shutdown cleanup src/runtime/internal/task.ts, test/unit/task.test.ts	startScheduleRunner stores created Cron instances and stops each one during the Nitro "close" hook. Stop errors are logged without preventing later jobs from stopping. Unit tests cover hook registration, multiple stop calls, and stop failures.

Priority: ➖ Normal — Impact reflects medium issue severity.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 7612a

Scheduled Croner tasks now remain active during server operation and stop on Nitro close, allowing graceful shutdown without lingering timers. No current merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits syntax and accurately describes stopping scheduled tasks when the runtime closes.
Description check	✅ Passed	The description explains the scheduled-task shutdown problem, the Croner cleanup change, and the related verification.
Linked Issues check	✅ Passed	The changes retain scheduled Croner jobs during runtime and stop them through the Nitro close hook, which addresses issue #4415 by allowing graceful shutdown to terminate the process normally.
Out of Scope Changes check	✅ Passed	The code and test changes are limited to scheduled-task lifecycle cleanup and its regression coverage, which are within the scope of issue #4415.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pi0]

While this is a valid fix for durable servers, if someone makes a custom entry like CLI only app, scheduled tasks should keep running even without server listener ref.

I think better alternative would be to make sure scheduled tasks are destroyed when calling nitro close hook in runtime.

[Prains]

@pi0 Updated in 089466b8: scheduled timers remain referenced for CLI-only entries, Croner jobs stop from the Nitro close hook, and srvx server shutdown now forwards to that runtime hook for Bun, Node, Node cluster, and Deno server presets. The Bun SIGTERM reproduction exits cleanly, and the full Rollup/Rolldown suite passes.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/runtime/internal/app.ts`:
- Around line 42-50: Make shutdown resilient in nitroRuntimeHooksPlugin at
src/runtime/internal/app.ts lines 42-50 by catching failures from the memoized
close hook and ensuring the original server.close call always proceeds; in
src/runtime/internal/task.ts lines 69-73, wrap each job.stop() invocation in
try/catch so one failing job does not prevent subsequent jobs from stopping or
reject the close hook.

In `@src/runtime/internal/task.ts`:
- Around line 75-89: Update the Cron construction in the scheduledTasks loop to
pass an options object with unref enabled, while preserving the existing
scheduled callback. Update the related unit test expectation to include this
Cron option.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4cb6a897-b57a-4a6c-85f1-583e8efacb1c

📥 Commits

Reviewing files that changed from the base of the PR and between eee0abd and 089466b.

📒 Files selected for processing (8)

• src/presets/bun/runtime/bun.ts
• src/presets/deno/runtime/deno-server.ts
• src/presets/node/runtime/node-cluster.ts
• src/presets/node/runtime/node-server.ts
• src/runtime/internal/app.ts
• src/runtime/internal/task.ts
• test/unit/runtime-app.test.ts
• test/unit/task.test.ts

[xmlking]

I noticed same issue with bun runtime with scheduledTasks. looking to this fix

[pi0x]

Rebased this on latest main locally to check it. Notes:

• Main already landed the same server-close wiring in fix(node, bun, deno): call runtime close hooks on server shutdown #4574 (setupCloseHooks in src/runtime/internal/shutdown.ts). So nitroRuntimeHooksPlugin, the four preset edits and test/unit/runtime-app.test.ts are now duplicates. Please drop them.
• The other half still applies and is the useful part: keeping the Cron jobs and stopping them on the close hook. It also fixes the dev server, which already calls that hook.
• Nothing here uses unref or Node-only APIs, so workers and edge are fine.
• Small nit: import useNitroHooks from ./app.ts, like shutdown.ts does.
• node_middleware starts schedules but has no server to close, so crons still run on there.

I could not push my rebase from this environment.

This comment was written by an AI assistant on behalf of the Nitro maintainers. Please double-check anything that looks wrong.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[Prains]

@pi0, updated the branch based on the latest feedback and rebased it onto main (206f243c). The current HEAD is 7612a1a0.

• Removed nitroRuntimeHooksPlugin, the four server preset changes, and test/unit/runtime-app.test.ts. The branch now relies on the existing setupCloseHooks from fix(node, bun, deno): call runtime close hooks on server shutdown #4574.
• Kept the Cron job references and cleanup through the runtime close hook, including per-job stop() error isolation and tests.
• Changed the useNitroHooks import to ./app.ts and updated the test mock. No unref or Node-only APIs were added.
• Left node_middleware behavior unchanged: closing the external server does not automatically call the Nitro close hook, so the integration still needs to connect the host lifecycle to that runtime hook explicitly.

Validation: formatting, lint, build, typecheck, and all 7 targeted tests passed. The full Rollup and Rolldown runs each had 1,039 passing tests and one failure in test/vite/hmr.test.ts involving an extra full-reload. All 7 HMR tests passed when rerun separately with each builder. The full pipeline is therefore not reported as fully passing; this PR does not change the HMR code.

For transparency, this comment was prepared with AI assistance. The feedback was checked against the current code, and the validation results above include the observed test failures.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4416

commit: 7612a1a