WebSocket API

[lilnasy]

Body

• Exploration branch: lilnasy:proposal-websocket

Summary

A way for adapters to expose websocket abilities to Astro.

Example

---
if (Astro.request.headers.has('Upgrade')) {
        const { socket, response } = Astro.upgradeWebSocket()
        // echo
        socket.addEventListener('message', (event) => {
                socket.send(event.data)
        })
        
        return response
}
---
<script>
        const websocket = new WebSocket(`ws://localhost:4321/`)
        websocket.addEventListener('message', (event) => {
                console.log(event.data)
        })
        websocket.addEventListener('open', () => {
                websocket.send('Hey ho!')
        })
</script>

Background & Motivation

As astro matures as a choice for the backend framework, it becomes natural to want to utilize server features using it. Among these features is websockets, a cornerstone for real-time applications.

• Using the platform-provided API directly (Deno, Cloudflare) comes at the cost poking holes in the type-safety.
• No good way to test the functionality in dev mode.
• Node adapter operates on a layer of abstraction for WHATWG Request and Response objects, making it impossible to use websockets in standalone mode.

This proposal introduces an abstract runtime API for websockets that adapters can implement, giving users ease of use, full type-safety, and effortless migration from one adapter to another.

Goals

• Decide an agnostic API for websockets.

Non-Goals

• Implement the API for every platform. The adapters can implement the API at their own pace.

Testing Strategy

This feature can be adequately tested by fixture-based suites.

Alternatives

• Socket.io - necessitates shipping a runtime library to the browser.

[lordnox]

While trying to figure out how you solved the "there is no request-close event" issue I found that you saved the request within the "innerRequest"-Symbol.

Would it not make more sense to actually change the Astro.request from a basic WebAPI Request object to one which is what is actually required by server usage, like the http.IncomingMessage of node, or maybe just an enhanced version with an eventEmitter to handle the close event?

[lilnasy]

It would, except the standard WHATWG Request is the one required by server usage on runtimes other than Node.

For example, the two that inspired this API - Deno and Cloudflare Workers.

[bvoigtlaender]

This would be an great addition and a needed one. There are many use cases besides a simple chat to be able to add that little extra and reactivity to your website. Hope to see this added in the main branch one day. 🤞

[lilnasy]

You can use it today! There are websocket-enabled adapters.

https://github.com/lilnasy/gratelets?tab=readme-ov-file#websocket-adapters-for-astro