Feature Request: Unified WebSocket Disconnection Method Across Environments

[shtse8]

Hello h3 team,

I am currently leveraging the new WebSocket feature in h3 for integrating GraphQL WebSocket functionalities into my application. While exploring the capabilities and trying to integrate graphql-ws with h3, I encountered a limitation that I believe could be beneficial to address for the wider h3 user community.

Issue Description:

The current WebSocket handler implementation in h3 does not provide a built-in method to close WebSocket connections directly within the handler functions (open, message, close, error). This limitation requires users to access the underlying context (ctx) to close the socket manually. However, the context object's structure is dependent on the runtime environment (e.g., Node.js vs. Bun), leading to a non-uniform approach to closing WebSocket connections. In Node.js environments, the socket can be closed using ctx.node.server, whereas in Bun environments, ctx.bun.ws is used.

A critical aspect of this issue is the behavior observed when exceptions are thrown within WebSocket handlers. Currently, even when an exception is encountered, the WebSocket connection remains active. This behavior can lead to unintended consequences, such as open connections that should have been terminated, reflecting a gap in the error handling and connection management capabilities of h3's WebSocket feature.

Example Scenario:

I was attempting to manually handle GraphQL WebSocket messages using h3's defineWebSocketHandler feature. Upon needing to close the WebSocket connection from within my message handler based on specific conditions, I realized that there wasn't a straightforward way to do this across different environments without directly accessing environment-specific context properties.

Proposed Solution:

It would be highly beneficial if h3 could abstract the environment-specific details and provide a unified way to close WebSocket connections directly within the WebSocket handler functions. A possible solution could involve enhancing the peer object provided to the WebSocket handlers with a method like peer.close(), which internally handles the environment-specific logic for closing the connection.

This enhancement would greatly simplify the development experience, especially for applications that need to run across different JavaScript runtimes and require consistent behavior for managing WebSocket connections.

Potential Benefits:

• Simplifies WebSocket management by providing a uniform API across different environments.
• Enhances the portability of h3-based applications that use WebSockets, making it easier to run the same application codebase in different JavaScript runtimes.
• Improves developer experience by abstracting away the environment-specific details involved in WebSocket connection management.

I believe this feature would be a valuable addition to the h3 library, enhancing its flexibility and ease of use for real-time applications. I am looking forward to your thoughts and feedback on this proposal.

Thank you for considering this feature request.

Additional information

• Would you be willing to help implement this feature?

[tobiasdiez]

This seems to be the same request as unjs/crossws#23.

Btw, I came across the same use case as you as I also implemented graphql-ws support on top of crossws. It's working great so far, and I will include it in the apollo-server h3-integration package: apollo-server-integrations/apollo-server-integration-h3#65. Would be awesome if you could give it a try and maybe compare the code to what you have. I'm happy to incorporate any feedback.