Skip to content

fix(core): let a GET middleware exclusion cover HEAD requests - #17950

Merged
kamilmysliwiec merged 2 commits into
nestjs:masterfrom
Chaoqi31:fix/middleware-exclude-head
Sep 30, 2026
Merged

kamilmysliwiec merged 2 commits into
nestjs:masterfrom
Chaoqi31:fix/middleware-exclude-head

Conversation

@Chaoqi31

Copy link
Copy Markdown
Contributor

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

  • Bugfix
  • Feature
  • Code style update (formatting, local variables)
  • Refactoring (no functional changes, no api changes)
  • Build related changes
  • CI related changes
  • Other... Please describe:

What is the current behavior?

consumer
  .apply(AuthMiddleware)
  .exclude({ path: 'health', method: RequestMethod.GET })
  .forRoutes('*');

GET /health skips the middleware, but HEAD /health still runs it, although the router serves HEAD from the @Get() handler. Uptime monitors and load balancers often probe with HEAD, so the health check gets the middleware's 401 or side effects. Express and Fastify behave the same way.

isMiddlewareRouteExcluded() passes the request method straight to isRouteExcluded(), which needs an exact method match. When deciding whether a middleware runs, MiddlewareModule.registerHandler() already lets a HEAD request match a RequestMethod.GET route (pinned by the "HEAD auto-forwarding to GET" cases in integration/hello-world/e2e/middleware-fastify.spec.ts), so a middleware bound to GET runs for HEAD while an exclusion for GET does not cover it.

The new spec against the current utils.ts:

 × middleware utils > isRouteExcluded > when a HEAD request targets a route excluded for GET > should return true
AssertionError: expected false to be true // Object.is equality

Issue Number: N/A

What is the new behavior?

A HEAD request is excluded when the route is excluded for HEAD or for GET, the same HEAD-for-GET rule that registerHandler() uses. isRouteExcluded() itself is unchanged, since the global prefix exclusion also uses it. A HEAD-only exclusion still does not cover GET requests; a second new case pins that, so the rule cannot be widened into skipping the middleware for GET. The rule is by path and method, not by handler: a route that also has an explicit @Head() handler and is excluded for GET now skips the middleware on HEAD as well.

A throwaway app on Express and Fastify, with forRoutes('*') and with forRoutes({ path: '*', method: RequestMethod.GET }), now skips the middleware for HEAD /health and still runs it for other paths.

Does this PR introduce a breaking change?

  • Yes
  • No

Other information

npx vitest run packages/core: 1401 passed.

`MiddlewareConsumer.exclude({ path, method: RequestMethod.GET })` skipped
the middleware for GET requests only. A HEAD request to the same path,
which the router serves from the GET handler, still ran it, although
the middleware module already lets a HEAD request match a GET
middleware route when deciding whether the middleware runs.

Treat a HEAD request as excluded when the route is excluded for GET.
A HEAD-only exclusion still does not cover GET requests.
@kamilmysliwiec
kamilmysliwiec merged commit 2e4dea3 into nestjs:master Sep 30, 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