onClose hook added right after await app.ready() runs before the server stops, while requests are still in flight #7166

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

5.12.7 (also on main, 6.0.0-alpha.5 at 5df959f)

Plugin version

Node.js version

24.21.0

Operating system

Windows

Operating system version (i.e. 20.04, 11.3, 10)

11

Description

addHook() is supposed to throw once the instance has started (FST_ERR_INSTANCE_ALREADY_LISTENING on 5.x, FST_ERR_INSTANCE_ALREADY_STARTED on main), but there is a window right after ready() resolves where it is still accepted. An onClose hook added in that window runs before Fastify's own close routine, so it releases its resource while the server is still listening and requests are still in flight.

Hooks.md says the opposite: "By the time onClose hooks execute, the HTTP server has already stopped listening, all in-flight HTTP requests have been completed, and connections have been drained."

// repro.mjs
import Fastify from 'fastify'

const pool = { open: true, query: async () => { if (!pool.open) throw new Error('pool is closed'); return 42 } }
const app = Fastify()
app.get('/slow', async () => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return { value: await pool.query() }
})

await app.ready()
app.addHook('onClose', async () => {
  console.log('onClose, listening:', app.server.listening)
  pool.open = false
})
await app.listen({ port: 0, host: '127.0.0.1' })

const res = fetch(`http://127.0.0.1:${app.server.address().port}/slow`, { headers: { connection: 'close' } }).then(async r => [r.status, await r.text()])
await new Promise(resolve => setTimeout(resolve, 50))
const closing = app.close()
console.log(...await res)
await closing

Output:

onClose, listening: true
500 {"statusCode":500,"error":"Internal Server Error","message":"pool is closed"}

Registering the same hook before ready() prints listening: false and 200 {"value":42}. The same hook is also accepted from a ready(cb) callback, and from inside an onReady hook, where it also runs before the server stops (see the note at the end about onReady).

The same window also leaves a half-registered route behind. After await app.ready(), app.get('/late', ...) throws AVV_ERR_ROOT_PLG_BOOTED, but the route was already inserted into the router (lib/route.js:363, before the this.after at lib/route.js:378 that throws). If the caller catches the error and keeps going, the first request to /late crashes the process with TypeError: Cannot read properties of undefined (reading 'length') (on main it is thrown from lib/hooks.js:341, while running the preParsing hooks of a context that was never finished).

What I think is happening (line numbers at 5df959f):

1. ready() resolves the user promise in manageErr (fastify.js:587), inside avvio's ready queue.
2. kState.started is only set on avvio's 'start' event (fastify.js:394, emitted at avvio/index.js:77, avvio 9.3.1), which happens after that.
3. Every check that rejects late registration reads kState.started: throwIfAlreadyStarted (fastify.js:491, used by addHook and route), decorate (lib/decorate.js:146) and the content type parser methods (lib/content-type-parser.js:378). So addHook, route and decorate called from a ready(cb) callback or right after await app.ready() pass them. One macrotask later (setImmediate) the same calls throw as expected.
4. addHook('onClose') goes to avvio's onClose (fastify.js:636), which does _closeQ.unshift (avvio/index.js:312), so close hooks run last-registered first.
5. The internal hook that runs preClose and calls server.close() is registered at preReady (fastify.js:408) and relies on being the last one registered. Anything added after it runs before it.

Link to code that reproduces the bug

Inline above.

Expected Behavior

Once ready() has resolved, adding a hook, a route or a decorator throws, as it does a tick later. A route that fails to register is not left in the router.

One way to get there is to set kState.started = true in manageErr right before the ready promise is resolved (fastify.js:587), so every check above sees it. I tried that locally on main: the await app.ready() and ready(cb) cases throw for addHook and decorate, the late route is rejected before it reaches the router (the request gets a 404 instead of crashing the process), and npm run unit passes (2386 passed, 0 failed).

This does not change onReady. test/hooks.on-ready.test.js:270 expects decorate to be accepted inside onReady (and a nested addHook('onReady'), which is accepted but never runs), so an onClose added there still runs before the server stops. Hooks.md already says onReady "cannot change the routes or add new hooks"; whether that case should throw or only be documented is your call.

Code that relies on the window after ready() would start throwing, so this may count as a breaking change. I'd be happy to send a PR with tests if this direction makes sense.