Skip to content

fix(fastify): settle async lifecycle hooks once - #17997

Merged
kamilmysliwiec merged 2 commits into
nestjs:masterfrom
jackie-cqz:fix/fastify-async-hooks
Oct 8, 2026
Merged

kamilmysliwiec merged 2 commits into
nestjs:masterfrom
jackie-cqz:fix/fastify-async-hooks

Conversation

@jackie-cqz

@jackie-cqz jackie-cqz commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

PR Checklist

  • Commit message follows the contribution guidelines
  • Regression tests added
  • Docs updated (no API additions)

PR Type

  • Bugfix

What is the current behavior?

The Fastify wrappers discard the results of setOnRequestHook and setOnResponseHook, although both accept Promise-returning hooks. A promise-only request hook leaves the request pending, and an async response hook does not advance the response lifecycle.

Simply returning the promise introduces another failure: an async hook that also calls done() advances Fastify twice. A POST handler awaiting asynchronous work can execute twice, and the final response callback can run twice.

Issue Number: N/A

What is the new behavior?

Both wrappers complete through a shared, once-only callback. Whichever happens first — done(), promise fulfillment, or failure — settles the hook. Promise rejection and synchronous throws reach Fastify through the guarded callback; later completion signals are ignored. The wrappers consume the promise rather than returning it to Fastify.

The implementation preserves callback hooks and their adapter receiver, and retains Fastify's error for a promise rejected without a reason. Real injected requests verify promise-only hooks, error handling, async hooks that also call done(), repeated/late callbacks, late rejection, and exactly one response completion.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

Validation on the existing PR branch:

  • All 12 lifecycle-hook tests pass, including 8 additional tests.
  • Before the review fix, the mixed async/done POST handler and response completion each ran twice; their regressions failed, along with the repeated callback regression.
  • Unit suite: 3824 passed. Two existing process-signal tests were excluded on Windows because they terminate the test worker: shutdown process should not be interrupted by another handler and should defer shutdown until all init hooks are resolved.
  • npm run build, npm run lint:ci, and git diff --check passed. Lint retains one existing warning in packages/websockets/socket-module.ts.

Unit command:

npm test -- --reporter dot --testNamePattern '^(?!.*(shutdown process should not be interrupted by another handler|should defer shutdown until all init hooks are resolved)).*'

@kamilmysliwiec kamilmysliwiec left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Returning the hook's promise fixes promise-only hooks, but it breaks the documented style (setOnRequestHook says to call done()): for an async (req, reply, done) => { await x; done(); } hook, fastify's hook runner now continues twice, once from done and once when the promise resolves, so the route handler runs twice (a POST would create its record twice). The same pattern makes the final onResponse callback run twice.

Instead of returning the result, please guard done so it can only fire once and continue on whichever comes first, done being called or the returned promise settling (rejection → done(err)), and add a test with an async hook that also calls done(), asserting the handler runs once.

@jackie-cqz jackie-cqz changed the title fix(fastify): forward async lifecycle hook results fix(fastify): settle async lifecycle hooks once Oct 8, 2026
@kamilmysliwiec
kamilmysliwiec merged commit 8857ab6 into nestjs:master Oct 8, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants