Hook onRoute doesn't work correct inside registered plugin

[corsicanec82]

Prerequisites

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

Fastify version

4.1.0

Plugin version

No response

Node.js version

16.15.1

Operating system

Linux

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

Ubuntu 22.04 LTS

Description

If the onRoute hook is in the main application code, then callback is called for all routes. And extraneous HEAD routes appear. If the onRoute hook is placed inside the plugin, then the callback is called only for the HEAD routes. But registration of such a HEAD route did not occur.

Steps to Reproduce

Example:

const fastify = Fastify({ logger: true });

fastify.addHook('onRoute', (routeOptions) => {
  const { path, method } = routeOptions;
  console.log({ path, method });
});

fastify.get('/', (req, reply) => {
  reply.send('index');
});

// Output:
// { path: '/', method: 'GET' }
// { path: '/', method: 'HEAD' }

Example with hook inside plugin:

const fastify = Fastify({ logger: true });

fastify.register((instance, opts, done) => {
  instance.addHook('onRoute', (routeOptions) => {
    const { path, method } = routeOptions;
    console.log({ path, method });
  });
  done();
});

fastify.get('/', (req, reply) => {
  reply.send('index');
});

// Output:
// Empty output

Example with using fastify-plugin

import fp from 'fastify-plugin';

const fastify = Fastify({ logger: true });

fastify.register(fp((instance, opts, done) => {
  instance.addHook('onRoute', (routeOptions) => {
    const { path, method } = routeOptions;
    console.log({ path, method });
  });
  done();
}));

fastify.get('/', (req, reply) => {
  reply.send('index');
});

// Output:
// { path: '/', method: 'HEAD' }
// No GET route

Expected Behavior

Inside the plugin, the hook should have a route { path: '/', method: 'GET' } and should not have a HEAD route. When using a hook outside the plugin, there should also be only one GET route.
This behavior was in fastify version 3.29.0.

[mcollina]

This is the sum of a few semver-major changes in Fastify v4.

1. Fastify will generate a new HEAD route for all your GET routes. You can disable it with exposeHeadRoute: false in the Fastify options.
2. route definition is now synchronous, so if you specify an 'onRoute' hook in a plugin you should either
   a. wrap your routes in a plugin (recommended)
   b. use await register(...)

We should better document those in https://github.com/fastify/fastify/blob/main/docs/Guides/Migration-Guide-V4.md. Would you like to send a PR?

[corsicanec82]

Thanks for your reply!
Using the await with register helped to get the desired behavior.
I'm afraid that my knowledge of English will not be enough to send a PR to the migration guide.

[denes-fekeshazy]

I have created a small PR to update the migration documents based on @mcollina's comment and the article about the v4 release: https://medium.com/@fastifyjs/fastify-v4-ga-59f2103b5f0e.
PR: #4091