feat: add handleUpgradeRequest route option

[infiton]

At gadget we make extensive use of @fastify/websocket. One use case is a websocket proxy that connects vite hmr clients in the browser to a developers serverless development environment. The vite client has a ping protocol with the following semantics:

1. If the vite dev server listening then the hmr endpoint should upgrade the connection and immediately close
2. If the vite dev server isn't listening yet the endpoint should reject the connection https://github.com/vitejs/vite/blob/main/packages/vite/src/node/server/ws.ts#L258-L263

We need a way to handle upgrade events in our proxy layer and not upgrade connections until we know that the upstream vite will also upgrade the connection. To do this I have introduced a route level option handleUpgradeRequest that allows for a route by route customization of how the upgrade event should be handled.

handleUpgradeRequest is a function that takes the incoming FastifyRequest, the source socket and the head buffer; to continue through to the normal wsHandler the use should return a promise that resolves to a connected websocket; to reject the connection the user can either throw an error (optionally with a statusCode) or write directly to/teardown the source socket

Checklist

• run npm run test && npm run benchmark --if-present
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[infiton]

@mcollina any thoughts on this?

[gurgunday]

lgtm

[Copilot]

Pull Request Overview

This PR introduces a new handleUpgradeRequest route-level option to allow custom handling of WebSocket upgrade requests before the standard WebSocket handler is invoked. This enables use cases like implementing a WebSocket proxy that needs to validate upstream connections before upgrading.

• Adds handleUpgradeRequest function option that receives request, socket, and head buffer parameters
• Allows custom upgrade logic with error handling and status code customization
• Maintains backward compatibility with existing WebSocket routing behavior

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

File	Description
index.js	Implements the core handleUpgradeRequest functionality with custom upgrade handling and error management
test/base.test.js	Adds comprehensive tests covering successful upgrades, error handling, and custom status codes
types/index.test-d.ts	Provides TypeScript type definitions and validation for the new upgrade handler
README.md	Documents the new feature with usage examples and API details

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}